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

package/src/view-switching/stack.meta.ts

@@ -0,0 +1,53 @@
+// Shared, renderer-agnostic metadata for the Stack story. Imported by the GTK
+// renderer (stack.story.ts) and the browser renderer
+// (browser/view-switching/stack.web.ts) so the two expose identical controls.
+
+import { ControlType, type StoryMeta } from '@gjsify/stories';
+
+/**
+ * The three pages both renderers build, as the C would: a name for `visible-child-name`,
+ * a short title for the switcher's button, and a body. `attn` marks the page as
+ * `needs-attention`, which is what the switcher draws the dot for.
+ */
+export const STACK_PAGES = [
+    { name: 'overview', title: 'Overview', attn: false, body: 'Three pages, one visible at a time.' },
+    { name: 'activity', title: 'Activity', attn: false, body: 'Switching is animated by transition-type.' },
+    { name: 'settings', title: 'Settings', attn: true, body: 'This page wants your attention.' },
+] as const;
+
+export const stackMeta: StoryMeta = {
+    title: 'View Switching/Stack',
+    description:
+        'Gtk.Stack — one visible child out of many, with the animated change between them. ' +
+        '`transition-type` picks the animation and `transition-duration` its length; `hhomogeneous` and ' +
+        '`vhomogeneous` say whether every page is allocated the same size. A Gtk.StackPage is a GObject ' +
+        'rather than a widget, so its title, icon and needs-attention live on the page itself.',
+    controls: [
+        {
+            name: 'transitionType',
+            label: 'Transition type',
+            type: ControlType.SELECT,
+            options: [
+                { label: 'None', value: 'none' },
+                { label: 'Crossfade', value: 'crossfade' },
+                { label: 'Slide left / right', value: 'slide-left-right' },
+                { label: 'Slide up / down', value: 'slide-up-down' },
+                { label: 'Over left / right', value: 'over-left-right' },
+                { label: 'Rotate left / right', value: 'rotate-left-right' },
+            ],
+            defaultValue: 'slide-left-right',
+        },
+        {
+            name: 'transitionDuration',
+            label: 'Duration (ms)',
+            type: ControlType.RANGE,
+            min: 0,
+            max: 600,
+            step: 50,
+            defaultValue: 200,
+        },
+        { name: 'interpolateSize', label: 'Interpolate size', type: ControlType.BOOLEAN, defaultValue: false },
+        { name: 'hhomogeneous', label: 'HHomogeneous', type: ControlType.BOOLEAN, defaultValue: true },
+        { name: 'vhomogeneous', label: 'VHomogeneous', type: ControlType.BOOLEAN, defaultValue: true },
+    ],
+};

package/src/view-switching/stack.story.ts

