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

package/src/layout/popover-menu.meta.ts

@@ -0,0 +1,54 @@
+// Shared, renderer-agnostic metadata for the Popover Menu story. Imported by the GTK
+// renderer (popover-menu.story.ts) and the browser renderer
+// (browser/layout/popover-menu.web.ts), so both expose identical controls.
+
+import { ControlType, type StoryMeta } from '@gjsify/stories';
+
+/**
+ * The menu both renderings build: a section with a heading, a plain item and a submenu, so
+ * the page stack and the decoration are both on show. Written as the PORTABLE model
+ * (ADR 0042) — the JSON `<gtk-popover-menu menu-model>` takes and `Gio.Menu` is built from
+ * on the GTK side.
+ */
+export const POPOVER_MENU_ITEMS = [
+    { label: 'New Window', accel: '<Control>N' },
+    { section: [{ label: 'Cut' }, { label: 'Copy' }, { label: 'Paste' }], label: 'Edit' },
+    {
+        label: 'Open With',
+        submenu: [{ label: 'Text Editor' }, { label: 'Web Browser' }, { label: 'Terminal' }],
+    },
+] as const;
+
+export const popoverMenuMeta: StoryMeta = {
+    title: 'Layout/Popover Menu',
+    description:
+        'Gtk.PopoverMenu — a Gtk.Popover whose contents are a menu model instead of a child widget. ' +
+        'A submenu swaps the page of the ONE surface rather than opening a second popup beside it, ' +
+        'which is why the open page is a named one (`visible-submenu`).',
+    controls: [
+        { name: 'menuTitle', label: 'Heading', type: ControlType.TEXT, defaultValue: 'Document' },
+        {
+            name: 'position',
+            label: 'Position',
+            type: ControlType.SELECT,
+            options: [
+                { label: 'Bottom', value: 'bottom' },
+                { label: 'Top', value: 'top' },
+                { label: 'Start', value: 'start' },
+                { label: 'End', value: 'end' },
+            ],
+            defaultValue: 'bottom',
+        },
+        {
+            name: 'align',
+            label: 'Align',
+            type: ControlType.SELECT,
+            options: [
+                { label: 'Start', value: 'start' },
+                { label: 'End', value: 'end' },
+            ],
+            defaultValue: 'start',
+        },
+        { name: 'autohide', label: 'Dismiss on outside click', type: ControlType.BOOLEAN, defaultValue: true },
+    ],
+};

package/src/layout/popover-menu.story.ts

