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

package/src/layout/grid.meta.ts

@@ -0,0 +1,45 @@
+// Shared, renderer-agnostic metadata for the Grid story. Imported by the GTK
+// renderer (grid.story.ts) and the browser renderer (browser/layout/grid.web.ts),
+// so both expose identical controls.
+
+import { ControlType, type StoryMeta } from '@gjsify/stories';
+
+export const gridMeta: StoryMeta = {
+    title: 'Layout/Grid',
+    description:
+        'Gtk.Grid — a table of cells sized by what is in them, filled row by row. The two spacings are the ' +
+        'gap between lines, the two homogeneous flags make every line the same, and a vertical grid attaches ' +
+        'down the rows instead of across the columns.',
+    controls: [
+        {
+            name: 'columnSpacing',
+            label: 'Column spacing',
+            type: ControlType.RANGE,
+            min: 0,
+            max: 36,
+            step: 2,
+            defaultValue: 12,
+        },
+        {
+            name: 'rowSpacing',
+            label: 'Row spacing',
+            type: ControlType.RANGE,
+            min: 0,
+            max: 36,
+            step: 2,
+            defaultValue: 12,
+        },
+        { name: 'columnHomogeneous', label: 'Column homogeneous', type: ControlType.BOOLEAN, defaultValue: false },
+        { name: 'rowHomogeneous', label: 'Row homogeneous', type: ControlType.BOOLEAN, defaultValue: false },
+        {
+            name: 'orientation',
+            label: 'Orientation',
+            type: ControlType.SELECT,
+            options: [
+                { label: 'Horizontal', value: 'horizontal' },
+                { label: 'Vertical', value: 'vertical' },
+            ],
+            defaultValue: 'horizontal',
+        },
+    ],
+};

package/src/layout/grid.story.ts

@@ -0,0 +1,80 @@
+// Gtk.Grid — a table of cells filled row by row.
+// 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 { gridMeta } from './grid.meta.js';
+
+/** Story: a Gtk.Grid of four labels with its spacings, homogeneity and orientation bound to args. */
+export class GridStory extends StoryWidget {
+    private _grid: Gtk.Grid | null = null;
+    private _cells: Gtk.Label[] = [];
+    private _orientation: Gtk.Orientation | null = null;
+
+    static {
+        GObject.registerClass({ GTypeName: 'AdwStorybookGrid' }, GridStory);
+    }
+
+    constructor() {
+        super(StoryWidget.fromMeta(GridStory.getMetadata(), 'Default'));
+    }
+
+    static getMetadata(): StoryMeta {
+        return { ...gridMeta, component: Gtk.Grid.$gtype };
+    }
+
+    initialize(): void {
+        this._grid = new Gtk.Grid({
+            hexpand: true,
+            margin_top: 12,
+            margin_bottom: 12,
+            margin_start: 12,
+            margin_end: 12,
+        });
+        for (const text of ['Name', 'Value', 'Unit', 'editable']) {
+            const cell = new Gtk.Label({ label: text, hexpand: true });
+            cell.set_margin_top(6);
+            cell.set_margin_bottom(6);
+            cell.set_margin_start(6);
+            cell.set_margin_end(6);
+            this._cells.push(cell);
+        }
+        this._attach();
+        this._apply();
+        this.addContent(this._grid);
+    }
+
+    updateArgs(_args: StoryArgs): void {
+        this._apply();
+    }
+
+    /** `attach(child, -1, -1, 1, 1)` — what `Gtk.Builder` writes for a child with no position. */
+    private _attach(): void {
+        if (!this._grid) return;
+        for (const cell of this._cells) this._grid.attach(cell, -1, -1, 1, 1);
+    }
+
+    private _apply(): void {
+        if (!this._grid) return;
+        const orientation =
+            (this.args.orientation as string) === 'vertical' ? Gtk.Orientation.VERTICAL : Gtk.Orientation.HORIZONTAL;
+        this._grid.columnSpacing = this.args.columnSpacing as number;
+        this._grid.rowSpacing = this.args.rowSpacing as number;
+        this._grid.columnHomogeneous = this.args.columnHomogeneous as boolean;
+        this._grid.rowHomogeneous = this.args.rowHomogeneous as boolean;
+        // A child is attached along the ORIENTATION at the moment it is added
+        // (gtkgrid.c:493-507), so turning a filled grid around is re-attaching — which is
+        // exactly what the browser renderer's `grid-auto-flow` change does for free.
+        if (this._orientation !== null && this._orientation !== orientation) {
+            for (const cell of this._cells) this._grid.remove(cell);
+            this._attach();
+        }
+        this._grid.orientation = orientation;
+        this._orientation = orientation;
+    }
+}
+
+GObject.type_ensure(GridStory.$gtype);
+
+export const GridStories: StoryModule = { stories: [GridStory] };

