@gjsify/storybook 0.7.5

package/README.md

@@ -0,0 +1,100 @@
+# @gjsify/storybook
+
+A reusable **GTK/Adwaita storybook** for GJS. Author component previews as `*.story.ts` files anywhere in your project, then browse them in a generic Adwaita component explorer — a sidebar grouped by category, a live preview pane, and an auto-generated controls panel with two-way binding. No per-project storybook *application* to maintain.
+
+It is the GTK renderer for the runtime-agnostic [`@gjsify/stories`](../stories) contract (re-exported here, so a story needs only one import).
+
+## Author a story
+
+```ts
+import GObject from '@girs/gobject-2.0';
+import { ControlType, StoryWidget, type StoryArgs, type StoryMeta, type StoryModule } from '@gjsify/storybook';
+import { MyButton } from './my-button.js';
+
+export class MyButtonStory extends StoryWidget {
+    private _button: MyButton | null = null;
+    static {
+        GObject.registerClass({ GTypeName: 'MyButtonStory' }, MyButtonStory);
+    }
+
+    constructor() {
+        super(StoryWidget.fromMeta(MyButtonStory.getMetadata(), 'Default')); // defaults derived from controls
+    }
+
+    static getMetadata(): StoryMeta {
+        return {
+            title: 'UI/My Button', // "UI" groups the sidebar
+            component: MyButton.$gtype,
+            controls: [
+                { name: 'label', label: 'Label', type: ControlType.TEXT, defaultValue: 'Click me' },
+                { name: 'size', label: 'Size', type: ControlType.RANGE, min: 16, max: 96, step: 2, defaultValue: 42 },
+            ],
+        };
+    }
+
+    initialize(): void {
+        this._button = new MyButton({ label: this.args.label as string });
+        this.addContent(this._button);
+    }
+
+    updateArgs(_args: StoryArgs): void {
+        if (this._button && typeof this.args.label === 'string') this._button.label = this.args.label;
+    }
+}
+
+GObject.type_ensure(MyButtonStory.$gtype);
+
+export const MyButtonStories: StoryModule = { stories: [MyButtonStory] };
+```
+
+Subclasses that supply their own composite `.blp` template have full layout control; otherwise `addContent()` drops the preview into default chrome. The optional `withActionGroup(prefix, actions)` decorator (`StoryModule.decorators`) installs a stubbed `Gio.SimpleActionGroup` so a previewed widget's buttons resolve in the sandbox.
+
+## Run it
+
+The easy way — let the CLI discover and launch every `*.story.ts`:
+
+```bash
+gjsify storybook
+```
+
+Configure it in `package.json`:
+
+```jsonc
+"gjsify": {
+  "storybook": {
+    "applicationId": "org.example.Storybook",
+    "title": "Example Storybook",
+    "stories": "src/**/*.story.ts",
+    "globals": "auto,dom"   // add ,dom when stories use canvas/DOM widgets
+  }
+}
+```
+
+Or wire a launcher yourself with `runStorybook` + `collectStoryModules`:
+
+```ts
+import { collectStoryModules, runStorybook } from '@gjsify/storybook';
+import * as button from './widgets/my-button.story.js';
+
+await runStorybook({
+    applicationId: 'org.example.Storybook',
+    stories: collectStoryModules([button]),
+});
+```
+
+## Exports
+
+- `StoryWidget` — Adw.Bin base class; `fromMeta()`, `addContent()`, `initialize()`/`updateArgs()`/`teardown()` hooks
+- `StoryModule` / `StoryWidgetConstructor` — registration shape (with optional module `decorators`)
+- `StoryRegistryService` — collects modules and instantiates their widgets
+- `StorybookApplication` / `StorybookWindow` — the Adwaita host + component browser
+- `runStorybook(options)` / `collectStoryModules(namespaces)` — launcher + discovery
+- `withActionGroup` / `installActionGroup` / `StoryAction` — action-group decorator helpers
+- re-exported contract: `ControlType`, `StoryControl` (+ per-kind types), `StoryMeta`, `StoryArgs`, `argsFromControls`
+
+## Build / test
+
+```bash
+gjsify workspace @gjsify/storybook build
+gjsify workspace @gjsify/storybook test
+```

package/lib/esm/_virtual/_rolldown/runtime.js

@@ -0,0 +1 @@
+var e=Object.defineProperty,__name=(t,n)=>e(t,`name`,{value:n,configurable:!0});export{__name};

package/lib/esm/application.js

