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

package/src/layout/aspect-frame.meta.ts

@@ -0,0 +1,19 @@
+// Shared, renderer-agnostic metadata for the Aspect Frame story. Imported by the GTK
+// renderer (aspect-frame.story.ts) and the browser renderer
+// (browser/layout/aspect-frame.web.ts), so both expose identical controls.
+
+import { ControlType, type StoryMeta } from '@gjsify/stories';
+
+export const aspectFrameMeta: StoryMeta = {
+    title: 'Layout/Aspect Frame',
+    description:
+        'Gtk.AspectFrame — one child, given a width/height ratio and a place in the space left over. ' +
+        'obey-child is TRUE by default and takes the ratio from the child itself, so the story starts with ' +
+        'it FALSE or the ratio control would be inert.',
+    controls: [
+        { name: 'ratio', label: 'Ratio', type: ControlType.RANGE, min: 0.5, max: 3, step: 0.25, defaultValue: 2 },
+        { name: 'xalign', label: 'Xalign', type: ControlType.RANGE, min: 0, max: 1, step: 0.5, defaultValue: 0.5 },
+        { name: 'yalign', label: 'Yalign', type: ControlType.RANGE, min: 0, max: 1, step: 0.5, defaultValue: 0.5 },
+        { name: 'obeyChild', label: 'Obey child', type: ControlType.BOOLEAN, defaultValue: false },
+    ],
+};

package/src/layout/aspect-frame.story.ts

@@ -0,0 +1,62 @@
+// Gtk.AspectFrame — one child, given a shape and a place.
+// 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 { aspectFrameMeta } from './aspect-frame.meta.js';
+
+/** Story: a Gtk.AspectFrame over a box, with its ratio and both alignments bound to args. */
+export class AspectFrameStory extends StoryWidget {
+    private _frame: Gtk.AspectFrame | null = null;
+
+    static {
+        GObject.registerClass({ GTypeName: 'AdwStorybookAspectFrame' }, AspectFrameStory);
+    }
+
+    constructor() {
+        super(StoryWidget.fromMeta(AspectFrameStory.getMetadata(), 'Default'));
+    }
+
+    static getMetadata(): StoryMeta {
+        return { ...aspectFrameMeta, component: Gtk.AspectFrame.$gtype };
+    }
+
+    initialize(): void {
+        this._frame = new Gtk.AspectFrame({
+            hexpand: true,
+            valign: Gtk.Align.CENTER,
+            width_request: 320,
+            height_request: 180,
+        });
+        const body = new Gtk.Label({
+            label: 'The frame gives this child the ratio above, and puts it where xalign and yalign say.',
+        });
+        body.set_margin_top(12);
+        body.set_margin_bottom(12);
+        body.set_margin_start(12);
+        body.set_margin_end(12);
+        body.set_vexpand(true);
+        this._frame.set_child(body);
+        this._apply();
+        this.addContent(this._frame);
+    }
+
+    updateArgs(_args: StoryArgs): void {
+        this._apply();
+    }
+
+    private _apply(): void {
+        if (!this._frame) return;
+        this._frame.ratio = this.args.ratio as number;
+        this._frame.xalign = this.args.xalign as number;
+        this._frame.yalign = this.args.yalign as number;
+        // TRUE makes the child\'s own ratio win and `ratio` inert — set LAST, so the control
+        // order above is the order the story reads it in.
+        this._frame.obeyChild = this.args.obeyChild as boolean;
+    }
+}
+
+GObject.type_ensure(AspectFrameStory.$gtype);
+
+export const AspectFrameStories: StoryModule = { stories: [AspectFrameStory] };

package/src/layout/bin.meta.ts

@@ -0,0 +1,15 @@
+// Shared, renderer-agnostic metadata for the Bin story. Imported by the GTK renderer
+// (bin.story.ts) and the browser renderer (browser/layout/bin.web.ts).
+
+import { ControlType, type StoryMeta } from '@gjsify/stories';
+
+export const binMeta: StoryMeta = {
+    title: 'Layout/Bin',
+    description:
+        'Adw.Bin — a widget with exactly one child. It draws nothing of its own and gives the child its whole ' +
+        'allocation; setting a new child replaces the old one.',
+    controls: [
+        { name: 'label', label: 'Child label', type: ControlType.TEXT, defaultValue: 'The one child of this bin.' },
+        { name: 'swap', label: 'Replace the child', type: ControlType.BOOLEAN, defaultValue: false },
+    ],
+};

