@gjsify/example-gtk-adwaita-storybook 0.53.0 → 0.55.0

package/src/windows/gtk-application-window.meta.ts

@@ -0,0 +1,27 @@
+// Shared, renderer-agnostic metadata for the GTK Application Window story. Imported by the GTK
+// renderer (gtk-application-window.story.ts) and the browser renderer
+// (browser/windows/gtk-application-window.web.ts), so both expose identical controls.
+//
+// The NAME is `gtk-application-window` and not `application-window` because
+// `Adw.ApplicationWindow` holds that bare name on the adwaita/layout page, and the
+// storybook keys every meta on its file name: a second `application-window.meta.ts`
+// would silently displace one of the two. The block in /gjsify/gtk/windows/ is titled
+// `Gtk.ApplicationWindow`, which `TITLED_AFTER` in
+// `scripts/check-website-adwaita-gallery.mjs` maps onto this meta.
+
+import { ControlType, type StoryMeta } from '@gjsify/stories';
+
+export const gtkApplicationWindowMeta: StoryMeta = {
+    title: 'Windows/Application Window',
+    description:
+        'Gtk.ApplicationWindow — a Gtk.Window that also handles an application menubar. The ' +
+        'bar shows only when `show-menubar` is set AND the application HAS one: GTK builds it ' +
+        "from the GtkApplication's menu model, and reads the item count before deciding " +
+        '(gtkapplicationwindow.c:400-402). Everything else about the window is the base class.',
+    controls: [
+        { name: 'title', label: 'Title', type: ControlType.TEXT, defaultValue: 'Editor' },
+        { name: 'showMenubar', label: 'Show menubar', type: ControlType.BOOLEAN, defaultValue: true },
+        { name: 'hasMenubar', label: 'The application has one', type: ControlType.BOOLEAN, defaultValue: true },
+        { name: 'deletable', label: 'Deletable', type: ControlType.BOOLEAN, defaultValue: true },
+    ],
+};

package/src/windows/gtk-application-window.story.ts

@@ -0,0 +1,89 @@
+// Gtk.ApplicationWindow — a Gtk.Window with an application menubar, and the property that
+// decides whether the bar is shown.
+// original implementation.
+
+import Gio from 'gi://Gio?version=2.0';
+import Gtk from 'gi://Gtk?version=4.0';
+import GObject from 'gi://GObject?version=2.0';
+import { type StoryArgs, type StoryMeta, type StoryModule, StoryWidget } from '@gjsify/storybook';
+import { gtkApplicationWindowMeta } from './gtk-application-window.meta.js';
+
+/** The menu model the bar is built from — the thing no attribute can carry. */
+function menubarModel(): Gio.Menu {
+    const menu = new Gio.Menu();
+    const file = new Gio.Menu();
+    file.append('_New', 'win.new');
+    file.append('_Open…', 'win.open');
+    const edit = new Gio.Menu();
+    edit.append('_Copy', 'win.copy');
+    edit.append('_Paste', 'win.paste');
+    menu.append_section(null, file);
+    menu.append_section(null, edit);
+    return menu;
+}
+
+/** Story: a Gtk.ApplicationWindow whose `show-menubar` and menu model are both driven by args. */
+export class GtkApplicationWindowStory extends StoryWidget {
+    private _window: Gtk.ApplicationWindow | null = null;
+    private _application: Gtk.Application | null = null;
+    private _menubar: Gio.Menu | null = null;
+
+    static {
+        GObject.registerClass({ GTypeName: 'AdwStorybookGtkApplicationWindow' }, GtkApplicationWindowStory);
+    }
+
+    constructor() {
+        super(StoryWidget.fromMeta(GtkApplicationWindowStory.getMetadata(), 'Default'));
+    }
+
+    static getMetadata(): StoryMeta {
+        return { ...gtkApplicationWindowMeta, component: Gtk.ApplicationWindow.$gtype };
+    }
+
+    initialize(): void {
+        this._application = new Gtk.Application({ application_id: 'eu.jumplink.AdwStorybookGtkApplicationWindow' });
+        this._menubar = menubarModel();
+        // The bar reads the MENU MODEL off the application, never off the window
+        // (gtkapplicationwindow.c:337-348), so the story sets it on the application.
+        this._application.set_menubar(this._menubar);
+
+        this._window = new Gtk.ApplicationWindow({
+            application: this._application,
+            default_width: 460,
+            default_height: 260,
+        });
+        this._window.set_titlebar(new Gtk.HeaderBar());
+        const body = new Gtk.Box({
+            orientation: Gtk.Orientation.VERTICAL,
+            spacing: 12,
+            margin_top: 12,
+            margin_start: 12,
+        });
+        body.append(
+            new Gtk.Label({ label: 'The bar above is built from the application menu.', css_classes: ['dimmed'] }),
+        );
+        this._window.set_child(body);
+
+        this.addContent(this._window);
+        this._apply();
+    }
+
+    updateArgs(_args: StoryArgs): void {
+        this._apply();
+    }
+
+    private _apply(): void {
+        if (!this._window || !this._application) return;
+        this._window.title = this.args.title as string;
+        this._window.deletable = this.args.deletable as boolean;
+        // The second half of `update_menubar`'s rule (:400-402): a window with no menubar at
+        // all shows nothing, whatever `show-menubar` says. `set_menubar(null)` is the same
+        // "no model" state an application starts in.
+        this._application.set_menubar((this.args.hasMenubar as boolean) ? this._menubar : null);
+        this._window.show_menubar = this.args.showMenubar as boolean;
+    }
+}
+
+GObject.type_ensure(GtkApplicationWindowStory.$gtype);
+
+export const GtkApplicationWindowStories: StoryModule = { stories: [GtkApplicationWindowStory] };

