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

package/src/media/video.story.ts

@@ -0,0 +1,57 @@
+// Gtk.Video — a play surface with an overlay and a self-hiding controls 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 { videoMeta } from './video.meta.js';
+
+/** Story: a Gtk.Video at the reader's width, with no stream attached. */
+export class VideoStory extends StoryWidget {
+    private _video: Gtk.Video | null = null;
+
+    static {
+        GObject.registerClass({ GTypeName: 'AdwStorybookVideo' }, VideoStory);
+    }
+
+    constructor() {
+        super(StoryWidget.fromMeta(VideoStory.getMetadata(), 'Default'));
+    }
+
+    static getMetadata(): StoryMeta {
+        return { ...videoMeta, component: Gtk.Video.$gtype };
+    }
+
+    initialize(): void {
+        // NO `set_media_stream`. A stream needs a backend behind it — gstreamer — and the
+        // overlay's first arm is the one a stream-less video shows anyway: `media-eject` is
+        // what `gtk_video_update_overlay_icon` draws when there is no stream at all
+        // (gtkvideo.c:629). So the story shows the state every GtkVideo starts in, which is
+        // the state a browser's `<video>` cannot reach.
+        this._video = new Gtk.Video({ halign: Gtk.Align.CENTER, valign: Gtk.Align.CENTER });
+        this._apply();
+        this.addContent(this._video);
+    }
+
+    updateArgs(_args: StoryArgs): void {
+        this._apply();
+    }
+
+    private _apply(): void {
+        if (!this._video) return;
+        const width = this.args.width as number;
+        this._video.set_size_request(width, Math.round((width * 9) / 16));
+        this._video.autoplay = this.args.autoplay as boolean;
+        this._video.loop = this.args.loop as boolean;
+        // Graphics offload is a rendering hint with no visible effect until something is
+        // actually drawn, so this control exists to show that the property takes the write
+        // rather than to show a difference.
+        this._video.graphics_offload = this.args.graphicsOffload
+            ? Gtk.GraphicsOffloadEnabled.ENABLED
+            : Gtk.GraphicsOffloadEnabled.DISABLED;
+    }
+}
+
+GObject.type_ensure(VideoStory.$gtype);
+
+export const VideoStories: StoryModule = { stories: [VideoStory] };

package/src/metas.ts

@@ -7,29 +7,90 @@
 export * from './buttons/button-content.meta.js';
 export * from './buttons/button-styles.meta.js';
 export * from './buttons/menu-button.meta.js';
+export * from './buttons/color-dialog-button.meta.js';
+export * from './buttons/font-dialog-button.meta.js';
+export * from './buttons/link-button.meta.js';
 export * from './buttons/split-button.meta.js';
+export * from './buttons/scale-button.meta.js';
+export * from './buttons/toggle-button.meta.js';
 export * from './buttons/toggle-group.meta.js';
+export * from './controls/check-button.meta.js';
 export * from './controls/drop-down.meta.js';
 export * from './controls/entry.meta.js';
+export * from './controls/gtk-spinner.meta.js';
+export * from './controls/level-bar.meta.js';
+export * from './controls/password-entry.meta.js';
+export * from './controls/progress-bar.meta.js';
+export * from './controls/scale.meta.js';
+export * from './controls/search-entry.meta.js';
+export * from './controls/spin-button.meta.js';
+export * from './controls/switch.meta.js';
+export * from './drawing/drag-icon.meta.js';
+export * from './drawing/drawing-area.meta.js';
+export * from './drawing/gl-area.meta.js';
+export * from './drawing/graphics-offload.meta.js';
 export * from './feedback/about-dialog.meta.js';
 export * from './feedback/alert-dialog.meta.js';
+export * from './feedback/dialog.meta.js';
+export * from './feedback/emoji-chooser.meta.js';
+export * from './feedback/gtk-about-dialog.meta.js';
+export * from './feedback/page-setup-unix-dialog.meta.js';
 export * from './feedback/preferences-dialog.meta.js';
+export * from './feedback/print-unix-dialog.meta.js';
+export * from './feedback/shortcuts-dialog.meta.js';
 export * from './feedback/toast.meta.js';
+export * from './layout/bin.meta.js';
+export * from './layout/breakpoint-bin.meta.js';
+export * from './layout/clamp-scrollable.meta.js';
 export * from './layout/clamp.meta.js';
