@gjsify/example-gtk-adwaita-storybook 0.19.0

package/README.md

@@ -0,0 +1,120 @@
+# Adwaita Storybook
+
+An interactive **component browser for [Libadwaita](https://gnome.pages.gitlab.gnome.org/libadwaita/)**
+widgets — the GNOME equivalent of a web "storybook". Each widget is rendered live, in
+isolation, with a two-way-bound **Controls** panel so you can poke at its properties and
+watch it update.
+
+It is a showcase for three pieces of gjsify tooling working together:
+
+- **[`@gjsify/storybook`](../../../packages/framework/storybook)** — the GTK/Adwaita story
+  renderer (sidebar by category, live control panel).
+- **[`@gjsify/stories`](../../../packages/framework/stories)** — the pure-TS story contract.
+- **[`@gjsify/devtools`](../../../packages/framework/devtools)** — a DBus + MCP control plane
+  that lets an agent (or you, with `gdbus`) drive and screenshot every story headlessly.
+
+![Avatar story](docs/avatar.png)
+
+## Run it
+
+```bash
+# from this directory
+gjsify storybook            # discover every *.story.ts, build (--app gjs), launch the browser
+gjsify storybook --watch    # rebuild + relaunch on change
+```
+
+`gjsify storybook` reads the `gjsify.storybook` block in [`package.json`](package.json)
+(application id, window title, the `src` story dir, and `--globals auto`). No per-project
+storybook *app* — just `*.story.ts` files plus the shared renderer.
+
+## Debug / drive it over DBus + MCP
+
+Launch with the devtools control plane enabled, then drive it from `gdbus`, an MCP client,
+or the bundled harness:
+
+```bash
+GJSIFY_DEVTOOLS=1 gjsify storybook          # exports org.gjsify.Devtools on the session bus
+# in another shell — list + open stories, read/set args:
+gdbus call --session --dest org.gjsify.AdwaitaStorybook \
+  --object-path /org/gjsify/AdwaitaStorybook/devtools \
+  --method org.gjsify.Devtools.ListStories
+```
+
+Over MCP (the storybook profile adds `list_stories` / `open_story` / `get_current_story` /
+`set_story_arg` on top of the generic `screenshot` / `swap_css` / … tools):
+
+```bash
+gjsify debug --profile storybook            # MCP bridge to a running storybook
+```
+
+### Screenshot every story
+
+[`tools/shoot-stories.js`](tools/shoot-stories.js) opens each story over the devtools DBus
+surface and saves a GSK-rendered PNG of the window — the same path used to review this
+showcase:
+
+```bash
+GJSIFY_DEVTOOLS=1 gjsify storybook &                       # launch
+gjs -m tools/shoot-stories.js org.gjsify.AdwaitaStorybook ./shots   # capture all stories
+```
+
+## Stories
+
+Stories live under [`src/`](src), grouped into category folders. The sidebar group comes
+from the `"Category/Name"` story `title`, not the folder.
+
+| Category | Widgets |
+|---|---|
+| Presentation | Avatar, Banner, StatusPage, Spinner, WindowTitle |
+| Boxed Lists | ActionRow, EntryRow, PasswordEntryRow, ComboRow, SpinRow, SwitchRow, ExpanderRow, ButtonRow, PreferencesGroup |
+| Buttons | SplitButton, ButtonContent, ToggleGroup, button style classes |
+| Layout | Clamp, WrapBox, ToolbarView, HeaderBar |
+| Navigation | NavigationView, NavigationSplitView, OverlaySplitView, BottomSheet, Sidebar |
+| View Switching | ViewSwitcher + ViewStack, InlineViewSwitcher, Carousel, TabView |
+| Feedback | Toast, AlertDialog, AboutDialog, PreferencesDialog |
+
+## Add a story
+
+A story is a `StoryWidget` subclass with a `static getMetadata(): StoryMeta` (the
+`"Category/Name"` title groups the sidebar, the `controls` drive the live panel),
+exported as a `StoryModule`. See [`src/presentation/avatar.story.ts`](src/presentation/avatar.story.ts)
+for the canonical pattern:
+
+```ts
+import Adw from '@girs/adw-1';
+import GObject from '@girs/gobject-2.0';
+import { ControlType, type StoryArgs, type StoryMeta, type StoryModule, StoryWidget } from '@gjsify/storybook';
+
+export class MyStory extends StoryWidget {
+    private _widget: Adw.Avatar | null = null;
+    static {
+        GObject.registerClass({ GTypeName: 'AdwStorybookMyStory' }, MyStory);
+    }
+    constructor() {
+        super(StoryWidget.fromMeta(MyStory.getMetadata(), 'Default'));
+    }
+    static getMetadata(): StoryMeta {
+        return {
+            title: 'Presentation/My Widget',
+            controls: [{ name: 'text', label: 'Text', type: ControlType.TEXT, defaultValue: 'Hi' }],
+        };
+    }
+    initialize(): void {
+        this._widget = new Adw.Avatar({ text: this.args.text as string, size: 96 });
+        this.addContent(this._widget);
+    }
+    updateArgs(_args: StoryArgs): void {
+        if (this._widget) this._widget.text = this.args.text as string;
+    }
+}
+GObject.type_ensure(MyStory.$gtype);
+export const MyStories: StoryModule = { stories: [MyStory] };
+```
+
+Rules of thumb: globally-unique `GTypeName` (prefix `AdwStorybook…`), wrap `Adw.*Row`s in an
+`Adw.PreferencesGroup`, give space-filling widgets a `widthRequest`/`heightRequest`, and
+present dialogs from a button rather than embedding them.
+
+## License
+
+MIT © Pascal Garber. Libadwaita is LGPL-2.1+ © GNOME contributors.

package/dist/adw-runasync.mjs

@@ -0,0 +1 @@
+import{createRequire as e}from"node:module";import"@gjsify/node-gi/globals";var t=Object.defineProperty,__name=(e,n)=>t(e,`name`,{value:n,configurable:!0});const n=e(import.meta.url);let r;function load$3(){return r===void 0&&(r=n(`@gjsify/node-gi/gi`).requireGi(`Adw`,`1`)),r}__name(load$3,`load`);var i=new Proxy(Object.create(null),{get(e,t){return load$3()[t]},has(e,t){return t in load$3()}});const a=e(import.meta.url);let o;function load$2(){return o===void 0&&(o=a(`@gjsify/node-gi/gi`).requireGi(`Gtk`,`4.0`)),o}__name(load$2,`load`);var s=new Proxy(Object.create(null),{get(e,t){return load$2()[t]},has(e,t){return t in load$2()}});const c=e(import.meta.url);let l;function load$1(){return l===void 0&&(l=c(`@gjsify/node-gi/gi`).requireGi(`Gio`,`2.0`)),l}__name(load$1,`load`);var u=new Proxy(Object.create(null),{get(e,t){return load$1()[t]},has(e,t){return t in load$1()}});const d=e(import.meta.url);let f;function load(){return f===void 0&&(f=d("@gjsify/node-gi/gi").requireGi(`GLib`,`2.0`)),f}var p=new Proxy(Object.create(null),{get(e,t){return load()[t]},has(e,t){return t in load()}});print(`A: start`);const m=new i.Application({application_id:`org.gjsify.AdwRunAsync`,flags:u.ApplicationFlags.NON_UNIQUE});m.connect(`activate`,()=>{print(`C: activate`);let e=new i.ApplicationWindow({application:m}),t=new i.ToolbarView;t.add_top_bar(new i.HeaderBar),t.set_content(new s.Label({label:`hi from node-gi`})),e.set_content(t),print(`D: window built, presenting`),e.present(),print(`E: presented`),p.timeout_add(p.PRIORITY_DEFAULT,600,()=>(print(`F: timeout in loop, windows=`+m.get_windows().length),m.quit(),p.SOURCE_REMOVE))}),print(`B: runAsync`);const h=await m.runAsync([]);print(`G: resolved status=`+h);export{};