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

package/src/index.ts

@@ -114,8 +114,9 @@ export * as Adw from './namespace/adw.js';
 export * as Gtk from './namespace/gtk.js';
 
 // The THIRD namespace, and the one that defines no element: the GObject types an author
-// CONSTRUCTS while building a tree. `Gio.Menu` is what makes `menuModel: menu` the same
-// program here as on GJS — `./namespace/gio.ts` says what does not go in it.
+// CONSTRUCTS while building a tree. `Gio.Menu` is a real `Gio.MenuModel` (ADR 0128), which
+// is what makes `menuModel: menu` the same program here as on GJS — `./namespace/gio.ts`
+// says what does not go in it.
 export * as Gio from './namespace/gio.js';
 
 // Gdk's clipboard (`Display`, `Clipboard`, `ContentProvider`): `./namespace/gdk.ts` says what is absent.
@@ -189,6 +190,12 @@ export type { AdwViewStackPageInfo } from './elements/adw-view-stack.js';
 // The portable menu model (ADR 0042) is `@gjsify/adwaita-core`'s, re-exported so a
 // consumer of THIS package reaches the menu types without a second dependency — one
 // definition, two doors, never two declarations.
+//
+// `buildMenu` is a VALUE and not only a type, because since ADR 0128 a `menuModel`
+// property takes a real `Gio.MenuModel` and an authored array is refused: without the
+// builder an app depending on this package alone could not write a menu in code at all.
+// The `menu-model` ATTRIBUTE still takes the JSON string, so markup needs none of this.
+export { buildMenu, menuTree, watchMenuModel } from '@gjsify/adwaita-core';
 export type {
     AdwMenuActions,
     AdwMenuEntryInput,
@@ -199,6 +206,7 @@ export type {
     AdwMenuPath,
     AdwMenuSection,
     AdwMenuSubmenu,
+    AdwMenuTree,
 } from '@gjsify/adwaita-core';
 export type { GtkDropDownOption } from './elements/gtk-drop-down.js';
 export type { AdwDialogPresentationMode } from './elements/adw-dialog.js';

package/src/keyboard-operable.spec.ts

@@ -19,6 +19,7 @@
 // A real Tab press escaping an untrapped dialog is measured one layer up, by
 // `tests/browser/specs/adwaita-keyboard.spec.ts`.
 import { describe, expect, it } from '@gjsify/unit';
+import { buildMenu } from '@gjsify/adwaita-core';
 
 import type { AdwAlertDialog } from './elements/adw-alert-dialog.js';
 import { AdwToggle, AdwToggleGroup } from './elements/adw-toggle-group.js';
@@ -737,11 +738,11 @@ export const AdwKeyboardOperableTest = async () => {
             };
             document.body.appendChild(el);
             el.actions = { 'app.export': { enabled: false }, 'app.new': {} };
-            el.menuModel = [
+            el.menuModel = buildMenu([
                 { label: 'New', action: 'app.new' },
                 { section: [{ label: 'Export', action: 'app.export' }, { label: 'Print' }] },
                 { label: 'More', submenu: [{ label: 'Rename' }, { label: 'Duplicate' }] },
-            ];
+            ]);
             (el.querySelector('.adw-menu-button-button') as HTMLElement).click();
             return {
                 el,
@@ -828,14 +829,14 @@ export const AdwKeyboardOperableTest = async () => {
             };
             document.body.appendChild(el);
             el.actions = { 'app.off': { enabled: false } };
-            el.menuModel = [
+            el.menuModel = buildMenu([
                 { label: 'Dim', action: 'app.off' },
                 { label: 'Live' },
                 {
                     label: 'More',
                     submenu: [{ label: 'SubDim', action: 'app.off' }, { label: 'SubLive' }],
                 },
-            ];
+            ]);
             (el.querySelector('.adw-menu-button-button') as HTMLElement).click();
             const rows = () => [...el.querySelectorAll<HTMLButtonElement>('.adw-popover-item')];
             const label = () =>
@@ -867,7 +868,7 @@ export const AdwKeyboardOperableTest = async () => {
             };
             document.body.appendChild(el);
             el.actions = { 'app.off': { enabled: false } };
-            el.menuModel = [{ label: 'More', submenu: [{ label: 'Only', action: 'app.off' }] }];
+            el.menuModel = buildMenu([{ label: 'More', submenu: [{ label: 'Only', action: 'app.off' }] }]);
             (el.querySelector('.adw-menu-button-button') as HTMLElement).click();
             const opener = el.querySelector('.adw-popover-item') as HTMLButtonElement;
             opener.focus();

package/src/menu-actions.spec.ts

@@ -7,6 +7,7 @@ import {
     registryMenuActionScene,
     type SharedTreeNode,
 } from '@gjsify/adwaita-core/conformance';
+import { menuTree } from '@gjsify/adwaita-core';
 import { describe, expect, it } from '@gjsify/unit';
 
 import { parentOfElement } from './application.js';
@@ -39,7 +40,11 @@ export const MenuActionsTest = async () => {
                     return;
                 }
                 const button = buildSharedTree(node) as unknown as GtkMenuButton;
-                expect(button.menuModel.map((entry) => entry.kind).join(',')).toBe(result.kinds.join(','));
+                expect(
+                    menuTree(button.menuModel!)
+                        .map((entry) => entry.kind)
+                        .join(','),
+                ).toBe(result.kinds.join(','));
             });
         }
     });