+export * from './layout/expander.meta.js';
 export * from './layout/header-bar.meta.js';
+export * from './layout/layout-slot.meta.js';
+export * from './layout/multi-layout-view.meta.js';
+export * from './layout/overlay.meta.js';
+export * from './layout/paned.meta.js';
+export * from './layout/popover-bin.meta.js';
+export * from './layout/popover-menu.meta.js';
+export * from './layout/popover.meta.js';
+export * from './layout/revealer.meta.js';
+export * from './layout/scrollbar.meta.js';
+export * from './layout/scrolled-window.meta.js';
+export * from './layout/separator.meta.js';
+export * from './layout/aspect-frame.meta.js';
+export * from './layout/center-box.meta.js';
+export * from './layout/fixed.meta.js';
+export * from './layout/frame.meta.js';
+export * from './layout/grid.meta.js';
 export * from './layout/toolbar-view.meta.js';
+export * from './layout/viewport.meta.js';
+export * from './layout/application-window.meta.js';
+export * from './layout/window.meta.js';
 export * from './layout/wrap-box.meta.js';
+export * from './media/image.meta.js';
+export * from './media/inscription.meta.js';
+export * from './media/media-controls.meta.js';
+export * from './media/picture.meta.js';
+export * from './media/video.meta.js';
 export * from './navigation/bottom-sheet.meta.js';
 export * from './navigation/navigation-split-view.meta.js';
 export * from './navigation/navigation-view.meta.js';
 export * from './navigation/overlay-split-view.meta.js';
+export * from './navigation/popover-menu-bar.meta.js';
 export * from './navigation/sidebar.meta.js';
 export * from './overview/widgets.meta.js';
 export * from './presentation/avatar.meta.js';
 export * from './presentation/banner.meta.js';
+export * from './presentation/calendar.meta.js';
+export * from './presentation/column-view.meta.js';
+export * from './presentation/flow-box.meta.js';
+export * from './presentation/grid-view.meta.js';
+export * from './presentation/list-box.meta.js';
+export * from './presentation/list-view.meta.js';
 export * from './presentation/shortcut-label.meta.js';
 export * from './presentation/spinner.meta.js';
 export * from './presentation/status-page.meta.js';
+export * from './presentation/tree-expander.meta.js';
+export * from './presentation/window-handle.meta.js';
 export * from './presentation/window-title.meta.js';
 export * from './rows/action-row.meta.js';
 export * from './rows/button-row.meta.js';
@@ -38,10 +99,28 @@ export * from './rows/entry-row.meta.js';
 export * from './rows/expander-row.meta.js';
 export * from './rows/password-entry-row.meta.js';
 export * from './rows/preferences-group.meta.js';
+export * from './rows/preferences-row.meta.js';
 export * from './rows/spin-row.meta.js';
 export * from './rows/switch-row.meta.js';
+export * from './text/editable-label.meta.js';
+export * from './text/search-bar.meta.js';
+export * from './text/text-view.meta.js';
+export * from './text/text.meta.js';
 export * from './view-switching/carousel.meta.js';
 export * from './view-switching/inline-view-switcher.meta.js';
+export * from './view-switching/notebook.meta.js';
+export * from './view-switching/stack-sidebar.meta.js';
+export * from './view-switching/stack-switcher.meta.js';
+export * from './view-switching/stack.meta.js';
+export * from './view-switching/tab-bar.meta.js';
+export * from './view-switching/tab-button.meta.js';
+export * from './view-switching/tab-overview.meta.js';
+export * from './view-switching/view-switcher-sidebar.meta.js';
 export * from './view-switching/tab-view.meta.js';
 export * from './view-switching/view-switcher-bar.meta.js';
 export * from './view-switching/view-switcher.meta.js';
+export * from './windows/action-bar.meta.js';
+export * from './windows/gtk-application-window.meta.js';
+export * from './windows/gtk-header-bar.meta.js';
+export * from './windows/gtk-window.meta.js';
+export * from './windows/window-controls.meta.js';

package/src/navigation/popover-menu-bar.meta.ts

