@gjsify/adwaita-web 0.64.12-next.280 → 0.64.12

package/src/elements/adw-combo-row.ts

@@ -1,7 +1,7 @@
-// <adw-combo-row> — row with a title/subtitle and a dropdown select. The model is a JSON
-// array in the `model` attribute (`["a","b"]` or `[{"value":"a","label":"A"}]`), `selected`
-// an index, and the native <select> is stretched invisibly over the row so clicking
-// anywhere opens it.
+// <adw-combo-row> — row with a title/subtitle and a dropdown select. The model is a real
+// `Gio.ListModel` on the PROPERTY and a JSON array in the `model` ATTRIBUTE (`["a","b"]` or
+// `[{"value":"a","label":"A"}]`), `selected` an index, and the native <select> is stretched
+// invisibly over the row so clicking anywhere opens it.
 //
 // The SELECTION state machine (the model, the two-way index↔value mapping, the
 // empty/out-of-range guards and the programmatic-vs-interactive notify split) is HEADLESS
@@ -16,6 +16,13 @@
 // `scripts/check-adwaita-collection-reactivity.mjs` holds the rule for every collection
 // either renderer takes in.
 //
+// THE PROPERTY TAKES A LIST MODEL, THE ATTRIBUTE TAKES JSON (ADR 0122). `model` is an object
+// property over `Gio.ListModel`, held by identity, and an array written to it is a
+// `TypeError`. The ATTRIBUTE is untouched — a `Gio.ListModel` has no attribute spelling — and
+// it fills the element's own `GjsifyOptionList`, whose identity survives an edit so appending
+// one option to `model='[…]'` splices rather than replacing the list and resetting the
+// selection. `readModelWrite` in core is the one door both go through.
+//
 // THE MODEL IS SPLICED, NOT REBUILT (ADR 0046). `ComboState` reports WHERE the model
 // changed — `Gio.ListModel::items-changed`, one splice per assignment — and this element
 // applies exactly that range. Appending one item to a hundred-item model adds ONE
@@ -35,17 +42,16 @@
 // Properties — the `<gtk-drop-down>` set minus `enableSearch` and `active`, which are that
 // element's own popover chrome and have no counterpart on a row that opens a native
 // <select>:
-//   model            — the list model ({ value, label }[]) (get/set). `Adw.ComboRow:model`'s
-//     own name, per ADR 0034 clause 1; it replaced `options`/`items`, which were two
-//     further spellings of one GTK property.
-//   selected         — the selected index (get/set). PERMISSIVE, and this is the one row of
-//     `ComboState`'s contract the two selectors answer differently: an index past the end
-//     is ACCEPTED here and reads back with an empty `selectedValue`/label, where
-//     `<gtk-drop-down>` rejects the set outright (gtk-drop-down.ts). Neither is a bug —
-//     `ComboState.hasIndex` is where the bounds live and why the policy is each
-//     renderer's. Stated here because a consumer of THIS element reads this file.
+//   model            — the list model, a `Gio.ListModel` (get/set), held BY IDENTITY.
+//     `Adw.ComboRow:model`'s own name, per ADR 0034 clause 1; it replaced
+//     `options`/`items`, which were two further spellings of one GTK property. An ARRAY is a
+//     `TypeError` naming the type (ADR 0122 § 4) — `options` is the descriptor side.
+//   options          — the held model's items as `{ value, label }` descriptors (get).
+//   selected         — the selected index (get/set). An index past the end is IGNORED, as
+//     measured in libadwaita and as on `<gtk-drop-down>`; the two selectors no longer
+//     answer this differently. `ComboState.hasIndex` is where the bounds live.
 //   selectedValue    — the selected option's value ('' when empty) (get/set-by-value).
-//   selectedItem     — the selected option descriptor, or null (get).
+//   selectedItem     — the model's own selected item, or null (get).
 // Events:
 //   `notify::selected` (CustomEvent, bubbles, detail = { selected }) — a USER pick.
 //     Deliberately NOT every change, unlike `<gtk-drop-down>`: this row's event has