package/src/layout/bin.story.ts

@@ -0,0 +1,56 @@
+// Adw.Bin — one child, replaced rather than stacked.
+// 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 { binMeta } from './bin.meta.js';
+
+/** Story: an Adw.Bin whose child is swapped for another by `set_child`. */
+export class BinStory extends StoryWidget {
+    private _bin: Adw.Bin | null = null;
+
+    static {
+        GObject.registerClass({ GTypeName: 'AdwStorybookBin' }, BinStory);
+    }
+
+    constructor() {
+        super(StoryWidget.fromMeta(BinStory.getMetadata(), 'Default'));
+    }
+
+    static getMetadata(): StoryMeta {
+        return { ...binMeta, component: Adw.Bin.$gtype };
+    }
+
+    initialize(): void {
+        this._bin = new Adw.Bin({ widthRequest: 320 });
+        this._apply();
+        this.addContent(this._bin);
+    }
+
+    updateArgs(_args: StoryArgs): void {
+        this._apply();
+    }
+
+    private _apply(): void {
+        if (!this._bin) return;
+        const swap = this.args.swap as boolean;
+        const label = new Gtk.Label({
+            label: swap ? 'The first child was replaced, not stacked.' : (this.args.label as string),
+            wrap: true,
+            marginTop: 18,
+            marginBottom: 18,
+            marginStart: 18,
+            marginEnd: 18,
+        });
+        const card = new Gtk.Box();
+        card.add_css_class('card');
+        card.append(label);
+        this._bin.child = card;
+    }
+}
+
+GObject.type_ensure(BinStory.$gtype);
+
+export const BinStories: StoryModule = { stories: [BinStory] };

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

@@ -0,0 +1,38 @@
+// Shared, renderer-agnostic metadata for the Breakpoint Bin story. Imported by the GTK
+// renderer (breakpoint-bin.story.ts) and the browser renderer
+// (browser/layout/breakpoint-bin.web.ts), so both expose identical controls.
+
+import { ControlType, type StoryMeta } from '@gjsify/stories';
+
+export const breakpointBinMeta: StoryMeta = {
+    title: 'Layout/Breakpoint Bin',
+    description:
+        'Adw.BreakpointBin gives breakpoints a home without a window: its one child rearranges ' +
+        'itself at a size threshold, and the bin applies the LAST breakpoint whose condition ' +
+        'holds. Resize the stage to see it.',
+    controls: [
+        {
+            name: 'condition',
+            label: 'Condition',
+            type: ControlType.SELECT,
+            options: [
+                { label: 'max-width: 480px', value: 'max-width: 480px' },
+                { label: 'max-width: 320px', value: 'max-width: 320px' },
+                { label: 'max-height: 200px', value: 'max-height: 200px' },
+            ],
+            defaultValue: 'max-width: 480px',
+        },
+        {
+            name: 'narrowLabel',
+            label: 'Narrow label',
+            type: ControlType.TEXT,
+            defaultValue: 'Narrow',
+        },
+        {
+            name: 'wideLabel',
+            label: 'Wide label',
+            type: ControlType.TEXT,
+            defaultValue: 'Wide',
+        },
+    ],
+};

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

