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

package/src/controls/level-bar.story.ts

@@ -0,0 +1,58 @@
+// Gtk.LevelBar — a level over a real interval, continuous or in blocks.
+// 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 { levelBarMeta } from './level-bar.meta.js';
+
+/** Story: a Gtk.LevelBar with interval, mode, orientation and `inverted` bound to args. */
+export class LevelBarStory extends StoryWidget {
+    private _box: Gtk.Box | null = null;
+    private _bar: Gtk.LevelBar | null = null;
+
+    static {
+        GObject.registerClass({ GTypeName: 'AdwStorybookLevelBar' }, LevelBarStory);
+    }
+
+    constructor() {
+        super(StoryWidget.fromMeta(LevelBarStory.getMetadata(), 'Default'));
+    }
+
+    static getMetadata(): StoryMeta {
+        return { ...levelBarMeta, component: Gtk.LevelBar.$gtype };
+    }
+
+    initialize(): void {
+        this._bar = new Gtk.LevelBar();
+        // A horizontal bar has no intrinsic width of its own, so the story gives it one;
+        // the vertical one needs a HEIGHT instead, and the box is what decides which.
+        this._box = new Gtk.Box({ halign: Gtk.Align.CENTER, valign: Gtk.Align.CENTER });
+        this._box.append(this._bar);
+        this._apply();
+        this.addContent(this._box);
+    }
+
+    updateArgs(_args: StoryArgs): void {
+        this._apply();
+    }
+
+    private _apply(): void {
+        if (!this._bar) return;
+        const vertical = this.args.orientation === 'vertical';
+        this._bar.orientation = vertical ? Gtk.Orientation.VERTICAL : Gtk.Orientation.HORIZONTAL;
+        this._bar.widthRequest = vertical ? 0 : 200;
+        this._bar.heightRequest = vertical ? 120 : 0;
+        // The ORDER is the C's: a new `max-value` drags `value` down and clamps every
+        // offset into the new interval (gtklevelbar.c:1229-1234), so `value` goes second.
+        this._bar.max_value = this.args.maxValue as number;
+        this._bar.mode =
+            (this.args.mode as string) === 'discrete' ? Gtk.LevelBarMode.DISCRETE : Gtk.LevelBarMode.CONTINUOUS;
+        this._bar.value = this.args.value as number;
+        this._bar.inverted = this.args.inverted as boolean;
+    }
+}
+
+GObject.type_ensure(LevelBarStory.$gtype);
+
+export const LevelBarStories: StoryModule = { stories: [LevelBarStory] };

package/src/controls/password-entry.meta.ts

@@ -0,0 +1,18 @@
+// Shared, renderer-agnostic metadata for the Password Entry story. Imported by the GTK
+// renderer (password-entry.story.ts) and the browser renderer
+// (browser/controls/password-entry.web.ts), so both expose identical controls.
+
+import { ControlType, type StoryMeta } from '@gjsify/stories';
+
+export const passwordEntryMeta: StoryMeta = {
+    title: 'Controls/Password Entry',
+    description:
+        'Gtk.PasswordEntry — a field for a secret: masked, no copy, a Caps Lock warning while it has focus, ' +
+        'and show-peek-icon for a button that reveals it for one look. Adw.PasswordEntryRow is the ' +
+        'boxed-list row built on it. Press the peek button, or Caps Lock on the keyboard, to see both states.',
+    controls: [
+        { name: 'showPeekIcon', label: 'Show peek icon', type: ControlType.BOOLEAN, defaultValue: true },
+        { name: 'placeholderText', label: 'Placeholder', type: ControlType.TEXT, defaultValue: 'Password' },
+        { name: 'disabled', label: 'Disabled', type: ControlType.BOOLEAN, defaultValue: false },
+    ],
+};

package/src/controls/password-entry.story.ts