@@ -0,0 +1,119 @@
+// Gtk.PopoverMenu — a Gtk.Popover whose contents are a menu model.
+// 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 { POPOVER_MENU_ITEMS, popoverMenuMeta } from './popover-menu.meta.js';
+
+/**
+ * Story: a Gtk.PopoverMenu over a Gio.Menu with a section, a submenu and accelerators,
+ * anchored to a plain button.
+ *
+ * `GtkPopoverMenu.new_from_model` builds SLIDING submenus by default
+ * (gtkpopovermenu.c:786-799), which is the page-swap this element's replica draws; the
+ * nested form is the `flags` argument of `new_from_model_full` and is left at the default on
+ * purpose, so both renderings show the same shape.
+ */
+/** A detailed action name GIO parses: a label's spaces would make `g_menu_item_set_detailed_action` abort. */
+const actionOf = (label: string): string => `app.${label.toLowerCase().replace(/[^a-z0-9]+/g, '-')}`;
+
+export class PopoverMenuStory extends StoryWidget {
+    private _anchor: Gtk.Button | null = null;
+    private _popover: Gtk.PopoverMenu | null = null;
+
+    static {
+        GObject.registerClass({ GTypeName: 'AdwStorybookPopoverMenu' }, PopoverMenuStory);
+    }
+
+    constructor() {
+        super(StoryWidget.fromMeta(PopoverMenuStory.getMetadata(), 'Default'));
+    }
+
+    static getMetadata(): StoryMeta {
+        return { ...popoverMenuMeta, component: Gtk.PopoverMenu.$gtype };
+    }
+
+    initialize(): void {
+        this._anchor = new Gtk.Button({ label: 'Open menu', halign: Gtk.Align.CENTER });
+        this._apply();
+        this.addContent(this._anchor);
+    }
+
+    updateArgs(_args: StoryArgs): void {
+        this._apply();
+    }
+
+    /**
+     * The portable menu (ADR 0042) as a `Gio.Menu`: a submenu is a `Gio.Menu` appended
+     * under its label, and an accelerator is a display string — nothing here binds a key,
+     * exactly as in GTK, where the binding is `gtk_application_set_accels_for_action`.
+     *
+     * THE HEADING IS THE FIRST SECTION, because `GMenuModel` has no title of its own. The
+     * browser element's `menu-title` is that shorthand, and this is the GTK half of the
+     * same fact: `gtk_popover_menu_open_submenu`'s "main" page is a `GtkStack` of
+     * `GtkMenuSectionBox`es, each of which can carry a label (gtkpopovermenu.c:152-164).
+     */
+    private _buildMenu(title: string): Gio.Menu {
+        const menu = new Gio.Menu();
+        // The items that carry no section of their own, kept aside until the title decides
+        // whether they stand alone or become the heading's group.
+        const loose: string[] = [];
+        for (const entry of POPOVER_MENU_ITEMS) {
+            if ('submenu' in entry) {
+                const submenu = new Gio.Menu();
+                for (const item of entry.submenu) submenu.append(item.label, actionOf(item.label));
+                menu.append_submenu(entry.label, submenu);
+                continue;
+            }
+            if ('section' in entry) {
+                const section = new Gio.Menu();
+                for (const item of entry.section) section.append(item.label, actionOf(item.label));
+                menu.append_section('Edit', section);
+                continue;
+            }
+            loose.push(entry.label);
+        }
+        // A heading IS a labelled section — `GMenuModel` has no title, which is exactly why
+        // the browser element's `menu-title` is a shorthand for one. With no title the
+        // loose items are appended one by one, so the menu reads the same without one.
+        if (title.length > 0) {
+            const section = new Gio.Menu();
+            for (const label of loose) section.append(label, actionOf(label));
+            menu.append_section(title, section);
+        } else {
+            for (const label of loose) menu.append(label, actionOf(label));
+        }
+        return menu;
+    }
+
+    private _apply(): void {
+        if (!this._anchor) return;
+        // Rebuilt rather than mutated: a `Gio.Menu` is immutable to the popover once shown,
+        // and `gtk_popover_menu_set_menu_model` REPLACES the whole stack on every call
+        // (gtkpopovermenu.c:838-852).
+        const previous = this._popover;
+        this._popover = Gtk.PopoverMenu.new_from_model(this._buildMenu(this.args.menuTitle as string));
+        this._popover.set_parent(this._anchor);
+        previous?.unparent();
+        // The four GtkPositionType values, by name, so both renderers read one control.
+        const positions: Record<string, Gtk.PositionType> = {
+            bottom: Gtk.PositionType.BOTTOM,
+            top: Gtk.PositionType.TOP,
+            start: Gtk.PositionType.LEFT,
+            end: Gtk.PositionType.RIGHT,
+        };
+        this._popover.position = positions[this.args.position as string] ?? Gtk.PositionType.BOTTOM;
+        // `GtkPopover` has no align property: alignment is the parent widget's `halign`, which
+        // is why the browser element carries an `align` attribute of its own.
+        if (this._anchor) {
+            this._anchor.halign = (this.args.align as string) === 'end' ? Gtk.Align.END : Gtk.Align.START;
+        }
+        this._popover.autohide = this.args.autohide as boolean;
+    }
+}
+
+GObject.type_ensure(PopoverMenuStory.$gtype);
+
+export const PopoverMenuStories: StoryModule = { stories: [PopoverMenuStory] };

package/src/layout/popover.meta.ts

