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

package/src/text/search-bar.story.ts

@@ -0,0 +1,48 @@
+// Gtk.SearchBar — the strip that reveals a search entry when search starts.
+// 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 { searchBarMeta } from './search-bar.meta.js';
+
+/** Story: a Gtk.SearchBar over a Gtk.SearchEntry, its two properties bound to args. */
+export class SearchBarStory extends StoryWidget {
+    private _bar: Gtk.SearchBar | null = null;
+    private _entry: Gtk.SearchEntry | null = null;
+
+    static {
+        GObject.registerClass({ GTypeName: 'AdwStorybookSearchBar' }, SearchBarStory);
+    }
+
+    constructor() {
+        super(StoryWidget.fromMeta(SearchBarStory.getMetadata(), 'Default'));
+    }
+
+    static getMetadata(): StoryMeta {
+        return { ...searchBarMeta, component: Gtk.SearchBar.$gtype };
+    }
+
+    initialize(): void {
+        this._entry = new Gtk.SearchEntry({ hexpand: true });
+        this._bar = new Gtk.SearchBar({ child: this._entry });
+        // The entry is the bar's own child here, which is the case `connect_entry` handles
+        // without a call (gtksearchbar.c:611-625).
+        this._apply();
+        this.addContent(this._bar);
+    }
+
+    updateArgs(_args: StoryArgs): void {
+        this._apply();
+    }
+
+    private _apply(): void {
+        if (!this._bar) return;
+        this._bar.search_mode_enabled = this.args.searchModeEnabled as boolean;
+        this._bar.show_close_button = this.args.showCloseButton as boolean;
+    }
+}
+
+GObject.type_ensure(SearchBarStory.$gtype);
+
+export const SearchBarStories: StoryModule = { stories: [SearchBarStory] };

package/src/text/text-view.meta.ts

@@ -0,0 +1,49 @@
+// Shared, renderer-agnostic metadata for the Text View story. Imported by the GTK
+// renderer (text-view.story.ts) and the browser renderer (browser/text/text-view.web.ts),
+// so both expose identical controls.
+
+import { ControlType, type StoryMeta } from '@gjsify/stories';
+
+export const textViewMeta: StoryMeta = {
+    title: 'Text/Text View',
+    description:
+        'Gtk.TextView — the multi-line editor. Its text lives in a Gtk.TextBuffer rather than in a ' +
+        "property, wrap-mode and justification are Pango's, and accepts-tab defaults to TRUE, which is " +
+        "the opposite of a browser's.",
+    controls: [
+        {
+            name: 'text',
+            label: 'Text',
+            type: ControlType.TEXT,
+            defaultValue: 'A text view holds as many lines as it is given.\nTab inserts a tab character.',
+        },
+        {
+            name: 'wrapMode',
+            label: 'Wrap mode',
+            type: ControlType.SELECT,
+            options: [
+                { label: 'None', value: 'none' },
+                { label: 'Char', value: 'char' },
+                { label: 'Word', value: 'word' },
+                { label: 'Word or char', value: 'word-char' },
+            ],
+            defaultValue: 'none',
+        },
+        {
+            name: 'justification',
+            label: 'Justification',
+            type: ControlType.SELECT,
+            options: [
+                { label: 'Left', value: 'left' },
+                { label: 'Right', value: 'right' },
+                { label: 'Center', value: 'center' },
+                { label: 'Fill', value: 'fill' },
+            ],
+            defaultValue: 'left',
+        },
+        { name: 'monospace', label: 'Monospace', type: ControlType.BOOLEAN, defaultValue: false },
+        { name: 'acceptsTab', label: 'Tab inserts a tab', type: ControlType.BOOLEAN, defaultValue: true },
+        { name: 'cursorVisible', label: 'Show cursor', type: ControlType.BOOLEAN, defaultValue: true },
+        { name: 'topMargin', label: 'Top margin', type: ControlType.NUMBER, defaultValue: 6 },
+    ],
+};

package/src/text/text-view.story.ts

