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

package/src/drawing/drag-icon.story.ts

@@ -0,0 +1,117 @@
+// Gtk.DragIcon — the widget that follows the pointer, reached the only way it can be
+// reached: a drag source. Drag the row; the icon that comes with the drag is this widget,
+// and GTK destroys it when the drag ends. original implementation.
+
+import Gtk from 'gi://Gtk?version=4.0';
+import Gdk from 'gi://Gdk?version=4.0';
+import GObject from 'gi://GObject?version=2.0';
+import { type StoryArgs, type StoryMeta, type StoryModule, StoryWidget } from '@gjsify/storybook';
+import { dragIconMeta } from './drag-icon.meta.js';
+
+/** The value the drag offers, as both renderers offer it: a string, a colour, or nothing. */
+type DragValue = string | { red: number; green: number; blue: number; alpha: number } | null;
+
+/** Story: a draggable row whose drag icon is a `GtkDragIcon`, with the value bound to args. */
+export class DragIconStory extends StoryWidget {
+    private _row: Gtk.Box | null = null;
+    private _source: Gtk.DragSource | null = null;
+    private _hint: Gtk.Label | null = null;
+
+    static {
+        GObject.registerClass({ GTypeName: 'AdwStorybookDragIcon' }, DragIconStory);
+    }
+
+    constructor() {
+        super(StoryWidget.fromMeta(DragIconStory.getMetadata(), 'Default'));
+    }
+
+    static getMetadata(): StoryMeta {
+        return { ...dragIconMeta, component: Gtk.DragIcon.$gtype };
+    }
+
+    initialize(): void {
+        const box = new Gtk.Box({
+            orientation: Gtk.Orientation.VERTICAL,
+            spacing: 12,
+            halign: Gtk.Align.CENTER,
+            valign: Gtk.Align.CENTER,
+        });
+        this._hint = new Gtk.Label({ label: 'Drag the row and watch the pointer' });
+        this._hint.add_css_class('dim-label');
+
+        this._row = new Gtk.Box({
+            orientation: Gtk.Orientation.HORIZONTAL,
+            spacing: 12,
+            cssClasses: ['card'],
+        });
+        this._row.append(this._buildLabel());
+
+        // `GtkDragSource` is an EVENT CONTROLLER, not a widget: the doc's own snippet
+        // creates one, connects `prepare` and `drag-begin`, and hands it to
+        // `gtk_widget_add_controller` (gtkdragsource.c:44-58).
+        this._source = Gtk.DragSource.new();
+        this._source.actions = (this.args.actions as string) === 'move' ? Gdk.DragAction.MOVE : Gdk.DragAction.COPY;
+        this._source.connect('prepare', () => this._contentProvider());
+        this._source.connect('drag-begin', (_source: Gtk.DragSource, drag: Gdk.Drag) => this._setIcon(drag));
+        this._row.add_controller(this._source);
+
+        this._apply();
+        box.append(this._hint);
+        box.append(this._row);
+        this.addContent(box);
+    }
+
+    updateArgs(_args: StoryArgs): void {
+        if (this._source === null) return;
+        this._source.actions = (this.args.actions as string) === 'move' ? Gdk.DragAction.MOVE : Gdk.DragAction.COPY;
+        this._apply();
+    }
+
+    /** What the drag offers, which is also what decides the icon — the two are one thing. */
+    private _value(): DragValue {
+        switch (this.args.value) {
+            case 'rgba':
+                return { red: 0.25, green: 0.55, blue: 0.95, alpha: 1 };
+            case 'none':
+                return null;
+            default:
+                return 'Report.odt';
+        }
+    }
+
+    /** `::prepare` answers the content provider, set just in time rather than ahead. */
+    private _contentProvider(): Gdk.ContentProvider | null {
+        const value = this._value();
+        return value === null ? null : Gdk.ContentProvider.new_for_value(value);
+    }
+
+    /**
+     * `::drag-begin` is where an icon of your own is set: `gtk_drag_icon_get_for_drag`
+     * (gtkdragicon.c:400-421) is the ONLY way to reach one, and
+     * `gtk_drag_icon_create_widget_for_value` (:529-556) is what decides what a value shows.
+     */
+    private _setIcon(drag: Gdk.Drag): void {
+        const value = this._value();
+        const icon = Gtk.DragIcon.get_for_drag(drag);
+        const child = value === null ? null : Gtk.DragIcon.create_widget_for_value(value);
+        // `set_child` unparents the old child and shows the icon (:468-489), so this is
+        // also how an icon that had none starts showing.
+        icon.set_child(child);
+    }
+
+    private _buildLabel(): Gtk.Label {
+        return new Gtk.Label({ label: 'Report.odt', cssClasses: ['heading'] });
+    }
+
+    private _apply(): void {
+        if (this._hint === null) return;
+        this._hint.label =
+            this.args.value === 'none'
+                ? 'Drag the row — no icon, because the value has no widget to show'
+                : 'Drag the row and watch the pointer';
+    }
+}
+
+GObject.type_ensure(DragIconStory.$gtype);
+
+export const DragIconStories: StoryModule = { stories: [DragIconStory] };

