@gtkx/storybook 0.0.1

package/src/catalog.ts

@@ -0,0 +1,263 @@
+import type { Args, ArgTypes, ComponentMeta, ComposedStory, Preview, StoryAnnotations } from "./types.js";
+import { composeStories } from "./compose.js";
+import { storyNameFromExport } from "./upstream.js";
+
+/** A lazily loaded CSF module discovered in a Storybook project. */
+type StorySource = {
+    /** Stable module identifier used for caching and error reporting. */
+    id: string;
+    /** Fallback story group title when the module does not declare one. */
+    title: string;
+    /** Imports the module and resolves to its CSF exports. */
+    load: () => Promise<unknown>;
+};
+
+/** A composed story and the metadata used to display it in the explorer. */
+type StoryEntry = {
+    /** Storybook identifier used to preserve the selected story across updates. */
+    id: string;
+    /** Component group title declared by the module or derived from its source. */
+    title: string;
+    /** Display name declared by the story or derived from its export name. */
+    name: string;
+    /** Name of the CSF export that defines this story. */
+    exportName: string;
+    /** Identifier of the module containing this story. */
+    source: string;
+    /** Renderable story with its metadata, decorators, and default args composed. */
+    story: ComposedStory;
+    /** Resolved arg types with explicitly configured explorer controls. */
+    controls: ArgTypes;
+};
+
+/** A source loading or composition failure displayed alongside healthy stories. */
+type StoryLoadError = {
+    /** Identifier of the failed source, or Storybook for a session failure. */
+    source: string;
+    /** Normalized error raised while loading or composing the source. */
+    error: Error;
+};
+
+/** Current explorer contents and loading state exposed to subscribers. */
+type StoryCatalogSnapshot = {
+    /** Successfully composed stories with duplicate identifiers excluded. */
+    stories: StoryEntry[];
+    /** Failures encountered during the latest load or reported by the session. */
+    errors: StoryLoadError[];
+    /** Whether the catalog is waiting for the latest source load to finish. */
+    isLoading: boolean;
+};
+
+type CachedStories = {
+    module: unknown;
+    title: string;
+    preview: Preview;
+    entries: StoryEntry[];
+};
+
+type LoadedSource = StoryLoadError | { source: StorySource; cached: CachedStories };
+
+const EMPTY_PREVIEW: Preview = {};
+
+const normalizeError = (cause: unknown): Error => cause instanceof Error ? cause : new Error(String(cause));
+
+const isObject = (value: unknown): value is Record<string, unknown> =>
+    value !== null && typeof value === "object" && !Array.isArray(value);
+
+const explicitControls = (
+    resolved: ArgTypes,
+    story: StoryAnnotations<Args> | undefined,
+    meta: ComponentMeta<Args>,
+    preview: Preview,
+): ArgTypes => {
+    const controls: ArgTypes = {};
+
+    for (const [argument, annotation] of Object.entries(resolved)) {
+        const control = story?.argTypes?.[argument]?.control ??
+            meta.argTypes?.[argument]?.control ?? preview.argTypes?.[argument]?.control;
+
+        if (control === undefined) {
+            continue;
+        }
+
+        controls[argument] = { ...annotation, control: control === false ? false : annotation?.control ?? control };
+    }
+
+    return controls;
+};
+
+const displayName = (story: StoryAnnotations<Args> | undefined, exportName: string): string => {
+    const name = story?.name;
+
+    if (name === undefined) {
+        return storyNameFromExport(exportName);
+    }
+
+    if (typeof name !== "string") {
+        throw new TypeError("Expected a story display name");
+    }
+
+    return name;
+};
+
+const composeSource = (source: StorySource, module: unknown, preview: Preview): StoryEntry[] => {
+    if (!isObject(module) || !isObject(module.default)) {
+        throw new TypeError(`Expected CSF3 component metadata in ${source.id}`);
+    }
+
+    const title = module.default.title ?? source.title;
+
+    if (typeof title !== "string" || title.trim().length === 0) {
+        throw new TypeError(`Expected a story title in ${source.id}`);
+    }
+
+    const annotations = {
+        ...module,
+        default: { ...module.default, title },
+    } as Record<string, StoryAnnotations<Args>> & { default: ComponentMeta<Args> };
+    const stories = composeStories(annotations, preview);
+
+    return Object.entries(stories).map(([exportName, story]) => ({
+        id: story.id,
+        title,
+        name: displayName(annotations[exportName], exportName),
+        exportName,
+        source: source.id,
+        story,
+        controls: explicitControls(story.argTypes, annotations[exportName], annotations.default, preview),
+    }));
+};
+
+const withoutDuplicateIds = (entries: StoryEntry[], errors: StoryLoadError[]): StoryEntry[] => {
+    const counts: Map<string, number> = new Map();
+
+    for (const entry of entries) {
+        counts.set(entry.id, (counts.get(entry.id) ?? 0) + 1);
+    }
+
+    return entries.filter((entry) => {
+        if (counts.get(entry.id) === 1) {
+            return true;
+        }
+
+        errors.push({ source: entry.source, error: new Error(`Duplicate story ID: ${entry.id}`) });
+
+        return false;
+    });
+};
+
+const collectSources = (loaded: LoadedSource[]) => {
+    const cache: Map<string, CachedStories> = new Map();
+    const entries: StoryEntry[] = [];
+    const errors: StoryLoadError[] = [];
+
+    for (const result of loaded) {
+        if ("error" in result) {
+            errors.push(result);
+        } else {
+            cache.set(result.source.id, result.cached);
+            entries.push(...result.cached.entries);
+        }
+    }
+
+    return { cache, stories: withoutDuplicateIds(entries, errors), errors };
+};
+
+const createSourceCache = (): Map<string, CachedStories> => new Map();
+
+const loadSource = async (
+    source: StorySource,
+    preview: Preview,
+    getCache: () => Map<string, CachedStories>,
+): Promise<LoadedSource> => {
+    try {
+        const module = await source.load();
+        const previous = getCache().get(source.id);
+        const cached = previous !== undefined && previous.module === module &&
+            previous.title === source.title && previous.preview === preview
+            ? previous
+            : { module, title: source.title, preview, entries: composeSource(source, module, preview) };
+
+        return { source, cached };
+    } catch (error) {
+        return { source: source.id, error: normalizeError(error) };
+    }
+};
+
+/** Loads CSF modules and publishes subscribable explorer snapshots. */
+class StoryCatalog {
+    private snapshot: StoryCatalogSnapshot = { stories: [], errors: [], isLoading: false };
+    private readonly listeners: Set<() => void> = new Set();
+    private readonly loadFailures: WeakSet<Error> = new WeakSet();
+    private cache = createSourceCache();
+    private sessionError: StoryLoadError | undefined;
+    private revision = 0;
+
+    /** Returns the current snapshot, retaining its identity until the next update. */
+    getSnapshot = (): StoryCatalogSnapshot => this.snapshot;
+
+    /** Registers a snapshot listener and returns a function that unsubscribes it. */
+    subscribe = (listener: () => void): (() => void) => {
+        this.listeners.add(listener);
+
+        return () => {
+            this.listeners.delete(listener);
+        };
+    };
+
+    private publish(snapshot: StoryCatalogSnapshot): void {
+        this.snapshot = snapshot;
+
+        for (const listener of this.listeners) {
+            listener();
+        }
+    }
+
+    /**
+     * Replaces the catalog with stories composed from the supplied sources and preview.
+     * Only the latest load publishes results; unchanged module identities reuse composed stories.
+     * Rejects with an AggregateError after publishing healthy stories when any source fails.
+     */
+    async load(sources: StorySource[], preview: Preview = EMPTY_PREVIEW): Promise<void> {
+        const revision = ++this.revision;
+        this.publish({ ...this.snapshot, isLoading: true });
+        const loaded = await Promise.all(sources.map((source) => loadSource(source, preview, () => this.cache)));
+
+        if (revision !== this.revision) {
+            return;
+        }
+
+        const { cache, stories, errors } = collectSources(loaded);
+        this.cache = cache;
+        this.sessionError = undefined;
+        this.publish({ stories, errors, isLoading: false });
+
+        if (errors.length > 0) {
+            const failure = new AggregateError(errors.map(({ error }) => error), "Some stories could not be loaded");
+            this.loadFailures.add(failure);
+            throw failure;
+        }
+    }
+
+    /**
+     * Replaces the current session failure while preserving source errors and superseding pending loads.
+     * Ignores aggregate failures already published by this catalog's load operation.
+     */
+    reportError(cause: unknown): void {
+        if (cause instanceof Error && this.loadFailures.has(cause)) {
+            return;
+        }
+
+        this.revision++;
+        const errors = this.snapshot.errors.filter((entry) => entry !== this.sessionError);
+        this.sessionError = { source: "Storybook", error: normalizeError(cause) };
+        this.publish({
+            ...this.snapshot,
+            isLoading: false,
+            errors: [...errors, this.sessionError],
+        });
+    }
+}
+
+export { StoryCatalog };
+export type { StoryCatalogSnapshot, StoryEntry, StoryLoadError, StorySource };