@@ -0,0 +1,69 @@
+// Gtk.TextView — the multi-line editor, its Pango layout properties and the buffer's text.
+// 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 { textViewMeta } from './text-view.meta.js';
+
+/** Story: a Gtk.TextView in a scrolled window, its buffer and layout properties bound to args. */
+export class TextViewStory extends StoryWidget {
+    private _buffer: Gtk.TextBuffer | null = null;
+    private _view: Gtk.TextView | null = null;
+
+    static {
+        GObject.registerClass({ GTypeName: 'AdwStorybookTextView' }, TextViewStory);
+    }
+
+    constructor() {
+        super(StoryWidget.fromMeta(TextViewStory.getMetadata(), 'Default'));
+    }
+
+    static getMetadata(): StoryMeta {
+        return { ...textViewMeta, component: Gtk.TextView.$gtype };
+    }
+
+    initialize(): void {
+        // The text is the BUFFER's, not a property of the view's — which is why the browser
+        // element takes its text from its light DOM and why this block is refused a static tree.
+        this._buffer = new Gtk.TextBuffer();
+        this._view = new Gtk.TextView({
+            buffer: this._buffer,
+            hexpand: true,
+            vexpand: false,
+            top_margin: 6,
+        });
+        const scroller = new Gtk.ScrolledWindow({
+            hscrollbar_policy: Gtk.PolicyType.AUTOMATIC,
+            vscrollbar_policy: Gtk.PolicyType.AUTOMATIC,
+            hexpand: true,
+            vexpand: false,
+            child: this._view,
+        });
+        scroller.set_size_request(320, -1);
+        this._apply();
+        this.addContent(scroller);
+    }
+
+    updateArgs(_args: StoryArgs): void {
+        this._apply();
+    }
+
+    private _apply(): void {
+        if (!this._buffer || !this._view) return;
+        const text = this.args.text as string;
+        if (this._buffer.text !== text) {
+            this._buffer.text = text;
+        }
+        this._view.wrap_mode = (this.args.wrapMode ?? 'none') as Gtk.WrapMode;
+        this._view.justification = (this.args.justification ?? 'left') as Gtk.Justification;
+        this._view.monospace = this.args.monospace as boolean;
+        this._view.accepts_tab = this.args.acceptsTab as boolean;
+        this._view.cursor_visible = this.args.cursorVisible as boolean;
+        this._view.top_margin = Number(this.args.topMargin ?? 0);
+    }
+}
+
+GObject.type_ensure(TextViewStory.$gtype);
+
+export const TextViewStories: StoryModule = { stories: [TextViewStory] };

package/src/text/text.meta.ts

@@ -0,0 +1,21 @@
+// Shared, renderer-agnostic metadata for the Text story. Imported by the GTK
+// renderer (text.story.ts) and the browser renderer (browser/text/text.web.ts),
+// so both expose identical controls.
+
+import { ControlType, type StoryMeta } from '@gjsify/stories';
+
+export const textMeta: StoryMeta = {
+    title: 'Text/Text',
+    description:
+        'Gtk.Text — the single-line text widget every Gtk.Entry is built on. Standalone it is a ' +
+        'field with a placeholder and a length limit; visibility=false masks it, propagate-text-width ' +
+        'grows it with its text.',
+    controls: [
+        { name: 'text', label: 'Text', type: ControlType.TEXT, defaultValue: 'Ada Lovelace' },
+        { name: 'placeholderText', label: 'Placeholder', type: ControlType.TEXT, defaultValue: '' },
+        { name: 'editable', label: 'Editable', type: ControlType.BOOLEAN, defaultValue: true },
+        { name: 'visibility', label: 'Visible', type: ControlType.BOOLEAN, defaultValue: true },
+        { name: 'maxLength', label: 'Max length (0 = none)', type: ControlType.NUMBER, defaultValue: 0 },
+        { name: 'propagateTextWidth', label: 'Grow with text', type: ControlType.BOOLEAN, defaultValue: false },
+    ],
+};

package/src/text/text.story.ts

