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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gtkx/storybook",
-  "version": "2.0.0-beta.11",
-  "description": "Explore GTKX components as native stories.",
+  "version": "2.0.0-beta.13",
+  "description": "Native component stories for GTKX.",
   "keywords": [
     "gtkx",
     "gtk",
@@ -10,7 +10,9 @@
     "react",
     "storybook",
     "csf",
-    "linux"
+    "linux",
+    "gnome",
+    "desktop"
   ],
   "homepage": "https://gtkx.dev",
   "bugs": {
@@ -50,36 +52,27 @@
     "dist",
     "src"
   ],
-  "nx": {
-    "targets": {
-      "lint": {
-        "options": {
-          "cwd": ".",
-          "command": "eslint {projectRoot}"
-        }
-      }
-    }
-  },
   "engines": {
     "node": ">=26.7.0"
   },
   "dependencies": {
-    "@gtkx/components": "2.0.0-beta.11",
-    "@gtkx/react": "2.0.0-beta.11",
-    "storybook": "10.6.0"
+    "@gtkx/components": "^2.0.0-beta.13",
+    "@gtkx/react": "^2.0.0-beta.13",
+    "@gtkx/utils": "^2.0.0-beta.13",
+    "storybook": "10.6.5"
   },
   "peerDependencies": {
     "@types/react": "^19.3",
     "react": "^19.3"
   },
   "devDependencies": {
-    "@gtkx/config": "2.0.0-beta.11",
-    "@gtkx/testing": "2.0.0-beta.11",
-    "@gtkx/vitest": "2.0.0-beta.11",
+    "@gtkx/config": "2.0.0-beta.13",
+    "@gtkx/testing": "2.0.0-beta.13",
+    "@gtkx/vitest": "2.0.0-beta.13",
     "@types/react": "^19.3.0",
-    "vitest": "^5.0.1"
+    "vitest": "5.1.0"
   },
   "scripts": {
-    "release": "tsx ../../scripts/release-package.ts"
+    "release": "node ../../scripts/release/publish-package.ts"
   }
 }

package/src/actions.ts

@@ -1,3 +1,4 @@
+import { normalizeError } from "@gtkx/utils";
 import { AsyncLocalStorage } from "node:async_hooks";
 import { inspect } from "node:util";
 import type { Args, ArgTypes } from "./types.js";
@@ -133,40 +134,39 @@ const settleCallback = async (
     }
 };
 
