@storybook/react 10.2.0-alpha.15 → 10.2.0-alpha.16

package/dist/index.d.ts

@@ -498,39 +498,157 @@ declare function composeStory<TArgs extends Args = Args>(story: StoryAnnotations
  */
 declare function composeStories<TModule extends Store_CSFExports<ReactRenderer, any>>(csfExports: TModule, projectAnnotations?: ProjectAnnotations<ReactRenderer>): Omit<StoriesWithPartialProps<ReactRenderer, TModule>, keyof Store_CSFExports>;
 
+/** Extracts and unions all args types from an array of decorators. */
+type DecoratorsArgs<TRenderer extends Renderer, Decorators> = UnionToIntersection<Decorators extends DecoratorFunction<TRenderer, infer TArgs> ? TArgs : unknown>;
+type InferArgs<TArgs, T, Decorators> = Simplify<TArgs & Simplify<RemoveIndexSignature<DecoratorsArgs<ReactTypes & T, Decorators>>>>;
+type InferReactTypes<T, TArgs, Decorators> = ReactTypes & T & {
+    args: Simplify<InferArgs<TArgs, T, Decorators>>;
+};
+/**
+ * Creates a React-specific preview configuration with CSF factories support.
+ *
+ * This function wraps the base `definePreview` and adds React-specific annotations for rendering
+ * and documentation. It returns a `ReactPreview` that provides type-safe `meta()` and `story()`
+ * factory methods.
+ *
+ * @example
+ *
+ * ```ts
+ * // .storybook/preview.ts
+ * import { definePreview } from '@storybook/react';
+ *
+ * export const preview = definePreview({
+ *   addons: [],
+ *   parameters: { layout: 'centered' },
+ * });
+ * ```
+ */
 declare function __definePreview<Addons extends PreviewAddon<never>[]>(input: {
     addons: Addons;
 } & ProjectAnnotations<ReactTypes & InferTypes<Addons>>): ReactPreview<ReactTypes & InferTypes<Addons>>;
-type InferArgs<TArgs extends Args, T extends AddonTypes, Decorators extends DecoratorFunction<ReactTypes & T, any>> = Simplify<TArgs & Simplify<RemoveIndexSignature<DecoratorsArgs<ReactTypes & T, Decorators>>>>;
+/**
+ * React-specific Preview interface that provides type-safe CSF factory methods.
+ *
+ * Use `preview.meta()` to create a meta configuration for a component, and then `meta.story()` to
+ * create individual stories. The type system will infer args from the component props, decorators,
+ * and any addon types.
+ *
+ * @example
+ *
+ * ```ts
+ * const meta = preview.meta({ component: Button });
+ * export const Primary = meta.story({ args: { label: 'Click me' } });
+ * ```
+ */
 /** @ts-expect-error We cannot implement the meta faithfully here, but that is okay. */
 interface ReactPreview<T extends AddonTypes> extends Preview$1<ReactTypes & T> {
-    meta<TArgs extends Args, Decorators extends DecoratorFunction<ReactTypes & T, any>, TMetaArgs extends Partial<TArgs>>(meta: {
-        render?: ArgsStoryFn<ReactTypes & T, TArgs>;
+    /**
+     * Narrows the type of the preview to include additional type information. This is useful when you
+     * need to add args that aren't inferred from the component.
+     *
+     * @example
+     *
+     * ```ts
+     * const meta = preview.type<{ args: { theme: 'light' | 'dark' } }>().meta({
+     *   component: Button,
+     * });
+     * ```
+     */
+    type<R>(): ReactPreview<T & R>;
+    meta<TArgs extends Args, Decorators extends DecoratorFunction<ReactTypes & T, any>, TMetaArgs extends Partial<TArgs & T['args']>>(meta: {
+        render?: ArgsStoryFn<ReactTypes & T, TArgs & T['args']>;
         component?: ComponentType<TArgs>;
         decorators?: Decorators | Decorators[];
         args?: TMetaArgs;
-    } & Omit<ComponentAnnotations<ReactTypes & T, TArgs>, 'decorators' | 'component' | 'args' | 'render'>): ReactMeta<ReactTypes & T & {
-        args: InferArgs<TArgs, T, Decorators>;
-    }, Omit<ComponentAnnotations<ReactTypes & T & {
-        args: InferArgs<TArgs, T, Decorators>;
-    }>, 'args'> & {
+    } & Omit<ComponentAnnotations<ReactTypes & T, TArgs>, 'decorators' | 'component' | 'args' | 'render'>): ReactMeta<InferReactTypes<T, TArgs, Decorators>, Omit<ComponentAnnotations<InferReactTypes<T, TArgs, Decorators>>, 'args'> & {
         args: Partial<TArgs> extends TMetaArgs ? {} : TMetaArgs;
     }>;
 }
-type DecoratorsArgs<TRenderer extends Renderer, Decorators> = UnionToIntersection<Decorators extends DecoratorFunction<TRenderer, infer TArgs> ? TArgs : unknown>;
+/**
+ * React-specific Meta interface returned by `preview.meta()`.
+ *
+ * Provides the `story()` method to create individual stories with proper type inference. Args
+ * provided in meta become optional in stories, while missing required args must be provided at the
+ * story level.
+ */
 interface ReactMeta<T extends ReactTypes, MetaInput extends ComponentAnnotations<T>>
-/** @ts-expect-error hard */
+/** @ts-expect-error ReactMeta requires two type parameters, but Meta's constraints differ */
  extends Meta$1<T, MetaInput> {
+    /**
+     * Creates a story with a custom render function that takes no args.
+     *
+     * This overload allows you to define a story using just a render function or an object with a
+     * render function that doesn't depend on args. Since the render function doesn't use args, no
+     * args need to be provided regardless of what's required by the component.
+     *
+     * @example
+     *
+     * ```ts
+     * // Using just a render function
+     * export const CustomRender = meta.story(() => <div>Custom content</div>);
+     *
+     * // Using an object with render
+     * export const WithRender = meta.story({
+     *   render: () => <MyComponent prop="static" />,
+     * });
+     * ```
+     */
     story<TInput extends (() => ReactTypes['storyResult']) | (StoryAnnotations<T, T['args']> & {
         render: () => ReactTypes['storyResult'];
     })>(story: TInput): ReactStory<T, TInput extends () => ReactTypes['storyResult'] ? {
         render: TInput;
     } : TInput>;
+    /**
+     * Creates a story with custom configuration including args, decorators, or other annotations.
+     *
+     * This is the primary overload for defining stories. Args that were already provided in meta
+     * become optional, while any remaining required args must be specified here.
+     *
+     * @example
+     *
+     * ```ts
+     * // Provide required args not in meta
+     * export const Primary = meta.story({
+     *   args: { label: 'Click me', disabled: false },
+     * });
+     *
+     * // Override meta args and add story-specific configuration
+     * export const Disabled = meta.story({
+     *   args: { disabled: true },
+     *   decorators: [withCustomWrapper],
+     * });
+     * ```
+     */
     story<TInput extends Simplify<StoryAnnotations<T, AddMocks<T['args'], MetaInput['args']>, SetOptional<T['args'], keyof T['args'] & keyof MetaInput['args']>>>>(story: TInput
     /** @ts-expect-error hard */
     ): ReactStory<T, TInput>;
+    /**
+     * Creates a story with no additional configuration.
+     *
+     * This overload is only available when all required args have been provided in meta. The
+     * conditional type `Partial<T['args']> extends SetOptional<...>` checks if the remaining required
+     * args (after accounting for args provided in meta) are all optional. If so, the function accepts
+     * zero arguments `[]`. Otherwise, it requires `[never]` which makes this overload unmatchable,
+     * forcing the user to provide args.
+     *
+     * @example
+     *
+     * ```ts
+     * // When meta provides all required args, story() can be called with no arguments
+     * const meta = preview.meta({ component: Button, args: { label: 'Hi', disabled: false } });
+     * export const Default = meta.story(); // Valid - all args provided in meta
+     * ```
+     */
     story(..._args: Partial<T['args']> extends SetOptional<T['args'], keyof T['args'] & keyof MetaInput['args']> ? [] : [never]): ReactStory<T, {}>;
 }
+/**
+ * React-specific Story interface returned by `meta.story()`.
+ *
+ * Represents a single story with its configuration and provides access to the composed story for
+ * testing via `story.run()`.
+ *
+ * Also includes a `Component` property for portable story compatibility.
+ */
 interface ReactStory<T extends ReactTypes, TInput extends StoryAnnotations<T, T['args']>> extends Story<T, TInput> {
     Component: ComponentType<Partial<T['args']>>;
 }

package/dist/preset.js

@@ -1,10 +1,10 @@
-import CJS_COMPAT_NODE_URL_4nd2qi8yguw from 'node:url';
-import CJS_COMPAT_NODE_PATH_4nd2qi8yguw from 'node:path';
-import CJS_COMPAT_NODE_MODULE_4nd2qi8yguw from "node:module";
+import CJS_COMPAT_NODE_URL_8h0e3j6j29r from 'node:url';
+import CJS_COMPAT_NODE_PATH_8h0e3j6j29r from 'node:path';
+import CJS_COMPAT_NODE_MODULE_8h0e3j6j29r from "node:module";
 
-var __filename = CJS_COMPAT_NODE_URL_4nd2qi8yguw.fileURLToPath(import.meta.url);
-var __dirname = CJS_COMPAT_NODE_PATH_4nd2qi8yguw.dirname(__filename);
-var require = CJS_COMPAT_NODE_MODULE_4nd2qi8yguw.createRequire(import.meta.url);
+var __filename = CJS_COMPAT_NODE_URL_8h0e3j6j29r.fileURLToPath(import.meta.url);
+var __dirname = CJS_COMPAT_NODE_PATH_8h0e3j6j29r.dirname(__filename);
+var require = CJS_COMPAT_NODE_MODULE_8h0e3j6j29r.createRequire(import.meta.url);
 
 // ------------------------------------------------------------
 // end of CJS compatibility banner, injected by Storybook's esbuild configuration

package/dist/preview.d.ts

@@ -389,39 +389,157 @@ type AddMocks<TArgs, DefaultArgs> = Simplify<{
     } ? DefaultArgs[T] : TArgs[T] : TArgs[T];
 }>;
 
+/** Extracts and unions all args types from an array of decorators. */
+type DecoratorsArgs<TRenderer extends Renderer, Decorators> = UnionToIntersection<Decorators extends DecoratorFunction<TRenderer, infer TArgs> ? TArgs : unknown>;
+type InferArgs<TArgs, T, Decorators> = Simplify<TArgs & Simplify<RemoveIndexSignature<DecoratorsArgs<ReactTypes & T, Decorators>>>>;
+type InferReactTypes<T, TArgs, Decorators> = ReactTypes & T & {
+    args: Simplify<InferArgs<TArgs, T, Decorators>>;
+};
+/**
+ * Creates a React-specific preview configuration with CSF factories support.
+ *
+ * This function wraps the base `definePreview` and adds React-specific annotations for rendering
+ * and documentation. It returns a `ReactPreview` that provides type-safe `meta()` and `story()`
+ * factory methods.
+ *
+ * @example
+ *
+ * ```ts
+ * // .storybook/preview.ts
+ * import { definePreview } from '@storybook/react';
+ *
+ * export const preview = definePreview({
+ *   addons: [],
+ *   parameters: { layout: 'centered' },
+ * });
+ * ```
+ */
 declare function __definePreview<Addons extends PreviewAddon<never>[]>(input: {
     addons: Addons;
 } & ProjectAnnotations<ReactTypes & InferTypes<Addons>>): ReactPreview<ReactTypes & InferTypes<Addons>>;
-type InferArgs<TArgs extends Args, T extends AddonTypes, Decorators extends DecoratorFunction<ReactTypes & T, any>> = Simplify<TArgs & Simplify<RemoveIndexSignature<DecoratorsArgs<ReactTypes & T, Decorators>>>>;
+/**
+ * React-specific Preview interface that provides type-safe CSF factory methods.
+ *
+ * Use `preview.meta()` to create a meta configuration for a component, and then `meta.story()` to
+ * create individual stories. The type system will infer args from the component props, decorators,
+ * and any addon types.
+ *
+ * @example
+ *
+ * ```ts
+ * const meta = preview.meta({ component: Button });
+ * export const Primary = meta.story({ args: { label: 'Click me' } });
+ * ```
+ */
 /** @ts-expect-error We cannot implement the meta faithfully here, but that is okay. */
 interface ReactPreview<T extends AddonTypes> extends Preview<ReactTypes & T> {
-    meta<TArgs extends Args, Decorators extends DecoratorFunction<ReactTypes & T, any>, TMetaArgs extends Partial<TArgs>>(meta: {
-        render?: ArgsStoryFn<ReactTypes & T, TArgs>;
+    /**
+     * Narrows the type of the preview to include additional type information. This is useful when you
+     * need to add args that aren't inferred from the component.
+     *
+     * @example
+     *
+     * ```ts
+     * const meta = preview.type<{ args: { theme: 'light' | 'dark' } }>().meta({
+     *   component: Button,
+     * });
+     * ```
+     */
+    type<R>(): ReactPreview<T & R>;
+    meta<TArgs extends Args, Decorators extends DecoratorFunction<ReactTypes & T, any>, TMetaArgs extends Partial<TArgs & T['args']>>(meta: {
+        render?: ArgsStoryFn<ReactTypes & T, TArgs & T['args']>;
         component?: ComponentType<TArgs>;
         decorators?: Decorators | Decorators[];
         args?: TMetaArgs;
-    } & Omit<ComponentAnnotations<ReactTypes & T, TArgs>, 'decorators' | 'component' | 'args' | 'render'>): ReactMeta<ReactTypes & T & {
-        args: InferArgs<TArgs, T, Decorators>;
-    }, Omit<ComponentAnnotations<ReactTypes & T & {
-        args: InferArgs<TArgs, T, Decorators>;
-    }>, 'args'> & {
+    } & Omit<ComponentAnnotations<ReactTypes & T, TArgs>, 'decorators' | 'component' | 'args' | 'render'>): ReactMeta<InferReactTypes<T, TArgs, Decorators>, Omit<ComponentAnnotations<InferReactTypes<T, TArgs, Decorators>>, 'args'> & {
         args: Partial<TArgs> extends TMetaArgs ? {} : TMetaArgs;
     }>;
 }
-type DecoratorsArgs<TRenderer extends Renderer, Decorators> = UnionToIntersection<Decorators extends DecoratorFunction<TRenderer, infer TArgs> ? TArgs : unknown>;
+/**
+ * React-specific Meta interface returned by `preview.meta()`.
+ *
+ * Provides the `story()` method to create individual stories with proper type inference. Args
+ * provided in meta become optional in stories, while missing required args must be provided at the
+ * story level.
+ */
 interface ReactMeta<T extends ReactTypes, MetaInput extends ComponentAnnotations<T>>
-/** @ts-expect-error hard */
+/** @ts-expect-error ReactMeta requires two type parameters, but Meta's constraints differ */
  extends Meta<T, MetaInput> {
+    /**
+     * Creates a story with a custom render function that takes no args.
+     *
+     * This overload allows you to define a story using just a render function or an object with a
+     * render function that doesn't depend on args. Since the render function doesn't use args, no
+     * args need to be provided regardless of what's required by the component.
+     *
+     * @example
+     *
+     * ```ts
+     * // Using just a render function
+     * export const CustomRender = meta.story(() => <div>Custom content</div>);
+     *
+     * // Using an object with render
+     * export const WithRender = meta.story({
+     *   render: () => <MyComponent prop="static" />,
+     * });
+     * ```
+     */
     story<TInput extends (() => ReactTypes['storyResult']) | (StoryAnnotations<T, T['args']> & {
         render: () => ReactTypes['storyResult'];
     })>(story: TInput): ReactStory<T, TInput extends () => ReactTypes['storyResult'] ? {
         render: TInput;
     } : TInput>;
+    /**
+     * Creates a story with custom configuration including args, decorators, or other annotations.
+     *
+     * This is the primary overload for defining stories. Args that were already provided in meta
+     * become optional, while any remaining required args must be specified here.
+     *
+     * @example
+     *
+     * ```ts
+     * // Provide required args not in meta
+     * export const Primary = meta.story({
+     *   args: { label: 'Click me', disabled: false },
+     * });
+     *
+     * // Override meta args and add story-specific configuration
+     * export const Disabled = meta.story({
+     *   args: { disabled: true },
+     *   decorators: [withCustomWrapper],
+     * });
+     * ```
+     */
     story<TInput extends Simplify<StoryAnnotations<T, AddMocks<T['args'], MetaInput['args']>, SetOptional<T['args'], keyof T['args'] & keyof MetaInput['args']>>>>(story: TInput
     /** @ts-expect-error hard */
     ): ReactStory<T, TInput>;
+    /**
+     * Creates a story with no additional configuration.
+     *
+     * This overload is only available when all required args have been provided in meta. The
+     * conditional type `Partial<T['args']> extends SetOptional<...>` checks if the remaining required
+     * args (after accounting for args provided in meta) are all optional. If so, the function accepts
+     * zero arguments `[]`. Otherwise, it requires `[never]` which makes this overload unmatchable,
+     * forcing the user to provide args.
+     *
+     * @example
+     *
+     * ```ts
+     * // When meta provides all required args, story() can be called with no arguments
+     * const meta = preview.meta({ component: Button, args: { label: 'Hi', disabled: false } });
+     * export const Default = meta.story(); // Valid - all args provided in meta
+     * ```
+     */
     story(..._args: Partial<T['args']> extends SetOptional<T['args'], keyof T['args'] & keyof MetaInput['args']> ? [] : [never]): ReactStory<T, {}>;
 }
+/**
+ * React-specific Story interface returned by `meta.story()`.
+ *
+ * Represents a single story with its configuration and provides access to the composed story for
+ * testing via `story.run()`.
+ *
+ * Also includes a `Component` property for portable story compatibility.
+ */
 interface ReactStory<T extends ReactTypes, TInput extends StoryAnnotations<T, T['args']>> extends Story<T, TInput> {
     Component: ComponentType<Partial<T['args']>>;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@storybook/react",
-  "version": "10.2.0-alpha.15",
+  "version": "10.2.0-alpha.16",
   "description": "Storybook React renderer",
   "keywords": [
     "storybook"
@@ -50,7 +50,7 @@
   ],
   "dependencies": {
     "@storybook/global": "^5.0.0",
-    "@storybook/react-dom-shim": "10.2.0-alpha.15",
+    "@storybook/react-dom-shim": "10.2.0-alpha.16",
     "react-docgen": "^8.0.2"
   },
   "devDependencies": {
@@ -77,7 +77,7 @@
   "peerDependencies": {
     "react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0",
     "react-dom": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0",
-    "storybook": "^10.2.0-alpha.15",
+    "storybook": "^10.2.0-alpha.16",
     "typescript": ">= 4.9.x"
   },
   "peerDependenciesMeta": {