@gjsify/adwaita-web 0.53.0 → 0.55.0

package/src/construct-vectors.spec.ts

@@ -0,0 +1,175 @@
+// ADR 0093: this renderer's `./capabilities` table held to `CONSTRUCT_VECTORS` through the real
+// tree builder and the elements it mounts.
+
+import {
+    BREAKPOINT_VECTOR_SIZES,
+    CONSTRUCT_VECTORS,
+    EXTERN_VECTOR_CLASS,
+    driveConstructVectors,
+    type ConstructVector,
+    type SharedTreeNode,
+} from '@gjsify/adwaita-core/conformance';
+import { describe, expect, it } from '@gjsify/unit';
+
+import type { AdwAlertDialog } from './elements/adw-alert-dialog.js';
+import { capabilities } from './capabilities.mjs';
+import { buildSharedTree, mountSharedTree } from './shared-tree-builder.js';
+import { registerTemplateClass } from './template-classes.js';
+
+const vector = (kind: string) => CONSTRUCT_VECTORS.find((each) => each.kind === kind)!.tree;
+
+class CorpusExtern extends HTMLElement {}
+customElements.define('corpus-extern', CorpusExtern);
+registerTemplateClass(EXTERN_VECTOR_CLASS, 'corpus-extern');
+
+function observe(vector: ConstructVector): unknown {
+    if (vector.kind === 'layout') {
+        buildSharedTree(vector.tree);
+        return undefined;
+    }
+    if (vector.kind === 'page') {
+        const stack = buildSharedTree(vector.tree);
+        return [{ name: stack.children[0]!.getAttribute('name'), title: stack.children[0]!.getAttribute('title') }];
+    }
+    if (vector.kind === 'signal') {
+        let calls = 0;
+        const { root, unmount } = mountSharedTree(vector.tree, {
+            scope: {
+                onClicked: () => {
+                    calls++;
+                },
+            },
+        });
+        try {
+            root.querySelector('#pressed')!.dispatchEvent(new Event('click'));
+            return [{ handler: 'onClicked', calls }];
+        } finally {
+            unmount();
+        }
+    }
+    if (vector.kind === 'bind') {
+        const { root, unmount } = mountSharedTree(vector.tree);
+        try {
+            const source = root.querySelector('#source') as unknown as { active: boolean };
+            const target = root.querySelector('#target') as unknown as { active: boolean };
+            const afterBuild = target.active;
+            source.active = true;
+            return { afterBuild, afterSourceOn: target.active };
+        } finally {
+            unmount();
+        }
+    }
+    if (vector.kind === 'breakpoint') {
+        let feed: ((size: { width: number; height: number }) => void) | undefined;
+        const { root, unmount } = mountSharedTree(vector.tree, {
+            observeSize: (_element, onSize) => {
+                feed = onSize;
+                return () => {};
+            },
+        });
+        try {
+            return BREAKPOINT_VECTOR_SIZES.map((size) => {
+                feed!(size);
+                return root.querySelector('#caption')!.getAttribute('label');
+            });
+        } finally {
+            unmount();
+        }
+    }
+    if (vector.kind === 'extern') {
+        return [...buildSharedTree(vector.tree).children].map((child) => ({
+            id: child.id,
+            builtByRegisteredClass: child instanceof CorpusExtern,
+        }));
+    }
+    const { root, unmount } = mountSharedTree(vector.tree);
+    try {
+        if (vector.kind === 'strings') {
+            return [...root.querySelectorAll('option, .adw-drop-down-item-label')].map((node) => node.textContent);
+        }
+        const dialog = root as unknown as AdwAlertDialog;
+        return (vector.tree.extensions?.responses ?? []).map(({ id }) => ({
+            id,
+            label: dialog.getResponseLabel(id),
+            appearance: dialog.getResponseAppearance(id),
+            enabled: dialog.getResponseEnabled(id),
+        }));
+    } finally {
+        unmount();
+    }
+}
+
+export const AdwConstructVectorsTest = async () => {
+    await driveConstructVectors(
+        { name: 'adwaita-web', capabilities, vectors: CONSTRUCT_VECTORS, observe },
+        { describe, it, expect },
+    );
+    await describe('adwaita-web: template classes and handlers (ADR 0093)', async () => {
+        await it('refuses an extern name nothing registered, naming it', () => {
+            expect(() =>
+                buildSharedTree({ tag: 'GtkBox', children: [{ tag: 'NobodyRegisteredThis', extern: true }] }),
+            ).toThrow("'$NobodyRegisteredThis'");
+        });
+        await it('refuses a second tag under a registered name', () => {
+            expect(() => registerTemplateClass(EXTERN_VECTOR_CLASS, 'corpus-extern-two')).toThrow('already registered');
+        });
+        await it('refuses a registered tag nothing defined, naming it', () => {
+            registerTemplateClass('CorpusUndefinedTag', 'corpus-undefined-tag');
+            expect(() =>
+                buildSharedTree({ tag: 'GtkBox', children: [{ tag: 'CorpusUndefinedTag', extern: true }] }),
+            ).toThrow('nothing has defined');
+        });
+        await it('refuses a signal handler the scope lacks, naming it', () => {
+            const tree = vector('signal');
+            expect(() => mountSharedTree(tree)).toThrow("'onClicked'");
+            expect(() => mountSharedTree(tree, { scope: {} })).toThrow('has no such function');
+        });
+        await it('refuses a signal the element does not declare, and the forms it has not verified', () => {
+            const on = (signal: NonNullable<SharedTreeNode['signals']>[number]): SharedTreeNode => ({
+                tag: 'GtkBox',
+                children: [{ tag: 'GtkButton', signals: [signal] }],
+            });
+            const scope = { onX: () => {} };
+            expect(() => mountSharedTree(on({ name: 'map', handler: 'onX' }), { scope })).toThrow("no signal 'map'");
+            expect(() => mountSharedTree(on({ name: 'clicked', handler: 'onX', flags: ['after'] }), { scope })).toThrow(
+                'plain handlers only',
+            );
+            expect(() => mountSharedTree(on({ name: 'clicked', handler: 'onX', object: 'a' }), { scope })).toThrow(
+                'plain handlers only',
+            );
+        });
+        await it('refuses a bind to an id nothing has, to a source that dispatches no notify, and the flags', () => {
+            const bound = (binding: NonNullable<SharedTreeNode['bindings']>[string], sourceTag = 'GtkToggleButton') =>
+                ({
+                    tag: 'GtkBox',
+                    children: [
+                        { tag: sourceTag, id: 'source' },
+                        { tag: 'GtkToggleButton', bindings: { active: binding } },
+                    ],
+                }) as SharedTreeNode;
+            expect(() => mountSharedTree(bound({ source: 'nobody', property: 'active' }))).toThrow("id 'nobody'");
+            expect(() => mountSharedTree(bound({ source: 'template', property: 'active' }))).toThrow("id 'template'");
+            expect(() => mountSharedTree(bound({ source: 'source', property: 'active' }, 'GtkLabel'))).toThrow(
+                "dispatches no 'notify::active'",
+            );
+            expect(() => mountSharedTree(bound({ source: 'source', property: 'active', flags: ['inverted'] }))).toThrow(
+                'plain form only',
+            );
+        });
+        await it('refuses a breakpoint setter that names no object, and a condition nobody can read', () => {
+            const withBreakpoint = (object: string, condition = 'max-width: 400px') =>
+                ({
+                    tag: 'GtkBox',
+                    children: [{ tag: 'GtkLabel', id: 'caption' }],
+                    breakpoints: [{ condition, setters: [{ object, property: 'label', value: 'x' }] }],
+                }) as SharedTreeNode;
+            expect(() => mountSharedTree(withBreakpoint('nobody'))).toThrow("id 'nobody'");
+            expect(() => mountSharedTree(withBreakpoint('template'))).toThrow("id 'template'");
+            expect(() => mountSharedTree(withBreakpoint('caption', 'wide please'))).toThrow('breakpoint condition');
+        });
+        await it('does not read a registered name for a node that is not extern', () => {
+            const el = buildSharedTree({ tag: 'GtkBox', children: [{ tag: 'GtkLabel' }] });
+            expect(el.children[0]!.localName).toBe('gtk-label');
+        });
+    });
+};