@@ -0,0 +1,54 @@
+// Gtk.PasswordEntry — the masked field, its peek button and its Caps Lock warning.
+// 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 { passwordEntryMeta } from './password-entry.meta.js';
+
+/**
+ * Story: a Gtk.PasswordEntry with its peek button, its placeholder and its sensitivity.
+ *
+ * The two states a reader cannot reach from a control are reached from the keyboard and the
+ * mouse instead, which is where they live in C as well: the reveal is the peek button
+ * (`gtk_password_entry_toggle_peek`) and the Caps Lock warning is read off the device
+ * (`gdk_device_get_caps_lock_state`), with no `Gtk.PasswordEntry` property behind either.
+ */
+export class PasswordEntryStory extends StoryWidget {
+    private _entry: Gtk.PasswordEntry | null = null;
+
+    static {
+        GObject.registerClass({ GTypeName: 'AdwStorybookPasswordEntry' }, PasswordEntryStory);
+    }
+
+    constructor() {
+        super(StoryWidget.fromMeta(PasswordEntryStory.getMetadata(), 'Default'));
+    }
+
+    static getMetadata(): StoryMeta {
+        return { ...passwordEntryMeta, component: Gtk.PasswordEntry.$gtype };
+    }
+
+    initialize(): void {
+        this._entry = new Gtk.PasswordEntry({ showPeekIcon: true, widthRequest: 240, halign: Gtk.Align.CENTER });
+        this._apply();
+        this.addContent(this._entry);
+    }
+
+    updateArgs(_args: StoryArgs): void {
+        this._apply();
+    }
+
+    private _apply(): void {
+        if (!this._entry) return;
+        this._entry.show_peek_icon = this.args.showPeekIcon as boolean;
+        this._entry.placeholder_text = this.args.placeholderText as string;
+        // `sensitive`, not `editable`: a sensitive widget greys out, which is what the
+        // browser rendering spells `disabled` — the same divergence the Entry story records.
+        this._entry.sensitive = !(this.args.disabled as boolean);
+    }
+}
+
+GObject.type_ensure(PasswordEntryStory.$gtype);
+
+export const PasswordEntryStories: StoryModule = { stories: [PasswordEntryStory] };

package/src/controls/progress-bar.meta.ts

@@ -0,0 +1,20 @@
+// Shared, renderer-agnostic metadata for the Progress Bar story. Imported by the GTK
+// renderer (progress-bar.story.ts) and the browser renderer
+// (browser/controls/progress-bar.web.ts), so both expose identical controls.
+
+import { ControlType, type StoryMeta } from '@gjsify/stories';
+
+export const progressBarMeta: StoryMeta = {
+    title: 'Controls/Progress Bar',
+    description:
+        'Gtk.ProgressBar — how much of a long operation is done. `fraction` is 0…1, `pulsing` is the ' +
+        'indeterminate mode where the app knows it is busy but not how far along it is, and `osd` is ' +
+        "libadwaita's hairline variant for under a header bar. Adw.Spinner is the size-less sibling.",
+    controls: [
+        { name: 'fraction', label: 'Fraction', type: ControlType.RANGE, min: 0, max: 1, step: 0.05, defaultValue: 0.4 },
+        { name: 'pulsing', label: 'Pulsing (indeterminate)', type: ControlType.BOOLEAN, defaultValue: false },
+        { name: 'showText', label: 'Show text', type: ControlType.BOOLEAN, defaultValue: true },
+        { name: 'inverted', label: 'Inverted', type: ControlType.BOOLEAN, defaultValue: false },
+        { name: 'osd', label: 'OSD (hairline)', type: ControlType.BOOLEAN, defaultValue: false },
+    ],
+};

package/src/controls/progress-bar.story.ts

@@ -0,0 +1,53 @@
+// Gtk.ProgressBar — determinate progress, indeterminate pulse, and the .osd variant.
+// 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 { progressBarMeta } from './progress-bar.meta.js';
+
+/** Story: a Gtk.ProgressBar with fraction, pulse, text and the `.osd` style class. */
+export class ProgressBarStory extends StoryWidget {
+    private _box: Gtk.Box | null = null;
+    private _bar: Gtk.ProgressBar | null = null;
+
+    static {
+        GObject.registerClass({ GTypeName: 'AdwStorybookProgressBar' }, ProgressBarStory);
+    }
+
+    constructor() {
+        super(StoryWidget.fromMeta(ProgressBarStory.getMetadata(), 'Default'));
+    }
+
+    static getMetadata(): StoryMeta {
+        return { ...progressBarMeta, component: Gtk.ProgressBar.$gtype };
+    }
+
+    initialize(): void {
+        this._bar = new Gtk.ProgressBar();
+        this._box = new Gtk.Box({ spacing: 12, halign: Gtk.Align.CENTER });
+        this._box.append(this._bar);
+        this._apply();
+        this.addContent(this._box);
+    }
+
+    updateArgs(_args: StoryArgs): void {
+        this._apply();
+    }
+
+    private _apply(): void {
+        if (!this._bar) return;
+        // Order is GTK's: setting `fraction` LEAVES activity mode (gtkprogressbar.c:791),
+        // `pulse()` enters it, so a pulsing bar is the one that was pulsed last.
+        if (this.args.pulsing as boolean) this._bar.pulse();
+        else this._bar.set_fraction(this.args.fraction as number);
+        this._bar.show_text = this.args.showText as boolean;
+        this._bar.inverted = this.args.inverted as boolean;
+        if (this.args.osd as boolean) this._bar.add_css_class('osd');
+        else this._bar.remove_css_class('osd');
+    }
+}
+
+GObject.type_ensure(ProgressBarStory.$gtype);
+
+export const ProgressBarStories: StoryModule = { stories: [ProgressBarStory] };

