@gjsify/adwaita-web 0.64.13-next.283 → 0.64.14

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

@@ -40,9 +40,9 @@
 //                      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.
+//   menuModel        — the real `Gio.MenuModel` (ADR 0128), or `null` (get/set; a `custom`
+//                      item throws here). A menu bar hands one of these over for a submenu
+//                      of its own; a JSON string is the authored spelling.
 //   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).
@@ -72,26 +72,22 @@
 // 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 { menuItemAt, menuNodeAt } from '@gjsify/adwaita-core';
 import { activateElementMenuItem, menuActionsOfElement } from '../application.js';
-import type { AdwMenuActions, AdwMenuInput, AdwMenuModel, AdwMenuPath } from '@gjsify/adwaita-core';
+import type { AdwMenuActions, AdwMenuModel, AdwMenuPath, AdwMenuTree } from '@gjsify/adwaita-core';
 
 import { GtkPopover } from './gtk-popover.js';
+import { MenuSlot } from './menu-slot.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 = [];
+    /** The model, its tree snapshot and its `items-changed` subscription (ADR 0128). */
+    private readonly _slot = new MenuSlot(() => {
+        if (this._menuInitialized) this._renderMenu();
+    });
     private _actions: AdwMenuActions | null = null;
     private _menuView!: PopoverMenuView;
     /** Named apart from `GtkPopover`'s own: two `private` fields of one name are two fields. */
@@ -101,26 +97,23 @@ export class GtkPopoverMenu extends GtkPopover {
         return [...GtkPopover.observedAttributes, 'menu-model', 'menu-title', 'visible-submenu'];
     }
 