@@ -0,0 +1 @@
+import"./_virtual/_rolldown/runtime.js";import{StoryRegistryService as e}from"./registry.js";import{STORYBOOK_CSS as t}from"./styles.js";import{StorybookWindow as n}from"./window.js";import r from"@girs/adw-1";import i from"@girs/gdk-4.0";import a from"@girs/gio-2.0";import o from"@girs/gobject-2.0";import s from"@girs/gtk-4.0";var c=class StorybookApplication extends r.Application{static{o.registerClass({GTypeName:`StorybookApplication`},StorybookApplication)}constructor(t){super({application_id:t.applicationId,flags:a.ApplicationFlags.DEFAULT_FLAGS}),this._window=null,this._registry=new e,this._options=t,this.connect(`startup`,()=>this._initStyles()),this.connect(`activate`,()=>this._onActivate())}_initStyles(){let e=new s.CssProvider;e.load_from_string(`${t}\n${this._options.css??``}`);let n=i.Display.get_default();if(!n){console.error(`No display found`);return}s.StyleContext.add_provider_for_display(n,e,s.STYLE_PROVIDER_PRIORITY_APPLICATION)}_onActivate(){if(!this._window){this._window=new n({application:this}),this._options.title&&this._window.set_title(this._options.title),this._registry.registerStories(this._options.stories);try{let e=this._registry.createStoryInstances();this._window.populateSidebar(e)}catch(e){console.error(`Failed to create story instances:`,e)}}this._window.present()}};o.type_ensure(c.$gtype);export{c as StorybookApplication};

package/lib/esm/decorators.js

@@ -0,0 +1 @@
+import"./_virtual/_rolldown/runtime.js";import e from"@girs/gio-2.0";import t from"@girs/glib-2.0";function installActionGroup(n,r,i){let a=new e.SimpleActionGroup;for(let n of i)if(typeof n.state==`boolean`){let r=e.SimpleAction.new_stateful(n.name,null,t.Variant.new_boolean(n.state));r.connect(`change-state`,(e,t)=>{e.set_state(t),n.onChange?.(t)}),a.add_action(r)}else if(typeof n.state==`string`){let r=e.SimpleAction.new_stateful(n.name,t.VariantType.new(`s`),t.Variant.new_string(n.state));r.connect(`change-state`,(e,t)=>{e.set_state(t),n.onChange?.(t)}),a.add_action(r)}else{let t=new e.SimpleAction({name:n.name});t.connect(`activate`,(e,t)=>n.onChange?.(t??null)),a.add_action(t)}return n.insert_action_group(r,a),a}function withActionGroup(e,t){return(n,r)=>{installActionGroup(r,e,t),n()}}export{installActionGroup,withActionGroup};

package/lib/esm/discover.js

@@ -0,0 +1 @@
+import"./_virtual/_rolldown/runtime.js";import{isStoryModule as e}from"@gjsify/stories";function collectStoryModules(t){let n=[];for(let r of t)if(!(!r||typeof r!=`object`))for(let t of Object.values(r))e(t)&&n.push(t);return n}export{collectStoryModules};

package/lib/esm/index.js

@@ -0,0 +1 @@
+import{StoryRegistryService as e}from"./registry.js";import{StorybookWindow as t}from"./window.js";import{StorybookApplication as n}from"./application.js";import{installActionGroup as r,withActionGroup as i}from"./decorators.js";import{collectStoryModules as a}from"./discover.js";import{StoryWidget as o}from"./story-widget.js";import{runStorybook as s}from"./run.js";import{ControlType as c,argsFromControls as l,isStoryModule as u}from"@gjsify/stories";export{c as ControlType,e as StoryRegistryService,o as StoryWidget,n as StorybookApplication,t as StorybookWindow,l as argsFromControls,a as collectStoryModules,r as installActionGroup,u as isStoryModule,s as runStorybook,i as withActionGroup};

package/lib/esm/registry.js

@@ -0,0 +1 @@
+import"./_virtual/_rolldown/runtime.js";var StoryRegistryService=class{constructor(){this.modules=[]}registerStory(e){if(!e||!Array.isArray(e.stories)){console.warn(`Invalid story module provided to registerStory`);return}this.modules.push(e)}registerStories(e){if(!Array.isArray(e)){console.warn(`Invalid story modules array provided to registerStories`);return}let t=e.filter(e=>e&&Array.isArray(e.stories));this.modules.push(...t)}getStories(){return[...this.modules]}createStoryInstances(){for(let e of this.modules)this.instantiateStoriesForModule(e);return[...this.modules]}instantiateStoriesForModule(e){e.instances||=[];let t=e.decorators??[];for(let n of e.stories)try{let r=new n,build=()=>{typeof r.initialize==`function`&&r.initialize()};t.reduceRight((e,t)=>()=>t(e,r),build)(),e.instances.push(r)}catch(e){console.error(`Failed to instantiate story widget: ${n.name||`Unknown`}`,e)}}};export{StoryRegistryService};

