@gjsify/adwaita-web 0.47.0 → 0.48.0

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

@@ -1,19 +1,62 @@
-// <adw-combo-row> — row with a title/subtitle and a dropdown select. `items` is a JSON
-// `string[]`, `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 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 options list, the two-way index↔value mapping, the
+// 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
 // and lives in `@gjsify/adwaita-core` (ADR 0004) as {@link ComboState}; this element keeps
 // only the DOM half — the <select>, the inline value label and `notify::selected`.
 //
+// THE MODEL IS INPUT, AND INPUT STAYS LIVE. This row and `<gtk-drop-down>` are the same
+// list widget on GTK and share that one `ComboState` here — but the row used to parse its
+// items once in `connectedCallback`, observe only `['title','subtitle','selected']` and
+// publish no accessor at all, so a model replaced after connect changed nothing, silently
+// (#1525). Both spellings now reach the same rebuild, and
+// `scripts/check-adwaita-collection-reactivity.mjs` holds the rule for every collection
+// either renderer takes in.
+//
+// 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
+// `<option>` and leaves the other hundred nodes standing; the previous code dropped every
+// node on every assignment, which is also what threw away the browser's own state for the
+// rows that did not change. It is what removes the ordering hazard this file used to
+// carry as a comment: the splice arrives BEFORE the selection change, so the subscriber's
+// index write already lands on the new list.
+//
+// Attributes:
+//   title / subtitle — the text column.
+//   model            — JSON array: `["a","b"]` or `[{"value":"a","label":"A"}]`.
+//   selected         — the selected index (number).
+// 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.
+//   selectedValue    — the selected option's value ('' when empty) (get/set-by-value).
+//   selectedItem     — the selected option descriptor, 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
+//     always been the interactive half of `ComboState`'s split, and `adw-row-state.spec.ts`
+//     pins it.
+//
 // Adapted from Adwaita Web UI Framework (https://github.com/mclellac/adwaita-web).
 // Copyright (c) 2025 csm. MIT License.
 // Modifications: Reimplemented as Web Component for @gjsify/adwaita-web;
 //   title/subtitle text column added to match Adw.ComboRow; the selection state
 //   machine composed from @gjsify/adwaita-core.
 
-import { ComboState, deriveRowLabels, normalizeComboOptions } from '@gjsify/adwaita-core';
+import { ComboState, deriveRowLabels, normalizeComboOptions, parseListModel } from '@gjsify/adwaita-core';
+import type { AdwComboOption, AdwListItemsChanged, AdwListModelInput } from '@gjsify/adwaita-core';
 
 export class AdwComboRow extends HTMLElement {
     private _select!: HTMLSelectElement;
@@ -25,9 +68,27 @@ export class AdwComboRow extends HTMLElement {
     private _initialized = false;
 
     static get observedAttributes() {
-        return ['title', 'subtitle', 'selected'];
+        return ['title', 'subtitle', 'model', 'selected'];
     }
 
+    /** The list model (`Adw.ComboRow:model`). Setting it splices the <select> and clamps the selection. */
+    get model(): AdwComboOption[] {
+        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));
+    }
+
+    /**
+     * 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.
+     */
     get selected(): number {
         return this._initialized ? this._state.selectedIndex : parseInt(this.getAttribute('selected') || '0', 10);
     }
@@ -36,17 +97,47 @@ export class AdwComboRow extends HTMLElement {
         this.setAttribute('selected', String(value));
     }
 
