@gtkx/storybook 0.0.1

package/dist/types.d.ts

@@ -0,0 +1,143 @@
+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, };
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

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

package/dist/upstream.d.ts

@@ -0,0 +1,14 @@
+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>;
+declare const composeStoryAnnotations: ComposeStory;
+export { composeStoryAnnotations };
+export { isExportStory, storyNameFromExport } from "storybook/internal/csf";
+//# sourceMappingURL=upstream.d.ts.map

package/dist/upstream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"upstream.d.ts","sourceRoot":"","sources":["../src/upstream.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACR,aAAa,EACb,aAAa,EACb,OAAO,EACP,gBAAgB,EAChB,WAAW,EACd,MAAM,YAAY,CAAC;AAEpB,KAAK,YAAY,GAAG,CAAC,KAAK,SAAS,MAAM,EACrC,GAAG,WAAW,EAAE;IACZ,KAAK,EAAE,gBAAgB,CAAC,KAAK,CAAC;IAC9B,IAAI,EAAE,aAAa,CAAC,KAAK,CAAC;IAC1B,OAAO,EAAE,OAAO;IAChB,QAAQ,EAAE;QAAE,MAAM,EAAE,WAAW,CAAC,KAAK,CAAC,CAAA;KAAE;IACxC,UAAU,CAAC,EAAE,MAAM;CACtB,KACA,aAAa,CAAC,KAAK,CAAC,CAAC;AAE1B,QAAA,MAAM,uBAAuB,EAAmB,YAAY,CAAC;AAE7D,OAAO,EAAE,uBAAuB,EAAE,CAAC;AAEnC,OAAO,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/upstream.js

@@ -0,0 +1,5 @@
+import { composeStory } from "storybook/preview-api";
+const composeStoryAnnotations = composeStory;
+export { composeStoryAnnotations };
+export { isExportStory, storyNameFromExport } from "storybook/internal/csf";
+//# sourceMappingURL=upstream.js.map

package/dist/upstream.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"upstream.js","sourceRoot":"","sources":["../src/upstream.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAmBrD,MAAM,uBAAuB,GAAG,YAA4B,CAAC;AAE7D,OAAO,EAAE,uBAAuB,EAAE,CAAC;AAEnC,OAAO,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC","sourcesContent":["import { composeStory } from \"storybook/preview-api\";\nimport type {\n    ComponentMeta,\n    ComposedStory,\n    Preview,\n    StoryAnnotations,\n    StoryRender,\n} from \"./types.js\";\n\ntype ComposeStory = <TArgs extends object>(\n    ...annotations: [\n        story: StoryAnnotations<TArgs>,\n        meta: ComponentMeta<TArgs>,\n        preview: Preview,\n        renderer: { render: StoryRender<TArgs> },\n        exportName?: string,\n    ]\n) => ComposedStory<TArgs>;\n\nconst composeStoryAnnotations = composeStory as ComposeStory;\n\nexport { composeStoryAnnotations };\n\nexport { isExportStory, storyNameFromExport } from \"storybook/internal/csf\";\n"]}

package/package.json

@@ -0,0 +1,86 @@
+{
+    "name": "@gtkx/storybook",
+    "version": "0.0.1",
+    "description": "Native story explorer and portable Component Story Format fixtures for GTKX applications.",
+    "keywords": [
+        "gtkx",
+        "gtk",
+        "gtk4",
+        "adwaita",
+        "react",
+        "storybook",
+        "csf",
+        "linux"
+    ],
+    "homepage": "https://gtkx.dev",
+    "bugs": {
+        "url": "https://github.com/gtkx-org/gtkx/issues"
+    },
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/gtkx-org/gtkx.git",
+        "directory": "packages/storybook"
+    },
+    "license": "MPL-2.0",
+    "author": "Eugenio Depalo <eugeniodepalo@gmail.com>",
+    "type": "module",
+    "exports": {
+        "./package.json": "./package.json",
+        ".": {
+            "source": "./src/index.ts",
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.js",
+            "require": null,
+            "default": "./dist/index.js"
+        },
+        "./config": {
+            "source": "./src/config.ts",
+            "types": "./dist/config.d.ts",
+            "import": "./dist/config.js",
+            "require": null,
+            "default": "./dist/config.js"
+        },
+        "./explorer": {
+            "source": "./src/explorer.ts",
+            "types": "./dist/explorer.d.ts",
+            "import": "./dist/explorer.js",
+            "require": null,
+            "default": "./dist/explorer.js"
+        }
+    },
+    "sideEffects": false,
+    "files": [
+        "dist",
+        "src"
+    ],
+    "scripts": {
+        "release": "tsx ../../scripts/release-package.ts"
+    },
+    "nx": {
+        "targets": {
+            "lint": {
+                "options": {
+                    "cwd": ".",
+                    "command": "eslint {projectRoot}"
+                }
+            }
+        }
+    },
+    "engines": {
+        "node": ">=26.7.0"
+    },
+    "dependencies": {
+        "@gtkx/components": "workspace:*",
+        "@gtkx/react": "workspace:*",
+        "storybook": "10.6.0"
+    },
+    "peerDependencies": {
+        "react": "^19.2"
+    },
+    "devDependencies": {
+        "@gtkx/config": "workspace:*",
+        "@gtkx/testing": "workspace:*",
+        "@gtkx/vitest": "workspace:*",
+        "vitest": "catalog:"
+    }
+}