package/src/elements/adw-application-window.ts

@@ -0,0 +1,154 @@
+// <adw-application-window> — the web counterpart of Adw.ApplicationWindow: an
+// AdwWindow that belongs to a GtkApplication, plus that application's menubar.
+//
+// WHAT ADDS UPSTREAM, measured: `Adw.ApplicationWindow` extends `GtkApplicationWindow`
+// and adds nothing but its own `content` / `adaptive-preview` pair, which are
+// AdwWindow's (Adw-1.gir, `parent="ApplicationWindow"`). The whole difference from
+// <adw-window> is `Gtk.ApplicationWindow:show-menubar` — one boolean, and the window
+// draws the menubar the GtkApplication installed in `Gtk.Application:menubar` when it
+// is on, and no menubar at all when it is off.
+//
+// A BROWSER HAS NO GtkApplication, so the model is handed to the window instead of to
+// an application that does not exist here. `menu-model` is the same portable menu value
+// ADR 0042 gave `<gtk-menu-button>` and `<adw-split-button>` (a JSON array), and it is
+// read through the same core parser, so one menu is written once. A menubar is a row of
+// MENU LINKS, which is what `Adw.Application`'s menubar is documented to be, so a
+// section is inlined and a bare item becomes a plain button — `flattenMenu` is the
+// walk that decides both.
+//
+// Attributes:
+//   show-menubar (boolean — Gtk.ApplicationWindow:show-menubar; the bar is drawn only
+//     while this is set AND the model has something in it, exactly as GTK draws no bar
+//     for an application that installed none)
+//   menu-model   (the portable menu model, JSON — the stand-in for the model a
+//     GtkApplication would own; the same value `<gtk-menu-button menu-model>` takes)
+//
+// Extends <adw-window> and adds nothing else: the content property, the size request,
+// the breakpoints and the dialog bookkeeping are all inherited.
+//
+// Reference: refs/libadwaita/src/adw-application-window.c (the class adds no behaviour)
+// Reference: Gtk-4.0.gir `Gtk.ApplicationWindow:show-menubar` ("If this property is true,
+//   the window will display a menubar unless it is shown by the desktop shell")
+// Copyright (c) 2021-2023 Alice Mikhaylenko / Purism SPC (libadwaita). LGPLv2.1+
+// Modifications: Implemented as a Web Component for @gjsify/adwaita-web.
+
+import {
+    flattenMenu,
+    normalizeMenuModel,
+    parseMenuModel,
+    type AdwMenuInput,
+    type AdwMenuModel,
+} from '@gjsify/adwaita-core';
+
+import { AdwWindow } from './adw-window.js';
+
+export class AdwApplicationWindow extends AdwWindow {
+    private _menubarEl: HTMLDivElement | null = null;
+    private _model: AdwMenuModel = [];
+
+    // The base's list BY NAME, not `super.observedAttributes`: `AdwPasswordEntryRow`
+    // spells its spread this way and the attribute readers follow (`adwaita-elements.mjs`
+    // resolves a `[...Base.observedAttributes]` spread across files, and reports a
+    // `super` one as unreadable rather than as empty).
+    static get observedAttributes(): string[] {
+        return [...AdwWindow.observedAttributes, 'show-menubar', 'menu-model'];
+    }
+
+    /** Whether this window shows the application's menubar (Gtk.ApplicationWindow:show-menubar). */
+    get showMenubar(): boolean {
+        return this.hasAttribute('show-menubar');
+    }
+
+    set showMenubar(value: boolean) {
+        if (value) this.setAttribute('show-menubar', '');
+        else this.removeAttribute('show-menubar');
+    }
+
+    /** The menubar's model — what a GtkApplication would own here. */
+    get menuModel(): AdwMenuModel {
+        return this._model;
+    }
+
+    set menuModel(value: AdwMenuInput) {
+        this._model = normalizeMenuModel(value);
+        this._renderMenubar();
+    }
+
+    /** The menubar strip, or null before the window is connected. */
+    get menubar(): HTMLDivElement | null {
+        return this._menubarEl;
+    }
+
+    connectedCallback() {
+        super.connectedCallback();
+        this._buildMenubar();
+    }
+
+    attributeChangedCallback(name: string) {
+        super.attributeChangedCallback(name);
+        // The attribute is the declarative form and it wins when it changes — the same
+        // precedence `<gtk-menu-button>` gives `menu-model`, through the same parser.
+        if (name === 'menu-model') this._model = parseMenuModel(this.getAttribute('menu-model'));
+        // Before the first connect the menubar does not exist yet, and `_buildMenubar`
+        // renders from the model this has just read — so nothing is built twice.
+        if (name === 'show-menubar' || name === 'menu-model') this._renderMenubar();
+    }
+
+    /**
+     * The menubar, INSIDE the content area rather than beside it.
+     *
+     * `bindSlottedChildren` watches the host and moves every child it does not claim
+     * into the content area, so a sibling would be re-homed into it one tick later. The
+     * content area's own children are not watched, so prepending here is stable — and
+     * it is also where the bar belongs: above the toolbar view, inside the window box.
+     */
+    private _buildMenubar() {
+        if (this._menubarEl) return;
+        this._menubarEl = document.createElement('div');
+        this._menubarEl.className = 'adw-application-window-menubar';
+        this.contentArea.prepend(this._menubarEl);
+
+        this._renderMenubar();
+    }
+
+    private _renderMenubar(): void {
+        const bar = this._menubarEl;
+        if (bar === null) return;
+
+        bar.replaceChildren();
+        // GTK draws no menubar for an application that installed none, so neither does
+        // this: both the flag and a model with rows in it are required.
+        bar.hidden = !this.showMenubar || this._model.length === 0;
+
+        for (const row of flattenMenu(this._model)) {
+            const node = row.node;
+            if (node.kind === 'submenu') {
+                // A link is a menu the user OPENS — a button with that menu on it,
+                // which is the whole of what a Gtk.PopoverMenuBar row is.
+                const button = document.createElement('gtk-menu-button');
+                button.setAttribute('menu-title', node.label);
+                (button as unknown as { menuModel: AdwMenuInput }).menuModel = node.items;
+                bar.appendChild(button);
+                continue;
+            }
+            // A bare item has no menu to open, so it is a button that activates it — and
+            // it reports the activation the way every other menu surface here does
+            // (`<gtk-menu-button>`, `<adw-split-button>`): the item's id, its label and
+            // its PATH in the model.
+            const button = document.createElement('gtk-button');
+            button.setAttribute('label', node.label ?? '');
+            button.setAttribute('flat', '');
+            button.addEventListener('click', () => {
+                this.dispatchEvent(
+                    new CustomEvent('menu-item-activated', {
+                        bubbles: true,
+                        detail: { id: node.id ?? node.label, label: node.label, path: [...row.path] },
+                    }),
+                );
+            });
+            bar.appendChild(button);
+        }
+    }
+}
+
+customElements.define('adw-application-window', AdwApplicationWindow);

