Story Creation & Types

/**
 * Metadata to configure the stories for a component.
 * Defines default export structure for story files.
 */
type Meta<TArgs = Args> = ComponentAnnotations<WebComponentsRenderer, TArgs>;

import type { Meta } from "@storybook/web-components";

const meta: Meta = {
  title: "Example/MyButton",
  component: "my-button",
  parameters: {
    layout: "centered",
    docs: {
      description: {
        component: "A simple button component",
      },
    },
  },
  argTypes: {
    label: {
      control: { type: "text" },
      description: "Button label text",
    },
    variant: {
      control: { type: "select" },
      options: ["primary", "secondary", "danger"],
    },
  },
};

export default meta;

/**
 * Story function that represents a CSFv2 component example.
 * Used for stories defined as functions.
 */
type StoryFn<TArgs = Args> = AnnotatedStoryFn<WebComponentsRenderer, TArgs>;

import type { Meta, StoryFn } from "@storybook/web-components";

const meta: Meta = {
  title: "Example/Button",
  component: "my-button",
};

export default meta;

export const Primary: StoryFn = (args) => {
  const button = document.createElement("my-button");
  button.setAttribute("label", args.label);
  button.setAttribute("variant", args.variant);
  return button;
};

Primary.args = {
  label: "Click me",
  variant: "primary",
};

/**
 * Story object that represents a CSFv3 component example.
 * Used for stories defined as objects with args and other properties.
 */
type StoryObj<TArgs = Args> = StoryAnnotations<WebComponentsRenderer, TArgs>;

import type { Meta, StoryObj } from "@storybook/web-components";

const meta: Meta = {
  title: "Example/Button",
  component: "my-button",
};

export default meta;
type Story = StoryObj;

export const Primary: Story = {
  args: {
    label: "Primary Button",
    variant: "primary",
  },
};

export const Secondary: Story = {
  args: {
    label: "Secondary Button",
    variant: "secondary",
  },
};

export const WithLongLabel: Story = {
  args: {
    label: "This is a button with a very long label to test text wrapping",
    variant: "primary",
  },
  parameters: {
    docs: {
      description: {
        story: "Example showing how the button handles long text labels.",
      },
    },
  },
};

/**
 * Decorator function type for wrapping stories with additional functionality.
 * Used to add common wrappers, contexts, or styling to stories.
 */
type Decorator<TArgs = StrictArgs> = DecoratorFunction<WebComponentsRenderer, TArgs>;

import type { Decorator } from "@storybook/web-components";

// Theme decorator example
const withTheme: Decorator = (story, context) => {
  const wrapper = document.createElement("div");
  wrapper.setAttribute("data-theme", context.globals.theme || "light");
  wrapper.appendChild(story());
  return wrapper;
};

// Apply to all stories in the file
export const decorators: Decorator[] = [withTheme];

// Or apply globally in .storybook/preview.js
export const decorators = [withTheme];

/**
 * Loader function type for pre-loading data needed by stories.
 * Runs before the story renders and provides data via context.loaded.
 */
type Loader<TArgs = StrictArgs> = LoaderFunction<WebComponentsRenderer, TArgs>;

import type { Meta, StoryObj, Loader } from "@storybook/web-components";

const meta: Meta = {
  title: "Example/UserCard",
  component: "user-card",
};

export default meta;
type Story = StoryObj;

const loadUserData: Loader = async () => {
  const response = await fetch("/api/users/1");
  const userData = await response.json();
  return { userData };
};

export const WithLoadedData: Story = {
  loaders: [loadUserData],
  render: (args, { loaded }) => {
    const card = document.createElement("user-card");
    card.setAttribute("name", loaded.userData.name);
    card.setAttribute("email", loaded.userData.email);
    return card;
  },
};

/**
 * Story context object containing story metadata and runtime information.
 * Available in story functions, decorators, and loaders.
 */
type StoryContext<TArgs = StrictArgs> = GenericStoryContext<WebComponentsRenderer, TArgs>;

interface StoryContext<TArgs = StrictArgs> {
  /** Unique story identifier */
  id: string;
  /** Story title from Meta */
  title: string;
  /** Component name */
  kind: string;
  /** Story name */
  name: string;
  /** Story export name */
  story: string;
  /** Story parameters */
  parameters: Parameters;
  /** Story arguments */
  args: TArgs;
  /** Argument type definitions */
  argTypes: ArgTypes;
  /** Global values */
  globals: Globals;
  /** Storybook hooks context */
  hooks: HooksContext;
  /** Data loaded by loaders */
  loaded: Record<string, any>;
  /** Current view mode (story, docs, etc.) */
  viewMode: ViewMode;
}

/**
 * Project annotations type for global Storybook configuration.
 * Used in .storybook/preview.js for global settings.
 */
type Preview = ProjectAnnotations<WebComponentsRenderer>;

import type { Preview } from "@storybook/web-components";

const preview: Preview = {
  parameters: {
    actions: { argTypesRegex: "^on[A-Z].*" },
    controls: {
      matchers: {
        color: /(background|color)$/i,
        date: /Date$/,
      },
    },
  },
  globalTypes: {
    theme: {
      description: "Global theme for components",
      defaultValue: "light",
      toolbar: {
        title: "Theme",
        icon: "circlehollow",
        items: ["light", "dark"],
      },
    },
  },
};

export default preview;

// Typed args interface
interface ButtonArgs {
  label: string;
  variant: "primary" | "secondary" | "danger";
  disabled?: boolean;
  onClick?: () => void;
}

// Fully typed story
const meta: Meta<ButtonArgs> = {
  title: "Example/TypedButton",
  component: "my-button",
};

export default meta;
type Story = StoryObj<ButtonArgs>;

export const Typed: Story = {
  args: {
    label: "Typed Button", // TypeScript knows this should be a string
    variant: "primary",    // TypeScript knows the valid options
    // disabled: "yes",    // TypeScript error: should be boolean
  },
};