-    /** The menu, normalised (ADR 0042). */
-    get menuModel(): AdwMenuModel {
-        return this._model;
+    /** The menu this popover draws, by identity, or `null` (ADR 0128). */
+    get menuModel(): AdwMenuModel | null {
+        return this._slot.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.
+     * Take a real model, a JSON string in the portable spelling, or `null`, 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 that path refuses the whole menu and
+     * says why on `console.error`; {@link MenuSlot} owns both doors.
      *
-     * `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.
+     * A REAL MODEL IS WHAT A MENU BAR HANDS OVER for one of its submenus, and the model
+     * it hands over is `buildMenu(node.items)` — a menu of its own rather than this
+     * element's authored one, so the two cannot overwrite each other.
      */
-    set menuModel(value: AdwMenuInput | AdwMenuModel) {
-        this._model = normalizeMenuModel(value as AdwMenuInput);
-        assertMenuRenderable(this._model, ADW_MENU_SURFACE_WEB);
+    set menuModel(value: AdwMenuModel | string | null) {
+        this._slot.write(value);
         if (this._menuInitialized) this._renderMenu();
     }
 
@@ -183,10 +176,10 @@ export class GtkPopoverMenu extends GtkPopover {
         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.
+        if (this._slot.model === null) this._slot.writeMarkup(this.getAttribute('menu-model'));
+        // The VIEW is what draws, and it holds the TREE it walks — seeding the slot
+        // without handing the view the same snapshot 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
@@ -194,7 +187,7 @@ export class GtkPopoverMenu extends GtkPopover {
         // a menu that reopens three levels deep is one the reader cannot get out of.
         this.subscribe((open) => {
             if (open) {
-                this._menuView.setActions(this._actions ?? menuActionsOfElement(this, this._model));
+                this._menuView.setActions(this._actions ?? menuActionsOfElement(this, this._slot.tree));
                 this._menuView.render();
                 this._menuView.focusableRows[0]?.focus();
             } else this._menuView.reset();
@@ -205,7 +198,7 @@ export class GtkPopoverMenu extends GtkPopover {
         super.attributeChangedCallback(name, previous, value);
         if (!this._menuInitialized) return;
         if (name === 'menu-model') {
-            this._model = this._parseMenuAttr();
+            this._slot.writeMarkup(this.getAttribute('menu-model'));
             this._renderMenu();
             return;
         }
@@ -258,7 +251,7 @@ export class GtkPopoverMenu extends GtkPopover {
         } else {
             const path = this._findSubmenu(name);
             if (path === null) return false;
-            this._menuView.setMenuModel(this._model);
+            this._menuView.setMenuTree(this._slot.tree);
             this._menuView.showPage(path);
         }
         this._menuView.render();
@@ -276,12 +269,12 @@ export class GtkPopoverMenu extends GtkPopover {
     private _openPageLabel(): string | null {
         const path = this._menuView.page;
         if (path.length === 0) return null;
-        const node = menuNodeAt(this._model, path);
+        const node = menuNodeAt(this._slot.tree, path);
         return node !== null && node.kind !== 'item' ? node.label : null;
     }
 
     private _findSubmenu(label: string): AdwMenuPath | null {
-        const walk = (nodes: AdwMenuModel, path: AdwMenuPath): AdwMenuPath | null => {
+        const walk = (nodes: AdwMenuTree, path: AdwMenuPath): AdwMenuPath | null => {
             for (const [index, node] of nodes.entries()) {
                 if (node.kind === 'item') continue;
                 const here = [...path, index];
@@ -291,7 +284,7 @@ export class GtkPopoverMenu extends GtkPopover {
             }
             return null;
         };
-        return walk(this._model, []);
+        return walk(this._slot.tree, []);
     }
 
     /**
@@ -313,7 +306,7 @@ export class GtkPopoverMenu extends GtkPopover {
      * open by choosing from it.
      */
     private _activate(path: AdwMenuPath): void {
-        const target = menuItemAt(this._model, path);
+        const target = menuItemAt(this._slot.tree, path);
         this.popdown();
         this.anchor?.focus();
         if (target === null) return;
@@ -327,22 +320,10 @@ export class GtkPopoverMenu extends GtkPopover {
     }
 
     private _renderMenu(): void {
-        this._menuView.setMenuModel(this._model);
+        this._menuView.setMenuTree(this._slot.tree);
         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 [];
+        if (this._slot.isEmpty) this.popdown();
     }
 }
 

package/src/elements/menu-slot.ts

@@ -0,0 +1,139 @@
+// The `menu-model` SLOT the menu-bearing elements of this package share.
+//
+// ADR 0128 made `menu-model` a real `Gio.MenuModel`, and that turned one assignment into
+// four steps that only work in one order:
+//
+//   1. read the write — `readMenuModelWrite` is the core's one door, and it is what tells a
+//      real model apart from the JSON string an attribute carries (ADR 0128 § 4);
+//   2. REFUSE what this surface cannot draw, before the element renders it;
+//   3. take a TREE SNAPSHOT, because every walker (`flattenMenu`, `menuNodeAt`,
+//      `menuItemAt`, `menuRefusals`) takes an `AdwMenuTree` and not a model — one snapshot
+//      per change rather than a chain of `get_item_link` calls per row;
+//   4. connect `items-changed` — on the root AND on every section and submenu it links,
+//      which is what `watchMenuModel` does, because a link's emission does NOT bubble.
+//
+// THE STEP THAT IS EASIEST TO GET WRONG IS THE LAST ONE: the watcher has to be RE-RUN after
+// every snapshot, since a mutation can add a section that was not there to connect to. Six
+// elements here need all four steps, so the arithmetic lives once and there is no sixth
+// place to forget it.
+//
+// THE TWO WRITES REFUSE DIFFERENTLY, and the difference is which side can hear it, exactly
+// as it was before the model became real. {@link MenuSlot.write} is a property assignment,
+// so it is a CALL and it THROWS; {@link MenuSlot.writeMarkup} is an attribute the browser
+// parsed, where a throw out of `connectedCallback` reaches nobody and is reported as an
+// uncaught page error (measured: it broke `adwaita-upgrade-order.spec.ts`, which counts
+// exactly those) — so markup refuses the MENU and says why on `console.error`.
+//
+// THE WATCHER'S LIFETIME IS THE ELEMENT'S, with no `release()` to call. GTK disconnects in
+// `dispose`, and a custom element has no dispose: it has `disconnectedCallback`, which also
+// fires when a node is MOVED, and an element re-inserted after dropping its watcher would
+// be deaf to the menu it still holds. A held model keeping its element alive is the same
+// shape GTK has, where the widget owns a reference to the model it reads.
+
+import {
+    ADW_MENU_SURFACE_WEB,
+    GjsifyMenu,
+    assertMenuRenderable,
+    menuRefusals,
+    menuTree,
+    readMenuModelWrite,
+    watchMenuModel,
+} from '@gjsify/adwaita-core';
+import type { AdwMenuTree, GioMenuModel } from '@gjsify/adwaita-core';
+
+export class MenuSlot {
+    /**
+     * The menu this element OWNS, so an edit to the same `menu-model="[…]"` attribute is a
+     * content change rather than a new menu — the popover already open follows it instead of
+     * being rebuilt (ADR 0128 § 5, the same rule `GjsifyOptionList` has for a list).
+     */
+    private readonly _authored = new GjsifyMenu();
+    private _model: GioMenuModel | null = null;
+    private _tree: AdwMenuTree = [];
+    private _unwatch: (() => void) | null = null;
+
+    /** @param onItemsChanged what to do when the HELD menu mutates under the element. */
+    constructor(private readonly onItemsChanged: () => void) {}
+
+    /** The model itself, by identity — what `menuModel` answers and what a child is handed. */
+    get model(): GioMenuModel | null {
+        return this._model;
+    }
+
+    /** The snapshot every walker reads. Re-taken on each `items-changed`, never aliased. */
+    get tree(): AdwMenuTree {
+        return this._tree;
+    }
+
+    /**
+     * Whether there is anything to show — NOT whether there is a menu.
+     *
+     * `null` and an empty `Gio.Menu` are different menus and GTK treats them differently: an
+     * empty non-null model still builds a `GtkPopoverMenu` and still dissociates an
+     * application-set popover (measured, `MENU_MODEL_DOOR_VECTORS`). This answers the
+     * question the ROWS ask — "is there a row to draw" — and the elements ask
+     * `model === null` where GTK asks about the model.
+     */
+    get isEmpty(): boolean {
+        return this._tree.length === 0;
+    }
+
+    /**
+     * A PROPERTY write: a real model by identity, a JSON string into the authored menu,
+     * `null` for no menu — and a `TypeError` for an array, which this door no longer takes
+     * (`buildMenu` is how an array becomes a model now).
+     *
+     * A REFUSAL PUTS THE AUTHORED MENU BACK, because the door has already reconciled it by
+     * the time the tree can be refused: without the restore a refused string would leave the
+     * element holding a menu it threw over, and the next render would draw it.
+     */
+    write(value: unknown): void {
+        const before = this._tree;
+        const next = readMenuModelWrite(value, this._authored);
+        try {
+            if (next !== null) assertMenuRenderable(menuTree(next), ADW_MENU_SURFACE_WEB);
+        } catch (error) {
+            if (next === this._authored) this._authored.reconcile(before);
+            throw error;
+        }
+        this._adopt(next);
+    }
+
+    /**
+     * The `menu-model` ATTRIBUTE, through the same door. A `null` attribute is no menu.
+     *
+     * A REFUSAL AND A TYPO ARE STILL DIFFERENT THINGS: `parseMenuModel` is total because
+     * malformed JSON is an author slip that must not stop the element upgrading, while a
+     * `custom` item is well-formed, deliberate, and unhonourable on this surface.
+     */
+    writeMarkup(value: string | null): void {
+        const next = readMenuModelWrite(value, this._authored);
+        const refusals = next === null ? [] : menuRefusals(menuTree(next), ADW_MENU_SURFACE_WEB);
+        if (refusals.length === 0) {
+            this._adopt(next);
+            return;
+        }
+        // `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}`);
+        this._adopt(null);
+    }
+
+    /** Hold `next`, snapshot it, and listen to it — the three that always happen together. */
+    private _adopt(next: GioMenuModel | null): void {
+        this._unwatch?.();
+        this._unwatch = null;
+        this._model = next;
+        this._tree = next === null ? [] : menuTree(next);
+        if (next === null) return;
+        // Re-adopting from inside the handler re-snapshots AND re-watches, which is what
+        // makes a section added by the mutation audible. The port's `emit` copies its
+        // handler list and skips ones disconnected mid-emission, so disconnecting here is
+        // safe (`gobject.ts`, `emit`).
+        this._unwatch = watchMenuModel(next, () => {
+            this._adopt(this._model);
+            this.onItemsChanged();
+        });
+    }
+}

package/src/elements/popover-menu.ts

@@ -47,7 +47,7 @@
 // Copyright (c) GNOME contributors (GTK, libadwaita). LGPLv2.1+.
 
 import { flattenMenu, menuLabelText, menuNodeAt, resolveMenuItemState } from '@gjsify/adwaita-core';
-import type { AdwMenuActions, AdwMenuItem, AdwMenuModel, AdwMenuPath } from '@gjsify/adwaita-core';
+import type { AdwMenuActions, AdwMenuItem, AdwMenuPath, AdwMenuTree } from '@gjsify/adwaita-core';
 
 import { createGtkImage } from './gtk-image.js';
 import type { GtkPopover } from './gtk-popover.js';
@@ -71,7 +71,7 @@ const BACK_LABEL = 'Back';
  * reopens three levels deep is a menu the reader cannot get out of.
  */
 export class PopoverMenuView {
-    private _model: AdwMenuModel = [];
+    private _tree: AdwMenuTree = [];
     private _actions: AdwMenuActions | null = null;
     private _title = '';
     /** The submenu whose items are showing; `[]` is the root page. */
@@ -80,7 +80,7 @@ export class PopoverMenuView {
     private _openers = new Set<HTMLElement>();
     /** The row that LEAVES a page — what ArrowLeft acts on. */
     private _backRow: HTMLElement | null = null;
-    /** The canonical text of the model showing, so an unchanged re-render keeps the page. */
+    /** The canonical text of the tree showing, so an unchanged re-render keeps the page. */
     private _key = '[]';
     private _rows: HTMLButtonElement[] = [];
 
@@ -181,24 +181,34 @@ export class PopoverMenuView {
     }
 
     /**
-     * Named for the value it takes, and NOT `setModel` — the portable LIST model gave
+     * Named for the value it takes, which since ADR 0128 is a TREE and not a model: this
+     * view never holds a `Gio.MenuModel`, it walks the snapshot its element took, and a
+     * `setMenuModel` here would name a type it has no way to read. The element is the one
+     * place that owns the model.
+     *
+     * It was `setMenuModel` for the reason the rename keeps: the portable LIST model gave
      * `ComboState` a `setModel` (ADR 0046), and two methods called `setModel` over two
      * unrelated values on one surface is the collision the vocabulary work exists to
-     * remove. It also un-blinds `check-adwaita-collection-reactivity`, which resolves a
-     * collection call by the setter's name.
+     * remove.
      */
-    setMenuModel(model: AdwMenuModel): void {
-        // A CHANGED model invalidates the open page: the submenu it named may not exist
+    setMenuTree(tree: AdwMenuTree): void {
+        // A CHANGED tree invalidates the open page: the submenu it named may not exist
         // any more, and rendering a page that is gone leaves an empty popover with a
         // back row and no way to see what happened. An UNCHANGED one must not — every
         // element re-render calls this, and resetting unconditionally shut the submenu
         // the reader had just opened.
-        const key = JSON.stringify(model);
+        //
+        // COMPARED BY VALUE, not by identity, which is the opposite of the guard
+        // `SplitButtonState.setMenuModel` has: the element's AUTHORED menu keeps its
+        // identity while its content is replaced (ADR 0128 § 5), so an identity guard
+        // here would never see an edit to a `menu-model="[…]"` attribute and would keep
+        // showing a page that is gone.
+        const key = JSON.stringify(tree);
         if (key !== this._key) {
             this._key = key;
             this._page = [];
         }
-        this._model = model;
+        this._tree = tree;
     }
 
     setActions(actions: AdwMenuActions | null): void {
@@ -215,10 +225,10 @@ export class PopoverMenuView {
     }
 
     /** The items of the page currently showing. */
-    private currentItems(): AdwMenuModel {
-        if (this._page.length === 0) return this._model;
-        const node = menuNodeAt(this._model, this._page);
-        return node !== null && node.kind !== 'item' ? node.items : this._model;
+    private currentItems(): AdwMenuTree {
+        if (this._page.length === 0) return this._tree;
+        const node = menuNodeAt(this._tree, this._page);
+        return node !== null && node.kind !== 'item' ? node.items : this._tree;
     }
 
     /** Rebuild the surface's children from the model. */
@@ -228,7 +238,7 @@ export class PopoverMenuView {
         this._openers = new Set();
         this._backRow = null;
 
-        const open = menuNodeAt(this._model, this._page);
+        const open = menuNodeAt(this._tree, this._page);
         if (this._page.length > 0 && open !== null && open.kind === 'submenu') {
             this.surface.appendChild(this.backRow(open.label));
         } else if (this._title.length > 0) {
@@ -263,7 +273,7 @@ export class PopoverMenuView {
     /** The label of the section at `path`, or `null` when it is not a labelled section. */
     private sectionHeading(path: AdwMenuPath): string | null {
         if (path.length <= this._page.length) return null;
-        const parent = menuNodeAt(this._model, path);
+        const parent = menuNodeAt(this._tree, path);
         return parent !== null && parent.kind === 'section' && parent.label !== undefined ? parent.label : null;
     }