@@ -0,0 +1,50 @@
+// Gtk.Text — the single-line text widget every Gtk.Entry is built on, shown standalone.
+// 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 { textMeta } from './text.meta.js';
+
+/** Story: a Gtk.Text with its text, placeholder, mask, limit and width policy bound to args. */
+export class TextStory extends StoryWidget {
+    private _text: Gtk.Text | null = null;
+
+    static {
+        GObject.registerClass({ GTypeName: 'AdwStorybookText' }, TextStory);
+    }
+
+    constructor() {
+        super(StoryWidget.fromMeta(TextStory.getMetadata(), 'Default'));
+    }
+
+    static getMetadata(): StoryMeta {
+        return { ...textMeta, component: Gtk.Text.$gtype };
+    }
+
+    initialize(): void {
+        this._text = new Gtk.Text({ halign: Gtk.Align.CENTER });
+        this._apply();
+        this.addContent(this._text);
+    }
+
+    updateArgs(_args: StoryArgs): void {
+        this._apply();
+    }
+
+    private _apply(): void {
+        if (!this._text) return;
+        // The two booleans GTK's pspec defaults to TRUE, written through the PROPERTY rather
+        // than a bare attribute, exactly as the element reads them (gtktext.c:1774-1805).
+        this._text.text = this.args.text as string;
+        this._text.placeholder_text = this.args.placeholderText as string;
+        this._text.editable = this.args.editable as boolean;
+        this._text.visibility = this.args.visibility as boolean;
+        this._text.max_length = Number(this.args.maxLength ?? 0);
+        this._text.propagate_text_width = this.args.propagateTextWidth as boolean;
+    }
+}
+
+GObject.type_ensure(TextStory.$gtype);
+
+export const TextStories: StoryModule = { stories: [TextStory] };

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

@@ -0,0 +1,44 @@
+// Shared, renderer-agnostic metadata for the Notebook story. Imported by the GTK
+// renderer (notebook.story.ts) and the browser renderer
+// (browser/view-switching/notebook.web.ts) so the two expose identical controls.
+
+import { ControlType, type StoryMeta } from '@gjsify/stories';
+
+/**
+ * The pages both renderers build. The third carries NO `tab-label` on purpose — that is
+ * the page `gtk_notebook_update_labels` numbers "Page 3" (gtknotebook.c:4353-4373), the
+ * fallback a page gets rather than no tab at all.
+ */
+export const NOTEBOOK_PAGES = [
+    { name: 'overview', label: 'Overview', body: 'A notebook brings its own tab strip.' },
+    { name: 'activity', label: 'Activity', body: 'tab-pos says which edge the strip is on.' },
+    { name: 'notes', label: '', body: 'No tab-label: the tab reads "Page 3".' },
+] as const;
+
+export const notebookMeta: StoryMeta = {
+    title: 'View Switching/Notebook',
+    description:
+        'Gtk.Notebook — the older page container, a stack that brings its own tab bar. `tab-pos` ' +
+        'picks the edge (top, bottom, left, right), `show-tabs` takes the strip away, `show-border` ' +
+        'is the bevel around the pages — a CSS class in C — and `page` is the current page by INDEX ' +
+        'rather than by name. A GtkNotebookPage is a GObject rather than a widget, so its tab-label ' +
+        'and friends live on the page itself, and a page without one gets the number "Page N" as ' +
+        'its tab text. `enable-popup` puts the pages in a right-click menu.',
+    controls: [
+        {
+            name: 'tabPos',
+            label: 'Tab position',
+            type: ControlType.SELECT,
+            options: [
+                { label: 'Top', value: 'top' },
+                { label: 'Bottom', value: 'bottom' },
+                { label: 'Left', value: 'left' },
+                { label: 'Right', value: 'right' },
+            ],
+            defaultValue: 'top',
+        },
+        { name: 'showTabs', label: 'Show tabs', type: ControlType.BOOLEAN, defaultValue: true },
+        { name: 'showBorder', label: 'Show border', type: ControlType.BOOLEAN, defaultValue: true },
+        { name: 'enablePopup', label: 'Enable popup (right-click)', type: ControlType.BOOLEAN, defaultValue: false },
+    ],
+};

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

