@gjsify/adwaita-core 0.64.12-next.281 → 0.64.12

package/lib/types/rows.d.ts

@@ -1,4 +1,4 @@
-import type { AdwComboOption, AdwListItemsChanged } from './list.js';
+import type { AdwComboOption, AdwListItemsChanged, AdwListModelSource } from './list.js';
 export { ADW_COMBO_NO_SELECTION, normalizeComboOptions } from './list.js';
 export type { AdwComboOption, AdwComboOptionInput } from './list.js';
 export { SpinState } from './adjustment.js';
@@ -43,6 +43,29 @@ export interface ComboStateChange {
 export type ComboStateListener = (change: ComboStateChange) => void;
 /** Subscriber for {@link ComboState} MODEL changes — one `items-changed` per replacement. */
 export type ComboItemsListener = (change: AdwListItemsChanged) => void;
+/**
+ * A GObject property of `Adw.ComboRow` / `Gtk.DropDown` whose `notify::` a renderer owes its
+ * widget — the three ADR 0122 § 5's table is written in terms of.
+ */
+export type ComboNotify = 'selected' | 'selected-item' | 'model';
+/** Subscriber for the `notify::*` a {@link ComboState} transition owes, in emission ORDER. */
+export type ComboNotifyListener = (property: ComboNotify) => void;
+/**
+ * What {@link ComboState} needs off a model to WATCH it, beyond reading it.
+ *
+ * Optional, and duck-typed for the reason `AdwListModelSource` is: a real `Gio.ListModel` has
+ * `connect`, and so does every model this repository builds, but the reader in `list.ts` accepts
+ * anything with the two getters and a state machine that DEMANDED a signal surface would refuse
+ * models it can otherwise read perfectly.
+ *
+ * EXPORTED because it is the published type of a `model` property now (ADR 0122 § 4). Left
+ * un-exported it still reached the `.d.ts`, so a consumer could satisfy it and not NAME it —
+ * which is the shape that makes a caller declare its own copy.
+ */
+export interface ComboWatchableModel extends AdwListModelSource {
+    connect?: (signal: string, handler: (...args: unknown[]) => void) => number;
+    disconnect?: (id: number) => void;
+}
 /**
  * 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.
@@ -60,12 +83,39 @@ export type ComboItemsListener = (change: AdwListItemsChanged) => void;
  * assignment.
  */
 export declare class ComboState {
+    /** The model's IDENTITY — the object `model` hands back, never a copy (ADR 0122 § 4). */
+    private _model;
+    /** The descriptors the held model holds, re-read whenever it says it changed. */
     private _options;
     private _selected;
+    /** Detaches this state from the held model's `items-changed`. */
+    private _unwatch;
     private readonly _listeners;
     private readonly _itemListeners;
+    private readonly _notifyListeners;
     /** Subscribe to selection changes. Returns an unsubscribe function. */
     subscribe(listener: ComboStateListener): () => void;
+    /**
+     * Subscribe to the `notify::*` each transition owes, delivered one at a time IN ORDER.
+     *
+     * Separate from {@link subscribe} because the two answer different questions and the
+     * ordering is the whole content of this one. It is the seam for a renderer that owns real
+     * GObject properties — none does today: both ports render DOM or NativeScript views and
+     * use {@link subscribe}, so this channel is measured in core alone (its table says so).
+     * Re-emitting it verbatim is what a host with real properties has to do, and the reason
+     * the order is recorded here rather than re-derived there.
+     *
+     * The ORDER is not derived, it is measured, and it is not the same on both paths
+     * (`~/.cache/gjsify-android/combo-probe2.js`, GJS 1.88.01 / libadwaita 1.9.4):
+     *
+     *   - a `model` write notifies `selected`, `selected-item`, `model` — in that order, and
+     *     ALL THREE even when `selected` ends on the value it already had;
+     *   - a `selected` write notifies `selected`, then `selected-item`;
+     *   - an `items-changed` on the HELD model notifies `selected-item` BEFORE `selected`.
+     *
+     * The third is the inverse of the second, which is why no single rule is written here.
+     */
+    subscribeNotify(listener: ComboNotifyListener): () => void;
     /**
      * Subscribe to MODEL changes — `Gio.ListModel::items-changed`, one splice per
      * {@link setModel}. Returns an unsubscribe function.
@@ -78,61 +128,112 @@ export declare class ComboState {
      */
     subscribeItems(listener: ComboItemsListener): () => void;
     private _emit;
+    /** Deliver one `notify::`, snapshotted for the reason `_emit` states. */
+    private _notify;
+    /** Deliver one `items-changed`, snapshotted for the reason `_emit` states. */
+    private _emitItems;
     private _setIndex;
     /**
-     * The list model — `Adw.ComboRow:model` / `Gtk.DropDown:model`, in portable form.
+     * The list model — `Adw.ComboRow:model` / `Gtk.DropDown:model`, by IDENTITY.
      *
-     * 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:
+     * The OBJECT that was assigned, never a copy and never a snapshot of its items: ADR 0122
+     * § 4 makes `model` an object-kind property over a real `Gio.ListModel`, and `row.model
+     * === model` is measured to hold in libadwaita. The copy this getter used to hand back
+     * belonged to the Array era, where the model WAS its items and the splice was computed by
+     * comparing two arrays — which made `const m = row.model; m.push(x); row.model = m` a
+     * silent no-op the copy existed to prevent. A live model has no such round trip: items go
+     * in through the model's own API, and it says so itself with `items-changed`.
      *
-     * ```ts
-     * const m = row.model; m.push(item); row.model = m;   // → no splice, DOM unchanged
-     * ```
+     * The normalised `{ value, label }` descriptors moved to {@link options}, which is what a
+     * renderer drawing the list wants and is still a copy.
+     */
+    get model(): ComboWatchableModel | null;
+    /**
+     * The held model's items as the normalised `{ value, label }` descriptors (ADR 0046's item
+     * vocabulary), re-read whenever the model says it changed.
      *
-     * 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.
+     * A COPY, items included, for the reason the cache exists: `_options` is what every label
+     * lookup on this class reads, so a caller that retained it and mutated an item would move
+     * the row's inline text without the model knowing. The copy is what keeps the model the
+     * single source — mutate the MODEL and the descriptors follow, which is the whole point of
+     * holding one.
      *
      * 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.
+     * row actually holds. What the shape rules out is a per-item read: the call sites that had
+     * one — `_applyItemsChanged` in each browser selector, `_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 options(): AdwComboOption[];
+    /**
+     * The selected ITEM — `Adw.ComboRow:selected-item` / `Gtk.DropDown:selected-item`.
+     *
+     * The model's OWN item at {@link selectedIndex}, read through `get_item`, so
+     * `row.selectedItem === model.get_item(row.selectedIndex)` the way it is measured to hold
+     * in libadwaita. Not a descriptor: the item is whatever the model holds — a
+     * `GjsifyOptionObject`, a `Gtk.StringObject`, an application object — and handing back the
+     * normalised `{ value, label }` instead would make the identity comparison every
+     * `selected-item` consumer writes fail. {@link selectedValue} / {@link selectedLabel} are
+     * the descriptor side of the same question.
+     *
+     * `null` for the sentinel, for no model, and for an item the model declines to hand over.
+     */
+    get selectedItem(): unknown;
+    /**
+     * Replace the model — the `model` property write of ADR 0122 § 5.
+     *
+     * Assigning the model the state ALREADY holds does nothing at all: no splice, no selection
+     * emit, no `notify::`. Identity is the test, because identity is now what the property
+     * holds — two distinct models with equal contents are two different values of `model`, and
+     * GTK treats them that way.
+     *
+     * Otherwise the state detaches from the old model's `items-changed`, attaches to the new
+     * one's, re-reads the descriptors, and RE-RUNS AUTOSELECT: the selection lands on 0, or on
+     * {@link ADW_COMBO_NO_SELECTION} when the new model is empty. Not a clamp of the old index
+     * — measured, a replacement resets the selection to 0 even when the old index exists in the
+     * new model (`combo-probe2.js`: selected 2, new model of 3 → selected 0).
+     *
+     * The `notify::` set is measured and is NOT conditional on anything having changed: a
+     * non-null model notifies `selected`, `selected-item`, `model` in that order, even when the
+     * selection ends on the value it already had; `model = null` notifies `model` ALONE, and
+     * the selection goes to the sentinel silently.
+     *
+     * The splice ({@link subscribeItems}) is emitted first and only when the descriptors
+     * actually differ, because that channel is a renderer's instruction to move item views and
+     * an empty instruction is noise. It is NOT `Gio.ListModel::items-changed` — no model emits
+     * one when a WIDGET swaps which model it points at — it is this class telling its renderer
+     * what the swap did to the drawn list.
      */
-    get model(): AdwComboOption[];
+    setModel(model: ComboWatchableModel | null): void;
     /**
-     * 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 ({@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 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.
+     * The held model moved under us — `Gio.ListModel::items-changed`, forwarded to the
+     * renderer and then applied to the selection the way `GtkSingleSelection` applies it.
+     *
+     * Four cases, all MEASURED (`combo-probe2.js`, GJS 1.88.01 / GTK 4.22.5), and the notify
+     * ORDER here is the inverse of the `selected`-write path — `selected-item` comes FIRST,
+     * because the item under the selection changed before the index did:
+     *
+     *   - nothing selected → autoselect takes 0 as soon as the model has one, notifying
+     *     `selected-item` then `selected`;
+     *   - the change sits entirely AFTER the selection → the index still addresses the same
+     *     item, no notify at all;
+     *   - entirely BEFORE it → the item did not change, only its position did, so the index
+     *     shifts by `added - removed` and ONLY `selected` notifies;
+     *   - the change COVERS the selection → the selected item is gone, so the index clamps to
+     *     `min(position, n_items - 1)` (the sentinel for an emptied model) and `selected-item`
+     *     notifies whether or not the index moved — which is what makes a replace-in-place
+     *     (`removed: 1, added: 1` at the selection) notify `selected-item` alone.
      */
-    setModel(model: AdwComboOption[]): void;
+    private _onItemsChanged;
     /**
-     * The selected option index, or {@link ADW_COMBO_NO_SELECTION}. May also sit PAST the
-     * options length: {@link setSelectedIndex} is deliberately permissive, mirroring a
-     * `guint` property that takes any position. {@link selectedValue} reads `''` in both
-     * cases, which is why the sentinel is what distinguishes "nothing selected" from "an
-     * empty label".
+     * The selected option index, or {@link ADW_COMBO_NO_SELECTION}.
+     *
+     * Always either the sentinel or a position the model HAS: every door that writes it
+     * ({@link setSelectedIndex}, {@link select}, autoselect) refuses an index the model does
+     * not address, so this is the one place "nothing selected" is spelled.
      */
     get selectedIndex(): number;
     /**
@@ -142,7 +243,16 @@ export declare class ComboState {
      * nothing.
      */
     get presentsChooser(): boolean;
-    /** Programmatic index set — notifies `interactive: false`. Returns whether it changed. */
+    /**
+     * Programmatic index set — notifies `interactive: false`. Returns whether it changed.
+     *
+     * An index the model does not have is IGNORED, silently: no change, no notify, no error.
+     * That is measured on both widgets (`combo-probe2.js`: `selected = 5` on a model of 3, and
+     * `selected = GTK_INVALID_LIST_POSITION` on a non-empty model, each leave `selected` where
+     * it was and emit nothing). `Adw.ComboRow` forwards the position to
+     * `gtk_single_selection_set_selected`, which validates it — so this is not a renderer
+     * policy and no renderer states its own answer any more.
+     */
     setSelectedIndex(index: number): boolean;
     /** The selected option's `value`, or `''` when out of range. */
     get selectedValue(): string;
@@ -151,17 +261,13 @@ export declare class ComboState {
     /** Programmatic value set — moves the index to the first option with this `value`. No-op for an unknown value. */
     setSelectedValue(value: string): boolean;
     /**
-     * Whether `index` addresses an option that exists.
-     *
-     * The bounds arithmetic lives here; the POLICY for a programmatic out-of-range set does
-     * not, because this tree cannot settle it: `adw_combo_row_set_selected` forwards the
-     * position straight to `gtk_single_selection_set_selected` and documents
-     * `GTK_INVALID_LIST_POSITION` as a legal argument, but `refs/gtk` is EMPTY so what
-     * GtkSingleSelection does with it is not verifiable here. Each renderer therefore states
-     * its own answer against this one predicate: {@link setSelectedIndex} keeps the permissive
-     * model (an index past the end is how "nothing selected" is spelled and
-     * {@link selectedValue} reads `''`), while `<gtk-drop-down>` rejects the set, as its
-     * published `selected` docs promise.
+     * Whether `index` addresses an item the held model has.
+     *
+     * The ONE bounds predicate: {@link setSelectedIndex} and {@link select} both refuse what it
+     * refuses, so a programmatic set and a user pick agree about what is out of range. They
+     * once did not — `refs/gtk` is empty, so what `gtk_single_selection_set_selected` does with
+     * `GTK_INVALID_LIST_POSITION` was not verifiable in this tree and each renderer stated its
+     * own answer. It is now measured (see {@link setSelectedIndex}) and there is one.
      */
     hasIndex(index: number): boolean;
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/adwaita-core",
-    "version": "0.64.12-next.281",
+    "version": "0.64.12",
     "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",
@@ -67,9 +67,9 @@
         "headless"
     ],
     "devDependencies": {
-        "@gjsify/cli": "0.64.12-next.281",
+        "@gjsify/cli": "^0.64.12",
         "@gjsify/node-gi": "file:../../../packages/node-gi/node-gi",
-        "@gjsify/unit": "0.64.12-next.281",
+        "@gjsify/unit": "^0.64.12",
         "@types/node": "^25.9.2",
         "typescript": "^6.0.3"
     },
@@ -92,6 +92,5 @@
     "bugs": {
         "url": "https://github.com/gjsify/gjsify/issues"
     },
-    "homepage": "https://github.com/gjsify/gjsify/tree/main/packages/web/adwaita-core#readme",
-    "gitHead": "c4d2e266c0d9849860b9828c14ebfe37b6d493b8"
+    "homepage": "https://github.com/gjsify/gjsify/tree/main/packages/web/adwaita-core#readme"
 }