@@ -0,0 +1,62 @@
+// Adw.BreakpointBin — a bin whose one child rearranges itself at a size threshold.
+// 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 { breakpointBinMeta } from './breakpoint-bin.meta.js';
+
+/** Story: a label that reads "Narrow" below the condition and "Wide" above it. */
+export class BreakpointBinStory extends StoryWidget {
+    private _bin: Adw.BreakpointBin | null = null;
+    private _label: Gtk.Label | null = null;
+    private _breakpoint: Adw.Breakpoint | null = null;
+
+    static {
+        GObject.registerClass({ GTypeName: 'AdwStorybookBreakpointBin' }, BreakpointBinStory);
+    }
+
+    constructor() {
+        super(StoryWidget.fromMeta(BreakpointBinStory.getMetadata(), 'Default'));
+    }
+
+    static getMetadata(): StoryMeta {
+        return { ...breakpointBinMeta, component: Adw.BreakpointBin.$gtype };
+    }
+
+    initialize(): void {
+        this._label = new Gtk.Label({ label: this.args.wideLabel as string, ellipsize: 3 /* PANGO_ELLIPSIZE_END */ });
+        this._label.add_css_class('title-1');
+        this._bin = new Adw.BreakpointBin();
+        // The C's own advice: a bin carrying breakpoints has no minimum size, so the stage
+        // is what decides how much room there is (adw-breakpoint-bin.c:57-61).
+        this._bin.set_size_request(150, 60);
+        this._bin.set_child(this._label);
+
+        this._apply();
+        this.addContent(this._bin);
+    }
+
+    updateArgs(_args: StoryArgs): void {
+        this._apply();
+    }
+
+    /** Rebuild the one breakpoint from the controls, then re-add it to the bin. */
+    private _apply(): void {
+        if (!this._bin || !this._label) return;
+        const condition = Adw.BreakpointCondition.parse(this.args.condition as string);
+        if (condition === null) return;
+        if (this._breakpoint !== null) this._bin.remove_breakpoint(this._breakpoint);
+        this._breakpoint = Adw.Breakpoint.new(condition);
+        this._breakpoint.add_setter(this._label, 'label', this.args.narrowLabel as string);
+        this._bin.add_breakpoint(this._breakpoint);
+        // The wide value is what the markup declared, so a rebuild restores to it rather
+        // than to whatever the previous breakpoint left behind.
+        this._label.label = this.args.wideLabel as string;
+    }
+}
+
+GObject.type_ensure(BreakpointBinStory.$gtype);
+
+export const BreakpointBinStories: StoryModule = { stories: [BreakpointBinStory] };

package/src/layout/center-box.meta.ts

@@ -0,0 +1,26 @@
+// Shared, renderer-agnostic metadata for the Center Box story. Imported by the GTK
+// renderer (center-box.story.ts) and the browser renderer
+// (browser/layout/center-box.web.ts), so both expose identical controls.
+
+import { ControlType, type StoryMeta } from '@gjsify/stories';
+
+export const centerBoxMeta: StoryMeta = {
+    title: 'Layout/Center Box',
+    description:
+        'Gtk.CenterBox — three widgets, pinned to the start, the centre and the end, with the space between ' +
+        'them going to whichever child can grow. shrink-center-last decides who gives up space first.',
+    controls: [
+        { name: 'shrinkCenterLast', label: 'Shrink center last', type: ControlType.BOOLEAN, defaultValue: true },
+        {
+            name: 'baselinePosition',
+            label: 'Baseline position',
+            type: ControlType.SELECT,
+            options: [
+                { label: 'Top', value: 'top' },
+                { label: 'Center', value: 'center' },
+                { label: 'Bottom', value: 'bottom' },
+            ],
+            defaultValue: 'center',
+        },
+    ],
+};

package/src/layout/center-box.story.ts

@@ -0,0 +1,54 @@
+// Gtk.CenterBox — three widgets pinned start, centre, end.
+// 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 { centerBoxMeta } from './center-box.meta.js';
+
+/** `Gtk.BaselinePosition`'s three members, by the nick the shared meta carries. */
+const BASELINE_POSITIONS: Record<string, Gtk.BaselinePosition> = {
+    top: Gtk.BaselinePosition.TOP,
+    center: Gtk.BaselinePosition.CENTER,
+    bottom: Gtk.BaselinePosition.BOTTOM,
+};
+
+/** Story: a Gtk.CenterBox whose three slots are filled and whose two properties bind args. */
+export class CenterBoxStory extends StoryWidget {
+    private _box: Gtk.CenterBox | null = null;
+
+    static {
+        GObject.registerClass({ GTypeName: 'AdwStorybookCenterBox' }, CenterBoxStory);
+    }
+
+    constructor() {
+        super(StoryWidget.fromMeta(CenterBoxStory.getMetadata(), 'Default'));
+    }
+
+    static getMetadata(): StoryMeta {
+        return { ...centerBoxMeta, component: Gtk.CenterBox.$gtype };
+    }
+
+    initialize(): void {
+        this._box = new Gtk.CenterBox({ margin_top: 12, margin_bottom: 12, margin_start: 12, margin_end: 12 });
+        this._box.set_start_widget(new Gtk.Label({ label: 'Start', hexpand: false }));
+        this._box.set_center_widget(new Gtk.Label({ label: 'Centre', hexpand: true }));
+        this._box.set_end_widget(new Gtk.Label({ label: 'End', hexpand: false }));
+        this._apply();
+        this.addContent(this._box);
+    }
+
+    updateArgs(_args: StoryArgs): void {
+        this._apply();
+    }
+
+    private _apply(): void {
+        if (!this._box) return;
+        this._box.shrinkCenterLast = this.args.shrinkCenterLast as boolean;
+        this._box.baselinePosition = BASELINE_POSITIONS[this.args.baselinePosition as string];
+    }
+}
+
+GObject.type_ensure(CenterBoxStory.$gtype);
+
+export const CenterBoxStories: StoryModule = { stories: [CenterBoxStory] };