package/src/windows/gtk-header-bar.meta.ts

@@ -0,0 +1,39 @@
+// Shared, renderer-agnostic metadata for the GTK Header Bar story. Imported by the GTK
+// renderer (gtk-header-bar.story.ts) and the browser renderer
+// (browser/windows/gtk-header-bar.web.ts), so both expose identical controls.
+
+import { ControlType, type StoryMeta } from '@gjsify/stories';
+
+export const gtkHeaderBarMeta: StoryMeta = {
+    title: 'Windows/Header Bar',
+    description:
+        'Gtk.HeaderBar — the titlebar widget: children packed at the start and at the end, ' +
+        'the window title in the middle, and the window-frame buttons GTK would otherwise ask ' +
+        'the window manager for. `end` PREPENDS, so the first end child sits nearest the ' +
+        'edge; a `title` child takes the middle away from the derived title label; and ' +
+        '`show-title-buttons` CREATES and REMOVES the two control groups rather than hiding them.',
+    controls: [
+        {
+            name: 'titleWidget',
+            label: 'Title widget',
+            type: ControlType.SELECT,
+            options: [
+                { label: 'The window title', value: 'none' },
+                { label: 'A custom centre widget', value: 'custom' },
+            ],
+            defaultValue: 'none',
+        },
+        { name: 'showTitleButtons', label: 'Title buttons', type: ControlType.BOOLEAN, defaultValue: true },
+        {
+            name: 'decorationLayout',
+            label: 'Decoration layout',
+            type: ControlType.SELECT,
+            options: [
+                { label: 'GNOME (menu:minimize,maximize,close)', value: 'menu:minimize,maximize,close' },
+                { label: 'Close only', value: ':close' },
+                { label: 'macOS (icon:minimize,maximize)', value: 'icon:minimize,maximize' },
+            ],
+            defaultValue: 'menu:minimize,maximize,close',
+        },
+    ],
+};

package/src/windows/gtk-header-bar.story.ts