@@ -0,0 +1,95 @@
+// Gtk.Stack — one visible child out of many, animated, with a Gtk.StackSwitcher on top.
+// 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 { STACK_PAGES, stackMeta } from './stack.meta.js';
+
+/**
+ * The GIR nicks this story offers, as the C enum members they name. A nick with no member
+ * here is `none`, which is also the property's default (gtkstack.c:1038-1044).
+ */
+const TRANSITIONS: Readonly<Record<string, Gtk.StackTransitionType>> = {
+    none: Gtk.StackTransitionType.NONE,
+    crossfade: Gtk.StackTransitionType.CROSSFADE,
+    'slide-left-right': Gtk.StackTransitionType.SLIDE_LEFT_RIGHT,
+    'slide-up-down': Gtk.StackTransitionType.SLIDE_UP_DOWN,
+    'over-left-right': Gtk.StackTransitionType.OVER_LEFT_RIGHT,
+    'rotate-left-right': Gtk.StackTransitionType.ROTATE_LEFT_RIGHT,
+};
+
+/** Story: a Gtk.Stack of three pages under a Gtk.StackSwitcher. */
+export class StackStory extends StoryWidget {
+    private _stack: Gtk.Stack | null = null;
+    private _switcher: Gtk.StackSwitcher | null = null;
+
+    static {
+        GObject.registerClass({ GTypeName: 'AdwStorybookStack' }, StackStory);
+    }
+
+    constructor() {
+        super(StoryWidget.fromMeta(StackStory.getMetadata(), 'Default'));
+    }
+
+    static getMetadata(): StoryMeta {
+        return { ...stackMeta, component: Gtk.Stack.$gtype };
+    }
+
+    initialize(): void {
+        this._stack = new Gtk.Stack({ vexpand: true, transitionDuration: 200 });
+
+        for (const page of STACK_PAGES) {
+            const label = new Gtk.Label({ label: page.body, vexpand: true });
+            label.add_css_class('title-2');
+            const box = new Gtk.Box({
+                orientation: Gtk.Orientation.VERTICAL,
+                halign: Gtk.Align.CENTER,
+                valign: Gtk.Align.CENTER,
+                spacing: 6,
+            });
+            box.append(new Gtk.Label({ label: page.title, cssClasses: ['title-4'] }));
+            box.append(label);
+            // `add_titled` is the C's own three-argument form (gtkstack.c:1644-1663); the
+            // page's `needs-attention` is set afterwards because it is a page PROPERTY,
+            // not an argument.
+            const info = this._stack.add_titled(box, page.name, page.title);
+            info.needs_attention = page.attn;
+            info.use_underline = true;
+        }
+
+        this._switcher = new Gtk.StackSwitcher({ stack: this._stack, halign: Gtk.Align.CENTER });
+
+        const root = new Gtk.Box({
+            orientation: Gtk.Orientation.VERTICAL,
+            spacing: 12,
+            widthRequest: 480,
+            heightRequest: 320,
+        });
+        root.append(this._switcher);
+        root.append(this._stack);
+
+        this._apply();
+        this.addContent(root);
+    }
+
+    updateArgs(_args: StoryArgs): void {
+        this._apply();
+    }
+
+    private _apply(): void {
+        if (!this._stack) return;
+        // The ORDER is the C's own: `transition-type` FIRST, because a new type is what
+        // `set_visible_child` consults when it resolves a two-way nick through
+        // `get_simple_transition_type` (gtkstack.c:1546-1561).
+        this._stack.transition_type = TRANSITIONS[this.args.transitionType as string] ?? Gtk.StackTransitionType.NONE;
+        this._stack.transition_duration = this.args.transitionDuration as number;
+        this._stack.interpolate_size = this.args.interpolateSize as boolean;
+        this._stack.hhomogeneous = this.args.hhomogeneous as boolean;
+        this._stack.vhomogeneous = this.args.vhomogeneous as boolean;
+    }
+}
+
+GObject.type_ensure(StackStory.$gtype);
+
+export const StackStories: StoryModule = { stories: [StackStory] };

package/src/view-switching/tab-bar.meta.ts

@@ -0,0 +1,22 @@
+// Shared, renderer-agnostic metadata for the Tab Bar story. Imported by both the GTK
+// renderer (tab-bar.story.ts) and the browser renderer
+// (browser/view-switching/tab-bar.web.ts) so the two expose identical controls.
+//
+// The controls are the bar's own five: the three booleans it carries and the two action
+// widgets, which are the only parts of `AdwTabBar` a story can show on its own — everything
+// else is read from the tab view underneath it.
+
+import { ControlType, type StoryMeta } from '@gjsify/stories';
+
+export const tabBarMeta: StoryMeta = {
+    title: 'View Switching/Tab Bar',
+    description:
+        'Adw.TabBar — the tab bar as a widget of its own, bound to an Adw.TabView through its `view`: one chip per page, an action widget on either side, and a strip that can autohide or expand its chips.',
+    controls: [
+        { name: 'autohide', label: 'Autohide', type: ControlType.BOOLEAN, defaultValue: false },
+        { name: 'expandTabs', label: 'Expand tabs', type: ControlType.BOOLEAN, defaultValue: false },
+        { name: 'inverted', label: 'Inverted', type: ControlType.BOOLEAN, defaultValue: false },
+        { name: 'startAction', label: 'Start action', type: ControlType.BOOLEAN, defaultValue: true },
+        { name: 'endAction', label: 'End action', type: ControlType.BOOLEAN, defaultValue: true },
+    ],
+};