package/src/controls/scale.meta.ts

@@ -0,0 +1,47 @@
+// Shared, renderer-agnostic metadata for the Scale story. Imported by the GTK
+// renderer (scale.story.ts) and the browser renderer (browser/controls/scale.web.ts),
+// so both expose identical controls.
+
+import { ControlType, type StoryMeta } from '@gjsify/stories';
+
+export const scaleMeta: StoryMeta = {
+    title: 'Controls/Scale',
+    description:
+        'Gtk.Scale — a slider. Gtk.Scale extends Gtk.Range, which is abstract: the range itself has no tag, ' +
+        'its adjustment, value, inverted and fill level are this widget’s properties. draw-value shows the ' +
+        'number beside the knob at the value-pos you name, and the .value style class dims it.',
+    controls: [
+        {
+            name: 'orientation',
+            label: 'Orientation',
+            type: ControlType.SELECT,
+            options: [
+                { label: 'Horizontal', value: 'horizontal' },
+                { label: 'Vertical', value: 'vertical' },
+            ],
+            defaultValue: 'horizontal',
+        },
+        {
+            name: 'valuePos',
+            label: 'Value position',
+            type: ControlType.SELECT,
+            options: [
+                { label: 'Top', value: 'top' },
+                { label: 'Bottom', value: 'bottom' },
+                { label: 'Left', value: 'left' },
+                { label: 'Right', value: 'right' },
+            ],
+            defaultValue: 'top',
+        },
+        { name: 'drawValue', label: 'Draw value', type: ControlType.BOOLEAN, defaultValue: true },
+        { name: 'digits', label: 'Digits', type: ControlType.NUMBER, defaultValue: 0 },
+        { name: 'inverted', label: 'Inverted', type: ControlType.BOOLEAN, defaultValue: false },
+        { name: 'hasOrigin', label: 'Has origin', type: ControlType.BOOLEAN, defaultValue: true },
+        {
+            name: 'value',
+            label: 'Value',
+            type: ControlType.NUMBER,
+            defaultValue: 40,
+        },
+    ],
+};

package/src/controls/scale.story.ts

@@ -0,0 +1,66 @@
+// Gtk.Scale — the slider, with its adjustment, its value text and the properties that
+// shape both.
+// 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 { scaleMeta } from './scale.meta.js';
+
+/** Story: a Gtk.Scale over 0…100, with the value text, the digits and the origin bound to args. */
+export class ScaleStory extends StoryWidget {
+    private _scale: Gtk.Scale | null = null;
+    private _adjustment: Gtk.Adjustment | null = null;
+
+    static {
+        GObject.registerClass({ GTypeName: 'AdwStorybookScale' }, ScaleStory);
+    }
+
+    constructor() {
+        super(StoryWidget.fromMeta(ScaleStory.getMetadata(), 'Default'));
+    }
+
+    static getMetadata(): StoryMeta {
+        return { ...scaleMeta, component: Gtk.Scale.$gtype };
+    }
+
+    initialize(): void {
+        this._adjustment = new Gtk.Adjustment({ value: 40, lower: 0, upper: 100, stepIncrement: 1, pageIncrement: 10 });
+        this._scale = new Gtk.Scale({
+            adjustment: this._adjustment,
+            digits: 0,
+            drawValue: true,
+            widthRequest: 260,
+            valign: Gtk.Align.CENTER,
+        });
+        this._apply();
+        this.addContent(this._scale);
+    }
+
+    updateArgs(_args: StoryArgs): void {
+        this._apply();
+    }
+
+    private _apply(): void {
+        if (!this._scale || !this._adjustment) return;
+        this._scale.orientation =
+            this.args.orientation === 'vertical' ? Gtk.Orientation.VERTICAL : Gtk.Orientation.HORIZONTAL;
+        // `Gtk.PositionType` is an enum, so the nick the meta offers is translated here.
+        const positions: Record<string, Gtk.PositionType> = {
+            top: Gtk.PositionType.TOP,
+            bottom: Gtk.PositionType.BOTTOM,
+            left: Gtk.PositionType.LEFT,
+            right: Gtk.PositionType.RIGHT,
+        };
+        this._scale.value_pos = positions[this.args.valuePos as string] ?? Gtk.PositionType.TOP;
+        this._scale.draw_value = this.args.drawValue as boolean;
+        this._scale.digits = this.args.digits as number;
+        this._scale.inverted = this.args.inverted as boolean;
+        this._scale.has_origin = this.args.hasOrigin as boolean;
+        this._adjustment.set_value(this.args.value as number);
+    }
+}
+
+GObject.type_ensure(ScaleStory.$gtype);
+
+export const ScaleStories: StoryModule = { stories: [ScaleStory] };

