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

package/src/feedback/emoji-chooser.story.ts

@@ -0,0 +1,98 @@
+// Gtk.EmojiChooser — the emoji popover a text widget opens, with a search entry.
+//
+// The story shows the half that is easy to get wrong: the SEARCH. A term matches when it
+// prefixes a word of the emoji's name or of one of its keywords, a section with no match at
+// all disappears heading and all, and a search that empties every section shows the "No
+// Results Found" page instead of the list.
+
+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 { emojiChooserMeta } from './emoji-chooser.meta.js';
+
+/** Story: an entry with an emoji chooser attached to its prefix button. */
+export class EmojiChooserStory extends StoryWidget {
+    private _button: Gtk.Button | null = null;
+    private _entry: Gtk.Entry | null = null;
+    private _chooser: Gtk.EmojiChooser | null = null;
+
+    static {
+        GObject.registerClass({ GTypeName: 'AdwStorybookEmojiChooser' }, EmojiChooserStory);
+    }
+
+    constructor() {
+        super(StoryWidget.fromMeta(EmojiChooserStory.getMetadata(), 'Default'));
+    }
+
+    static getMetadata(): StoryMeta {
+        return { ...emojiChooserMeta, component: Gtk.EmojiChooser.$gtype };
+    }
+
+    initialize(): void {
+        this._entry = new Gtk.Entry({
+            placeholderText: 'Type a message…',
+            halign: Gtk.Align.CENTER,
+        });
+        this._entry.add_css_class('card');
+        this._entry.hexpand = true;
+
+        this._chooser = Gtk.EmojiChooser.new();
+        this._chooser.connect('emoji-picked', (_chooser: Gtk.EmojiChooser, text: string) => {
+            if (this._entry === null) return;
+            // The signal carries the Unicode SEQUENCE, which is what an entry inserts.
+            this._entry.set_text(this._entry.get_text() + text);
+        });
+
+        this._button = new Gtk.Button({
+            iconName: 'face-smile-symbolic',
+            tooltipText: 'Insert an emoji',
+            valign: Gtk.Align.CENTER,
+        });
+        this._button.add_css_class('flat');
+        this._button.add_css_class('circular');
+        // The popover's anchor is the widget it is a child of, and the button is the entry's
+        // prefix — which is the arrangement GtkEntry's own emoji completion uses.
+        this._chooser.set_parent(this._button);
+        const row = new Gtk.Box({ orientation: Gtk.Orientation.HORIZONTAL, spacing: 6 });
+        row.append(this._button);
+        row.append(this._entry);
+
+        const box = new Gtk.Box({
+            orientation: Gtk.Orientation.VERTICAL,
+            spacing: 12,
+            halign: Gtk.Align.CENTER,
+            valign: Gtk.Align.CENTER,
+        });
+        box.append(row);
+        this.addContent(box);
+        this._applySearch(this.args.search as string);
+    }
+
+    /**
+     * The chooser's search entry.
+     *
+     * `GtkEmojiChooser` declares NO properties at all — the search is a `GtkSearchEntry`
+     * inside its template (`ui/gtkemojichooser.ui`), not a property of the widget — so the
+     * only way to drive it is to find it.
+     */
+    private _searchEntry(): Gtk.SearchEntry | null {
+        let child: Gtk.Widget | null = this._chooser?.get_first_child() ?? null;
+        while (child !== null) {
+            if (child instanceof Gtk.SearchEntry) return child;
+            child = child.get_first_child();
+        }
+        return null;
+    }
+
+    private _applySearch(text: string): void {
+        this._searchEntry()?.set_text(text);
+    }
+
+    updateArgs(args: StoryArgs): void {
+        if (typeof args.search === 'string') this._applySearch(args.search);
+    }
+}
+
+GObject.type_ensure(EmojiChooserStory.$gtype);
+
+export const EmojiChooserStories: StoryModule = { stories: [EmojiChooserStory] };

package/src/feedback/gtk-about-dialog.meta.ts