package/lib/esm/run.js

@@ -0,0 +1 @@
+import"./_virtual/_rolldown/runtime.js";import{StorybookApplication as e}from"./application.js";async function runStorybook(t){return new e(t).runAsync([imports.system.programInvocationName,...ARGV])}export{runStorybook};

package/lib/esm/story-widget.js

@@ -0,0 +1 @@
+import"./_virtual/_rolldown/runtime.js";import e from"@girs/adw-1";import t from"@girs/gobject-2.0";import n from"@girs/gtk-4.0";import{argsFromControls as r}from"@gjsify/stories";var i=class StoryWidget extends e.Bin{static{t.registerClass({GTypeName:`StoryWidget`,Properties:{meta:t.ParamSpec.object(`meta`,`Meta`,`Story metadata`,t.ParamFlags.READWRITE,t.Object),story:t.ParamSpec.string(`story`,`Story Name`,`Story name`,t.ParamFlags.READWRITE,``),args:t.ParamSpec.object(`args`,`Args`,`Story arguments`,t.ParamFlags.READWRITE,t.Object)}},StoryWidget)}constructor(e,t={}){super(t),this._story=``,this._storyContent=null,this._group=null,this._meta=e.meta,this._story=e.story,this._args=e.args,this.get_child()??this._installDefaultChrome()}static fromMeta(e,t){return{meta:e,story:t,args:r(e.controls)}}get meta(){return this._meta}set meta(e){this._meta!==e&&(this._meta=e,this.notify(`meta`),this._refreshChromeText())}get story(){return this._story}set story(e){this._story!==e&&(this._story=e,this.notify(`story`),this._refreshChromeText())}get args(){return this._args}set args(e){this._args!==e&&(this._args=e,this.notify(`args`),this.updateArgs(e))}initialize(){}updateArgs(e){}teardown(){}addContent(e){if(!this._storyContent)return;let t=this._storyContent.get_first_child();for(;t;)t.unparent(),t=this._storyContent.get_first_child();this._storyContent.append(e)}_installDefaultChrome(){let t=new e.PreferencesPage,r=new e.PreferencesGroup,i=new n.Box({orientation:n.Orientation.VERTICAL,halign:n.Align.CENTER,valign:n.Align.CENTER,margin_top:12,margin_bottom:12,spacing:12,hexpand:!0});r.add(i),t.add(r),this.set_child(t),this._group=r,this._storyContent=i,this._refreshChromeText()}_refreshChromeText(){if(!this._group)return;let e=this._meta?this._story?`${this._meta.title} — ${this._story}`:this._meta.title:this._story,t=this._meta?.description??``;this._group.set_title(e),this._group.set_description(t)}};t.type_ensure(i.$gtype);export{i as StoryWidget};

package/lib/esm/styles.js

@@ -0,0 +1,10 @@
+const e=`
+/* Range-control card in the controls sidebar — keeps the label + description
+   from being squashed into a single column when the sidebar is narrow. */
+.story-range-row {
+    padding: 0;
+}
+.story-range-row > box {
+    border-radius: 12px;
+}
+`;export{e as STORYBOOK_CSS};

package/lib/esm/window.js