@@ -0,0 +1,51 @@
+// Shared, renderer-agnostic metadata for the Popover Menu Bar story. Imported by the GTK
+// renderer (popover-menu-bar.story.ts) and the browser renderer
+// (browser/navigation/popover-menu-bar.web.ts), so both expose identical controls.
+
+import { ControlType, type StoryMeta } from '@gjsify/stories';
+
+/**
+ * A menu bar's model: SUBMENUS ONLY at the top level. `GtkPopoverMenuBar` builds one item
+ * per toplevel submenu link and warns "Don't know how to handle this item" for anything
+ * else (gtkpopovermenubar.c:422-468) — which is why there is no bare item here.
+ */
+export const POPOVER_MENU_BAR_ITEMS = [
+    {
+        label: 'File',
+        submenu: [
+            { label: 'New Window', accel: '<Control>N' },
+            { label: 'New Tab', accel: '<Control><Shift>N' },
+            { label: 'Open…', accel: '<Control>O' },
+        ],
+    },
+    {
+        label: 'Edit',
+        submenu: [
+            { label: 'Undo', accel: '<Control>Z' },
+            { label: 'Redo', accel: '<Control>Y' },
+        ],
+    },
+    { label: 'View', submenu: [{ label: 'Zoom In', accel: '<Control>plus' }, { label: 'Zoom Out' }] },
+    { label: 'Help', submenu: [{ label: 'Keyboard Shortcuts' }, { label: 'About' }] },
+] as const;
+
+export const popoverMenuBarMeta: StoryMeta = {
+    title: 'Navigation/Popover Menu Bar',
+    description:
+        'Gtk.PopoverMenuBar — a horizontal bar of items that pop up menus when clicked. Clicking an ' +
+        'item OPENS its menu; hovering only SELECTS, and the item lights up (.active) exactly ' +
+        'while its menu is up. Left and Right walk the bar and wrap.',
+    controls: [
+        {
+            name: 'position',
+            label: 'Menu position',
+            type: ControlType.SELECT,
+            options: [
+                { label: 'Below', value: 'bottom' },
+                { label: 'Above', value: 'top' },
+            ],
+            defaultValue: 'bottom',
+        },
+        { name: 'showLast', label: 'Include Help', type: ControlType.BOOLEAN, defaultValue: true },
+    ],
+};

package/src/navigation/popover-menu-bar.story.ts

@@ -0,0 +1,72 @@
+// Gtk.PopoverMenuBar — a bar of items that pop up menus.
+// 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_BAR_ITEMS, popoverMenuBarMeta } from './popover-menu-bar.meta.js';
+
+/**
+ * Story: a Gtk.PopoverMenuBar over four submenus.
+ *
+ * `GtkPopoverMenuBar.new_from_model` (gtkpopovermenubar.c:686-703) is the ONLY way to make
+ * one — there is no constructor that takes children — so the model is the whole story. Each
+ * item's popover is `GtkPopoverMenu.new_from_model_full (…, GTK_POPOVER_MENU_NESTED)`
+ * (:435), pinned below the item with `has-arrow` off, which `tracker_insert` does for us.
+ */
+export class PopoverMenuBarStory extends StoryWidget {
+    private _bar: Gtk.PopoverMenuBar | null = null;
+
+    static {
+        GObject.registerClass({ GTypeName: 'AdwStorybookPopoverMenuBar' }, PopoverMenuBarStory);
+    }
+
+    constructor() {
+        super(StoryWidget.fromMeta(PopoverMenuBarStory.getMetadata(), 'Default'));
+    }
+
+    static getMetadata(): StoryMeta {
+        return { ...popoverMenuBarMeta, component: Gtk.PopoverMenuBar.$gtype };
+    }
+
+    initialize(): void {
+        this._bar = Gtk.PopoverMenuBar.new_from_model(this._buildMenu());
+        this._bar.halign = Gtk.Align.START;
+        this._apply();
+        this.addContent(this._bar);
+    }
+
+    updateArgs(_args: StoryArgs): void {
+        this._apply();
+    }
+
+    private _buildMenu(): Gio.Menu {
+        const menu = new Gio.Menu();
+        const entries = this.args.showLast === false ? POPOVER_MENU_BAR_ITEMS.slice(0, 3) : POPOVER_MENU_BAR_ITEMS;
+        for (const entry of entries) {
+            const submenu = new Gio.Menu();
+            for (const item of entry.submenu)
+                submenu.append(item.label, `app.${item.label.toLowerCase().replace(/[^a-z0-9]+/g, '-')}`);
+            menu.append_submenu(entry.label, submenu);
+        }
+        return menu;
+    }
+
+    private _apply(): void {
+        if (!this._bar) return;
+        // Every item's popover is pinned `GTK_POS_BOTTOM` by `tracker_insert`, so this is the
+        // one thing about it an application actually changes: walk the bar's children and
+        // re-point the popover each one owns. `GtkPopoverMenuBarItem` is private, so the
+        // popover is reached through the widget tree rather than through a typed accessor.
+        const above = this.args.position === 'top';
+        for (let child = this._bar.get_first_child(); child !== null; child = child.get_next_sibling()) {
+            const popover = (child as unknown as { get_first_child(): Gtk.Popover | null }).get_first_child();
+            popover?.set_position(above ? Gtk.PositionType.TOP : Gtk.PositionType.BOTTOM);
+        }
+    }
+}
+
+GObject.type_ensure(PopoverMenuBarStory.$gtype);
+
+export const PopoverMenuBarStories: StoryModule = { stories: [PopoverMenuBarStory] };