@@ -0,0 +1,76 @@
+// Gtk.HeaderBar — GTK's own titlebar widget, with its three children, its derived title
+// label and the two window-control groups it creates.
+// original implementation.
+
+import Gtk from 'gi://Gtk?version=4.0';
+import GObject from 'gi://GObject?version=2.0';
+import { type StoryArgs, type StoryMeta, type StoryModule, StoryWidget } from '@gjsify/storybook';
+import { gtkHeaderBarMeta } from './gtk-header-bar.meta.js';
+
+/**
+ * Story: a Gtk.HeaderBar inside a Gtk.Window, with args driving layout and decorations.
+ *
+ * Named `GtkHeaderBarStory`, not `HeaderBarStory`, and the GType carries the same `Gtk`
+ * infix: GType names share ONE process-wide namespace, and
+ * `layout/header-bar.story.ts` (the Adw.HeaderBar) already owns `AdwStorybookHeaderBar`.
+ * Registering it twice throws `a GType named 'AdwStorybookHeaderBar' is already
+ * registered` the moment both story modules load — the storybook smoke proof, not a type
+ * error. Every sibling in this directory prefixes the same way (`GtkWindowStory`,
+ * `GtkApplicationWindowStory`).
+ */
+export class GtkHeaderBarStory extends StoryWidget {
+    private _bar: Gtk.HeaderBar | null = null;
+    private _titleLabel: Gtk.Label | null = null;
+
+    static {
+        GObject.registerClass({ GTypeName: 'AdwStorybookGtkHeaderBar' }, GtkHeaderBarStory);
+    }
+
+    constructor() {
+        super(StoryWidget.fromMeta(GtkHeaderBarStory.getMetadata(), 'Default'));
+    }
+
+    static getMetadata(): StoryMeta {
+        return { ...gtkHeaderBarMeta, component: Gtk.HeaderBar.$gtype };
+    }
+
+    initialize(): void {
+        this._bar = new Gtk.HeaderBar();
+
+        // `pack_end` PREPENDS (gtkheaderbar.c:843-861), so the order below is the order the
+        // buttons read in from the edge inwards: search, then the primary menu.
+        const menu = new Gtk.Button({ icon_name: 'open-menu-symbolic' });
+        menu.add_css_class('flat');
+        this._bar.pack_end(menu);
+        const search = new Gtk.Button({ icon_name: 'system-search-symbolic' });
+        search.add_css_class('flat');
+        this._bar.pack_end(search);
+
+        const back = new Gtk.Button({ label: '‹' });
+        back.add_css_class('flat');
+        this._bar.pack_start(back);
+
+        this._titleLabel = new Gtk.Label({ label: 'Mailboxes', css_classes: ['title'] });
+
+        this.addContent(this._bar);
+        this._apply();
+    }
+
+    updateArgs(_args: StoryArgs): void {
+        this._apply();
+    }
+
+    private _apply(): void {
+        if (!this._bar) return;
+        this._bar.decoration_layout = this.args.decorationLayout as string;
+        this._bar.show_title_buttons = this.args.showTitleButtons as boolean;
+        // The either/or of `gtk_header_bar_set_title_widget` (gtkheaderbar.c:313-341): the
+        // centre bin goes empty for the widget, and NULL hands the derived label back.
+        if ((this.args.titleWidget as string) === 'custom') this._bar.title_widget = this._titleLabel;
+        else this._bar.title_widget = null;
+    }
+}
+
+GObject.type_ensure(GtkHeaderBarStory.$gtype);
+
+export const GtkHeaderBarStories: StoryModule = { stories: [GtkHeaderBarStory] };

package/src/windows/gtk-window.meta.ts

@@ -0,0 +1,30 @@
+// Shared, renderer-agnostic metadata for the GTK Window story. Imported by the GTK
+// renderer (gtk-window.story.ts) and the browser renderer
+// (browser/windows/gtk-window.web.ts), so both expose identical controls.
+//
+// The NAME is `gtk-window` and not `window` because `Adw.Window` holds that bare name
+// on the adwaita/layout page, and the storybook keys every meta on its file name: a
+// second `window.meta.ts` would silently displace one of the two. The block in
+// /gjsify/gtk/windows/ is titled `Gtk.Window`, which `TITLED_AFTER` in
+// `scripts/check-website-adwaita-gallery.mjs` maps onto this meta.
+
+import { ControlType, type StoryMeta } from '@gjsify/stories';
+
+export const gtkWindowMeta: StoryMeta = {
+    title: 'Windows/Window',
+    description:
+        'Gtk.Window — a toplevel with a `titlebar` and a `child`, and the properties that ' +
+        'decide what its frame shows: `decorated`, `deletable`, `resizable`, `maximized` and ' +
+        '`hide-on-close`. The BROWSER replica of this one is an IN-PAGE FRAME, not a toplevel: ' +
+        'a browser document has no window to map. The story therefore cancels `close-request`, ' +
+        'which is what an application does when it wants to keep the window.',
+    controls: [
+        { name: 'title', label: 'Title', type: ControlType.TEXT, defaultValue: 'Documents' },
+        { name: 'decorated', label: 'Decorated', type: ControlType.BOOLEAN, defaultValue: true },
+        { name: 'deletable', label: 'Deletable', type: ControlType.BOOLEAN, defaultValue: true },
+        { name: 'resizable', label: 'Resizable', type: ControlType.BOOLEAN, defaultValue: true },
+        { name: 'maximized', label: 'Maximized', type: ControlType.BOOLEAN, defaultValue: false },
+        { name: 'modal', label: 'Modal', type: ControlType.BOOLEAN, defaultValue: false },
+        { name: 'hideOnClose', label: 'Hide on close', type: ControlType.BOOLEAN, defaultValue: true },
+    ],
+};