package/src/drawing/drawing-area.meta.ts

@@ -0,0 +1,45 @@
+// Shared, renderer-agnostic metadata for the Drawing Area story. Imported by the GTK
+// renderer (drawing-area.story.ts) and the browser renderer
+// (browser/drawing/drawing-area.web.ts), so both expose identical controls.
+
+import { ControlType, type StoryMeta } from '@gjsify/stories';
+
+export const drawingAreaMeta: StoryMeta = {
+    title: 'Drawing/Drawing Area',
+    description:
+        'Gtk.DrawingArea — a blank widget that owns a size and a callback and nothing else: whatever you ' +
+        'see is what `set_draw_func` painted. `content-width` and `content-height` are the MINIMUM and ' +
+        'natural size at once, so a parent can hand the area more room but never less; at 0 the area has ' +
+        'no intrinsic size at all and fills whatever it is given.',
+    controls: [
+        {
+            name: 'contentWidth',
+            label: 'Content width',
+            type: ControlType.RANGE,
+            min: 0,
+            max: 320,
+            step: 16,
+            defaultValue: 160,
+        },
+        {
+            name: 'contentHeight',
+            label: 'Content height',
+            type: ControlType.RANGE,
+            min: 0,
+            max: 320,
+            step: 16,
+            defaultValue: 120,
+        },
+        {
+            name: 'shape',
+            label: 'Shape',
+            type: ControlType.SELECT,
+            options: [
+                { label: 'Circle', value: 'circle' },
+                { label: 'Grid', value: 'grid' },
+                { label: 'Crosshair', value: 'crosshair' },
+            ],
+            defaultValue: 'circle',
+        },
+    ],
+};

package/src/drawing/drawing-area.story.ts

@@ -0,0 +1,78 @@
+// Gtk.DrawingArea — a blank widget you paint on.
+// 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 { drawingAreaMeta } from './drawing-area.meta.js';
+
+/** Story: a Gtk.DrawingArea with a draw function and the size properties bound to args. */
+export class DrawingAreaStory extends StoryWidget {
+    private _box: Gtk.Box | null = null;
+    private _area: Gtk.DrawingArea | null = null;
+
+    static {
+        GObject.registerClass({ GTypeName: 'AdwStorybookDrawingArea' }, DrawingAreaStory);
+    }
+
+    constructor() {
+        super(StoryWidget.fromMeta(DrawingAreaStory.getMetadata(), 'Default'));
+    }
+
+    static getMetadata(): StoryMeta {
+        return { ...drawingAreaMeta, component: Gtk.DrawingArea.$gtype };
+    }
+
+    initialize(): void {
+        this._area = new Gtk.DrawingArea();
+        // The area paints itself: the draw function reads the widget's colour rather than a
+        // hard-coded one, so the shape follows the theme in either renderer.
+        this._area.set_draw_func((area, cr, width, height) => {
+            // `get_color` is the function GTK's own documented draw_function reads
+            // (gtkdrawingarea.c:88-104), so the shape follows the widget's own colour.
+            const color = area.get_color();
+            cr.setSourceRGBA(color.red, color.green, color.blue, color.alpha);
+            cr.rectangle(0, 0, width, height);
+            cr.fill();
+            cr.setSourceRGBA(1 - color.red, 1 - color.green, 1 - color.blue, color.alpha);
+            switch (this.args.shape) {
+                case 'grid':
+                    for (let x = 0; x < width; x += 16) {
+                        cr.rectangle(x, 0, 8, height);
+                        cr.fill();
+                    }
+                    break;
+                case 'crosshair':
+                    cr.rectangle(width / 2 - 1, 0, 2, height);
+                    cr.rectangle(0, height / 2 - 1, width, 2);
+                    cr.fill();
+                    break;
+                default:
+                    cr.arc(width / 2, height / 2, Math.min(width, height) / 2, 0, 2 * Math.PI);
+                    cr.fill();
+                    break;
+            }
+        });
+        this._box = new Gtk.Box({ halign: Gtk.Align.CENTER, valign: Gtk.Align.CENTER });
+        this._box.append(this._area);
+        this._apply();
+        this.addContent(this._box);
+    }
+
+    updateArgs(_args: StoryArgs): void {
+        // A new size invalidates the picture GTK has of the area, and `queue_draw` is the
+        // documented way to ask for the draw function again (gtkdrawingarea.c:127-129).
+        this._area?.queue_draw();
+        this._apply();
+    }
+
+    private _apply(): void {
+        if (!this._area) return;
+        this._area.content_width = this.args.contentWidth as number;
+        this._area.content_height = this.args.contentHeight as number;
+    }
+}
+
+GObject.type_ensure(DrawingAreaStory.$gtype);
+
+export const DrawingAreaStories: StoryModule = { stories: [DrawingAreaStory] };

