@gjsify/adwaita-web 0.47.0 → 0.49.0

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

@@ -1,20 +1,29 @@
-// DOM-level tests for <gtk-menu-button>'s `menu` attribute.
+// DOM-level tests for <gtk-menu-button>'s `menu-model` attribute.
 //
 // The element parsed the JSON itself, and the copy was weaker than the core parser
 // the split button next to it already used: it kept `id` and `icon` whatever their
 // runtime type, so author markup could put a number in a field typed `string` — and
-// `id` is exactly what the activation event reports. These drive the core's parse
-// vectors against the real element.
+// `id` is exactly what the activation event reports. These drive the core's parse and
+// flatten vectors against the real element.
 
 import { describe, expect, it } from '@gjsify/unit';
-import { SPLIT_BUTTON_MENU_PARSE_VECTORS } from '@gjsify/adwaita-core/conformance';
+import { MENU_ITEM_STATE_VECTORS, MENU_PARSE_VECTORS, MENU_REFUSAL_VECTORS } from '@gjsify/adwaita-core/conformance';
+import { flattenMenu } from '@gjsify/adwaita-core';
+import type { AdwMenuInput } from '@gjsify/adwaita-core';
 
-/** Mount a menu button carrying `menu` as JSON, and return its rendered item labels. */
+interface MenuButtonElement extends HTMLElement {
+    menuModel: AdwMenuInput;
+    actions: Record<string, { enabled?: boolean; state?: string }> | null;
+}
+
+/** Mount a menu button carrying `menu-model` as JSON, and return its rendered row labels. */
 function mountWithMenu(json: string): { el: HTMLElement; labels: string[] } {
     const el = document.createElement('gtk-menu-button');
-    el.setAttribute('menu', json);
+    el.setAttribute('menu-model', json);
     document.body.appendChild(el);
-    const labels = Array.from(el.querySelectorAll('.adw-popover button')).map((b) => b.textContent?.trim() ?? '');
+    const labels = Array.from(el.querySelectorAll('.adw-popover-item')).map(
+        (b) => b.querySelector('.adw-menu-button-item-label')?.textContent ?? '',
+    );
     return { el, labels };
 }
 