package/src/windows/gtk-window.story.ts

@@ -0,0 +1,64 @@
+// Gtk.Window — a toplevel, its titlebar, and the properties that decide what the frame shows.
+// original implementation.
+
+import Gtk from 'gi://Gtk?version=4.0';
+import GObject from 'gi://GObject?version=2.0';
+import { type StoryArgs, type StoryMeta, type StoryModule, StoryWidget } from '@gjsify/storybook';
+import { gtkWindowMeta } from './gtk-window.meta.js';
+
+/** Story: a real Gtk.Window whose frame properties are all driven by args. */
+export class GtkWindowStory extends StoryWidget {
+    private _window: Gtk.Window | null = null;
+
+    static {
+        GObject.registerClass({ GTypeName: 'AdwStorybookGtkWindow' }, GtkWindowStory);
+    }
+
+    constructor() {
+        super(StoryWidget.fromMeta(GtkWindowStory.getMetadata(), 'Default'));
+    }
+
+    static getMetadata(): StoryMeta {
+        return { ...gtkWindowMeta, component: Gtk.Window.$gtype };
+    }
+
+    initialize(): void {
+        this._window = new Gtk.Window({ default_width: 460, default_height: 280 });
+
+        // `decorated: false` DROPS the titlebar outright (gtkwindow.c:1014), so the story
+        // keeps the bar in the TREE and lets the property decide whether it is seen.
+        const bar = new Gtk.HeaderBar();
+        this._window.set_titlebar(bar);
+
+        const body = new Gtk.Box({
+            orientation: Gtk.Orientation.VERTICAL,
+            spacing: 12,
+            margin_top: 12,
+            margin_start: 12,
+        });
+        body.append(new Gtk.Label({ label: 'The frame above is a Gtk.HeaderBar.', css_classes: ['dimmed'] }));
+        this._window.set_child(body);
+
+        this.addContent(this._window);
+        this._apply();
+    }
+
+    updateArgs(_args: StoryArgs): void {
+        this._apply();
+    }
+
+    private _apply(): void {
+        if (!this._window) return;
+        this._window.title = this.args.title as string;
+        this._window.decorated = this.args.decorated as boolean;
+        this._window.deletable = this.args.deletable as boolean;
+        this._window.resizable = this.args.resizable as boolean;
+        this._window.maximized = this.args.maximized as boolean;
+        this._window.modal = this.args.modal as boolean;
+        this._window.hide_on_close = this.args.hideOnClose as boolean;
+    }
+}
+
+GObject.type_ensure(GtkWindowStory.$gtype);
+
+export const GtkWindowStories: StoryModule = { stories: [GtkWindowStory] };

package/src/windows/window-controls.meta.ts