@@ -0,0 +1 @@
+import"./_virtual/_rolldown/runtime.js";import e from"@girs/adw-1";import t from"@girs/gdk-4.0";import n from"@girs/gobject-2.0";import r from"@girs/gtk-4.0";import{ControlType as i}from"@gjsify/stories";var a=class StorybookWindow extends e.ApplicationWindow{static{n.registerClass({GTypeName:`StorybookWindow`},StorybookWindow)}constructor(e){super(e),this._controlRows=[],this._controlRefreshers=[],this._activeStoryHandlerId=0,this._activeStory=null,this.set_default_size(1200,800),this.set_size_request(360,320),this.set_title(`Storybook`),this._buildUI(),this._sidebar_list.connect(`row-selected`,this._onStorySelected.bind(this)),this._show_controls_button.connect(`toggled`,this._onToggleControls.bind(this)),this._controls_split_view.set_show_sidebar(!0)}_buildUI(){this._sidebar_list=new r.ListBox({selection_mode:r.SelectionMode.SINGLE}),this._sidebar_list.add_css_class(`navigation-sidebar`);let t=new r.ScrolledWindow({hexpand:!0,vexpand:!0,child:this._sidebar_list}),n=new e.HeaderBar({title_widget:new e.WindowTitle({title:`Stories`}),show_end_title_buttons:!1}),i=new e.ToolbarView({content:t});i.add_top_bar(n);let a=new e.NavigationPage({title:`Stories`,tag:`stories`,child:i});this._content_area=new e.Bin({hexpand:!0,vexpand:!0});let o=new r.ScrolledWindow({hexpand:!0,vexpand:!0,child:this._content_area});this._control_panel=new e.PreferencesGroup({title:`Controls`});let s=new e.PreferencesPage;s.add(this._control_panel);let c=new r.ScrolledWindow({vexpand:!0,child:s});this._controls_split_view=new e.OverlaySplitView({show_sidebar:!0,sidebar_position:r.PackType.END,min_sidebar_width:280,max_sidebar_width:360,content:o,sidebar:c}),this._preview_title=new e.WindowTitle({title:`Preview`}),this._show_controls_button=new r.ToggleButton({icon_name:`sidebar-show-right-symbolic`,tooltip_text:`Toggle Controls`,active:!0});let l=new e.HeaderBar({title_widget:this._preview_title});l.pack_end(this._show_controls_button);let u=new e.ToolbarView({content:this._controls_split_view});u.add_top_bar(l);let d=new e.NavigationPage({title:`Preview`,tag:`preview`,child:u});this._main_split_view=new e.NavigationSplitView({min_sidebar_width:220,max_sidebar_width:320,sidebar:a,content:d}),this.set_content(this._main_split_view);let f=e.BreakpointCondition.parse(`max-width: 720sp`);if(f){let t=new e.Breakpoint({condition:f});t.connect(`apply`,()=>{this._main_split_view.collapsed=!0,this._controls_split_view.collapsed=!0}),t.connect(`unapply`,()=>{this._main_split_view.collapsed=!1,this._controls_split_view.collapsed=!1}),this.add_breakpoint(t)}}_onToggleControls(e){this._controls_split_view.set_show_sidebar(e.get_active())}populateSidebar(e){if(this._clearSidebar(),!e.some(e=>e.instances?.length)){console.error(`Story modules do not have instances. Call createStoryInstances first.`);return}this._groupStoriesByCategory(e).forEach((e,t)=>{this._addCategoryToSidebar(t),e.forEach(e=>{this._addStoryToSidebar(e)})})}_clearSidebar(){let e=this._sidebar_list.get_first_child();for(;e;){let t=e.get_next_sibling();e.unparent(),e=t}}_groupStoriesByCategory(e){let t=new Map;return e.forEach(e=>{e.instances?.length&&e.instances.forEach(e=>{let[n]=e.meta.title.split(`/`);t.has(n)||t.set(n,[]),t.get(n).push(e)})}),t}_addCategoryToSidebar(e){let t=new r.ListBoxRow({selectable:!1}),n=new r.Label({label:e,halign:r.Align.START,margin_top:10,margin_bottom:4,margin_start:12,margin_end:12});n.add_css_class(`heading`),n.add_css_class(`dim-label`),t.set_child(n),this._sidebar_list.append(t)}_addStoryToSidebar(e){let t=e.meta.title.split(`/`),n=t.length>1?t[1]:e.meta.title,i=new r.ListBoxRow,a=new r.Label({label:n||`Unnamed Story`,halign:r.Align.START,margin_start:20,margin_top:6,margin_bottom:6});i.set_child(a),this._sidebar_list.append(i),i.storyWidget=e}_onStorySelected(e,t){if(!t)return;let n=t;n.storyWidget&&(this._showStory(n.storyWidget),this._main_split_view.get_collapsed()&&this._main_split_view.set_show_content(!0))}_showStory(e){this._preview_title.set_title(`${e.meta.title} - ${e.story}`),this._content_area.set_child(e),this._updateControlPanel(e)}_updateControlPanel(e){this._clearControlPanel();let t=e.meta.controls;Array.isArray(t)&&(t.forEach(t=>{if(!t?.name||!t?.type){console.warn(`Invalid control configuration:`,t);return}let n=this._createControlRow(e,t);n&&(this._control_panel.add(n),this._controlRows.push(n))}),this._activeStory&&this._activeStoryHandlerId&&this._activeStory.disconnect(this._activeStoryHandlerId),this._activeStory=e,this._activeStoryHandlerId=e.connect(`notify::args`,()=>{for(let t of this._controlRefreshers)t(e.args)}),this._show_controls_button.set_active(!0))}_clearControlPanel(){for(let e of this._controlRows)this._control_panel.remove(e);this._controlRows=[],this._controlRefreshers=[]}_createControlRow(e,t){let n=e.args[t.name];switch(t.type){case i.TEXT:return this._createTextRow(e,t,typeof n==`string`?n:``);case i.NUMBER:return this._createNumberRow(e,t,typeof n==`number`?n:t.min??0);case i.BOOLEAN:return this._createBooleanRow(e,t,typeof n==`boolean`?n:!1);case i.RANGE:return this._createRangeRow(e,t,typeof n==`number`?n:t.min??0);case i.SELECT:return this._createSelectRow(e,t,n??null);case i.COLOR:return this._createColorRow(e,t,typeof n==`string`?n:`#000000`);default:return console.warn(`Unsupported control type: ${t.type}`),null}}_writeArg(e,t,n){e.args={...e.args,[t]:n}}_createTextRow(t,n,r){let i=new e.EntryRow({title:n.label||n.name});return i.set_text(r),n.description&&i.set_tooltip_text(n.description),i.connect(`changed`,()=>this._writeArg(t,n.name,i.get_text())),this._controlRefreshers.push(e=>{let t=typeof e[n.name]==`string`?e[n.name]:``;i.get_text()!==t&&i.set_text(t)}),i}_createNumberRow(t,n,r){let i=e.SpinRow.new_with_range(n.min??0,n.max??100,n.step??1);return i.set_title(n.label||n.name),n.description&&i.set_subtitle(n.description),i.set_value(r),i.connect(`changed`,()=>this._writeArg(t,n.name,i.get_value())),this._controlRefreshers.push(e=>{let t=typeof e[n.name]==`number`?e[n.name]:0;i.get_value()!==t&&i.set_value(t)}),i}_createBooleanRow(t,n,r){let i=new e.SwitchRow({title:n.label||n.name,subtitle:n.description??``,active:r});return i.connect(`notify::active`,()=>this._writeArg(t,n.name,i.get_active())),this._controlRefreshers.push(e=>{let t=!!e[n.name];i.get_active()!==t&&i.set_active(t)}),i}_createRangeRow(e,t,n){let i=t.min??0,a=t.max??100,o=t.step??1,s=Number.isInteger(o)&&Number.isInteger(n),c=new r.Adjustment({lower:i,upper:a,step_increment:o,value:n});c.step_increment=o;let l=new r.ListBoxRow({selectable:!1,activatable:!1});l.add_css_class(`story-range-row`);let u=new r.Box({orientation:r.Orientation.VERTICAL,spacing:6,margin_top:12,margin_bottom:12,margin_start:12,margin_end:12}),d=new r.Box({orientation:r.Orientation.HORIZONTAL,spacing:12}),f=new r.Label({label:t.label||t.name,halign:r.Align.START,hexpand:!0,ellipsize:3});f.add_css_class(`heading`);let p=new r.Label({label:this._formatRangeValue(n,s),halign:r.Align.END});if(p.add_css_class(`numeric`),p.add_css_class(`dim-label`),d.append(f),d.append(p),u.append(d),t.description){let e=new r.Label({label:t.description,halign:r.Align.START,xalign:0,wrap:!0,max_width_chars:32});e.add_css_class(`caption`),e.add_css_class(`dim-label`),u.append(e)}let m=new r.Scale({orientation:r.Orientation.HORIZONTAL,adjustment:c,draw_value:!1,hexpand:!0});return m.connect(`value-changed`,()=>{let n=m.get_value();if(s){let e=Math.round(n);if(e!==n){m.set_value(e);return}n=e}p.set_label(this._formatRangeValue(n,s)),this._writeArg(e,t.name,n)}),u.append(m),l.set_child(u),this._controlRefreshers.push(e=>{let r=typeof e[t.name]==`number`?e[t.name]:n;m.get_value()!==r&&(m.set_value(r),p.set_label(this._formatRangeValue(r,s)))}),l}_formatRangeValue(e,t){return t?String(Math.round(e)):e.toFixed(2)}_createSelectRow(t,n,i){let a=n.options;if(!a?.length)return console.warn(`SELECT control "${n.name}" has no options`),null;let o=r.StringList.new(a.map(e=>e.label)),s=new e.ComboRow({title:n.label||n.name,subtitle:n.description??``,model:o}),c=a.findIndex(e=>e.value===i);return c>=0&&s.set_selected(c),s.connect(`notify::selected`,()=>{let e=s.get_selected();e>=0&&e<a.length&&this._writeArg(t,n.name,a[e].value)}),this._controlRefreshers.push(e=>{let t=e[n.name],r=a.findIndex(e=>e.value===t);r>=0&&s.get_selected()!==r&&s.set_selected(r)}),s}_createColorRow(n,i,a){let o=new e.ActionRow({title:i.label||i.name,subtitle:i.description??``}),s=new r.ColorDialogButton({dialog:new r.ColorDialog({title:i.label||i.name}),valign:r.Align.CENTER}),c=new t.RGBA;return c.parse(a)&&s.set_rgba(c),s.connect(`notify::rgba`,()=>{this._writeArg(n,i.name,this._rgbaToHex(s.get_rgba()))}),o.add_suffix(s),o.set_activatable_widget(s),o}_rgbaToHex(e){let channel=e=>Math.round(Math.max(0,Math.min(1,e))*255).toString(16).padStart(2,`0`);return`#${channel(e.red)}${channel(e.green)}${channel(e.blue)}`}};n.type_ensure(a.$gtype);export{a as StorybookWindow};