@@ -0,0 +1,29 @@
+// Shared, renderer-agnostic metadata for the Gtk.AboutDialog story.
+
+import { ControlType, type StoryMeta } from '@gjsify/stories';
+
+export const gtkAboutDialogMeta: StoryMeta = {
+    title: 'Feedback/GTK About Dialog',
+    description:
+        "Gtk.AboutDialog — GTK's own about window: a dialog-size logo over the program name, with the Credits, License and System pages behind a stack switcher. NOT Adw.AboutDialog, which is a navigation view of preference rows.",
+    controls: [
+        { name: 'programName', label: 'Program name', type: ControlType.TEXT, defaultValue: 'Calculator' },
+        { name: 'version', label: 'Version', type: ControlType.TEXT, defaultValue: '48.1' },
+        {
+            name: 'licenseType',
+            label: 'License type',
+            type: ControlType.SELECT,
+            options: [
+                { label: 'Unknown', value: 'unknown' },
+                { label: 'Custom', value: 'custom' },
+                { label: 'GPL 3.0', value: 'gpl-3-0' },
+                { label: 'MIT', value: 'mit-x11' },
+                { label: 'BSD 3-Clause', value: 'bsd-3' },
+                { label: 'Apache 2.0', value: 'apache-2-0' },
+                { label: '0BSD', value: '0bsd' },
+            ],
+            defaultValue: 'gpl-3-0',
+        },
+        { name: 'withCredits', label: 'With credits', type: ControlType.BOOLEAN, defaultValue: true },
+    ],
+};

package/src/feedback/gtk-about-dialog.story.ts

@@ -0,0 +1,90 @@
+// Gtk.AboutDialog — GTK's own about window, presented from a button.
+//
+// The page-visibility rules are the story's subject: `license-type` picks which licence
+// text is on the main page and whether the License page exists at all, and `withCredits`
+// decides the third page and the switcher.
+
+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 { gtkAboutDialogMeta } from './gtk-about-dialog.meta.js';
+
+/** The `Gtk.License` nicks the control offers, in enum order. */
+const LICENSES: Record<string, Gtk.License> = {
+    unknown: Gtk.License.UNKNOWN,
+    custom: Gtk.License.CUSTOM,
+    'gpl-3-0': Gtk.License.GPL_3_0,
+    'mit-x11': Gtk.License.MIT_X11,
+    'bsd-3': Gtk.License.BSD_3,
+    'apache-2-0': Gtk.License.APACHE_2_0,
+    '0bsd': Gtk.License['0BSD'],
+};
+
+/** Story: Gtk.AboutDialog presented from a button, with a licence type and credits. */
+export class GtkAboutDialogStory extends StoryWidget {
+    private _button: Gtk.Button | null = null;
+
+    static {
+        GObject.registerClass({ GTypeName: 'AdwStorybookGtkAboutDialog' }, GtkAboutDialogStory);
+    }
+
+    constructor() {
+        super(StoryWidget.fromMeta(GtkAboutDialogStory.getMetadata(), 'Default'));
+    }
+
+    static getMetadata(): StoryMeta {
+        return { ...gtkAboutDialogMeta, component: Gtk.AboutDialog.$gtype };
+    }
+
+    initialize(): void {
+        this._button = new Gtk.Button({
+            label: 'Show dialog',
+            halign: Gtk.Align.CENTER,
+            valign: Gtk.Align.CENTER,
+        });
+        this._button.add_css_class('pill');
+        this._button.add_css_class('suggested-action');
+        this._button.connect('clicked', () => this._present());
+
+        this.addContent(this._button);
+    }
+
+    private _present(): void {
+        const dialog = new Gtk.AboutDialog({
+            programName: this.args.programName as string,
+            version: this.args.version as string,
+            logoIconName: 'application-x-executable-symbolic',
+            comments: 'An arithmetic calculator for the GNOME desktop.',
+            website: 'https://gitlab.gnome.org/World/gnome-calculator',
+            websiteLabel: 'GNOME Calculator',
+            copyright: '© 2026 The GNOME Project',
+            systemInformation: 'GTK 4.24.0\nglibc 2.42\nBuilt with meson 1.6',
+        });
+
+        const licenseType = LICENSES[this.args.licenseType as string] ?? Gtk.License.UNKNOWN;
+        if (licenseType === Gtk.License.CUSTOM) {
+            // A CUSTOM licence is the only one whose text the :license property supplies —
+            // set_license_type overwrites it for every other type (gtkaboutdialog.c:2259).
+            dialog.set_license('Permission is hereby granted, free of charge, to any person obtaining a copy…');
+        }
+        dialog.set_license_type(licenseType);
+
+        if (this.args.withCredits as boolean) {
+            dialog.set_authors(['Ada Lovelace <ada@example.org>', 'Grace Hopper']);
+            dialog.set_documenters(['Barbara Liskov']);
+            dialog.set_artists(['Margaret Hamilton']);
+            dialog.set_translator_credits('Alan Turing\nKatherine Johnson');
+            dialog.add_credit_section('Reviewed by', ['Tony Hoare <tony@example.org>']);
+        }
+
+        dialog.present();
+    }
+
+    updateArgs(_args: StoryArgs): void {
+        // The dialog reads the latest args each time it is presented; nothing to mutate live.
+    }
+}
+
+GObject.type_ensure(GtkAboutDialogStory.$gtype);
+
+export const GtkAboutDialogStories: StoryModule = { stories: [GtkAboutDialogStory] };