@@ -0,0 +1,38 @@
+// <gtk-popover> story: the plain content popover. Shared, renderer-agnostic metadata for the
+// GTK renderer (popover.story.ts) and the browser one
+// (browser/layout/popover.web.ts), so both expose identical controls.
+
+import { ControlType, type StoryMeta } from '@gjsify/stories';
+
+export const popoverMeta: StoryMeta = {
+    title: 'Layout/Popover',
+    description:
+        'Gtk.Popover — the bubble-like surface. No model and no menu: it holds whatever widget you ' +
+        'put in it, and everything here is about WHERE it appears and WHEN it goes away. ' +
+        '`autohide` off is entry completion: the list follows the typing and the caret never leaves.',
+    controls: [
+        {
+            name: 'position',
+            label: 'Position',
+            type: ControlType.SELECT,
+            options: [
+                { label: 'Bottom', value: 'bottom' },
+                { label: 'Top', value: 'top' },
+                { label: 'Start', value: 'start' },
+                { label: 'End', value: 'end' },
+            ],
+            defaultValue: 'bottom',
+        },
+        {
+            name: 'align',
+            label: 'Align',
+            type: ControlType.SELECT,
+            options: [
+                { label: 'Start', value: 'start' },
+                { label: 'End', value: 'end' },
+            ],
+            defaultValue: 'start',
+        },
+        { name: 'autohide', label: 'Dismiss on outside click', type: ControlType.BOOLEAN, defaultValue: true },
+    ],
+};

package/src/layout/popover.story.ts

@@ -0,0 +1,66 @@
+// Gtk.Popover — the bubble-like surface, with arbitrary content.
+// 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 { popoverMeta } from './popover.meta.js';
+
+/**
+ * Story: a Gtk.Popover over a button, holding a box of labels.
+ *
+ * `autohide` is the control worth trying: with it off the popover takes no grab
+ * (gtkpopover.c:1245-1247), so an outside click and an Escape stop dismissing it — which is
+ * what an entry's completion list needs.
+ */
+export class PopoverStory extends StoryWidget {
+    private _anchor: Gtk.Button | null = null;
+    private _popover: Gtk.Popover | null = null;
+
+    static {
+        GObject.registerClass({ GTypeName: 'AdwStorybookPopover' }, PopoverStory);
+    }
+
+    constructor() {
+        super(StoryWidget.fromMeta(PopoverStory.getMetadata(), 'Default'));
+    }
+
+    static getMetadata(): StoryMeta {
+        return { ...popoverMeta, component: Gtk.Popover.$gtype };
+    }
+
+    initialize(): void {
+        const box = new Gtk.Box({ orientation: Gtk.Orientation.VERTICAL, spacing: 6 });
+        box.append(new Gtk.Label({ label: 'Anything you like' }));
+        box.append(new Gtk.Label({ label: 'in here' }));
+
+        this._anchor = new Gtk.Button({ label: 'Show popover', halign: Gtk.Align.CENTER });
+        this._popover = new Gtk.Popover({ child: box });
+        this._popover.set_parent(this._anchor);
+        this._apply();
+        this.addContent(this._anchor);
+    }
+
+    updateArgs(_args: StoryArgs): void {
+        this._apply();
+    }
+
+    private _apply(): void {
+        if (!this._popover) return;
+        const positions: Record<string, Gtk.PositionType> = {
+            bottom: Gtk.PositionType.BOTTOM,
+            top: Gtk.PositionType.TOP,
+            start: Gtk.PositionType.LEFT,
+            end: Gtk.PositionType.RIGHT,
+        };
+        this._popover.position = positions[this.args.position as string] ?? Gtk.PositionType.BOTTOM;
+        if (this._anchor) {
+            this._anchor.halign = (this.args.align as string) === 'end' ? Gtk.Align.END : Gtk.Align.START;
+        }
+        this._popover.autohide = this.args.autohide as boolean;
+    }
+}
+
+GObject.type_ensure(PopoverStory.$gtype);
+
+export const PopoverStories: StoryModule = { stories: [PopoverStory] };

package/src/layout/revealer.meta.ts

