@gjsify/adwaita-web 0.56.0 → 0.57.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/adwaita-web",
-    "version": "0.56.0",
+    "version": "0.57.0",
     "description": "Adwaita/Libadwaita web components for browser targets",
     "type": "module",
     "main": "./src/index.ts",
@@ -38,7 +38,8 @@
     ],
     "scripts": {
         "clear": "gjsify clear lib dist tsconfig.tsbuildinfo scss/_icons.generated.scss src/styles.generated.ts",
-        "check": "gjsify run build:scss && gjsify tsc --noEmit",
+        "check": "gjsify run build:scss && gjsify tsc --noEmit && gjsify run check:consumer",
+        "check:consumer": "gjsify tsc -p tsconfig.consumer.json",
         "build": "gjsify run build:scss && gjsify run build:types",
         "build:scss": "node scripts/build-scss.mjs",
         "build:types": "gjsify tsc",
@@ -49,16 +50,17 @@
         "@codemirror/language": "^6.12.4",
         "@codemirror/state": "^6.7.0",
         "@codemirror/view": "^6.43.4",
-        "@gjsify/adwaita-core": "^0.56.0",
-        "@gjsify/adwaita-fonts": "^0.56.0",
-        "@gjsify/adwaita-icons": "^0.56.0",
+        "@gjsify/adwaita-core": "^0.57.0",
+        "@gjsify/adwaita-fonts": "^0.57.0",
+        "@gjsify/adwaita-icons": "^0.57.0",
+        "@gjsify/gtksource-core": "^0.57.0",
         "@lezer/highlight": "^1.2.3"
     },
     "devDependencies": {
-        "@gjsify/blueprint": "^0.56.0",
-        "@gjsify/cli": "^0.56.0",
-        "@gjsify/unit": "^0.56.0",
-        "@gjsify/vite-plugin-blueprint": "^0.56.0",
+        "@gjsify/blueprint": "^0.57.0",
+        "@gjsify/cli": "^0.57.0",
+        "@gjsify/unit": "^0.57.0",
+        "@gjsify/vite-plugin-blueprint": "^0.57.0",
         "sass": "^1.101.0",
         "typescript": "^6.0.3"
     },

package/scss/_reset.scss

@@ -47,7 +47,7 @@ $adw-components:
   gtk-gl-area, gtk-graphics-offload, gtk-grid, gtk-grid-view, gtk-header-bar, gtk-image, gtk-inscription, gtk-label, gtk-level-bar,
   gtk-link-button, gtk-list-box, gtk-list-box-row, gtk-list-view, gtk-media-controls, gtk-menu-button, gtk-overlay, gtk-page-setup-unix-dialog, gtk-paned,
   gtk-password-entry, gtk-picture, gtk-popover, gtk-popover-bin, gtk-popover-menu, gtk-popover-menu-bar, gtk-print-unix-dialog,
-  gtk-progress-bar, gtk-revealer, gtk-scale, gtk-scale-button, gtk-scrollbar, gtk-scrolled-window, gtk-search-bar, gtk-search-entry, gtk-separator,
+  gtk-progress-bar, gtk-revealer, gtk-scale, gtk-scale-button, gtk-scrollbar, gtk-scrolled-window, gtk-search-bar, gtk-search-entry, gtk-separator, gtk-source-view,
   gtk-spin-button, gtk-spinner, gtk-stack, gtk-stack-sidebar, gtk-stack-switcher, gtk-switch, gtk-text, gtk-text-view, gtk-toggle-button, gtk-tree-expander, gtk-video, gtk-viewport,
   gtk-window, gtk-window-controls, gtk-window-handle;
 

package/src/application.spec.ts