package/src/feedback/page-setup-unix-dialog.meta.ts

@@ -0,0 +1,37 @@
+// Shared, renderer-agnostic metadata for the Gtk.PageSetupUnixDialog story.
+
+import { ControlType, type StoryMeta } from '@gjsify/stories';
+
+export const pageSetupUnixDialogMeta: StoryMeta = {
+    title: 'Feedback/Page Setup Dialog',
+    description:
+        "Gtk.PageSetupUnixDialog — the page setup dialog Unix platforms have instead of a native one: a printer and a paper size, the chosen sheet's size and margins, and four orientation buttons.",
+    controls: [
+        {
+            name: 'paperSize',
+            label: 'Paper size',
+            type: ControlType.SELECT,
+            options: [
+                { label: 'US Letter', value: 'na_letter' },
+                { label: 'US Legal', value: 'na_legal' },
+                { label: 'A4', value: 'iso_a4' },
+                { label: 'A5', value: 'iso_a5' },
+                { label: 'B5', value: 'iso_b5' },
+                { label: 'A3', value: 'iso_a3' },
+            ],
+            defaultValue: 'iso_a4',
+        },
+        {
+            name: 'orientation',
+            label: 'Orientation',
+            type: ControlType.SELECT,
+            options: [
+                { label: 'Portrait', value: 'portrait' },
+                { label: 'Landscape', value: 'landscape' },
+                { label: 'Reverse portrait', value: 'reverse-portrait' },
+                { label: 'Reverse landscape', value: 'reverse-landscape' },
+            ],
+            defaultValue: 'landscape',
+        },
+    ],
+};

package/src/feedback/page-setup-unix-dialog.story.ts