@@ -0,0 +1,44 @@
+// Shared, renderer-agnostic metadata for the Revealer story. Imported by the GTK renderer
+// (revealer.story.ts) and the browser renderer (browser/layout/revealer.web.ts), so both
+// expose identical controls.
+
+import { ControlType, type StoryMeta } from '@gjsify/stories';
+
+export const revealerMeta: StoryMeta = {
+    title: 'Layout/Revealer',
+    description:
+        'Gtk.Revealer — shows and hides its child with an animation. The transition is one of ' +
+        'fourteen nicks and it is not only an opacity change: a slide scales the box along one ' +
+        'axis while allocating the child at its UNSCALED size, and a swing folds it in with ' +
+        'sin (π · pos / 2). Libadwaita styles no revealer node of its own, so everything here is ' +
+        'GTK behaviour the browser element ports.',
+    controls: [
+        {
+            name: 'transitionType',
+            label: 'Transition',
+            type: ControlType.SELECT,
+            options: [
+                { label: 'Slide down (the default)', value: 'slide-down' },
+                { label: 'Slide up', value: 'slide-up' },
+                { label: 'Slide left', value: 'slide-left' },
+                { label: 'Slide right', value: 'slide-right' },
+                { label: 'Crossfade', value: 'crossfade' },
+                { label: 'Fade + slide down', value: 'fade-slide-down' },
+                { label: 'Swing down (fold)', value: 'swing-down' },
+                { label: 'Swing right (fold)', value: 'swing-right' },
+                { label: 'None', value: 'none' },
+            ],
+            defaultValue: 'slide-down',
+        },
+        {
+            name: 'transitionDuration',
+            label: 'Duration (ms)',
+            type: ControlType.RANGE,
+            min: 0,
+            max: 800,
+            step: 50,
+            defaultValue: 250,
+        },
+        { name: 'revealChild', label: 'Reveal', type: ControlType.BOOLEAN, defaultValue: true },
+    ],
+};

package/src/layout/revealer.story.ts

@@ -0,0 +1,79 @@
+// Gtk.Revealer — one of the fourteen transitions, driven by the shared controls.
+// 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 { revealerMeta } from './revealer.meta.js';
+
+/** The story arg is the transition's GIR nick, which is also what `Gtk.Revealer` takes. */
+const TRANSITIONS: Record<string, Gtk.RevealerTransitionType> = {
+    none: Gtk.RevealerTransitionType.NONE,
+    crossfade: Gtk.RevealerTransitionType.CROSSFADE,
+    'slide-right': Gtk.RevealerTransitionType.SLIDE_RIGHT,
+    'slide-left': Gtk.RevealerTransitionType.SLIDE_LEFT,
+    'slide-up': Gtk.RevealerTransitionType.SLIDE_UP,
+    'slide-down': Gtk.RevealerTransitionType.SLIDE_DOWN,
+    'swing-right': Gtk.RevealerTransitionType.SWING_RIGHT,
+    'swing-left': Gtk.RevealerTransitionType.SWING_LEFT,
+    'swing-up': Gtk.RevealerTransitionType.SWING_UP,
+    'swing-down': Gtk.RevealerTransitionType.SWING_DOWN,
+    'fade-slide-right': Gtk.RevealerTransitionType.FADE_SLIDE_RIGHT,
+    'fade-slide-left': Gtk.RevealerTransitionType.FADE_SLIDE_LEFT,
+    'fade-slide-up': Gtk.RevealerTransitionType.FADE_SLIDE_UP,
+    'fade-slide-down': Gtk.RevealerTransitionType.FADE_SLIDE_DOWN,
+};
+
+/** Story: a Gtk.Revealer over a box, so every transition has room to move. */
+export class RevealerStory extends StoryWidget {
+    private _revealer: Gtk.Revealer | null = null;
+
+    static {
+        GObject.registerClass({ GTypeName: 'AdwStorybookRevealer' }, RevealerStory);
+    }
+
+    constructor() {
+        super(StoryWidget.fromMeta(RevealerStory.getMetadata(), 'Default'));
+    }
+
+    static getMetadata(): StoryMeta {
+        return { ...revealerMeta, component: Gtk.Revealer.$gtype };
+    }
+
+    initialize(): void {
+        const content = new Gtk.Box({
+            orientation: Gtk.Orientation.VERTICAL,
+            spacing: 6,
+            margin_top: 12,
+            margin_bottom: 12,
+            margin_start: 12,
+            margin_end: 12,
+        });
+        content.append(new Gtk.Label({ label: 'The revealed child' }));
+        const hint = new Gtk.Label({ label: 'Drag the controls to change the transition' });
+        hint.add_css_class('dim-label');
+        content.append(hint);
+
+        this._revealer = new Gtk.Revealer();
+        this._revealer.set_child(content);
+        this._apply();
+        this.addContent(this._revealer);
+    }
+
+    updateArgs(_args: StoryArgs): void {
+        this._apply();
+    }
+
+    private _apply(): void {
+        if (!this._revealer) return;
+        // `effective_transition` is not reachable from outside, so the story sets the nick the
+        // property takes and lets GTK mirror it for an RTL direction.
+        this._revealer.transition_type = TRANSITIONS[String(this.args.transitionType)];
+        this._revealer.transition_duration = Number(this.args.transitionDuration);
+        this._revealer.reveal_child = this.args.revealChild as boolean;
+    }
+}
+
+GObject.type_ensure(RevealerStory.$gtype);
+
+export const RevealerStories: StoryModule = { stories: [RevealerStory] };

