Story Types & Metadata

// Core types from @storybook/react
import type { Meta, StoryObj, StoryFn, Decorator, Loader, StoryContext, Preview } from "@storybook/react";

// Core types from React
import type { ComponentType, ComponentProps } from "react";

// Core Storybook internal types (used in type definitions)
import type {
  Args,
  ArgTypes, 
  Parameters,
  StrictArgs,
  ComponentAnnotations,
  StoryAnnotations,
  AnnotatedStoryFn,
  ArgsStoryFn,
  DecoratorFunction,
  LoaderFunction,
  GenericStoryContext,
  ProjectAnnotations,
  ArgsFromMeta
} from "storybook/internal/types";

// Utility types
import type { SetOptional, Simplify } from "type-fest";

// ReactRenderer type (see React Renderer Types documentation)
import type { ReactRenderer } from "./react-renderer.md#react-renderer-interface";

/**
 * Metadata to configure the stories for a component.
 * Automatically infers component props when a ComponentType is provided.
 */
type Meta<TCmpOrArgs = Args> = [TCmpOrArgs] extends [ComponentType<any>]
  ? ComponentAnnotations<ReactRenderer, ComponentProps<TCmpOrArgs>>
  : ComponentAnnotations<ReactRenderer, TCmpOrArgs>;

import type { Meta } from "@storybook/react";
import { Button } from "./Button";

const meta: Meta<typeof Button> = {
  title: "Example/Button",
  component: Button,
  parameters: {
    layout: "centered",
  },
  argTypes: {
    primary: { control: "boolean" },
    size: {
      control: { type: "select" },
      options: ["small", "medium", "large"],
    },
  },
};

export default meta;

/**
 * Story object that represents a CSFv3 component example.
 * Provides type safety for story args based on component props or meta configuration.
 */
type StoryObj<TMetaOrCmpOrArgs = Args> = [TMetaOrCmpOrArgs] extends [
  {
    render?: ArgsStoryFn<ReactRenderer, any>;
    component?: infer Component;
    args?: infer DefaultArgs;
  },
]
  ? Simplify<
      (Component extends ComponentType<any> ? ComponentProps<Component> : unknown) &
        ArgsFromMeta<ReactRenderer, TMetaOrCmpOrArgs>
    > extends infer TArgs
    ? StoryAnnotations<
        ReactRenderer,
        AddMocks<TArgs, DefaultArgs>,
        SetOptional<TArgs, keyof TArgs & keyof DefaultArgs>
      >
    : never
  : TMetaOrCmpOrArgs extends ComponentType<any>
    ? StoryAnnotations<ReactRenderer, ComponentProps<TMetaOrCmpOrArgs>>
    : StoryAnnotations<ReactRenderer, TMetaOrCmpOrArgs>;

import type { Meta, StoryObj } from "@storybook/react";
import { Button } from "./Button";

const meta: Meta<typeof Button> = {
  component: Button,
};

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

export const Primary: Story = {
  args: {
    primary: true,
    label: "Primary Button",
    size: "medium",
  },
};

export const CustomRender: Story = {
  args: {
    label: "Custom",
  },
  render: (args) => (
    <div style={{ padding: "20px" }}>
      <Button {...args} />
    </div>
  ),
};

/**
 * Story function that represents a CSFv2 component example.
 * Automatically infers component props when a ComponentType is provided.
 */
type StoryFn<TCmpOrArgs = Args> = [TCmpOrArgs] extends [ComponentType<any>]
  ? AnnotatedStoryFn<ReactRenderer, ComponentProps<TCmpOrArgs>>
  : AnnotatedStoryFn<ReactRenderer, TCmpOrArgs>;

import type { Meta, StoryFn } from "@storybook/react";
import { Button } from "./Button";

const meta: Meta<typeof Button> = {
  component: Button,
};

export default meta;

export const Primary: StoryFn<typeof Button> = (args) => <Button {...args} />;
Primary.args = {
  primary: true,
  label: "Primary Button",
};

/**
 * Decorator function type for wrapping stories with additional functionality.
 * Provides access to story context and parameters.
 */
type Decorator<TArgs = StrictArgs> = DecoratorFunction<ReactRenderer, TArgs>;

import type { Decorator } from "@storybook/react";

const withMargin: Decorator = (Story, context) => (
  <div style={{ margin: "3em" }}>
    <Story />
  </div>
);

const withTheme: Decorator = (Story, context) => {
  const theme = context.parameters.theme || "light";
  return (
    <div className={`theme-${theme}`}>
      <Story />
    </div>
  );
};

/**
 * Loader function type for fetching data before story rendering.
 * Returns data that will be available in the story context.
 */
type Loader<TArgs = StrictArgs> = LoaderFunction<ReactRenderer, TArgs>;

import type { Loader, Meta, StoryObj } from "@storybook/react";
import { UserProfile } from "./UserProfile";

const fetchUser: Loader = async () => ({
  user: await fetch("/api/user/1").then((res) => res.json()),
});

const meta: Meta<typeof UserProfile> = {
  component: UserProfile,
  loaders: [fetchUser],
};

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

export const Default: Story = {
  render: (args, { loaded: { user } }) => (
    <UserProfile user={user} {...args} />
  ),
};

/**
 * Story context type providing access to story metadata, parameters, and state.
 * Available in decorators, loaders, and custom render functions.
 */
type StoryContext<TArgs = StrictArgs> = GenericStoryContext<ReactRenderer, TArgs>;

/**
 * Project annotations type for configuring global Storybook behavior.
 * Used in .storybook/preview.ts files.
 */
type Preview = ProjectAnnotations<ReactRenderer>;

import type { Preview } from "@storybook/react";

const preview: Preview = {
  parameters: {
    actions: { argTypesRegex: "^on[A-Z].*" },
    controls: {
      matchers: {
        color: /(background|color)$/i,
        date: /Date$/,
      },
    },
  },
  decorators: [
    (Story) => (
      <div style={{ padding: "1rem" }}>
        <Story />
      </div>
    ),
  ],
};

export default preview;

/**
 * Type helper that preserves mock function types when mock functions are provided in meta args.
 * Ensures proper typing for mocked functions in stories.
 */
type AddMocks<TArgs, DefaultArgs> = Simplify<{
  [T in keyof TArgs]: T extends keyof DefaultArgs
    ? DefaultArgs[T] extends (...args: any) => any & { mock: {} }
      ? DefaultArgs[T]
      : TArgs[T]
    : TArgs[T];
}>;

/**
 * Story arguments type - key-value pairs passed to component
 */
type Args = Record<string, any>;

/**
 * Argument type definitions for controls and documentation
 */
type ArgTypes = Record<string, any>;

/**
 * Story parameters for configuration and addon data
 */
type Parameters = Record<string, any>;

/**
 * Strict arguments type requiring all properties
 */
type StrictArgs = Record<string, any>;