@gjsify/adwaita-web 0.54.0 → 0.56.0

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

@@ -0,0 +1,339 @@
+// <gtk-popover-menu> — `GtkPopoverMenu`, a `GtkPopover` whose contents are a MENU MODEL
+// instead of a child widget, and which switches between the pages of a submenu stack
+// rather than nesting a second surface.
+//
+// It EXTENDS `<gtk-popover>` and nothing is re-implemented: the dismissal state machine,
+// the document-level grab, the arrow/Home/End arithmetic and the `popup`/`popdown`
+// vocabulary are the ones the menu button, the drop down and the split button already
+// share (ADR 0004). What is new here is only what `gtkpopovermenu.c` adds on top of
+// `GtkPopover`:
+//
+//   · the MODEL, read through the portable value ADR 0042 gave it — the same
+//     `menu-model` JSON `<gtk-menu-button>` takes, parsed by the same core function;
+//   · the PAGE STACK. `gtk_popover_menu_rebuild_contents` (gtkpopovermenu.c:707-717)
+//     empties a `GtkStack` and rebuilds it from the model, and
+//     `gtk_popover_menu_open_submenu` is `gtk_stack_set_visible_child_name` (:755-757).
+//     So the submenu a reader is inside is a NAMED PAGE of one surface, not a second
+//     popup beside it — which is why `visible-submenu` is a real property here and why a
+//     back row is drawn at the top of an open page;
+//   · the two ARIA facts GTK sets on the surface: `menu` for the popover and the
+//     `menuitem` / `menuitemcheckbox` / `menuitemradio` roles the rows carry
+//     (gtkpopovermenu.c:160-164).
+//
+// The ROWS are not new either: they are `PopoverMenuView`, the one implementation
+// `<gtk-menu-button>` and `<adw-split-button>` already share, including Left/Right
+// changing the page and the accelerator/check/submenu decoration. What this element adds
+// is where the activation goes, and that is `GtkPopoverMenu`'s own rule: activating an
+// item closes the popover and hands focus back to the anchor, so a menu cannot be left
+// open by choosing from it.
+//
+// `menu-title` is a PORT-ONLY attribute. `GMenuModel` has no title; GTK spells a heading
+// as a labelled SECTION, which `menu-model` already carries. The title exists because a
+// popover menu with a heading is the commonest shape an application writes by hand, and
+// both existing surfaces take it.
+//
+// Attributes (in addition to every `<gtk-popover>` one):
+//   menu-model       — the portable menu model as JSON (ADR 0042): items, sections and
+//                      submenus, with the attribute names GTK reads.
+//   menu-title       — optional heading above the menu.
+//   visible-submenu  — the name of the open page; `'main'` is the root, a submenu's label
+//                      is its name. `gtk_popover_menu_open_submenu(popover, "main")` is
+//                      the way back, so this is writeable and readable.
+// Properties:
+//   menuModel        — the model, normalised (get/set; a `custom` item throws here). Takes
+//                      an already-normalised `AdwMenuModel` too, which is what a menu bar
+//                      hands over for one of its submenus.
+//   actions          — what the action group publishes about the actions the model names
+//                      (ADR 0042), the source of every row's enabled/checked state.
+//   visibleSubmenu   — the open page's name (get/set).
+// Methods:
+//   openSubmenu(name) — `gtk_popover_menu_open_submenu`.
+//   closeSubmenus()   — `gtk_popover_menu_close_submenus`, one level (gtkpopovermenu.c:223-233).
+// Events:
+//   `notify::visible-submenu` (CustomEvent, bubbles, detail = { visibleSubmenu }) —
+//     mirrors the GObject notify; the page changed.
+//   `menu-item-activated` (CustomEvent, bubbles, detail = { id, label, path }) — the
+//     item at `path` was chosen. Same payload and the same `id` fallback as
+//     `<gtk-menu-button>`, so one listener serves both.
+//
+// KNOWN_GAPS — the one `GtkPopoverMenu` scalar property this element does not observe:
+//
+//   `flags`   GTK's `GTK_POPOVER_MENU_NESTED` opens a submenu as a NESTED POPOVER beside
+//             the row (`gtk_popover_menu_new_from_model_full`, gtkpopovermenu.c:817-825)
+//             and `GTK_POPOVER_MENU_SLIDING` — the DEFAULT — swaps the page of the one
+//             surface, which is what `PopoverMenuView` has always drawn. Only the sliding
+//             half is modelled: a nested popover would need the arrow this package does not
+//             draw and a second anchor the CSS placement cannot point at.
+//
+// Reference: refs/gtk/gtk/gtkpopovermenu.c (the page stack :707-757, the flags :638-648,
+//   the roles :160-164, `close_submenus` :223-233)
+// Reference: refs/gtk/gtk/gtkmodelbutton.c:1174-1210 (Left/Right change the page)
+// Reference: refs/libadwaita/src/stylesheet/widgets/_menus.scss (popover.menu, modelbutton)
+// Copyright (c) GNOME contributors (GTK, libadwaita). LGPLv2.1+
+// Modifications: Implemented as a Web Component for @gjsify/adwaita-web.
+
+import {
+    ADW_MENU_SURFACE_WEB,
+    assertMenuRenderable,
+    menuItemAt,
+    menuNodeAt,
+    menuRefusals,
+    normalizeMenuModel,
+    parseMenuModel,
+} from '@gjsify/adwaita-core';
+import type { AdwMenuActions, AdwMenuInput, AdwMenuModel, AdwMenuPath } from '@gjsify/adwaita-core';
+
+import { GtkPopover } from './gtk-popover.js';
+import { PopoverMenuView } from './popover-menu.js';
+
+/** The name the ROOT page carries — `gtk_popover_menu_open_submenu`'s own "main". */
+const MAIN_PAGE = 'main';
+
+export class GtkPopoverMenu extends GtkPopover {
+    private _model: AdwMenuModel = [];
+    private _actions: AdwMenuActions | null = null;
+    private _menuView!: PopoverMenuView;
+    /** Named apart from `GtkPopover`'s own: two `private` fields of one name are two fields. */
+    private _menuInitialized = false;
+
+    static get observedAttributes() {
+        return [...GtkPopover.observedAttributes, 'menu-model', 'menu-title', 'visible-submenu'];
+    }
+
+    /** The menu, normalised (ADR 0042). */
+    get menuModel(): AdwMenuModel {
+        return this._model;
+    }
+
+    /**
+     * Set the menu from anything the portable model accepts, refusing a `custom` item
+     * HERE — at the assignment, where it is a call the caller can catch. An ATTRIBUTE is
+     * markup the browser parses, so the attribute path refuses the whole menu instead and
+     * says why on `console.error`, exactly as `<gtk-menu-button>` does.
+     *
+     * `AdwMenuModel` is in the union because a menu bar hands over a submenu's own `items`
+     * untouched, and `normalizeMenuModel` is documented to be IDEMPOTENT over an
+     * already-normalised node — that is what lets a renderer hand a model it is holding
+     * straight back. The one cast is where the core's parameter type (`AdwMenuInput`, whose
+     * entries are the AUTHORED shapes) is narrower than the behaviour it documents.
+     */
+    set menuModel(value: AdwMenuInput | AdwMenuModel) {
+        this._model = normalizeMenuModel(value as AdwMenuInput);
+        assertMenuRenderable(this._model, ADW_MENU_SURFACE_WEB);
+        if (this._menuInitialized) this._renderMenu();
+    }
+
+    /** What the action group publishes about the actions this menu names (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._menuInitialized) this._renderMenu();
+    }
+
+    /** The optional heading. GTK spells one as a labelled SECTION; this is the shorthand. */
+    get menuTitle(): string {
+        return this.getAttribute('menu-title') ?? '';
+    }
+
+    set menuTitle(value: string) {
+        this.setAttribute('menu-title', value ?? '');
+    }
+
+    /**
+     * The name of the open page — `'main'` for the root, a submenu's label for a submenu.
+     *
+     * GTK's value is the stack child's NAME, which `GtkMenuTracker` gives a submenu page
+     * from the node it links; with no name given that is the submenu's label, so the label
+     * is what this element answers with. `gtk_popover_menu_open_submenu` (gtkpopovermenu.c
+     * :755-757) is the only way in, so setting it navigates rather than describing.
+     */
+    get visibleSubmenu(): string {
+        const open = this._openPageLabel();
+        return open === null ? MAIN_PAGE : open;
+    }
+
+    set visibleSubmenu(value: string) {
+        this.openSubmenu(value);
+    }
+
+    connectedCallback() {
+        super.connectedCallback();
+        if (this._menuInitialized) return;
+        this._menuInitialized = true;
+
+        // `gtk_popover_menu_new` creates the popover with `autohide = TRUE`
+        // (gtkpopovermenu.c:729-731), which is also the plain `<gtk-popover>` default.
+        this.classList.add('adw-popover-menu');
+        this.setAttribute('role', 'menu');
+        // `GtkPopoverMenu` "is one of the cases that add a `.menu` style class to the main
+        // `popover` node" (gtkpopovermenu.c:152-154), so the 6px menu inset and the
+        // `min-width: 120px` are not a choice here — they are what the node IS.
+        this.setAttribute('menu', '');
+
+        this._menuView = new PopoverMenuView(this, 'adw-popover-menu', (path) => this._activate(path));
+        this._menuView.setActions(this._actions);
+
+        if (this._model.length === 0) this._model = this._parseMenuAttr();
+        // The VIEW is what draws, and it holds the model it walks — seeding `_model`
+        // directly and rendering without handing the view the same value would leave it
+        // drawing an EMPTY page over a model the element believes it has.
+        this._renderMenu();
+
+        // The visible page RESETS when the popover closes, as `gtk_popover_menu_show` does
+        // with `gtk_popover_menu_set_open_submenu (widget, NULL)` (gtkpopovermenu.c:573-579):
+        // a menu that reopens three levels deep is one the reader cannot get out of.
+        this.subscribe((open) => {
+            if (open) this._menuView.focusableRows[0]?.focus();
+            else this._menuView.reset();
+        });
+    }
+
+    attributeChangedCallback(name?: string, previous?: string | null, value?: string | null) {
+        super.attributeChangedCallback(name, previous, value);
+        if (!this._menuInitialized) return;
+        if (name === 'menu-model') {
+            this._model = this._parseMenuAttr();
+            this._renderMenu();
+            return;
+        }
+        if (name === 'menu-title') {
+            this._menuView.setTitle(this.menuTitle);
+            this._menuView.render();
+            return;
+        }
+        if (name === 'visible-submenu') {
+            // The ATTRIBUTE is navigation, because the PROPERTY is: `visibleSubmenu` is a
+            // thin setter over `openSubmenu`, so a markup change and a code change reach the
+            // same page. `_reflectSubmenu` writes the attribute back only when it DIFFERS,
+            // which is what stops this from looping.
+            this._navigate(value ?? MAIN_PAGE);
+        }
+    }
+
+    /** `gtk_popover_menu_open_submenu` — switch to the named page. */
+    openSubmenu(name: string): void {
+        this._navigate(name);
+    }
+
+    /**
+     * The ONE way the open page changes, from the property and from the attribute alike.
+     *
+     * The notify belongs HERE rather than beside the attribute write: a page can change
+     * without the attribute's text changing (`openSubmenu('More')` when it is already
+     * `More` after a dismissal, or an attribute set to the page already showing), and
+     * `GObject` notifies on the state, not on the spelling.
+     */
+    private _navigate(name: string): void {
+        const before = this.visibleSubmenu;
+        if (!this._showPage(name)) return;
+        const after = this.visibleSubmenu;
+        this._reflectSubmenu();
+        if (after === before) return;
+        this.dispatchEvent(
+            new CustomEvent('notify::visible-submenu', { bubbles: true, detail: { visibleSubmenu: after } }),
+        );
+    }
+
+    /**
+     * Point the page stack at the named page and rebuild it. `false` when the name is not
+     * one of the stack's children, which is what `gtk_stack_set_visible_child_name` leaves
+     * alone — the current page keeps showing rather than the surface blanking.
+     */
+    private _showPage(name: string): boolean {
+        if (name === MAIN_PAGE || name.length === 0) {
+            this._menuView.reset();
+        } else {
+            const path = this._findSubmenu(name);
+            if (path === null) return false;
+            this._menuView.setMenuModel(this._model);
+            this._menuView.showPage(path);
+        }
+        this._menuView.render();
+        return true;
+    }
+
+    /**
+     * `gtk_popover_menu_close_submenus` — leave the open submenu, ONE level
+     * (gtkpopovermenu.c:223-233), which is what the back row does.
+     */
+    closeSubmenus(): void {
+        this.openSubmenu(MAIN_PAGE);
+    }
+
+    private _openPageLabel(): string | null {
+        const path = this._menuView.page;
+        if (path.length === 0) return null;
+        const node = menuNodeAt(this._model, path);
+        return node !== null && node.kind !== 'item' ? node.label : null;
+    }
+
+    private _findSubmenu(label: string): AdwMenuPath | null {
+        const walk = (nodes: AdwMenuModel, path: AdwMenuPath): AdwMenuPath | null => {
+            for (const [index, node] of nodes.entries()) {
+                if (node.kind === 'item') continue;
+                const here = [...path, index];
+                if (node.label === label) return here;
+                const found = walk(node.items, here);
+                if (found !== null) return found;
+            }
+            return null;
+        };
+        return walk(this._model, []);
+    }
+
+    /**
+     * Write the open page back to the attribute, ONCE, and only when the spelling differs.
+     *
+     * Reading the attribute instead of the state is the whole loop guard: navigating sets
+     * this, the attribute change calls back into `_navigate`, and a comparison against the
+     * current value stops the second turn.
+     */
+    private _reflectSubmenu(): void {
+        const name = this.visibleSubmenu;
+        if (this.getAttribute('visible-submenu') === name) return;
+        this.setAttribute('visible-submenu', name);
+    }
+
+    /**
+     * Activating an item closes the popover and returns focus to the anchor — the
+     * behaviour every menu-bearing surface here has, and the reason a menu cannot be left
+     * open by choosing from it.
+     */
+    private _activate(path: AdwMenuPath): void {
+        const target = menuItemAt(this._model, path);
+        this.popdown();
+        this.anchor?.focus();
+        if (target === null) return;
+        this.dispatchEvent(
+            new CustomEvent('menu-item-activated', {
+                bubbles: true,
+                detail: { id: target.id ?? target.label, label: target.label, path: [...path] },
+            }),
+        );
+    }
+
+    private _renderMenu(): void {
+        this._menuView.setMenuModel(this._model);
+        this._menuView.setTitle(this.menuTitle);
+        this._menuView.render();
+        if (this._model.length === 0) this.popdown();
+    }
+
+    private _parseMenuAttr(): AdwMenuModel {
+        const model = normalizeMenuModel(parseMenuModel(this.getAttribute('menu-model')));
+        const refusals = menuRefusals(model, ADW_MENU_SURFACE_WEB);
+        if (refusals.length === 0) return model;
+        // A throw from `connectedCallback` is reported as an uncaught PAGE error and
+        // reaches nobody, so markup refuses the menu and says why. See
+        // `<gtk-menu-button>`'s `_acceptMenu` for the same two doors.
+        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 [];
+    }
+}
+
+customElements.define('gtk-popover-menu', GtkPopoverMenu);