package/src/layout/scrollbar.meta.ts

@@ -0,0 +1,33 @@
+// Shared, renderer-agnostic metadata for the Scrollbar story. Imported by the GTK renderer
+// (layout/scrollbar.story.ts) and the browser renderer (browser/layout/scrollbar.web.ts), so
+// both expose identical controls.
+
+// THE CONTROL NAMES ARE CAMEL-CASE ARG NAMES, not the adjustment's GIR field spellings: the
+// control panel's reader takes `name` as an identifier
+// (`scripts/check-storybook-control-parity.mjs` reads `\bname:\s*'([A-Za-z0-9_]+)'`), and
+// each renderer writes it into the adjustment whose own field it is.
+
+import { ControlType, type StoryMeta } from '@gjsify/stories';
+
+export const scrollbarMeta: StoryMeta = {
+    title: 'Layout/Scrollbar',
+    description:
+        'Gtk.Scrollbar — a trough and a slider, positioned by a GtkAdjustment. The slider is ' +
+        'page_size over the whole range long and sits at the position over the SCROLLABLE range, ' +
+        'which is why the two numbers it is made of do not share a denominator.',
+    controls: [
+        {
+            name: 'orientation',
+            label: 'Orientation',
+            type: ControlType.SELECT,
+            options: [
+                { label: 'Horizontal', value: 'horizontal' },
+                { label: 'Vertical', value: 'vertical' },
+            ],
+            defaultValue: 'vertical',
+        },
+        { name: 'upper', label: 'Adjustment upper', type: ControlType.NUMBER, defaultValue: 400 },
+        { name: 'pageSize', label: 'Adjustment page size', type: ControlType.NUMBER, defaultValue: 120 },
+        { name: 'value', label: 'Adjustment value', type: ControlType.NUMBER, defaultValue: 80 },
+    ],
+};

package/src/layout/scrollbar.story.ts