@@ -0,0 +1,75 @@
+// ADR 0098: the web port of `Gtk.Application`, held to the shared vectors (real GJS is their oracle,
+// in adwaita-core's `application.gjs.spec.ts`) through real custom elements.
+import {
+    APPLICATION_VECTORS,
+    driveApplicationVectors,
+    unprovenVfuncs,
+    type ApplicationScene,
+    type ApplicationSubject,
+} from '@gjsify/adwaita-core/conformance';
+import { describe, expect, it } from '@gjsify/unit';
+
+import { activateWidgetAction } from './application.js';
+import { Adw, Gio, GObject, Gtk } from './index.js';
+import type { GtkMenuButton } from './elements/gtk-menu-button.js';
+
+const place = <T extends Element>(parent: Element, child: T): T => {
+    parent.append(child);
+    return child;
+};
+
+const made: Element[] = [];
+
+const scene: ApplicationScene = {
+    window(app) {
+        const window = document.createElement('adw-application-window') as Adw.ApplicationWindow;
+        window.application = app;
+        document.body.append(window);
+        made.push(window);
+        return window;
+    },
+    buttonIn: (window) => place(window as Element, document.createElement('gtk-button')),
+    popoverButtonIn(window) {
+        const menuButton = place(window as Element, document.createElement('gtk-menu-button')) as GtkMenuButton;
+        const popover = menuButton.querySelector('gtk-popover') as Element;
+        return place(popover, document.createElement('gtk-button'));
+    },
+    loose: () => document.createElement('gtk-button'),
+    activate: (widget, name) => activateWidgetAction(widget as Element, name),
+    addWindowAction(window, action) {
+        (window as unknown as { add_action(a: object): void }).add_action(action);
+    },
+};
+
+const subject: ApplicationSubject = {
+    name: 'adwaita-web',
+    isOracle: false,
+    GObject: GObject as unknown as ApplicationSubject['GObject'],
+    Application: Gtk.Application as unknown as ApplicationSubject['Application'],
+    SimpleAction: Gio.SimpleAction as unknown as ApplicationSubject['SimpleAction'],
+    handlesOpen: Gio.ApplicationFlags.HANDLES_OPEN,
+    scene,
+};
+
+export const ApplicationTest = async () => {
+    await driveApplicationVectors(subject, { describe, it, expect });
+    // The page is shared with every other suite: a window left in it moves their layout.
+    for (const element of made.splice(0)) element.remove();
+
+    await describe('adwaita-web: Application (ADR 0098 § 3)', async () => {
+        await it('has a vector for every unlocked vfunc', () => {
+            expect(unprovenVfuncs(APPLICATION_VECTORS).length).toBe(0);
+        });
+        await it('Adw.Application is a Gtk.Application', () => {
+            expect(Adw.Application.prototype instanceof Gtk.Application).toBe(true);
+        });
+        await it('quit() takes the windows it added off the page', async () => {
+            const app = new Adw.Application({ application_id: 'org.gjsify.vec.WebQuit' });
+            const window = scene.window(app as never) as Element;
+            app.connect('activate', () => app.quit());
+            await app.runAsync([]);
+            expect(window.isConnected).toBe(false);
+            made.length = 0;
+        });
+    });
+};

package/src/application.ts

@@ -0,0 +1,92 @@
+// `Gio.Application`, `Gtk.Application` and `Adw.Application` on the browser (ADR 0098 §§ 1, 3).
+//
+// The behaviour is the core's (`@gjsify/adwaita-core`); this file is the HOST: when the platform is
+// ready (`DOMContentLoaded`), how a window leaves it, and the walk that resolves `app.` / `win.`
+// from an element. A web page has no process, so `quit()` removes the windows the application
+// added and the tab stays.
+
+import {
+    GioApplicationBase,
+    withGtkApplication,
+    activateWidgetAction as activateIn,
+    activateMenuItem,
+    applicationOfWindow,
+    menuActionsFor,
+    installActionMap,
+    type AdwMenuItem,
+    type AdwMenuActions,
+    type AdwMenuModel,
+    type ApplicationHost,
+} from '@gjsify/adwaita-core';
+
+export const webHost: ApplicationHost = {
+    name: 'adwaita-web',
+    requiresWindow: false,
+    start(body) {
+        return new Promise<void>((resolve) => {
+            const go = (): void => {
+                body();
+                resolve();
+            };
+            if (document.readyState === 'loading') document.addEventListener('DOMContentLoaded', go, { once: true });
+            else go();
+        });
+    },
+    detach(window) {
+        (window as Element).remove();
+    },
+    exit() {},
+};
+
+/** An element's parent for action resolution; a popover is rooted at the widget that owns it. */
+export function parentOfElement(node: object): object | null {
+    if (!(node instanceof Element)) return null;
+    const anchor = (node as { anchor?: unknown }).anchor;
+    return anchor instanceof Element ? anchor : node.parentElement;
+}
+
+/** What a `Gtk.Actionable` does on activation: the action `prefix.name` found from `widget`. */
+export function activateWidgetAction(widget: Element, fullName: string, parameter: unknown = null): boolean {
+    return activateIn(widget, fullName, parentOfElement, parameter);
+}
+
+/** What the items of `model` read from the actions registered above `el` (ADR 0097 § 3). */
+export function menuActionsOfElement(el: Element, model: AdwMenuModel): AdwMenuActions {
+    return menuActionsFor(model, el, parentOfElement);
+}
+
+/** What choosing `item` in a menu owned by `el` does: the action it names fires. */
+export function activateElementMenuItem(el: Element, item: AdwMenuItem): boolean {
+    return activateMenuItem(item, el, parentOfElement);
+}
+
+export class GioApplication extends GioApplicationBase {
+    static override host = webHost;
+}
+
+export class GtkApplication extends withGtkApplication(GioApplication) {}
+
+export class AdwApplication extends GtkApplication {}
+
+type WindowApplication = { add_window(window: object): void; remove_window(window: object): void };
+
+/**
+ * `Gtk.Window:application` and the window's `Gio.ActionMap` (`win.` actions) on an element class.
+ * Setting the property is `add_window`, as on GTK; setting it to `null` is `remove_window`.
+ */
+export function defineWindowApplication(proto: object): void {
+    installActionMap(proto);
+    Object.defineProperty(proto, 'application', {
+        configurable: true,
+        enumerable: true,
+        get(this: object) {
+            return applicationOfWindow(this);
+        },
+        set(this: object, value: WindowApplication | null) {
+            const current = applicationOfWindow(this) as unknown as WindowApplication | null;
+            if (current === value) return;
+            current?.remove_window(this);
+            value?.add_window(this);
+        },
+    });
+}