package/src/elements/gtk-popover.ts

@@ -17,13 +17,25 @@
 // Attributes:
 //   open      — boolean; reflects (and drives) the visible state.
 //   position  — bottom | top | start | end (default bottom) — which side of the anchor
-//               the surface sits on. Only the placement axis is modelled:
-//               `GtkPopover:position`'s autohide/has-arrow semantics belong to GTK,
-//               which libadwaita does not vendor, so they are not guessed at.
+//               the surface sits on. Only the placement AXIS is modelled: GTK's
+//               `GtkPopover:position` is a `GtkPositionType` whose four values pick a
+//               side and then, in GTK, negotiate with the surface for room
+//               (`present_popover`); here placement is CSS and nothing measures a rect.
+//   autohide  — boolean, default TRUE — GTK's grab. `gtk_popover_map` takes the grab
+//               only when it holds (gtkpopover.c:1245-1247) and `gtk_popover_show`
+//               focuses the first child only then (gtkpopover.c:1188-1192), so with it
+//               off an outside click and an Escape do not dismiss and focus stays where
+//               the caller left it. That is entry completion's own shape, which is the
+//               usecase the property documents (gtkpopover.c:1978-1988).
 //   align     — start | end (default start) — which edge it lines up with.
-//   role      — menu | listbox (default menu) — the ARIA role of the surface.
+//   role      — menu | listbox | dialog (default menu) — the ARIA role of the surface.
 //               An a11y fact ONLY; it does not pick the surface variant, see