package/src/layout/layout-slot.meta.ts

@@ -0,0 +1,22 @@
+// Shared, renderer-agnostic metadata for the Layout Slot story. Imported by the GTK
+// renderer (layout-slot.story.ts) and the browser renderer
+// (browser/layout/layout-slot.web.ts), so both expose identical controls.
+
+import { ControlType, type StoryMeta } from '@gjsify/stories';
+
+export const layoutSlotMeta: StoryMeta = {
+    title: 'Layout/Layout Slot',
+    description:
+        'Adw.LayoutSlot is the named hole a layout of an Adw.MultiLayoutView leaves for a ' +
+        'child: it takes the child whose id matches, and its visible property follows that ' +
+        "child's. On its own it is a bin, which is what this story shows.",
+    controls: [
+        { name: 'label', label: 'Child title', type: ControlType.TEXT, defaultValue: 'Inbox' },
+        {
+            name: 'visible',
+            label: 'Child visible',
+            type: ControlType.BOOLEAN,
+            defaultValue: true,
+        },
+    ],
+};

package/src/layout/layout-slot.story.ts

@@ -0,0 +1,68 @@
+// Adw.LayoutSlot — the named hole a layout of an Adw.MultiLayoutView leaves for a child.
+// 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 { layoutSlotMeta } from './layout-slot.meta.js';
+
+/**
+ * Story: one slot holding one child.
+ *
+ * A slot only ever exists inside a layout, and a layout only ever exists inside a
+ * multi-layout view — the view is what inserts the child whose id matches the slot's. So
+ * this story builds the whole pair and names the SLOT, which is the half a reader cannot
+ * see anywhere else: the `visible` binding the view installs between the two
+ * (adw-multi-layout-view.c:151).
+ */
+export class LayoutSlotStory extends StoryWidget {
+    private _view: Adw.MultiLayoutView | null = null;
+    private _slot: Adw.LayoutSlot | null = null;
+    private _child: Adw.NavigationPage | null = null;
+
+    static {
+        GObject.registerClass({ GTypeName: 'AdwStorybookLayoutSlot' }, LayoutSlotStory);
+    }
+
+    constructor() {
+        super(StoryWidget.fromMeta(LayoutSlotStory.getMetadata(), 'Default'));
+    }
+
+    static getMetadata(): StoryMeta {
+        return { ...layoutSlotMeta, component: Adw.LayoutSlot.$gtype };
+    }
+
+    initialize(): void {
+        this._slot = Adw.LayoutSlot.new('primary');
+        this._child = new Adw.NavigationPage({
+            title: this.args.label as string,
+            tag: 'primary',
+            child: new Gtk.Label({ label: 'The child the view inserted here.' }),
+        });
+
+        this._view = new Adw.MultiLayoutView();
+        const layout = Adw.Layout.new(this._slot);
+        layout.name = 'only';
+        this._view.add_layout(layout);
+        this._view.set_child('primary', this._child);
+
+        this._apply();
+        this.addContent(this._view);
+    }
+
+    updateArgs(_args: StoryArgs): void {
+        this._apply();
+    }
+
+    private _apply(): void {
+        if (!this._child) return;
+        this._child.title = this.args.label as string;
+        // The binding is child → slot, one way: the slot cannot show what the child hides.
+        this._child.visible = this.args.visible as boolean;
+    }
+}
+
+GObject.type_ensure(LayoutSlotStory.$gtype);
+
+export const LayoutSlotStories: StoryModule = { stories: [LayoutSlotStory] };