@@ -58,8 +64,8 @@
 //   title/subtitle text column added to match Adw.ComboRow; the selection state
 //   machine composed from @gjsify/adwaita-core.
 
-import { ComboState, deriveRowLabels, normalizeComboOptions, parseListModel } from '@gjsify/adwaita-core';
-import type { AdwComboOption, AdwListItemsChanged, AdwListModelInput } from '@gjsify/adwaita-core';
+import { ComboState, deriveRowLabels, GjsifyOptionList, parseListModel, readModelWrite } from '@gjsify/adwaita-core';
+import type { AdwComboOption, AdwListItemsChanged, ComboWatchableModel } from '@gjsify/adwaita-core';
 
 import { applyRowTooltip } from '../row-tooltip.js';
 import { bindSlottedChildren } from '../slotted-children.js';
@@ -76,34 +82,58 @@ export class AdwComboRow extends TooltipElement {
     private _subtitleEl!: HTMLSpanElement;
     /** The headless options list + selectedIndex↔selectedValue state machine (ADR 0004). */
     private readonly _state = new ComboState();
+    /**
+     * The list the MARKUP doors fill — the `model` ATTRIBUTE is JSON text and a
+     * `<gtk-string-list slot="model">` child is strings, and a real `Gio.ListModel` has no
+     * spelling in either (ADR 0122 § 5). Held for the element's whole life so re-parsing the
+     * attribute splices the list the element already points at rather than replacing it, which
+     * would reset the selection.
+     */
+    private readonly _authored = GjsifyOptionList.new(null);
     private _initialized = false;
 
     static get observedAttributes() {
         return ['title', 'subtitle', 'model', 'selected', 'tooltip-text', 'title-lines', 'subtitle-lines'];
     }
 
-    /** The list model (`Adw.ComboRow:model`). Setting it splices the <select> and clamps the selection. */
-    get model(): AdwComboOption[] {
+    /**
+     * The list model (`Adw.ComboRow:model`) — the OBJECT that was assigned, by identity, as
+     * `row.model === model` is measured to hold in libadwaita (ADR 0122 § 4). The normalised
+     * descriptors are {@link options}. Assigning splices the `<select>` and re-runs autoselect.
+     */
+    get model(): ComboWatchableModel | null {
         return this._state.model;
     }
 
-    set model(value: AdwListModelInput) {
-        // `setModel` re-runs autoselect, so an index the new model does not have falls
-        // back to 0 — the clamp is core's, exactly as `<gtk-drop-down>` gets it.
-        this._state.setModel(normalizeComboOptions(value));
+    set model(value: ComboWatchableModel | string | null) {
+        // ONE door for every surface: a real model by identity, `null` for none, a STRING for
+        // the `model` attribute (JSON), and a `TypeError` in the property's own words for
+        // anything else, an array included.
+        this._state.setModel(readModelWrite(value, this._authored));
+    }
+
+    /** The held model's items as `{ value, label }` descriptors. */
+    get options(): AdwComboOption[] {
+        return this._state.options;
     }
 
     /** `adw_combo_row_set_model`. */
-    set_model(model: AdwListModelInput | null): void {
-        this.model = model ?? [];
+    set_model(model: ComboWatchableModel | null): void {
+        this.model = model;
+    }
+
+    /** `adw_combo_row_get_model`. */
+    get_model(): ComboWatchableModel | null {
+        return this.model;
     }
 
     /**
-     * The selected index (Adw.ComboRow:selected). PERMISSIVE: an index past the end is
-     * accepted and reads back with an empty {@link selectedValue}, mirroring the `guint`
-     * property that takes any position — where `<gtk-drop-down>` rejects the same set, as
-     * its own docs promise. `ComboState.hasIndex` owns the bounds and records why the
-     * POLICY is each renderer's; `COMBO_SELECTION_VECTORS` drives both answers.
+     * The selected index (Adw.ComboRow:selected). An index past the end is IGNORED — the
+     * selection stays where it was, which is what libadwaita is measured to do (ADR 0122 § 4,
+     * `combo-probe2.js`) and what `<gtk-drop-down>` already did. This element used to ACCEPT
+     * such a set and read back an empty {@link selectedValue}, the one row of
+     * `COMBO_SELECTION_VECTORS` the two selectors answered differently; the permissive half
+     * was ours, not GTK's, and it is gone. `ComboState.hasIndex` owns the bounds.
      */
     get selected(): number {
         return this._initialized ? this._state.selectedIndex : parseInt(this.getAttribute('selected') || '0', 10);
@@ -134,19 +164,21 @@ export class AdwComboRow extends TooltipElement {
     }
 
     set selectedValue(value: string) {
-        const index = this._state.model.findIndex((option) => option.value === value);
+        const index = this._state.options.findIndex((option) => option.value === value);
         if (index >= 0) this.selected = index;
     }
 
     /**
-     * The selected option descriptor, or `null` (Adw.ComboRow:selected-item).
+     * The selected ITEM, or `null` (Adw.ComboRow:selected-item).
      *
-     * Read-only, as the GObject property is. `null` and not a blank descriptor: the
-     * sentinel and an index past the end both address no option, and inventing an empty
-     * one would make "nothing is selected" indistinguishable from an option with no text.
+     * Read-only, as the GObject property is, and the MODEL'S OWN object rather than a
+     * descriptor, so the identity comparison a `selected-item` consumer writes holds (ADR
+     * 0122 § 4). `null` and not a blank item: the sentinel and an index past the end both
+     * address no option, and inventing an empty one would make "nothing is selected"
+     * indistinguishable from an option with no text.
      */
-    get selectedItem(): AdwComboOption | null {
-        return this._state.model[this._state.selectedIndex] ?? null;
+    get selectedItem(): unknown {
+        return this._state.selectedItem;
     }
 
     connectedCallback() {
@@ -177,12 +209,26 @@ export class AdwComboRow extends TooltipElement {
         // A `<gtk-string-list slot="model">` child is the list a `.blp` authored (ADR 0072),
         // consumed here BEFORE the attribute seed below, so the seed sees a model and leaves
         // it alone, and before the selection, so an authored index lands on the real list.
-        bindSlottedChildren(this, [stringListSlot((model) => this._state.setModel(model))]).install(
-            text,
-            this._valueEl,
-            this._select,
-        );
-        if (this._state.count === 0) this._state.setModel(parseListModel(this.getAttribute('model')));
+        // The slot hands over DESCRIPTORS, which the authored list adopts — the same list the
+        // `model` attribute fills, because the two are one markup door and an author who wrote
+        // both should not get two lists.
+        bindSlottedChildren(this, [
+            stringListSlot((options) => {
+                this._authored.reconcile(options);
+                this._state.setModel(this._authored);
+            }),
+        ]).install(text, this._valueEl, this._select);
+        // Two tests, and both are needed. `model === null` and no longer "holds no items" is
+        // the test for "the slot above did not already set it": a model is an object now, so
+        // an EMPTY one is a model the author meant and the count test would have thrown it
+        // away. The ATTRIBUTE'S PRESENCE is the test for whether to seed at all — a fresh
+        // widget with no authored model has `model === null`, as GTK's does, and seeding the
+        // empty authored list unconditionally would hand every unconfigured row a model.
+        const authoredModel = this.getAttribute('model');
+        if (this._state.model === null && authoredModel !== null) {
+            this._authored.reconcile(parseListModel(authoredModel));
+            this._state.setModel(this._authored);
+        }
         this._state.setSelectedIndex(parseInt(this.getAttribute('selected') || '0', 10));
 
         // WHERE the model changed — applied before the selection change below, which is
@@ -218,7 +264,7 @@ export class AdwComboRow extends TooltipElement {
     attributeChangedCallback(name: string, _old: string | null, value: string | null) {
         if (!this._initialized) return;
         if (name === 'model') {
-            this._state.setModel(parseListModel(value));
+            this.model = value;
         } else if (name === 'selected') {
             // A programmatic set — the core state notifies `interactive: false`,
             // so the subscriber re-syncs the display without emitting an event.
@@ -257,11 +303,11 @@ export class AdwComboRow extends TooltipElement {
         if (!this._initialized) return;
         for (let i = 0; i < change.removed; i++) this._select.remove(change.position);
         const before = this._select.options[change.position] ?? null;
-        // Read ONCE: `model` hands back a copy (ADR 0046), so reading it per item would make
+        // Read ONCE: `options` hands back a copy (ADR 0046), so reading it per item would make
         // a splice of n items O(n²) instead of the O(n) the splice is.
-        const model = this._state.model;
+        const options = this._state.options;
         for (let i = 0; i < change.added; i++) {
-            const option = model[change.position + i];
+            const option = options[change.position + i];
             if (option) this._select.insertBefore(this._createOption(option), before);
         }
     }
@@ -274,7 +320,7 @@ export class AdwComboRow extends TooltipElement {
      */
     private _renderOptions(): void {
         if (!this._initialized) return;
-        this._select.replaceChildren(...this._state.model.map((option) => this._createOption(option)));
+        this._select.replaceChildren(...this._state.options.map((option) => this._createOption(option)));
         this._select.selectedIndex = this._state.selectedIndex;
         this._valueEl.textContent = this._state.selectedLabel;
         this._syncChooser();

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

@@ -32,16 +32,24 @@
 // shifted a row would have selected the wrong item. The handler now asks the list where
 // the row IS.
 //
+// THE `model` PROPERTY IS A REAL `Gio.ListModel` (ADR 0122 § 4), held by identity, and an
+// array written to it is a `TypeError` in GJS's own words. The ARRAY spellings are the
+// MARKUP doors — the JSON attribute and the `<gtk-string-list slot="model">` child — and they
+// fill one list this element owns for its whole life, so re-parsing the attribute splices
+// that list rather than replacing it. `options` is where the normalised `{ value, label }`
+// descriptors moved; everything that draws a row reads them from there.
+//
 // Attributes:
 //   model           — JSON array: `["a","b"]` or `[{"value":"a","label":"A"}]`.
 //   selected        — the selected index (number).
 //   enable-search   — boolean; show a filtering search entry in the popover.
 //   disabled        — boolean; a disabled dropdown does not open.
 // Properties (mirroring Gtk.DropDown):
-//   model           — the list model ({ value, label }[]) (get/set).
+//   model           — the list model, a real `Gio.ListModel` or null (get/set).
+//   options         — the model's items as { value, label } descriptors (get).
 //   selected        — the selected index (get/set; bounds-guarded).
 //   selectedValue   — the selected option's value ('' when empty) (get/set-by-value).
-//   selectedItem    — the selected option descriptor (or null).
+//   selectedItem    — the model's own selected item, or null (get).
 //   enableSearch    — whether the search entry is shown (get/set).
 //   active          — whether the popover is open (get).
 // Events:
@@ -67,8 +75,8 @@
 import './gtk-popover.js';
 import type { GtkPopover } from './gtk-popover.js';
 
-import { ComboState, normalizeComboOptions, parseListModel } from '@gjsify/adwaita-core';
-import type { AdwComboOption, AdwListItemsChanged, AdwListModelInput } from '@gjsify/adwaita-core';
+import { ComboState, GjsifyOptionList, parseListModel, readModelWrite } from '@gjsify/adwaita-core';
+import type { AdwComboOption, AdwListItemsChanged, ComboWatchableModel } from '@gjsify/adwaita-core';
 
 import { bindSlottedChildren } from '../slotted-children.js';
 import type { DispatchedSignals } from '../signals.js';
@@ -99,6 +107,14 @@ export class GtkDropDown extends WidgetElement {
     private _itemButtons: HTMLButtonElement[] = [];
     /** The headless options list + selectedIndex↔selectedValue machine (ADR 0004). */
     private readonly _state = new ComboState();
+    /**
+     * The list the MARKUP doors fill — the `model` ATTRIBUTE is JSON text and a
+     * `<gtk-string-list slot="model">` child is strings, and a real `Gio.ListModel` has no
+     * spelling in either (ADR 0122 § 5). Held for the element's whole life so re-parsing the
+     * attribute splices the list the element already points at rather than replacing it, which
+     * would reset the selection.
+     */
+    private readonly _authored = GjsifyOptionList.new(null);
     private _initialized = false;
     private _typeAheadBuffer = '';
     private _typeAheadTimer: ReturnType<typeof setTimeout> | null = null;
@@ -107,15 +123,35 @@ export class GtkDropDown extends WidgetElement {
         return ['model', 'selected', 'enable-search', 'disabled'];
     }
 
-    /** The list model (`Gtk.DropDown:model`). Setting it splices the popover and clamps the selection. */
-    get model(): GtkDropDownOption[] {
+    /**
+     * The list model (`Gtk.DropDown:model`) — the OBJECT that was assigned, by identity, as
+     * `dropdown.model === model` is measured to hold in GTK (ADR 0122 § 4). The normalised
+     * descriptors are {@link options}. Assigning splices the popover and re-runs autoselect.
+     */
+    get model(): ComboWatchableModel | null {
         return this._state.model;
     }
 
-    set model(value: AdwListModelInput) {
-        // `setModel` resets the index to 0 when it no longer fits — the same
-        // clamp this element used to spell out.
-        this._state.setModel(normalizeComboOptions(value));
+    set model(value: ComboWatchableModel | string | null) {
+        // ONE door for every surface: a real model by identity, `null` for none, a STRING for
+        // the `model` attribute (JSON), and a `TypeError` in the property's own words for
+        // anything else, an array included.
+        this._state.setModel(readModelWrite(value, this._authored));
+    }
+
+    /** The held model's items as `{ value, label }` descriptors. */
+    get options(): AdwComboOption[] {
+        return this._state.options;
+    }
+
+    /** `gtk_drop_down_set_model`. */
+    set_model(model: ComboWatchableModel | null): void {
+        this.model = model;
+    }
+
+    /** `gtk_drop_down_get_model`. */
+    get_model(): ComboWatchableModel | null {
+        return this.model;
     }
 
     /** The selected index. Out-of-range values are ignored (Gtk.DropDown:selected). */
@@ -143,12 +179,23 @@ export class GtkDropDown extends WidgetElement {
     }
 
     set selectedValue(value: string) {
-        const index = this._state.model.findIndex((o) => o.value === value);
+        const index = this._state.options.findIndex((o) => o.value === value);
         if (index >= 0) this._selectIndex(index);
     }
 
-    get selectedItem(): GtkDropDownOption | null {
-        return this._state.model[this._state.selectedIndex] ?? null;
+    /**
+     * The selected ITEM, or `null` (Gtk.DropDown:selected-item).
+     *
+     * The MODEL'S OWN object rather than a descriptor, so the identity comparison a
+     * `selected-item` consumer writes holds (ADR 0122 § 4).
+     */
+    get selectedItem(): unknown {
+        return this._state.selectedItem;
+    }
+
+    /** `gtk_drop_down_get_selected_item`. */
+    get_selected_item(): unknown {
+        return this.selectedItem;
     }
 
     get enableSearch(): boolean {
@@ -200,15 +247,30 @@ export class GtkDropDown extends WidgetElement {
         this._popoverEl.appendChild(this._listEl);
 
         // A `<gtk-string-list slot="model">` child is the list a `.blp` authored (ADR 0072),
-        // consumed first so the attribute seed below sees a model and leaves it alone.
-        bindSlottedChildren(this, [stringListSlot((model) => this._state.setModel(model))]).install(
-            this._buttonEl,
-            this._popoverEl,
-        );
+        // consumed first so the attribute seed below sees a model and leaves it alone. The
+        // slot hands over DESCRIPTORS, which the authored list adopts — the same list the
+        // `model` attribute fills, because the two are one markup door and an author who
+        // wrote both should not get two lists.
+        bindSlottedChildren(this, [
+            stringListSlot((options) => {
+                this._authored.reconcile(options);
+                this._state.setModel(this._authored);
+            }),
+        ]).install(this._buttonEl, this._popoverEl);
 
         // Seed options BEFORE anything subscribes, so building the initial DOM below is
-        // not driven by a change notification.
-        if (this._state.count === 0) this._state.setModel(parseListModel(this.getAttribute('model')));
+        // not driven by a change notification. Two tests, and both are needed. `model ===
+        // null` and no longer "holds no items" is the test for "the slot above did not
+        // already set it": a model is an object now, so an EMPTY one is a model the author
+        // meant and the count test would have thrown it away. The ATTRIBUTE'S PRESENCE is
+        // the test for whether to seed at all — a fresh widget with no authored model has
+        // `model === null`, as GTK's does, and seeding the empty authored list
+        // unconditionally would hand every unconfigured drop-down a model.
+        const authoredModel = this.getAttribute('model');
+        if (this._state.model === null && authoredModel !== null) {
+            this._authored.reconcile(parseListModel(authoredModel));
+            this._state.setModel(this._authored);
+        }
         const attrSelected = Number.parseInt(this.getAttribute('selected') ?? '', 10);
         if (this._state.hasIndex(attrSelected)) this._state.setSelectedIndex(attrSelected);
 
@@ -216,6 +278,17 @@ export class GtkDropDown extends WidgetElement {
         // assignment reaches the splice rather than a rebuild.
         this._state.subscribeItems((change) => this._applyItemsChanged(change));
 
+        // THAT the selection moved, for the moves this element did not ask for: a `model`
+        // write re-runs autoselect and lands the selection on 0 (ADR 0122 § 4), and an
+        // `items-changed` clamp moves it too. Neither goes through `_selectIndex`, and a
+        // model of EQUAL shape splices nothing, so `subscribeItems` alone would leave the
+        // button reading the old item's label. The DOM half only — `_selectIndex` owns the
+        // `notify::` dispatch and the `change` event, so there is still one emitter.
+        this._state.subscribe(() => {
+            this._updateLabel();
+            this._updateSelectedStates();
+        });
+
         this._popoverEl.anchor = this._buttonEl;
         this._popoverEl.subscribe((open) => this._onPopoverToggled(open));
         // Type-ahead is the ONE key class the shared popover deliberately leaves to the
@@ -230,7 +303,7 @@ export class GtkDropDown extends WidgetElement {
         if (name === 'model') {
             // No render call: the splice subscription does the DOM half, so the markup door
             // and the property door cannot drift into two update paths.
-            this._state.setModel(parseListModel(value));
+            this.model = value;
         } else if (name === 'selected') {
             const index = Number.parseInt(value ?? '', 10);
             if (!Number.isNaN(index)) this._selectIndex(index, { fromAttr: true });
@@ -243,9 +316,9 @@ export class GtkDropDown extends WidgetElement {
     }
 
     private _selectIndex(index: number, opts: { fromAttr?: boolean; fromUser?: boolean } = {}): void {
-        // The bounds arithmetic is `ComboState`'s; the POLICY of rejecting an
-        // out-of-range set is this element's published `selected` contract, and
-        // `<adw-combo-row>` deliberately answers it the other way (`ComboState.hasIndex`).
+        // The bounds arithmetic AND the policy are `ComboState`'s: an index the model does
+        // not address is ignored silently, measured on both widgets (ADR 0122 § 4). This
+        // element and `<adw-combo-row>` once answered it differently; neither does now.
         if (!this._state.hasIndex(index)) return;
         // Both core setters return "did it change", which is what gates the notify — no
         // second copy of the current index is kept here, so `setModel`' own label
@@ -258,7 +331,10 @@ export class GtkDropDown extends WidgetElement {
             this.setAttribute('selected', String(index));
         }
         if (changed) {
-            const option = this._state.model[index];
+            // The MODEL'S OWN item, not a descriptor: `selected-item` is an identity in GTK
+            // (ADR 0122 § 4), so a listener comparing it against the item it put in the model
+            // has to match.
+            const item = this._state.selectedItem;
             // `notify::selected` mirrors GObject property-notify: EVERY change,
             // programmatic included.
             this.dispatchEvent(new CustomEvent('notify::selected', { bubbles: true, detail: { selected: index } }));
@@ -266,7 +342,7 @@ export class GtkDropDown extends WidgetElement {
             this.dispatchEvent(
                 new CustomEvent('notify::selected-item', {
                     bubbles: true,
-                    detail: { 'selected-item': option ?? null },
+                    detail: { 'selected-item': item ?? null },
                 }),
             );
             // `change` mirrors the DOM <select> contract: ONLY a user-initiated change. A
@@ -276,7 +352,7 @@ export class GtkDropDown extends WidgetElement {
                 this.dispatchEvent(
                     new CustomEvent('change', {
                         bubbles: true,
-                        detail: { index, value: option?.value ?? '', label: option?.label ?? '' },
+                        detail: { index, value: this._state.selectedValue, label: this._state.selectedLabel },
                     }),
                 );
             }
@@ -319,7 +395,7 @@ export class GtkDropDown extends WidgetElement {
         this._typeAheadBuffer += char.toLowerCase();
         if (this._typeAheadTimer) clearTimeout(this._typeAheadTimer);
         this._typeAheadTimer = setTimeout(() => (this._typeAheadBuffer = ''), 800);
-        const match = this._state.model.findIndex((o) => o.label.toLowerCase().startsWith(this._typeAheadBuffer));
+        const match = this._state.options.findIndex((o) => o.label.toLowerCase().startsWith(this._typeAheadBuffer));
         if (match < 0) return;
         if (this._popoverEl.open) this._itemButtons[match]?.focus();
         else this._selectIndex(match, { fromUser: true });
@@ -329,9 +405,9 @@ export class GtkDropDown extends WidgetElement {
         const q = query.trim().toLowerCase();
         // Hoisted for the reason `_applyItemsChanged` gives: this runs on every keystroke of
         // the search field, over every row.
-        const model = this._state.model;
+        const options = this._state.options;
         this._itemButtons.forEach((button, index) => {
-            const match = q.length === 0 || (model[index]?.label.toLowerCase().includes(q) ?? false);
+            const match = q.length === 0 || (options[index]?.label.toLowerCase().includes(q) ?? false);
             button.hidden = !match;
         });
     }
@@ -380,7 +456,7 @@ export class GtkDropDown extends WidgetElement {
             if (existing) existing.remove();
         }
 
-        for (const option of this._state.model) {
+        for (const option of this._state.options) {
             const item = this._createItem(option);
             this._listEl.appendChild(item);
             this._itemButtons.push(item);
@@ -439,11 +515,11 @@ export class GtkDropDown extends WidgetElement {
         }
         const before = this._itemButtons[change.position] ?? null;
         const inserted: HTMLButtonElement[] = [];
-        // Read ONCE: `model` hands back a copy (ADR 0046), so reading it per item would make
-        // a splice of n items O(n²) instead of the O(n) the splice is.
-        const model = this._state.model;
+        // Read ONCE: `options` normalises every item on each call (ADR 0046), so reading it
+        // per item would make a splice of n items O(n²) instead of the O(n) the splice is.
+        const options = this._state.options;
         for (let i = 0; i < change.added; i++) {
-            const option = model[change.position + i];
+            const option = options[change.position + i];
             if (!option) continue;
             const item = this._createItem(option);
             this._listEl.insertBefore(item, before);

package/src/elements/gtk-page-setup-unix-dialog.ts

@@ -178,12 +178,14 @@ export class GtkPageSetupUnixDialog extends AdwDialog {
      */
     set pageSetup(value: PageSetup) {
         const index = this._setups.findIndex((setup) => pageSetupEquals(setup, value));
-        if (index < 0) {
-            this._setups.push(value);
-            this._paperEl.selected = this._setups.length - 1;
-        } else if (this._paperEl.selected !== index) {
-            this._paperEl.selected = index;
-        }
+        if (index < 0) this._setups.push(value);
+        // The row list GROWS BEFORE the selection moves. The drop-down refuses an index its
+        // model does not address, and a splice that lands at or before the selection shifts
+        // it rather than leaving it standing (ADR 0122 § 4). Selecting first worked only
+        // while the appended row happened to fall where `Manage Custom Sizes…` already was.
+        if (this._built) this._renderSetup();
+        const wanted = index < 0 ? this._setups.length - 1 : index;
+        if (this._paperEl.selected !== wanted) this._paperEl.selected = wanted;
         this._setOrientation(value.orientation);
         if (this._built) this._renderSetup();
     }

package/src/file-chooser-host.ts

@@ -22,6 +22,7 @@ import {
     dialogFailedError,
     dismissedError,
     fileFilterAccepts,
+    GjsifyOptionList,
     GLibError,
     registerFileChooserDriver,
     type FileChooserDriver,
@@ -291,7 +292,7 @@ export function presentOpfsDialog(
     let dropDown: GtkDropDown | null = null;
     if (filters.length > 0) {
         dropDown = el('gtk-drop-down') as GtkDropDown;
-        dropDown.model = filters.map((f, i) => f.name ?? `Filter ${i + 1}`);
+        dropDown.model = GjsifyOptionList.new(filters.map((f, i) => f.name ?? `Filter ${i + 1}`));
         dropDown.selected = Math.max(initial, 0);
         bottom.append(dropDown);
     }

package/src/gobject-door.spec.ts

@@ -91,6 +91,45 @@ GObject.registerClass(
     GoWebSensitive as never,
 );
 
+const SiblingsTemplate = tree(`template $GoWebSiblings : Adw.Bin {
+    child: Gtk.Box {
+        Gtk.Label caption { label: bind peer.title; }
+    };
+}
+
+Adw.AlertDialog unsavedChangesDialog { heading: "Save changes?"; }
+
+$GoWebPeer peer { }`);
+
+class GoWebPeer extends Adw.Bin {
+    declare title: string;
+}
+GObject.registerClass(
+    {
+        GTypeName: 'GoWebPeer',
+        Properties: { title: GObject.ParamSpec.string('title', '', '', GObject.ParamFlags.READWRITE, 'first') },
+    },
+    GoWebPeer as never,
+);
+
+class GoWebSiblings extends Adw.Bin {
+    declare _unsavedChangesDialog: HTMLElement & { heading: string };
+    declare _peer: GoWebPeer;
+    declare _caption: HTMLElement & { label: string };
+    constructor(params?: Record<string, unknown>) {
+        // @ts-expect-error the element's own constructor takes none; the registered class's takes the params
+        super(params);
+    }
+}
+GObject.registerClass(
+    {
+        GTypeName: 'GoWebSiblings',
+        Template: SiblingsTemplate,
+        InternalChildren: ['unsavedChangesDialog', 'peer', 'caption'],
+    },
+    GoWebSiblings as never,
+);
+
 export const GObjectDoorTest = async () => {
     await driveGObjectVectors(subject, { describe, it, expect }, GOBJECT_VECTORS);
     await describe('adwaita-web: GObject.registerClass end to end (ADR 0096)', async () => {
@@ -98,6 +137,24 @@ export const GObjectDoorTest = async () => {
             expect(tagForTypeName('Hexdump')).toBe('gjsify-hexdump');
             expect(customElements.get('gjsify-go-web-hexdump')).toBe(GoWebHexdump);
         });
+        await it('reaches the objects written beside the template through InternalChildren, outside its children', () => {
+            const el = new GoWebSiblings();
+            expect(el._unsavedChangesDialog.localName).toBe('adw-alert-dialog');
+            expect(el._peer instanceof GoWebPeer).toBe(true);
+            document.body.append(el);
+            try {
+                // Independent objects, as in GTK: neither is a child of the template widget.
+                expect(el.contains(el._unsavedChangesDialog)).toBe(false);
+                expect(el.contains(el._peer)).toBe(false);
+                expect(el.contains(el._caption)).toBe(true);
+                // A template child names a sibling by id, and follows it.
+                expect(el._caption.label).toBe('first');
+                el._peer.title = 'second';
+                expect(el._caption.label).toBe('second');
+            } finally {
+                el.remove();
+            }
+        });
         await it('refuses a second class under the same tag', () => {
             expect(() =>
                 GObject.registerClass({ GTypeName: 'GoWebHexdump' }, class extends Adw.Bin {} as never),