package/src/drawing/gl-area.meta.ts

@@ -0,0 +1,30 @@
+// Shared, renderer-agnostic metadata for the GL Area story. Imported by the GTK
+// renderer (gl-area.story.ts) and the browser renderer
+// (browser/drawing/gl-area.web.ts), so both expose identical controls.
+
+import { ControlType, type StoryMeta } from '@gjsify/stories';
+
+export const glAreaMeta: StoryMeta = {
+    title: 'Drawing/GL Area',
+    description:
+        'Gtk.GLArea — a widget whose contents are drawn on a GPU. GTK emits `::resize` before the first ' +
+        '`::render` and the render flag is cleared AFTER the signal, so a handler may queue another frame ' +
+        'with `queue_render()`. Here the replica is a `<canvas>` with a real WebGL context: the browser has ' +
+        'no desktop GL, so `api` always reports the ES flavour it was given.',
+    controls: [
+        { name: 'autoRender', label: 'Auto render', type: ControlType.BOOLEAN, defaultValue: true },
+        { name: 'hasDepthBuffer', label: 'Depth buffer', type: ControlType.BOOLEAN, defaultValue: false },
+        {
+            name: 'allowedApis',
+            label: 'Allowed APIs',
+            type: ControlType.SELECT,
+            options: [
+                { label: 'GL and GLES (default)', value: 'gl gles' },
+                { label: 'GLES only', value: 'gles' },
+                { label: 'GL only', value: 'gl' },
+            ],
+            defaultValue: 'gl gles',
+        },
+        { name: 'spinning', label: 'Spin the triangle', type: ControlType.BOOLEAN, defaultValue: true },
+    ],
+};

package/src/drawing/gl-area.story.ts

