feat(docs): provide docs-custom-elements output targets

[runarberg]

Follows the draft outlined in webcomponents/custom-elements-json#8

Closes: #2048

[manucorporat]

Thanks for the PR.

Unfortunately, it's just a self-called standard, we have never been asked for feedback even though our docs-json came first.

In the meantime, stencil supports docs-custom so external generators can be integrated without being part of the core.

We can leave this PR open after there is some traction

[manucorporat]

I guess we could merge it, i am just not sure docs-custom-elements is the correct name.

[runarberg]

@manucorporat I am indeed using the docs-custom and it’s working great. In fact this the PR is pretty much a port of the function I put in my stencil.config.ts. I figured it could be useful for the community, if only to link to for other authors that are trying to integrate storybook’s docs addon.

[dmartinjs]

Hello @runarberg

can you share you docs-custom function ?

[runarberg]

@dmartinjs sure: Note that storybook uses experimental field names compatible with web-component-analizer (cssParts and cssProperties; this standard combat is a mess), so this is a little different from the associated PR:

import { promises as fs } from 'fs';
import { Config } from '@stencil/core';
import { JsonDocs } from '@stencil/core/internal';

async function generateCustomElementsJson(docsData: JsonDocs) {
  const jsonData = {
    version: 1.2,
    tags: docsData.components.map((component) => ({
      name: component.tag,
      path: component.filePath,
      description: component.docs,

      attributes: component.props
        .filter((prop) => prop.attr)
        .map((prop) => ({
          name: prop.attr,
          type: prop.type,
          description: prop.docs,
          defaultValue: prop.default,
          required: prop.required,
        })),

      properties: component.props.map((prop) => ({
        name: prop.name,
        type: prop.type,
        description: prop.docs,
        defaultValue: prop.default,
        required: prop.required,
      })),

      events: component.events.map((event) => ({
        name: event.event,
        description: event.docs,
      })),

      methods: component.methods.map((method) => ({
        name: method.name,
        description: method.docs,
        signature: method.signature,
      })),

      slots: component.slots.map((slot) => ({
        name: slot.name,
        description: slot.docs,
      })),

      cssProperties: component.styles
        .filter((style) => style.annotation === 'prop')
        .map((style) => ({
          name: style.name,
          description: style.docs,
        })),

      cssParts: component.parts.map((part) => ({
        name: part.name,
        description: part.docs,
      })),
    })),
  };

  await fs.writeFile(
    './custom-elements.json',
    JSON.stringify(jsonData, null, 2),
  );
}

export const config: Config = {
  // ...
  outputTargets: [
    // ...
    {
      type: 'docs-custom',
      generator: generateCustomElementsJson,
    },
  ],
};

[dmartinjs]

Is there some news on this feature ?

[LeeBurton]

@manucorporat This pull request has been open since April 2020... please can you add this feature?? We have also been waiting on this for a long time, and would rather have this built in than using a third-party dependency.

It is also not great if people invest time an effort in creating PRs to add new functionality and they are not merged fairly quickly or given suggestions for improvement. There is even a further question above from October 2020, asking if there is any news on this feature, and absolutely no response from anyone.

If it takes this long for them to be merged, people will simply stop contributing :-}

[runarberg]

@LeeBurton I think this PR is obsolete. The standard in question has changed a little since I opened this PR almost a year ago (see current schema). E.g. now they use cssParts as opposed to the previous cssShadowParts.

This PR would need some work before it could be merged.

[christian-bromann]

I think this PR is obsolete. The standard in question has changed a little since I opened this PR almost a year ago (see current schema). E.g. now they use cssParts as opposed to the previous cssShadowParts.

Thanks @runarberg for raising the PR.

I will go ahead and close this and propose for anyone interested in this to upvote https://github.com/ionic-team/stencil/issues/2048 so we can gauge interest.