package/src/layout/clamp-scrollable.meta.ts

@@ -0,0 +1,30 @@
+// Shared, renderer-agnostic metadata for the Clamp Scrollable story.
+
+import { ControlType, type StoryMeta } from '@gjsify/stories';
+
+export const clampScrollableMeta: StoryMeta = {
+    title: 'Layout/Clamp Scrollable',
+    description:
+        'Adw.ClampScrollable — a clamp whose child scrolls. The scrollbar stays at the edge of the window while ' +
+        'the content is held at a maximum width.',
+    controls: [
+        {
+            name: 'maximumSize',
+            label: 'Maximum size',
+            type: ControlType.RANGE,
+            min: 200,
+            max: 600,
+            step: 10,
+            defaultValue: 400,
+        },
+        {
+            name: 'tighteningThreshold',
+            label: 'Tightening threshold',
+            type: ControlType.RANGE,
+            min: 100,
+            max: 600,
+            step: 10,
+            defaultValue: 300,
+        },
+    ],
+};

package/src/layout/clamp-scrollable.story.ts

@@ -0,0 +1,51 @@
+// Adw.ClampScrollable — a clamp around a scrolling 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 { clampScrollableMeta } from './clamp-scrollable.meta.js';
+
+const LINES = Array.from({ length: 24 }, (_, i) => `Line ${i + 1}: held at the clamp's width while it scrolls.`);
+
+/** Story: a Gtk.TextView (a Gtk.Scrollable) inside an Adw.ClampScrollable inside a scrolled window. */
+export class ClampScrollableStory extends StoryWidget {
+    private _clamp: Adw.ClampScrollable | null = null;
+
+    static {
+        GObject.registerClass({ GTypeName: 'AdwStorybookClampScrollable' }, ClampScrollableStory);
+    }
+
+    constructor() {
+        super(StoryWidget.fromMeta(ClampScrollableStory.getMetadata(), 'Default'));
+    }
+
+    static getMetadata(): StoryMeta {
+        return { ...clampScrollableMeta, component: Adw.ClampScrollable.$gtype };
+    }
+
+    initialize(): void {
+        const text = new Gtk.TextView({ editable: false, cursorVisible: false, topMargin: 12, bottomMargin: 12 });
+        text.buffer.set_text(LINES.join('\n'), -1);
+
+        this._clamp = new Adw.ClampScrollable({
+            maximumSize: this.args.maximumSize as number,
+            tighteningThreshold: this.args.tighteningThreshold as number,
+            child: text,
+        });
+
+        const scrolled = new Gtk.ScrolledWindow({ child: this._clamp, widthRequest: 640, heightRequest: 240 });
+        this.addContent(scrolled);
+    }
+
+    updateArgs(_args: StoryArgs): void {
+        if (!this._clamp) return;
+        this._clamp.maximumSize = this.args.maximumSize as number;
+        this._clamp.tighteningThreshold = this.args.tighteningThreshold as number;
+    }
+}
+
+GObject.type_ensure(ClampScrollableStory.$gtype);
+
+export const ClampScrollableStories: StoryModule = { stories: [ClampScrollableStory] };

package/src/layout/expander.meta.ts