-//               `menu` below.
+//               `menu` below. `menu` and `listbox` are the LIST roles: their
+//               `.adw-popover-item` rows are what the arrow keys walk. `dialog` is for a
+//               surface holding CONTENT — an info button's explanatory text — read as
+//               content instead of as a menu of commands; it takes an accessible name
+//               (`aria-label`) and must not claim `aria-modal`, which is
+//               `modal-surface.ts`'s alone.
 //   menu      — boolean; libadwaita's `.menu` STYLE CLASS on the popover node (0
 //               padding on the contents, `$menu_margin` on the item box), opt-in
 //               exactly as it is in GTK. DO NOT infer it from `role`: `GtkDropDown`'s
@@ -32,6 +44,7 @@
 //               the role pads the drop-down like a bare content popover.
 // Properties:
 //   open      — whether the popover is showing (get/set).
+//   autohide  — whether an outside click dismisses (get/set).
 //   anchor    — the element the surface is positioned against and returns focus
 //               to. Defaults to `parentElement` (get/set).
 //   items     — the navigable rows, in DOM order (get). Used for keyboard moves.
@@ -43,6 +56,25 @@
 //   `popover-item-activated` (CustomEvent, bubbles, detail = { index }) — a row
 //     was chosen by keyboard. Click activation stays the row's own listener.
 //