package/src/controls/search-entry.meta.ts

@@ -0,0 +1,18 @@
+// Shared, renderer-agnostic metadata for the Search Entry story. Imported by the GTK
+// renderer (search-entry.story.ts) and the browser renderer
+// (browser/controls/search-entry.web.ts), so both expose identical controls.
+
+import { ControlType, type StoryMeta } from '@gjsify/stories';
+
+export const searchEntryMeta: StoryMeta = {
+    title: 'Controls/Search Entry',
+    description:
+        'Gtk.SearchEntry — a field for typing a query. A search glyph leads while it is empty and a clear ' +
+        'button follows once it is not, and search-changed waits out search-delay so a filter is not driven ' +
+        'by every keystroke. Escape is stop-search, Ctrl+G is next-match.',
+    controls: [
+        { name: 'searchDelay', label: 'Search delay (ms)', type: ControlType.NUMBER, defaultValue: 150 },
+        { name: 'placeholderText', label: 'Placeholder', type: ControlType.TEXT, defaultValue: 'Search…' },
+        { name: 'disabled', label: 'Disabled', type: ControlType.BOOLEAN, defaultValue: false },
+    ],
+};

package/src/controls/search-entry.story.ts

@@ -0,0 +1,57 @@
+// Gtk.SearchEntry — the query field, its clear button and its delayed search-changed.
+// 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 { searchEntryMeta } from './search-entry.meta.js';
+
+/** Story: a Gtk.SearchEntry with its placeholder, its search delay and the last signal it emitted. */
+export class SearchEntryStory extends StoryWidget {
+    private _entry: Gtk.SearchEntry | null = null;
+    private _label: Gtk.Label | null = null;
+    private _handler = 0;
+
+    static {
+        GObject.registerClass({ GTypeName: 'AdwStorybookSearchEntry' }, SearchEntryStory);
+    }
+
+    constructor() {
+        super(StoryWidget.fromMeta(SearchEntryStory.getMetadata(), 'Default'));
+    }
+
+    static getMetadata(): StoryMeta {
+        return { ...searchEntryMeta, component: Gtk.SearchEntry.$gtype };
+    }
+
+    initialize(): void {
+        this._entry = new Gtk.SearchEntry({ widthRequest: 260, halign: Gtk.Align.CENTER });
+        this._label = new Gtk.Label({ label: 'search-changed has not fired yet' });
+        // The signal is the reason the widget exists, so the story shows that it fires —
+        // and at what delay, which is the control above it.
+        this._handler = this._entry.connect('search-changed', () => {
+            if (this._label) this._label.label = `search-changed: "${this._entry?.text ?? ''}"`;
+        });
+        this._apply();
+        const box = new Gtk.Box({ orientation: Gtk.Orientation.VERTICAL, spacing: 12 });
+        box.append(this._entry);
+        box.append(this._label);
+        this.addContent(box);
+    }
+
+    updateArgs(_args: StoryArgs): void {
+        this._apply();
+    }
+
+    private _apply(): void {
+        if (!this._entry) return;
+        this._entry.search_delay = this.args.searchDelay as number;
+        this._entry.placeholder_text = this.args.placeholderText as string;
+        // `sensitive`, not `editable`, for the same reason the Password Entry story gives.
+        this._entry.sensitive = !(this.args.disabled as boolean);
+    }
+}
+
+GObject.type_ensure(SearchEntryStory.$gtype);
+
+export const SearchEntryStories: StoryModule = { stories: [SearchEntryStory] };

package/src/controls/spin-button.meta.ts