@@ -0,0 +1,30 @@
+// Shared, renderer-agnostic metadata for the Expander story. Imported by the GTK renderer
+// (expander.story.ts) and the browser renderer (browser/layout/expander.web.ts), so both
+// expose identical controls.
+
+import { ControlType, type StoryMeta } from '@gjsify/stories';
+
+export const expanderMeta: StoryMeta = {
+    title: 'Layout/Expander',
+    description:
+        'Gtk.Expander — a title the user clicks to reveal the child below it. The arrow is its ' +
+        'own CSS node and `:checked` is set on THAT node, not on the widget, which is what ' +
+        "libadwaita's _expanders.scss keys the glyph swap on. `use-underline` marks a mnemonic " +
+        'with `_`, and Alt+that character activates the expander.',
+    controls: [
+        { name: 'expanded', label: 'Expanded', type: ControlType.BOOLEAN, defaultValue: false },
+        { name: 'useUnderline', label: 'Label marks a mnemonic', type: ControlType.BOOLEAN, defaultValue: false },
+        {
+            name: 'label',
+            label: 'Label',
+            type: ControlType.TEXT,
+            defaultValue: '_More options',
+        },
+        {
+            name: 'resizeToplevel',
+            label: 'Resize the toplevel',
+            type: ControlType.BOOLEAN,
+            defaultValue: false,
+        },
+    ],
+};

package/src/layout/expander.story.ts

@@ -0,0 +1,62 @@
+// Gtk.Expander — the disclosure, with the label's mnemonic and the toplevel-resize flag.
+// 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 { expanderMeta } from './expander.meta.js';
+
+/** Story: a Gtk.Expander over a small box of rows. */
+export class ExpanderStory extends StoryWidget {
+    private _expander: Gtk.Expander | null = null;
+
+    static {
+        GObject.registerClass({ GTypeName: 'AdwStorybookExpander' }, ExpanderStory);
+    }
+
+    constructor() {
+        super(StoryWidget.fromMeta(ExpanderStory.getMetadata(), 'Default'));
+    }
+
+    static getMetadata(): StoryMeta {
+        return { ...expanderMeta, component: Gtk.Expander.$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,
+        });
+        for (const line of ['Notifications', 'Sound', 'Network']) {
+            content.append(new Gtk.Label({ label: line }));
+        }
+
+        this._expander = new Gtk.Expander();
+        this._expander.set_child(content);
+        this._apply();
+        this.addContent(this._expander);
+    }
+
+    updateArgs(_args: StoryArgs): void {
+        this._apply();
+    }
+
+    private _apply(): void {
+        if (!this._expander) return;
+        // `set_label` builds a real GtkLabel out of the string with `use_underline` and
+        // `use_markup` forwarded to it (gtkexpander.c:974-979), so the two flags are set
+        // BEFORE the text — the order the C's own docs give.
+        this._expander.use_underline = this.args.useUnderline as boolean;
+        this._expander.label = String(this.args.label);
+        this._expander.resize_toplevel = this.args.resizeToplevel as boolean;
+        this._expander.expanded = this.args.expanded as boolean;
+    }
+}
+
+GObject.type_ensure(ExpanderStory.$gtype);
+
+export const ExpanderStories: StoryModule = { stories: [ExpanderStory] };

package/src/layout/fixed.meta.ts

@@ -0,0 +1,16 @@
+// Shared, renderer-agnostic metadata for the Fixed story. Imported by the GTK
+// renderer (fixed.story.ts) and the browser renderer (browser/layout/fixed.web.ts),
+// so both expose identical controls.
+
+import { ControlType, type StoryMeta } from '@gjsify/stories';
+
+export const fixedMeta: StoryMeta = {
+    title: 'Layout/Fixed',
+    description:
+        'Gtk.Fixed — children at pixel positions, which is the whole of its API: it declares no property of ' +
+        'its own. The two offsets are the arguments of gtk_fixed_put().',
+    controls: [
+        { name: 'offsetX', label: 'Offset x', type: ControlType.RANGE, min: 0, max: 80, step: 4, defaultValue: 24 },
+        { name: 'offsetY', label: 'Offset y', type: ControlType.RANGE, min: 0, max: 80, step: 4, defaultValue: 16 },
+    ],
+};

package/src/layout/fixed.story.ts