@@ -0,0 +1,70 @@
+// Gtk.PageSetupUnixDialog — the Unix page setup dialog, presented from a button.
+//
+// The subject is what the dialog REPORTS: the chosen sheet's size in the user's unit, with
+// the four margins in the label's tooltip, and the four orientation buttons that read back
+// into the page setup.
+
+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 { pageSetupUnixDialogMeta } from './page-setup-unix-dialog.meta.js';
+
+/** The `Gtk.PageOrientation` nicks the control offers, in enum order. */
+const ORIENTATIONS: Record<string, Gtk.PageOrientation> = {
+    portrait: Gtk.PageOrientation.PORTRAIT,
+    landscape: Gtk.PageOrientation.LANDSCAPE,
+    'reverse-portrait': Gtk.PageOrientation.REVERSE_PORTRAIT,
+    'reverse-landscape': Gtk.PageOrientation.REVERSE_LANDSCAPE,
+};
+
+/** Story: the page setup dialog with a paper size and an orientation. */
+export class PageSetupUnixDialogStory extends StoryWidget {
+    private _button: Gtk.Button | null = null;
+
+    static {
+        GObject.registerClass({ GTypeName: 'AdwStorybookPageSetupUnixDialog' }, PageSetupUnixDialogStory);
+    }
+
+    constructor() {
+        super(StoryWidget.fromMeta(PageSetupUnixDialogStory.getMetadata(), 'Default'));
+    }
+
+    static getMetadata(): StoryMeta {
+        return { ...pageSetupUnixDialogMeta, component: Gtk.PageSetupUnixDialog.$gtype };
+    }
+
+    initialize(): void {
+        this._button = new Gtk.Button({
+            label: 'Page Setup…',
+            halign: Gtk.Align.CENTER,
+            valign: Gtk.Align.CENTER,
+        });
+        this._button.add_css_class('pill');
+        this._button.add_css_class('suggested-action');
+        this._button.connect('clicked', () => this._present());
+
+        this.addContent(this._button);
+    }
+
+    private _present(): void {
+        const dialog = Gtk.PageSetupUnixDialog.new('Page Setup', null);
+        // A page setup the dialog takes its values from. `set_page_setup` selects the
+        // matching row — appending it when no row matches, which is why the margins come
+        // from the paper size's own defaults here.
+        const setup = new Gtk.PageSetup();
+        setup.set_paper_size_and_default_margins(Gtk.PaperSize.new(this.args.paperSize as string));
+        setup.set_orientation(ORIENTATIONS[this.args.orientation as string] ?? Gtk.PageOrientation.PORTRAIT);
+        dialog.set_page_setup(setup);
+        dialog.present();
+    }
+
+    updateArgs(_args: StoryArgs): void {
+        // The dialog reads the latest args each time it is presented; nothing to mutate live.
+    }
+}
+
+// Unix-only widget: GTK's Windows build has no page setup dialog, so the module contributes no story.
+const available = 'PageSetupUnixDialog' in Gtk;
+if (available) GObject.type_ensure(PageSetupUnixDialogStory.$gtype);
+
+export const PageSetupUnixDialogStories: StoryModule = { stories: [PageSetupUnixDialogStory].filter(() => available) };

package/src/feedback/print-unix-dialog.meta.ts

@@ -0,0 +1,30 @@
+// Shared, renderer-agnostic metadata for the Gtk.PrintUnixDialog story.
+
+import { ControlType, type StoryMeta } from '@gjsify/stories';
+
+export const printUnixDialogMeta: StoryMeta = {
+    title: 'Feedback/Print Dialog',
+    description:
+        'Gtk.PrintUnixDialog — the Unix print dialog: seven notebook pages over a printer list, a Range and a Copies group on General, the sheet preview on Page Setup, and the Preview / Cancel / Print action area.',
+    controls: [
+        {
+            name: 'capabilities',
+            label: 'Capabilities',
+            type: ControlType.TEXT,
+            defaultValue: 'copies|collate|reverse|scale|preview|page-set',
+        },
+        {
+            name: 'range',
+            label: 'Range',
+            type: ControlType.SELECT,
+            options: [
+                { label: 'All Pages', value: 'all' },
+                { label: 'Current Page', value: 'current' },
+                { label: 'Selection', value: 'selection' },
+                { label: 'Pages', value: 'pages' },
+            ],
+            defaultValue: 'all',
+        },
+        { name: 'copies', label: 'Copies', type: ControlType.NUMBER, defaultValue: 2 },
+    ],
+};

package/src/feedback/print-unix-dialog.story.ts