package/src/construct-vectors.spec.ts

@@ -138,6 +138,161 @@ export const AdwConstructVectorsTest = async () => {
                 'plain handlers only',
             );
         });
+        await it('runs a CheckButton `toggled` handler on a click and on a programmatic change', () => {
+            let calls = 0;
+            const { root, unmount } = mountSharedTree(
+                {
+                    tag: 'GtkBox',
+                    children: [
+                        { tag: 'GtkCheckButton', id: 'box', signals: [{ name: 'toggled', handler: 'onToggled' }] },
+                    ],
+                },
+                { scope: { onToggled: () => calls++ } },
+            );
+            try {
+                const box = root.querySelector('#box') as unknown as HTMLElement & { active: boolean };
+                box.click();
+                expect(box.active).toBe(true);
+                box.active = false;
+                expect(calls).toBe(2);
+            } finally {
+                unmount();
+            }
+        });
+        await it('makes a bind follow a CheckButton `active`', () => {
+            const { root, unmount } = mountSharedTree({
+                tag: 'GtkBox',
+                children: [
+                    { tag: 'GtkCheckButton', id: 'box' },
+                    {
+                        tag: 'GtkToggleButton',
+                        id: 'target',
+                        bindings: { active: { source: 'box', property: 'active' } },
+                    },
+                ],
+            });
+            try {
+                const target = root.querySelector('#target') as unknown as { active: boolean };
+                expect(target.active).toBe(false);
+                (root.querySelector('#box') as HTMLElement).click();
+                expect(target.active).toBe(true);
+            } finally {
+                unmount();
+            }
+        });
+        await it('makes a bind follow a Switch `active`', () => {
+            const { root, unmount } = mountSharedTree({
+                tag: 'GtkBox',
+                children: [
+                    { tag: 'GtkSwitch', id: 'source' },
+                    { tag: 'GtkSwitch', id: 'target', bindings: { active: { source: 'source', property: 'active' } } },
+                ],
+            });
+            try {
+                const target = root.querySelector('#target') as unknown as { active: boolean };
+                (root.querySelector('#source') as unknown as { active: boolean }).active = true;
+                expect(target.active).toBe(true);
+            } finally {
+                unmount();
+            }
+        });
+        await it('runs an Entry `changed` and `notify::text` handler on typing and on a programmatic set', () => {
+            const seen: string[] = [];
+            const { root, unmount } = mountSharedTree(
+                {
+                    tag: 'GtkBox',
+                    children: [
+                        {
+                            tag: 'GtkEntry',
+                            id: 'entry',
+                            signals: [
+                                { name: 'changed', handler: 'onChanged' },
+                                { name: 'notify::text', handler: 'onText' },
+                            ],
+                        },
+                    ],
+                },
+                { scope: { onChanged: () => seen.push('changed'), onText: () => seen.push('notify::text') } },
+            );
+            try {
+                const entry = root.querySelector('#entry') as unknown as HTMLElement & {
+                    text: string;
+                    input: HTMLInputElement;
+                };
+                entry.input.value = 'typed';
+                entry.input.dispatchEvent(new Event('input'));
+                entry.text = 'set';
+                entry.text = 'set';
+                expect(seen.join()).toBe('changed,notify::text,changed,notify::text');
+            } finally {
+                unmount();
+            }
+        });
+        await it('dispatches ViewStack `notify::visible-child-name` when the visible page changes', () => {
+            const stack = document.createElement('adw-view-stack') as HTMLElement & {
+                addTitled(c: HTMLElement, name: string, title: string): unknown;
+                visibleChildName: string;
+            };
+            const names: string[] = [];
+            stack.addEventListener('notify::visible-child-name', (e) =>
+                names.push((e as CustomEvent).detail['visible-child-name']),
+            );
+            document.body.append(stack);
+            try {
+                stack.addTitled(document.createElement('div'), 'a', 'A');
+                stack.addTitled(document.createElement('div'), 'b', 'B');
+                stack.visibleChildName = 'b';
+                expect(names.join()).toBe('a,b');
+            } finally {
+                stack.remove();
+            }
+        });
+        await it('dispatches DropDown `notify::selected-item` after `notify::selected`, on a real change only', () => {
+            const dropDown = document.createElement('gtk-drop-down') as HTMLElement & {
+                model: string[];
+                selected: number;
+            };
+            const seen: string[] = [];
+            for (const name of ['notify::selected', 'notify::selected-item'])
+                dropDown.addEventListener(name, () => seen.push(name));
+            document.body.append(dropDown);
+            try {
+                dropDown.model = ['a', 'b'];
+                seen.length = 0;
+                dropDown.selected = 1;
+                dropDown.selected = 1;
+                expect(seen.join()).toBe('notify::selected,notify::selected-item');
+            } finally {
+                dropDown.remove();
+            }
+        });
+        await it('dispatches Stack `notify::visible-child` before `notify::visible-child-name`', () => {
+            const stack = document.createElement('gtk-stack') as HTMLElement & { visibleChildName: string | null };
+            const a = document.createElement('div');
+            a.setAttribute('name', 'a');
+            const b = document.createElement('div');
+            b.setAttribute('name', 'b');
+            stack.append(a, b);
+            document.body.append(stack);
+            try {
+                const seen: string[] = [];
+                for (const name of ['notify::visible-child', 'notify::visible-child-name'])
+                    stack.addEventListener(name, () => seen.push(name));
+                stack.visibleChildName = 'b';
+                expect(seen.join()).toBe('notify::visible-child,notify::visible-child-name');
+            } finally {
+                stack.remove();
+            }
+        });
+        await it('declares the notify each of DropDown, Stack and Switch dispatches', () => {
+            const declared = (tag: string) =>
+                (customElements.get(tag) as unknown as { signals: Record<string, string> }).signals;
+            expect(declared('gtk-drop-down')['notify::selected']).toBe('notify::selected');
+            expect(declared('gtk-drop-down')['notify::selected-item']).toBe('notify::selected-item');
+            expect(declared('gtk-stack')['notify::visible-child']).toBe('notify::visible-child');
+            expect(declared('gtk-stack')['notify::visible-child-name']).toBe('notify::visible-child-name');
+            expect(declared('gtk-switch')['notify::active']).toBe('notify::active');
+        });
         await it('refuses a bind to an id nothing has, to a source that dispatches no notify, and the flags', () => {
             const bound = (binding: NonNullable<SharedTreeNode['bindings']>[string], sourceTag = 'GtkToggleButton') =>
                 ({

package/src/elements/adw-application-window.ts

@@ -41,8 +41,11 @@ import {
 } from '@gjsify/adwaita-core';
 
 import { AdwWindow } from './adw-window.js';
+import { defineWindowApplication } from '../application.js';
 
 export class AdwApplicationWindow extends AdwWindow {
+    /** `Gtk.Window:application`: setting it is `add_window` (ADR 0098), set by `defineWindowApplication`. */
+    declare application: object | null;
     private _menubarEl: HTMLDivElement | null = null;
     private _model: AdwMenuModel = [];
 
@@ -152,3 +155,5 @@ export class AdwApplicationWindow extends AdwWindow {
 }
 
 customElements.define('adw-application-window', AdwApplicationWindow);
+
+defineWindowApplication(AdwApplicationWindow.prototype);

package/src/elements/adw-split-button.ts

@@ -57,6 +57,7 @@ import type {
     SplitButtonChange,
     SplitButtonDirection,
 } from '@gjsify/adwaita-core';
+import { activateElementMenuItem, menuActionsOfElement } from '../application.js';
 
 import { PopoverMenuView } from './popover-menu.js';
 
@@ -336,6 +337,7 @@ export class AdwSplitButton extends HTMLElement {
         this._menuView = new PopoverMenuView(this._menuEl, 'adw-split-button-menu', (path) => {
             const activated = this._state.activateMenuItem(path);
             if (activated === null) return;
+            activateElementMenuItem(this, activated);
             this.dispatchEvent(
                 new CustomEvent('menu-activated', {
                     bubbles: true,
@@ -525,7 +527,9 @@ export class AdwSplitButton extends HTMLElement {
 
     private _renderMenu(): void {
         this._menuEl.open = this._state.open;
-        this._menuView.setMenuModel(this._state.menuModel ?? []);
+        const model = this._state.menuModel ?? [];
+        this._menuView.setMenuModel(model);
+        this._menuView.setActions(this._actions ?? menuActionsOfElement(this, model));
         this._menuView.render();
     }
 }

package/src/elements/adw-view-stack.ts

@@ -50,9 +50,17 @@
 import { ViewStackState } from '@gjsify/adwaita-core';
 import type { AdwViewStackPageInfo as CorePageInfo, ViewStackStateChange } from '@gjsify/adwaita-core';
 
+import type { DispatchedSignals } from '../signals.js';
+
 export type AdwViewStackPageInfo = CorePageInfo<HTMLElement>;
 
 export class AdwViewStack extends HTMLElement {
+    /** The GTK signals this element dispatches, each with the DOM event it arrives as (ADR 0093). */
+    static readonly signals: DispatchedSignals = {
+        'notify::visible-child': 'notify::visible-child',
+        'notify::visible-child-name': 'notify::visible-child-name',
+    };
+
     private readonly _state = new ViewStackState<HTMLElement>();
     private _initialized = false;
 
@@ -255,6 +263,12 @@ export class AdwViewStack extends HTMLElement {
                 },
             }),
         );
+        this.dispatchEvent(
+            new CustomEvent('notify::visible-child-name', {
+                bubbles: true,
+                detail: { 'visible-child-name': change.name },
+            }),
+        );
     }
 
     private _applyVisibility(): void {

package/src/elements/checks.ts

@@ -87,6 +87,8 @@
 
 import { RadioGroupState, resolveCheckState } from '@gjsify/adwaita-core';
 
+import type { DispatchedSignals } from '../signals.js';
+
 /**
  * The document's radio groups. ONE registry, as global as a bare
  * `<input type="radio" name="x">` outside a form is — two independent groups therefore
@@ -124,6 +126,15 @@ abstract class AdwCheckBase extends HTMLElement {
         this.toggleAttribute('checked', !!value);
     }
 
+    /** `Gtk.CheckButton:active`, the GObject name for {@link checked}. */
+    get active(): boolean {
+        return this.checked;
+    }
+
+    set active(value: boolean) {
+        this.checked = value;
+    }
+
     /** Whether the control is in the third, inconsistent state. */
     get indeterminate(): boolean {
         return this.hasAttribute('indeterminate');
@@ -202,10 +213,17 @@ abstract class AdwCheckBase extends HTMLElement {
             this._label.textContent = this.getAttribute('label') ?? '';
         }
         this.render();
+        if (name === 'active') {
+            // The GObject spelling a projected `.blp` writes; `checked` stays the state.
+            this.checked = this.hasAttribute('active');
+        }
         if (name === 'checked') {
             this.dispatchEvent(
                 new CustomEvent('notify::checked', { bubbles: true, detail: { checked: this.checked } }),
             );
+            // `toggled` fires on every change of `active`, programmatic included.
+            this.dispatchEvent(new CustomEvent('toggled', { bubbles: true }));
+            this.dispatchEvent(new CustomEvent('notify::active', { bubbles: true, detail: { active: this.checked } }));
         }
     }
 
@@ -227,8 +245,14 @@ abstract class AdwCheckBase extends HTMLElement {
 
 /** The Adwaita checkbox — `checkbutton > check` as a custom element. */
 export class GtkCheckButton extends AdwCheckBase {
+    /** The GTK signals this element dispatches, each with the DOM event it arrives as (ADR 0093). */
+    static readonly signals: DispatchedSignals = {
+        toggled: 'toggled',
+        'notify::active': 'notify::active',
+    };
+
     static get observedAttributes() {
-        return ['checked', 'indeterminate', 'disabled', 'label'];
+        return ['checked', 'active', 'indeterminate', 'disabled', 'label'];
     }
 
     protected get inputType(): 'checkbox' {

package/src/elements/gtk-application-window.ts

@@ -26,8 +26,11 @@
 
 import type { AdwSlot } from '../slotted-children.js';
 import { GtkWindow } from './gtk-window.js';
+import { defineWindowApplication } from '../application.js';
 
 export class GtkApplicationWindow extends GtkWindow {
+    /** `Gtk.Window:application`: setting it is `add_window` (ADR 0098), set by `defineWindowApplication`. */
+    declare application: object | null;
     private _menubar: HTMLDivElement | null = null;
     private _menubarObserver: MutationObserver | null = null;
 
@@ -106,3 +109,5 @@ export class GtkApplicationWindow extends GtkWindow {
 }
 
 customElements.define('gtk-application-window', GtkApplicationWindow);
+
+defineWindowApplication(GtkApplicationWindow.prototype);

package/src/elements/gtk-drop-down.ts

@@ -47,6 +47,8 @@
 // Events:
 //   `notify::selected` (CustomEvent, bubbles, detail = { selected }) — the index
 //     changed (mirrors the Gtk.DropDown `notify::selected` GObject signal).
+//   `notify::selected-item` (CustomEvent, bubbles, detail = { 'selected-item' }) — fired
+//     right after `notify::selected`, on the same real change.
 //   `change`           (CustomEvent, bubbles, detail = { index, value, label }) —
 //     a convenience event carrying the full selection. Fires ONLY on a user
 //     pick — `ComboState`'s `interactive` flag is what tells the two apart.
@@ -69,6 +71,7 @@ import { ComboState, normalizeComboOptions, parseListModel } from '@gjsify/adwai
 import type { AdwComboOption, AdwListItemsChanged, AdwListModelInput } from '@gjsify/adwaita-core';
 
 import { bindSlottedChildren } from '../slotted-children.js';
+import type { DispatchedSignals } from '../signals.js';
 import { stringListSlot } from '../string-list-slot.js';
 
 import { createGtkImage } from './gtk-image.js';
@@ -81,6 +84,12 @@ import { createGtkImage } from './gtk-image.js';
 export type GtkDropDownOption = AdwComboOption;
 
 export class GtkDropDown extends HTMLElement {
+    /** The GTK signals this element dispatches, each with the DOM event it arrives as (ADR 0093). */
+    static readonly signals: DispatchedSignals = {
+        'notify::selected': 'notify::selected',
+        'notify::selected-item': 'notify::selected-item',
+    };
+
     private _buttonEl!: HTMLButtonElement;
     private _labelEl!: HTMLSpanElement;
     private _popoverEl!: GtkPopover;
@@ -242,6 +251,13 @@ export class GtkDropDown extends HTMLElement {
             // `notify::selected` mirrors GObject property-notify: EVERY change,
             // programmatic included.
             this.dispatchEvent(new CustomEvent('notify::selected', { bubbles: true, detail: { selected: index } }));
+            // `gtk_drop_down_set_selected` notifies `selected-item` right after `selected`.
+            this.dispatchEvent(
+                new CustomEvent('notify::selected-item', {
+                    bubbles: true,
+                    detail: { 'selected-item': option ?? null },
+                }),
+            );
             // `change` mirrors the DOM <select> contract: ONLY a user-initiated change. A
             // programmatic assignment stays silent, just as native `select.value = x` fires
             // no `change`, so consumers can set the value without guarding against it.