package/src/compose.ts

@@ -0,0 +1,94 @@
+import { createElement } from "react";
+import type {
+    Args,
+    ComponentMeta,
+    ComposedStories,
+    ComposedStory,
+    Preview,
+    StoryAnnotations,
+    StoryModule,
+} from "./types.js";
+import { composeStoryAnnotations, isExportStory } from "./upstream.js";
+
+const requireObject = (value: unknown): void => {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        throw new TypeError("Expected a CSF3 annotation object");
+    }
+};
+
+/**
+ * Composes a CSF3 story into a native React component with resolved defaults and decorators.
+ * Compose outside render to preserve component identity. Rendering props override the composed args.
+ * This function does not create an application, window, or Storybook preview lifecycle.
+ *
+ * @param story The named story's annotations.
+ * @param meta The module's default component metadata.
+ * @param preview Shared project annotations, scoped to this composition.
+ * @param exportName Export name used for the story identifier and default display name.
+ * @returns A renderable component exposing its composed annotations.
+ * @throws If an annotation is not an object or no component or render function is available.
+ */
+const composeStory = <TArgs extends object>(
+    story: StoryAnnotations<NoInfer<TArgs>>,
+    meta: ComponentMeta<TArgs>,
+    preview: Preview = {},
+    exportName?: string,
+): ComposedStory<TArgs> => {
+    requireObject(story);
+    requireObject(meta);
+    requireObject(preview);
+
+    if (!story.render && !meta.render && !preview.render && !meta.component) {
+        throw new TypeError("A story needs a component or render function");
+    }
+
+    return composeStoryAnnotations(story, { ...meta }, preview, {
+        render: (args) => {
+            if (!meta.component) {
+                throw new TypeError("A story needs a component or render function");
+            }
+
+            return createElement(meta.component, args);
+        },
+    }, exportName);
+};
+
+/**
+ * Composes the selected CSF3 exports of a module into native React components.
+ * The default export supplies metadata; its includeStories and excludeStories select named exports.
+ * Returned keys retain the original export names.
+ *
+ * @param stories A story module containing default metadata and named story objects.
+ * @param preview Shared project annotations, scoped to the returned compositions.
+ * @returns Composed components keyed by the selected export names.
+ * @throws If metadata or a selected export is invalid, or a selected story has no renderer.
+ */
+const composeStories = <TModule extends StoryModule>(
+    stories: TModule,
+    preview: Preview = {},
+): ComposedStories<TModule> => {
+    requireObject(stories);
+    requireObject(stories.default);
+    requireObject(preview);
+
+    const meta = stories.default as ComponentMeta<Args>;
+    const composed: Partial<ComposedStories<TModule>> = {};
+
+    for (const [exportName, story] of Object.entries(stories)) {
+        if (exportName === "default" || exportName === "__namedExportsOrder" || !isExportStory(exportName, meta)) {
+            continue;
+        }
+
+        requireObject(story);
+        Object.defineProperty(composed, exportName, {
+            value: composeStory(story as StoryAnnotations<Args>, meta, preview, exportName),
+            enumerable: true,
+            configurable: true,
+            writable: true,
+        });
+    }
+
+    return composed as ComposedStories<TModule>;
+};
+
+export { composeStory, composeStories };