package/lib/types/application.d.ts

@@ -0,0 +1,26 @@
+import Adw from '@girs/adw-1';
+import type { StoryModule } from './story-widget.js';
+/** Options that adapt the generic storybook to a host project. */
+export interface StorybookOptions {
+    /** GApplication id, e.g. `org.example.Storybook`. */
+    applicationId: string;
+    /** Window title (defaults to the `.blp` template's "Storybook"). */
+    title?: string;
+    /** Story modules to display. */
+    stories: StoryModule[];
+    /** Consumer's own widget stylesheet, layered on top of the built-in chrome CSS. */
+    css?: string;
+}
+/**
+ * Hosts the storybook: loads styles on startup, builds the window and populates
+ * it from a fresh {@link StoryRegistryService} on activate. One registry per
+ * application instance (no shared singleton).
+ */
+export declare class StorybookApplication extends Adw.Application {
+    private _window;
+    private _registry;
+    private _options;
+    constructor(options: StorybookOptions);
+    private _initStyles;
+    private _onActivate;
+}

package/lib/types/decorators.d.ts

@@ -0,0 +1,28 @@
+import Gio from '@girs/gio-2.0';
+import GLib from '@girs/glib-2.0';
+import type Gtk from '@girs/gtk-4.0';
+import type { StoryDecorator } from './story-widget.js';
+/** Declarative description of one action to install in a story sandbox. */
+export interface StoryAction {
+    /** Action name (without the group prefix). */
+    name: string;
+    /**
+     * Initial state for a stateful action. `boolean` → a toggle, `string` → a
+     * radio/enum action. Omit for a plain (parameterless, stateless) action.
+     */
+    state?: boolean | string;
+    /** Called when the action activates (plain) or changes state (stateful). */
+    onChange?: (value: GLib.Variant | null) => void;
+}
+/**
+ * Install a `Gio.SimpleActionGroup` on a widget so a story's buttons reach
+ * stubbed actions in the sandbox — replaces the hand-rolled
+ * `Gio.SimpleAction.new_stateful(...)` boilerplate that every interactive
+ * story used to repeat.
+ */
+export declare function installActionGroup(widget: Gtk.Widget, prefix: string, actions: StoryAction[]): Gio.SimpleActionGroup;
+/**
+ * Decorator that installs an action group before the story builds — so the
+ * actions exist by the time the previewed widget wires its buttons.
+ */
+export declare function withActionGroup(prefix: string, actions: StoryAction[]): StoryDecorator;