+    /**
+     * The selected option's `value`, or '' when nothing is selected (Adw.ComboRow:selected-item).
+     *
+     * Assigning routes through `selected`, i.e. through the attribute, so a set BY VALUE
+     * and a set BY INDEX leave the element in the same observable state — including the
+     * reflected `selected=` a consumer or a stylesheet may be reading. An unknown value is
+     * a no-op, as on `<gtk-drop-down>`.
+     */
+    get selectedValue(): string {
+        return this._state.selectedValue;
+    }
+
+    set selectedValue(value: string) {
+        const index = this._state.model.findIndex((option) => option.value === value);
+        if (index >= 0) this.selected = index;
+    }
+
+    /**
+     * The selected option descriptor, 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.
+     */
+    get selectedItem(): AdwComboOption | null {
+        return this._state.model[this._state.selectedIndex] ?? null;
+    }
+
     connectedCallback() {
         if (this._initialized) return;
         this._initialized = true;
 
-        const items: string[] = JSON.parse(this.getAttribute('items') || '[]');
         // Seed the headless state BEFORE subscribing, so building the initial DOM below is
         // not driven by a change notification. The string→descriptor mapping is core's, so
         // this row and `<gtk-drop-down>` accept one option vocabulary.
-        this._state.setOptions(normalizeComboOptions(items));
+        //
+        // Only when the PROPERTY was not already set, the rule `<adw-data-grid>` and
+        // `<gtk-drop-down>` both follow: a model assigned to a detached element must
+        // survive being attached, and an absent attribute must not blank it.
+        if (this._state.count === 0) this._state.setModel(parseListModel(this.getAttribute('model')));
         this._state.setSelectedIndex(parseInt(this.getAttribute('selected') || '0', 10));
-        const selectedIdx = this._state.selectedIndex;
 
         const text = document.createElement('div');
         text.className = 'adw-row-text';
@@ -58,20 +149,14 @@ export class AdwComboRow extends HTMLElement {
 
         this._valueEl = document.createElement('span');
         this._valueEl.className = 'adw-row-value';
-        this._valueEl.textContent = this._state.selectedLabel;
 
-        const select = document.createElement('select');
-        items.forEach((item, i) => {
-            const option = document.createElement('option');
-            option.value = String(i);
-            option.textContent = item;
-            if (i === selectedIdx) option.selected = true;
-            select.appendChild(option);
-        });
+        this._select = document.createElement('select');
 
-        this.replaceChildren(text, this._valueEl, select);
+        this.replaceChildren(text, this._valueEl, this._select);
 
-        this._select = select;
+        // WHERE the model changed — applied before the selection change below, which is
+        // the ordering that lets that subscriber's index write land on the new list.
+        this._state.subscribeItems((change) => this._applyItemsChanged(change));
 
         // The core state drives the inline label + the <select> on every change,
         // and the notify::selected event only on an interactive pick.
@@ -95,13 +180,15 @@ export class AdwComboRow extends HTMLElement {
             this._state.select(this._select.selectedIndex);
         });
 
-        this._syncChooser();
+        this._renderOptions();
         this._renderText();
     }
 
     attributeChangedCallback(name: string, _old: string | null, value: string | null) {
         if (!this._initialized) return;
-        if (name === 'selected') {
+        if (name === 'model') {
+            this._state.setModel(parseListModel(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.
             this._state.setSelectedIndex(parseInt(value || '0', 10));
@@ -110,6 +197,58 @@ export class AdwComboRow extends HTMLElement {
         }
     }
 
+    /**
+     * Build one `<option>` for a model item.
+     *
+     * ITS `value` IS THE MODEL'S value, not the position. The position used to be written
+     * there with a comment defending it, and nothing in this package or its consumers ever
+     * read it back — while it made every insertion renumber the whole tail, which is the
+     * one thing a splice exists to avoid. The element still addresses its model by
+     * POSITION (`selectedIndex`); what the attribute now carries is the descriptor's own
+     * value, which is also what a form submission would have wanted.
+     */
+    private _createOption(option: AdwComboOption): HTMLOptionElement {
+        const el = document.createElement('option');
+        el.value = option.value;
+        el.textContent = option.label;
+        return el;
+    }
+
+    /**
+     * Apply one `items-changed` to the `<option>` list — remove `removed` nodes at
+     * `position`, insert `added` fresh ones there, touch nothing else.
+     *
+     * A no-op before `connectedCallback` has built the DOM, which is what lets `model` be
+     * assigned to a detached element: the state keeps the model and the connect path
+     * renders it whole.
+     */
+    private _applyItemsChanged(change: AdwListItemsChanged): void {
+        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
+        // 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) this._select.insertBefore(this._createOption(option), before);
+        }
+    }
+
+    /**
+     * Build the whole `<option>` list — the CONNECT path only, where there is no previous
+     * list to splice against.
+     *
+     * Every later assignment goes through {@link _applyItemsChanged}.
+     */
+    private _renderOptions(): void {
+        if (!this._initialized) return;
+        this._select.replaceChildren(...this._state.model.map((option) => this._createOption(option)));
+        this._select.selectedIndex = this._state.selectedIndex;
+        this._valueEl.textContent = this._state.selectedLabel;
+        this._syncChooser();
+    }
+
     /**
      * `model_changed`: one option or none is not a choice, so the arrow goes and the row
      * stops being activatable.

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

@@ -1,29 +1,40 @@
 // <adw-spin-row> — row with a title/subtitle and a numeric spin control (+/− buttons).
 //
-// The ADJUSTMENT state machine (value/min/max/step plus the clamp-on-every-mutation and
-// the change detection) is HEADLESS and lives in `@gjsify/adwaita-core` (ADR 0004) as
+// The ADJUSTMENT state machine (the range, the clamp on every mutation and the change
+// detection) is HEADLESS and lives in `@gjsify/adwaita-core` (ADR 0004) as
 // {@link SpinState}; this element keeps only the DOM half — the −/input/+ control, the
 // step-precision display (the `Adw.SpinRow:digits` concern, which belongs to the widget
 // rather than to the adjustment) and the `notify::value` event.
 //
+// THE RANGE IS ONE ATTRIBUTE, `adjustment`, and it is JSON:
+//
+//     <adw-spin-row title="Zoom" adjustment='{"lower":1,"upper":20,"stepIncrement":1}'>
+//
+// `min` / `max` / `step` are gone. `Adw.SpinRow` has no such properties — it has an
+// `adjustment`, and three renderers spelling that range three ways is what ADR 0047
+// removes. The value is the portable `AdwAdjustment`, so a range authored here is the one
+// the NativeScript row and the React Native widget take. The same markup door
+// `<adw-combo-row model=…>` opens for its list, on the same reasoning.
+//
 // Adapted from Adwaita Web UI Framework (https://github.com/mclellac/adwaita-web).
 // Copyright (c) 2025 csm. MIT License.
 // Modifications: Reimplemented as Web Component for @gjsify/adwaita-web;
 //   title/subtitle text column added to match Adw.SpinRow; the adjustment state
 //   machine composed from @gjsify/adwaita-core.
 
-import { SpinState, deriveRowLabels } from '@gjsify/adwaita-core';
+import { SpinState, deriveRowLabels, normalizeAdjustment, parseAdjustment } from '@gjsify/adwaita-core';
+import type { AdwAdjustment, AdwAdjustmentInput } from '@gjsify/adwaita-core';
 
 export class AdwSpinRow extends HTMLElement {
     private _input!: HTMLInputElement;
     private _titleEl!: HTMLSpanElement;
     private _subtitleEl!: HTMLSpanElement;
-    /** The headless value/min/max/step adjustment with clamping (ADR 0004). */
+    /** The headless adjustment: the range, the clamp and the two signals (ADR 0004, ADR 0047). */
     private readonly _state = new SpinState();
     private _initialized = false;
 
     static get observedAttributes() {
-        return ['title', 'subtitle', 'value', 'min', 'max', 'step'];
+        return ['title', 'subtitle', 'value', 'adjustment'];
     }
 
     get value(): number {
@@ -37,16 +48,35 @@ export class AdwSpinRow extends HTMLElement {
         this._syncValue();
     }
 
+    /**
+     * The numeric range — `Adw.SpinRow:adjustment`, as the portable value.
+     *
+     * Reads back whole; writes MERGE, so `el.adjustment = { upper: 20 }` moves one bound
+     * and leaves the value where it is. A string is read as the JSON the attribute carries,
+     * so the property and the attribute mean the same thing.
+     */
+    get adjustment(): AdwAdjustment {
+        return this._state.adjustment;
+    }
+
+    set adjustment(v: AdwAdjustmentInput | string) {
+        this._state.configure(typeof v === 'string' ? parseAdjustment(v) : v);
+    }
+
     connectedCallback() {
         if (this._initialized) return;
         this._initialized = true;
 
         // Seed the headless adjustment BEFORE subscribing, so building the initial
-        // DOM below is not driven by a change notification.
-        this._state.setMin(parseFloat(this.getAttribute('min') || '0'));
-        this._state.setMax(parseFloat(this.getAttribute('max') || '100'));
-        this._state.setStep(parseFloat(this.getAttribute('step') || '1'));
-        this._state.setValue(this._roundToStep(parseFloat(this.getAttribute('value') || String(this._state.min))));
+        // DOM below is not driven by a change notification. The range comes whole, so the
+        // authored `value` attribute is applied against the range it was authored beside
+        // rather than against whatever a partly-seeded state held.
+        const range = normalizeAdjustment(parseAdjustment(this.getAttribute('adjustment')));
+        this._state.configure(range);
+        const authoredValue = this.getAttribute('value');
+        this._state.setValue(
+            this._roundToStep(authoredValue === null ? range.value : Number.parseFloat(authoredValue)),
+        );
 
         const text = document.createElement('div');
         text.className = 'adw-row-text';
@@ -62,7 +92,7 @@ export class AdwSpinRow extends HTMLElement {
         const decBtn = document.createElement('button');
         decBtn.className = 'adw-spin-dec';
         decBtn.textContent = '−';
-        decBtn.addEventListener('click', () => this._adjust(-this._state.step));
+        decBtn.addEventListener('click', () => this._adjust(-this._state.adjustment.stepIncrement));
 
         const input = document.createElement('input');
         input.type = 'text';
@@ -80,7 +110,7 @@ export class AdwSpinRow extends HTMLElement {
         const incBtn = document.createElement('button');
         incBtn.className = 'adw-spin-inc';
         incBtn.textContent = '+';
-        incBtn.addEventListener('click', () => this._adjust(this._state.step));
+        incBtn.addEventListener('click', () => this._adjust(this._state.adjustment.stepIncrement));
 
         control.append(decBtn, input, incBtn);
         this.replaceChildren(text, control);
@@ -99,21 +129,12 @@ export class AdwSpinRow extends HTMLElement {
             this._renderText();
             return;
         }
-        const num = parseFloat(val || '0');
-        switch (name) {
-            case 'value':
-                this._state.setValue(this._roundToStep(num));
-                break;
-            case 'min':
-                this._state.setMin(num);
-                break;
-            case 'max':
-                this._state.setMax(num);
-                break;
-            case 'step':
-                this._state.setStep(num);
-                break;
+        if (name === 'adjustment') {
+            this._state.configure(parseAdjustment(val));
+            return;
         }
+        // `value`, the only other observed attribute reaching here.
+        this._state.setValue(this._roundToStep(Number.parseFloat(val || '0')));
     }
 
     private _renderText() {
@@ -151,7 +172,7 @@ export class AdwSpinRow extends HTMLElement {
 
     private _roundToStep(n: number): number {
         if (!Number.isFinite(n)) return n;
-        const decimals = this._countDecimals(this._state.step);
+        const decimals = this._countDecimals(this._state.adjustment.stepIncrement);
         return decimals > 0 ? parseFloat(n.toFixed(decimals)) : n;
     }
 
@@ -162,7 +183,7 @@ export class AdwSpinRow extends HTMLElement {
     }
 
     private _formatValue(v: number): string {
-        const decimals = this._countDecimals(this._state.step);
+        const decimals = this._countDecimals(this._state.adjustment.stepIncrement);
         return decimals > 0 ? v.toFixed(decimals) : String(v);
     }
 }

package/src/elements/adw-split-button.ts

@@ -11,14 +11,15 @@
 //   tooltip          — tooltip/accessible name of the action half.
 //   dropdown-tooltip — tooltip of the dropdown half; empty restores "More Options".
 //   direction        — none | up | down | left | right (default down).
-//   menu             — JSON array of entries, each `{ "label", "action"? }`.
+//   menu-model       — JSON array in the portable menu model (ADR 0042): items,
+//                      sections (`{"section":[…]}`) and submenus (`{"submenu":[…]}`).
 //   disabled, flat, suggested, destructive — boolean flags.
 // Events (all CustomEvent, bubbles — mirror the Adw.SplitButton GObject signals):
 //   `clicked`         — the primary action half was activated.
 //   `notify::active`  — the dropdown menu was opened/closed (detail.active).
 //   `notify::<prop>`  — one per GObject property the state machine notified,
 //                       in libadwaita's emission order.
-//   `menu-activated`  — a menu entry was chosen (detail.label / .action / .index).
+//   `menu-activated`  — a menu item was chosen (detail.label / .action / .id / .path).
 //
 // All of the behaviour above lives in `@gjsify/adwaita-core` (ADR 0004) as
 // {@link SplitButtonState}; this element only paints it and translates DOM events
@@ -36,15 +37,28 @@
 // Modifications: Implemented as a Web Component for @gjsify/adwaita-web.
 
 import {
+    ADW_MENU_SURFACE_WEB,
     SplitButtonState,
+    assertMenuRenderable,
     isSplitButtonDirection,
-    parseMenuEntries,
+    menuRefusals,
+    normalizeMenuModel,
+    parseMenuModel,
     resolveDropdownTooltip,
     splitButtonArrowIcon,
     splitButtonPopupDirection,
     splitButtonRootState,
 } from '@gjsify/adwaita-core';
-import type { AdwArrowIcon, AdwMenuEntry, SplitButtonChange, SplitButtonDirection } from '@gjsify/adwaita-core';
+import type {
+    AdwArrowIcon,
+    AdwMenuActions,
+    AdwMenuInput,
+    AdwMenuModel,
+    SplitButtonChange,
+    SplitButtonDirection,
+} from '@gjsify/adwaita-core';
+
+import { PopoverMenuView } from './popover-menu.js';
 
 // SIDE-EFFECT import, deliberately separate from the type import below: it is
 // what guarantees `gtk-popover` is defined before this module's own
@@ -109,6 +123,8 @@ export class AdwSplitButton extends HTMLElement {
     private _dropdownEl!: HTMLButtonElement;
     private _arrowEl!: GtkImage;
     private _menuEl!: GtkPopover;
+    private _menuView!: PopoverMenuView;
+    private _actions: AdwMenuActions | null = null;
     /** Inline text content, captured before we take over the subtree. */
     private _inlineLabel = '';
     /** Last `open` value reflected as `notify::active`, so the event fires once per flip. */
@@ -123,7 +139,7 @@ export class AdwSplitButton extends HTMLElement {
             'tooltip',
             'dropdown-tooltip',
             'direction',
-            'menu',
+            'menu-model',
             'disabled',
             'flat',
             'suggested',
@@ -162,12 +178,74 @@ export class AdwSplitButton extends HTMLElement {
         this.removeAttribute('label');
     }
 
-    get menuItems(): readonly AdwMenuEntry[] {
+    /** The menu, normalised (ADR 0042). Empty when the dropdown has none. */
+    get menuModel(): AdwMenuModel {
         return this._state.menuModel ?? [];
     }
 
-    set menuItems(value: readonly AdwMenuEntry[]) {
-        this._state.setMenuModel(Array.isArray(value) ? value.map((entry) => ({ ...entry })) : null);
+    /**
+     * Set the menu from anything the portable model accepts — a bare `string[]`, item
+     * descriptors, sections, submenus.
+     *
+     * The REFUSAL is here rather than at render time: a `custom` item names an
+     * application widget this surface cannot host, and discovering that as a blank row
+     * three interactions later is what {@link assertMenuRenderable} exists to prevent.
+     */
+    set menuModel(value: AdwMenuInput) {
+        // Refused BEFORE it is stored, so a throw leaves the widget showing the menu it
+        // had rather than one it cannot draw.
+        this._state.setMenuModel(this._acceptMenu(value));
+        if (this._initialized) this._render();
+    }
+
+    /**
+     * Normalise, REFUSE, store — the one door every menu comes through.
+     *
+     * The property setter is not the only way a menu arrives: an attribute is, and the
+     * first cut refused only the setter, so a `custom` item written in markup drew
+     * exactly the row `assertMenuRenderable` exists to prevent — one that reads like a
+     * command and does nothing.
+     *
+     * THE TWO DOORS REFUSE DIFFERENTLY, and the difference is which side can hear it.
+     * A property assignment is a CALL, so it throws and the caller can catch. An
+     * attribute is MARKUP, parsed by the browser: a throw from `connectedCallback` is
+     * not delivered to whoever appended the element, it is reported as an uncaught
+     * page error — measured, it broke `adwaita-upgrade-order.spec.ts`, which counts
+     * exactly those. Nobody can handle it and everybody else pays for it. So the
+     * attribute path REFUSES THE MENU (no menu, and a menu-less dropdown is
+     * insensitive, which is visible) and says why on `console.error`.
+     *
+     * A REFUSAL AND A TYPO ARE STILL DIFFERENT THINGS. `parseMenuModel` is total
+     * because malformed JSON is an author slip and must not stop the element
+     * upgrading; `custom` is well-formed, deliberate, and unhonourable here.
+     */
+    private _acceptMenu(input: AdwMenuInput, strict = true): AdwMenuModel {
+        const model = normalizeMenuModel(input);
+        if (strict) {
+            assertMenuRenderable(model, ADW_MENU_SURFACE_WEB);
+            return model;
+        }
+        const refusals = menuRefusals(model, ADW_MENU_SURFACE_WEB);
+        if (refusals.length === 0) return model;
+        // `console.error` is the browser's own channel for "this is wrong, the page
+        // continues" — and the alternative here is a row that lies.
+        console.error(`${ADW_MENU_SURFACE_WEB.name} cannot render this menu, so it has none:`);
+        for (const refusal of refusals) console.error(`  [${refusal.path.join('.')}] ${refusal.message}`);
+        return [];
+    }
+
+    /**
+     * What the action group publishes about the actions this menu names — the portable
+     * stand-in for a `GActionGroup`, and the ONLY place a menu's enabled/checked state
+     * can come from (ADR 0042). Setting it re-renders the rows.
+     */
+    get actions(): AdwMenuActions | null {
+        return this._actions;
+    }
+
+    set actions(value: AdwMenuActions | null) {
+        this._actions = value ?? null;
+        this._menuView?.setActions(this._actions);
         if (this._initialized) this._render();
     }
 
@@ -248,8 +326,29 @@ export class AdwSplitButton extends HTMLElement {
         // `notify::active` all read it). A dismissal the popover owns — outside
         // click, Escape — is fed back in here rather than diverging.
         this._menuEl.subscribe((open) => {
-            if (!open) this._state.closeMenu();
+            if (!open) {
+                this._state.closeMenu();
+                // A menu that reopens three pages deep is a menu the reader cannot get
+                // out of, so a dismissal returns it to the top.
+                this._menuView.reset();
+            }
+        });
+        this._menuView = new PopoverMenuView(this._menuEl, 'adw-split-button-menu', (path) => {
+            const activated = this._state.activateMenuItem(path);
+            if (activated === null) return;
+            this.dispatchEvent(
+                new CustomEvent('menu-activated', {
+                    bubbles: true,
+                    detail: {
+                        label: activated.label,
+                        action: activated.action,
+                        id: activated.id ?? activated.label,
+                        path: [...path],
+                    },
+                }),
+            );
         });
+        this._menuView.setActions(this._actions);
 
         this._actionEl.addEventListener('click', () => {
             if (this.hasAttribute('disabled')) return;
@@ -284,8 +383,8 @@ export class AdwSplitButton extends HTMLElement {
             case 'dropdown-tooltip':
                 this._state.setDropdownTooltip(value ?? '');
                 break;
-            case 'menu':
-                this._state.setMenuModel(parseMenuEntries(value));
+            case 'menu-model':
+                this._state.setMenuModel(this._acceptMenu(parseMenuModel(value), false));
                 break;
             default:
                 break;
@@ -307,9 +406,11 @@ export class AdwSplitButton extends HTMLElement {
         const direction = this.getAttribute('direction');
         if (isSplitButtonDirection(direction)) this._state.setDirection(direction);
         this._state.setDropdownTooltip(this.getAttribute('dropdown-tooltip') ?? '');
-        // The `menuItems` property may have been set before the element upgraded;
+        // The `menuModel` property may have been set before the element upgraded;
         // the attribute only seeds an otherwise empty menu.
-        if (this._state.menuModel === null) this._state.setMenuModel(parseMenuEntries(this.getAttribute('menu')));
+        if (this._state.menuModel === null) {
+            this._state.setMenuModel(this._acceptMenu(parseMenuModel(this.getAttribute('menu-model')), false));
+        }
     }
 
     /**
@@ -344,7 +445,7 @@ export class AdwSplitButton extends HTMLElement {
         this._render();
         // Focus lands in the menu on open, AFTER _render has built the rows —
         // otherwise the popover's arrow keys have nothing to move from.
-        if (opened) this._menuEl.items[0]?.focus();
+        if (opened) this._menuView.focusableRows[0]?.focus();
     }
 
     private _render(): void {
@@ -423,32 +524,9 @@ export class AdwSplitButton extends HTMLElement {
     }
 
     private _renderMenu(): void {
-        this._menuEl.replaceChildren();
         this._menuEl.open = this._state.open;
-
-        for (const [index, entry] of (this._state.menuModel ?? []).entries()) {
-            const item = document.createElement('button');
-            item.type = 'button';
-            // `.adw-popover-item` is what makes the row navigable: it is the selector
-            // `<gtk-popover>` walks for arrow/Home/End/Enter.
-            item.className = 'adw-popover-item adw-split-button-menu-item';
-            item.setAttribute('role', 'menuitem');
-            item.tabIndex = -1;
-            item.textContent = entry.label;
-            item.addEventListener('click', () => {
-                // By position, never by label: two entries called "Copy" are legal
-                // and must each dispatch their own action.
-                const activated = this._state.activateMenuEntry(index);
-                if (activated === null) return;
-                this.dispatchEvent(
-                    new CustomEvent('menu-activated', {
-                        bubbles: true,
-                        detail: { label: activated.label, action: activated.action, index },
-                    }),
-                );
-            });
-            this._menuEl.appendChild(item);
-        }
+        this._menuView.setMenuModel(this._state.menuModel ?? []);
+        this._menuView.render();
     }
 }