+// KNOWN_GAPS — the `GtkPopover` scalar properties this element does not observe:
+//
+//   `cascade-popdown`   GTK closes the ANCESTOR popovers when a child popover takes the
+//                       focus (`cascade_popdown`, gtkpopover.c:2455-2478), walking
+//                       `gtk_widget_get_parent` upward while each ancestor opts in. A
+//                       DOM popup has no focus owner to walk FROM — focus moves without
+//                       the element learning of it — so there is no event to hang this on.
+//   `has-arrow`         GTK draws the `arrow` node, and `popover > arrow` is a real rule
+//                       (_popovers.scss:44-56). Placement here is the `position`/`align`
+//                       pair alone, with nothing for an arrow to point at.
+//   `mnemonics-visible` GTK underlines the `_` mnemonic of a Pango label
+//                       (gtkpopover.c:2034-2041). The labels here are plain text with no
+//                       keyval, so there is nothing for the property to reveal.
+//
+// `child` and `default-widget` are widget-typed, and on this renderer they are SLOTS —
+// the exclusion `check-adwaita-element-properties.mjs` already applies to every
+// widget-valued property.
+//
+// Reference: refs/gtk/gtk/gtkpopover.c (autohide :1046, :1188, :1245; the property list)
 // Reference: refs/libadwaita/src/stylesheet/widgets/_popovers.scss (popover > contents)
 // Reference: refs/libadwaita/src/stylesheet/widgets/_menus.scss (popover.menu, modelbutton)
 // Copyright (c) GNOME contributors (libadwaita). LGPLv2.1+.