package/lib/types/discover.d.ts

@@ -0,0 +1,8 @@
+import type { StoryModule as GtkStoryModule } from './story-widget.js';
+/**
+ * Flatten a list of module namespaces (the `import * as m from './x.story.js'`
+ * objects the `gjsify storybook` command generates) into the story modules
+ * they export — regardless of the export name. Any exported value shaped like a
+ * {@link StoryModule} (an object with a `stories` array) is collected.
+ */
+export declare function collectStoryModules(namespaces: Array<Record<string, unknown>>): GtkStoryModule[];

package/lib/types/discover.spec.d.ts

@@ -0,0 +1,2 @@
+declare const _default: () => Promise<void>;
+export default _default;

package/lib/types/index.d.ts

@@ -0,0 +1,10 @@
+export { ControlType, argsFromControls, isStoryModule, type StoryArgs, type StoryArgValue, type StoryBooleanControl, type StoryColorControl, type StoryControl, type StoryMeta, type StoryNumberControl, type StorySelectControl, type StorySelectOption, type StoryTextControl, } from '@gjsify/stories';
+export { StoryWidget } from './story-widget.js';
+export type { StoryDecorator, StoryModule, StoryWidgetConstructor } from './story-widget.js';
+export { StoryRegistryService } from './registry.js';
+export { installActionGroup, withActionGroup, type StoryAction } from './decorators.js';
+export { StorybookWindow } from './window.js';
+export { StorybookApplication, type StorybookOptions } from './application.js';
+export { runStorybook } from './run.js';
+export { collectStoryModules } from './discover.js';
+export type { StoryRow } from './types.js';

package/lib/types/registry.d.ts