package/src/presentation/calendar.meta.ts

@@ -0,0 +1,28 @@
+// Shared, renderer-agnostic metadata for the Calendar story. Imported by the GTK renderer
+// (calendar.story.ts) and the browser renderer (browser/presentation/calendar.web.ts), so
+// both expose identical controls.
+
+import { ControlType, type StoryMeta } from '@gjsify/stories';
+
+/**
+ * The date both renderings start from, in the ISO form `GDateTime` serialises to. A fixed
+ * date rather than "today", so a screenshot of the story is the same on every machine —
+ * which is the same trade the `dir` reading in `roving-focus.ts` makes.
+ */
+export const CALENDAR_STORY_DATE = '2026-10-02';
+
+/** The days both renderings mark, so the tint appears at the same place everywhere. */
+export const CALENDAR_STORY_MARKS = [14, 25];
+
+export const calendarMeta: StoryMeta = {
+    title: 'Presentation/Calendar',
+    description:
+        'Gtk.Calendar — a six-by-seven month grid with four navigation arrows. The arrows clamp the way ' +
+        'g_date_time_add_months does, so paging from the 31st lands on the 28th, and a marked day is a day ' +
+        'NUMBER of the shown month, so it survives a month that has no such day.',
+    controls: [
+        { name: 'showHeading', label: 'Heading', type: ControlType.BOOLEAN, defaultValue: true },
+        { name: 'showDayNames', label: 'Day names', type: ControlType.BOOLEAN, defaultValue: true },
+        { name: 'showWeekNumbers', label: 'Week numbers', type: ControlType.BOOLEAN, defaultValue: true },
+    ],
+};

package/src/presentation/calendar.story.ts

@@ -0,0 +1,64 @@
+// Gtk.Calendar — the month grid, with the marks and the four arrows.
+// original implementation.
+
+import GLib from 'gi://GLib?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 { CALENDAR_STORY_DATE, CALENDAR_STORY_MARKS, calendarMeta } from './calendar.meta.js';
+
+/** Story: a Gtk.Calendar on a fixed date, so a screenshot is the same on every machine. */
+export class CalendarStory extends StoryWidget {
+    private _calendar: Gtk.Calendar | null = null;
+    private _marked = false;
+
+    static {
+        GObject.registerClass({ GTypeName: 'AdwStorybookCalendar' }, CalendarStory);
+    }
+
+    constructor() {
+        super(StoryWidget.fromMeta(CalendarStory.getMetadata(), 'Default'));
+    }
+
+    static getMetadata(): StoryMeta {
+        return { ...calendarMeta, component: Gtk.Calendar.$gtype };
+    }
+
+    initialize(): void {
+        this._calendar = new Gtk.Calendar({ hexpand: false });
+        // `GtkCalendar:date` holds a GDateTime; the deprecated year/month/day halves are the
+        // same write, and a template cannot construct one, so the story sets the object.
+        this._calendar.date = parseIso(CALENDAR_STORY_DATE);
+        this._apply();
+        this.addContent(this._calendar);
+    }
+
+    updateArgs(_args: StoryArgs): void {
+        this._apply();
+    }
+
+    private _apply(): void {
+        if (!this._calendar) return;
+        // Both default TRUE and one defaults FALSE (gtkcalendar.c:440-460), so the args write
+        // the values rather than the absences.
+        this._calendar.show_heading = this.args.showHeading as boolean;
+        this._calendar.show_day_names = this.args.showDayNames as boolean;
+        this._calendar.show_week_numbers = this.args.showWeekNumbers as boolean;
+
+        // `mark_day()` is IDEMPOTENT and the table is 31 slots, so marking twice is silent
+        // (gtkcalendar.c:1657) — but clearing first is what makes an arg change visible at all.
+        if (this._marked) this._calendar.clear_marks();
+        for (const day of CALENDAR_STORY_MARKS) this._calendar.mark_day(day);
+        this._marked = true;
+    }
+}
+
+/** `YYYY-MM-DD` → a local `GDateTime`, which is what `GtkCalendar:date` holds. */
+function parseIso(iso: string): GLib.DateTime {
+    const [year, month, day] = iso.split('-').map(Number);
+    return GLib.DateTime.new_local(year!, month!, day!, 0, 0, 0);
+}
+
+GObject.type_ensure(CalendarStory.$gtype);
+
+export const CalendarStories: StoryModule = { stories: [CalendarStory] };