@@ -24,24 +33,26 @@ function unmountAll(): void {
 
 export const GtkMenuButtonTest = async () => {
     await describe('<gtk-menu-button> menu attribute', async () => {
-        for (const { json, entries, rule } of SPLIT_BUTTON_MENU_PARSE_VECTORS) {
+        for (const { json, model, rule } of MENU_PARSE_VECTORS) {
             await it(`${rule}`, () => {
                 const { labels } = mountWithMenu(json ?? '');
-                expect(labels).toStrictEqual(entries.map((entry) => entry.label));
+                // The rendered rows are what `flattenMenu` says: a section is inlined,
+                // a submenu is ONE row, and both keep their own label.
+                expect(labels).toStrictEqual(flattenMenu(model).map((row) => row.node.label));
                 unmountAll();
             });
         }
 
         await it('drops a non-string id instead of leaking a number into the event', () => {
             const el = document.createElement('gtk-menu-button');
-            el.setAttribute('menu', '[{"label":"Open","id":7}]');
+            el.setAttribute('menu-model', '[{"label":"Open","id":7}]');
             document.body.appendChild(el);
 
             let seen: unknown = 'not fired';
             el.addEventListener('menu-item-activated', (e) => {
                 seen = (e as CustomEvent<{ id: string }>).detail.id;
             });
-            (el.querySelector('.adw-popover button') as HTMLElement | null)?.click();
+            (el.querySelector('.adw-popover-item') as HTMLElement | null)?.click();
 
             // `id` fell back to the label, which is the documented default — rather
             // than arriving as the number 7 in a field every consumer reads as text.
@@ -49,4 +60,147 @@ export const GtkMenuButtonTest = async () => {
             unmountAll();
         });
     });
+
+    await describe('<gtk-menu-button> keeps its menu replaceable while live', async () => {
+        // The property `check-adwaita-collection-reactivity.mjs` exists to protect, and
+        // the one it cannot see here: this widget keeps its model in its own field rather
+        // than in a core state class, and parses its attribute through a MODULE function,
+        // so every rule in that reader is silent on it. A spec stands where the reader
+        // cannot.
+        await it('a menuModel assigned AFTER connect reaches the rows', () => {
+            const el = document.createElement('gtk-menu-button') as MenuButtonElement;
+            document.body.appendChild(el);
+            expect(el.querySelectorAll('.adw-popover-item').length).toBe(0);
+            el.menuModel = ['New', 'Open'];
+            expect([...el.querySelectorAll('.adw-menu-button-item-label')].map((n) => n.textContent)).toStrictEqual([
+                'New',
+                'Open',
+            ]);
+            // REPLACED, not merely seeded — the failure mode is a second assignment
+            // writing an expando while the first happened to work at connect.
+            el.menuModel = [{ label: 'Only', action: 'app.only' }];
+            expect([...el.querySelectorAll('.adw-menu-button-item-label')].map((n) => n.textContent)).toStrictEqual([
+                'Only',
+            ]);
+            unmountAll();
+        });
+
+        await it('a menu-model ATTRIBUTE set after connect reaches them too', () => {
+            const el = document.createElement('gtk-menu-button') as MenuButtonElement;
+            document.body.appendChild(el);
+            el.setAttribute('menu-model', '[{"label":"Later"}]');
+            expect([...el.querySelectorAll('.adw-menu-button-item-label')].map((n) => n.textContent)).toStrictEqual([
+                'Later',
+            ]);
+            unmountAll();
+        });
+    });
+
+    await describe('<gtk-menu-button> renders the whole model (ADR 0042)', async () => {
+        await it('draws a section heading, a separator and a submenu page', () => {
+            const el = document.createElement('gtk-menu-button') as MenuButtonElement;
+            document.body.appendChild(el);
+            el.menuModel = [
+                { label: 'New' },
+                { section: [{ label: 'Cut' }, { label: 'Copy' }], label: 'Edit' },
+                { label: 'More', submenu: [{ label: 'Rename' }, { label: 'Duplicate' }] },
+            ];
+
+            // TWO: a section is separated from what comes before it AND from what comes
+            // after, which is what `GtkPopoverMenu` draws for the same model.
+            expect(el.querySelectorAll('.adw-popover-separator').length).toBe(2);
+            expect(el.querySelector('.adw-popover-section-title')?.textContent).toBe('Edit');
+            const rows = [...el.querySelectorAll('.adw-popover-item')] as HTMLButtonElement[];
+            expect(rows.length).toBe(4);
+            // The submenu is a row that OPENS, not a row that acts.
+            expect(rows[3].getAttribute('aria-haspopup')).toBe('menu');
+
+            rows[3].click();
+            const page = [...el.querySelectorAll('.adw-popover-item')] as HTMLButtonElement[];
+            // A back row plus the submenu's two items — the submenu's contents were
+            // never inlined into the parent page.
+            expect(page.length).toBe(3);
+            expect(page[0].classList.contains('adw-popover-back')).toBe(true);
+            expect(page.map((r) => r.querySelector('.adw-menu-button-item-label')?.textContent)).toStrictEqual([
+                'More',
+                'Rename',
+                'Duplicate',
+            ]);
+
+            page[0].click();
+            expect(el.querySelectorAll('.adw-popover-item').length).toBe(4);
+            unmountAll();
+        });
+
+        for (const { item, actions, state, rule } of MENU_ITEM_STATE_VECTORS) {
+            await it(`action state reaches the DOM — ${rule}`, () => {
+                const el = document.createElement('gtk-menu-button') as MenuButtonElement;
+                document.body.appendChild(el);
+                el.actions = { ...actions };
+                el.menuModel = [item];
+                const row = el.querySelector('.adw-popover-item') as HTMLButtonElement;
+                expect(row.hidden).toBe(!state.visible);
+                expect(row.disabled).toBe(!state.sensitive);
+                const expectedRole =
+                    state.role === 'normal'
+                        ? 'menuitem'
+                        : state.role === 'check'
+                          ? 'menuitemcheckbox'
+                          : 'menuitemradio';
+                expect(row.getAttribute('role')).toBe(expectedRole);
+                expect(row.getAttribute('aria-checked')).toBe(state.role === 'normal' ? null : String(state.toggled));
+                unmountAll();
+            });
+        }
+
+        await it('the ATTRIBUTE path refuses too — markup is where a blank row actually ships', () => {
+            // The first cut asserted only the property setter, so a `custom` item written
+            // in markup drew exactly the row the refusal exists to prevent.
+            //
+            // It does NOT throw, and that is measured rather than chosen: a throw from
+            // `connectedCallback` is not delivered to whoever appended the element, it is
+            // reported as an uncaught PAGE error — it broke `adwaita-upgrade-order`,
+            // which counts those. So the menu is refused whole (a menu-less dropdown is
+            // insensitive, which is visible) and the reason goes to `console.error`.
+            const errors: unknown[] = [];
+            const real = console.error;
+            console.error = (...args: unknown[]) => errors.push(args.join(' '));
+            try {
+                const el = document.createElement('gtk-menu-button');
+                el.setAttribute('menu-model', '[{"label":"Zoom","custom":"zoom-control"},{"label":"Quit"}]');
+                document.body.appendChild(el);
+                expect(el.querySelectorAll('.adw-popover-item').length).toBe(0);
+                expect(errors.join('\n')).toContain('zoom-control');
+            } finally {
+                console.error = real;
+            }
+            unmountAll();
+        });
+
+        await it('a malformed attribute is NOT a refusal — a typo may not stop the upgrade', () => {
+            // The other half of the same rule: `parseMenuModel` stays total, so this
+            // element upgrades with no menu instead of throwing.
+            const { labels } = mountWithMenu('not json at all');
+            expect(labels).toStrictEqual([]);
+            unmountAll();
+        });
+
+        for (const { model, paths, rule } of MENU_REFUSAL_VECTORS) {
+            await it(`refusal — ${rule}`, () => {
+                const el = document.createElement('gtk-menu-button') as MenuButtonElement;
+                document.body.appendChild(el);
+                if (paths.length === 0) {
+                    el.menuModel = model;
+                    expect(el.querySelectorAll('.adw-popover-item').length).toBe(flattenMenu(model).length);
+                } else {
+                    // LOUD, at the assignment: a `custom` item names an application
+                    // widget, and a surface that ignored it would draw a blank row.
+                    expect(() => {
+                        el.menuModel = model;
+                    }).toThrow('adwaita-web');
+                }
+                unmountAll();
+            });
+        }
+    });
 };

package/src/index.ts

@@ -134,6 +134,19 @@ export { AdwAlertResponse } from './elements/adw-alert-dialog.js';
 // return. Not widgets, so clause 2 has nothing to say about them.
 export type { GtkPopoverAlign, GtkPopoverPosition, GtkPopoverRole } from './elements/gtk-popover.js';
 export type { AdwViewStackPageInfo } from './elements/adw-view-stack.js';
-export type { AdwMenuItem } from './elements/gtk-menu-button.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.
+export type {
+    AdwMenuActions,
+    AdwMenuEntryInput,
+    AdwMenuInput,
+    AdwMenuItem,
+    AdwMenuModel,
+    AdwMenuNode,
+    AdwMenuPath,
+    AdwMenuSection,
+    AdwMenuSubmenu,
+} 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

@@ -685,6 +685,175 @@ export const AdwKeyboardOperableTest = async () => {
         });
     });
 