@@ -0,0 +1,22 @@
+import type { StoryModule } from './story-widget.js';
+/**
+ * Manages story-module registration and instantiation. Unlike the original
+ * PixelRPG implementation there is no exported singleton — each
+ * {@link runStorybook} run owns exactly one registry, which removes the
+ * double-registration footgun.
+ */
+export declare class StoryRegistryService {
+    private modules;
+    /** Register a single story module. */
+    registerStory(storyModule: StoryModule): void;
+    /** Register multiple story modules (invalid ones are filtered out). */
+    registerStories(storyModules: StoryModule[]): void;
+    /** All registered story modules (a shallow copy). */
+    getStories(): StoryModule[];
+    /**
+     * Instantiate every registered story widget and prepare it for display.
+     * Call once GTK is ready.
+     */
+    createStoryInstances(): StoryModule[];
+    private instantiateStoriesForModule;
+}

package/lib/types/registry.spec.d.ts

@@ -0,0 +1,2 @@
+declare const _default: () => Promise<void>;
+export default _default;

package/lib/types/run.d.ts

@@ -0,0 +1,12 @@
+import { type StorybookOptions } from './application.js';
+/**
+ * Construct and run a storybook application, resolving with its exit code when
+ * the window closes. The whole per-project launcher collapses to:
+ *
+ * ```ts
+ * import { runStorybook, collectStoryModules } from '@gjsify/storybook';
+ * import * as bar from './widgets/bar.story.js';
+ * await runStorybook({ applicationId: 'org.example.Storybook', stories: collectStoryModules([bar]) });
+ * ```
+ */
+export declare function runStorybook(options: StorybookOptions): Promise<number>;

package/lib/types/story-widget.d.ts

@@ -0,0 +1,68 @@
+import Adw from '@girs/adw-1';
+import GObject from '@girs/gobject-2.0';
+import Gtk from '@girs/gtk-4.0';
+import { type StoryArgs, type StoryMeta } from '@gjsify/stories';
+export declare namespace StoryWidget {
+    interface ConstructorProps {
+        meta: StoryMeta;
+        story: string;
+        args: StoryArgs;
+    }
+}
+/**
+ * Base class for GJS story widgets.
+ *
+ * Provides default chrome — a centered `Adw.PreferencesPage` /
+ * `Adw.PreferencesGroup` with title + description above a content slot — built
+ * programmatically (no `Template`). Simple stories compose their preview by
+ * calling {@link addContent}; elaborate subclasses can override the layout by
+ * providing their own composite template (then {@link addContent} is a no-op).
+ */
+export declare class StoryWidget extends Adw.Bin {
+    private _meta;
+    private _story;
+    private _args;
+    private _storyContent;
+    private _group;
+    constructor(params: StoryWidget.ConstructorProps, adwParams?: Partial<Adw.Bin.ConstructorProps>);
+    /**
+     * Build the constructor params from a story's metadata, deriving the initial
+     * args from the controls' default values (so defaults are spelled once).
+     */
+    static fromMeta(meta: StoryMeta, story: string): StoryWidget.ConstructorProps;
+    get meta(): StoryMeta;
+    set meta(value: StoryMeta);
+    get story(): string;
+    set story(value: string);
+    get args(): StoryArgs;
+    set args(value: StoryArgs);
+    /** Override in subclasses — build the preview. Runs in the registry init path. */
+    initialize(): void;
+    /** Override in subclasses — react to a control change. */
+    updateArgs(_args: StoryArgs): void;
+    /** Override in subclasses to release resources / disconnect signals on deselect. */
+    teardown(): void;
+    /**
+     * Add a widget to the default story preview slot. No-op if the subclass
+     * installed its own composite template.
+     */
+    addContent(widget: Gtk.Widget): void;
+    private _installDefaultChrome;
+    private _refreshChromeText;
+}
+/** Wraps a story's content-build step (e.g. to install a shared action group). */
+export type StoryDecorator = (build: () => void, widget: StoryWidget) => void;
+/** Constructor contract for a story class: zero-arg `new`, static metadata. */
+export interface StoryWidgetConstructor {
+    new (): StoryWidget;
+    $gtype: GObject.GType;
+    getMetadata(): StoryMeta;
+}
+/** A group of related stories, optionally wrapped by module-level decorators. */
+export interface StoryModule {
+    stories: StoryWidgetConstructor[];
+    /** Populated by {@link StoryRegistryService.createStoryInstances}. */
+    instances?: StoryWidget[];
+    /** Decorators applied around every story's `initialize()` in this module. */
+    decorators?: StoryDecorator[];
+}

package/lib/types/styles.d.ts

@@ -0,0 +1 @@
+export declare const STORYBOOK_CSS = "\n/* Range-control card in the controls sidebar \u2014 keeps the label + description\n   from being squashed into a single column when the sidebar is narrow. */\n.story-range-row {\n    padding: 0;\n}\n.story-range-row > box {\n    border-radius: 12px;\n}\n";

package/lib/types/types.d.ts