package/src/presentation/column-view.meta.ts

@@ -0,0 +1,30 @@
+// Shared, renderer-agnostic metadata for the Column View story. Imported by the GTK
+// renderer (column-view.story.ts) and the browser renderer
+// (browser/presentation/column-view.web.ts), so both expose identical controls.
+
+import { ControlType, type StoryMeta } from '@gjsify/stories';
+
+/** Two-field items, which is what makes a two-column table out of the portable list. */
+export const COLUMN_VIEW_ITEMS = [
+    { value: 'de', label: 'German' },
+    { value: 'fr', label: 'French' },
+    { value: 'nl', label: 'Dutch' },
+    { value: 'pt', label: 'Portuguese' },
+];
+
+export const columnViewMeta: StoryMeta = {
+    title: 'Presentation/Column View',
+    description:
+        'Gtk.ColumnView — a list view with a header and one cell per column. Clicking a sortable header ' +
+        'sets the sort and inverts it on the next click; the view itself reorders nothing.',
+    controls: [
+        { name: 'showRowSeparators', label: 'Row separators', type: ControlType.BOOLEAN, defaultValue: true },
+        {
+            name: 'showColumnSeparators',
+            label: 'Column separators',
+            type: ControlType.BOOLEAN,
+            defaultValue: false,
+        },
+        { name: 'reorderable', label: 'Drag columns to reorder', type: ControlType.BOOLEAN, defaultValue: false },
+    ],
+};

package/src/presentation/column-view.story.ts