package/src/layout/multi-layout-view.meta.ts

@@ -0,0 +1,31 @@
+// Shared, renderer-agnostic metadata for the Multi Layout View story. Imported by the GTK
+// renderer (multi-layout-view.story.ts) and the browser renderer
+// (browser/layout/multi-layout-view.web.ts), so both expose identical controls.
+
+import { ControlType, type StoryMeta } from '@gjsify/stories';
+
+export const multiLayoutViewMeta: StoryMeta = {
+    title: 'Layout/Multi Layout View',
+    description:
+        'Adw.MultiLayoutView holds one set of children and several arrangements of them: each ' +
+        'child has an id, each layout has slots with ids, and switching layouts re-inserts ' +
+        'every child into the slot of the SAME id.',
+    controls: [
+        {
+            name: 'layoutName',
+            label: 'Layout',
+            type: ControlType.SELECT,
+            options: [
+                { label: 'wide (split)', value: 'wide' },
+                { label: 'narrow (stacked)', value: 'narrow' },
+            ],
+            defaultValue: 'wide',
+        },
+        {
+            name: 'showDetails',
+            label: 'Show the details pane',
+            type: ControlType.BOOLEAN,
+            defaultValue: true,
+        },
+    ],
+};

package/src/layout/multi-layout-view.story.ts

@@ -0,0 +1,101 @@
+// Adw.MultiLayoutView — one set of children, two arrangements of them.
+// 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 { multiLayoutViewMeta } from './multi-layout-view.meta.js';
+
+/** The two ids every layout here carries: the content, and the secondary pane. */
+const PRIMARY = 'primary';
+const SECONDARY = 'secondary';
+
+/** A short list, so the two children are visibly different once they move. */
+function page(rows: readonly (readonly [string, string])[]): Gtk.ListBox {
+    const list = new Gtk.ListBox({ selectionMode: Gtk.SelectionMode.NONE });
+    for (const [name, detail] of rows) list.append(new Adw.ActionRow({ title: name, subtitle: detail }));
+    return list;
+}
+
+/** A split-view pane that holds nothing but a slot, so the child lands by id. */
+function slotPage(id: string): Adw.NavigationPage {
+    return new Adw.NavigationPage({ title: id, child: Adw.LayoutSlot.new(id), tag: id });
+}
+
+/**
+ * One arrangement: a split view whose two panes are SLOTS, so the children land by id.
+ *
+ * `collapsed` is what makes the second arrangement different — and it is the same pair of
+ * children either way, which is the whole point of the widget.
+ */
+function arrangement(collapsed: boolean): Adw.NavigationSplitView {
+    const view = new Adw.NavigationSplitView({ collapsed, minSidebarWidth: 160 });
+    view.sidebar = slotPage(SECONDARY);
+    view.content = slotPage(PRIMARY);
+    view.set_size_request(420, 220);
+    return view;
+}
+
+/** Story: the same two pages docked, then the same two pages stacked. */
+export class MultiLayoutViewStory extends StoryWidget {
+    private _view: Adw.MultiLayoutView | null = null;
+    private _details: Gtk.Widget | null = null;
+
+    static {
+        GObject.registerClass({ GTypeName: 'AdwStorybookMultiLayoutView' }, MultiLayoutViewStory);
+    }
+
+    constructor() {
+        super(StoryWidget.fromMeta(MultiLayoutViewStory.getMetadata(), 'Default'));
+    }
+
+    static getMetadata(): StoryMeta {
+        return { ...multiLayoutViewMeta, component: Adw.MultiLayoutView.$gtype };
+    }
+
+    initialize(): void {
+        this._details = page([
+            ['From', 'Adwaita List'],
+            ['Subject', 'Resizing the window'],
+        ]);
+        this._view = new Adw.MultiLayoutView();
+        // `add_layout` makes the FIRST layout current (adw-multi-layout-view.c:553), so the
+        // wide one goes in first; the name is set before the second is added, because
+        // `add_layout` warns on a duplicate and reads the name to do it.
+        const wide = Adw.Layout.new(arrangement(false));
+        wide.name = 'wide';
+        this._view.add_layout(wide);
+        const narrow = Adw.Layout.new(arrangement(true));
+        narrow.name = 'narrow';
+        this._view.add_layout(narrow);
+
+        this._view.set_child(
+            PRIMARY,
+            page([
+                ['General', '12 unread'],
+                ['Starred', '3 threads'],
+            ]),
+        );
+        this._view.set_child(SECONDARY, this._details);
+
+        this._apply();
+        this.addContent(this._view);
+    }
+
+    updateArgs(_args: StoryArgs): void {
+        this._apply();
+    }
+
+    private _apply(): void {
+        if (!this._view || !this._details) return;
+        // `visible` is bound one way, child to slot, so hiding the CHILD is what takes the
+        // hole with it.
+        this._details.visible = this.args.showDetails as boolean;
+        this._view.layout_name = this.args.layoutName as string;
+    }
+}
+
+GObject.type_ensure(MultiLayoutViewStory.$gtype);
+
+export const MultiLayoutViewStories: StoryModule = { stories: [MultiLayoutViewStory] };

