@gtkx/storybook 0.0.1 → 2.0.0-beta.12

package/src/controls.tsx

@@ -7,6 +7,9 @@ import type { Args, ArgTypes } from "./types.js";
 
 type ControlsProps = { argTypes: ArgTypes; args: Args; onChange: (update: Args) => void };
 
+const NO_SELECTION_ID = "no-selection";
+const NO_SELECTION_LABEL = "Choose option...";
+
 type ControlProps = {
     argument: string;
     title: string;
@@ -24,7 +27,7 @@ const isObject = (value: unknown): value is Args =>
 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 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);
@@ -51,9 +54,15 @@ const NumberControl = ({
     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)
+        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." />;
     }
@@ -69,7 +78,7 @@ const NumberControl = ({
             digits={numberDigits(step)}
             numeric
             widthChars={8}
-            adjustment={(
+            adjustment={
                 <GtkAdjustment
                     lower={min}
                     upper={max}
@@ -77,12 +86,9 @@ const NumberControl = ({
                     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)
-                ) {
+                if (!Object.is(next, value)) {
                     onChange({ [argument]: next });
                 }
             }}
@@ -92,19 +98,31 @@ const NumberControl = ({
 
 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")) {
+    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)];
+    const items = [
+        { id: NO_SELECTION_ID, value: NO_SELECTION_LABEL },
+        ...values.map((option, index) => {
+            const label = labels[String(option)];
 
-        return { id: String(index), value: typeof label === "string" ? label : String(option) };
-    });
+            return { id: String(index), value: typeof label === "string" ? label : String(option) };
+        }),
+    ];
 
     return (
         <ComboRow
@@ -112,13 +130,19 @@ const SelectControl = (props: Omit<ControlProps, "type">): ReactNode => {
             title={markupEscapeText(title, -1)}
             sensitive={!isDisabled}
             items={items}
-            selectedId={selected === -1 ? null : String(selected)}
+            selectedId={selected === -1 ? NO_SELECTION_ID : String(selected)}
             onSelectionChanged={(id) => {
-                const index = Number(id);
+                if (id === NO_SELECTION_ID) {
+                    onChange({ [argument]: undefined });
 
-                if (Number.isSafeInteger(index) && index >= 0 && index < values.length) {
-                    onChange({ [argument]: values[index] });
+                    return;
                 }
+
+                if (id === null) {
+                    return;
+                }
+
+                onChange({ [argument]: values[Number(id)] });
             }}
         />
     );
@@ -136,7 +160,7 @@ const Control = (props: ControlProps): ReactNode => {
                     sensitive={!isDisabled}
                     active={value === true}
                     onNotifyActive={(active) => {
-                        if (typeof active === "boolean" && !Object.is(active, value)) {
+                        if (!Object.is(active, value)) {
                             onChange({ [argument]: active });
                         }
                     }}
@@ -151,7 +175,7 @@ const Control = (props: ControlProps): ReactNode => {
                     sensitive={!isDisabled}
                     text={typeof value === "string" ? value : ""}
                     onNotifyText={(text) => {
-                        if (typeof text === "string" && !Object.is(text, value)) {
+                        if (!Object.is(text, value)) {
                             onChange({ [argument]: text });
                         }
                     }}
@@ -177,9 +201,9 @@ 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;
+            const table = isObject(annotation?.table) ? annotation.table : {};
 
-            if (control === undefined || control === false || (isObject(table) && table.disable === true)) {
+            if (control === undefined || control === false || table.disable === true) {
                 return null;
             }
 
@@ -195,7 +219,7 @@ const Controls = ({ argTypes, args, onChange }: ControlsProps): ReactNode => (
                     type={typeof type === "string" ? type : "unknown"}
                     settings={settings}
                     options={annotation?.options}
-                    isDisabled={settings.disable === true}
+                    isDisabled={settings.disable === true || table.readonly === true}
                     onChange={onChange}
                 />
             );

package/src/explorer-navigator.tsx

@@ -20,14 +20,7 @@ type GroupProps = Pick<NavigatorProps, "selectedId" | "onSelect"> & {
 
 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
-        />
+        <GtkLabel label={title} xalign={0} marginStart={18} marginEnd={18} cssClasses={["heading"]} wrap />
         <GtkListBox
             cssClasses={["navigation-sidebar"]}
             selectedIndex={entries.findIndex((entry) => entry.id === selectedId)}
@@ -54,22 +47,23 @@ const StoryGroup = ({ title, entries, selectedId, onSelect }: GroupProps): React
     </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 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("");

package/src/explorer-preview.tsx

@@ -4,6 +4,7 @@ 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";
@@ -32,23 +33,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."
+                }
+            />
+        );
     }
 }
 
@@ -108,11 +111,16 @@ 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],
@@ -148,12 +156,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}
@@ -175,27 +178,29 @@ const StorybookPreview = ({ entry }: PreviewProps): ReactNode => {
         <AdwToolbarView
             hexpand
             vexpand
-            topBar={(
+            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."}
-                                    />
-                                )}
+                        {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

@@ -42,15 +42,15 @@ const StorybookView = ({ catalog, title = "GTKX Storybook" }: StorybookViewProps
         <AdwOverlaySplitView
             minSidebarWidth={220}
             maxSidebarWidth={300}
-            sidebar={(
+            sidebar={
                 <AdwToolbarView
-                    topBar={(
+                    topBar={
                         <AdwHeaderBar
-                            titleWidget={(
+                            titleWidget={
                                 <AdwWindowTitle title={title} subtitle={`${String(snapshot.stories.length)} stories`} />
-                            )}
+                            }
                         />
-                    )}
+                    }
                 >
                     <StoryNavigator
                         stories={snapshot.stories}
@@ -59,20 +59,20 @@ const StorybookView = ({ catalog, title = "GTKX Storybook" }: StorybookViewProps
                         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 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>
     );
 };

package/src/types.ts

@@ -1,9 +1,11 @@
 import type * as Gtk from "@gtkx/gi/gtk";
 import type { ComponentType, ReactNode } from "react";
 import type {
+    ArgsFromMeta,
     ComponentAnnotations,
     GlobalTypes,
     Renderer,
+    StoryAnnotations as StorybookAnnotations,
     ArgTypes as StorybookArgTypes,
     StoryContext as StorybookContext,
 } from "storybook/internal/types";
@@ -69,51 +71,29 @@ 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] };
 
-/** 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 }
+type ArgsFrom<T> = T extends { component?: infer Component; render?: unknown; decorators?: unknown }
     ? 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;
+          (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>>;
@@ -130,14 +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>> & (Record<never, never> extends RequiredStoryArgs<T, ArgsFrom<T>>
-        ? { args?: RequiredStoryArgs<T, ArgsFrom<T>> }
-        : { args: RequiredStoryArgs<T, ArgsFrom<T>> })
+    ? 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. */
@@ -177,9 +159,10 @@ 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;
+          ? Key
+          : never;
+}[keyof TModule] &
+    string;
 
 /** Composed stories keyed by their original named exports. */
 type ComposedStories<TModule extends StoryModule> = Record<

package/src/upstream.ts

@@ -1,11 +1,5 @@
 import { composeStory } from "storybook/preview-api";
-import type {
-    ComponentMeta,
-    ComposedStory,
-    Preview,
-    StoryAnnotations,
-    StoryRender,
-} from "./types.js";
+import type { ComponentMeta, ComposedStory, Preview, StoryAnnotations, StoryRender } from "./types.js";
 
 type ComposeStory = <TArgs extends object>(
     ...annotations: [