@gtkx/storybook 2.0.0-beta.11 → 2.0.0-beta.13

package/src/explorer-preview.tsx

@@ -4,12 +4,14 @@ import * as Gtk from "@gtkx/gi/gtk";
 import { AdwHeaderBar, AdwStatusPage, AdwToolbarView, AdwWindowTitle } from "@gtkx/jsx/adw";
 import { GtkBox, GtkButton, GtkScrolledWindow } from "@gtkx/jsx/gtk";
 import { createPortal, rootElement } from "@gtkx/react";
+import { normalizeError } from "@gtkx/utils";
 import { Component, useCallback, useMemo, useState } from "react";
 import type { StoryEntry } from "./catalog.js";
-import type { Args, ComposedStory } from "./types.js";
+import type { Args, ArgTypes, ComposedStory } from "./types.js";
 import { ActionsPanel } from "./actions-panel.js";
 import { ActionStore, bindActions } from "./actions.js";
 import { Controls } from "./controls.js";
+import { isConditionalArgIncluded } from "./upstream.js";
 
 type PreviewProps = {
     entry: StoryEntry;
@@ -32,23 +34,25 @@ class PreviewBoundary extends Component<BoundaryProps, BoundaryState> {
     }
 
     static getDerivedStateFromError(error: unknown): Pick<BoundaryState, "error"> {
-        return { error: error instanceof Error ? error : new Error(String(error)) };
+        return { error: normalizeError(error) };
     }
 
     override state: BoundaryState = { error: null, args: this.props.args };
 
     override render(): ReactNode {
-        return this.state.error === null
-            ? this.props.children
-            : (
-                    <AdwStatusPage
-                        name="storybook-preview-error"
-                        title="Preview failed"
-                        iconName="dialog-error-symbolic"
-                        description={markupEscapeText(this.state.error.message.slice(0, 500), -1) +
-                            "\n\nAdjust controls, reset the preview, or select another story to continue."}
-                    />
-                );
+        return this.state.error === null ? (
+            this.props.children
+        ) : (
+            <AdwStatusPage
+                name="storybook-preview-error"
+                title="Preview failed"
+                iconName="dialog-error-symbolic"
+                description={
+                    markupEscapeText(this.state.error.message.slice(0, 500), -1) +
+                    "\n\nAdjust controls, reset the preview, or select another story to continue."
+                }
+            />
+        );
     }
 }
 
@@ -63,6 +67,36 @@ const previewMode = (story: ComposedStory): "content" | "window" | "dialog" => {
     return mode;
 };
 
+const mapValue = (value: unknown, mapping: Record<string, unknown>): unknown => {
+    const key = String(value);
+
+    return Object.hasOwn(mapping, key) ? mapping[key] : value;
+};
+
+const mapArgs = (args: Args, argTypes: ArgTypes): Args =>
+    Object.fromEntries(
+        Object.entries(args).map(([argument, value]) => {
+            const mapping = argTypes[argument]?.mapping;
+
+            if (mapping === undefined) {
+                return [argument, value];
+            }
+
+            return [
+                argument,
+                Array.isArray(value) ? value.map((item) => mapValue(item, mapping)) : mapValue(value, mapping),
+            ];
+        }),
+    );
+
+const includedArgs = (args: Args, argTypes: ArgTypes, globals: Args): Args =>
+    Object.fromEntries(
+        Object.entries(args).map(([argument, value]) => [
+            argument,
+            isConditionalArgIncluded(argTypes[argument] ?? {}, args, globals) ? value : undefined,
+        ]),
+    );
+
 const PreviewContent = ({ story: Story, args }: { story: ComposedStory; args: Args }): ReactNode => {
     const mode = previewMode(Story);
 
@@ -83,20 +117,20 @@ const PreviewContent = ({ story: Story, args }: { story: ComposedStory; args: Ar
     const align = Story.parameters.layout === "centered" ? Gtk.Align.CENTER : Gtk.Align.FILL;
 
     return (
-        <GtkBox
-            name="storybook-canvas"
-            orientation={Gtk.Orientation.VERTICAL}
-            hexpand
-            vexpand
-            halign={align}
-            valign={align}
-            marginTop={margin}
-            marginBottom={margin}
-            marginStart={margin}
-            marginEnd={margin}
-        >
-            <Story {...args} />
-        </GtkBox>
+        <GtkScrolledWindow hexpand vexpand propagateNaturalWidth propagateNaturalHeight>
+            <GtkBox
+                name="storybook-canvas"
+                orientation={Gtk.Orientation.VERTICAL}
+                halign={align}
+                valign={align}
+                marginTop={margin}
+                marginBottom={margin}
+                marginStart={margin}
+                marginEnd={margin}
+            >
+                <Story {...args} />
+            </GtkBox>
+        </GtkScrolledWindow>
     );
 };
 
@@ -108,14 +142,24 @@ const usePreviewState = ({ entry }: PreviewProps) => {
         error: null,
         actions: new ActionStore(),
     }));