package/src/layout/overlay.meta.ts

@@ -0,0 +1,42 @@
+// Shared, renderer-agnostic metadata for the Overlay story. Imported by the GTK renderer
+// (overlay.story.ts) and the browser renderer (browser/layout/overlay.web.ts), so both
+// expose identical controls.
+
+import { ControlType, type StoryMeta } from '@gjsify/stories';
+
+export const overlayMeta: StoryMeta = {
+    title: 'Layout/Overlay',
+    description:
+        'Gtk.Overlay — widgets stacked on top of one main child. The main child sizes the overlay; ' +
+        'every other child is placed by its own halign/valign, which is what ' +
+        'gtk_overlay_get_child_position reads and nothing else. Libadwaita ships no Adw.Overlay ' +
+        'and gives the node no rule of its own — the .left/.right/.top/.bottom classes it puts on ' +
+        'an edge-aligned child are the whole published contract.',
+    controls: [
+        {
+            name: 'halign',
+            label: 'Overlay halign',
+            type: ControlType.SELECT,
+            options: [
+                { label: 'Fill (the default)', value: 'fill' },
+                { label: 'Start', value: 'start' },
+                { label: 'Center', value: 'center' },
+                { label: 'End', value: 'end' },
+            ],
+            defaultValue: 'end',
+        },
+        {
+            name: 'valign',
+            label: 'Overlay valign',
+            type: ControlType.SELECT,
+            options: [
+                { label: 'Fill (the default)', value: 'fill' },
+                { label: 'Start', value: 'start' },
+                { label: 'Center', value: 'center' },
+                { label: 'End', value: 'end' },
+            ],
+            defaultValue: 'end',
+        },
+        { name: 'showLabel', label: 'Label the overlay', type: ControlType.BOOLEAN, defaultValue: true },
+    ],
+};

package/src/layout/overlay.story.ts