package/src/view-switching/tab-bar.story.ts

@@ -0,0 +1,85 @@
+// Adw.TabBar — the tab bar as its own widget, bound to an Adw.TabView through `view`, with
+// a start and an end action widget beside the chips. 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 { tabBarMeta } from './tab-bar.meta.js';
+
+const TABS: ReadonlyArray<{ title: string; body: string }> = [
+    { title: 'Overview', body: 'A summary of everything at a glance.' },
+    { title: 'Details', body: 'The specifics, broken down line by line.' },
+    { title: 'History', body: 'A log of every change made so far.' },
+];
+
+/** Story: an AdwTabBar over an AdwTabView, with the bar's five properties on controls. */
+export class TabBarStory extends StoryWidget {
+    private _bar: Adw.TabBar | null = null;
+    private _startAction: Gtk.Button | null = null;
+    private _endAction: Gtk.Button | null = null;
+
+    static {
+        GObject.registerClass({ GTypeName: 'AdwStorybookTabBar' }, TabBarStory);
+    }
+
+    constructor() {
+        super(StoryWidget.fromMeta(TabBarStory.getMetadata(), 'Default'));
+    }
+
+    static getMetadata(): StoryMeta {
+        return { ...tabBarMeta, component: Adw.TabBar.$gtype };
+    }
+
+    initialize(): void {
+        const view = new Adw.TabView({ vexpand: true });
+        for (const tab of TABS) {
+            const page = view.append(
+                new Adw.StatusPage({ iconName: 'view-paged-symbolic', title: tab.title, description: tab.body }),
+            );
+            page.title = tab.title;
+        }
+
+        // The two action widgets are `GtkWidget`-typed PROPERTIES, so they are widgets of the
+        // caller's rather than children: `AdwTabBar` puts each in an `AdwBin` beside the box.
+        this._startAction = new Gtk.Button({
+            iconName: 'list-add-symbolic',
+            tooltipText: 'New page',
+            cssClasses: ['flat'],
+        });
+        this._endAction = new Gtk.Button({
+            iconName: 'view-more-symbolic',
+            tooltipText: 'Menu',
+            cssClasses: ['flat'],
+        });
+
+        const bar = new Adw.TabBar({ view });
+        this._bar = bar;
+
+        const root = new Gtk.Box({ orientation: Gtk.Orientation.VERTICAL, widthRequest: 480, heightRequest: 320 });
+        root.append(bar);
+        root.append(view);
+        this.addContent(root);
+        this._apply();
+    }
+
+    updateArgs(_args: StoryArgs): void {
+        this._apply();
+    }
+
+    private _apply(): void {
+        const bar = this._bar;
+        if (bar === null) return;
+        bar.autohide = this.args.autohide as boolean;
+        bar.expandTabs = this.args.expandTabs as boolean;
+        bar.inverted = this.args.inverted as boolean;
+        // `null` is how C removes an action widget, and it is what the element's own
+        // `startActionWidget = null` mirrors.
+        bar.startActionWidget = (this.args.startAction as boolean) ? this._startAction : null;
+        bar.endActionWidget = (this.args.endAction as boolean) ? this._endAction : null;
+    }
+}
+
+GObject.type_ensure(TabBarStory.$gtype);
+
+export const TabBarStories: StoryModule = { stories: [TabBarStory] };

package/src/view-switching/tab-button.meta.ts

@@ -0,0 +1,14 @@
+// Shared, renderer-agnostic metadata for the Tab Button story.
+
+import { ControlType, type StoryMeta } from '@gjsify/stories';
+
+export const tabButtonMeta: StoryMeta = {
+    title: 'View Switching/Tab Button',
+    description:
+        'Adw.TabButton — a button that shows how many pages an Adw.TabView holds, and a dot when a page you are ' +
+        'not looking at needs attention. From ten pages the number shrinks; at a hundred it becomes a glyph.',
+    controls: [
+        { name: 'pages', label: 'Pages', type: ControlType.RANGE, min: 0, max: 100, step: 1, defaultValue: 3 },
+        { name: 'needsAttention', label: 'Last page needs attention', type: ControlType.BOOLEAN, defaultValue: false },
+    ],
+};