@@ -0,0 +1,42 @@
+// Shared, renderer-agnostic metadata for the Window Controls story. Imported by the GTK
+// renderer (window-controls.story.ts) and the browser renderer
+// (browser/windows/window-controls.web.ts), so both expose identical controls.
+
+import { ControlType, type StoryMeta } from '@gjsify/stories';
+
+export const windowControlsMeta: StoryMeta = {
+    title: 'Windows/Window Controls',
+    description:
+        'Gtk.WindowControls — one SIDE of the window frame controls, and the decision table ' +
+        'behind them. The decoration layout is split on the first colon; each token of the ' +
+        'selected half builds one button or none, because `icon` and `minimize` want a ' +
+        'SOVEREIGN window, `maximize` wants a resizable one and `close` wants a deletable one. ' +
+        '`empty` is the property that says none of them did.',
+    controls: [
+        {
+            name: 'side',
+            label: 'Side',
+            type: ControlType.SELECT,
+            options: [
+                { label: 'Start', value: 'start' },
+                { label: 'End', value: 'end' },
+            ],
+            defaultValue: 'start',
+        },
+        {
+            name: 'decorationLayout',
+            label: 'Decoration layout',
+            type: ControlType.SELECT,
+            options: [
+                { label: 'GNOME (menu:minimize,maximize,close)', value: 'menu:minimize,maximize,close' },
+                { label: 'Windows (icon:minimize,maximize,close)', value: 'icon:minimize,maximize,close' },
+                { label: 'Close only', value: ':close' },
+                { label: 'macOS (icon:minimize,maximize)', value: 'icon:minimize,maximize' },
+            ],
+            defaultValue: 'menu:minimize,maximize,close',
+        },
+        { name: 'resizable', label: 'Resizable window', type: ControlType.BOOLEAN, defaultValue: true },
+        { name: 'maximized', label: 'Maximized window', type: ControlType.BOOLEAN, defaultValue: false },
+        { name: 'modal', label: 'Modal window', type: ControlType.BOOLEAN, defaultValue: false },
+    ],
+};

package/src/windows/window-controls.story.ts

@@ -0,0 +1,61 @@
+// Gtk.WindowControls — the frame buttons of ONE side, and the window properties each token
+// reads. A Gtk.WindowControls outside a Gtk.Window draws NOTHING (gtkwindowcontrols.c:257-264),
+// which is why this story is a window rather than a bare widget.
+// original implementation.
+
+import Gtk from 'gi://Gtk?version=4.0';
+import GObject from 'gi://GObject?version=2.0';
+import { type StoryArgs, type StoryMeta, type StoryModule, StoryWidget } from '@gjsify/storybook';
+import { windowControlsMeta } from './window-controls.meta.js';
+
+/** Story: a Gtk.WindowControls in the titlebar of a real Gtk.Window, driven by args. */
+export class WindowControlsStory extends StoryWidget {
+    private _window: Gtk.Window | null = null;
+    private _controls: Gtk.WindowControls | null = null;
+
+    static {
+        GObject.registerClass({ GTypeName: 'AdwStorybookWindowControls' }, WindowControlsStory);
+    }
+
+    constructor() {
+        super(StoryWidget.fromMeta(WindowControlsStory.getMetadata(), 'Default'));
+    }
+
+    static getMetadata(): StoryMeta {
+        return { ...windowControlsMeta, component: Gtk.WindowControls.$gtype };
+    }
+
+    initialize(): void {
+        this._window = new Gtk.Window({ title: 'Documents', default_width: 420, default_height: 220 });
+        const box = new Gtk.Box({ orientation: Gtk.Orientation.VERTICAL, spacing: 8 });
+        box.append(new Gtk.Label({ label: 'The bar draws nothing outside a window.', css_classes: ['dimmed'] }));
+        this._window.set_child(box);
+
+        // A window with NO titlebar of its own, so the controls really are the titlebar —
+        // which is the shape `update_window_buttons` reads its four window properties for.
+        this._controls = new Gtk.WindowControls();
+        this._window.set_titlebar(this._controls);
+
+        this.addContent(this._window);
+        this._apply();
+    }
+
+    updateArgs(_args: StoryArgs): void {
+        this._apply();
+    }
+
+    private _apply(): void {
+        if (!this._window || !this._controls) return;
+        const side = (this.args.side as string) === 'end' ? Gtk.PackType.END : Gtk.PackType.START;
+        this._controls.side = side;
+        this._controls.decoration_layout = this.args.decorationLayout as string;
+        // `update_window_buttons` (:270-274) reads exactly these four off the root.
+        this._window.resizable = this.args.resizable as boolean;
+        this._window.maximized = this.args.maximized as boolean;
+        this._window.modal = this.args.modal as boolean;
+    }
+}
+
+GObject.type_ensure(WindowControlsStory.$gtype);
+
+export const WindowControlsStories: StoryModule = { stories: [WindowControlsStory] };