package/src/namespace/gio.ts

@@ -1,4 +1,4 @@
-// The GIO half of `@gjsify/adwaita-web`'s vocabulary — `Gio.Menu`, `Gio.MenuItem`.
+// The GIO half of `@gjsify/adwaita-web`'s vocabulary — `Gio.MenuModel` and its subclasses.
 // `export * as Gio from './namespace/gio.js'` in `src/index.ts` makes it the namespace,
 // the same module shape `./adw.ts` and `./gtk.ts` take and for the same reason (one list
 // carrying the value AND the type meaning — see the header of `./adw.ts`).
@@ -28,7 +28,24 @@ import { createAppInfo } from '@gjsify/adwaita-core';
 
 import { webPlatformHost } from '../platform-host.js';
 
-export { GioMenu as Menu, GioMenuItem as MenuItem } from '@gjsify/adwaita-core';
+// ADR 0128: `Gio.MenuModel` is an abstract CLASS, so the whole menu hierarchy is here and
+// `menu instanceof Gio.MenuModel` answers the same on both runtimes. The two iterators come
+// with it because `iterate_item_attributes` / `iterate_item_links` return them by name.
+export {
+    GioMenu as Menu,
+    GioMenuItem as MenuItem,
+    GioMenuModel as MenuModel,
+    GioMenuAttributeIter as MenuAttributeIter,
+    GioMenuLinkIter as MenuLinkIter,
+    MENU_ATTRIBUTE_ACTION,
+    MENU_ATTRIBUTE_ACTION_NAMESPACE,
+    MENU_ATTRIBUTE_ICON,
+    MENU_ATTRIBUTE_LABEL,
+    MENU_ATTRIBUTE_TARGET,
+    MENU_EXPORTER_MAX_SECTION_SIZE,
+    MENU_LINK_SECTION,
+    MENU_LINK_SUBMENU,
+} from '@gjsify/adwaita-core';
 // ADR 0122 § 2: the interface a `Gtk.StringList` implements and an `Implements: [Gio.ListModel]`
 // names. It is a token, not a class — the whole of the subset's interface support.
 export { ListModel } from '@gjsify/adwaita-core';

package/src/pango-markup.spec.ts

@@ -73,6 +73,17 @@ export const PangoMarkupTest = async () => {
             expect(target.querySelector('i > u')?.textContent).toBe('b');
         });
 