package/src/view-switching/tab-button.story.ts

@@ -0,0 +1,52 @@
+// Adw.TabButton — the page counter for an Adw.TabView.
+// 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 { tabButtonMeta } from './tab-button.meta.js';
+
+/** Story: an Adw.TabButton bound to a view whose page count the control sets. */
+export class TabButtonStory extends StoryWidget {
+    private _view: Adw.TabView | null = null;
+
+    static {
+        GObject.registerClass({ GTypeName: 'AdwStorybookTabButton' }, TabButtonStory);
+    }
+
+    constructor() {
+        super(StoryWidget.fromMeta(TabButtonStory.getMetadata(), 'Default'));
+    }
+
+    static getMetadata(): StoryMeta {
+        return { ...tabButtonMeta, component: Adw.TabButton.$gtype };
+    }
+
+    initialize(): void {
+        // The view is the counter's data source and is never shown.
+        this._view = new Adw.TabView();
+        const button = new Adw.TabButton({ view: this._view, halign: Gtk.Align.CENTER });
+        this._apply();
+        this.addContent(button);
+    }
+
+    updateArgs(_args: StoryArgs): void {
+        this._apply();
+    }
+
+    private _apply(): void {
+        const view = this._view;
+        if (!view) return;
+        const wanted = this.args.pages as number;
+        while (view.nPages < wanted) view.append(new Gtk.Box()).title = `Page ${view.nPages}`;
+        while (view.nPages > wanted) view.close_page(view.get_nth_page(view.nPages - 1));
+        for (let i = 0; i < view.nPages; i++) {
+            view.get_nth_page(i).needsAttention = (this.args.needsAttention as boolean) && i === view.nPages - 1;
+        }
+    }
+}
+
+GObject.type_ensure(TabButtonStory.$gtype);
+
+export const TabButtonStories: StoryModule = { stories: [TabButtonStory] };

package/src/view-switching/tab-overview.meta.ts

@@ -0,0 +1,21 @@
+// Shared, renderer-agnostic metadata for the Tab Overview story. Imported by both
+// the GTK renderer (tab-overview.story.ts) and the browser renderer
+// (browser/view-switching/tab-overview.web.ts) so the two expose identical controls.
+//
+// The controls are the overview's own booleans, because everything else about it is
+// driven by the tab view underneath: opening it, whether search is available, whether
+// the new-tab button is there and whether the thumbnails run inverted.
+
+import { ControlType, type StoryMeta } from '@gjsify/stories';
+
+export const tabOverviewMeta: StoryMeta = {
+    title: 'View Switching/Tab Overview',
+    description:
+        'Adw.TabOverview — a grid of tab thumbnails over an Adw.TabView; open it to see every page at once, search them and close or unpin them.',
+    controls: [
+        { name: 'open', label: 'Open', type: ControlType.BOOLEAN, defaultValue: true },
+        { name: 'enableSearch', label: 'Enable search', type: ControlType.BOOLEAN, defaultValue: true },
+        { name: 'enableNewTab', label: 'Enable new tab', type: ControlType.BOOLEAN, defaultValue: false },
+        { name: 'inverted', label: 'Inverted', type: ControlType.BOOLEAN, defaultValue: false },
+    ],
+};

package/src/view-switching/tab-overview.story.ts