@@ -0,0 +1,93 @@
+// Gtk.PrintUnixDialog — the Unix print dialog, presented from a button.
+//
+// The story is about the CAPABILITIES: `manual-capabilities` is the half of the mask the
+// APPLICATION can handle, and every control on the General and Page Setup pages is gated on
+// it — copies, collate (which also needs a count above one), reverse, scale, the two-sided
+// sheet picker, and whether Preview appears at all. The printer list is empty here because
+// GTK's comes from a print backend, and a story has none.
+
+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 { printUnixDialogMeta } from './print-unix-dialog.meta.js';
+
+/**
+ * The nicks of `GtkPrintCapabilities`, in enum order. Read lazily: GTK compiles the Unix print
+ * dialog, and with it this enum, out of its Windows build, so the namespace has no
+ * `PrintCapabilities` there.
+ */
+const capabilities = (): Record<string, Gtk.PrintCapabilities> => ({
+    collate: Gtk.PrintCapabilities.COLLATE,
+    copies: Gtk.PrintCapabilities.COPIES,
+    'generate-pdf': Gtk.PrintCapabilities.GENERATE_PDF,
+    'generate-ps': Gtk.PrintCapabilities.GENERATE_PS,
+    'number-up': Gtk.PrintCapabilities.NUMBER_UP,
+    'number-up-layout': Gtk.PrintCapabilities.NUMBER_UP_LAYOUT,
+    'page-set': Gtk.PrintCapabilities.PAGE_SET,
+    preview: Gtk.PrintCapabilities.PREVIEW,
+    reverse: Gtk.PrintCapabilities.REVERSE,
+    scale: Gtk.PrintCapabilities.SCALE,
+});
+
+/** Story: the print dialog with the capabilities the application declares it can handle. */
+export class PrintUnixDialogStory extends StoryWidget {
+    private _button: Gtk.Button | null = null;
+
+    static {
+        GObject.registerClass({ GTypeName: 'AdwStorybookPrintUnixDialog' }, PrintUnixDialogStory);
+    }
+
+    constructor() {
+        super(StoryWidget.fromMeta(PrintUnixDialogStory.getMetadata(), 'Default'));
+    }
+
+    static getMetadata(): StoryMeta {
+        return { ...printUnixDialogMeta, component: Gtk.PrintUnixDialog.$gtype };
+    }
+
+    initialize(): void {
+        this._button = new Gtk.Button({
+            label: 'Print…',
+            halign: Gtk.Align.CENTER,
+            valign: Gtk.Align.CENTER,
+        });
+        this._button.add_css_class('pill');
+        this._button.add_css_class('suggested-action');
+        this._button.connect('clicked', () => this._present());
+
+        this.addContent(this._button);
+    }
+
+    private _present(): void {
+        const dialog = Gtk.PrintUnixDialog.new('Print', null);
+        const nicks = capabilities();
+        const mask = String(this.args.capabilities)
+            .split('|')
+            .map((nick) => nicks[nick.trim()] ?? 0)
+            .reduce((caps, capability) => caps | capability, 0);
+        dialog.set_manual_capabilities(mask);
+
+        // The range group and the copies count, the two controls whose state decides what
+        // the dialog itself lets a user do (update_dialog_from_capabilities).
+        dialog.set_current_page(2);
+        dialog.set_support_selection(true);
+        dialog.set_has_selection(true);
+        const settings = new Gtk.PrintSettings();
+        settings.set_n_copies(Number(this.args.copies));
+        settings.set_collate(this.args.range === 'all');
+        settings.set_print_pages(this.args.range === 'current' ? Gtk.PrintPages.CURRENT : Gtk.PrintPages.ALL);
+        dialog.set_settings(settings);
+
+        dialog.present();
+    }
+
+    updateArgs(_args: StoryArgs): void {
+        // The dialog reads the latest args each time it is presented; nothing to mutate live.
+    }
+}
+
+// Unix-only widget: on Windows there is nothing to show, so the module contributes no story.
+const available = 'PrintUnixDialog' in Gtk;
+if (available) GObject.type_ensure(PrintUnixDialogStory.$gtype);
+
+export const PrintUnixDialogStories: StoryModule = { stories: [PrintUnixDialogStory].filter(() => available) };

package/src/feedback/shortcuts-dialog.meta.ts

@@ -0,0 +1,12 @@
+// Shared, renderer-agnostic metadata for the Shortcuts Dialog story. Imported by
+// both the GTK renderer (shortcuts-dialog.story.ts) and the browser renderer
+// (browser/feedback/shortcuts-dialog.web.ts) so the two expose identical controls.
+
+import { ControlType, type StoryMeta } from '@gjsify/stories';
+
+export const shortcutsDialogMeta: StoryMeta = {
+    title: 'Feedback/Shortcuts Dialog',
+    description:
+        'Adw.ShortcutsDialog — the window that lists an application’s keyboard shortcuts, one titled section at a time.',
+    controls: [{ name: 'title', label: 'Title', type: ControlType.TEXT, defaultValue: 'Keyboard Shortcuts' }],
+};

package/src/feedback/shortcuts-dialog.story.ts