@@ -0,0 +1,61 @@
+// Gtk.Scrollbar — one adjustment, drawn as a trough and a slider.
+// 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 { scrollbarMeta } from './scrollbar.meta.js';
+
+/** Story: a Gtk.Scrollbar over one adjustment, with every adjustment field bound to args. */
+export class ScrollbarStory extends StoryWidget {
+    private _scrollbar: Gtk.Scrollbar | null = null;
+
+    static {
+        GObject.registerClass({ GTypeName: 'AdwStorybookScrollbar' }, ScrollbarStory);
+    }
+
+    constructor() {
+        super(StoryWidget.fromMeta(ScrollbarStory.getMetadata(), 'Default'));
+    }
+
+    static getMetadata(): StoryMeta {
+        return { ...scrollbarMeta, component: Gtk.Scrollbar.$gtype };
+    }
+
+    initialize(): void {
+        // `GtkScrollbar` has no adjustment of its own — unlike `GtkRange`, it makes none — so
+        // the construct bag is where one arrives (gtkscrollbar.c:409-420).
+        this._scrollbar = new Gtk.Scrollbar({
+            adjustment: new Gtk.Adjustment({ step_increment: 10, page_increment: 80 }),
+        });
+        this._apply();
+        this.addContent(this._scrollbar);
+    }
+
+    updateArgs(_args: StoryArgs): void {
+        this._apply();
+    }
+
+    private _apply(): void {
+        const scrollbar = this._scrollbar;
+        if (!scrollbar) return;
+        scrollbar.orientation =
+            (this.args.orientation as string) === 'horizontal' ? Gtk.Orientation.HORIZONTAL : Gtk.Orientation.VERTICAL;
+        const adjustment = scrollbar.get_adjustment();
+        if (!adjustment) return;
+        // `configure` is all six at once, "so that the change notifications are compressed into
+        // one" — the GIR's own sentence for the method the C prefers over the setters.
+        adjustment.configure(
+            Number(this.args.value),
+            0,
+            Number(this.args.upper),
+            adjustment.step_increment,
+            adjustment.page_increment,
+            Number(this.args.pageSize),
+        );
+    }
+}
+
+GObject.type_ensure(ScrollbarStory.$gtype);
+
+export const ScrollbarStories: StoryModule = { stories: [ScrollbarStory] };

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

@@ -0,0 +1,57 @@
+// Shared, renderer-agnostic metadata for the Scrolled Window story. Imported by the GTK
+// renderer (layout/scrolled-window.story.ts) and the browser renderer
+// (browser/layout/scrolled-window.web.ts), so both expose identical controls.
+//
+// THE CONTROL NAMES ARE CAMEL-CASE ARG NAMES, not GIR property spellings: the control
+// panel's reader takes `name` as an identifier (`scripts/check-storybook-control-parity.mjs`
+// reads `\bname:\s*'([A-Za-z0-9_]+)'`), and each renderer writes it onto the property
+// whose own name it is — `hscrollbar-policy` here.
+
+import { ControlType, type StoryMeta } from '@gjsify/stories';
+
+export const scrolledWindowMeta: StoryMeta = {
+    title: 'Layout/ScrolledWindow',
+    description:
+        'Gtk.ScrolledWindow — one child, two adjustments, and a scrollbar per edge that can ' +
+        'actually scroll. The policies decide whether a bar appears, window-placement which ' +
+        'edge it takes, and overlay-scrolling turns the bars into the auto-hiding indicators ' +
+        'GNOME draws over the content.',
+    controls: [
+        {
+            name: 'hPolicy',
+            label: 'Horizontal policy',
+            type: ControlType.SELECT,
+            options: [
+                { label: 'Automatic', value: 'automatic' },
+                { label: 'Always', value: 'always' },
+                { label: 'Never', value: 'never' },
+            ],
+            defaultValue: 'automatic',
+        },
+        {
+            name: 'vPolicy',
+            label: 'Vertical policy',
+            type: ControlType.SELECT,
+            options: [
+                { label: 'Automatic', value: 'automatic' },
+                { label: 'Always', value: 'always' },
+                { label: 'Never', value: 'never' },
+            ],
+            defaultValue: 'automatic',
+        },
+        {
+            name: 'placement',
+            label: 'Window placement',
+            type: ControlType.SELECT,
+            options: [
+                { label: 'Top left', value: 'top-left' },
+                { label: 'Top right', value: 'top-right' },
+                { label: 'Bottom left', value: 'bottom-left' },
+                { label: 'Bottom right', value: 'bottom-right' },
+            ],
+            defaultValue: 'top-left',
+        },
+        { name: 'frame', label: 'Frame', type: ControlType.BOOLEAN, defaultValue: false },
+        { name: 'overlayScrolling', label: 'Overlay scrolling', type: ControlType.BOOLEAN, defaultValue: true },
+    ],
+};

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

