@gjsify/adwaita-web 0.47.0 → 0.49.0

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

@@ -106,11 +106,11 @@ export class AdwTabView extends HTMLElement {
     private readonly _hovered = new Set<string>();
     private _initialized = false;
     private _generatedIds = 0;
-    /** Guards the `selected` attribute reflection against re-entering the model. */
+    /** Guards the `selected-page` attribute reflection against re-entering the model. */
     private _reflecting = false;
 
     static get observedAttributes() {
-        return ['selected', 'autohide', 'expand-tabs', 'no-close'];
+        return ['selected-page', 'autohide', 'expand-tabs', 'no-close'];
     }
 
     constructor() {
@@ -131,13 +131,26 @@ export class AdwTabView extends HTMLElement {
         this._state.subscribe((change) => this._onSelectionChange(change));
     }
 
-    /** Zero-based index of the visible page, `-1` when the view is empty. */
-    get selected(): number {
-        return this._state.selectedIndex;
+    /**
+     * The selected page (`Adw.TabView:selected-page`), `null` when the view is empty.
+     *
+     * THE PAGE, NOT ITS POSITION (ADR 0048). Its position is {@link selectedIndex}, which
+     * stays a read-only report; `Adw.TabView` selects by object, and the model has held
+     * that object all along.
+     */
+    get selectedPage(): AdwTabViewPage | null {
+        return this._state.selectedPage;
     }
 
-    set selected(value: number) {
-        this._state.selectNthPage(value);
+    set selectedPage(page: AdwTabViewPage | null) {
+        // Straight to the core, which owns the page list and therefore owns
+        // `page_belongs_to_this_view` — the check an ID cannot answer: an id is unique
+        // WITHIN a view, never across two (a declared `page-id` is the author's to repeat
+        // and `_nextId` counts per element, so two views both hold a `tab-1`). Measured
+        // before the core took the page: `viewA.selectedPage = viewB.pages[2]` moved viewA
+        // to index 2 instead of refusing. The refusal carries C's own diagnostic now,
+        // where a renderer-side guard could only return in silence.
+        this._state.setSelectedPage(page);
     }
 
     /**
@@ -177,8 +190,8 @@ export class AdwTabView extends HTMLElement {
         this._initialized = true;
 
         // Read the declared selection BEFORE adopting anything: the auto-select
-        // of the first page reflects its own index into this very attribute.
-        const declaredSelection = this.getAttribute('selected');
+        // of the first page reflects its own id into this very attribute.
+        const declaredSelection = this.getAttribute('selected-page');
 
         // Snapshot the declared pages, then take over the subtree. The elements
         // themselves become the panels, so they must survive replaceChildren.
@@ -195,12 +208,12 @@ export class AdwTabView extends HTMLElement {
 
     attributeChangedCallback(name: string, _old: string | null, _value: string | null) {
         if (!this._initialized) return;
-        if (name === 'selected') {
+        if (name === 'selected-page') {
             // The LIVE attribute, not the value captured when the reaction was
             // queued: reflection writes this attribute, and a custom-element
             // reaction can run after a later write has already superseded it.
             if (this._reflecting) return;
-            const current = this.getAttribute('selected');
+            const current = this.getAttribute('selected-page');
             if (current !== null) this._applySelectedAttribute(current);
             return;
         }
@@ -272,8 +285,9 @@ export class AdwTabView extends HTMLElement {
         return this._state.isClosing(id);
     }
 
-    setSelectedPage(id: string | null): boolean {
-        return this._state.setSelectedPage(id);
+    /** `adw_tab_view_set_selected_page`, which takes the PAGE; an id is accepted too. */
+    setSelectedPage(page: AdwTabViewPage | string | null): boolean {
+        return this._state.setSelectedPage(page);
     }
 
     selectNthPage(n: number): boolean {
@@ -724,19 +738,25 @@ export class AdwTabView extends HTMLElement {
 
     private _reflectSelected(): void {
         this._reflecting = true;
-        const index = this._state.selectedIndex;
-        if (index < 0) this.removeAttribute('selected');
-        else if (this.getAttribute('selected') !== String(index)) this.setAttribute('selected', String(index));
+        const id = this._state.selectedId;
+        if (id === null) this.removeAttribute('selected-page');
+        else if (this.getAttribute('selected-page') !== id) this.setAttribute('selected-page', id);
         this._reflecting = false;
     }
 
+    /**
+     * `selected-page="<page id>"` — the markup half of {@link selectedPage} (ADR 0048).
+     *
+     * The id is the one `<adw-tab-page page-id>` declares; a page that declares none gets
+     * a generated one, which an author cannot predict and therefore cannot select by. That
+     * is the same bargain `<adw-view-stack visible-child-name>` already makes for a page
+     * with no name, and it is why `page-id` exists.
+     *
+     * An id no page holds is IGNORED rather than treated as the first page — libadwaita
+     * refuses a foreign `AdwTabPage` outright, and `setSelectedPage` is the refusal here.
+     */
     private _applySelectedAttribute(value: string): void {
-        const index = Number.parseInt(value, 10);
-        // An unparseable value is IGNORED rather than treated as 0, and an out-of-range
-        // one is refused rather than clamped: libadwaita refuses both, so
-        // `selected="oops"` must not select the first page nor `selected="99"` the last.
-        if (Number.isNaN(index)) return;
-        this._state.selectNthPage(index);
+        this._state.setSelectedPage(value);
     }
 
     /**

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

@@ -26,7 +26,8 @@
 // Properties (mirroring Adw.ViewStack):
 //   pages               — readonly page descriptors ({ name, title, icon, content, visible }).
 //   visibleChildName    — name of the visible page ('' when nothing is selected).
-//   visibleChildIndex   — zero-based index of the visible page, -1 for none (guarded).
+//   visibleChildIndex   — READ-ONLY report: position of the visible page, -1 for none.
+//                         Selecting is `visibleChildName` (ADR 0048).
 //   visibleChild        — the visible page's content element (or null).
 // Methods:
 //   add(content, name, title?, icon?) — append a page; returns its descriptor.
@@ -70,13 +71,28 @@ export class AdwViewStack extends HTMLElement {
         return this._state.pages;
     }
 
-    /** Zero-based index of the visible page, `-1` when nothing is selected. */
+    /**
+     * Zero-based position of the visible page, `-1` when nothing is selected.
+     *
+     * A REPORT, NOT A DOOR (ADR 0048). `Adw.ViewStack` selects by NAME, and an ordinal is
+     * derived — an insertion before the visible page increments it, a reorder rewrites it,
+     * a removal decrements it. Selecting is {@link visibleChildName}.
+     */
     get visibleChildIndex(): number {
         return this._state.visibleIndex;
     }
 
-    set visibleChildIndex(value: number) {
-        this._state.setVisibleIndex(value);
+    /**
+     * Show the page at position `n`. Returns whether the selection moved.
+     *
+     * THE ORDINAL IS A CALL, NOT A PROPERTY (ADR 0048): it resolves against the page list
+     * as it is now and keeps nothing, where a held index comes to mean another page after
+     * an insert, a reorder or a removal. Port-owned — `refs/libadwaita` gives
+     * `AdwViewStack` no ordinal API — and named for the tab view's existing
+     * `selectNthPage`. The guard on `n` is the core's and is pinned by the shared vectors.
+     */
+    selectNthPage(n: number): boolean {
+        return this._state.setVisibleIndex(n);
     }
 
     get visibleChildName(): string {

package/src/elements/adw-view-switcher-bar.ts

@@ -99,8 +99,10 @@ export class AdwViewSwitcherBar extends HTMLElement {
                     const stack = this._stack;
                     if (!stack) return;
                     const index = Number(item.dataset.pageIndex);
-                    // Re-assigning the current index would re-run the stack's transition.
-                    if (stack.visibleChildIndex !== index) stack.visibleChildIndex = index;
+                    // The roving-focus list is ordinal and the stack resolves it (ADR 0048).
+                    // Re-selecting the current page would re-run the stack's transition, which
+                    // is why the position is compared before the call.
+                    if (stack.visibleChildIndex !== index) stack.selectNthPage(index);
                 },
             });
         }
@@ -238,7 +240,8 @@ export class AdwViewSwitcherBar extends HTMLElement {
 
         button.append(icon, label, indicator);
         button.addEventListener('click', () => {
-            if (this._stack) this._stack.visibleChildIndex = pageIndex;
+            // Ordinal here, resolved by the stack (ADR 0048) — as in `select` above.
+            this._stack?.selectNthPage(pageIndex);
         });
 
         return { button, icon, label, indicator };

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

@@ -5,9 +5,10 @@
 // <adw-combo-row> (which embeds the same idea inside a boxed-list row) — reach
 // for this one when you need a bare dropdown, not a row.
 //
-// Options are `{ value, label }` pairs (or plain strings, where the string is
-// both value and label), supplied via the `options` / `items` property or a
-// JSON `options` attribute. Optional `enable-search` puts a search entry atop
+// The model is `{ value, label }` pairs (or plain strings, where the string is
+// both value and label), supplied via the `model` property or a JSON `model`
+// attribute — `Gtk.DropDown:model`'s own name (ADR 0034 clause 1, ADR 0046), which
+// replaced the two spellings `options`/`items`. Optional `enable-search` puts a search entry atop
 // the popover for long lists. The popover is dismissed on an outside click or
 // Escape and supports arrow-key navigation, Home/End, Enter to pick, and
 // type-ahead (typing jumps to the next matching option).
@@ -23,13 +24,21 @@
 // copy is how ArrowUp from an unfocused list lands on the SECOND-TO-LAST option, which
 // `enable-search` hits on every open because it focuses the entry.
 //
+// THE MODEL IS SPLICED, NOT REBUILT (ADR 0046). `ComboState` reports WHERE the model
+// changed — `Gio.ListModel::items-changed`, one splice per assignment — so replacing a
+// model that gained one item inserts ONE row button and leaves the rest, with their focus
+// and their scroll position, alone. It also closed a latent defect the rebuild hid: each
+// row's click handler used to close over the index it was built at, so any splice that
+// shifted a row would have selected the wrong item. The handler now asks the list where
+// the row IS.
+//
 // Attributes:
-//   options / items — JSON array: `["a","b"]` or `[{"value":"a","label":"A"}]`.
+//   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):
-//   options / items — the option list ({ value, label }[]) (get/set).
+//   model           — the list model ({ value, label }[]) (get/set).
 //   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).
@@ -56,8 +65,8 @@
 import './gtk-popover.js';
 import type { GtkPopover } from './gtk-popover.js';
 
-import { ComboState, normalizeComboOptions } from '@gjsify/adwaita-core';
-import type { AdwComboOption, AdwComboOptionInput } from '@gjsify/adwaita-core';
+import { ComboState, normalizeComboOptions, parseListModel } from '@gjsify/adwaita-core';
+import type { AdwComboOption, AdwListItemsChanged, AdwListModelInput } from '@gjsify/adwaita-core';
 
 import { createGtkImage } from './gtk-image.js';
 
@@ -82,27 +91,18 @@ export class GtkDropDown extends HTMLElement {
     private _typeAheadTimer: ReturnType<typeof setTimeout> | null = null;
 
     static get observedAttributes() {
-        return ['options', 'items', 'selected', 'enable-search', 'disabled'];
+        return ['model', 'selected', 'enable-search', 'disabled'];
     }
 
-    /** The options list. Setting it rebuilds the popover and clamps the selection. */
-    get options(): GtkDropDownOption[] {
-        return this._state.options;
+    /** The list model (`Gtk.DropDown:model`). Setting it splices the popover and clamps the selection. */
+    get model(): GtkDropDownOption[] {
+        return this._state.model;
     }
 
-    set options(value: ReadonlyArray<AdwComboOptionInput>) {
-        // `setOptions` resets the index to 0 when it no longer fits — the same
+    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.setOptions(normalizeComboOptions(value));
-        if (this._initialized) this._renderAll();
-    }
-
-    get items(): GtkDropDownOption[] {
-        return this._state.options;
-    }
-
-    set items(value: ReadonlyArray<AdwComboOptionInput>) {
-        this.options = value;
+        this._state.setModel(normalizeComboOptions(value));
     }
 
     /** The selected index. Out-of-range values are ignored (Gtk.DropDown:selected). */
@@ -120,12 +120,12 @@ export class GtkDropDown extends HTMLElement {
     }
 
     set selectedValue(value: string) {
-        const index = this._state.options.findIndex((o) => o.value === value);
+        const index = this._state.model.findIndex((o) => o.value === value);
         if (index >= 0) this._selectIndex(index);
     }
 
     get selectedItem(): GtkDropDownOption | null {
-        return this._state.options[this._state.selectedIndex] ?? null;
+        return this._state.model[this._state.selectedIndex] ?? null;
     }
 
     get enableSearch(): boolean {
@@ -178,10 +178,14 @@ export class GtkDropDown extends HTMLElement {
 
         // 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.setOptions(this._parseOptionsAttr());
+        if (this._state.count === 0) this._state.setModel(parseListModel(this.getAttribute('model')));
         const attrSelected = Number.parseInt(this.getAttribute('selected') ?? '', 10);
         if (this._state.hasIndex(attrSelected)) this._state.setSelectedIndex(attrSelected);
 
+        // WHERE the model changed. Subscribed before the first render so every later
+        // assignment reaches the splice rather than a rebuild.
+        this._state.subscribeItems((change) => this._applyItemsChanged(change));
+
         this.replaceChildren(this._buttonEl, this._popoverEl);
         this._popoverEl.anchor = this._buttonEl;
         this._popoverEl.subscribe((open) => this._onPopoverToggled(open));
@@ -194,9 +198,10 @@ export class GtkDropDown extends HTMLElement {
 
     attributeChangedCallback(name: string, _old: string | null, value: string | null) {
         if (!this._initialized || !this._buttonEl) return;
-        if (name === 'options' || name === 'items') {
-            this._state.setOptions(this._parseOptionsAttr());
-            this._renderAll();
+        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));
         } else if (name === 'selected') {
             const index = Number.parseInt(value ?? '', 10);
             if (!Number.isNaN(index)) this._selectIndex(index, { fromAttr: true });
@@ -208,25 +213,13 @@ export class GtkDropDown extends HTMLElement {
         }
     }
 
-    private _parseOptionsAttr(): GtkDropDownOption[] {
-        const raw = this.getAttribute('options') ?? this.getAttribute('items');
-        if (!raw) return [];
-        try {
-            // `normalizeComboOptions` already guards a non-array, so a JSON object or
-            // scalar yields the empty model rather than a throw.
-            return normalizeComboOptions(JSON.parse(raw) as AdwComboOptionInput[]);
-        } catch {
-            return [];
-        }
-    }
-
     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`).
         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 `setOptions`' own label
+        // second copy of the current index is kept here, so `setModel`' own label
         // re-sync cannot masquerade as one.
         const changed = opts.fromUser ? this._state.select(index) : this._state.setSelectedIndex(index);
         this._updateLabel();
@@ -236,7 +229,7 @@ export class GtkDropDown extends HTMLElement {
             this.setAttribute('selected', String(index));
         }
         if (changed) {
-            const option = this._state.options[index];
+            const option = this._state.model[index];
             // `notify::selected` mirrors GObject property-notify: EVERY change,
             // programmatic included.
             this.dispatchEvent(new CustomEvent('notify::selected', { bubbles: true, detail: { selected: index } }));
@@ -290,7 +283,7 @@ export class GtkDropDown extends HTMLElement {
         this._typeAheadBuffer += char.toLowerCase();
         if (this._typeAheadTimer) clearTimeout(this._typeAheadTimer);
         this._typeAheadTimer = setTimeout(() => (this._typeAheadBuffer = ''), 800);
-        const match = this._state.options.findIndex((o) => o.label.toLowerCase().startsWith(this._typeAheadBuffer));
+        const match = this._state.model.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 });
@@ -298,8 +291,11 @@ export class GtkDropDown extends HTMLElement {
 
     private _filter(query: string): void {
         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;
         this._itemButtons.forEach((button, index) => {
-            const match = q.length === 0 || (this._state.options[index]?.label.toLowerCase().includes(q) ?? false);
+            const match = q.length === 0 || (model[index]?.label.toLowerCase().includes(q) ?? false);
             button.hidden = !match;
         });
     }
@@ -348,27 +344,8 @@ export class GtkDropDown extends HTMLElement {
             if (existing) existing.remove();
         }
 
-        for (const [index, option] of this._state.options.entries()) {
-            const item = document.createElement('button');
-            item.type = 'button';
-            item.className = 'adw-popover-item adw-drop-down-item';
-            item.setAttribute('role', 'option');
-            item.tabIndex = -1;
-
-            const label = document.createElement('span');
-            label.className = 'adw-drop-down-item-label';
-            label.textContent = option.label;
-
-            const check = document.createElement('span');
-            check.className = 'adw-drop-down-item-check';
-            check.setAttribute('aria-hidden', 'true');
-
-            item.append(label, check);
-            item.addEventListener('click', () => {
-                this._selectIndex(index, { fromUser: true });
-                this._popoverEl.popdown();
-                this._buttonEl.focus();
-            });
+        for (const option of this._state.model) {
+            const item = this._createItem(option);
             this._listEl.appendChild(item);
             this._itemButtons.push(item);
         }
@@ -376,6 +353,72 @@ export class GtkDropDown extends HTMLElement {
         this._updateSelectedStates();
         if (this._state.count === 0) this._popoverEl.popdown();
     }
+
+    /**
+     * One row button.
+     *
+     * The click handler reads the row's CURRENT position out of `_itemButtons` instead of
+     * closing over the index it was built at. Under a full rebuild the two were always
+     * equal, which is why the closure survived; under a splice they are not, and a row
+     * that shifted by one would have selected its neighbour.
+     */
+    private _createItem(option: GtkDropDownOption): HTMLButtonElement {
+        const item = document.createElement('button');
+        item.type = 'button';
+        item.className = 'adw-popover-item adw-drop-down-item';
+        item.setAttribute('role', 'option');
+        item.tabIndex = -1;
+
+        const label = document.createElement('span');
+        label.className = 'adw-drop-down-item-label';
+        label.textContent = option.label;
+
+        const check = document.createElement('span');
+        check.className = 'adw-drop-down-item-check';
+        check.setAttribute('aria-hidden', 'true');
+
+        item.append(label, check);
+        item.addEventListener('click', () => {
+            const index = this._itemButtons.indexOf(item);
+            if (index < 0) return;
+            this._selectIndex(index, { fromUser: true });
+            this._popoverEl.popdown();
+            this._buttonEl.focus();
+        });
+        return item;
+    }
+
+    /**
+     * Apply one `items-changed` to the row list — remove `removed` buttons at `position`,
+     * insert `added` fresh ones there, leave every other row (and its focus) standing.
+     *
+     * It owns everything a model replacement has to refresh, so the property door and the
+     * attribute door share one update path: the button label, the per-row selected state,
+     * and popping the popover down when the model empties under it.
+     */
+    private _applyItemsChanged(change: AdwListItemsChanged): void {
+        if (!this._initialized) return;
+        for (const removedButton of this._itemButtons.splice(change.position, change.removed)) {
+            removedButton.remove();
+        }
+        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;
+        for (let i = 0; i < change.added; i++) {
+            const option = model[change.position + i];
+            if (!option) continue;
+            const item = this._createItem(option);
+            this._listEl.insertBefore(item, before);
+            inserted.push(item);
+        }
+        this._itemButtons.splice(change.position, 0, ...inserted);
+
+        this._updateSelectedStates();
+        this._updateLabel();
+        if (this._state.count === 0) this._popoverEl.popdown();
+    }
 }
 
 customElements.define('gtk-drop-down', GtkDropDown);