package/src/actions-panel.tsx

@@ -0,0 +1,32 @@
+import type { ReactNode } from "react";
+import { markupEscapeText } from "@gtkx/gi/glib";
+import { AdwActionRow, AdwPreferencesGroup } from "@gtkx/jsx/adw";
+import { GtkButton } from "@gtkx/jsx/gtk";
+import { useSyncExternalStore } from "react";
+import type { ActionStore } from "./actions.js";
+
+const ActionsPanel = ({ store }: { store: ActionStore }): ReactNode => {
+    const entries = useSyncExternalStore(store.subscribe, store.getSnapshot);
+
+    return (
+        <AdwPreferencesGroup
+            title="Actions"
+            description={entries.length === 0 ? "Interact with the story to record events." : ""}
+            headerSuffix={<GtkButton label="Clear actions" sensitive={entries.length > 0} onClicked={store.clear} />}
+        >
+            {entries.toReversed().map((entry) => (
+                <AdwActionRow
+                    key={entry.id}
+                    name={`storybook-action-${String(entry.id)}`}
+                    title={markupEscapeText(entry.name, -1)}
+                    subtitle={markupEscapeText(entry.error ?? entry.args.join(", "), -1)}
+                    subtitleSelectable
+                    subtitleLines={3}
+                    cssClasses={entry.error === undefined ? [] : ["error"]}
+                />
+            ))}
+        </AdwPreferencesGroup>
+    );
+};
+
+export { ActionsPanel };

package/src/actions.ts

