@gjsify/adwaita-core 0.47.0 → 0.49.0

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. */
@@ -311,15 +335,24 @@ export declare class TabViewState<T = unknown> {
     /** The selected page, or `null`. */
     get selectedPage(): AdwTabPageState<T> | null;
     /**
-     * Select a page by id. Returns whether the selection changed.
+     * Select a page — by the PAGE, or by its id. Returns whether the selection changed.
      *
      * An unknown id is refused, and `null` is accepted only while the view is empty —
      * `adw_tab_view_set_selected_page` asserts `ADW_IS_TAB_PAGE` +
      * `page_belongs_to_this_view` when `n_pages > 0`, and `selected_page == NULL`
      * otherwise. `interactive` defaults to `true` because this IS the explicit call;
      * the model-driven paths (first-page auto-select, close successor) pass `false`.
+     *
+     * THE PAGE OVERLOAD IS WHAT MAKES `page_belongs_to_this_view` TRUE HERE. An id is
+     * unique within ONE view (`_nextId` counts per view), so handing this view another
+     * view's page and reading only its id selects the page of the same id HERE — measured
+     * on the renderers' `selectedPage` setters, where `viewA.selectedPage = viewB.pages[2]`
+     * moved viewA to index 2 rather than refusing. The object is what separates them, so
+     * the identity check belongs at the one place that owns the page list, and the refusal
+     * carries the same diagnostic C raises rather than being a silent no-op in two
+     * renderers.
      */
-    setSelectedPage(id: string | null, interactive?: boolean): boolean;
+    setSelectedPage(page: AdwTabPageState<T> | string | null, interactive?: boolean): boolean;
     /**
      * Select the page at `n` — the Alt+1…Alt+9 / Alt+0 path (`select_nth_page_cb`;
      * Alt+0 is `n = 9`, since pages count from 0).

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/adwaita-core",
-    "version": "0.47.0",
+    "version": "0.49.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.49.0",
+        "@gjsify/unit": "^0.49.0",
         "@types/node": "^25.9.2",
         "typescript": "^6.0.3"
     },