@@ -56,12 +88,21 @@ export type GtkPopoverPosition = 'bottom' | 'top' | 'start' | 'end';
 /** Which edge of the anchor the surface lines up with. */
 export type GtkPopoverAlign = 'start' | 'end';
 
-/** The ARIA role of the surface — it decides the row role consumers give their items. */
-export type GtkPopoverRole = 'menu' | 'listbox';
+/**
+ * The ARIA role of the surface — it decides the row role consumers give their items.
+ *
+ * `dialog` is the one role that is not a container of ROWS: it is for a surface holding
+ * content, so nothing derives an item role from it. Upstream splits the same way —
+ * `GtkPopoverMenu` declares itself a menu (`refs/gtk/gtk/gtkpopovermenu.c:676`), a bare
+ * `GtkPopover` declares nothing.
+ */
+export type GtkPopoverRole = 'menu' | 'listbox' | 'dialog';
 
 const POSITIONS: readonly GtkPopoverPosition[] = ['bottom', 'top', 'start', 'end'];
 const ALIGNS: readonly GtkPopoverAlign[] = ['start', 'end'];
-const ROLES: readonly GtkPopoverRole[] = ['menu', 'listbox'];
+/** The roles whose `.adw-popover-item` rows the LIST keys walk. */
+const LIST_ROLES: readonly GtkPopoverRole[] = ['menu', 'listbox'];
+const ROLES: readonly GtkPopoverRole[] = [...LIST_ROLES, 'dialog'];
 
 /** The row selector keyboard navigation walks. */
 const ITEM_SELECTOR = '.adw-popover-item';
