@storybook/react 10.2.0-alpha.8 → 10.2.0-beta.0

package/dist/_browser-chunks/{chunk-BMWJYMA6.js → chunk-HWOFIGZP.js}

@@ -1,6 +1,6 @@
 import {
   entry_preview_exports
-} from "./chunk-GLRRNWDU.js";
+} from "./chunk-L3JF7GGZ.js";
 import {
   entry_preview_argtypes_exports
 } from "./chunk-DX2KEMQY.js";

package/dist/_browser-chunks/{chunk-GLRRNWDU.js → chunk-L3JF7GGZ.js}

@@ -17,6 +17,7 @@ __export(entry_preview_exports, {
   renderToCanvas: () => renderToCanvas
 });
 import * as React4 from "react";
+import { Tag } from "storybook/internal/preview-api";
 import { global as global2 } from "@storybook/global";
 import { configure } from "storybook/test";
 
@@ -156,7 +157,7 @@ var decorators = [
     return React4.createElement(React4.Suspense, null, story());
   },
   (story, context) => {
-    if (context.tags?.includes("test-fn") && !global2.FEATURES?.experimentalTestSyntax)
+    if (context.tags?.includes(Tag.TEST_FN) && !global2.FEATURES?.experimentalTestSyntax)
       throw new Error(
         "To use the experimental test function, you must enable the experimentalTestSyntax feature flag. See https://storybook.js.org/docs/api/main-config/main-config-features#experimentaltestsyntax"
       );

package/dist/entry-preview.js

@@ -5,7 +5,7 @@ import {
   parameters,
   render,
   renderToCanvas
-} from "./_browser-chunks/chunk-GLRRNWDU.js";
+} from "./_browser-chunks/chunk-L3JF7GGZ.js";
 import {
   applyDecorators
 } from "./_browser-chunks/chunk-DDIRQRCA.js";

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/index.js

@@ -1,10 +1,10 @@
 import {
   __definePreview
-} from "./_browser-chunks/chunk-BMWJYMA6.js";
+} from "./_browser-chunks/chunk-HWOFIGZP.js";
 import {
   entry_preview_exports,
   renderToCanvas
-} from "./_browser-chunks/chunk-GLRRNWDU.js";
+} from "./_browser-chunks/chunk-L3JF7GGZ.js";
 import {
   entry_preview_argtypes_exports
 } from "./_browser-chunks/chunk-DX2KEMQY.js";