@@ -0,0 +1,40 @@
+// Shared, renderer-agnostic metadata for the Spin Button story. Imported by the GTK
+// renderer (spin-button.story.ts) and the browser renderer
+// (browser/controls/spin-button.web.ts), so both expose identical controls.
+
+import { ControlType, type StoryMeta } from '@gjsify/stories';
+
+export const spinButtonMeta: StoryMeta = {
+    title: 'Controls/Spin Button',
+    description:
+        'Gtk.SpinButton — a number field with an arrow either side of it. The range is a Gtk.Adjustment, the ' +
+        'typed value is clamped into it (or left alone, under update-policy if-valid), and numeric refuses ' +
+        'anything that is not a number. Adw.SpinRow is the boxed-list row that wraps this same widget.',
+    controls: [
+        {
+            name: 'orientation',
+            label: 'Orientation',
+            type: ControlType.SELECT,
+            options: [
+                { label: 'Horizontal', value: 'horizontal' },
+                { label: 'Vertical', value: 'vertical' },
+            ],
+            defaultValue: 'horizontal',
+        },
+        { name: 'digits', label: 'Digits', type: ControlType.NUMBER, defaultValue: 0 },
+        { name: 'numeric', label: 'Numeric', type: ControlType.BOOLEAN, defaultValue: false },
+        { name: 'snapToTicks', label: 'Snap to ticks', type: ControlType.BOOLEAN, defaultValue: false },
+        { name: 'wrap', label: 'Wrap', type: ControlType.BOOLEAN, defaultValue: false },
+        {
+            name: 'updatePolicy',
+            label: 'Update policy',
+            type: ControlType.SELECT,
+            options: [
+                { label: 'Always', value: 'always' },
+                { label: 'If valid', value: 'if-valid' },
+            ],
+            defaultValue: 'always',
+        },
+        { name: 'value', label: 'Value', type: ControlType.NUMBER, defaultValue: 5 },
+    ],
+};

package/src/controls/spin-button.story.ts

@@ -0,0 +1,55 @@
+// Gtk.SpinButton — the number field with its two arrows.
+// 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 { spinButtonMeta } from './spin-button.meta.js';
+
+/** Story: a Gtk.SpinButton over 0…10, with its numeric/snap/wrap/policy switches bound to args. */
+export class SpinButtonStory extends StoryWidget {
+    private _spin: Gtk.SpinButton | null = null;
+    private _adjustment: Gtk.Adjustment | null = null;
+
+    static {
+        GObject.registerClass({ GTypeName: 'AdwStorybookSpinButton' }, SpinButtonStory);
+    }
+
+    constructor() {
+        super(StoryWidget.fromMeta(SpinButtonStory.getMetadata(), 'Default'));
+    }
+
+    static getMetadata(): StoryMeta {
+        return { ...spinButtonMeta, component: Gtk.SpinButton.$gtype };
+    }
+
+    initialize(): void {
+        this._adjustment = new Gtk.Adjustment({ value: 5, lower: 0, upper: 10, stepIncrement: 1, pageIncrement: 2 });
+        this._spin = new Gtk.SpinButton({ adjustment: this._adjustment, digits: 0, halign: Gtk.Align.CENTER });
+        this._apply();
+        this.addContent(this._spin);
+    }
+
+    updateArgs(_args: StoryArgs): void {
+        this._apply();
+    }
+
+    private _apply(): void {
+        if (!this._spin || !this._adjustment) return;
+        this._spin.orientation =
+            this.args.orientation === 'vertical' ? Gtk.Orientation.VERTICAL : Gtk.Orientation.HORIZONTAL;
+        this._spin.digits = this.args.digits as number;
+        this._spin.numeric = this.args.numeric as boolean;
+        this._spin.snap_to_ticks = this.args.snapToTicks as boolean;
+        this._spin.wrap = this.args.wrap as boolean;
+        this._spin.update_policy =
+            this.args.updatePolicy === 'if-valid'
+                ? Gtk.SpinButtonUpdatePolicy.IF_VALID
+                : Gtk.SpinButtonUpdatePolicy.ALWAYS;
+        this._adjustment.set_value(this.args.value as number);
+    }
+}
+
+GObject.type_ensure(SpinButtonStory.$gtype);
+
+export const SpinButtonStories: StoryModule = { stories: [SpinButtonStory] };

package/src/controls/switch.meta.ts