@@ -0,0 +1,113 @@
+// Gtk.GLArea — the widget whose contents are drawn on a GPU.
+// original implementation.
+
+import Gtk from 'gi://Gtk?version=4.0';
+import Gdk from 'gi://Gdk?version=4.0';
+import GLib from 'gi://GLib?version=2.0';
+import GObject from 'gi://GObject?version=2.0';
+import { type StoryArgs, type StoryMeta, type StoryModule, StoryWidget } from '@gjsify/storybook';
+import { glAreaMeta } from './gl-area.meta.js';
+
+/** 33 ms is about thirty frames a second, the tick GTK's own demos use. */
+const TICK_MS = 33;
+
+/**
+ * Story: a Gtk.GLArea whose lifecycle is the subject — `::resize` before the first
+ * `::render`, `queue_render()` from a tick, and the two flags bound to args.
+ *
+ * WHAT THIS STORY DOES NOT DRAW, AND WHY. Painting the triangle needs `gi://GL` calls
+ * (`glCreateShader`, `glDrawArrays`, …), and a GL binding is not one of this storybook's
+ * dependencies — every other story here is widget-shaped, and importing a binding to fill
+ * one would make the one GL widget the one that cannot be built. So the area renders
+ * nothing and the readout below it shows what the SIGNALS did: the device-pixel viewport
+ * from `::resize`, and how many frames `::render` produced. The browser story draws the
+ * same triangle for real, because a `<canvas>` has WebGL built in.
+ */
+export class GLAreaStory extends StoryWidget {
+    private _area: Gtk.GLArea | null = null;
+    private _readout: Gtk.Label | null = null;
+    private _box: Gtk.Box | null = null;
+    private _tick = 0;
+    private _renders = 0;
+    private _viewport = '—';
+
+    static {
+        GObject.registerClass({ GTypeName: 'AdwStorybookGLArea' }, GLAreaStory);
+    }
+
+    constructor() {
+        super(StoryWidget.fromMeta(GLAreaStory.getMetadata(), 'Default'));
+    }
+
+    static getMetadata(): StoryMeta {
+        return { ...glAreaMeta, component: Gtk.GLArea.$gtype };
+    }
+
+    initialize(): void {
+        this._area = new Gtk.GLArea({ widthRequest: 240, heightRequest: 160 });
+        this._readout = new Gtk.Label({ label: '—' });
+        this._readout.add_css_class('dimmed');
+
+        // `::resize` comes BEFORE the first `::render` and on every later allocation: the
+        // order a GL program depends on to know its viewport (gtkglarea.c:797-807). The
+        // numbers are DEVICE pixels — `w = width * scale` (:761-763).
+        this._area.connect('resize', (_area, width: number, height: number) => {
+            this._viewport = `${width} × ${height}`;
+            this._refresh();
+        });
+        this._area.connect('render', () => {
+            this._renders += 1;
+            this._refresh();
+        });
+
+        this._box = new Gtk.Box({ orientation: Gtk.Orientation.VERTICAL, spacing: 6 });
+        this._box.append(this._area);
+        this._box.append(this._readout);
+        this._apply();
+        this.addContent(this._box);
+    }
+
+    updateArgs(_args: StoryArgs): void {
+        this._stop();
+        this._apply();
+        this._start();
+    }
+
+    private _apply(): void {
+        if (!this._area) return;
+        // `allowed_apis` REFUSES a realized area (`g_return_if_fail (!realized)`,
+        // gtkglarea.c:1242), so it belongs before the first render, not after it.
+        this._area.allowed_apis = this.args.allowedApis === 'gles' ? Gdk.GLAPI.GLES : Gdk.GLAPI.GL | Gdk.GLAPI.GLES;
+        this._area.auto_render = this.args.autoRender as boolean;
+        this._area.has_depth_buffer = this.args.hasDepthBuffer as boolean;
+    }
+
+    /**
+     * `queue_render()` is how a GL application asks for the next frame (gtkglarea.c:1465):
+     * the flag is set and a redraw queued, and `::render` runs on that frame. Nothing here
+     * redraws on its own, which is the point — `auto-render` decides whether a draw the
+     * element was asked for ends in `::render`, not whether frames appear.
+     */
+    private _start(): void {
+        if (!this._area || !this.args.spinning) return;
+        this._tick = GLib.timeout_add(GLib.PRIORITY_DEFAULT, TICK_MS, () => {
+            this._area?.queue_render();
+            return GLib.SOURCE_CONTINUE;
+        });
+    }
+
+    private _stop(): void {
+        if (this._tick === 0) return;
+        GLib.source_remove(this._tick);
+        this._tick = 0;
+    }
+
+    private _refresh(): void {
+        if (!this._readout) return;
+        this._readout.label = `viewport ${this._viewport} device px · ${this._renders} renders`;
+    }
+}
+
+GObject.type_ensure(GLAreaStory.$gtype);
+
+export const GLAreaStories: StoryModule = { stories: [GLAreaStory] };

package/src/drawing/graphics-offload.meta.ts

@@ -0,0 +1,39 @@
+// Shared, renderer-agnostic metadata for the Graphics Offload story. Imported by the GTK
+// renderer (graphics-offload.story.ts) and the browser renderer
+// (browser/drawing/graphics-offload.web.ts), so both expose identical controls.
+
+import { ControlType, type StoryMeta } from '@gjsify/stories';
+
+export const graphicsOffloadMeta: StoryMeta = {
+    title: 'Drawing/Graphics Offload',
+    description:
+        'Gtk.GraphicsOffload — a wrapper that asks the compositor to take its ONE child as it is, which ' +
+        'is worth doing for content that changes every frame. `enabled` says whether it is attempted, and ' +
+        "`black-background` paints the letterbox bars. The passthrough itself is the platform's: no browser " +
+        'API hands a surface to a compositor, so the replica carries the enum, the black rectangle and the ' +
+        'bin layout, and says plainly which part is missing.',
+    controls: [
+        {
+            name: 'enabled',
+            label: 'Enabled',
+            type: ControlType.SELECT,
+            options: [
+                { label: 'Enabled (default)', value: 'enabled' },
+                { label: 'Disabled', value: 'disabled' },
+            ],
+            defaultValue: 'enabled',
+        },
+        { name: 'blackBackground', label: 'Black background', type: ControlType.BOOLEAN, defaultValue: false },
+        {
+            name: 'child',
+            label: 'Child',
+            type: ControlType.SELECT,
+            options: [
+                { label: 'Label', value: 'label' },
+                { label: 'Image', value: 'image' },
+                { label: 'Row of labels', value: 'box' },
+            ],
+            defaultValue: 'image',
+        },
+    ],
+};