package/src/elements/adw-bin.ts

@@ -0,0 +1,101 @@
+// <adw-bin> — a widget with ONE child.
+//
+// The smallest container libadwaita ships and the base every other one-child widget
+// derives from: `adw_bin_set_child` replaces what was there, `GtkBinLayout` gives the
+// child the whole allocation, `compute_expand` follows the child and `focus` goes to
+// it (adw-bin.c:108-123). There is no `bin` node in the stylesheet — the widget draws
+// nothing of its own, which is why the whole element is the slot and nothing else.
+//
+// ONE CHILD, and the replacement is C's, not the DOM's: a second child REPLACES the
+// first rather than stacking beside it. Two doors lead there — `child`/`setChild`, which
+// libadwaita offers, and a plain `append`, which markup and a `.blp`'s `child: …` use —
+// and an observer on the host makes the second one end where the first does: the LAST
+// child stays. The slot routing below only enrols the NAME `child` so a `.blp`'s child is
+// not refused sight unseen (`src/slotted-children.ts`, and the reason `adw-clamp.ts`
+// gives for not calling `.install()`).
+//
+// `set_child` REFUSES a child that already has a parent (`g_return_if_fail (gtk_widget
+// _get_parent (child) == NULL)`, adw-bin.c:208). A DOM append MOVES such a node rather
+// than rejecting it, so `setChild` refuses a child whose parent is another element and
+// says so — the same contract `adw_preferences_group_remove` keeps in
+// `<adw-preferences-group>`.
+//
+// A11Y: no role. `adw_bin_class_init` sets none, so the widget keeps `GtkWidget`'s
+// default `GENERIC` and a bin contributes nothing to the accessibility tree of its own.
+//
+// KNOWN_GAPS: none — `AdwBin`'s only property is `child`, a widget, which is a SLOT on
+// every renderer.
+//
+// Reference: refs/libadwaita/src/adw-bin.c (adw_bin_set_child, class_init)
+// Copyright (c) 2021 Purism SPC / GNOME contributors (libadwaita). LGPLv2.1+.
+// Modifications: Implemented as a Web Component for @gjsify/adwaita-web.
+
+import { bindSlottedChildren } from '../slotted-children.js';
+
+export class AdwBin extends HTMLElement {
+    private _observer: MutationObserver | null = null;
+
+    /** `Adw.Bin:child` — the one child, or `null`. The last one appended is the one that stays. */
+    get child(): Element | null {
+        return this.lastElementChild;
+    }
+
+    /** `adw_bin_set_child`: replace the current child, unparenting it. */
+    set child(value: Element | null) {
+        this.setChild(value);
+    }
+
+    connectedCallback() {
+        // The NAME only. Every child of a bin already IS its content — there is no
+        // internal structure to route into — so `.install()` is deliberately not called
+        // for the reason `adw-clamp.ts` gives: it would `replaceChildren` a subtree the
+        // author wrote and arm an observer that then re-routes what the element itself
+        // puts there.
+        bindSlottedChildren(this, [{ name: 'child', into: this }]);
+        this._enforceSingleChild();
+        // After the enforcement above, so its own removals are not reported back to it.
+        this._observer ??= new MutationObserver(() => this._enforceSingleChild());
+        this._observer.observe(this, { childList: true });
+    }
+
+    disconnectedCallback() {
+        // A bin parked with two children (both appended while detached, where no
+        // observer is watching) comes back to one on re-entry, in connectedCallback.
+        this._observer?.disconnect();
+    }
+
+    /**
+     * `adw_bin_set_child` — the LAST child wins, and the one it replaces leaves.
+     *
+     * A removal, not a move: C unparents the child it replaces.
+     */
+    private _enforceSingleChild(): void {
+        const last = this.lastElementChild;
+        if (last === null) return;
+        for (const child of Array.from(this.children)) {
+            if (child === last) break;
+            child.remove();
+        }
+    }
+
+    /** `adw_bin_set_child`, including its refusal of a child that already has a parent. */
+    setChild(value: Element | null): void {
+        if (value !== null && value.parentElement !== null && value.parentElement !== this) {
+            // C's `g_return_if_fail` is a no-op with a message on stderr; returning
+            // `false` is the same contract without the write, and `child`'s setter
+            // drops the answer the way the other elements' do.
+            throw new Error('AdwBin.setChild: the child already has a parent.');
+        }
+        if (value === this.child) return;
+
+        const previous = this.child;
+        if (value === null) {
+            previous?.remove();
+        } else {
+            this.replaceChildren(value);
+        }
+        this.dispatchEvent(new CustomEvent('notify::child', { bubbles: true, detail: { child: value } }));
+    }
+}
+
+customElements.define('adw-bin', AdwBin);