package/src/config.ts

@@ -0,0 +1,14 @@
+/** Story discovery and preview configuration for the native explorer. */
+type StorybookConfig = {
+    /** Project-relative globs; defaults to CSF story files under src. */
+    stories?: string[];
+    /** Additional project-relative globs excluded from discovery. */
+    exclude?: string[];
+    /** Project-relative preview module; defaults to a discovered .storybook/preview file. */
+    preview?: string;
+};
+
+/** Returns a typed explorer configuration without changing it or resolving its paths. */
+const defineConfig = (config: StorybookConfig): StorybookConfig => config;
+
+export { defineConfig, type StorybookConfig };

package/src/controls.tsx

@@ -0,0 +1,206 @@
+import type { ReactNode } from "react";
+import { ComboRow } from "@gtkx/components";
+import { markupEscapeText } from "@gtkx/gi/glib";
+import { AdwActionRow, AdwEntryRow, AdwPreferencesGroup, AdwSpinRow, AdwSwitchRow } from "@gtkx/jsx/adw";
+import { GtkAdjustment } from "@gtkx/jsx/gtk";
+import type { Args, ArgTypes } from "./types.js";
+
+type ControlsProps = { argTypes: ArgTypes; args: Args; onChange: (update: Args) => void };
+
+type ControlProps = {
+    argument: string;
+    title: string;
+    value: unknown;
+    type: string;
+    settings: Args;
+    options: unknown;
+    isDisabled: boolean;
+    onChange: (update: Args) => void;
+};
+
+const isObject = (value: unknown): value is Args =>
+    value !== null && typeof value === "object" && !Array.isArray(value);
+
+const isWithinBoundsOrAbsent = (value: unknown, min: number, max: number): boolean =>
+    value === undefined || (typeof value === "number" && Number.isFinite(value) && value >= min && value <= max);
+
+const controlTitle = (name: unknown, argument: string): string => typeof name === "string" ? name : argument;
+
+const numberDigits = (step: number): number => {
+    const [coefficient = "", exponent = "0"] = String(step).split("e", 2);
+    const fraction = coefficient.split(".", 2)[1]?.length ?? 0;
+    const digits = Math.max(0, fraction - Number(exponent));
+
+    return Math.min(20, digits);
+};
+
+const UnsupportedControl = ({ title, description }: { title: string; description: string }): ReactNode => (
+    <AdwActionRow title={markupEscapeText(title, -1)} subtitle={markupEscapeText(description, -1)} sensitive={false} />
+);
+
+const NumberControl = ({
+    argument,
+    title,
+    value,
+    settings,
+    isDisabled,
+    onChange,
+}: Omit<ControlProps, "type" | "options">): ReactNode => {
+    const min = settings.min ?? -Number.MAX_SAFE_INTEGER;
+    const max = settings.max ?? Number.MAX_SAFE_INTEGER;
+    const step = settings.step ?? 1;
+
+    if (
+        typeof min !== "number" || typeof max !== "number" || typeof step !== "number" ||
+        !Number.isFinite(min) || !Number.isFinite(max) || !Number.isFinite(step) ||
+        step <= 0 || min > max || !isWithinBoundsOrAbsent(value, min, max)
+    ) {
+        return <UnsupportedControl title={title} description="Provide a finite number and valid bounds." />;
+    }
+
+    const currentValue = typeof value === "number" ? value : Math.max(min, Math.min(0, max));
+
+    return (
+        <AdwSpinRow
+            name={`storybook-control-${argument}`}
+            title={markupEscapeText(title, -1)}
+            sensitive={!isDisabled}
+            value={currentValue}
+            digits={numberDigits(step)}
+            numeric
+            widthChars={8}
+            adjustment={(
+                <GtkAdjustment
+                    lower={min}
+                    upper={max}
+                    stepIncrement={step}
+                    pageIncrement={Math.min(Number.MAX_VALUE, step * 10)}
+                    value={currentValue}
+                />
+            )}
+            onNotifyValue={(next) => {
+                if (
+                    typeof next === "number" && Number.isFinite(next) &&
+                    next >= min && next <= max && !Object.is(next, value)
+                ) {
+                    onChange({ [argument]: next });
+                }
+            }}
+        />
+    );
+};
+
+const SelectControl = (props: Omit<ControlProps, "type">): ReactNode => {
+    const { argument, title, value, options, settings, isDisabled, onChange } = props;
+    if (!Array.isArray(options) || options.length === 0 || options.some((option: unknown) =>
+        option !== null && typeof option !== "string" && typeof option !== "number" && typeof option !== "boolean")) {
+        return <UnsupportedControl title={title} description="Provide a list of text, number, or boolean options." />;
+    }
+
+    const values: unknown[] = options;
+    const selected = values.findIndex((option) => Object.is(option, value));
+    const labels = isObject(settings.labels) ? settings.labels : {};
+    const items = values.map((option, index) => {
+        const label = labels[String(option)];
+
+        return { id: String(index), value: typeof label === "string" ? label : String(option) };
+    });
+
+    return (
+        <ComboRow
+            name={`storybook-control-${argument}`}
+            title={markupEscapeText(title, -1)}
+            sensitive={!isDisabled}
+            items={items}
+            selectedId={selected === -1 ? null : String(selected)}
+            onSelectionChanged={(id) => {
+                const index = Number(id);
+
+                if (Number.isSafeInteger(index) && index >= 0 && index < values.length) {
+                    onChange({ [argument]: values[index] });
+                }
+            }}
+        />
+    );
+};
+
+const Control = (props: ControlProps): ReactNode => {
+    const { argument, title, value, type, isDisabled, onChange } = props;
+
+    switch (type) {
+        case "boolean": {
+            return (
+                <AdwSwitchRow
+                    name={`storybook-control-${argument}`}
+                    title={markupEscapeText(title, -1)}
+                    sensitive={!isDisabled}
+                    active={value === true}
+                    onNotifyActive={(active) => {
+                        if (typeof active === "boolean" && !Object.is(active, value)) {
+                            onChange({ [argument]: active });
+                        }
+                    }}
+                />
+            );
+        }
+        case "text": {
+            return (
+                <AdwEntryRow
+                    name={`storybook-control-${argument}`}
+                    title={markupEscapeText(title, -1)}
+                    sensitive={!isDisabled}
+                    text={typeof value === "string" ? value : ""}
+                    onNotifyText={(text) => {
+                        if (typeof text === "string" && !Object.is(text, value)) {
+                            onChange({ [argument]: text });
+                        }
+                    }}
+                />
+            );
+        }
+        case "number":
+        case "range": {
+            return <NumberControl {...props} />;
+        }
+        case "select":
+        case "radio":
+        case "inline-radio": {
+            return <SelectControl {...props} />;
+        }
+        default: {
+            return <UnsupportedControl title={title} description={`Unsupported control: ${type}`} />;
+        }
+    }
+};
+
+const Controls = ({ argTypes, args, onChange }: ControlsProps): ReactNode => (
+    <AdwPreferencesGroup title="Controls">
+        {Object.entries(argTypes).map(([argument, annotation]) => {
+            const control: unknown = annotation?.control;
+            const table: unknown = annotation?.table;
+
+            if (control === undefined || control === false || (isObject(table) && table.disable === true)) {
+                return null;
+            }
+
+            const settings = isObject(control) ? control : {};
+            const type = typeof control === "string" ? control : settings.type;
+
+            return (
+                <Control
+                    key={argument}
+                    argument={argument}
+                    title={controlTitle(annotation?.name, argument)}
+                    value={args[argument]}
+                    type={typeof type === "string" ? type : "unknown"}
+                    settings={settings}
+                    options={annotation?.options}
+                    isDisabled={settings.disable === true}
+                    onChange={onChange}
+                />
+            );
+        })}
+    </AdwPreferencesGroup>
+);
+
+export { Controls };