package/src/drawing/graphics-offload.story.ts

@@ -0,0 +1,73 @@
+// Gtk.GraphicsOffload — one child, handed to the compositor as it is.
+// 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 { graphicsOffloadMeta } from './graphics-offload.meta.js';
+
+/** Story: a Gtk.GraphicsOffload around one child, with `enabled` and the black rect bound to args. */
+export class GraphicsOffloadStory extends StoryWidget {
+    private _offload: Gtk.GraphicsOffload | null = null;
+    private _box: Gtk.Box | null = null;
+
+    static {
+        GObject.registerClass({ GTypeName: 'AdwStorybookGraphicsOffload' }, GraphicsOffloadStory);
+    }
+
+    constructor() {
+        super(StoryWidget.fromMeta(GraphicsOffloadStory.getMetadata(), 'Default'));
+    }
+
+    static getMetadata(): StoryMeta {
+        return { ...graphicsOffloadMeta, component: Gtk.GraphicsOffload.$gtype };
+    }
+
+    initialize(): void {
+        this._offload = new Gtk.GraphicsOffload({ widthRequest: 280, heightRequest: 96 });
+        // The order is the property order (gtkgraphicsoffload.c:366-380, :423-437): `enabled`
+        // first — it syncs the subsurface — then the black rectangle, which paints before the child.
+        this._offload.enabled = (this.args.enabled as string) === 'disabled' ? 1 : 0;
+        this._offload.black_background = this.args.blackBackground as boolean;
+        this._box = new Gtk.Box({ halign: Gtk.Align.CENTER, valign: Gtk.Align.CENTER });
+        this._box.append(this._offload);
+        this._applyChild();
+        this.addContent(this._box);
+    }
+
+    updateArgs(_args: StoryArgs): void {
+        if (!this._offload) return;
+        this._offload.enabled = (this.args.enabled as string) === 'disabled' ? 1 : 0;
+        this._offload.black_background = this.args.blackBackground as boolean;
+        this._applyChild();
+    }
+
+    /** The wrapper holds exactly ONE child, so changing it means replacing it. */
+    private _applyChild(): void {
+        if (!this._offload) return;
+        let child: Gtk.Widget;
+        switch (this.args.child) {
+            case 'label':
+                child = new Gtk.Label({ label: 'The child of an offloaded layer' });
+                break;
+            case 'box': {
+                // A row of three labels, centred — the bin layout hands it the whole
+                // allocation whatever its own request is.
+                const row = new Gtk.Box({ orientation: Gtk.Orientation.HORIZONTAL, spacing: 12 });
+                for (const text of ['One', 'Two', 'Three']) row.append(new Gtk.Label({ label: text }));
+                child = new Gtk.CenterBox();
+                (child as Gtk.CenterBox).set_center_widget(row);
+                break;
+            }
+            default:
+                child = new Gtk.Image({ iconName: 'camera-photo-symbolic', pixelSize: 48 });
+                break;
+        }
+        // `set_child` unparents the old one and notifies (gtkgraphicsoffload.c:317-336).
+        this._offload.child = child;
+    }
+}
+
+GObject.type_ensure(GraphicsOffloadStory.$gtype);
+
+export const GraphicsOffloadStories: StoryModule = { stories: [GraphicsOffloadStory] };

package/src/feedback/dialog.meta.ts