-    const onError = useCallback((error: Error) => {
-        setState((current) => current.story === state.story && current.generation === state.generation
-            ? { ...current, error }
-            : current);
-    }, [state.story, state.generation]);
+    const onError = useCallback(
+        (error: Error) => {
+            setState((current) =>
+                current.story === state.story && current.generation === state.generation
+                    ? { ...current, error }
+                    : current,
+            );
+        },
+        [state.story, state.generation],
+    );
     const boundArgs = useMemo(
-        () => bindActions(state.args, state.story.argTypes, state.actions, onError),
-        [state.args, state.story.argTypes, state.actions, onError],
+        () =>
+            includedArgs(
+                bindActions(mapArgs(state.args, state.story.argTypes), state.story.argTypes, state.actions, onError),
+                state.story.argTypes,
+                state.story.globals,
+            ),
+        [state.args, state.story.argTypes, state.story.globals, state.actions, onError],
     );
 
     if (state.story !== entry.story) {
@@ -148,12 +192,7 @@ const usePreviewState = ({ entry }: PreviewProps) => {
 type InspectorProps = PreviewProps & { actions: ActionStore; args: Args; onChange: (args: Args) => void };
 
 const StoryInspector = ({ entry, actions, args, onChange }: InspectorProps): ReactNode => (
-    <GtkScrolledWindow
-        name="storybook-inspector"
-        widthRequest={280}
-        hscrollbarPolicy={Gtk.PolicyType.NEVER}
-        vexpand
-    >
+    <GtkScrolledWindow name="storybook-inspector" widthRequest={280} hscrollbarPolicy={Gtk.PolicyType.NEVER} vexpand>
         <GtkBox
             orientation={Gtk.Orientation.VERTICAL}
             spacing={24}
@@ -162,7 +201,7 @@ const StoryInspector = ({ entry, actions, args, onChange }: InspectorProps): Rea
             marginStart={12}
             marginEnd={12}
         >
-            <Controls argTypes={entry.controls} args={args} onChange={onChange} />
+            <Controls argTypes={entry.controls} args={args} globals={entry.story.globals} onChange={onChange} />
             <ActionsPanel store={actions} />
         </GtkBox>
     </GtkScrolledWindow>
@@ -175,27 +214,29 @@ const StorybookPreview = ({ entry }: PreviewProps): ReactNode => {
         <AdwToolbarView
             hexpand
             vexpand
-            topBar={(
+            top={
                 <AdwHeaderBar
                     titleWidget={<AdwWindowTitle title={entry.name} subtitle={entry.title} />}
                     end={<GtkButton label="Reset story" onClicked={reset} />}
                 />
-            )}
+            }
         >
             <GtkBox>
                 <GtkBox orientation={Gtk.Orientation.VERTICAL} hexpand vexpand>
                     <PreviewBoundary key={state.generation} args={state.args}>
-                        {state.error === null
-                            ? <PreviewContent story={entry.story} args={boundArgs} />
-                            : (
-                                    <AdwStatusPage
-                                        name="storybook-preview-error"
-                                        title="Story action failed"
-                                        iconName="dialog-error-symbolic"
-                                        description={markupEscapeText(state.error.message.slice(0, 500), -1) +
-                                            "\n\nReset the preview or select another story to continue."}
-                                    />
-                                )}
+                        {state.error === null ? (
+                            <PreviewContent story={entry.story} args={boundArgs} />
+                        ) : (
+                            <AdwStatusPage
+                                name="storybook-preview-error"
+                                title="Story action failed"
+                                iconName="dialog-error-symbolic"
+                                description={
+                                    markupEscapeText(state.error.message.slice(0, 500), -1) +
+                                    "\n\nReset the preview or select another story to continue."
+                                }
+                            />
+                        )}
                     </PreviewBoundary>
                 </GtkBox>
                 <StoryInspector entry={entry} actions={state.actions} args={state.args} onChange={onChange} />

package/src/explorer-view.tsx

@@ -10,7 +10,7 @@ import {
     AdwWindowTitle,
 } from "@gtkx/jsx/adw";
 import { quit } from "@gtkx/react";
-import { useCallback, useState, useSyncExternalStore } from "react";
+import { useCallback, useEffect, useEffectEvent, useState, useSyncExternalStore } from "react";
 import type { StoryCatalog } from "./catalog.js";
 import { StoryNavigator } from "./explorer-navigator.js";
 import { StorybookPreview } from "./explorer-preview.js";
@@ -23,56 +23,78 @@ type StorybookProps = {
     applicationId?: string;
     /** Explorer window and sidebar title; defaults to GTKX Storybook. */
     title?: string;
+    /** Story selected once the catalog lists it; the first story is selected otherwise. */
+    initialStoryId?: string | undefined;
+    /** Called with the identifier of each story the explorer selects. */
+    onStorySelected?: ((id: string) => void) | undefined;
 };
 
-type StorybookViewProps = Pick<StorybookProps, "catalog" | "title">;
+type StorybookViewProps = Pick<StorybookProps, "catalog" | "title" | "initialStoryId" | "onStorySelected">;
 
-const StorybookView = ({ catalog, title = "GTKX Storybook" }: StorybookViewProps): ReactNode => {
+const storyCount = (count: number): string => (count === 1 ? "1 story" : `${String(count)} stories`);
+
+const StorybookView = ({
+    catalog,
+    title = "GTKX Storybook",
+    initialStoryId,
+    onStorySelected,
+}: StorybookViewProps): ReactNode => {
     const subscribe = useCallback((listener: () => void) => catalog.subscribe(listener), [catalog]);
     const getSnapshot = useCallback(() => catalog.getSnapshot(), [catalog]);
     const snapshot = useSyncExternalStore(subscribe, getSnapshot);
-    const [selectedId, setSelectedId] = useState<string>();
+    const [selectedId, setSelectedId] = useState(initialStoryId);
     const selected = snapshot.stories.find((entry) => entry.id === selectedId) ?? snapshot.stories[0];
 
-    if (selectedId !== selected?.id) {
-        setSelectedId(selected?.id);
+    if (selected !== undefined && selectedId !== selected.id) {
+        setSelectedId(selected.id);
     }
 
+    const selectedStoryId = selected?.id;
+    const reportSelection = useEffectEvent((id: string) => {
+        onStorySelected?.(id);
+    });
+
+    useEffect(() => {
+        if (selectedStoryId !== undefined) {
+            reportSelection(selectedStoryId);
+        }
+    }, [selectedStoryId]);
+
     return (
         <AdwOverlaySplitView
             minSidebarWidth={220}
             maxSidebarWidth={300}
-            sidebar={(
+            sidebar={
                 <AdwToolbarView
-                    topBar={(
+                    top={
                         <AdwHeaderBar
-                            titleWidget={(
-                                <AdwWindowTitle title={title} subtitle={`${String(snapshot.stories.length)} stories`} />
-                            )}
+                            titleWidget={
+                                <AdwWindowTitle title={title} subtitle={storyCount(snapshot.stories.length)} />
+                            }
                         />
-                    )}
+                    }
                 >
                     <StoryNavigator
                         stories={snapshot.stories}
                         errors={snapshot.errors}
-                        selectedId={selected?.id}
+                        selectedId={selectedStoryId}
                         onSelect={setSelectedId}
                     />
                 </AdwToolbarView>
-            )}
+            }
         >
-            {selected
-                ? <StorybookPreview key={selected.id} entry={selected} />
-                : (
-                        <AdwToolbarView topBar={<AdwHeaderBar />}>
-                            <AdwStatusPage
-                                name="storybook-empty"
-                                title={snapshot.isLoading ? "Loading stories" : "Choose a story"}
-                                iconName="applications-development-symbolic"
-                                description="Stories from your project appear in the sidebar."
-                            />
-                        </AdwToolbarView>
-                    )}
+            {selected ? (
+                <StorybookPreview key={selected.id} entry={selected} />
+            ) : (
+                <AdwToolbarView top={<AdwHeaderBar />}>
+                    <AdwStatusPage
+                        name="storybook-empty"
+                        title={snapshot.isLoading ? "Loading stories" : "Choose a story"}
+                        iconName="applications-development-symbolic"
+                        description="Stories from your project appear in the sidebar."
+                    />
+                </AdwToolbarView>
+            )}
         </AdwOverlaySplitView>
     );
 };
@@ -82,10 +104,17 @@ const Storybook = ({
     catalog,
     applicationId = "org.gtkx.Storybook",
     title = "GTKX Storybook",
+    initialStoryId,
+    onStorySelected,
 }: StorybookProps): ReactNode => (
     <AdwApplication applicationId={applicationId} flags={Gio.ApplicationFlags.NON_UNIQUE}>
         <AdwApplicationWindow title={title} defaultWidth={1200} defaultHeight={800} onCloseRequest={quit}>
-            <StorybookView catalog={catalog} title={title} />
+            <StorybookView
+                catalog={catalog}
+                title={title}
+                initialStoryId={initialStoryId}
+                onStorySelected={onStorySelected}
+            />
         </AdwApplicationWindow>
     </AdwApplication>
 );

package/src/explorer.ts

@@ -19,10 +19,21 @@ type StorybookSession = {
 const startStorybook = (options: {
     /** Gio application identifier assigned to the explorer application. */
     applicationId: string;
+    /** Story to select once it is loaded, such as the one a restarted explorer was showing. */
+    initialStoryId?: string | undefined;
+    /** Called with the identifier of each story the explorer selects. */
+    onStorySelected?: ((id: string) => void) | undefined;
 }): StorybookSession => {
     const catalog = new StoryCatalog();
     const root = createRoot(undefined, { onUncaughtError: catalog.reportError.bind(catalog) });
-    root.render(createElement(Storybook, { catalog, applicationId: options.applicationId }));
+    root.render(
+        createElement(Storybook, {
+            catalog,
+            applicationId: options.applicationId,
+            initialStoryId: options.initialStoryId,
+            onStorySelected: options.onStorySelected,
+        }),
+    );
 
     return {
         updateStories: (sources, preview) => catalog.load(sources, preview),

package/src/types.ts

@@ -71,20 +71,16 @@ type Annotations<TArgs extends object> = {
 };
 
 /** Default export metadata describing a component's stories and their shared annotations. */
-type ComponentMeta<TArgs extends object> = Annotations<TArgs> & Pick<
-    ComponentAnnotations<NativeRenderer<TArgs>, TArgs>,
-    "title" | "id" | "includeStories" | "excludeStories"
-> & {
-    /** Component rendered with story args when no custom render annotation applies. */
-    component?: ComponentType<TArgs>;
-    /** Global overrides shared by this component's stories. */
-    globals?: Args;
-};
+type ComponentMeta<TArgs extends object> = Annotations<TArgs> &
+    Pick<ComponentAnnotations<NativeRenderer<TArgs>, TArgs>, "title" | "id" | "includeStories" | "excludeStories"> & {
+        /** Component rendered with story args when no custom render annotation applies. */
+        component?: ComponentType<TArgs>;
+        /** Global overrides shared by this component's stories. */
+        globals?: Args;
+    };
 
 /** Resolves a component's props or accepts an explicitly supplied args object type. */
-type ComponentOrProps<T> = T extends ComponentType<infer Props extends object>
-    ? Props
-    : T extends object ? T : Args;
+type ComponentOrProps<T> = T extends ComponentType<infer Props extends object> ? Props : T extends object ? T : Args;
 
 /** Presents combined inferred args as a single object type. */
 type Simplify<T> = { [Key in keyof T]: T[Key] };
@@ -92,10 +88,12 @@ type Simplify<T> = { [Key in keyof T]: T[Key] };
 /** Infers story args from component props, render functions, decorators, or declared defaults. */
 type ArgsFrom<T> = T extends { component?: infer Component; render?: unknown; decorators?: unknown }
     ? Simplify<
-        (NonNullable<Component> extends ComponentType<infer Props extends object> ? Props : object) &
-        ArgsFromMeta<NativeRenderer, T>
-    >
-    : T extends { args: infer Defaults extends object } ? Defaults : Args;
+          (NonNullable<Component> extends ComponentType<infer Props extends object> ? Props : object) &
+              ArgsFromMeta<NativeRenderer, T>
+      >
+    : T extends { args: infer Defaults extends object }
+      ? Defaults
+      : Args;
 
 /** CSF3 default export metadata typed from a React component or an explicit args type. */
 type Meta<T = Args> = ComponentMeta<ComponentOrProps<T>>;
@@ -112,15 +110,16 @@ type StoryAnnotations<TArgs extends object> = Annotations<TArgs> & {
 type DefaultArgs<T> = T extends { args: infer Defaults } ? Defaults : Record<never, never>;
 
 /** Makes args with metadata defaults optional while preserving other required args. */
-type RequiredStoryArgs<T, TArgs extends object> =
-    Omit<TArgs, keyof DefaultArgs<T>> & Partial<Pick<TArgs, keyof TArgs & keyof DefaultArgs<T>>>;
+type RequiredStoryArgs<T, TArgs extends object> = Omit<TArgs, keyof DefaultArgs<T>> &
+    Partial<Pick<TArgs, keyof TArgs & keyof DefaultArgs<T>>>;
 
 /** CSF3 story object inferred from metadata, a React component, or an explicit args type. */
 type StoryObj<T = Args> = T extends { component?: unknown; render?: unknown; decorators?: unknown; args?: unknown }
-    ? StoryAnnotations<ArgsFrom<T>> & Pick<
-        StorybookAnnotations<NativeRenderer<ArgsFrom<T>>, ArgsFrom<T>, RequiredStoryArgs<T, ArgsFrom<T>>>,
-        "args"
-    >
+    ? StoryAnnotations<ArgsFrom<T>> &
+          Pick<
+              StorybookAnnotations<NativeRenderer<ArgsFrom<T>>, ArgsFrom<T>, RequiredStoryArgs<T, ArgsFrom<T>>>,
+              "args"
+          >
     : StoryAnnotations<ComponentOrProps<T>>;
 
 /** Project annotations shared by all composed stories. */
@@ -155,20 +154,33 @@ type StoryModule = {
     default: unknown;
 };
 
+/** Whether a story's declared args name only args of the component metadata, as stories typed from the metadata do. */
+type IsMetaArgs<TArgs, TMetaArgs> = [Exclude<keyof TArgs, keyof TMetaArgs>] extends [never] ? true : false;
+
+/** Args of a story export: the component metadata's args, or the args type the story declares itself. */
+type StoryArgs<TModule extends StoryModule, TStory> =
+    TStory extends StoryAnnotations<infer TArgs extends object>
+        ? IsMetaArgs<TArgs, ArgsFrom<TModule["default"]>> extends true
+            ? TStory extends StoryAnnotations<ArgsFrom<TModule["default"]>>
+                ? ArgsFrom<TModule["default"]>
+                : TArgs
+            : TArgs
+        : never;
+
 /** Named module exports whose types match CSF3 stories, excluding module bookkeeping. */
 type StoryKeys<TModule extends StoryModule> = {
     [Key in keyof TModule]: Key extends "default" | "__esModule" | "__namedExportsOrder"
         ? never
-        : TModule[Key] extends StoryAnnotations<ArgsFrom<TModule["default"]>>
-            ? Key
-            : never;
-}[keyof TModule] & string;
+        : [StoryArgs<TModule, TModule[Key]>] extends [never]
+          ? never
+          : Key;
+}[keyof TModule] &
+    string;
 
 /** Composed stories keyed by their original named exports. */
-type ComposedStories<TModule extends StoryModule> = Record<
-    StoryKeys<TModule>,
-    ComposedStory<ArgsFrom<TModule["default"]>>
->;
+type ComposedStories<TModule extends StoryModule> = {
+    [Key in StoryKeys<TModule>]: ComposedStory<StoryArgs<TModule, TModule[Key]>>;
+};
 
 export type {
     Args,

package/src/upstream.ts

@@ -1,11 +1,7 @@
+import type { InputType } from "storybook/internal/types";
+import { includeConditionalArg } from "storybook/internal/csf";
 import { composeStory } from "storybook/preview-api";
-import type {
-    ComponentMeta,
-    ComposedStory,
-    Preview,
-    StoryAnnotations,
-    StoryRender,
-} from "./types.js";
+import type { Args, ComponentMeta, ComposedStory, Preview, StoryAnnotations, StoryRender } from "./types.js";
 
 type ComposeStory = <TArgs extends object>(
     ...annotations: [
@@ -19,6 +15,8 @@ type ComposeStory = <TArgs extends object>(
 
 const composeStoryAnnotations = composeStory as ComposeStory;
 
-export { composeStoryAnnotations };
+const isConditionalArgIncluded: (argType: InputType, args: Args, globals: Args) => boolean = includeConditionalArg;
+
+export { composeStoryAnnotations, isConditionalArgIncluded };
 
 export { isExportStory, storyNameFromExport } from "storybook/internal/csf";