@@ -0,0 +1,73 @@
+// Gtk.ColumnView — a list view with a header and one cell per column.
+// 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 { COLUMN_VIEW_ITEMS, columnViewMeta } from './column-view.meta.js';
+
+/**
+ * Story: a Gtk.ColumnView of two columns over a Gtk.StringList of labels.
+ *
+ * The model is a string list, as the browser rendering's is, so both draw the same two
+ * fields: the Name column shows the string and the Code column the two-letter id the
+ * story holds beside it. A richer item type would need a GObject per row, which is the
+ * authoring step the portable list exists to avoid.
+ */
+export class ColumnViewStory extends StoryWidget {
+    private _view: Gtk.ColumnView | null = null;
+
+    static {
+        GObject.registerClass({ GTypeName: 'AdwStorybookColumnView' }, ColumnViewStory);
+    }
+
+    constructor() {
+        super(StoryWidget.fromMeta(ColumnViewStory.getMetadata(), 'Default'));
+    }
+
+    static getMetadata(): StoryMeta {
+        return { ...columnViewMeta, component: Gtk.ColumnView.$gtype };
+    }
+
+    initialize(): void {
+        const model = Gtk.StringList.new(COLUMN_VIEW_ITEMS.map((item) => item.label));
+        this._view = new Gtk.ColumnView({ model: Gtk.SingleSelection.new(model), vexpand: true });
+        this._view.append_column(this._column('Name', (item) => item.label));
+        this._view.append_column(this._column('Code', (item) => item.value));
+
+        const scroller = new Gtk.ScrolledWindow({ child: this._view, heightRequest: 200, hexpand: true });
+        this._apply();
+        this.addContent(scroller);
+    }
+
+    updateArgs(_args: StoryArgs): void {
+        this._apply();
+    }
+
+    private _apply(): void {
+        if (!this._view) return;
+        this._view.showRowSeparators = this.args.showRowSeparators as boolean;
+        this._view.showColumnSeparators = this.args.showColumnSeparators as boolean;
+        this._view.reorderable = this.args.reorderable as boolean;
+    }
+
+    /** One column, with the factory that reads the field this column draws. */
+    private _column(title: string, read: (item: { value: string; label: string }) => string): Gtk.ColumnViewColumn {
+        const factory = new Gtk.SignalListItemFactory();
+        factory.connect('setup', (_factory, item: GObject.Object) => {
+            (item as Gtk.ListItem).child = new Gtk.Label({ xalign: 0 });
+        });
+        factory.connect('bind', (_factory, item: GObject.Object) => {
+            const listItem = item as Gtk.ListItem;
+            const label = listItem.child as Gtk.Label;
+            const text = (listItem.item as Gtk.StringObject).string;
+            const entry = COLUMN_VIEW_ITEMS.find((candidate) => candidate.label === text);
+            label.label = entry === undefined ? text : read(entry);
+        });
+        return new Gtk.ColumnViewColumn({ title, factory, expand: true });
+    }
+}
+
+GObject.type_ensure(ColumnViewStory.$gtype);
+
+export const ColumnViewStories: StoryModule = { stories: [ColumnViewStory] };

package/src/presentation/flow-box.meta.ts

@@ -0,0 +1,51 @@
+// Shared, renderer-agnostic metadata for the Flow Box story. Imported by the GTK renderer
+// (flow-box.story.ts) and the browser renderer (browser/presentation/flow-box.web.ts), so
+// both expose identical controls.
+
+import { ControlType, type StoryMeta } from '@gjsify/stories';
+
+/** The cells both renderings build — more than a full line, so the reflow is visible. */
+export const FLOW_BOX_CELLS = ['Red', 'Orange', 'Yellow', 'Green', 'Blue', 'Purple', 'Teal', 'Grey'] as const;
+
+/** The four `Gtk.SelectionMode` values, under the nicks the shared selection module uses. */
+export const FLOW_BOX_SELECTION_MODES = [
+    { label: 'Single', value: 'single' },
+    { label: 'Multiple', value: 'multiple' },
+    { label: 'Browse', value: 'browse' },
+    { label: 'None', value: 'none' },
+];
+
+export const flowBoxMeta: StoryMeta = {
+    title: 'Presentation/Flow Box',
+    description:
+        'Gtk.FlowBox — the same selectable rows a list box holds, reflowed into as many per line as the ' +
+        'width fits. HORIZONTAL is the default here, unlike every GtkOrientable list base; the arrows move ' +
+        'by visual position, so the cross-line key lands in the same column of the next line.',
+    controls: [
+        {
+            name: 'selectionMode',
+            label: 'Selection',
+            type: ControlType.SELECT,
+            options: FLOW_BOX_SELECTION_MODES,
+            defaultValue: 'multiple',
+        },
+        {
+            name: 'orientation',
+            label: 'Orientation',
+            type: ControlType.SELECT,
+            options: [
+                { label: 'Horizontal', value: 'horizontal' },
+                { label: 'Vertical', value: 'vertical' },
+            ],
+            defaultValue: 'horizontal',
+        },
+        {
+            name: 'maxChildrenPerLine',
+            label: 'Max children per line',
+            type: ControlType.NUMBER,
+            defaultValue: 3,
+        },
+        { name: 'homogeneous', label: 'Homogeneous', type: ControlType.BOOLEAN, defaultValue: false },
+        { name: 'rowSpacing', label: 'Row spacing', type: ControlType.NUMBER, defaultValue: 6 },
+    ],
+};

package/src/presentation/flow-box.story.ts