@@ -0,0 +1,77 @@
+// Gtk.Notebook — the older page container, which brings its own tab bar.
+// 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 { NOTEBOOK_PAGES, notebookMeta } from './notebook.meta.js';
+
+/** The `GtkPositionType` nicks this story offers (gtknotebook.c:1113-1117). */
+const POSITIONS: Readonly<Record<string, Gtk.PositionType>> = {
+    top: Gtk.PositionType.TOP,
+    bottom: Gtk.PositionType.BOTTOM,
+    left: Gtk.PositionType.LEFT,
+    right: Gtk.PositionType.RIGHT,
+};
+
+/** Story: a three-page Gtk.Notebook whose tab strip moves with `tab-pos`. */
+export class NotebookStory extends StoryWidget {
+    private _notebook: Gtk.Notebook | null = null;
+
+    static {
+        GObject.registerClass({ GTypeName: 'AdwStorybookNotebook' }, NotebookStory);
+    }
+
+    constructor() {
+        super(StoryWidget.fromMeta(NotebookStory.getMetadata(), 'Default'));
+    }
+
+    static getMetadata(): StoryMeta {
+        return { ...notebookMeta, component: Gtk.Notebook.$gtype };
+    }
+
+    initialize(): void {
+        this._notebook = new Gtk.Notebook({ vexpand: true, widthRequest: 480, heightRequest: 320 });
+
+        for (const page of NOTEBOOK_PAGES) {
+            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.label || page.name, cssClasses: ['title-4'] }));
+            box.append(new Gtk.Label({ label: page.body, cssClasses: ['title-2'] }));
+
+            // `append_page_menu` rather than `append_page`: a GtkNotebookPage is a GObject
+            // whose tab-label AND menu-label are two properties, and only the `_menu` form
+            // takes both (gtknotebook.c:5871-5884). The third page passes `null` for the
+            // tab label, which is what makes C number it "Page 3" instead of drawing no
+            // tab at all (`gtk_notebook_update_labels`, gtknotebook.c:4353-4373).
+            const label = page.label ? new Gtk.Label({ label: page.label }) : null;
+            const menu = new Gtk.Label({ label: page.label || page.name });
+            this._notebook.append_page_menu(box, label, menu);
+        }
+
+        this._apply();
+        this.addContent(this._notebook);
+    }
+
+    updateArgs(_args: StoryArgs): void {
+        this._apply();
+    }
+
+    private _apply(): void {
+        if (!this._notebook) return;
+        // The ORDER is the C's own: `tab_pos` is read by the layout, so it goes first, and
+        // `show-border` last because it is a style class either way (gtknotebook.c:6134).
+        this._notebook.tab_pos = POSITIONS[this.args.tabPos as string] ?? Gtk.PositionType.TOP;
+        this._notebook.show_tabs = this.args.showTabs as boolean;
+        this._notebook.enable_popup = this.args.enablePopup as boolean;
+        this._notebook.show_border = this.args.showBorder as boolean;
+    }
+}
+
+GObject.type_ensure(NotebookStory.$gtype);
+
+export const NotebookStories: StoryModule = { stories: [NotebookStory] };

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

@@ -0,0 +1,50 @@
+// Shared, renderer-agnostic metadata for the Stack Sidebar story. Imported by the
+// GTK renderer (stack-sidebar.story.ts) and the browser renderer
+// (browser/view-switching/stack-sidebar.web.ts) so the two expose identical controls.
+
+import { ControlType, type StoryMeta } from '@gjsify/stories';
+
+/**
+ * The pages both renderers build. Two carry a title, one carries ONLY an icon — which
+ * is the page the sidebar skips and the switcher shows, the one visible difference
+ * between the two widgets' visibility rules (`update_row`, gtkstacksidebar.c:186,
+ * against `update_button`, gtkstackswitcher.c:200).
+ */
+// ONE LINE PER PAGE, deliberately: `check-storybook-category-order.mjs` reads the
+// categories out of every `^\s*title: '…'` line in a `*.meta.ts`, so a page table
+// formatted one field per line reads as a category named after its first page. The
+// lines are kept under the print width so the formatter does not wrap them back.
+export const STACK_SIDEBAR_PAGES = [
+    { name: 'inbox', title: 'Inbox', icon: 'mail-unread-symbolic', attn: false, body: 'Three unread conversations.' },
+    { name: 'starred', title: 'Starred', icon: 'starred-symbolic', attn: false, body: 'Messages marked important.' },
+    { name: 'drafts', title: 'Drafts', icon: 'document-edit-symbolic', attn: true, body: 'One draft needs attention.' },
+    {
+        name: 'settings',
+        title: '',
+        icon: 'preferences-system-symbolic',
+        attn: false,
+        body: 'No row: a title is the row.',
+    },
+] as const;
+
+export const stackSidebarMeta: StoryMeta = {
+    title: 'View Switching/Stack Sidebar',
+    description:
+        "Gtk.StackSidebar — a vertical list of a Gtk.Stack's pages, the sidebar counterpart of the stack " +
+        "switcher. A row is made of the page's TITLE alone: `update_row` never reads `icon-name`, so the page " +
+        'with only an icon at the end of this story gets no row at all, where the switcher would show an icon ' +
+        'button for it. `needs-attention` puts a dot in front of the label.',
+    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' },
+            ],
+            defaultValue: 'slide-left-right',
+        },
+    ],
+};

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

