Autodocs for a "vanilla" TypeScript component / class?

[supermoos]

Summary

I have a class similar to this one:

export class SimpleComponent {
  hostElement: HTMLElement;
  private shadowElement: ShadowRoot | null = null;
  private container: HTMLElement;

  readonly config = {
    useShadowDOM: true,
    customMessage: 'Hello, World!',
  };

  constructor(target?: HTMLElement, config: Partial<typeof SimpleComponent.prototype.config> = {}) {
    this.hostElement = target || (document.querySelector('#simple-container') as HTMLElement);
    if (!this.hostElement) {
      console.warn('No target element found for SimpleComponent. Please provide a valid element.');
      return;
    }

    this.config = { ...this.config, ...config };

    this.container = document.createElement('div');
    this.container.classList.add('simple-component');

    if (this.config.useShadowDOM) {
      this.shadowElement = this.hostElement.attachShadow({ mode: 'closed' });
      this.shadowElement.appendChild(this.container);
    } else {
      this.hostElement.appendChild(this.container);
    }

    this.render();
  }

  render() {
    this.container.innerHTML = `<p>${this.config.customMessage}</p>`;
  }
}

// Example usage:
const targetElement = document.getElementById('my-component-container');
const component = new SimpleComponent(targetElement, { customMessage: 'Welcome to SimpleComponent!' });

And a sample story:

// @ts-nocheck
import type { StoryObj, Meta } from '@storybook/html';
import '../../build/dist/style.css';
import { SimpleComponent } from '../SimpleComponent.ts';

const renderFunction = (args, addGlobalStyles = false) => {
  // Clear the existing content to ensure a fresh re-render
  const existingContainer = document.body.querySelector('#simple-container');
  if (existingContainer) {
    existingContainer.remove();
  }

  // Create a new container element
  const container = document.createElement('div');
  container.id = 'simple-container';
  document.body.appendChild(container);

  if (addGlobalStyles === true) {
    // Add global styles for H1
    const styleTag = document.createElement('style');
    styleTag.id = 'global-demo-styles';
    styleTag.innerHTML = `
      h1::before {
       color: red;
       content: 'Global styles will bleed into the component, when no Shadow DOM is used';
      }
      h1 {
        color: blue !important;
      }
    `;
    container.appendChild(styleTag);
  }

  // Initialize the component with the updated arguments
  new SimpleComponent(container, args);

  console.log('SimpleComponent rendered with args', args);
  return container;
};

const meta: Meta<typeof SimpleComponent> = {
  title: 'Components/SimpleComponent',
  tags: ['autodocs'],
  render: renderFunction,
  component: SimpleComponent,
  parameters: {
    layout: 'fullscreen',
    previewHeight: '600px',
    docs: {
      autodocs: true,
      story: {
        inline: false,
        iframeHeight: 700,
      },
    },
  },
} satisfies Meta<typeof SimpleComponent>;

export default meta;
type Story = StoryObj<typeof SimpleComponent>;

export const Default: Story = {};

export const NoShadowDOM: Story = {
  args: {
    useShadowDOM: false,
  },
  render: args => renderFunction(args, true),
};

export const CustomMessage: Story = {
  args: {
    customMessage: `<h1>Hi there!</h1>Welcome to SimpleComponent!`,
  },
};

I'm currently using html-vite framework, but I'm wondering if that's the correct framework to use? I'm looking to get autodocs to generate args and argTypes automatically based on the SimpleComponent constructor arguments?

However it seems I currently need to manually re-specify all the args and argTypes in the story file, rather than autodocs automatically picking them up from the source Typescript file.

Is it just not supported to have Vanille -no-framework files used with autodocs?

Additional information

storybook v8.2.9

main.ts:

import type { StorybookConfig } from '@storybook/html-vite';

const config: StorybookConfig = {
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  addons: ['@storybook/addon-links', '@storybook/addon-essentials', '@chromatic-com/storybook', '@storybook/addon-interactions'],
  framework: {
    name: '@storybook/html-vite',
    options: {},
  },
  // typescript: {
  //   check: false,
  //   reactDocgen: 'react-docgen-typescript',
    // reactDocgenTypescriptOptions: {
    //   shouldExtractLiteralValuesFromEnum: true,
    //   propFilter: (prop) => (prop.parent ? !/node_modules/.test(prop.parent.fileName) : true),
    // },
  // },
};
export default config;