@@ -0,0 +1,72 @@
+// Gtk.Overlay — a card with a badge pinned to its bottom end corner.
+// 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 { overlayMeta } from './overlay.meta.js';
+
+/** `Gtk.Align` for a story arg — `fill` is the DEFAULT and has no `Gtk.Align` member. */
+const ALIGNMENTS: Record<string, Gtk.Align> = {
+    start: Gtk.Align.START,
+    center: Gtk.Align.CENTER,
+    end: Gtk.Align.END,
+};
+
+/** Story: a Gtk.Overlay whose main child is a frame, with a badge over one of its corners. */
+export class OverlayStory extends StoryWidget {
+    private _overlay: Gtk.Overlay | null = null;
+    private _main: Gtk.Frame | null = null;
+    private _badge: Gtk.Box | null = null;
+
+    static {
+        GObject.registerClass({ GTypeName: 'AdwStorybookOverlay' }, OverlayStory);
+    }
+
+    constructor() {
+        super(StoryWidget.fromMeta(OverlayStory.getMetadata(), 'Default'));
+    }
+
+    static getMetadata(): StoryMeta {
+        return { ...overlayMeta, component: Gtk.Overlay.$gtype };
+    }
+
+    initialize(): void {
+        this._main = new Gtk.Frame({ width_request: 260, height_request: 160, margin_top: 12, margin_bottom: 12 });
+        const mainText = new Gtk.Label({ label: 'Main child — its size is the overlay' });
+        mainText.add_css_class('dim-label');
+        this._main.set_child(mainText);
+
+        this._badge = new Gtk.Box({ valign: Gtk.Align.END, halign: Gtk.Align.END });
+        this._badge.set_css_classes(['osd', 'flat']);
+        this._badge.append(new Gtk.Label({ label: '2' }));
+
+        this._overlay = new Gtk.Overlay();
+        this._overlay.set_child(this._main);
+        this._overlay.add_overlay(this._badge);
+        this._apply();
+        this.addContent(this._overlay);
+    }
+
+    updateArgs(_args: StoryArgs): void {
+        this._apply();
+    }
+
+    private _apply(): void {
+        if (!this._badge) return;
+        // `fill` is `GtkWidget`'s DEFAULT alignment and has no `Gtk.Align` member, so it is
+        // spelled as an absent property — the same choice the web element reads as "no
+        // halign attribute".
+        const halign = ALIGNMENTS[String(this.args.halign)];
+        const valign = ALIGNMENTS[String(this.args.valign)];
+        if (halign === undefined) this._badge.halign = Gtk.Align.FILL;
+        else this._badge.halign = halign;
+        if (valign === undefined) this._badge.valign = Gtk.Align.FILL;
+        else this._badge.valign = valign;
+        this._badge.visible = this.args.showLabel as boolean;
+    }
+}
+
+GObject.type_ensure(OverlayStory.$gtype);
+
+export const OverlayStories: StoryModule = { stories: [OverlayStory] };

package/src/layout/paned.meta.ts

@@ -0,0 +1,45 @@
+// Shared, renderer-agnostic metadata for the Paned story. Imported by the GTK renderer
+// (paned.story.ts) and the browser renderer (browser/layout/paned.web.ts), so both expose
+// identical controls.
+
+import { ControlType, type StoryMeta } from '@gjsify/stories';
+
+export const panedMeta: StoryMeta = {
+    title: 'Layout/Paned',
+    description:
+        'Gtk.Paned — two children either side of a divider the user drags. With both children ' +
+        'resizable and no position set, GTK divides the paned in PROPORTION TO THE TWO SIZE ' +
+        'REQUESTS rather than in half, and it draws the divider as the `separator` node a ' +
+        'GtkPanedHandle carries. Libadwaita styles that node in _paned.scss: 1px, 5px when ' +
+        '`wide-handle`, with the rule as an inset shadow rather than a fill.',
+    controls: [
+        {
+            name: 'orientation',
+            label: 'Orientation',
+            type: ControlType.SELECT,
+            options: [
+                { label: 'Horizontal', value: 'horizontal' },
+                { label: 'Vertical', value: 'vertical' },
+            ],
+            defaultValue: 'horizontal',
+        },
+        { name: 'wideHandle', label: 'Wide handle', type: ControlType.BOOLEAN, defaultValue: false },
+        { name: 'resizeStartChild', label: 'Resize the first child', type: ControlType.BOOLEAN, defaultValue: true },
+        { name: 'resizeEndChild', label: 'Resize the second child', type: ControlType.BOOLEAN, defaultValue: true },
+        {
+            name: 'shrinkStartChild',
+            label: 'The first child may shrink',
+            type: ControlType.BOOLEAN,
+            defaultValue: true,
+        },
+        {
+            name: 'position',
+            label: 'Position (0 = derive)',
+            type: ControlType.NUMBER,
+            min: -1,
+            max: 400,
+            step: 1,
+            defaultValue: -1,
+        },
+    ],
+};