@@ -0,0 +1,74 @@
+// Gtk.ScrolledWindow — a tall column in a window that scrolls it.
+// 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 { scrolledWindowMeta } from './scrolled-window.meta.js';
+
+/** `GtkPolicyType`'s four nicks as the constants, and `GtkCornerType`'s four. */
+const POLICIES: Record<string, Gtk.PolicyType> = {
+    automatic: Gtk.PolicyType.AUTOMATIC,
+    always: Gtk.PolicyType.ALWAYS,
+    never: Gtk.PolicyType.NEVER,
+};
+const PLACEMENTS: Record<string, Gtk.CornerType> = {
+    'top-left': Gtk.CornerType.TOP_LEFT,
+    'top-right': Gtk.CornerType.TOP_RIGHT,
+    'bottom-left': Gtk.CornerType.BOTTOM_LEFT,
+    'bottom-right': Gtk.CornerType.BOTTOM_RIGHT,
+};
+
+/** Story: a Gtk.ScrolledWindow over a column of labels, with every policy bound to args. */
+export class ScrolledWindowStory extends StoryWidget {
+    private _window: Gtk.ScrolledWindow | null = null;
+
+    static {
+        GObject.registerClass({ GTypeName: 'AdwStorybookScrolledWindow' }, ScrolledWindowStory);
+    }
+
+    constructor() {
+        super(StoryWidget.fromMeta(ScrolledWindowStory.getMetadata(), 'Default'));
+    }
+
+    static getMetadata(): StoryMeta {
+        return { ...scrolledWindowMeta, component: Gtk.ScrolledWindow.$gtype };
+    }
+
+    initialize(): void {
+        const box = new Gtk.Box({ orientation: Gtk.Orientation.VERTICAL, spacing: 8 });
+        for (let i = 1; i <= 16; i++) {
+            box.append(new Gtk.Label({ label: `Row ${i}` }));
+        }
+        this._window = new Gtk.ScrolledWindow({
+            child: box,
+            // An allocation, which is what GTK hands this widget and what makes it scroll
+            // rather than grow: `min_content_height` is one of the two size requests the C
+            // answers with the child's minimum.
+            min_content_height: 240,
+            halign: Gtk.Align.CENTER,
+        });
+        this._apply();
+        this.addContent(this._window);
+    }
+
+    updateArgs(_args: StoryArgs): void {
+        this._apply();
+    }
+
+    private _apply(): void {
+        const window = this._window;
+        if (!window) return;
+        window.set_policy(
+            POLICIES[this.args.hPolicy as string] ?? Gtk.PolicyType.AUTOMATIC,
+            POLICIES[this.args.vPolicy as string] ?? Gtk.PolicyType.AUTOMATIC,
+        );
+        window.set_placement(PLACEMENTS[this.args.placement as string] ?? Gtk.CornerType.TOP_LEFT);
+        window.has_frame = this.args.frame as boolean;
+        window.set_overlay_scrolling(this.args.overlayScrolling as boolean);
+    }
+}
+
+GObject.type_ensure(ScrolledWindowStory.$gtype);
+
+export const ScrolledWindowStories: StoryModule = { stories: [ScrolledWindowStory] };

package/src/layout/separator.meta.ts

@@ -0,0 +1,25 @@
+// Shared, renderer-agnostic metadata for the Separator story. Imported by the GTK
+// renderer (separator.story.ts) and the browser renderer (browser/layout/separator.web.ts),
+// so both expose identical controls.
+
+import { ControlType, type StoryMeta } from '@gjsify/stories';
+
+export const separatorMeta: StoryMeta = {
+    title: 'Layout/Separator',
+    description:
+        'Gtk.Separator — a one-pixel rule between two groups of widgets. Libadwaita ships no Adw.Separator; ' +
+        'it only styles the GTK one, and the .spacer style class turns the rule into an empty 12px gap.',
+    controls: [
+        {
+            name: 'orientation',
+            label: 'Orientation',
+            type: ControlType.SELECT,
+            options: [
+                { label: 'Horizontal', value: 'horizontal' },
+                { label: 'Vertical', value: 'vertical' },
+            ],
+            defaultValue: 'horizontal',
+        },
+        { name: 'spacer', label: 'Spacer (draws nothing)', type: ControlType.BOOLEAN, defaultValue: false },
+    ],
+};