+        await it("sub and sup carry pango's 1 / 1.2 font_scale fallback", () => {
+            const { target } = render('<sub>d</sub><sup>e</sup>');
+            // Compared as a computed ratio: browsers serialise the `calc()` differently
+            // (Firefox gives `calc(0.833333em)`).
+            const base = Number.parseFloat(getComputedStyle(target).fontSize);
+            for (const el of target.children) {
+                const ratio = Number.parseFloat(getComputedStyle(el).fontSize) / base;
+                expect(Math.abs(ratio - 1 / 1.2)).toBeLessThan(0.01);
+            }
+        });
+
         await it("<markup> draws its children — it is pango's implicit root, not a box", async () => {
             const { target } = render('<markup><b>x</b></markup>');
             expect(target.querySelector('b')?.textContent).toBe('x');

package/src/pango-markup.ts

@@ -59,8 +59,11 @@ export const TAG_STYLES: Readonly<Record<string, { element: string; style?: Read
     tt: { element: 'span', style: { 'font-family': 'monospace' } },
     big: { element: 'span', style: { 'font-size': 'larger' } },
     small: { element: 'span', style: { 'font-size': 'smaller' } },
-    sub: { element: 'sub' },
-    sup: { element: 'sup' },
+    // pango's `font_scale` for `<sub>`/`<sup>` falls back to `1 / 1.2` when the font's OpenType
+    // metrics carry no script size (pango/itemize.c, `PANGO_FONT_SCALE_SUBSCRIPT`/`SUPERSCRIPT`);
+    // spelled out so it does not depend on each UA's `font-size: smaller` ratio.
+    sub: { element: 'sub', style: { 'font-size': 'calc(1em / 1.2)' } },
+    sup: { element: 'sup', style: { 'font-size': 'calc(1em / 1.2)' } },
     markup: { element: 'span', style: { display: 'contents' } },
     span: { element: 'span' },
 };

package/src/shared-tree-builder.ts

@@ -35,6 +35,7 @@
 // this small, most of which (the `SharedTreeNode` type) is erased at build anyway.
 
 import {
+    buildMenu,
     createBreakpointDriver,
     menuAssignments,
     parseBreakpointCondition,
@@ -512,8 +513,12 @@ function writeLook(el: HTMLElement, node: SharedTreeNode, menus?: SharedTreeNode
     for (const [prop, value] of Object.entries(node.props ?? {})) {
         if (prop !== 'menu-model') writeProp(el, prop, value);
     }
+    // `buildMenu`, because since ADR 0128 `menuModel` is a real `Gio.MenuModel` and a tree
+    // written at it is refused the way GJS refuses one. `menuAssignments` stays a tree walker
+    // — it resolves a `menu-model: id` against the file's `menus` — so the model is built
+    // here, at the one place the resolved tree becomes a widget's property.
     for (const [prop, model] of menuAssignments(node, menus)) {
-        (el as unknown as Record<string, unknown>)[propertyOf(prop)] = model;
+        (el as unknown as Record<string, unknown>)[propertyOf(prop)] = buildMenu(model);
     }
     // `styleClasses` is `GtkWidget:css-classes`, and this renderer's door for it is the
     // `class` attribute — what `.title-1`, `.dimmed` and `.card` select on. Unread, a

package/src/split-button.spec.ts

@@ -17,7 +17,7 @@ import {
     SPLIT_BUTTON_STYLE_CLASS_VECTORS,
     SPLIT_BUTTON_TOOLTIP_VECTORS,
 } from '@gjsify/adwaita-core/conformance';
-import { ADW_MENU_SURFACE_WEB, flattenMenu, menuRefusals } from '@gjsify/adwaita-core';
+import { ADW_MENU_SURFACE_WEB, buildMenu, flattenMenu, menuRefusals, menuTree } from '@gjsify/adwaita-core';
 import type { SplitButtonProperty } from '@gjsify/adwaita-core';
 import type { AdwSplitButton } from './elements/adw-split-button.js';
 import { fallbackMask, maskOf } from './icon-masks.spec.js';
@@ -238,24 +238,24 @@ export const AdwSplitButtonTest = async () => {
     });
 
     await describe('adw-split-button menu', async () => {
-        for (const { input, model, rule } of MENU_NORMALIZE_VECTORS) {
+        for (const { input, tree, rule } of MENU_NORMALIZE_VECTORS) {
             await it(`normalises an authored menu — ${rule}`, () => {
                 const { el, host } = mount({ label: 'Save' });
                 // What THIS surface refuses is core's answer, not a list restated here:
                 // a `custom` item names an application widget the browser cannot host,
                 // and the setter is where that is said out loud.
-                if (menuRefusals(model, ADW_MENU_SURFACE_WEB).length > 0) {
+                if (menuRefusals(tree, ADW_MENU_SURFACE_WEB).length > 0) {
                     expect(() => {
-                        el.menuModel = input;
+                        el.menuModel = buildMenu(input);
                     }).toThrow('adwaita-web');
                     host.remove();
                     return;
                 }
-                el.menuModel = input;
-                expect([...el.menuModel]).toStrictEqual([...model]);
+                el.menuModel = buildMenu(input);
+                expect(menuTree(el.menuModel!)).toStrictEqual([...tree]);
                 // Every node the model draws is a row: a section is inlined, a submenu
                 // is one row of its own.
-                expect(el.querySelectorAll('.adw-split-button-menu-item').length).toBe(flattenMenu(model).length);
+                expect(el.querySelectorAll('.adw-split-button-menu-item').length).toBe(flattenMenu(tree).length);
                 host.remove();
             });
         }
@@ -312,11 +312,28 @@ export const AdwSplitButtonTest = async () => {
             const { el, host } = mount({ 'menu-model': '[{"label":"Print"}]' });
             dropdownHalf(el).click();
             expect(el.active).toBe(true);
-            el.setAttribute('menu-model', '[]');
+            // REMOVING the attribute is how a menu is lost since ADR 0128 — `null` is the
+            // only spelling of "no menu", and the row below is the other half of that.
+            el.removeAttribute('menu-model');
             expect(el.active).toBe(false);
             expect(el.dropdownEnabled).toBe(false);
             host.remove();
         });
+
+        await it('an EMPTY menu is still a menu, so the dropdown stays live', () => {
+            // Measured on `Adw.SplitButton`: an empty non-null `Gio.Menu` at `menu-model`
+            // still builds a `GtkPopoverMenu` and `set_menu_model(null)` is what returns
+            // the popover to null (`MENU_MODEL_DOOR_VECTORS`). `[]` therefore edits the
+            // menu this element OWNS rather than taking it away, so the open popup follows
+            // the edit instead of being closed by it.
+            const { el, host } = mount({ 'menu-model': '[{"label":"Print"}]' });
+            dropdownHalf(el).click();
+            el.setAttribute('menu-model', '[]');
+            expect(el.dropdownEnabled).toBe(true);
+            expect(el.active).toBe(true);
+            expect(el.querySelectorAll('.adw-split-button-menu-item').length).toBe(0);
+            host.remove();
+        });
     });
 
     await describe('adw-split-button signals + state classes', async () => {

package/src/widget-element.ts

@@ -16,10 +16,25 @@
 // Reference: GTK gtk/gtkwidget.c (gtk_widget_set_visible, gtk_widget_set_tooltip_text)
 // Copyright (c) GNOME contributors (GTK). LGPLv2.1+.
 
+import { isWidgetNode } from '@gjsify/adwaita-core';
+
 import { WIDGET_VISIBLE_GETTERS, installElementApi, markLazyElementApi, notifyElement } from './gobject-elements.js';
 import { dispatchedSignalsOf, type DispatchedSignals } from './signals.js';
 import { isMapped } from './widget-mapping.js';
 
+/** Element links, walked until one lands on a widget: `isWidgetNode` says which those are. */
+type ElementLink =
+    | 'firstElementChild'
+    | 'lastElementChild'
+    | 'nextElementSibling'
+    | 'previousElementSibling'
+    | 'parentElement';
+
+function widgetChild(from: Element, first: ElementLink, next: ElementLink): Element | null {
+    for (let at = from[first]; at !== null; at = at[next]) if (isWidgetNode(at)) return at;
+    return null;
+}
+
 export class WidgetElement extends HTMLElement {
     /** `Gtk.Widget::map` / `::unmap`, which every subclass inherits (`dispatchedSignalsOf`). */
     static readonly signals: DispatchedSignals = { map: 'map', unmap: 'unmap' };
@@ -41,25 +56,31 @@ export class WidgetElement extends HTMLElement {
     set_visible(visible: boolean): void {
         this.visible = visible;
     }
-    /** `gtk_widget_get_first_child`: the first child element, `null` for a leaf. */
+    /**
+     * `gtk_widget_get_first_child`: the first child WIDGET, `null` for a leaf.
+     *
+     * The five walkers skip the elements a port builds for its own insides — `isWidgetNode`
+     * in `@gjsify/adwaita-core` carries the rule and the incident behind it, and the
+     * registered-class copy in `widgetTreeMembers()` answers from the same function.
+     */
     get_first_child(): Element | null {
-        return this.firstElementChild;
+        return widgetChild(this, 'firstElementChild', 'nextElementSibling');
     }
     /** `gtk_widget_get_last_child`. */
     get_last_child(): Element | null {
-        return this.lastElementChild;
+        return widgetChild(this, 'lastElementChild', 'previousElementSibling');
     }
     /** `gtk_widget_get_next_sibling`. */
     get_next_sibling(): Element | null {
-        return this.nextElementSibling;
+        return widgetChild(this, 'nextElementSibling', 'nextElementSibling');
     }
     /** `gtk_widget_get_prev_sibling`. */
     get_prev_sibling(): Element | null {
-        return this.previousElementSibling;
+        return widgetChild(this, 'previousElementSibling', 'previousElementSibling');
     }
-    /** `gtk_widget_get_parent`. */
+    /** `gtk_widget_get_parent`: the nearest ancestor that is a widget, not a port's own wrapper. */
     get_parent(): Element | null {
-        return this.parentElement;
+        return widgetChild(this, 'parentElement', 'parentElement');
     }
     /** `gtk_widget_get_width`: the layout box in CSS px; 0 until the widget is rendered. */
     get_width(): number {

package/src/widget-members.spec.ts

@@ -60,10 +60,10 @@ export const WidgetMembersTest = async () => {
             expect(() => widget.set_direction(7)).toThrow();
         });
 
-        await it('walks the element tree with the GTK link names', () => {
+        await it('walks the widget tree with the GTK link names', () => {
             const parent = make('WidgetMembersParent');
-            const a = document.createElement('div');
-            const b = document.createElement('div');
+            const a = new Gtk.Label() as unknown as WidgetLike;
+            const b = new Gtk.Label() as unknown as WidgetLike;
             parent.append(a, b);
             expect(parent.get_first_child()).toBe(a);
             expect(parent.get_last_child()).toBe(b);
@@ -73,6 +73,45 @@ export const WidgetMembersTest = async () => {
             expect(parent.get_parent()).toBe(null);
         });
 
+        await it("steps over the plain elements a port builds for a widget's insides", () => {
+            // `gtk_widget_get_first_child` hands back a GtkWidget, always. In a DOM port the
+            // same `children` list also holds what the port made for itself — the `<span>` a
+            // label's markup renderer writes, the `<div>` a row lays its slots out in — and a
+            // caller walking the tree would get one of those and find no `get_first_child` on
+            // it at all. The custom-element hyphen separates the two kinds (`isWidgetNode`).
+            const parent = make('WidgetMembersInsides');
+            const a = new Gtk.Label() as unknown as WidgetLike;
+            const b = new Gtk.Label() as unknown as WidgetLike;
+            parent.append(
+                document.createElement('span'),
+                a,
+                document.createElement('div'),
+                b,
+                document.createElement('span'),
+            );
+            expect(parent.get_first_child()).toBe(a);
+            expect(parent.get_last_child()).toBe(b);
+            expect(a.get_next_sibling()).toBe(b);
+            expect(b.get_prev_sibling()).toBe(a);
+            expect(b.get_next_sibling()).toBe(null);
+        });
+
+        await it('a widget holding only its own markup is a LEAF', () => {
+            const label = make('WidgetMembersLeaf');
+            label.append(document.createElement('span'), document.createElement('span'));
+            expect(label.get_first_child()).toBe(null);
+            expect(label.get_last_child()).toBe(null);
+        });
+
+        await it('get_parent reports the nearest ancestor that is a widget', () => {
+            const box = new Gtk.Box() as unknown as WidgetLike;
+            const wrapper = document.createElement('div');
+            const label = new Gtk.Label() as unknown as WidgetLike;
+            box.append(wrapper);
+            wrapper.append(label);
+            expect(label.get_parent()).toBe(box);
+        });
+
         await it('walks the element tree of a built-in widget with the GTK link names', () => {
             const box = new Gtk.Box() as unknown as WidgetLike;
             const a = new Gtk.Label() as unknown as WidgetLike;