@@ -0,0 +1,72 @@
+// Gtk.FlowBox — the same selectable rows a list box holds, reflowed into as many per line
+// as the width fits.
+// 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 { FLOW_BOX_CELLS, flowBoxMeta } from './flow-box.meta.js';
+
+/** Story: a Gtk.FlowBox of GtkFlowBoxChild cells, its line arithmetic driven by args. */
+export class FlowBoxStory extends StoryWidget {
+    private _box: Gtk.FlowBox | null = null;
+
+    static {
+        GObject.registerClass({ GTypeName: 'AdwStorybookFlowBox' }, FlowBoxStory);
+    }
+
+    constructor() {
+        super(StoryWidget.fromMeta(FlowBoxStory.getMetadata(), 'Default'));
+    }
+
+    static getMetadata(): StoryMeta {
+        return { ...flowBoxMeta, component: Gtk.FlowBox.$gtype };
+    }
+
+    initialize(): void {
+        this._box = new Gtk.FlowBox({ hexpand: true, vexpand: true });
+        // `GtkFlowBoxChild` is a Bin, so the wrapped widget goes through `set_child()` — the
+        // wrapper the markup form writes as `<gtk-flow-box-child>`.
+        for (const name of FLOW_BOX_CELLS) {
+            this._box.append(new Gtk.FlowBoxChild({ child: new Gtk.Label({ label: name }) }));
+        }
+        this._apply();
+        this.addContent(this._box);
+    }
+
+    updateArgs(_args: StoryArgs): void {
+        this._apply();
+    }
+
+    private _apply(): void {
+        if (!this._box) return;
+        this._box.selection_mode = this._selectionMode();
+        // HORIZONTAL is the default (gtkflowbox.c:3981) and the default the meta starts from,
+        // so the arg only has to write the property, not its absence.
+        this._box.orientation =
+            (this.args.orientation as string) === 'vertical' ? Gtk.Orientation.VERTICAL : Gtk.Orientation.HORIZONTAL;
+        // The ParamSpec minimum is 1 (gtkflowbox.c:3767-3770), so 0 from a cleared arg is
+        // clamped the way the setter would clamp it rather than silently wrapping everything
+        // onto one line.
+        this._box.max_children_per_line = Math.max(1, Math.trunc(this.args.maxChildrenPerLine as number));
+        this._box.homogeneous = this.args.homogeneous as boolean;
+        this._box.row_spacing = Math.max(0, Math.trunc(this.args.rowSpacing as number));
+    }
+
+    private _selectionMode(): Gtk.SelectionMode {
+        switch (this.args.selectionMode as string) {
+            case 'single':
+                return Gtk.SelectionMode.SINGLE;
+            case 'browse':
+                return Gtk.SelectionMode.BROWSE;
+            case 'none':
+                return Gtk.SelectionMode.NONE;
+            default:
+                return Gtk.SelectionMode.MULTIPLE;
+        }
+    }
+}
+
+GObject.type_ensure(FlowBoxStory.$gtype);
+
+export const FlowBoxStories: StoryModule = { stories: [FlowBoxStory] };

package/src/presentation/grid-view.meta.ts

@@ -0,0 +1,28 @@
+// Shared, renderer-agnostic metadata for the Grid View story. Imported by the GTK
+// renderer (grid-view.story.ts) and the browser renderer
+// (browser/presentation/grid-view.web.ts), so both expose identical controls.
+
+import { ControlType, type StoryMeta } from '@gjsify/stories';
+
+import { LIST_VIEW_SELECTION_MODES } from './list-view.meta.js';
+
+/** Enough items that a column-count change is visible as a reflow rather than as a resize. */
+export const GRID_VIEW_ITEMS = ['January', 'February', 'March', 'April', 'May', 'June', 'July', 'August'] as const;
+
+export const gridViewMeta: StoryMeta = {
+    title: 'Presentation/Grid View',
+    description:
+        'Gtk.GridView — the same model and factory as a list view, reflowed into as many equal columns as ' +
+        'the width fits, between min-columns and max-columns.',
+    controls: [
+        { name: 'maxColumns', label: 'Max columns', type: ControlType.NUMBER, defaultValue: 4 },
+        { name: 'minColumns', label: 'Min columns', type: ControlType.NUMBER, defaultValue: 1 },
+        {
+            name: 'selectionMode',
+            label: 'Selection',
+            type: ControlType.SELECT,
+            options: LIST_VIEW_SELECTION_MODES,
+            defaultValue: 'single',
+        },
+    ],
+};