@@ -0,0 +1,25 @@
+// Shared, renderer-agnostic metadata for the Dialog story. Imported by
+// both the GTK renderer (dialog.story.ts) and the browser renderer
+// (browser/feedback/dialog.web.ts) so the two expose identical controls.
+
+import { ControlType, type StoryMeta } from '@gjsify/stories';
+
+export const dialogMeta: StoryMeta = {
+    title: 'Feedback/Dialog',
+    description:
+        'Adw.Dialog — the generic dialog: arbitrary content over a scrim, anchored as a floating card on a wide window and as a bottom sheet on a narrow one.',
+    controls: [
+        { name: 'title', label: 'Title', type: ControlType.TEXT, defaultValue: 'Preferences' },
+        {
+            name: 'presentation',
+            label: 'Presentation',
+            type: ControlType.SELECT,
+            options: [
+                { label: 'Auto', value: 'auto' },
+                { label: 'Floating', value: 'floating' },
+                { label: 'Bottom sheet', value: 'bottom-sheet' },
+            ],
+            defaultValue: 'auto',
+        },
+    ],
+};

package/src/feedback/dialog.story.ts

@@ -0,0 +1,78 @@
+// Adw.Dialog — the generic dialog: arbitrary content over a scrim.
+// 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 { dialogMeta } from './dialog.meta.js';
+
+/**
+ * The meta's `presentation` NICK → the enum member, spelled out rather than cast.
+ *
+ * `Adw.DialogPresentationMode` is a GIR enum and the control carries a string, so
+ * `as Adw.DialogPresentationMode` would be a lie the compiler cannot see: it hands the
+ * property the string `"bottom-sheet"`. Every renderer of this story reads the SAME
+ * nick out of the shared meta, and this table is where GTK turns it back into a number.
+ */
+const DIALOG_PRESENTATION: Record<string, Adw.DialogPresentationMode> = {
+    auto: Adw.DialogPresentationMode.AUTO,
+    floating: Adw.DialogPresentationMode.FLOATING,
+    'bottom-sheet': Adw.DialogPresentationMode.BOTTOM_SHEET,
+};
+
+/** Story: Adw.Dialog presented from a button, holding a preferences page as its child. */
+export class DialogStory extends StoryWidget {
+    private _button: Gtk.Button | null = null;
+
+    static {
+        GObject.registerClass({ GTypeName: 'AdwStorybookDialog' }, DialogStory);
+    }
+
+    constructor() {
+        super(StoryWidget.fromMeta(DialogStory.getMetadata(), 'Default'));
+    }
+
+    static getMetadata(): StoryMeta {
+        return { ...dialogMeta, component: Adw.Dialog.$gtype };
+    }
+
+    initialize(): void {
+        this._button = new Gtk.Button({
+            label: 'Show dialog',
+            halign: Gtk.Align.CENTER,
+            valign: Gtk.Align.CENTER,
+        });
+        this._button.add_css_class('pill');
+        this._button.add_css_class('suggested-action');
+        this._button.connect('clicked', () => this._present());
+
+        this.addContent(this._button);
+    }
+
+    private _present(): void {
+        // ONE child, and it is a property (`Adw.Dialog:child`), not a pack: this is the
+        // dialog the specialised ones are written as subclasses of.
+        const group = new Adw.PreferencesGroup({ title: 'Appearance' });
+        group.add(new Adw.SwitchRow({ title: 'Dark style', subtitle: 'Use a dark colour scheme', active: true }));
+
+        const page = new Adw.PreferencesPage({ title: 'General' });
+        page.add(group);
+
+        const dialog = new Adw.Dialog({
+            title: this.args.title as string,
+            child: page,
+            presentation_mode: DIALOG_PRESENTATION[this.args.presentation as string],
+        });
+
+        dialog.present(this);
+    }
+
+    updateArgs(_args: StoryArgs): void {
+        // The dialog reads the latest args each time it is presented; nothing to mutate live.
+    }
+}
+
+GObject.type_ensure(DialogStory.$gtype);
+
+export const DialogStories: StoryModule = { stories: [DialogStory] };

package/src/feedback/emoji-chooser.meta.ts

@@ -0,0 +1,10 @@
+// Shared, renderer-agnostic metadata for the Gtk.EmojiChooser story.
+
+import { ControlType, type StoryMeta } from '@gjsify/stories';
+
+export const emojiChooserMeta: StoryMeta = {
+    title: 'Feedback/Emoji Chooser',
+    description:
+        'Gtk.EmojiChooser — the popover a text widget opens to insert an emoji: a search entry over nine named sections, a toolbar that follows the scroll position, and an emoji-picked signal.',
+    controls: [{ name: 'search', label: 'Search', type: ControlType.TEXT, defaultValue: 'smile' }],
+};