@gtkx/storybook 0.0.1

package/src/explorer-preview.tsx

@@ -0,0 +1,207 @@
+import type { ReactNode } from "react";
+import { markupEscapeText } from "@gtkx/gi/glib";
+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 { Component, useCallback, useMemo, useState } from "react";
+import type { StoryEntry } from "./catalog.js";
+import type { Args, ComposedStory } from "./types.js";
+import { ActionsPanel } from "./actions-panel.js";
+import { ActionStore, bindActions } from "./actions.js";
+import { Controls } from "./controls.js";
+
+type PreviewProps = {
+    entry: StoryEntry;
+};
+
+type PreviewState = {
+    story: ComposedStory;
+    args: Args;
+    generation: number;
+    error: Error | null;
+    actions: ActionStore;
+};
+
+type BoundaryProps = { children: ReactNode; args: Args };
+type BoundaryState = { error: Error | null; args: Args };
+
+class PreviewBoundary extends Component<BoundaryProps, BoundaryState> {
+    static getDerivedStateFromProps(props: BoundaryProps, state: BoundaryState): BoundaryState | null {
+        return props.args === state.args ? null : { error: null, args: props.args };
+    }
+
+    static getDerivedStateFromError(error: unknown): Pick<BoundaryState, "error"> {
+        return { error: error instanceof Error ? error : new Error(String(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."}
+                    />
+                );
+    }
+}
+
+const previewMode = (story: ComposedStory): "content" | "window" | "dialog" => {
+    const gtkx = story.parameters.gtkx;
+    const mode = typeof gtkx === "object" && gtkx !== null && "preview" in gtkx ? gtkx.preview : "content";
+
+    if (mode !== "content" && mode !== "window" && mode !== "dialog") {
+        throw new Error("Unsupported GTKX story preview mode");
+    }
+
+    return mode;
+};
+
+const PreviewContent = ({ story: Story, args }: { story: ComposedStory; args: Args }): ReactNode => {
+    const mode = previewMode(Story);
+
+    if (mode !== "content") {
+        return (
+            <>
+                <AdwStatusPage
+                    title={mode === "window" ? "Window preview" : "Dialog preview"}
+                    iconName="window-new-symbolic"
+                    description="The story owns its presentation. Reset to open it again."
+                />
+                {createPortal(<Story {...args} />, rootElement)}
+            </>
+        );
+    }
+
+    const margin = Story.parameters.layout === "fullscreen" ? 0 : 24;
+    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>
+    );
+};
+
+const usePreviewState = ({ entry }: PreviewProps) => {
+    const [state, setState] = useState<PreviewState>(() => ({
+        story: entry.story,
+        args: { ...entry.story.args },
+        generation: 0,
+        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 boundArgs = useMemo(
+        () => bindActions(state.args, state.story.argTypes, state.actions, onError),
+        [state.args, state.story.argTypes, state.actions, onError],
+    );
+
+    if (state.story !== entry.story) {
+        setState({
+            story: entry.story,
+            args: { ...entry.story.args },
+            generation: state.generation + 1,
+            error: null,
+            actions: new ActionStore(),
+        });
+    }
+
+    const reset = (): void => {
+        setState((current) => ({
+            story: entry.story,
+            args: { ...entry.story.args },
+            generation: current.generation + 1,
+            error: null,
+            actions: new ActionStore(),
+        }));
+    };
+
+    const onChange = (args: Args): void => {
+        setState((current) => ({ ...current, args: { ...current.args, ...args } }));
+    };
+
+    return { state, boundArgs, reset, onChange };
+};
+
+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
+    >
+        <GtkBox
+            orientation={Gtk.Orientation.VERTICAL}
+            spacing={24}
+            marginTop={18}
+            marginBottom={18}
+            marginStart={12}
+            marginEnd={12}
+        >
+            <Controls argTypes={entry.controls} args={args} onChange={onChange} />
+            <ActionsPanel store={actions} />
+        </GtkBox>
+    </GtkScrolledWindow>
+);
+
+const StorybookPreview = ({ entry }: PreviewProps): ReactNode => {
+    const { state, boundArgs, reset, onChange } = usePreviewState({ entry });
+
+    return (
+        <AdwToolbarView
+            hexpand
+            vexpand
+            topBar={(
+                <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."}
+                                    />
+                                )}
+                    </PreviewBoundary>
+                </GtkBox>
+                <StoryInspector entry={entry} actions={state.actions} args={state.args} onChange={onChange} />
+            </GtkBox>
+        </AdwToolbarView>
+    );
+};
+
+export { StorybookPreview };

package/src/explorer-view.tsx

@@ -0,0 +1,93 @@
+import type { ReactNode } from "react";
+import * as Gio from "@gtkx/gi/gio";
+import {
+    AdwApplication,
+    AdwApplicationWindow,
+    AdwHeaderBar,
+    AdwOverlaySplitView,
+    AdwStatusPage,
+    AdwToolbarView,
+    AdwWindowTitle,
+} from "@gtkx/jsx/adw";
+import { quit } from "@gtkx/react";
+import { useCallback, useState, useSyncExternalStore } from "react";
+import type { StoryCatalog } from "./catalog.js";
+import { StoryNavigator } from "./explorer-navigator.js";
+import { StorybookPreview } from "./explorer-preview.js";
+
+/** Configuration for the native Storybook application shell. */
+type StorybookProps = {
+    /** Source catalog whose stories and loading errors appear in the explorer. */
+    catalog: StoryCatalog;
+    /** Gio application identifier; defaults to org.gtkx.Storybook. */
+    applicationId?: string;
+    /** Explorer window and sidebar title; defaults to GTKX Storybook. */
+    title?: string;
+};
+
+type StorybookViewProps = Pick<StorybookProps, "catalog" | "title">;
+
+const StorybookView = ({ catalog, title = "GTKX Storybook" }: 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 selected = snapshot.stories.find((entry) => entry.id === selectedId) ?? snapshot.stories[0];
+
+    if (selectedId !== selected?.id) {
+        setSelectedId(selected?.id);
+    }
+
+    return (
+        <AdwOverlaySplitView
+            minSidebarWidth={220}
+            maxSidebarWidth={300}
+            sidebar={(
+                <AdwToolbarView
+                    topBar={(
+                        <AdwHeaderBar
+                            titleWidget={(
+                                <AdwWindowTitle title={title} subtitle={`${String(snapshot.stories.length)} stories`} />
+                            )}
+                        />
+                    )}
+                >
+                    <StoryNavigator
+                        stories={snapshot.stories}
+                        errors={snapshot.errors}
+                        selectedId={selected?.id}
+                        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>
+                    )}
+        </AdwOverlaySplitView>
+    );
+};
+
+/** Renders the Adwaita explorer application with navigation, story previews, controls, and actions. */
+const Storybook = ({
+    catalog,
+    applicationId = "org.gtkx.Storybook",
+    title = "GTKX Storybook",
+}: StorybookProps): ReactNode => (
+    <AdwApplication applicationId={applicationId} flags={Gio.ApplicationFlags.NON_UNIQUE}>
+        <AdwApplicationWindow title={title} defaultWidth={1200} defaultHeight={800} onCloseRequest={quit}>
+            <StorybookView catalog={catalog} title={title} />
+        </AdwApplicationWindow>
+    </AdwApplication>
+);
+
+export { Storybook };

package/src/explorer.ts

@@ -0,0 +1,44 @@
+import { createRoot } from "@gtkx/react";
+import { createElement } from "react";
+import type { StorySource } from "./catalog.js";
+import type { Preview } from "./types.js";
+import { StoryCatalog } from "./catalog.js";
+import { Storybook } from "./explorer-view.js";
+
+/** Controls a running native Storybook explorer and its source catalog. */
+type StorybookSession = {
+    /** Replaces discovered sources and preview annotations, rejecting if any source fails to load. */
+    updateStories: (sources: StorySource[], preview?: Preview) => Promise<void>;
+    /** Displays a session failure while keeping successfully loaded stories available. */
+    reportStorybookError: (cause: unknown) => void;
+    /** Unmounts the explorer and its story windows or dialogs. */
+    stop: () => void;
+};
+
+/** Starts a native explorer and returns the handle used to load stories and stop it. */
+const startStorybook = (options: {
+    /** Gio application identifier assigned to the explorer application. */
+    applicationId: string;
+}): StorybookSession => {
+    const catalog = new StoryCatalog();
+    const root = createRoot(undefined, { onUncaughtError: catalog.reportError.bind(catalog) });
+    root.render(createElement(Storybook, { catalog, applicationId: options.applicationId }));
+
+    return {
+        updateStories: (sources, preview) => catalog.load(sources, preview),
+        reportStorybookError: (cause) => {
+            catalog.reportError(cause);
+        },
+        stop: () => {
+            root.unmount();
+        },
+    };
+};
+
+export { startStorybook };
+export type { StorybookSession };
+export type { StoryCatalogSnapshot, StoryEntry, StoryLoadError, StorySource } from "./catalog.js";
+
+export { StoryCatalog } from "./catalog.js";
+
+export { Storybook } from "./explorer-view.js";

package/src/index.ts

@@ -0,0 +1,16 @@
+export { action } from "./actions.js";
+export type { ActionCallback } from "./actions.js";
+export { composeStories, composeStory } from "./compose.js";
+export type {
+    Args,
+    ArgTypes,
+    ComposedStories,
+    ComposedStory,
+    Decorator,
+    Meta,
+    Preview,
+    StoryContext,
+    StoryContextUpdate,
+    StoryObj,
+    StoryRender,
+} from "./types.js";

package/src/types.ts

@@ -0,0 +1,205 @@
+import type * as Gtk from "@gtkx/gi/gtk";
+import type { ComponentType, ReactNode } from "react";
+import type {
+    ComponentAnnotations,
+    GlobalTypes,
+    Renderer,
+    ArgTypes as StorybookArgTypes,
+    StoryContext as StorybookContext,
+} from "storybook/internal/types";
+
+/** Named values supplied to a story, including component props and custom render args. */
+type Args = Record<string, unknown>;
+
+/** Storybook renderer types for React content rendered as native GTK widgets. */
+type NativeRenderer<TArgs extends object = Args> = Renderer & {
+    /** React component receiving the story's args. */
+    component: ComponentType<TArgs>;
+    /** React content returned by story rendering. */
+    storyResult: ReactNode;
+    /** Native widget type representing the preview canvas. */
+    canvasElement: Gtk.Widget;
+};
+
+/** Explicit argument metadata used to configure native controls and named actions. */
+type ArgTypes<TArgs extends object = Args> = Partial<StorybookArgTypes<TArgs>>;
+
+/** Composed story identity, args, and annotations available to render functions and decorators. */
+type StoryContext<TArgs extends object = Args> = Pick<
+    StorybookContext<NativeRenderer<TArgs>, TArgs>,
+    "id" | "name" | "title" | "args" | "initialArgs" | "argTypes" | "viewMode"
+> & {
+    /** Parameters merged from preview, component metadata, and the story. */
+    parameters: Args;
+    /** Global values after applying preview defaults and metadata or story overrides. */
+    globals: Args;
+};
+
+/** Renders native React content from the current story args and composition context. */
+type StoryRender<TArgs extends object = Args> = (args: TArgs, context: StoryContext<TArgs>) => ReactNode;
+
+/** Values a decorator can override when invoking the decorated story. */
+type StoryContextUpdate<TArgs extends object = Args> = {
+    /** Partial args merged into the current invocation without changing composed defaults. */
+    args?: Partial<TArgs>;
+    /** Global values overridden for the decorated invocation. */
+    globals?: Args;
+};
+
+/** Wraps story content and can override args or globals when invoking the supplied Story function. */
+type Decorator<TArgs extends object = Args> = (
+    Story: (update?: StoryContextUpdate<TArgs>) => ReactNode,
+    context: StoryContext<TArgs>,
+) => ReactNode;
+
+/** Shared CSF annotations accepted at preview, component, and story scope. */
+type Annotations<TArgs extends object> = {
+    /** Default args, with more specific annotation scopes taking precedence. */
+    args?: Partial<TArgs>;
+    /** Explicit argument descriptions, controls, and action registrations. */
+    argTypes?: ArgTypes<TArgs>;
+    /** Parameters merged across scopes, including native preview and layout settings. */
+    parameters?: Args;
+    /** Wrappers composed around the story's render function. */
+    decorators?: Decorator<TArgs>[];
+    /** Custom renderer used in place of the component or a less specific render annotation. */
+    render?: StoryRender<TArgs>;
+    /** Storybook tags composed with tags from other annotation scopes. */
+    tags?: string[];
+};
+
+/** 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;
+};
+
+/** 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;
+
+/** Presents combined inferred args as a single object type. */
+type Simplify<T> = { [Key in keyof T]: T[Key] };
+
+/** Combines the argument requirements of every member of a union. */
+type UnionToIntersection<T> = (
+    T extends unknown ? (value: T) => void : never
+) extends (value: infer Intersection) => void ? Intersection : never;
+
+/** Retains explicitly named args while removing broad index signatures. */
+type DeclaredArgs<T> = {
+    [Key in keyof T as string extends Key
+        ? never
+        : number extends Key ? never : symbol extends Key ? never : Key]: T[Key];
+};
+
+/** Extracts the args accepted by a custom render function. */
+type RenderArgs<T> = T extends (args: infer Props extends object, context: never) => ReactNode ? Props : object;
+
+/** Combines the args required by a metadata object's decorators. */
+type DecoratorArgs<T> = T extends readonly (infer Item)[]
+    ? UnionToIntersection<Item extends Decorator<infer Props extends object> ? Props : object>
+    : object;
+
+/** Infers story args from component props, render functions, decorators, or declared defaults. */
+type ArgsFrom<T> = T extends { component?: infer Component; render?: infer Render; decorators?: infer Decorators }
+    ? Simplify<
+        (NonNullable<Component> extends ComponentType<infer Props extends object> ? Props : object) &
+        DeclaredArgs<RenderArgs<NonNullable<Render>> & DecoratorArgs<NonNullable<Decorators>>>
+    >
+    : 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>>;
+
+/** Annotations for one CSF3 story object, including its display name and global overrides. */
+type StoryAnnotations<TArgs extends object> = Annotations<TArgs> & {
+    /** Display name overriding the name derived from the story's named export. */
+    name?: string;
+    /** Global overrides applied specifically to this story. */
+    globals?: Args;
+};
+
+/** Extracts args already defaulted by component metadata. */
+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>>>;
+
+/** 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>> & (Record<never, never> extends RequiredStoryArgs<T, ArgsFrom<T>>
+        ? { args?: RequiredStoryArgs<T, ArgsFrom<T>> }
+        : { args: RequiredStoryArgs<T, ArgsFrom<T>> })
+    : StoryAnnotations<ComponentOrProps<T>>;
+
+/** Project annotations shared by all composed stories. */
+type Preview = Annotations<Args> & {
+    /** Initial global values available in story rendering and decorators. */
+    initialGlobals?: Args;
+    /** Storybook metadata describing global values; native toolbar controls are not provided. */
+    globalTypes?: GlobalTypes;
+};
+
+/** Renderable story with merged annotations; props override its composed default args. */
+type ComposedStory<TArgs extends object = Args> = ((args: Partial<TArgs>) => ReactNode) & {
+    /** Default args merged across preview, component metadata, and story annotations. */
+    args: Partial<TArgs>;
+    /** Composed argument metadata available to native controls and actions. */
+    argTypes: ArgTypes<TArgs>;
+    /** Composed parameters available to the renderer and explorer. */
+    parameters: Args;
+    /** Composed global values available in story context. */
+    globals: Args;
+    /** Storybook identifier derived from component identity and the story export. */
+    id: string;
+    /** Story name attached by Storybook's portable composition API. */
+    storyName: string;
+    /** Tags resulting from composition across annotation scopes. */
+    tags: string[];
+};
+
+/** Imported CSF module containing default metadata and named story exports. */
+type StoryModule = {
+    /** Component metadata validated when the module is composed. */
+    default: unknown;
+};
+
+/** 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;
+
+/** Composed stories keyed by their original named exports. */
+type ComposedStories<TModule extends StoryModule> = Record<
+    StoryKeys<TModule>,
+    ComposedStory<ArgsFrom<TModule["default"]>>
+>;
+
+export type {
+    Args,
+    ArgTypes,
+    ComponentMeta,
+    ComposedStories,
+    ComposedStory,
+    Decorator,
+    Meta,
+    Preview,
+    StoryAnnotations,
+    StoryContext,
+    StoryContextUpdate,
+    StoryModule,
+    StoryObj,
+    StoryRender,
+};

package/src/upstream.ts

@@ -0,0 +1,24 @@
+import { composeStory } from "storybook/preview-api";
+import type {
+    ComponentMeta,
+    ComposedStory,
+    Preview,
+    StoryAnnotations,
+    StoryRender,
+} from "./types.js";
+
+type ComposeStory = <TArgs extends object>(
+    ...annotations: [
+        story: StoryAnnotations<TArgs>,
+        meta: ComponentMeta<TArgs>,
+        preview: Preview,
+        renderer: { render: StoryRender<TArgs> },
+        exportName?: string,
+    ]
+) => ComposedStory<TArgs>;
+
+const composeStoryAnnotations = composeStory as ComposeStory;
+
+export { composeStoryAnnotations };
+
+export { isExportStory, storyNameFromExport } from "storybook/internal/csf";