@@ -0,0 +1,79 @@
+// Adw.ShortcutsDialog — the window that lists an application's shortcuts.
+// original implementation.
+
+import Adw from 'gi://Adw?version=1';
+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 { shortcutsDialogMeta } from './shortcuts-dialog.meta.js';
+
+/** Story: Adw.ShortcutsDialog presented from a button, with two sections of shortcuts. */
+export class ShortcutsDialogStory extends StoryWidget {
+    private _button: Gtk.Button | null = null;
+
+    static {
+        GObject.registerClass({ GTypeName: 'AdwStorybookShortcutsDialog' }, ShortcutsDialogStory);
+    }
+
+    constructor() {
+        super(StoryWidget.fromMeta(ShortcutsDialogStory.getMetadata(), 'Default'));
+    }
+
+    static getMetadata(): StoryMeta {
+        return { ...shortcutsDialogMeta, component: Adw.ShortcutsDialog.$gtype };
+    }
+
+    initialize(): void {
+        this._button = new Gtk.Button({
+            label: 'Show dialog',
+            halign: Gtk.Align.CENTER,
+            valign: Gtk.Align.CENTER,
+        });
+        this._button.add_css_class('pill');
+        this._button.add_css_class('suggested-action');
+        this._button.connect('clicked', () => this._present());
+
+        this.addContent(this._button);
+    }
+
+    private _present(): void {
+        // SECTIONS ARE GObjects, not widgets: each is added with `add(section)`, and an
+        // untitled one is the documented way to subdivide a section into groups.
+        const general = new Adw.ShortcutsSection({ title: 'General' });
+        general.add(new Adw.ShortcutsItem({ title: 'Open Menu', accelerator: 'F10' }));
+        general.add(new Adw.ShortcutsItem({ title: 'Preferences', action_name: 'app.preferences' }));
+        general.add(new Adw.ShortcutsItem({ title: 'Quit', accelerator: '<Control>q' }));
+
+        // No title: the section below is a continuation of the one above, which is what
+        // the class documents an untitled section for.
+        const navigation = new Adw.ShortcutsSection();
+        navigation.add(
+            new Adw.ShortcutsItem({
+                title: 'Move Tab Left',
+                accelerator: '<Shift><Control>Page_Up',
+                direction: Gtk.TextDirection.LTR,
+            }),
+        );
+        navigation.add(
+            new Adw.ShortcutsItem({
+                title: 'Move Tab Left',
+                accelerator: '<Shift><Control>Page_Up',
+                direction: Gtk.TextDirection.RTL,
+            }),
+        );
+
+        const dialog = new Adw.ShortcutsDialog({ title: this.args.title as string });
+        dialog.add(general);
+        dialog.add(navigation);
+
+        dialog.present(this);
+    }
+
+    updateArgs(_args: StoryArgs): void {
+        // The dialog reads the latest args each time it is presented; nothing to mutate live.
+    }
+}
+
+GObject.type_ensure(ShortcutsDialogStory.$gtype);
+
+export const ShortcutsDialogStories: StoryModule = { stories: [ShortcutsDialogStory] };

package/src/layout/application-window.meta.ts

@@ -0,0 +1,16 @@
+// Shared, renderer-agnostic metadata for the Application Window story. Imported by
+// both the GTK renderer (application-window.story.ts) and the browser renderer
+// (browser/layout/application-window.web.ts) so the two expose identical controls.
+
+import { ControlType, type StoryMeta } from '@gjsify/stories';
+
+export const applicationWindowMeta: StoryMeta = {
+    title: 'Layout/Application Window',
+    description:
+        'Adw.ApplicationWindow — an Adw.Window that belongs to a GtkApplication, plus that application’s menubar.',
+    controls: [
+        { name: 'title', label: 'Title', type: ControlType.TEXT, defaultValue: 'Text Editor' },
+        { name: 'subtitle', label: 'Subtitle', type: ControlType.TEXT, defaultValue: 'notes.md' },
+        { name: 'showMenubar', label: 'Show menubar', type: ControlType.BOOLEAN, defaultValue: true },
+    ],
+};

package/src/layout/application-window.story.ts

