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

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,31 +23,53 @@ 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={
                 <AdwToolbarView
-                    topBar={
+                    top={
                         <AdwHeaderBar
                             titleWidget={
-                                <AdwWindowTitle title={title} subtitle={`${String(snapshot.stories.length)} stories`} />
+                                <AdwWindowTitle title={title} subtitle={storyCount(snapshot.stories.length)} />
                             }
                         />
                     }
@@ -55,7 +77,7 @@ const StorybookView = ({ catalog, title = "GTKX Storybook" }: StorybookViewProps
                     <StoryNavigator
                         stories={snapshot.stories}
                         errors={snapshot.errors}
-                        selectedId={selected?.id}
+                        selectedId={selectedStoryId}
                         onSelect={setSelectedId}
                     />
                 </AdwToolbarView>
@@ -64,7 +86,7 @@ const StorybookView = ({ catalog, title = "GTKX Storybook" }: StorybookViewProps
             {selected ? (
                 <StorybookPreview key={selected.id} entry={selected} />
             ) : (
-                <AdwToolbarView topBar={<AdwHeaderBar />}>
+                <AdwToolbarView top={<AdwHeaderBar />}>
                     <AdwStatusPage
                         name="storybook-empty"
                         title={snapshot.isLoading ? "Loading stories" : "Choose a story"}
@@ -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

@@ -154,21 +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;
+        : [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,5 +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: [
@@ -13,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";