package/src/explorer-navigator.tsx

@@ -0,0 +1,120 @@
+import type { ReactNode } from "react";
+import { markupEscapeText } from "@gtkx/gi/glib";
+import * as Gtk from "@gtkx/gi/gtk";
+import { AdwActionRow, AdwStatusPage } from "@gtkx/jsx/adw";
+import { GtkBox, GtkLabel, GtkListBox, GtkScrolledWindow, GtkSearchEntry } from "@gtkx/jsx/gtk";
+import { useState } from "react";
+import type { StoryEntry, StoryLoadError } from "./catalog.js";
+
+type NavigatorProps = {
+    stories: StoryEntry[];
+    errors: StoryLoadError[];
+    selectedId: string | undefined;
+    onSelect: (id: string) => void;
+};
+
+type GroupProps = Pick<NavigatorProps, "selectedId" | "onSelect"> & {
+    title: string;
+    entries: StoryEntry[];
+};
+
+const StoryGroup = ({ title, entries, selectedId, onSelect }: GroupProps): ReactNode => (
+    <GtkBox orientation={Gtk.Orientation.VERTICAL} spacing={6}>
+        <GtkLabel
+            label={title}
+            xalign={0}
+            marginStart={18}
+            marginEnd={18}
+            cssClasses={["heading"]}
+            wrap
+        />
+        <GtkListBox
+            cssClasses={["navigation-sidebar"]}
+            selectedIndex={entries.findIndex((entry) => entry.id === selectedId)}
+            onRowSelected={(row) => {
+                const entry = row === null ? undefined : entries[row.getIndex()];
+
+                if (entry) {
+                    onSelect(entry.id);
+                }
+            }}
+        >
+            {entries.map((entry) => (
+                <AdwActionRow
+                    key={entry.id}
+                    name={`storybook-story-${entry.id}`}
+                    title={markupEscapeText(entry.name, -1)}
+                    activatable
+                    onActivated={() => {
+                        onSelect(entry.id);
+                    }}
+                />
+            ))}
+        </GtkListBox>
+    </GtkBox>
+);
+
+const LoadErrors = ({ errors }: Pick<NavigatorProps, "errors">): ReactNode => errors.length > 0 && (
+    <GtkBox name="storybook-load-errors" orientation={Gtk.Orientation.VERTICAL} spacing={6}>
+        {errors.map(({ source, error }, index) => (
+            <GtkLabel
+                key={`${source}-${String(index)}`}
+                label={`${source}\n${error.message.slice(0, 500)}`}
+                cssClasses={["error"]}
+                marginStart={18}
+                marginEnd={18}
+                wrap
+                selectable
+                xalign={0}
+            />
+        ))}
+    </GtkBox>
+);
+
+const StoryNavigator = ({ stories, errors, selectedId, onSelect }: NavigatorProps): ReactNode => {
+    const [search, setSearch] = useState("");
+    const query = search.trim().toLocaleLowerCase();
+    const groups = Map.groupBy(
+        stories.filter((entry) => `${entry.title} ${entry.name}`.toLocaleLowerCase().includes(query)),
+        (entry) => entry.title,
+    );
+
+    return (
+        <GtkBox orientation={Gtk.Orientation.VERTICAL} spacing={12}>
+            <GtkSearchEntry
+                name="storybook-search"
+                placeholderText="Search stories"
+                text={search}
+                marginStart={12}
+                marginEnd={12}
+                onChanged={(entry) => {
+                    setSearch(entry.getText());
+                }}
+            />
+            <GtkScrolledWindow hscrollbarPolicy={Gtk.PolicyType.NEVER} vexpand>
+                <GtkBox orientation={Gtk.Orientation.VERTICAL} spacing={18} marginBottom={18}>
+                    {[...groups].map(([title, entries]) => (
+                        <StoryGroup
+                            key={title}
+                            title={title}
+                            entries={entries}
+                            selectedId={selectedId}
+                            onSelect={onSelect}
+                        />
+                    ))}
+                    {groups.size === 0 && (
+                        <AdwStatusPage
+                            name="storybook-no-matches"
+                            title={query ? "No matching stories" : "No stories"}
+                            iconName="system-search-symbolic"
+                            cssClasses={["compact"]}
+                        />
+                    )}
+                    <LoadErrors errors={errors} />
+                </GtkBox>
+            </GtkScrolledWindow>
+        </GtkBox>
+    );
+};
+
+export { StoryNavigator };