@@ -0,0 +1,18 @@
+// Shared, renderer-agnostic metadata for the Switch story. Imported by the GTK renderer
+// (switch.story.ts) and the browser renderer (browser/controls/switch.web.ts), so both
+// expose identical controls.
+
+import { ControlType, type StoryMeta } from '@gjsify/stories';
+
+export const switchMeta: StoryMeta = {
+    title: 'Controls/Switch',
+    description:
+        'Gtk.Switch — a light switch with two states that are NOT the same thing: active is where the ' +
+        'user put it, state is what the switched thing currently is, which is how a change that takes a ' +
+        'while looks like a pending one. Adw.SwitchRow is the same control with a title beside it.',
+    controls: [
+        { name: 'active', label: 'Active', type: ControlType.BOOLEAN, defaultValue: true },
+        { name: 'state', label: 'State (the backend)', type: ControlType.BOOLEAN, defaultValue: true },
+        { name: 'disabled', label: 'Disabled', type: ControlType.BOOLEAN, defaultValue: false },
+    ],
+};

package/src/controls/switch.story.ts

@@ -0,0 +1,50 @@
+// Gtk.Switch — the light switch, with `active` and `state` shown apart.
+// 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 { switchMeta } from './switch.meta.js';
+
+/** Story: a Gtk.Switch whose `active` and `state` are driven separately, as the C allows. */
+export class SwitchStory extends StoryWidget {
+    private _switch: Gtk.Switch | null = null;
+
+    static {
+        GObject.registerClass({ GTypeName: 'AdwStorybookSwitch' }, SwitchStory);
+    }
+
+    constructor() {
+        super(StoryWidget.fromMeta(SwitchStory.getMetadata(), 'Default'));
+    }
+
+    static getMetadata(): StoryMeta {
+        return { ...switchMeta, component: Gtk.Switch.$gtype };
+    }
+
+    initialize(): void {
+        this._switch = new Gtk.Switch({ halign: Gtk.Align.CENTER });
+        this._apply();
+        this.addContent(this._switch);
+    }
+
+    updateArgs(_args: StoryArgs): void {
+        this._apply();
+    }
+
+    private _apply(): void {
+        if (!this._switch) return;
+        // The ORDER is the story's point. `set_active` also sets `state`, because its
+        // default `::state-set` handler does (gtkswitch.c:800, :558), so `active` goes
+        // first and `state` second: a `state` of false on an `active` of true is the
+        // delayed-change case, where the knob is where the user put it and the trough is
+        // where the thing still is.
+        this._switch.active = this.args.active as boolean;
+        this._switch.state = this.args.state as boolean;
+        this._switch.sensitive = !(this.args.disabled as boolean);
+    }
+}
+
+GObject.type_ensure(SwitchStory.$gtype);
+
+export const SwitchStories: StoryModule = { stories: [SwitchStory] };

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

@@ -0,0 +1,39 @@
+// Shared, renderer-agnostic metadata for the Drag Icon story. Imported by the GTK renderer
+// (drag-icon.story.ts) and the browser renderer (browser/drawing/drag-icon.web.ts), so both
+// expose identical controls.
+
+import { ControlType, type StoryMeta } from '@gjsify/stories';
+
+export const dragIconMeta: StoryMeta = {
+    title: 'Drawing/Drag Icon',
+    description:
+        'Gtk.DragIcon — the widget that follows the pointer while a drag is in flight, and is destroyed ' +
+        'with the drag. No application builds one: `get_for_drag` returns the icon a drag is using, and ' +
+        'the drag source sets its child. What it takes as that child is the interesting part, because ' +
+        '`create_widget_for_value` answers for six kinds of value and a drag source that offers a string ' +
+        'gets a label and one that offers a colour gets a swatch. A drag icon takes no input at all, which ' +
+        "is the C's own note: 'drag icons do not allow user input'.",
+    controls: [
+        {
+            name: 'value',
+            label: 'Value being dragged',
+            type: ControlType.SELECT,
+            options: [
+                { label: 'A string (a Gtk.Label)', value: 'string' },
+                { label: 'A GdkRGBA (a colour swatch)', value: 'rgba' },
+                { label: 'A content provider only (no icon)', value: 'none' },
+            ],
+            defaultValue: 'string',
+        },
+        {
+            name: 'actions',
+            label: 'Drag actions',
+            type: ControlType.SELECT,
+            options: [
+                { label: 'Copy', value: 'copy' },
+                { label: 'Move', value: 'move' },
+            ],
+            defaultValue: 'copy',
+        },
+    ],
+};