+    await describe('a portable menu is traversable, page by page (ADR 0042)', async () => {
+        // The roving tabindex on a menu row moved into `PopoverMenuView` when the two
+        // menu buttons started sharing one popup, and it took its keyboard obligation
+        // with it. `check-adwaita-keyboard-contract.mjs` holds that a listener EXISTS;
+        // this holds that the keys move focus — the half a static reader cannot have.
+        const open = (): { el: HTMLElement; rows: () => HTMLButtonElement[] } => {
+            const el = document.createElement('gtk-menu-button') as HTMLElement & {
+                menuModel: unknown;
+                actions: unknown;
+            };
+            document.body.appendChild(el);
+            el.actions = { 'app.export': { enabled: false }, 'app.new': {} };
+            el.menuModel = [
+                { 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,
+                rows: () => [...el.querySelectorAll<HTMLButtonElement>('.adw-popover-item')],
+            };
+        };
+        const labelOf = (el: Element | null) =>
+            el?.querySelector('.adw-menu-button-item-label')?.textContent ?? el?.localName ?? 'none';
+
+        await it('the arrow keys walk the rows and wrap, and Home/End jump', () => {
+            const { el, rows } = open();
+            const items = rows();
+            // Four ROWS, but only three are navigable: `app.export` is disabled by the
+            // action group, and a disabled button cannot take focus.
+            expect(items.length).toBe(4);
+            expect(items[1].disabled).toBe(true);
+
+            items[0].focus();
+            press(items[0], 'ArrowDown');
+            // Straight past the disabled row — an arrow that lands on it is a dead press.
+            expect(labelOf(document.activeElement)).toBe('Print');
+            press(document.activeElement as HTMLElement, 'ArrowDown');
+            expect(labelOf(document.activeElement)).toBe('More');
+            // A menu popover WRAPS, unlike the tab lists: `resolvePopoverKey` is modular.
+            press(document.activeElement as HTMLElement, 'ArrowDown');
+            expect(labelOf(document.activeElement)).toBe('New');
+
+            press(document.activeElement as HTMLElement, 'End');
+            expect(labelOf(document.activeElement)).toBe('More');
+            press(document.activeElement as HTMLElement, 'Home');
+            expect(labelOf(document.activeElement)).toBe('New');
+            el.remove();
+        });
+
+        await it('neither a section heading nor a separator is a row', () => {
+            const { el } = open();
+            // Both are `<div>`s without `.adw-popover-item`, so the walk cannot land on
+            // them — asserted rather than assumed, because the class is what decides it.
+            expect(el.querySelectorAll('.adw-popover-separator').length).toBe(2);
+            for (const node of el.querySelectorAll('.adw-popover-separator, .adw-popover-title')) {
+                expect(node.classList.contains('adw-popover-item')).toBe(false);
+            }
+            el.remove();
+        });
+
+        await it('ArrowRight opens a submenu and ArrowLeft leaves it — the row answers, not the surface', () => {
+            const { el, rows } = open();
+            const opener = rows()[3];
+            expect(labelOf(opener)).toBe('More');
+
+            opener.focus();
+            // `gtk_model_button_focus`: GTK_DIR_RIGHT on a row with a `menu-name`
+            // (gtkmodelbutton.c:1189-1195).
+            const right = press(opener, 'ArrowRight');
+            expect(right.defaultPrevented).toBe(true);
+            expect(rows().map(labelOf)).toStrictEqual(['More', 'Rename', 'Duplicate']);
+            // Focus lands on the first ITEM of the page, past the back row.
+            expect(labelOf(document.activeElement)).toBe('Rename');
+
+            // GTK_DIR_LEFT answers only on the TITLE row (:1182-1188), so from the
+            // middle of the page it does nothing — deliberately the same here.
+            const inert = press(document.activeElement as HTMLElement, 'ArrowLeft');
+            expect(inert.defaultPrevented).toBe(false);
+            expect(labelOf(document.activeElement)).toBe('Rename');
+
+            const back = rows()[0];
+            back.focus();
+            const left = press(back, 'ArrowLeft');
+            expect(left.defaultPrevented).toBe(true);
+            expect(rows().map(labelOf)).toStrictEqual(['New', 'Export', 'Print', 'More']);
+            el.remove();
+        });
+
+        await it('a page change never strands focus outside the popup, whatever is disabled', () => {
+            // K1. Both page changes focused a HARD-CODED index of `_rows`, which includes
+            // rows no key can reach — so entering a submenu whose first item is disabled
+            // put `document.activeElement` on <body>, OUTSIDE an open popover: Tab then
+            // walked to the control behind it and every arrow was dead, because both
+            // keydown listeners are element-scoped. The two ELEMENTS already filtered on
+            // their open path; the two page changes did not, which is two of four.
+            const el = document.createElement('gtk-menu-button') as HTMLElement & {
+                menuModel: unknown;
+                actions: unknown;
+            };
+            document.body.appendChild(el);
+            el.actions = { 'app.off': { enabled: false } };
+            el.menuModel = [
+                { 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 = () =>
+                document.activeElement?.querySelector('.adw-menu-button-item-label')?.textContent ??
+                document.activeElement?.localName ??
+                'none';
+            const inside = () => el.contains(document.activeElement);
+
+            // ENTERING: past the back row, counted in REACHABLE rows — not index 1.
+            const opener = rows()[2] as HTMLButtonElement;
+            opener.focus();
+            press(opener, 'ArrowRight');
+            expect(inside()).toBe(true);
+            expect(label()).toBe('SubLive');
+
+            // LEAVING: the parent's first row is disabled too, so index 0 would strand.
+            const back = rows()[0] as HTMLButtonElement;
+            back.focus();
+            press(back, 'ArrowLeft');
+            expect(inside()).toBe(true);
+            expect(label()).toBe('Live');
+            el.remove();
+        });
+
+        await it('a submenu with NOTHING reachable focuses its back row, not the page', () => {
+            const el = document.createElement('gtk-menu-button') as HTMLElement & {
+                menuModel: unknown;
+                actions: unknown;
+            };
+            document.body.appendChild(el);
+            el.actions = { 'app.off': { enabled: false } };
+            el.menuModel = [{ 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();
+            press(opener, 'ArrowRight');
+            // The back row is always reachable, so the reader can still leave.
+            expect(el.contains(document.activeElement)).toBe(true);
+            expect(document.activeElement?.classList.contains('adw-popover-back')).toBe(true);
+            el.remove();
+        });
+
+        await it('Enter activates the focused row, and reports its path', () => {
+            const { el, rows } = open();
+            const seen: number[][] = [];
+            el.addEventListener('menu-item-activated', (event) => {
+                seen.push((event as CustomEvent<{ path: number[] }>).detail.path);
+            });
+            const print = rows()[2];
+            print.focus();
+            press(print, 'Enter');
+            // Inside a section, so only a PATH names it — the flat index would be 2 here
+            // and 1 in the model.
+            expect(seen).toStrictEqual([[1, 1]]);
+            el.remove();
+        });
+    });
+
     await describe('the row family is a tab stop where libadwaita makes one', async () => {
         const mount = (markup: string) => {
             const host = document.createElement('div');
@@ -728,7 +897,7 @@ export const AdwKeyboardOperableTest = async () => {
         await it('activates on Enter and Space, and lets a child keep its own keys', () => {
             const host = mount(
                 '<adw-action-row id="k-keys" title="Keys" activatable></adw-action-row>' +
-                    '<adw-combo-row id="k-combo" title="Combo" items=\'["a","b"]\'></adw-combo-row>',
+                    '<adw-combo-row id="k-combo" title="Combo" model=\'["a","b"]\'></adw-combo-row>',
             );
             const row = document.getElementById('k-keys') as HTMLElement;
             let activated = 0;

package/src/shared-trees.spec.ts

@@ -0,0 +1,151 @@
+// ONE AUTHORED TREE, BUILT BY THIS RENDERER — ADR 0051, and the renderer ADR 0027 § 9
+// names by name: "the same authored tree, rendered through this host and through
+// `adwaita-web`, satisfies the same `@gjsify/adwaita-core/conformance` vectors with no
+// per-surface markup branch".
+//
+// The sibling driver is `packages/framework/gtk-host/src/shared-trees.spec.ts`. One corpus
+// — `scripts/adwaita-gallery-shared-trees.mjs`, read here and not transcribed — one set of
+// expectations, a driver per renderer: ADR 0030's shape one level up, so a green-here /
+// red-there diff is attributable to the RENDERER and not to two suites disagreeing about
+// what they test.
+//
+// TWO DECLARED TRANSFORMS ON THE WAY IN, and no third. `hostTagOf` turns the authored GIR
+// class name into the element name, which is the same case rule `gtk-host` stamps its tags
+// with; and an authored property name becomes its kebab-case ATTRIBUTE, because this
+// renderer's door is markup. Both are total functions over the corpus with no tag list and
+// no per-block case — a `switch` on a widget name here would be the per-surface branch
+// § 9 forbids, and the reason the corpus admits a block only when it needs no alias.
+//
+// The readers below go through the REAL DOM the element rendered, never a state object of
+// its own: an element asserting against its own bookkeeping agrees with itself while the
+// page is wrong.
+//
+// What is NOT here is everything that is not about this renderer — which tables the corpus
+// reaches, which block is declared to reach none, whether an expectation's address exists.
+// Those are facts about the CORPUS and are asserted once, in `adwaita-core`'s own suite,
+// which runs on Node as well as in a browser.
+
+import { describe, expect, it } from '@gjsify/unit';
+
+import {
+    authoredTags,
+    sharedTreeExpectations,
+    subjectIndexOf,
+    type SharedTreeExpectation,
+    type SharedTreeNode,
+} from '@gjsify/adwaita-core/conformance';
+
+// `attributeOf` — `buttonLabel` -> `button-label` — comes from the corpus rather than
+// being spelled again here, because arm 13 of `check-generated-website-data.mjs` reads
+// gallery fences back through the SAME rule: two copies would let this driver and that
+// check agree with each other while the fence a reader copies means something else.
+import {
+    ADWAITA_GALLERY_SHARED_TREES,
+    attributeOf,
+    hostTagOf,
+} from '../../../../scripts/adwaita-gallery-shared-trees.mjs';
+
+import '@gjsify/adwaita-web';
+
+/**
+ * The whole renderer-specific half of this driver: an element, its authored properties as
+ * attributes, its children, in that order.
+ *
+ * A boolean is the ATTRIBUTE'S PRESENCE, which is what every element here reads
+ * (`hasAttribute('revealed')`, `hasAttribute('expanded')`) — spelling `"true"` would set a
+ * present attribute for `false` as well.
+ */
+function build(node: SharedTreeNode): HTMLElement {
+    const el = document.createElement(hostTagOf(node.tag));
+    for (const [prop, value] of Object.entries(node.props ?? {})) {
+        if (typeof value === 'boolean') el.toggleAttribute(attributeOf(prop), value);
+        else el.setAttribute(attributeOf(prop), String(value));
+    }
+    for (const child of node.children ?? []) el.append(build(child));
+    return el;
+}
+
+/**
+ * Connect the authored root — these elements build on connect — run, and take it down again.
+ *
+ * The teardown is in a `finally` because a RED test must not leave a mounted tree behind:
+ * the next test would then be reading a document two blocks deep, and the failure it
+ * reported would name the wrong renderer.
+ */
+function mounted<T>(node: SharedTreeNode, use: (root: Element) => T): T {
+    const host = document.createElement('div');
+    host.append(build(node));
+    document.body.append(host);
+    try {
+        return use(host.firstElementChild!);
+    } finally {
+        host.remove();
+    }
+}
+
+const bannerButton = (banner: Element) => banner.querySelector<HTMLButtonElement>('.adw-banner-button');
+
+/**
+ * Read one observable off the element this renderer built.
+ *
+ * The ONE seam between the shared expectations and this renderer, and the mirror of
+ * `read()` in the gtk-host driver. Everything above it is renderer-free.
+ */
+function read(expectation: SharedTreeExpectation, el: Element): string | number | boolean {
+    switch (expectation.observable) {
+        case 'entry-text-length':
+            return (el as unknown as { textLength: number }).textLength;
+        case 'switch-row-active':
+            return (el as unknown as { active: boolean }).active;
+        case 'banner-button-visible': {
+            const button = bannerButton(el);
+            return button ? !button.hidden : false;
+        }
+        case 'banner-button-text':
+            return bannerButton(el)?.textContent ?? '';
+    }
+}
+
+/**
+ * The realised tree, depth-first in document order and filtered to the authored element
+ * names: the parts an element renders for itself (a listbox, a revealer, a title span) are
+ * not the renderer's promise; the ORDER and the NESTING of what was authored is.
+ */
+function realised(root: Element, wanted: readonly string[]): Element[] {
+    const set = new Set(wanted);
+    return [root, ...root.querySelectorAll('*')].filter((el) => set.has(el.tagName.toLowerCase()));
+}
+
+export const AdwSharedTreesTest = async () => {
+    await describe('the shared corpus builds through adwaita-web', async () => {
+        for (const block of ADWAITA_GALLERY_SHARED_TREES) {
+            await it(`${block.widget} builds, and the REAL DOM carries the authored nodes in order`, () => {
+                const wanted = authoredTags(block.root, hostTagOf);
+
+                mounted(block.root, (root) => {
+                    const built = realised(root, wanted).map((el) => el.tagName.toLowerCase());
+                    expect(built).toStrictEqual(wanted);
+                });
+            });
+        }
+    });
+
+    await describe('the shared corpus against the adwaita-core vectors it reaches', async () => {
+        for (const block of ADWAITA_GALLERY_SHARED_TREES) {
+            for (const expectation of sharedTreeExpectations(block.root)) {
+                await it(`${block.widget} — ${expectation.path}: ${expectation.table} — ${expectation.rule}`, () => {
+                    mounted(block.root, (root) => {
+                        // The SAME filtered walk the shape test asserts, so the element an
+                        // expectation is read off is the one at the authored ADDRESS rather
+                        // than the first of its name the DOM happens to contain.
+                        const built = realised(root, authoredTags(block.root, hostTagOf));
+                        const subject = built[subjectIndexOf(block.root, expectation.path)]!;
+                        expect(subject.tagName.toLowerCase()).toBe(hostTagOf(expectation.gtype));
+
+                        expect(read(expectation, subject)).toBe(expectation.expected);
+                    });
+                });
+            }
+        }
+    });
+};