preview.ts

import type { Preview } from '@storybook/html';

const preview: Preview = {
  parameters: {
    controls: {
      matchers: {
        color: /(background|color)$/i,
        date: /Date$/i,
      },
    },
  },
};

export default preview;

Create a reproduction

No response

[Marklb]

The way argTypes are parsed is unique to the individual frameworks, since different frameworks define inputs/outputs differently. Unless I just don't know what framework/pattern that you are using, you seem to be using a custom object structure that is unique to your classes. So, I don't expect there to be a an existing solution that you could just drop in. You may be able to just tweak one for your structure though, if one is close.

I don't see the @storybook/html-vite framework specifying functions to parse argTypes. A table listing the frameworks that do implement it is here: https://github.com/storybookjs/storybook/blob/next/code/addons/docs/docs/props-tables.md#known-limitations

The closest framework that does implement argTypes parsing is maybe @storybook/web-components-vite. I am not familiar with it, but it seems to use a json file. Angular also works that way, since no one has got around to implementing something better, and I am familiar with that. The downside is that you may have to regenerate the json file and rebuild, to update the argTypes. You could take a look at the tools that can output that json file and see if they would work for your components: https://github.com/storybookjs/storybook/blob/next/code/addons/docs/web-components/README.md#props-tables

I don't think there is documentation on implementing the functions that hook the independent framework solutions for auto populated argTypes, but I was curious what all you would need to do and I wrote a very naive solution for the component that you provided. You would not want to actually use my solution, but if you are familiar with a typescript parsing tool then this may give you a starting point to implement your own solution.

There are two functions, extractArgTypes and extractComponentDescription. The description is just for documentation, so it doesn't affect the argTypes.

Here is the bad solution that I wrote for your SimpleComponent, just to give a small example starting snippet. I used only used js, so I needed to initialize the class to access the config object. There are plenty of tools that can parse that information and embed static metadata to read at runtime, so you most likely want to go that route for a real solution.

// .storybook/preview.ts
import type { Preview } from '@storybook/html';
import { SourceType } from 'storybook/internal/docs-tools';

/**
 * Very poorly written example, just to show idea.
 */
const extractArgTypes = (component: any) => {
  const targetElement = document.createElement('div');
  const tmp = new component(targetElement);
  const keys = Object.keys(tmp.config);
  const argTypes: any = {};
  if (keys.length > 1) {
    for (const k of keys) {
      const type = typeof tmp.config[k];
      if (type === 'string') {
        argTypes[k] = {
          type: { name: 'string' },
          description: `Desc ${k}`,
        };
      } else if (type === 'boolean') {
        argTypes[k] = {
          type: { name: 'boolean' },
          description: `Desc ${k}`,
        };
      }
    }
  }
  return argTypes;
};

/**
 * Very poorly written example, just to show idea.
 */
const extractComponentDescription = (component: any) => {
  return `Component: ${component.name}`;
};

const preview: Preview = {
  parameters: {
    controls: {
      matchers: {
        color: /(background|color)$/i,
        date: /Date$/i,
      },
    },
    docs: {
      extractArgTypes,
      extractComponentDescription,
      story: { inline: true },
      source: {
        type: SourceType.DYNAMIC,
        language: 'html',
        code: undefined,
        excludeDecorators: undefined,
      },
    },
  },
};

export default preview;

Here is a Stackblitz for my bad, but working, solution: https://stackblitz.com/edit/github-8egspp

[supermoos]

Thank you so much, @Marklb - that's a very comprehensive answer. Thanks for putting time an effort into this! I think a more generalized Typescript static based approach as you mention is probably the way to go to widen support for autodocs, it's not my own key area of expertise so sadly I'll leave it at that for now, as I just needed it for one component and the effort into setting that up probably can't be justified for my current project. I'll post back here if I do end up taking it further.