@@ -74,6 +115,12 @@ export class GtkPopover extends HTMLElement {
     private _reflecting = false;
 
     private _onDocumentPointerDown = (event: Event): void => {
+        // GTK's grab is the whole mechanism: `gtk_popover_map` adds it only when
+        // `autohide` holds (gtkpopover.c:1245-1247), and without a grab nothing routes an
+        // outside click to the popover. So the property is honoured HERE rather than in the
+        // markup, and the listener is still bound either way — unbinding it would make the
+        // attribute change rebuild the document bindings for a boolean.
+        if (!this.autohide) return;
         const target = event.target as Node;
         if (this.contains(target)) return;
         // A click on the anchor is the anchor's own toggle — closing here too would close
@@ -84,6 +131,10 @@ export class GtkPopover extends HTMLElement {
 
     private _onDocumentKeyDown = (event: KeyboardEvent): void => {
         if (event.key !== 'Escape') return;
+        // Same grab, same gate: with `autohide` off the caret belongs to whatever is
+        // behind the surface, and an Escape that closed it would be a keypress with no
+        // handler at all.
+        if (!this.autohide) return;
         // Captured at the document, so a nested popover's Escape does not also close its
         // parent.
         event.stopPropagation();
@@ -92,7 +143,7 @@ export class GtkPopover extends HTMLElement {
     };
 
     static get observedAttributes() {
-        return ['open', 'position', 'align', 'role', 'menu'];
+        return ['open', 'position', 'align', 'role', 'menu', 'autohide'];
     }
 
     get open(): boolean {
@@ -104,6 +155,26 @@ export class GtkPopover extends HTMLElement {
         else this._state.popdown();
     }
 
+    /**
+     * Whether an outside click (or an Escape) dismisses the popover — GTK's grab.
+     *
+     * `autohide` defaults to TRUE in C (`priv->autohide = TRUE`, gtkpopover.c:1046) and
+     * that default is what every existing consumer in this package relies on, so it is
+     * the ABSENCE of the attribute rather than its presence, exactly as GTK spells it.
+     * Turning it off is entry completion's shape, which is the usecase the property
+     * documents: the entry keeps the caret and the list follows the typing.
+     */
+    get autohide(): boolean {
+        return this.getAttribute('autohide') !== 'false';
+    }
+
+    set autohide(value: boolean) {
+        // `autohide` is a DEFAULT-TRUE boolean, so its attribute form has to be able to
+        // say BOTH values: `<gtk-popover autohide="false">` is the only markup spelling
+        // of "no grab", and a bare `autohide` cannot be told apart from the default.
+        this.setAttribute('autohide', String(value));
+    }
+
     /**
      * The element the surface is positioned against and hands focus back to. Defaults to
      * `parentElement`: the popover is normally the last child of the widget that owns it.
@@ -134,6 +205,7 @@ export class GtkPopover extends HTMLElement {
         this.setAttribute('align', value);
     }
 
+    /** The ARIA role of the surface; an unknown value reads as the `menu` default. */
     get popoverRole(): GtkPopoverRole {
         const value = this.getAttribute('role');
         return ROLES.includes(value as GtkPopoverRole) ? (value as GtkPopoverRole) : 'menu';
@@ -206,7 +278,13 @@ export class GtkPopover extends HTMLElement {
         this._unbindDocument();
     }
 
-    attributeChangedCallback(name: string, _previous: string | null, value: string | null) {
+    /**
+     * Every parameter is optional, and that is FOR `<gtk-popover-menu>`, which subclasses
+     * this element: an override may not demand a parameter the base signature does not pass,
+     * and the platform always passes all three — the `?` is a typescript-visible fact about
+     * the CALLER, not about what arrives.
+     */
+    attributeChangedCallback(name?: string, _previous?: string | null, value?: string | null) {
         if (!this._initialized) return;
         if (name === 'open') {
             if (this._reflecting) return;
@@ -263,6 +341,10 @@ export class GtkPopover extends HTMLElement {
      */
     private _onKeyDown(event: KeyboardEvent): void {
         if (!this._state.open) return;
+        // The LIST keys belong to a `menu` / `listbox`. A `dialog` holds CONTENT, and a key
+        // there is the content's — the arrows scroll it, and taking them for a row walk
+        // would leave an explanatory popover on keys that move nothing.
+        if (!LIST_ROLES.includes(this.popoverRole)) return;
         const items = this.items;
         const active = document.activeElement as HTMLElement | null;
         const currentIndex = active === null ? -1 : items.indexOf(active);