@@ -0,0 +1,85 @@
+// Gtk.StackSidebar — a list of a Gtk.Stack's pages beside the stack itself.
+// 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_SIDEBAR_PAGES, stackSidebarMeta } from './stack-sidebar.meta.js';
+
+/** The nicks this story offers, as the C enum members they name (gtkstack.c:95-121). */
+const TRANSITIONS: Readonly<Record<string, Gtk.StackTransitionType>> = {
+    none: Gtk.StackTransitionType.NONE,
+    crossfade: Gtk.StackTransitionType.CROSSFADE,
+    'slide-left-right': Gtk.StackTransitionType.SLIDE_LEFT_RIGHT,
+};
+
+/** Story: a four-page Gtk.Stack with a Gtk.StackSidebar down its left-hand side. */
+export class StackSidebarStory extends StoryWidget {
+    private _stack: Gtk.Stack | null = null;
+
+    static {
+        GObject.registerClass({ GTypeName: 'AdwStorybookStackSidebar' }, StackSidebarStory);
+    }
+
+    constructor() {
+        super(StoryWidget.fromMeta(StackSidebarStory.getMetadata(), 'Default'));
+    }
+
+    static getMetadata(): StoryMeta {
+        return { ...stackSidebarMeta, component: Gtk.StackSidebar.$gtype };
+    }
+
+    initialize(): void {
+        this._stack = new Gtk.Stack({ vexpand: true, transitionDuration: 200 });
+
+        for (const page of STACK_SIDEBAR_PAGES) {
+            const label = new Gtk.Label({ label: page.body });
+            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 || page.name, cssClasses: ['title-4'] }));
+            box.append(label);
+
+            // The last page carries an icon and NO title, which is the page a sidebar row
+            // cannot represent: `update_row` reads title, needs-attention and visible, and
+            // never `icon-name` (gtkstacksidebar.c:178-184).
+            const info = this._stack.add_titled(box, page.name, page.title);
+            info.icon_name = page.icon;
+            info.needs_attention = page.attn;
+            info.use_underline = true;
+        }
+
+        const sidebar = new Gtk.StackSidebar({ stack: this._stack });
+
+        // The pane a sidebar belongs in, which is where GTK puts one too.
+        const pane = new Gtk.Box({ orientation: Gtk.Orientation.VERTICAL, spacing: 0 });
+        pane.append(sidebar);
+
+        const root = new Gtk.Paned({ orientation: Gtk.Orientation.HORIZONTAL, widthRequest: 480, heightRequest: 320 });
+        root.set_start_child(pane);
+        root.set_end_child(this._stack);
+        root.set_position(180);
+
+        this._apply();
+        this.addContent(root);
+    }
+
+    updateArgs(_args: StoryArgs): void {
+        this._apply();
+    }
+
+    private _apply(): void {
+        if (!this._stack) return;
+        // `transition-type` FIRST: a new type is what `set_visible_child` consults when
+        // it resolves a two-way nick (gtkstack.c:1546-1561).
+        this._stack.transition_type = TRANSITIONS[this.args.transitionType as string] ?? Gtk.StackTransitionType.NONE;
+    }
+}
+
+GObject.type_ensure(StackSidebarStory.$gtype);
+
+export const StackSidebarStories: StoryModule = { stories: [StackSidebarStory] };

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

