@gjsify/adwaita-core 0.47.0 → 0.48.0

package/lib/types/rows.d.ts

@@ -1,3 +1,8 @@
+import type { AdwComboOption, AdwListItemsChanged } from './list.js';
+export { ADW_COMBO_NO_SELECTION, normalizeComboOptions } from './list.js';
+export type { AdwComboOption, AdwComboOptionInput } from './list.js';
+export { SpinState } from './adjustment.js';
+export type { SpinStateChange, SpinStateListener, SpinStateRangeListener } from './adjustment.js';
 /** Subscriber for {@link ExpanderState} changes — receives the new expanded flag. */
 export type ExpanderStateListener = (expanded: boolean) => void;
 /**
@@ -23,44 +28,6 @@ export declare class ExpanderState {
     /** Collapse the disclosure. Returns whether it changed. */
     collapse(): boolean;
 }
-/** One selectable option in a {@link ComboState}. */
-export interface AdwComboOption {
-    /** Display label shown in the row + chooser. */
-    label: string;
-    /** Underlying value returned by {@link ComboState.selectedValue}. */
-    value: string;
-}
-/**
- * What an author may write for one option before {@link normalizeComboOptions}
- * has seen it: a bare string (value === label, the `Gtk.StringList` case), or a
- * partial descriptor where either half may stand in for the other.
- */
-export type AdwComboOptionInput = string | {
-    value?: unknown;
-    label?: unknown;
-};
-/**
- * Raw authored options → the stable `{ value, label }` descriptors every combo surface
- * works with.
- *
- * A bare string is both value and label (`Gtk.StringList`'s model, which is what
- * `Adw.ComboRow` is fed in the common case). In a descriptor either half stands in for the
- * missing other, so `{ label: 'Apple' }` is addressable by the value `'Apple'` rather than
- * by `undefined`. ONE home for the rule, so `<adw-combo-row>` and `<gtk-drop-down>` cannot
- * accept two different option vocabularies.
- */
-export declare function normalizeComboOptions(raw: ReadonlyArray<AdwComboOptionInput> | null | undefined): AdwComboOption[];
-/**
- * The "no item is selected" index — the TS mirror of `GTK_INVALID_LIST_POSITION`
- * (`AdwComboRow:selected`'s default and empty value).
- *
- * libadwaita spells it `G_MAXUINT` because the property is a `guint`; `-1` is the idiomatic
- * TS sentinel and the spelling {@link ADW_SIDEBAR_NO_SELECTION} uses for the same GTK
- * constant. Without it, an EMPTY model and a model whose first item has an empty label are
- * indistinguishable — both report index 0 with `selectedValue === ''` — so a renderer that
- * wants to draw a placeholder has nothing to test.
- */
-export declare const ADW_COMBO_NO_SELECTION = -1;
 /** Payload of a {@link ComboState} change. */
 export interface ComboStateChange {
     /** The (new) selected index, or {@link ADW_COMBO_NO_SELECTION}. */
@@ -72,41 +39,94 @@ export interface ComboStateChange {
     /** True for a user pick ({@link ComboState.select}); false for a programmatic set. */
     interactive: boolean;
 }
-/** Subscriber for {@link ComboState} changes. */
+/** Subscriber for {@link ComboState} selection changes. */
 export type ComboStateListener = (change: ComboStateChange) => void;
+/** Subscriber for {@link ComboState} MODEL changes — one `items-changed` per replacement. */
+export type ComboItemsListener = (change: AdwListItemsChanged) => void;
 /**
- * The selection state of a combo row: an options list plus the selected index,
- * with a two-way index↔value mapping and empty/out-of-range guards. Mirrors
- * `Adw.ComboRow`: a programmatic set ({@link setSelectedIndex} / {@link setSelectedValue}
- * / {@link setOptions}) updates silently (`interactive: false` — the renderer refreshes
- * the inline value but re-emits no `notify::selected`), while {@link select} is the
- * user pick that notifies (`interactive: true`).
+ * The selection state of a combo row: a portable list model (`AdwListModel`) plus
+ * the selected index, with a two-way index↔value mapping and empty/out-of-range guards.
+ * Mirrors `Adw.ComboRow`: a programmatic set ({@link setSelectedIndex} /
+ * {@link setSelectedValue} / {@link setModel}) updates silently (`interactive: false` —
+ * the renderer refreshes the inline value but re-emits no `notify::selected`), while
+ * {@link select} is the user pick that notifies (`interactive: true`).
+ *
+ * TWO SIGNALS, because they answer different questions and a renderer needs both
+ * (ADR 0046). {@link subscribe} reports the SELECTION; {@link subscribeItems} reports WHERE
+ * the model changed, so a renderer splices its item views instead of rebuilding them.
+ * `Adw.ComboRow` gets both from GTK for free — the first is `notify::selected`, the second
+ * is `Gio.ListModel::items-changed` on the model it holds — and this class had only the
+ * first, which is why both browser selectors dropped every option node on every
+ * assignment.
  */
 export declare class ComboState {
     private _options;
     private _selected;
     private readonly _listeners;
+    private readonly _itemListeners;
     /** Subscribe to selection changes. Returns an unsubscribe function. */
     subscribe(listener: ComboStateListener): () => void;
+    /**
+     * Subscribe to MODEL changes — `Gio.ListModel::items-changed`, one splice per
+     * {@link setModel}. Returns an unsubscribe function.
+     *
+     * Fires BEFORE the selection change {@link setModel} also emits, which is the order
+     * that makes it usable: the selection subscriber writes the new index into the item
+     * views, so those views have to exist by then. The rebuild path had the inverse
+     * ordering hazard written down in `<adw-combo-row>` — "AFTER the rebuild, never during
+     * it" — and this is what removes it rather than documenting it again.
+     */
+    subscribeItems(listener: ComboItemsListener): () => void;
     private _emit;
     private _setIndex;
-    /** The selectable options. */
-    get options(): AdwComboOption[];
     /**
-     * Replace the options, then notify (`interactive: false`) so the renderer re-syncs the
-     * inline value label — which may change even at an unchanged index, because the label is
-     * read out of the MODEL.
+     * The list model — `Adw.ComboRow:model` / `Gtk.DropDown:model`, in portable form.
+     *
+     * A COPY, items included, and that is load-bearing rather than defensive. The splice
+     * (ADR 0046) decides what changed by COMPARING the assigned model against the stored
+     * one, so anything that leaks a reference into `_options` makes the comparison read the
+     * new value on both sides and answer "nothing changed". Handing back `_options` itself
+     * did exactly that, and it turned a pattern that WORKED under the old full rebuild into
+     * a silent no-op:
+     *
+     * ```ts
+     * const m = row.model; m.push(item); row.model = m;   // → no splice, DOM unchanged
+     * ```
+     *
+     * Fresh items and not just a fresh array, because the same failure sits one level down:
+     * `m[0].label = 'x'` through a shared descriptor mutates the stored one too, and the
+     * comparison is by BOTH halves. A frozen item would have made the mutation loud; a copy
+     * makes the round trip CORRECT, which is the difference between documenting the hazard
+     * and removing it.
+     *
+     * Cost, MEASURED rather than assumed (Node 24.19, `{value,label}` records): linear, about
+     * four nanoseconds per item — so a read is well under a microsecond at every size a combo
+     * row actually holds, and the assignment beside it already costs more. What the shape
+     * rules out is a per-item read: the three call sites that had one — `_applyItemsChanged`
+     * in each browser selector and `_filter` in `<gtk-drop-down>`, which runs per row per
+     * keystroke — hoist it out of their loop, so a read is O(n) once per operation instead of
+     * O(n²). Nothing reads it per frame. A model large enough for the linear term to matter is
+     * a `Gtk.ListView` and belongs to `ListController`'s virtualisation, which ADR 0046 § 7
+     * keeps out of this class on purpose.
+     */
+    get model(): AdwComboOption[];
+    /**
+     * Replace the model: emit the splice that turns the old one into the new
+     * ({@link subscribeItems}), then notify the SELECTION (`interactive: false`) so the
+     * renderer re-syncs the inline value label — which may change even at an unchanged
+     * index, because the label is read out of the model.
      *
-     * Replacing the model re-runs autoselect, so an index the new one does not have falls
-     * back to 0 — including the sentinel, which is how a row recovers a selection when its
-     * model grows. An EMPTY model has no 0 to fall back to and lands on
-     * {@link ADW_COMBO_NO_SELECTION}.
+     * Replacing the model re-runs autoselect ({@link clampListSelection}), so an index the
+     * new one does not have falls back to 0 — including the sentinel, which is how a row
+     * recovers a selection when its model grows. An EMPTY model has no 0 to fall back to
+     * and lands on {@link ADW_COMBO_NO_SELECTION}.
      *
-     * The check is `hasIndex`, not `selected >= length`: the sentinel is BELOW the range, so
-     * a one-sided comparison leaves a `-1` in place and a model that was emptied and
-     * refilled comes back with nothing selected.
+     * The selection notify is UNCONDITIONAL while the splice is not: an assignment of an
+     * equal model emits no `items-changed` (GTK emits none either) but still re-runs the
+     * label sync, because that is the behaviour every renderer has depended on since this
+     * class existed and nothing measured says it is wrong.
      */
-    setOptions(options: AdwComboOption[]): void;
+    setModel(model: AdwComboOption[]): void;
     /**
      * The selected option index, or {@link ADW_COMBO_NO_SELECTION}. May also sit PAST the
      * options length: {@link setSelectedIndex} is deliberately permissive, mirroring a
@@ -157,57 +177,6 @@ export declare class ComboState {
     /** Number of options. */
     get count(): number;
 }
-/** Payload of a {@link SpinState} change. */
-export interface SpinStateChange {
-    /** The new value (already clamped to `[min, max]`). */
-    value: number;
-    /** True for a stepper press ({@link SpinState.increment}/{@link SpinState.decrement}); false for a programmatic set/re-clamp. */
-    interactive: boolean;
-}
-/** Subscriber for {@link SpinState} changes. */
-export type SpinStateListener = (change: SpinStateChange) => void;
-/**
- * The numeric adjustment state of a spin row: `value` bounded by `[min, max]` and
- * stepped by `step`. Every mutation clamps into range. Mirrors `Adw.SpinRow`: a
- * programmatic {@link setValue} (or a re-clamp from a moved {@link setMin}/{@link setMax})
- * notifies `interactive: false` (the renderer refreshes the display but re-emits no
- * `notify::value`), while {@link increment}/{@link decrement} are the stepper presses
- * that notify `interactive: true`.
- */
-export declare class SpinState {
-    private _value;
-    private _min;
-    private _max;
-    private _step;
-    private readonly _listeners;
-    /** Subscribe to value changes. Returns an unsubscribe function. */
-    subscribe(listener: SpinStateListener): () => void;
-    private _emit;
-    private _clamp;
-    private _bump;
-    /** Re-clamp the current value after a bound moved; notifies `interactive: false` on change. */
-    private _reclamp;
-    /** The current numeric value (always within `[min, max]`). */
-    get value(): number;
-    /** Lower bound. */
-    get min(): number;
-    /** Upper bound. */
-    get max(): number;
-    /** Increment/decrement step applied per stepper press. */
-    get step(): number;
-    /** Programmatic value set — clamp, notify `interactive: false` on change. Returns whether it changed. */
-    setValue(value: number): boolean;
-    /** Set the lower bound and re-clamp the value into range. Returns whether the value changed. */
-    setMin(value: number): boolean;
-    /** Set the upper bound and re-clamp the value into range. Returns whether the value changed. */
-    setMax(value: number): boolean;
-    /** Set the step. A non-positive or non-finite step falls back to `1`. */
-    setStep(value: number): void;
-    /** Step up by `step`, clamped to `max`. Notifies `interactive: true` on change. Returns whether it changed. */
-    increment(): boolean;
-    /** Step down by `step`, clamped to `min`. Notifies `interactive: true` on change. Returns whether it changed. */
-    decrement(): boolean;
-}
 /** Payload of a {@link ToggleGroupState} change. */
 export interface ToggleGroupStateChange {
     /** The newly-selected segment index. */

package/lib/types/split-button.d.ts

@@ -1,3 +1,4 @@
+import type { AdwMenuInput, AdwMenuItem, AdwMenuModel, AdwMenuPath } from './menu.js';
 /**
  * The four mutually exclusive content slots of the action half. `'empty'` is the
  * initial state — `label`, `icon-name` and `child` are all `NULL`.
@@ -21,22 +22,6 @@ export type SplitButtonStyleClass = 'image-button' | 'text-button';
  * single freeze/thaw, and that sequence cannot be reconstructed from the final state alone.
  */
 export type SplitButtonProperty = 'label' | 'icon-name' | 'child' | 'use-underline' | 'menu-model' | 'popover' | 'direction' | 'dropdown-tooltip';
-/**
- * One `GMenuModel` item: a label plus the detailed action it invokes, i.e. what
- * `Gio.Menu.append (label, action)` produces. `id` and `icon` are the renderers'
- * menu-button extras, so every menu call site can converge on ONE type; the name is
- * family-neutral because `Adw.MenuButton` needs exactly this.
- */
-export interface AdwMenuEntry {
-    /** Display label. */
-    label: string;
-    /** Detailed action name, e.g. `app.save-as`. */
-    action?: string;
-    /** Stable identifier, defaulting to {@link label} on activation. */
-    id?: string;
-    /** Symbolic icon name for the item. */
-    icon?: string;
-}
 /** Payload of a {@link SplitButtonState} notification. */
 export interface SplitButtonChange {
     /** Which content slot is filled. */
@@ -55,7 +40,7 @@ export interface SplitButtonChange {
     open: boolean;
     /** The `notify::*` properties C emits for this one mutation, in emission order. */
     notified: readonly SplitButtonProperty[];
-    /** True for a user gesture ({@link SplitButtonState.toggleMenu} / {@link SplitButtonState.activateMenuEntry}). */
+    /** True for a user gesture ({@link SplitButtonState.toggleMenu} / {@link SplitButtonState.activateMenuItem}). */
     interactive: boolean;
 }
 /** Subscriber for {@link SplitButtonState} changes. */
@@ -127,12 +112,6 @@ export declare function splitButtonRootState(action: SplitButtonHalfState, dropd
     active: boolean;
     checked: boolean;
 };
-/**
- * Parse a JSON menu attribute into entries. Total by construction — malformed JSON, a
- * non-array root and entries without a `label` key all yield `[]` / are dropped — because
- * the input is author-written markup and a typo must not take the widget down with it.
- */
-export declare function parseMenuEntries(json: string | null | undefined): AdwMenuEntry[];
 /**
  * The whole `Adw.SplitButton` state machine: content mode, use-underline,
  * menu-model/popover exclusivity, direction, dropdown tooltip and the popup flag. Every
@@ -194,19 +173,25 @@ export declare class SplitButtonState {
      * PROPERTY lives here; the `_S` → underlined-S derivation belongs to `GtkLabel`.
      */
     setUseUnderline(value: boolean): boolean;
-    /** The menu entries, or `null` when no menu model is set. */
-    get menuModel(): readonly AdwMenuEntry[] | null;
+    /** The menu model, or `null` when none is set. Always normalised (ADR 0042). */
+    get menuModel(): AdwMenuModel | null;
     /**
      * Set the menu model, dissociating any popover and replacing it with the model-derived
      * one.
      *
+     * NORMALISES AT THE DOOR, so every surface stores the same shape whatever it was
+     * handed — a JSON attribute, a bare `string[]`, a JSX array of descriptors. It is
+     * {@link normalizeMenuModel}'s idempotence that makes `setMenuModel(state.menuModel)`
+     * a no-op rather than a quiet flattening.
+     *
      * DELIBERATE NORMALISATION: an EMPTY list is stored as "no menu model". C can hold a
      * non-`NULL` but empty `GMenu`, which leaves the dropdown live and pops up an empty
-     * popover — but no renderer can construct that state (one parses a JSON array, another
-     * takes a label list), so collapsing the two is what makes "no menu ⇒ insensitive
-     * dropdown" hold from a renderer's point of view.
+     * popover; collapsing the two is what makes "no menu ⇒ insensitive dropdown" hold
+     * from a renderer's point of view. A model that is non-empty but draws nothing — one
+     * empty section — is NOT collapsed: it has a node, so it is a menu, which is the
+     * answer GTK gives for the same `GMenu`.
      */
-    setMenuModel(entries: readonly AdwMenuEntry[] | null | undefined): boolean;
+    setMenuModel(input: AdwMenuInput | null | undefined): boolean;
     /** The popover: the one the app set, or the model-derived stand-in, or `null`. */
     get popover(): object | null;
     /**
@@ -248,13 +233,17 @@ export declare class SplitButtonState {
     /** The dropdown half was activated by the user; flips the menu open/closed. */
     toggleMenu(): boolean;
     /**
-     * Activate a menu entry BY POSITION and dismiss the menu, returning the entry
-     * (or `null` for an out-of-range index).
+     * Activate a menu item BY POSITION and dismiss the menu, returning the item
+     * (or `null` for a path that names no item).
      *
      * Position is the addressing a `GMenuModel` actually uses — each item carries its own
      * detailed action. Resolving a choice by LABEL instead silently dispatches the first of
      * two identically named entries and cannot tell an entry called `Cancel` from a
      * dismissed sheet.
+     *
+     * A PATH rather than a single index (ADR 0042), because a link is a model of its own:
+     * `[1, 0]` is the first item of the submenu at position 1, and a flat index cannot
+     * name it. A top-level choice is `[2]`.
      */
-    activateMenuEntry(index: number): AdwMenuEntry | null;
+    activateMenuItem(path: AdwMenuPath): AdwMenuItem | null;
 }

package/lib/types/tab-view.d.ts

@@ -1,3 +1,4 @@
+import type { AdwListItemsChanged } from './list.js';
 /**
  * Input shape for a tab page.
  *
@@ -120,6 +121,29 @@ export interface TabViewPagesChange {
 }
 /** Subscriber for {@link TabViewState} page-list changes. */
 export type TabViewPagesListener = (change: TabViewPagesChange) => void;
+/**
+ * The same change as a portable `items-changed` (ADR 0046) — the mapping that makes "the
+ * tab view's page signal IS the positional list signal" a CHECKABLE claim rather than a
+ * sentence in an ADR.
+ *
+ * `TabViewPagesChange` was the only positional collection signal in this package, and it
+ * is the evidence the portable one is shaped right; the portable one is GLib's, because
+ * `AdwTabView:pages` really is a `GListModel` even though the PAGES are appended by a
+ * method. The five kinds fold onto the three numbers exactly:
+ *
+ *   attached   (p, 0, 1)  an item arrived at p
+ *   detached   (p, 1, 0)  an item left p
+ *   updated    (p, 1, 1)  the item at p is a different thing to draw — which is how
+ *                         `GListModel` spells a per-item change; it has no other verb
+ *   reordered  \
+ *   pinned     /  the span between the two positions, removed and re-added. A move has no
+ *                 verb either, and `g_list_store_move` reports it the same way.
+ *
+ * NOT a lossy conversion in the direction that matters: {@link AdwListItemsChanged} plus
+ * the change's `id` is enough to replay the whole page order, which is what the two
+ * renderer tab-view suites assert against the orders their real widgets end on.
+ */
+export declare function tabViewItemsChanged(change: TabViewPagesChange): AdwListItemsChanged;
 /** What a tab draws in its icon and indicator slots — the result of {@link tabIconState}. */
 export interface TabIconState {
     /** The icon name to paint, or `null` when there is none to paint. */

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/adwaita-core",
-    "version": "0.47.0",
+    "version": "0.48.0",
     "description": "Headless Adwaita widget behavior (breakpoint condition grammar + apply/unapply state machine, color-scheme observable, avatar derivation) shared by the web and NativeScript Adwaita renderers — pure TS, no platform imports",
     "type": "module",
     "module": "lib/esm/index.js",
@@ -50,8 +50,8 @@
         "headless"
     ],
     "devDependencies": {
-        "@gjsify/cli": "^0.47.0",
-        "@gjsify/unit": "^0.47.0",
+        "@gjsify/cli": "^0.48.0",
+        "@gjsify/unit": "^0.48.0",
         "@types/node": "^25.9.2",
         "typescript": "^6.0.3"
     },