storybook-addon-docs-stencil

Attribution

This package is community-maintained work based on prior Storybook + Stencil community effort.

• Original project: https://github.com/pixtron/storybook-addon-docs-stencil

This repository was reinitialized independently (not a GitHub fork), and it preserves upstream attribution and MIT license notices.

For additional provenance details, see NOTICE.

Converts stencil.js doc json derived from stencils output target docs-json to storybook ArgTypes.

With this addon activated

• Storybook will render basic controls for properties Controls.
• Storybook will auto generate documentation for Props, Events, Methods, Slots, Shadow Parts and Custom Properties.
• Storybook doc page will contain stencils component documentation (readme.md or inline)

Installation

npm i -D @dropsy-ui/storybook-addon-docs-stencil

Versioning

This package follows Storybook major versions:

• 9.x supports Storybook 9.x
• 10.x will support Storybook 10.x

This means breaking compatibility with a new Storybook major is released as a new addon major.

Releasing

Release and contribution guidelines live in CONTRIBUTING.md.

Usage

Configure stencil to generate docs-json at build time.

// stencil.config.ts

import { Config } from '@stencil/core';

export const config: Config = {
  outputTargets: [
    {
      type: 'docs-json',
      file: 'path/to/docs.json'
    }
  ]
};

Configure Storybook

//.storybook/main.js

module.exports = {
  addons: [
    '@storybook/addon-essentials',
    '@dropsy-ui/storybook-addon-docs-stencil',
  ],
};

//.storybook/preview.js

import { setStencilDocJson } from '@dropsy-ui/storybook-addon-docs-stencil';
import docJson from 'path/to/docs.json';
if (docJson) setStencilDocJson(docJson);

export const parameters = {
  controls: { hideNoControlsWarning: true },
};

Configure the argTypes extractor

//.storybook/preview.js

import { extractArgTypesFactory } from '@dropsy-ui/storybook-addon-docs-stencil';

/** @type { import('@dropsy-ui/storybook-addon-docs-stencil').ExtractArgTypesOptions } */
const options = {
  excludeCategories: 'properties',
  controlsFor: 'attributes',
  eventNaming: 'jsx',
};

export const parameters = {
  docs: {
    extractArgTypes: extractArgTypesFactory(options),
  },
};

ExtractArgTypesOptions

• excludeCategories: Category[]: categories to exclude from argTypes and docs (default: ['attributes]).
• controlsFor: 'attributes' | 'properties': for wich category to render controls.
• eventNaming: 'native' | 'jsx': naming of the arg key for events (default: 'native'). If jsx the args can be spread <my-component {...args} /> when using JSX to render stories.

Default render method

When using @storybook/web-components or @storybook/html as renderer args and actions do not get bound automatically. This addon includes an optional default renderer that works out of the box

//.storybook/preview.js

import {
  extractArgTypesFactory,
  stencilRender,
} from '@dropsy-ui/storybook-addon-docs-stencil';

/** @type { import('@storybook/web-components').Preview } */
const preview = {
  render: stencilRender(),
};

export default preview;

stencilRender can be configured by these options:

• eventNaming: 'native' | 'jsx': use the same naming used in ExtractArgTypesOptions (default: 'native)
• bindEvents: boolean: whether events/actions should be bound (default: true)

eg:

stencilRender({ bindEvents: false });

Component documentation

readme.md

If not already created by stencil create src/components/my-component/readme.md If the line <!-- Auto Generated Below --> is not present, stencil will ignore this file.

Everything above this line will be included in storybook

<!-- Auto Generated Below -->

inline documentation

// src/components/my-component/my-component.tsx`

/**
 * Everything written here will be included, if readme.md is not present.
 */
@Component({
  tag: 'my-component',
  styleUrl: 'my-component.css',
  shadow: true,
})

If you prefere the inline documentation over the readme, see issue #15.

Troubleshooting

Hint your component in your stories

// your-story.ts

export default {
  title: 'My Component',
  component: 'my-component',
};

Breaking Changes in v7

• attributes and properties are now shown as own categories, before both where visible under "props" with some inconsistency in naming (dashCase vs camelCase). Use excludeCategories to configure which categories are shown.
• removed configuration dashCase properties and attributes are now shown in single sections. Use controlsFor and excludeCategories instead of dashCase.