@@ -0,0 +1,53 @@
+// Shared, renderer-agnostic metadata for the Stack Switcher story. Imported by the
+// GTK renderer (stack-switcher.story.ts) and the browser renderer
+// (browser/view-switching/stack-switcher.web.ts) so the two expose identical controls.
+
+import { ControlType, type StoryMeta } from '@gjsify/stories';
+
+/**
+ * The pages both renderers build. `icon` is empty for a text-only page and
+ * `attn` marks the page `needs-attention`, which is what the switcher draws a dot
+ * for — both are the `rebuild_child` / `update_button` branches of the widget.
+ */
+// ONE LINE PER PAGE, deliberately: `check-storybook-category-order.mjs` reads the
+// categories out of every `^\s*title: '…'` line in a `*.meta.ts`, so a page table
+// formatted one field per line reads as a category named after its first page. The
+// lines are kept under the print width so the formatter does not wrap them back.
+export const STACK_SWITCHER_PAGES = [
+    { name: 'inbox', title: 'Inbox', icon: 'mail-unread-symbolic', attn: false, body: 'Three unread conversations.' },
+    { name: 'starred', title: 'Starred', icon: 'starred-symbolic', attn: false, body: 'Messages marked important.' },
+    { name: 'archive', title: 'Archive', icon: '', attn: false, body: 'Older conversations kept for reference.' },
+    { name: 'drafts', title: '', icon: 'document-edit-symbolic', attn: true, body: 'One draft needs your attention.' },
+] as const;
+
+export const stackSwitcherMeta: StoryMeta = {
+    title: 'View Switching/Stack Switcher',
+    description:
+        'Gtk.StackSwitcher — a linked row of toggle buttons, one per page of a Gtk.Stack. A page with a title ' +
+        'and no icon gets a label button; one with an icon and no title gets an icon button and puts the title on ' +
+        'the switcher as a tooltip; a page with NEITHER is left out of the row entirely. `orientation` turns the ' +
+        'row vertical, and `needs-attention` on a page puts a dot on its button.',
+    controls: [
+        {
+            name: 'orientation',
+            label: 'Orientation',
+            type: ControlType.SELECT,
+            options: [
+                { label: 'Horizontal', value: 'horizontal' },
+                { label: 'Vertical', value: 'vertical' },
+            ],
+            defaultValue: 'horizontal',
+        },
+        {
+            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' },
+            ],
+            defaultValue: 'slide-left-right',
+        },
+    ],
+};

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

@@ -0,0 +1,95 @@
+// Gtk.StackSwitcher — a linked row of toggle buttons switching over a Gtk.Stack.
+// 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_SWITCHER_PAGES, stackSwitcherMeta } from './stack-switcher.meta.js';
+
+/** The nicks this story offers, as the C enum members they name (gtkstack.c:95-121). */
+const TRANSITIONS: Readonly<Record<string, Gtk.StackTransitionType>> = {
+    none: Gtk.StackTransitionType.NONE,
+    crossfade: Gtk.StackTransitionType.CROSSFADE,
+    'slide-left-right': Gtk.StackTransitionType.SLIDE_LEFT_RIGHT,
+};
+
+/** Story: a four-page Gtk.Stack under a Gtk.StackSwitcher, covering both button shapes. */
+export class StackSwitcherStory extends StoryWidget {
+    private _stack: Gtk.Stack | null = null;
+    private _switcher: Gtk.StackSwitcher | null = null;
+
+    static {
+        GObject.registerClass({ GTypeName: 'AdwStorybookStackSwitcher' }, StackSwitcherStory);
+    }
+
+    constructor() {
+        super(StoryWidget.fromMeta(StackSwitcherStory.getMetadata(), 'Default'));
+    }
+
+    static getMetadata(): StoryMeta {
+        return { ...stackSwitcherMeta, component: Gtk.StackSwitcher.$gtype };
+    }
+
+    initialize(): void {
+        this._stack = new Gtk.Stack({ vexpand: true, transitionDuration: 200 });
+
+        for (const page of STACK_SWITCHER_PAGES) {
+            const label = new Gtk.Label({ label: page.body });
+            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 || page.name, cssClasses: ['title-4'] }));
+            box.append(label);
+
+            // The four shapes `rebuild_child` and `update_row` branch on
+            // (gtkstackswitcher.c:137-207): title + icon, title only, icon only, and
+            // the last page with `needs-attention`.
+            if (page.icon) {
+                const info = this._stack.add_titled(box, page.name, page.title);
+                info.icon_name = page.icon;
+                info.needs_attention = page.attn;
+                info.use_underline = true;
+            } else {
+                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 || !this._switcher) return;
+        // `transition-type` FIRST: a new type is what `set_visible_child` consults when
+        // it resolves a two-way nick (gtkstack.c:1546-1561).
+        this._stack.transition_type = TRANSITIONS[this.args.transitionType as string] ?? Gtk.StackTransitionType.NONE;
+        // `GtkStackSwitcher` is a GtkOrientable (gtkstackswitcher.c:47).
+        this._switcher.orientation =
+            (this.args.orientation as string) === 'vertical' ? Gtk.Orientation.VERTICAL : Gtk.Orientation.HORIZONTAL;
+    }
+}
+
+GObject.type_ensure(StackSwitcherStory.$gtype);
+
+export const StackSwitcherStories: StoryModule = { stories: [StackSwitcherStory] };