@@ -0,0 +1,234 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { inspect } from "node:util";
+import type { Args, ArgTypes } from "./types.js";
+
+type ActionEntry = {
+    id: number;
+    name: string;
+    args: string[];
+    timestamp: number;
+    error?: string;
+};
+
+/** A named story callback whose arguments can be recorded by the native explorer. */
+type ActionCallback = (...args: unknown[]) => void;
+type EventCallback = (...args: unknown[]) => unknown;
+
+const actionNames: WeakMap<object, string> = new WeakMap();
+const actionScope: AsyncLocalStorage<ActionStore> = new AsyncLocalStorage();
+const DEFAULT_HISTORY_LIMIT = 100;
+const MAX_ARGUMENT_LENGTH = 400;
+
+const objectLabel = (value: unknown): string | undefined => {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        return undefined;
+    }
+
+    const prototype: unknown = Object.getPrototypeOf(value);
+
+    if (prototype === null || typeof prototype !== "object" || prototype === Object.prototype) {
+        return undefined;
+    }
+
+    const constructor: unknown = Object.getOwnPropertyDescriptor(prototype, "constructor")?.value;
+
+    return typeof constructor === "function" ? `[${constructor.name}]` : "[Object]";
+};
+
+const formatArgument = (value: unknown): string => {
+    try {
+        const label = objectLabel(value);
+
+        if (label !== undefined) {
+            return label;
+        }
+
+        return inspect(value, {
+            depth: 1,
+            maxArrayLength: 5,
+            maxStringLength: 120,
+            customInspect: false,
+            getters: false,
+            breakLength: Infinity,
+        }).slice(0, MAX_ARGUMENT_LENGTH);
+    } catch {
+        return "[Unreadable value]";
+    }
+};
+
+/**
+ * Creates a named action for a story's callback arguments.
+ * The explorer records bounded argument summaries; calls outside its action scope have no effect.
+ *
+ * @param name Nonempty label displayed in the Actions panel.
+ * @returns A callback to supply in story args.
+ * @throws If the name is empty or contains only whitespace.
+ */
+const action = (name: string): ActionCallback => {
+    if (name.trim().length === 0) {
+        throw new TypeError("An action needs a name");
+    }
+
+    const callback: ActionCallback = (...args) => {
+        actionScope.getStore()?.record(name, args);
+    };
+    actionNames.set(callback, name);
+
+    return callback;
+};
+
+class ActionStore {
+    private entries: ActionEntry[] = [];
+    private readonly listeners: Set<() => void> = new Set();
+    private nextId = 0;
+    private readonly limit: number;
+
+    getSnapshot = (): ActionEntry[] => this.entries;
+
+    subscribe = (listener: () => void): (() => void) => {
+        this.listeners.add(listener);
+
+        return () => {
+            this.listeners.delete(listener);
+        };
+    };
+
+    clear = (): void => {
+        this.publish([]);
+    };
+
+    constructor(limit: number = DEFAULT_HISTORY_LIMIT) {
+        if (!Number.isSafeInteger(limit) || limit < 1) {
+            throw new RangeError("Action history needs a positive integer limit");
+        }
+
+        this.limit = limit;
+    }
+
+    private publish(entries: ActionEntry[]): void {
+        this.entries = entries;
+
+        for (const listener of this.listeners) {
+            listener();
+        }
+    }
+
+    record(name: string, args: unknown[], error?: Error): void {
+        const entry: ActionEntry = {
+            id: this.nextId++,
+            name,
+            args: args.slice(0, 8).map((value) => formatArgument(value)),
+            timestamp: Date.now(),
+            ...(error !== undefined && { error: error.message.slice(0, MAX_ARGUMENT_LENGTH) }),
+        };
+        this.publish([...this.entries, entry].slice(-this.limit));
+    }
+}
+
+type CallbackOptions = { callback?: EventCallback; name: string; onError?: (error: Error) => void };
+
+const settleCallback = async (
+    result: Promise<unknown>,
+    succeed: () => void,
+    fail: (cause: unknown) => void,
+): Promise<unknown> => {
+    try {
+        const value = await result;
+        succeed();
+
+        return value;
+    } catch (error) {
+        fail(error);
+
+        return undefined;
+    }
+};
+
+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);
+
+        if (options.onError === undefined) {
+            throw error;
+        }
+
+        options.onError(error);
+    };
+
+    try {
+        const result = actionScope.run(store, () => options.callback?.(...values));
+
+        if (result instanceof Promise) {
+            return settleCallback(result, succeed, fail);
+        }
+
+        succeed();
+
+        return result;
+    } catch (error) {
+        fail(error);
+
+        return;
+    }
+};
+
+const actionName = (value: unknown, configuredName: unknown): string | undefined => {
+    if (typeof configuredName === "string") {
+        return configuredName;
+    }
+
+    return typeof value === "function" ? actionNames.get(value) : undefined;
+};
+
+const isOriginalCallback = (value: unknown): value is EventCallback =>
+    typeof value === "function" && !actionNames.has(value);
+
+const callbackOptions = (
+    value: unknown,
+    name: string | undefined,
+    onError: ((error: Error) => void) | undefined,
+): CallbackOptions | undefined => {
+    if (name === undefined) {
+        return undefined;
+    }
+
+    return {
+        name,
+        ...(isOriginalCallback(value) && { callback: value }),
+        ...(onError !== undefined && { onError }),
+    };
+};
+
+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)]);
+
+    for (const argument of names) {
+        const value = args[argument];
+        const name = actionName(value, argTypes[argument]?.action);
+        const options = callbackOptions(value, name, onError);
+
+        if (options === undefined) {
+            continue;
+        }
+
+        bound[argument] = bindCallback(store, options);
+    }
+
+    return bound;
+};
+
+export { action, ActionStore, bindActions };
+export type { ActionCallback };