package/src/layout/paned.story.ts

@@ -0,0 +1,70 @@
+// Gtk.Paned — a draggable divider between two boxes.
+// 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 { panedMeta } from './paned.meta.js';
+
+function pane(label: string, request: number): Gtk.Box {
+    const box = new Gtk.Box({
+        orientation: Gtk.Orientation.VERTICAL,
+        spacing: 4,
+        margin_top: 12,
+        margin_bottom: 12,
+        margin_start: 12,
+        margin_end: 12,
+    });
+    box.append(new Gtk.Label({ label }));
+    const hint = new Gtk.Label({ label: `${request}px of size request` });
+    hint.add_css_class('dim-label');
+    box.append(hint);
+    return box;
+}
+
+/** Story: a Gtk.Paned whose panes have visibly different requests, so the split is legible. */
+export class PanedStory extends StoryWidget {
+    private _paned: Gtk.Paned | null = null;
+
+    static {
+        GObject.registerClass({ GTypeName: 'AdwStorybookPaned' }, PanedStory);
+    }
+
+    constructor() {
+        super(StoryWidget.fromMeta(PanedStory.getMetadata(), 'Default'));
+    }
+
+    static getMetadata(): StoryMeta {
+        return { ...panedMeta, component: Gtk.Paned.$gtype };
+    }
+
+    initialize(): void {
+        this._paned = new Gtk.Paned({ orientation: Gtk.Orientation.HORIZONTAL });
+        this._paned.set_start_child(pane('First child', 100));
+        this._paned.set_end_child(pane('Second child', 300));
+        this._paned.set_size_request(400, 140);
+        this._apply();
+        this.addContent(this._paned);
+    }
+
+    updateArgs(_args: StoryArgs): void {
+        this._apply();
+    }
+
+    private _apply(): void {
+        if (!this._paned) return;
+        this._paned.orientation =
+            this.args.orientation === 'vertical' ? Gtk.Orientation.VERTICAL : Gtk.Orientation.HORIZONTAL;
+        this._paned.wide_handle = this.args.wideHandle as boolean;
+        this._paned.resize_start_child = this.args.resizeStartChild as boolean;
+        this._paned.resize_end_child = this.args.resizeEndChild as boolean;
+        this._paned.shrink_start_child = this.args.shrinkStartChild as boolean;
+        // `set_position (-1)` is the C's own "let the size requests decide" (gtkpaned.c:1874),
+        // which is why the control's floor is -1 rather than 0.
+        this._paned.position = Number(this.args.position);
+    }
+}
+
+GObject.type_ensure(PanedStory.$gtype);
+
+export const PanedStories: StoryModule = { stories: [PanedStory] };

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