@@ -0,0 +1,54 @@
+// Gtk.Fixed — children at pixel positions.
+// 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 { fixedMeta } from './fixed.meta.js';
+
+/** Story: two labels in a Gtk.Fixed, both moved to the offsets the args carry. */
+export class FixedStory extends StoryWidget {
+    private _fixed: Gtk.Fixed | null = null;
+    private _first: Gtk.Label | null = null;
+    private _second: Gtk.Label | null = null;
+
+    static {
+        GObject.registerClass({ GTypeName: 'AdwStorybookFixed' }, FixedStory);
+    }
+
+    constructor() {
+        super(StoryWidget.fromMeta(FixedStory.getMetadata(), 'Default'));
+    }
+
+    static getMetadata(): StoryMeta {
+        return { ...fixedMeta, component: Gtk.Fixed.$gtype };
+    }
+
+    initialize(): void {
+        this._fixed = new Gtk.Fixed();
+        this._first = new Gtk.Label({ label: 'at (x, y)' });
+        this._second = new Gtk.Label({ label: 'at (x + 96, y + 40)' });
+        this._fixed.put(this._first, 0, 0);
+        this._fixed.put(this._second, 0, 0);
+        this._apply();
+        this.addContent(this._fixed);
+    }
+
+    updateArgs(_args: StoryArgs): void {
+        this._apply();
+    }
+
+    private _apply(): void {
+        if (!this._fixed || !this._first || !this._second) return;
+        const x = this.args.offsetX as number;
+        const y = this.args.offsetY as number;
+        // `move` rather than `put`: both children are already in this fixed, and GTK's
+        // `gtk_fixed_move` is the method that only relocates.
+        this._fixed.move(this._first, x, y);
+        this._fixed.move(this._second, x + 96, y + 40);
+    }
+}
+
+GObject.type_ensure(FixedStory.$gtype);
+
+export const FixedStories: StoryModule = { stories: [FixedStory] };

package/src/layout/frame.meta.ts

@@ -0,0 +1,24 @@
+// Shared, renderer-agnostic metadata for the Frame story. Imported by the GTK
+// renderer (frame.story.ts) and the browser renderer (browser/layout/frame.web.ts),
+// so both expose identical controls.
+
+import { ControlType, type StoryMeta } from '@gjsify/stories';
+
+export const frameMeta: StoryMeta = {
+    title: 'Layout/Frame',
+    description:
+        'Gtk.Frame — a 1px border with a label embedded in its top edge. GTK draws the label as its own ' +
+        'widget above the child, and label-xalign says where across the frame it sits.',
+    controls: [
+        { name: 'label', label: 'Label', type: ControlType.TEXT, defaultValue: 'Details' },
+        {
+            name: 'labelXalign',
+            label: 'Label xalign',
+            type: ControlType.RANGE,
+            defaultValue: 0,
+            min: 0,
+            max: 1,
+            step: 0.5,
+        },
+    ],
+};

package/src/layout/frame.story.ts

@@ -0,0 +1,51 @@
+// Gtk.Frame — a 1px border with a label in its top edge.
+// 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 { frameMeta } from './frame.meta.js';
+
+/** Story: a Gtk.Frame with its label text and label alignment bound to args. */
+export class FrameStory extends StoryWidget {
+    private _frame: Gtk.Frame | null = null;
+
+    static {
+        GObject.registerClass({ GTypeName: 'AdwStorybookFrame' }, FrameStory);
+    }
+
+    constructor() {
+        super(StoryWidget.fromMeta(FrameStory.getMetadata(), 'Default'));
+    }
+
+    static getMetadata(): StoryMeta {
+        return { ...frameMeta, component: Gtk.Frame.$gtype };
+    }
+
+    initialize(): void {
+        this._frame = new Gtk.Frame({ halign: Gtk.Align.CENTER });
+        const body = new Gtk.Label({ label: 'A framed region: the label sits in the top edge of the border.' });
+        body.set_margin_top(12);
+        body.set_margin_bottom(12);
+        body.set_margin_start(12);
+        body.set_margin_end(12);
+        this._frame.set_child(body);
+        this._apply();
+        this.addContent(this._frame);
+    }
+
+    updateArgs(_args: StoryArgs): void {
+        this._apply();
+    }
+
+    private _apply(): void {
+        if (!this._frame) return;
+        this._frame.label = this.args.label as string;
+        // `gtk_frame_set_label_align` clamps to 0…1, exactly as the pspec does.
+        this._frame.set_label_align(this.args.labelXalign as number);
+    }
+}
+
+GObject.type_ensure(FrameStory.$gtype);
+
+export const FrameStories: StoryModule = { stories: [FrameStory] };