@@ -0,0 +1,86 @@
+// Adw.TabOverview — a grid of tab thumbnails over an Adw.TabView. 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 { tabOverviewMeta } from './tab-overview.meta.js';
+
+const TABS: ReadonlyArray<{ title: string; body: string }> = [
+    { title: 'Overview', body: 'A summary of everything at a glance.' },
+    { title: 'Details', body: 'The specifics, broken down line by line.' },
+    { title: 'History', body: 'A log of every change made so far.' },
+];
+
+/** Story: Adw.TabOverview over an Adw.TabView with three pages, one of them pinned. */
+export class TabOverviewStory extends StoryWidget {
+    private _overview: Adw.TabOverview | null = null;
+
+    static {
+        GObject.registerClass({ GTypeName: 'AdwStorybookTabOverview' }, TabOverviewStory);
+    }
+
+    constructor() {
+        super(StoryWidget.fromMeta(TabOverviewStory.getMetadata(), 'Default'));
+    }
+
+    static getMetadata(): StoryMeta {
+        return { ...tabOverviewMeta, component: Adw.TabOverview.$gtype };
+    }
+
+    initialize(): void {
+        const view = new Adw.TabView({ vexpand: true });
+        for (const [index, tab] of TABS.entries()) {
+            const status = new Adw.StatusPage({
+                iconName: 'view-paged-symbolic',
+                title: tab.title,
+                description: tab.body,
+                vexpand: true,
+            });
+            const page = view.append(status);
+            page.title = tab.title;
+            // One PINNED page, so the overview has a pinned grid above the ordinary
+            // one — the two-grid arrangement `AdwTabOverview` builds its template with.
+            if (index === 0) view.set_page_pinned(page, true);
+        }
+
+        const overview = new Adw.TabOverview({
+            view,
+            child: view,
+            widthRequest: 480,
+            heightRequest: 340,
+        });
+        this._overview = overview;
+
+        // Without a `create-tab` handler the new-tab button cannot work: C warns
+        // ("AdwTabOverview::create-tab handler must not return NULL") when one is
+        // missing, so the story connects one and the button is usable.
+        overview.connect('create-tab', () => {
+            const page = view.append(
+                new Adw.StatusPage({ iconName: 'view-paged-symbolic', title: 'New Page', vexpand: true }),
+            );
+            page.title = 'New Page';
+            return page;
+        });
+
+        this.addContent(overview);
+        this._apply();
+    }
+
+    updateArgs(_args: StoryArgs): void {
+        this._apply();
+    }
+
+    private _apply(): void {
+        const overview = this._overview;
+        if (!overview) return;
+        overview.enableSearch = this.args.enableSearch as boolean;
+        overview.enableNewTab = this.args.enableNewTab as boolean;
+        overview.inverted = this.args.inverted as boolean;
+        overview.open = this.args.open as boolean;
+    }
+}
+
+GObject.type_ensure(TabOverviewStory.$gtype);
+
+export const TabOverviewStories: StoryModule = { stories: [TabOverviewStory] };

package/src/view-switching/view-switcher-sidebar.meta.ts

@@ -0,0 +1,42 @@
+// Shared, renderer-agnostic metadata for the View Switcher Sidebar story. Imported by
+// both the GTK renderer (view-switcher-sidebar.story.ts) and the browser renderer
+// (browser/view-switching/view-switcher-sidebar.web.ts) so the two expose identical
+// controls.
+//
+// The pages are the story's content, so they live here: both renderers must build the
+// same stack — the same sections, the same badge and the same unread dot — or the two
+// panes are not comparable.
+
+import { ControlType, type StoryMeta } from '@gjsify/stories';
+
+/** One page of the story's stack. */
+export interface ViewSwitcherSidebarPage {
+    name: string;
+    title: string;
+    icon: string;
+    /** Section heading, and a flag only on the page that OPENS it. */
+    sectionTitle?: string;
+    /** `AdwViewStackPage:badge-number`. */
+    badgeNumber?: number;
+    /** `AdwViewStackPage:needs-attention`. */
+    needsAttention?: boolean;
+}
+
+export const VIEW_SWITCHER_SIDEBAR_PAGES: readonly ViewSwitcherSidebarPage[] = [
+    { name: 'inbox', title: 'Inbox', icon: 'mail-unread-symbolic', sectionTitle: 'Mail', badgeNumber: 3 },
+    { name: 'starred', title: 'Starred', icon: 'starred-symbolic' },
+    { name: 'drafts', title: 'Drafts', icon: 'document-edit-symbolic' },
+    // One line per page, deliberately: `check-storybook-category-order` reads every line
+    // that STARTS with `title:` as a story title, and a wrapped page entry puts one
+    // there. `name` first keeps the key off the start of the line.
+    { name: 'sent', title: 'Sent', icon: 'mail-send-symbolic', sectionTitle: 'Older', needsAttention: true },
+    { name: 'archive', title: 'Archive', icon: 'folder-symbolic' },
+    { name: 'trash', title: 'Trash', icon: 'user-trash-symbolic' },
+];
+
+export const viewSwitcherSidebarMeta: StoryMeta = {
+    title: 'View Switching/View Switcher Sidebar',
+    description:
+        'Adw.ViewSwitcherSidebar — an Adw.Sidebar driven by an Adw.ViewStack, which is the one Adw switcher whose rows can be grouped into sections and carry an unread dot or a badge. `page` collapses it into a page of boxed lists.',
+    controls: [{ name: 'mode', label: 'Page mode', type: ControlType.BOOLEAN, defaultValue: false }],
+};