@@ -0,0 +1,29 @@
+// Shared, renderer-agnostic metadata for the Popover Bin story. Imported by the GTK renderer
+// (popover-bin.story.ts) and the browser renderer (browser/layout/popover-bin.web.ts), so
+// both expose identical controls.
+
+import { ControlType, type StoryMeta } from '@gjsify/stories';
+
+/** The menu a bin builds its popover from — the portable model of ADR 0042. */
+export const POPOVER_BIN_ITEMS = [
+    { label: 'Cut' },
+    { label: 'Copy' },
+    { label: 'Paste' },
+    { label: 'Delete', accel: '<Shift>Delete' },
+] as const;
+
+export const popoverBinMeta: StoryMeta = {
+    title: 'Layout/Popover Bin',
+    description:
+        'Gtk.PopoverBin — GTK 4.22’s one-child container with a popover, for the place where "any ' +
+        'part of this window can offer a menu" is the answer. `menu-model` builds the popover for ' +
+        'you, and `handle-input` is what turns a right click or a long press into a popup — a ' +
+        'plain click still reaches the child.',
+    // ONE control, because one is all `GtkPopoverBin` has to switch: whether the container
+    // claims a gesture. A "which child" control would be inert on both renderings — a bin
+    // holds exactly one child and both stories build the same one — and
+    // `check-storybook-control-parity.mjs` fails a control that moves and does nothing.
+    controls: [
+        { name: 'handleInput', label: 'Right click / long press opens', type: ControlType.BOOLEAN, defaultValue: true },
+    ],
+};

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

@@ -0,0 +1,66 @@
+// Gtk.PopoverBin — one child, and a popover to present from it.
+// 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_BIN_ITEMS, popoverBinMeta } from './popover-bin.meta.js';
+
+/**
+ * Story: a Gtk.PopoverBin wrapping a list row, with `handle-input` on so a right click (or a
+ * long press on a touchscreen) opens the menu, and a plain click selects the row as usual.
+ *
+ * The bin's own `menu.popup` action (gtkpopoverbin.c:381) is what the browser rendering
+ * exposes as a `popup()` method and a `menu.popup` event, so both reach the same surface a
+ * gesture reaches.
+ */
+export class PopoverBinStory extends StoryWidget {
+    private _bin: Gtk.PopoverBin | null = null;
+    private _list: Gtk.ListBox | null = null;
+
+    static {
+        GObject.registerClass({ GTypeName: 'AdwStorybookPopoverBin' }, PopoverBinStory);
+    }
+
+    constructor() {
+        super(StoryWidget.fromMeta(PopoverBinStory.getMetadata(), 'Default'));
+    }
+
+    static getMetadata(): StoryMeta {
+        return { ...popoverBinMeta, component: Gtk.PopoverBin.$gtype };
+    }
+
+    initialize(): void {
+        this._list = new Gtk.ListBox({ selectionMode: Gtk.SelectionMode.SINGLE });
+        for (const label of ['Documents', 'Downloads', 'Pictures']) {
+            this._list.append(new Gtk.ListBoxRow({ child: new Gtk.Label({ label }) }));
+        }
+        this._bin = new Gtk.PopoverBin({ child: this._list });
+        this._apply();
+        this.addContent(this._bin);
+    }
+
+    updateArgs(_args: StoryArgs): void {
+        this._apply();
+    }
+
+    private _buildMenu(): Gio.Menu {
+        const menu = new Gio.Menu();
+        for (const item of POPOVER_BIN_ITEMS)
+            menu.append(item.label, `app.${item.label.toLowerCase().replace(/[^a-z0-9]+/g, '-')}`);
+        return menu;
+    }
+
+    private _apply(): void {
+        if (!this._bin) return;
+        // `gtk_popover_bin_set_menu_model` builds the popover from the model and pins it to
+        // GTK_POS_BOTTOM (gtkpopoverbin.c:474-500) — there is nothing to position by hand.
+        this._bin.menuModel = this._buildMenu();
+        this._bin.handleInput = this.args.handleInput as boolean;
+    }
+}
+
+GObject.type_ensure(PopoverBinStory.$gtype);
+
+export const PopoverBinStories: StoryModule = { stories: [PopoverBinStory] };