@gjsify/adwaita-web 0.47.0 → 0.48.0

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);

package/src/elements/gtk-menu-button.ts

@@ -9,10 +9,13 @@
 // `normalizeIconName` guard is what keeps a multi-token `icon-name="a b"` from
 // shipping a stray CSS class — for the button icon and for every menu entry's.
 //
-// The `menu` attribute is a JSON array of `{ "id"?, "label", "icon"? }`. Choosing an
-// item closes the popover and fires `menu-item-activated` (CustomEvent, bubbles,
-// detail `{ id, label, index }`) with `id` falling back to `label`, matching the NS
-// twin.
+// The `menu-model` attribute is a JSON array in the portable menu model (ADR 0042) —
+// items, sections and submenus, with the same attributes GTK reads. Choosing an item
+// closes the popover and fires `menu-item-activated` (CustomEvent, bubbles, detail
+// `{ id, label, path }`) with `id` falling back to `label`, matching the NS twin. The
+// rows themselves are `PopoverMenuView`'s, shared with `<adw-split-button>`: the split
+// button's dropdown half IS a GtkMenuButton, so one popup implementation is the whole
+// point.
 //
 // Reference: refs/gtk/gtk/gtkmenubutton.c (GtkMenuButton)
 // Reference: refs/libadwaita/src/stylesheet/widgets/_buttons.scss (menubutton)
@@ -22,12 +25,18 @@
 // Modifications: Implemented as a Web Component for @gjsify/adwaita-web.
 
 import {
+    ADW_MENU_SURFACE_WEB,
+    assertMenuRenderable,
     isSplitButtonDirection,
+    menuRefusals,
     menuButtonPopupDirection,
-    parseMenuEntries,
-    stringIsNotEmpty,
+    menuItemAt,
+    normalizeMenuModel,
+    parseMenuModel,
 } from '@gjsify/adwaita-core';
-import type { AdwMenuEntry, SplitButtonDirection } from '@gjsify/adwaita-core';
+import type { AdwMenuActions, AdwMenuInput, AdwMenuModel, SplitButtonDirection } from '@gjsify/adwaita-core';
+
+import { PopoverMenuView } from './popover-menu.js';
 
 // SIDE-EFFECT import, deliberately separate from the type import below: it guarantees
 // `gtk-popover` is defined before this module's `customElements.define` can upgrade a
@@ -40,25 +49,6 @@ import type { GtkPopover } from './gtk-popover.js';
 
 import { createGtkImage } from './gtk-image.js';
 
-/**
- * A menu entry — `@gjsify/adwaita-core`'s {@link AdwMenuEntry} under the name both
- * renderers export it as.
- *
- * IT KEEPS THE `Adw` PREFIX WHILE THE ELEMENT ABOVE IT DOES NOT, and the reason is not
- * "the name it has always used" — ADR 0034 clause 1 just moved every name in this file
- * that had one. It is that this is not a WIDGET name: clause 1 is about the tag, and
- * this is the descriptor a consumer writes menu entries with. `@gjsify/adwaita-
- * nativescript` exports `AdwMenuItem` for the same type, and that port deliberately
- * keeps `Adw` throughout, so renaming this half would give one object two spellings —
- * which is the thing the ADR is removing, not applying. (`GtkDropDownOption` next door
- * DID move: its NativeScript twin exports no such name, so there was nothing to split.)
- *
- * It used to be a SECOND declaration of the same shape, and the NativeScript menu
- * button declared a THIRD that was missing `icon` entirely. One type, so a consumer
- * writing menu entries writes the same object for either renderer.
- */
-export type AdwMenuItem = AdwMenuEntry;
-
 /**
  * Where the popover sits, per `GtkArrowType`. `menuButtonPopupDirection` folds `none`
  * onto `down` — GtkMenuButton's rule, not ours; this table is only the
@@ -77,13 +67,14 @@ const POPOVER_POSITIONS = {
 export class GtkMenuButton extends HTMLElement {
     private _buttonEl!: HTMLButtonElement;
     private _popoverEl!: GtkPopover;
-    private _items: AdwMenuItem[] = [];
+    private _model: AdwMenuModel = [];
+    private _actions: AdwMenuActions | null = null;
     private _menuTitle = '';
     private _initialized = false;
-    private _itemButtons: HTMLButtonElement[] = [];
+    private _menuView!: PopoverMenuView;
 
     static get observedAttributes() {
-        return ['icon-name', 'menu-title', 'menu', 'disabled', 'flat', 'circular', 'direction'];
+        return ['icon-name', 'menu-title', 'menu-model', 'disabled', 'flat', 'circular', 'direction'];
     }
 
     /** Whether the popover menu is currently open. */