package/src/view-switching/view-switcher-sidebar.story.ts

@@ -0,0 +1,73 @@
+// Adw.ViewSwitcherSidebar — an Adw.Sidebar driven by an Adw.ViewStack, beside the stack
+// it controls. 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 { VIEW_SWITCHER_SIDEBAR_PAGES, viewSwitcherSidebarMeta } from './view-switcher-sidebar.meta.js';
+
+/** Story: an Adw.ViewSwitcherSidebar with two sections over a six-page Adw.ViewStack. */
+export class ViewSwitcherSidebarStory extends StoryWidget {
+    private _switcher: Adw.ViewSwitcherSidebar | null = null;
+
+    static {
+        GObject.registerClass({ GTypeName: 'AdwStorybookViewSwitcherSidebar' }, ViewSwitcherSidebarStory);
+    }
+
+    constructor() {
+        super(StoryWidget.fromMeta(ViewSwitcherSidebarStory.getMetadata(), 'Default'));
+    }
+
+    static getMetadata(): StoryMeta {
+        return { ...viewSwitcherSidebarMeta, component: Adw.ViewSwitcherSidebar.$gtype };
+    }
+
+    initialize(): void {
+        const stack = new Adw.ViewStack({ vexpand: true });
+        for (const spec of VIEW_SWITCHER_SIDEBAR_PAGES) {
+            const content = new Adw.StatusPage({
+                iconName: spec.icon,
+                title: spec.title,
+                vexpand: true,
+            });
+            stack.add_titled(content, spec.name, spec.title);
+        }
+
+        // The page properties come BEFORE the switcher exists: `set_stack` populates the
+        // sidebar once, and the only signals it later follows are the page list's and the
+        // selection's — a section or a badge set afterwards reaches nothing.
+        const pages = stack.get_pages();
+        for (let i = 0; i < pages.get_n_items(); i++) {
+            const page = pages.get_item(i) as Adw.ViewStackPage;
+            const spec = VIEW_SWITCHER_SIDEBAR_PAGES.find((candidate) => candidate.name === page.name);
+            if (!spec?.sectionTitle) continue;
+            page.startsSection = true;
+            page.sectionTitle = spec.sectionTitle;
+            if (spec.badgeNumber) page.badgeNumber = spec.badgeNumber;
+            if (spec.needsAttention) page.needsAttention = true;
+        }
+
+        const switcher = new Adw.ViewSwitcherSidebar({ stack });
+        this._switcher = switcher;
+
+        const box = new Gtk.Box({ orientation: Gtk.Orientation.HORIZONTAL, widthRequest: 480, heightRequest: 340 });
+        box.append(switcher);
+        box.append(stack);
+        this.addContent(box);
+        this._apply();
+    }
+
+    updateArgs(_args: StoryArgs): void {
+        this._apply();
+    }
+
+    private _apply(): void {
+        if (!this._switcher) return;
+        this._switcher.mode = (this.args.mode as boolean) ? Adw.SidebarMode.PAGE : Adw.SidebarMode.SIDEBAR;
+    }
+}
+
+GObject.type_ensure(ViewSwitcherSidebarStory.$gtype);
+
+export const ViewSwitcherSidebarStories: StoryModule = { stories: [ViewSwitcherSidebarStory] };