-const bindCallback = (
-    store: ActionStore,
-    options: CallbackOptions,
-): EventCallback => (...values) => {
-    const succeed = (): void => {
-        store.record(options.name, values);
-    };
-    const fail = (cause: unknown): void => {
-        const error = cause instanceof Error ? cause : new Error(String(cause));
-        store.record(options.name, values, error);
+const bindCallback =
+    (store: ActionStore, options: CallbackOptions): EventCallback =>
+    (...values) => {
+        const succeed = (): void => {
+            store.record(options.name, values);
+        };
+        const fail = (cause: unknown): void => {
+            const error = normalizeError(cause);
+            store.record(options.name, values, error);
 
-        if (options.onError === undefined) {
-            throw error;
-        }
+            if (options.onError === undefined) {
+                throw error;
+            }
 
-        options.onError(error);
-    };
+            options.onError(error);
+        };
 
-    try {
-        const result = actionScope.run(store, () => options.callback?.(...values));
+        try {
+            const result = actionScope.run(store, () => options.callback?.(...values));
 
-        if (result instanceof Promise) {
-            return settleCallback(result, succeed, fail);
-        }
+            if (result instanceof Promise) {
+                return settleCallback(result, succeed, fail);
+            }
 
-        succeed();
+            succeed();
 
-        return result;
-    } catch (error) {
-        fail(error);
+            return result;
+        } catch (error) {
+            fail(error);
 
-        return;
-    }
-};
+            return;
+        }
+    };
 
 const actionName = (value: unknown, configuredName: unknown): string | undefined => {
     if (typeof configuredName === "string") {
@@ -195,12 +195,7 @@ const callbackOptions = (
     };
 };
 
-const bindActions = (
-    args: Args,
-    argTypes: ArgTypes,
-    store: ActionStore,
-    onError?: (error: Error) => void,
-): Args => {
+const bindActions = (args: Args, argTypes: ArgTypes, store: ActionStore, onError?: (error: Error) => void): Args => {
     const bound = { ...args };
     const names = new Set([...Object.keys(args), ...Object.keys(argTypes)]);
 

package/src/catalog.ts

@@ -1,3 +1,4 @@
+import { normalizeError } from "@gtkx/utils";
 import type { Args, ArgTypes, ComponentMeta, ComposedStory, Preview, StoryAnnotations } from "./types.js";
 import { composeStories } from "./compose.js";
 import { storyNameFromExport } from "./upstream.js";
@@ -40,7 +41,7 @@ type StoryLoadError = {
 
 /** Current explorer contents and loading state exposed to subscribers. */
 type StoryCatalogSnapshot = {
-    /** Successfully composed stories with duplicate identifiers excluded. */
+    /** Successfully composed stories tagged `dev`, with duplicate identifiers excluded. */
     stories: StoryEntry[];
     /** Failures encountered during the latest load or reported by the session. */
     errors: StoryLoadError[];
@@ -58,8 +59,7 @@ type CachedStories = {
 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 DEVELOPMENT_TAG = "dev";
 
 const isObject = (value: unknown): value is Record<string, unknown> =>
     value !== null && typeof value === "object" && !Array.isArray(value);
@@ -73,8 +73,10 @@ const explicitControls = (
     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;
+        const control =
+            story?.argTypes?.[argument]?.control ??
+            meta.argTypes?.[argument]?.control ??
+            preview.argTypes?.[argument]?.control;
 
         if (control === undefined) {
             continue;
@@ -117,15 +119,17 @@ const composeSource = (source: StorySource, module: unknown, preview: Preview):
     } 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),
-    }));
+    return Object.entries(stories)
+        .filter(([, story]) => story.tags.includes(DEVELOPMENT_TAG))
+        .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[] => {
@@ -173,10 +177,13 @@ const loadSource = async (
     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) };
+        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) {
@@ -233,7 +240,10 @@ class StoryCatalog {
         this.publish({ stories, errors, isLoading: false });
 
         if (errors.length > 0) {
-            const failure = new AggregateError(errors.map(({ error }) => error), "Some stories could not be loaded");
+            const failure = new AggregateError(
+                errors.map(({ error }) => error),
+                "Some stories could not be loaded",
+            );
             this.loadFailures.add(failure);
             throw failure;
         }

package/src/compose.ts

@@ -38,15 +38,21 @@ const composeStory = <TArgs extends object>(
         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 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);
+                return createElement(meta.component, args);
+            },
         },
-    }, exportName);
+        exportName,
+    );
 };
 
 /**

package/src/config.ts

@@ -1,6 +1,9 @@
 /** Story discovery and preview configuration for the native explorer. */
 type StorybookConfig = {
-    /** Project-relative globs; defaults to CSF story files under src. */
+    /**
+     * Project-relative globs; defaults to CSF story files under src. A glob may reach a sibling workspace
+     * package through `..` segments when every file it matches lies inside the workspace root.
+     */
     stories?: string[];
     /** Additional project-relative globs excluded from discovery. */
     exclude?: string[];

package/src/controls.tsx

@@ -4,8 +4,9 @@ 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";
+import { isConditionalArgIncluded } from "./upstream.js";
 
-type ControlsProps = { argTypes: ArgTypes; args: Args; onChange: (update: Args) => void };
+type ControlsProps = { argTypes: ArgTypes; args: Args; globals: Args; onChange: (update: Args) => void };
 
 const NO_SELECTION_ID = "no-selection";
 const NO_SELECTION_LABEL = "Choose option...";
@@ -27,10 +28,10 @@ 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);
+const numberDigits = (value: number): number => {
+    const [coefficient = "", exponent = "0"] = String(value).split("e", 2);
     const fraction = coefficient.split(".", 2)[1]?.length ?? 0;
     const digits = Math.max(0, fraction - Number(exponent));
 
@@ -54,9 +55,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,10 +76,10 @@ const NumberControl = ({
             title={markupEscapeText(title, -1)}
             sensitive={!isDisabled}
             value={currentValue}
-            digits={numberDigits(step)}
+            digits={Math.max(numberDigits(step), numberDigits(currentValue))}
             numeric
             widthChars={8}
-            adjustment={(
+            adjustment={
                 <GtkAdjustment
                     lower={min}
                     upper={max}
@@ -80,7 +87,7 @@ const NumberControl = ({
                     pageIncrement={Math.min(Number.MAX_VALUE, step * 10)}
                     value={currentValue}
                 />
-            )}
+            }
             onNotifyValue={(next) => {
                 if (!Object.is(next, value)) {
                     onChange({ [argument]: next });
@@ -92,19 +99,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 = [{ id: NO_SELECTION_ID, value: NO_SELECTION_LABEL }, ...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
@@ -179,13 +198,18 @@ const Control = (props: ControlProps): ReactNode => {
     }
 };
 
-const Controls = ({ argTypes, args, onChange }: ControlsProps): ReactNode => (
+const Controls = ({ argTypes, args, globals, onChange }: ControlsProps): ReactNode => (
     <AdwPreferencesGroup title="Controls">
         {Object.entries(argTypes).map(([argument, annotation]) => {
             const control: unknown = annotation?.control;
             const table = isObject(annotation?.table) ? annotation.table : {};
 
-            if (control === undefined || control === false || table.disable === true) {
+            if (
+                control === undefined ||
+                control === false ||
+                table.disable === true ||
+                !isConditionalArgIncluded(annotation ?? {}, args, globals)
+            ) {
                 return null;
             }
 

package/src/explorer-navigator.tsx

@@ -18,16 +18,51 @@ type GroupProps = Pick<NavigatorProps, "selectedId" | "onSelect"> & {
     entries: StoryEntry[];
 };
 
+type Group = {
+    title: string;
+    entries: StoryEntry[];
+    path: number[];
+};
+
+const TITLE_SEPARATOR = "/";
+
+const titlePrefixes = (title: string): string[] =>
+    title.split(TITLE_SEPARATOR).map((_, index, segments) => segments.slice(0, index + 1).join(TITLE_SEPARATOR));
+
+const compareIndexPaths = (left: number[], right: number[]): number => {
+    for (const [index, value] of left.entries()) {
+        const other = right[index];
+
+        if (other === undefined) {
+            return 1;
+        }
+
+        if (value !== other) {
+            return value - other;
+        }
+    }
+
+    return left.length - right.length;
+};
+
+/**
+ * Groups stories by title, keeping titles that share a path prefix together as Storybook's sidebar nests
+ * them: the first title under each prefix decides where the prefix appears.
+ */
+const groupStoriesByTitle = (stories: StoryEntry[]): Group[] => {
+    const firstOccurrence: Map<string, number> = new Map();
+    const groups = [...Map.groupBy(stories, (entry) => entry.title)].map(([title, entries], order) => ({
+        title,
+        entries,
+        path: titlePrefixes(title).map((prefix) => firstOccurrence.getOrInsert(prefix, order)),
+    }));
+
+    return groups.toSorted((left, right) => compareIndexPaths(left.path, right.path));
+};
+
 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,29 +89,29 @@ 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("");
     const query = search.trim().toLocaleLowerCase();
-    const groups = Map.groupBy(
+    const groups = groupStoriesByTitle(
         stories.filter((entry) => `${entry.title} ${entry.name}`.toLocaleLowerCase().includes(query)),
-        (entry) => entry.title,
     );
 
     return (
@@ -93,7 +128,7 @@ const StoryNavigator = ({ stories, errors, selectedId, onSelect }: NavigatorProp
             />
             <GtkScrolledWindow hscrollbarPolicy={Gtk.PolicyType.NEVER} vexpand>
                 <GtkBox orientation={Gtk.Orientation.VERTICAL} spacing={18} marginBottom={18}>
-                    {[...groups].map(([title, entries]) => (
+                    {groups.map(({ title, entries }) => (
                         <StoryGroup
                             key={title}
                             title={title}
@@ -102,7 +137,7 @@ const StoryNavigator = ({ stories, errors, selectedId, onSelect }: NavigatorProp
                             onSelect={onSelect}
                         />
                     ))}
-                    {groups.size === 0 && (
+                    {groups.length === 0 && (
                         <AdwStatusPage
                             name="storybook-no-matches"
                             title={query ? "No matching stories" : "No stories"}