@@ -91,13 +82,69 @@ export class GtkMenuButton extends HTMLElement {
         return this._popoverEl?.open ?? false;
     }
 
-    /** The menu entries. Setting rebuilds the popover. */
-    get menuItems(): AdwMenuItem[] {
-        return this._items;
+    /** The menu, normalised (ADR 0042). Setting rebuilds the popover. */
+    get menuModel(): AdwMenuModel {
+        return this._model;
     }
 
-    set menuItems(value: AdwMenuItem[]) {
-        this._items = Array.isArray(value) ? value.map((it) => ({ ...it })) : [];
+    /**
+     * Set the menu from anything the portable model accepts. Refused HERE, at the
+     * assignment, for a `custom` item this surface cannot host — see the split button's
+     * note on the same setter.
+     */
+    set menuModel(value: AdwMenuInput) {
+        this._model = this._acceptMenu(value);
+        if (this._initialized) this._renderMenu();
+    }
+
+    /**
+     * 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 source of a menu's enabled/checked
+     * state (ADR 0042).
+     */
+    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._renderMenu();
     }
 
@@ -145,15 +192,29 @@ export class GtkMenuButton extends HTMLElement {
         this._popoverEl.anchor = this._buttonEl;
         this._popoverEl.subscribe((open) => this._onPopoverToggled(open));
 
+        this._menuView = new PopoverMenuView(this._popoverEl, 'adw-menu-button', (path) => {
+            const item = menuItemAt(this._model, path);
+            if (item === null) return;
+            this._popoverEl.popdown();
+            this._buttonEl.focus();
+            this.dispatchEvent(
+                new CustomEvent('menu-item-activated', {
+                    bubbles: true,
+                    detail: { id: item.id ?? item.label, label: item.label, path: [...path] },
+                }),
+            );
+        });
+        this._menuView.setActions(this._actions);
+
         this._buttonEl.addEventListener('click', () => {
             if (this.hasAttribute('disabled')) return;
             // Nothing to show is not a menu — never open an empty popover.
-            if (!this._popoverEl.open && this._items.length === 0) return;
+            if (!this._popoverEl.open && this._model.length === 0) return;
             this._popoverEl.open = !this._popoverEl.open;
         });
 
-        // Seed items from the `menu` attribute if the property was not set.
-        if (this._items.length === 0) this._items = this._parseMenuAttr();
+        // Seed the menu from the attribute if the property was not set.
+        if (this._model.length === 0) this._model = this._parseMenuAttr();
         // The flat default is set only now the DOM exists, so the observed-attribute
         // callback (which renders) never runs before `_buttonEl` is created.
         if (!this.hasAttribute('flat') && !this.hasAttribute('circular')) this.setAttribute('flat', '');
@@ -162,8 +223,8 @@ export class GtkMenuButton extends HTMLElement {
 
     attributeChangedCallback(name: string) {
         if (!this._initialized || !this._buttonEl) return;
-        if (name === 'menu') {
-            this._items = this._parseMenuAttr();
+        if (name === 'menu-model') {
+            this._model = this._parseMenuAttr();
             this._renderMenu();
             return;
         }
@@ -171,21 +232,24 @@ export class GtkMenuButton extends HTMLElement {
     }
 
     /**
-     * The `menu` attribute, through the core parser the split button already used.
+     * The `menu-model` attribute, through the core parser both elements share.
      *
      * The copy this replaces was weaker in a way markup can reach: it kept `id` and
      * `icon` WHATEVER their runtime type, so `{"label":"Open","id":7}` produced an
      * entry whose `id` is a number in a field typed `string` — and `id` is what the
-     * activation event reports. The core parser keeps only string-typed extras.
+     * activation event reports. The core parser keeps only string-typed attributes.
      */
-    private _parseMenuAttr(): AdwMenuItem[] {
-        return parseMenuEntries(this.getAttribute('menu'));
+    private _parseMenuAttr(): AdwMenuModel {
+        return this._acceptMenu(parseMenuModel(this.getAttribute('menu-model')), false);
     }
 
     private _onPopoverToggled(open: boolean): void {
         this.classList.toggle('active', open);
         this._buttonEl.setAttribute('aria-expanded', String(open));
-        if (open) this._itemButtons[0]?.focus();
+        if (open) this._menuView.focusableRows[0]?.focus();
+        // A dismissal returns the popup to its top page: a menu that reopens inside a
+        // submenu is one the reader cannot get out of.
+        else this._menuView.reset();
     }
 
     private _render(): void {
@@ -207,50 +271,10 @@ export class GtkMenuButton extends HTMLElement {
     }
 
     private _renderMenu(): void {
-        this._popoverEl.replaceChildren();
-        this._itemButtons = [];
-
-        const title = this.getAttribute('menu-title') ?? this._menuTitle;
-        if (title) {
-            const titleEl = document.createElement('div');
-            titleEl.className = 'adw-popover-title adw-menu-button-title';
-            titleEl.textContent = title;
-            this._popoverEl.appendChild(titleEl);
-        }
-
-        for (const [index, entry] of this._items.entries()) {
-            const item = document.createElement('button');
-            item.type = 'button';
-            item.className = 'adw-popover-item adw-menu-button-item';
-            item.setAttribute('role', 'menuitem');
-            item.tabIndex = -1;
-
-            // An entry that asked for NO icon gets no icon node — the emptiness of the
-            // declared name, not whether it resolved. Testing `resolvedIconName` dropped
-            // the node for a name that was given and merely undrawable, which is the one
-            // case a reader needs to SEE; `<gtk-image>` draws `image-missing` there.
-            const entryIcon = createGtkImage(entry.icon ?? null, 'adw-menu-button-item-icon');
-            if (stringIsNotEmpty(entry.icon)) item.appendChild(entryIcon);
-            const labelEl = document.createElement('span');
-            labelEl.className = 'adw-menu-button-item-label';
-            labelEl.textContent = entry.label;
-            item.appendChild(labelEl);
-
-            item.addEventListener('click', () => {
-                this._popoverEl.popdown();
-                this._buttonEl.focus();
-                this.dispatchEvent(
-                    new CustomEvent('menu-item-activated', {
-                        bubbles: true,
-                        detail: { id: entry.id ?? entry.label, label: entry.label, index },
-                    }),
-                );
-            });
-            this._popoverEl.appendChild(item);
-            this._itemButtons.push(item);
-        }
-
-        if (this._items.length === 0) this._popoverEl.popdown();
+        this._menuView.setMenuModel(this._model);
+        this._menuView.setTitle(this.getAttribute('menu-title') ?? this._menuTitle);
+        this._menuView.render();
+        if (this._model.length === 0) this._popoverEl.popdown();
     }
 }
 

package/src/elements/gtk-popover.ts

@@ -139,9 +139,24 @@ export class GtkPopover extends HTMLElement {
         return ROLES.includes(value as GtkPopoverRole) ? (value as GtkPopoverRole) : 'menu';
     }
 
-    /** The navigable rows, in DOM order. Hidden rows are skipped — a filtered list navigates what it shows. */
+    /**
+     * The navigable rows, in DOM order.
+     *
+     * HIDDEN rows are skipped — a filtered list navigates what it shows. DISABLED rows
+     * are skipped for a harder reason: a disabled `<button>` cannot take focus at all, so
+     * `items[index].focus()` is a NO-OP and the arrow key reads as dead. Keeping one in
+     * the walk is the same defect a roving tabindex with no keys behind it has, one row
+     * wide — measured on a menu whose action group reported an action disabled
+     * (ADR 0042): ArrowDown onto it left `document.activeElement` where it was.
+     *
+     * GTK skips them for the same reason and says so in the general rule rather than in
+     * the menu: `gtk_widget_focus_move` walks only widgets `gtk_widget_get_can_focus`
+     * accepts, and an insensitive widget is not one.
+     */
     get items(): HTMLElement[] {
-        return [...this.querySelectorAll<HTMLElement>(ITEM_SELECTOR)].filter((item) => !item.hidden);
+        return [...this.querySelectorAll<HTMLElement>(ITEM_SELECTOR)].filter(
+            (item) => !item.hidden && !(item as HTMLButtonElement).disabled,
+        );
     }
 
     /** Show the popover — `gtk_popover_popup()`. */