package/src/windows/action-bar.meta.ts

@@ -0,0 +1,27 @@
+// Shared, renderer-agnostic metadata for the Action Bar story. Imported by the GTK
+// renderer (action-bar.story.ts) and the browser renderer
+// (browser/windows/action-bar.web.ts), so both expose identical controls.
+
+import { ControlType, type StoryMeta } from '@gjsify/stories';
+
+export const actionBarMeta: StoryMeta = {
+    title: 'Windows/Action Bar',
+    description:
+        "Gtk.ActionBar — GTK's bottom bar, and the one libadwaita styles but does not own " +
+        '(`actionbar > revealer > box`). `start` appends and `end` PREPENDS, so the first end ' +
+        'child sits nearest the edge; `center` is a real placement with no property behind it, ' +
+        'because GtkBuilder refuses `center-widget`; and `revealed` slides the whole bar away.',
+    controls: [
+        { name: 'revealed', label: 'Revealed', type: ControlType.BOOLEAN, defaultValue: true },
+        {
+            name: 'center',
+            label: 'Centre',
+            type: ControlType.SELECT,
+            options: [
+                { label: 'A label', value: 'label' },
+                { label: 'Nothing', value: 'none' },
+            ],
+            defaultValue: 'label',
+        },
+    ],
+};

package/src/windows/action-bar.story.ts

@@ -0,0 +1,65 @@
+// Gtk.ActionBar — GTK's bottom bar of packed widgets, with `revealed` and a centre 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 { actionBarMeta } from './action-bar.meta.js';
+
+/** Story: a Gtk.ActionBar with both ends packed and a centre widget driven by args. */
+export class ActionBarStory extends StoryWidget {
+    private _bar: Gtk.ActionBar | null = null;
+    private _centre: Gtk.Label | null = null;
+
+    static {
+        GObject.registerClass({ GTypeName: 'AdwStorybookActionBar' }, ActionBarStory);
+    }
+
+    constructor() {
+        super(StoryWidget.fromMeta(ActionBarStory.getMetadata(), 'Default'));
+    }
+
+    static getMetadata(): StoryMeta {
+        return { ...actionBarMeta, component: Gtk.ActionBar.$gtype };
+    }
+
+    initialize(): void {
+        this._bar = new Gtk.ActionBar();
+
+        // `pack_end` PREPENDS (gtkactionbar.c:262-277), so the button added LAST sits
+        // nearest the edge.
+        const save = new Gtk.Button({ icon_name: 'document-save-symbolic' });
+        save.add_css_class('flat');
+        this._bar.pack_end(save);
+        const open = new Gtk.Button({ icon_name: 'document-open-symbolic' });
+        open.add_css_class('flat');
+        this._bar.pack_end(open);
+        const print = new Gtk.Button({ icon_name: 'document-print-symbolic' });
+        print.add_css_class('flat');
+        this._bar.pack_start(print);
+
+        this._centre = new Gtk.Label({ label: 'notes.md' });
+
+        const column = new Gtk.Box({ orientation: Gtk.Orientation.VERTICAL, spacing: 8 });
+        column.append(new Gtk.Label({ label: 'The bar below is Gtk.ActionBar.', css_classes: ['dimmed'] }));
+        column.append(this._bar);
+        this.addContent(column);
+        this._apply();
+    }
+
+    updateArgs(_args: StoryArgs): void {
+        this._apply();
+    }
+
+    private _apply(): void {
+        if (!this._bar) return;
+        this._bar.revealed = this.args.revealed as boolean;
+        // `gtk_action_bar_set_center_widget` (:306-...) takes a widget or NULL, and NULL
+        // clears the centre rather than replacing it with an empty label.
+        this._bar.set_center_widget((this.args.center as string) === 'label' ? this._centre : null);
+    }
+}
+
+GObject.type_ensure(ActionBarStory.$gtype);
+
+export const ActionBarStories: StoryModule = { stories: [ActionBarStory] };