@@ -0,0 +1,97 @@
+// Adw.ApplicationWindow — an Adw.Window that belongs to a GtkApplication, and the
+// menubar such an application installs.
+// original implementation.
+
+import Adw from 'gi://Adw?version=1';
+import Gtk from 'gi://Gtk?version=4.0';
+import Gio from 'gi://Gio?version=2.0';
+import GObject from 'gi://GObject?version=2.0';
+import { type StoryArgs, type StoryMeta, type StoryModule, StoryWidget } from '@gjsify/storybook';
+import { applicationWindowMeta } from './application-window.meta.js';
+
+/** Story: Adw.ApplicationWindow with a menubar, a header bar and a status page. */
+export class ApplicationWindowStory extends StoryWidget {
+    private _window: Adw.ApplicationWindow | null = null;
+    private _title: Adw.WindowTitle | null = null;
+    private _toolbarView: Adw.ToolbarView | null = null;
+    private _menubar: Gtk.PopoverMenuBar | null = null;
+
+    static {
+        GObject.registerClass({ GTypeName: 'AdwStorybookApplicationWindow' }, ApplicationWindowStory);
+    }
+
+    constructor() {
+        super(StoryWidget.fromMeta(ApplicationWindowStory.getMetadata(), 'Default'));
+    }
+
+    static getMetadata(): StoryMeta {
+        return { ...applicationWindowMeta, component: Adw.ApplicationWindow.$gtype };
+    }
+
+    initialize(): void {
+        this._title = new Adw.WindowTitle({
+            title: this.args.title as string,
+            subtitle: this.args.subtitle as string,
+        });
+
+        const headerBar = new Adw.HeaderBar({ titleWidget: this._title, widthRequest: 460 });
+
+        const backButton = new Gtk.Button({ iconName: 'go-previous-symbolic' });
+        backButton.add_css_class('flat');
+        headerBar.pack_start(backButton);
+
+        this._toolbarView = new Adw.ToolbarView();
+        this._toolbarView.add_top_bar(headerBar);
+        this._toolbarView.content = new Adw.StatusPage({
+            title: 'Your Library',
+            description: 'Content sits between the toolbars and scrolls independently of them.',
+        });
+
+        // The menubar is a row of LINKS, which is what `Gtk.Application:menubar` is
+        // documented to be — two sections, each opening into its own popover.
+        const menu = new Gio.Menu();
+        const fileSection = new Gio.Menu();
+        fileSection.append('New Window', 'app.new-window');
+        fileSection.append('Quit', 'app.quit');
+        menu.append_section(null, fileSection);
+        const helpSection = new Gio.Menu();
+        helpSection.append('Keyboard Shortcuts', 'app.shortcuts');
+        helpSection.append('About', 'app.about');
+        menu.append_section(null, helpSection);
+
+        // Gtk.MenuBar is gone from GTK 4, so the row is a Gtk.PopoverMenuBar — and it is
+        // the WIDGET an application window draws as its menubar. An app never adds it:
+        // `Gtk.Application` installs the menu model at construction, and the property
+        // this story toggles is what decides whether the window DRAWS it. A story has no
+        // GtkApplication to install one, so it adds the same widget by hand, as the
+        // toolbar view's second top bar, which is where the application window's own
+        // menubar sits.
+        this._menubar = new Gtk.PopoverMenuBar({ menu_model: menu });
+        if (this.args.showMenubar as boolean) this._toolbarView.add_top_bar(this._menubar);
+
+        this._window = new Adw.ApplicationWindow({
+            content: this._toolbarView,
+            show_menubar: this.args.showMenubar as boolean,
+        });
+        this._window.set_default_size(460, 260);
+
+        this.addContent(this._window);
+    }
+
+    updateArgs(_args: StoryArgs): void {
+        if (!this._title || !this._window || !this._toolbarView || !this._menubar) return;
+        this._title.title = this.args.title as string;
+        this._title.subtitle = this.args.subtitle as string;
+        this._window.show_menubar = this.args.showMenubar as boolean;
+
+        // The property and the bar are one decision, so the control moves both — which
+        // is what the application window does with the menubar its application installed.
+        const showing = this.args.showMenubar as boolean;
+        if (showing && this._menubar.get_parent() === null) this._toolbarView.add_top_bar(this._menubar);
+        if (!showing && this._menubar.get_parent() !== null) this._toolbarView.remove(this._menubar);
+    }
+}
+
+GObject.type_ensure(ApplicationWindowStory.$gtype);
+
+export const ApplicationWindowStories: StoryModule = { stories: [ApplicationWindowStory] };