@@ -0,0 +1,6 @@
+import type Gtk from '@girs/gtk-4.0';
+import type { StoryWidget } from './story-widget.js';
+/** A sidebar row that remembers which story widget it selects. */
+export interface StoryRow extends Gtk.ListBoxRow {
+    storyWidget: StoryWidget;
+}

package/lib/types/window.d.ts

@@ -0,0 +1,44 @@
+import Adw from '@girs/adw-1';
+import type { StoryModule } from './story-widget.js';
+/**
+ * Main window for the storybook. The sidebar lists story instances grouped by
+ * the `Category/Name` title prefix; the preview pane holds the active
+ * {@link StoryWidget} and an `Adw.PreferencesGroup` of controls drives its
+ * `args` with two-way binding.
+ */
+export declare class StorybookWindow extends Adw.ApplicationWindow {
+    private _sidebar_list;
+    private _content_area;
+    private _control_panel;
+    private _preview_title;
+    private _show_controls_button;
+    private _controls_split_view;
+    private _main_split_view;
+    private _controlRows;
+    private _controlRefreshers;
+    private _activeStoryHandlerId;
+    private _activeStory;
+    constructor(params: Partial<Adw.ApplicationWindow.ConstructorProps>);
+    private _buildUI;
+    private _onToggleControls;
+    /** Populate the sidebar with story instances grouped by category. */
+    populateSidebar(storyModules: StoryModule[]): void;
+    private _clearSidebar;
+    private _groupStoriesByCategory;
+    private _addCategoryToSidebar;
+    private _addStoryToSidebar;
+    private _onStorySelected;
+    private _showStory;
+    private _updateControlPanel;
+    private _clearControlPanel;
+    private _createControlRow;
+    private _writeArg;
+    private _createTextRow;
+    private _createNumberRow;
+    private _createBooleanRow;
+    private _createRangeRow;
+    private _formatRangeValue;
+    private _createSelectRow;
+    private _createColorRow;
+    private _rgbaToHex;
+}

package/package.json

@@ -0,0 +1,70 @@
+{
+    "name": "@gjsify/storybook",
+    "version": "0.7.5",
+    "description": "Reusable GTK/Adwaita storybook for GJS — author *.story.ts and browse them in a generic component explorer",
+    "type": "module",
+    "module": "lib/esm/index.js",
+    "types": "lib/types/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./lib/types/index.d.ts",
+            "default": "./lib/esm/index.js"
+        }
+    },
+    "files": [
+        "lib"
+    ],
+    "scripts": {
+        "clear": "rm -rf lib tmp tsconfig.tsbuildinfo test.gjs.mjs || exit 0",
+        "check": "gjsify tsc --noEmit",
+        "build": "gjsify run build:gjsify && gjsify run build:types",
+        "build:gjsify": "gjsify build --library 'src/**/*.{ts,js}' --exclude 'src/**/*.spec.{mts,ts}' 'src/test.{mts,ts}'",
+        "build:types": "gjsify tsc",
+        "build:test": "gjsify run build:test:gjs",
+        "build:test:gjs": "gjsify build src/test.mts --app gjs --outfile test.gjs.mjs",
+        "test": "gjsify run build:gjsify && gjsify run build:test && gjsify run test:gjs",
+        "test:gjs": "gjsify run test.gjs.mjs"
+    },
+    "keywords": [
+        "gjs",
+        "storybook",
+        "stories",
+        "gtk",
+        "adwaita",
+        "ui"
+    ],
+    "dependencies": {
+        "@girs/adw-1": "1.10.0-4.0.4",
+        "@girs/gdk-4.0": "4.0.0-4.0.4",
+        "@girs/gio-2.0": "2.88.0-4.0.4",
+        "@girs/gjs": "4.0.4",
+        "@girs/glib-2.0": "2.88.0-4.0.4",
+        "@girs/gobject-2.0": "2.88.0-4.0.4",
+        "@girs/gtk-4.0": "4.23.0-4.0.4",
+        "@gjsify/stories": "^0.7.5"
+    },
+    "devDependencies": {
+        "@gjsify/cli": "^0.7.5",
+        "@gjsify/unit": "^0.7.5",
+        "@types/node": "^25.9.2",
+        "typescript": "^6.0.3"
+    },
+    "gjsify": {
+        "runtimes": {
+            "gjs": "polyfill",
+            "node": "none",
+            "browser": "none",
+            "nativescript": "none"
+        }
+    },
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/gjsify/gjsify.git",
+        "directory": "packages/framework/storybook"
+    },
+    "bugs": {
+        "url": "https://github.com/gjsify/gjsify/issues"
+    },
+    "homepage": "https://github.com/gjsify/gjsify/tree/main/packages/framework/storybook#readme"
+}