@gjsify/adwaita-web 0.64.1 → 0.64.2-next.254

package/src/shared-tree-builder.ts

@@ -28,7 +28,7 @@
 // into a host `<div>` it was never given.
 //
 // Placed flat under `src/`, at parity with this package's other single-purpose modules
-// (`accent.ts`, `breakpoints.ts`, `icon-registry.ts`) rather than a new `conformance/` or
+// (`accent.ts`, `breakpoints.ts`, `icon-theme.ts`) rather than a new `conformance/` or
 // `builder/` directory for one file: unlike `gtk-host`, this package has no existing
 // `conformance/` home to add to. Exported through the existing barrel, `src/index.ts` — the
 // package's `exports` map ships only `.`, and a new subpath would buy nothing for a module
@@ -55,7 +55,14 @@ import {
 
 import { observeAdaptiveSize } from './breakpoints.js';
 import { capabilities } from './capabilities.mjs';
-import { endpointOf, hasElementApi, installElementApi, installSensitive } from './gobject-elements.js';
+import {
+    endpointOf,
+    hasElementApi,
+    hasInstalledVisible,
+    installElementApi,
+    installSensitive,
+    installVisible,
+} from './gobject-elements.js';
 import { dispatchedSignalsOf } from './signals.js';
 import { slottedChildrenOf } from './slotted-children.js';
 import { isTemplateTag, templateTagFor } from './template-classes.js';
@@ -154,14 +161,93 @@ function isWritable(el: object, member: string): boolean {
  * upgraded has declared no slots yet, so the refusal below belongs to the mount.
  */
 export function buildSharedTree(node: SharedTreeNode, record: BuildRecord = newRecord()): HTMLElement {
+    refuseSiblings(node, 'buildSharedTree');
+    return buildTree(node, record).root;
+}
+
+/** What {@link buildWithSiblings} hands back: the root element and the objects built beside it. */
+export interface BuiltTree {
+    /** The element the tree roots at, as {@link buildSharedTree} returns it. */
+    root: HTMLElement;
+    /**
+     * The sibling objects by id — `Adw.AlertDialog unsavedChangesDialog { }` or `$Learn learn { }`
+     * written after the template. A sibling is built in the root's id scope (a setter or a bind
+     * may name it) but is no child of the root: the code beside the file decides where, or
+     * whether, it is placed.
+     */
+    siblings: ReadonlyMap<string, HTMLElement>;
+    /** Every element the tree names by id, siblings included: what `GtkBuilder.get_object` answers for. */
+    objects: ReadonlyMap<string, HTMLElement>;
+}
+
+/** What {@link buildWithSiblings} takes beside the tree. */
+export interface BuildOptions {
+    /** The object a handler NAME is looked up on (ADR 0093 § 3). */
+    scope?: Readonly<Record<string, unknown>>;
+    /** The size source a `breakpoints` node is driven from. */
+    observeSize?: SizeSource;
+}
+
+/**
+ * A tree with sibling roots (ADR 0093): the root element, and each sibling by id, all DETACHED
+ * like {@link buildSharedTree}'s result.
+ *
+ * {@link buildSharedTree}, {@link mountSharedTree} and {@link buildTemplateTree} refuse such a
+ * tree by name, because they return one element and the siblings would be built and then thrown
+ * away. A sibling with no id is refused too: nothing could ever ask for it, which is how a
+ * dropped object looks finished.
+ */
+export function buildWithSiblings(node: SharedTreeNode, options: BuildOptions = {}): BuiltTree {
+    const record = newRecord(options.scope, options.observeSize);
+    const built = buildTree(node, record);
+    // An element declares its slots when it is connected, so a detached tree cannot be checked
+    // as it stands. It is connected for the length of the check and handed back detached, as
+    // documented: a placement the renderer could not honour is refused here, like
+    // `mountSharedTree` refuses it, instead of surfacing as a widget missing from the page.
+    const probe = document.createElement('div');
+    probe.hidden = true;
+    probe.append(built.root, ...built.siblings.values());
+    document.body.append(probe);
+    try {
+        refuseUnknownSlots(record.placed);
+        refuseUnheldExtensions(record.extended);
+    } catch (error) {
+        for (const dispose of record.disposers) dispose();
+        throw error;
+    } finally {
+        probe.remove();
+        for (const el of [built.root, ...built.siblings.values()]) el.remove();
+    }
+    return built;
+}
+
+function refuseSiblings(node: SharedTreeNode, door: string): void {
+    if ((node.siblings?.length ?? 0) === 0) return;
+    throw new Error(
+        `\`${node.tag}\` carries ${node.siblings!.length} sibling object(s), and \`${door}\` returns one object ` +
+            'so they would be built and lost. Use `buildWithSiblings`, which hands them back by id.',
+    );
+}
+
+/** Every node, its siblings in the same id scope, then the binds and breakpoints that name them. */
+function buildTree(node: SharedTreeNode, record: BuildRecord): BuiltTree {
     // ADR 0093 § 2: the whole tree is checked against the capability table before an element is
     // created. A refused `layout` is named with its node and the reason the table gives.
-    assertTreeConstructs('adwaita-web', capabilities, node);
+    assertTreeConstructs('adwaita-web', capabilities, node, Object.keys(ARIA_OF));
     if (node.menus !== undefined) record.menus = node.menus;
     const root = buildNode(node, record);
+    const siblings = new Map<string, HTMLElement>();
+    for (const sibling of node.siblings ?? []) {
+        if (sibling.id === undefined) {
+            throw new Error(
+                `the sibling \`${sibling.tag}\` has no id, so nothing could ever ask for it: give it one in the .blp.`,
+            );
+        }
+        siblings.set(sibling.id, buildNode(sibling, record));
+    }
     for (const bind of record.binds) bindProperty(bind, record);
     for (const host of record.breakpointHosts) bindBreakpoints(host.el, host.node, record);
-    return root;
+    return { root, siblings, objects: new Map(record.ids) };
 }
 
 /** A fresh record, with the scope when the caller has one. */
@@ -344,7 +430,9 @@ export function writeProp(el: HTMLElement, prop: string, value: string | number
     const member = propertyOf(prop);
     const expand = GTK_WIDGET_EXPAND.find((name) => name === attr);
     if (expand !== undefined && typeof value === 'boolean') el.setAttribute(expand, value ? '' : 'false');
-    else if (isTemplateTag(el.localName) && member in el) {
+    else if (attr === 'visible' && typeof value === 'boolean' && hasInstalledVisible(el)) {
+        (el as unknown as Record<string, unknown>)[member] = value;
+    } else if (isTemplateTag(el.localName) && member in el) {
         // An application class has no attributeChangedCallback: its properties are GObject properties,
         // set the way `Gtk.Builder` sets them, after the constructor.
         (el as unknown as Record<string, unknown>)[member] = value;
@@ -372,9 +460,14 @@ function buildNode(node: SharedTreeNode, record: BuildRecord): HTMLElement {
     const el = document.createElement(node.extern === true ? templateTagFor(node.tag) : hostTagOf(node.tag));
     // A template's children talk GObject to the template: `connect`, `emit`, `notify` (ADR 0096).
     if (record.template !== undefined) installElementApi(el);
+    // `Gtk.Widget:visible`, which no element spells: a setter's target and an authored `false` need it.
+    installVisible(el);
     // The id is how the TypeScript beside a `.blp` reaches this element
     // (`root.querySelector('#…')`), the counterpart of `InternalChildren` on GTK.
     if (node.id !== undefined) {
+        if (record.ids.has(node.id)) {
+            throw new Error(`Two nodes of this tree carry the id '${node.id}'; GtkBuilder refuses a duplicate id.`);
+        }
         el.id = node.id;
         record.ids.set(node.id, el);
     }
@@ -419,6 +512,29 @@ function writeLook(el: HTMLElement, node: SharedTreeNode, menus?: SharedTreeNode
     // `.blp`'s `styles ["title-1"]` reached the tree and never the page.
     if (node.styleClasses !== undefined && node.styleClasses.length > 0) el.classList.add(...node.styleClasses);
     writeExtensions(el, node);
+    writeAccessibility(el, node);
+}
+
+/**
+ * The `accessibility { }` names this renderer has a door for, and the ARIA attribute each is.
+ * The rest (states, relations, `row-index`, …) are refused by name before the build, in
+ * {@link assertTreeConstructs}: no element here reads them, so they would be dropped.
+ */
+const ARIA_OF: Readonly<Record<string, string>> = {
+    label: 'aria-label',
+    description: 'aria-description',
+};
+
+/**
+ * `accessibility { label; description; }` as the host's `aria-label` / `aria-description`.
+ * Written after the props, so an element that derives a name from its tooltip sees the
+ * authored one first; an element whose role lives on an inner control forwards both
+ * (`accessible.ts`). A translatable value is written as its source text, as a prop's is.
+ */
+function writeAccessibility(el: HTMLElement, node: SharedTreeNode): void {
+    for (const [name, entry] of Object.entries(node.accessibility ?? {})) {
+        el.setAttribute(ARIA_OF[name], String(entry.value));
+    }
 }
 
 /** The `GtkGridLayoutChild` properties `layout { }` may carry, and the CSS Grid line each one is. */
@@ -492,7 +608,8 @@ export interface BuiltTemplateTree {
  * belong to the first `connectedCallback`.
  */
 export function buildTemplateTree(tree: SharedTreeNode, scope: TemplateScope, host: HTMLElement): BuiltTemplateTree {
-    assertTreeConstructs('adwaita-web', capabilities, tree);
+    refuseSiblings(tree, 'buildTemplateTree');
+    assertTreeConstructs('adwaita-web', capabilities, tree, Object.keys(ARIA_OF));
     const record = newRecord(undefined, undefined, scope);
     record.menus = tree.menus;
     if (tree.id !== undefined) record.ids.set(tree.id, host);
@@ -591,9 +708,9 @@ function writeExtensions(el: HTMLElement, node: SharedTreeNode): void {
 
 /** The response API an element answers to — `<adw-alert-dialog>`'s, named after libadwaita's. */
 interface ResponseReader {
-    getResponseLabel(id: string): string | null;
-    getResponseAppearance(id: string): string | null;
-    getResponseEnabled(id: string): boolean;
+    get_response_label(id: string): string | null;
+    get_response_appearance(id: string): string | null;
+    get_response_enabled(id: string): boolean;
 }
 
 /**
@@ -617,10 +734,10 @@ function refuseUnheldExtensions(extended: readonly ExtendedNode[]): void {
         const reader = el as unknown as Partial<ResponseReader>;
         for (const response of node.extensions?.responses ?? []) {
             const held =
-                typeof reader.getResponseLabel === 'function' &&
-                reader.getResponseLabel(response.id) === response.label &&
-                reader.getResponseAppearance?.(response.id) === (response.appearance ?? 'default') &&
-                reader.getResponseEnabled?.(response.id) === (response.enabled ?? true);
+                typeof reader.get_response_label === 'function' &&
+                reader.get_response_label(response.id) === response.label &&
+                reader.get_response_appearance?.(response.id) === (response.appearance ?? 'default') &&
+                reader.get_response_enabled?.(response.id) === (response.enabled ?? true);
             if (!held) {
                 throw new Error(
                     `<${el.localName}> did not register the response "${response.id}" as authored, so the ` +
@@ -696,6 +813,7 @@ export interface MountOptions {
  * `buildSharedTree` is for a caller that already has somewhere of its own to attach it.
  */
 export function mountSharedTree(node: SharedTreeNode, options: MountOptions = {}): MountedSharedTree {
+    refuseSiblings(node, 'mountSharedTree');
     const { into } = options;
     const host = into ?? document.createElement('div');
     const record = newRecord(options.scope, options.observeSize);

package/src/shared-trees.spec.ts

@@ -54,7 +54,7 @@ import { ADWAITA_GALLERY_SHARED_TREES } from '../../../../scripts/adwaita-galler
 
 import '@gjsify/adwaita-web';
 
-import { mountSharedTree } from './shared-tree-builder.js';
+import { buildWithSiblings, mountSharedTree } from './shared-tree-builder.js';
 
 /**
  * Connect the authored root — these elements build on connect — run, and take it down again.
@@ -364,6 +364,20 @@ export const AdwSharedTreesTest = async () => {
             ).toThrow('has no slot "middle"');
         });
 
+        // The detached door refuses it too: a root built and handed back is mounted by the
+        // caller, after the builder could still say anything.
+        await it('`buildWithSiblings` refuses the same placement, and hands a good tree back detached', () => {
+            const bad = { tag: 'AdwToolbarView', children: [{ tag: 'AdwBanner', slot: 'middle' }] };
+            expect(() => buildWithSiblings(bad)).toThrow('has no slot "middle"');
+            const { root, siblings } = buildWithSiblings({
+                tag: 'AdwToolbarView',
+                children: [{ tag: 'AdwBanner', slot: 'top' }],
+                siblings: [{ tag: 'GtkLabel', id: 'beside' }],
+            });
+            expect(root.isConnected || siblings.get('beside')!.isConnected).toBe(false);
+            expect(root.querySelector('adw-banner') !== null).toBe(true);
+        });
+
         // ADR 0092's `layout { }`: a grid child's cell. GTK counts from 0, CSS Grid from 1.
         await it('`layout { }` places a grid child in its cell, spans defaulting to one', () => {
             mounted(

package/src/signals.ts

@@ -9,7 +9,16 @@
 /** GTK signal name → the DOM event type the element dispatches it as. */
 export type DispatchedSignals = Readonly<Record<string, string>>;
 
-/** The signals `el`'s class declares, or none. */
+/**
+ * The signals `el`'s class and every class above it declare, or none. A class inherits its
+ * base's signals as a GObject class does (`map` / `unmap` are declared once, on
+ * `WidgetElement`); where two declare the same name, the more derived class wins.
+ */
 export function dispatchedSignalsOf(el: Element): DispatchedSignals {
-    return (el.constructor as { signals?: DispatchedSignals }).signals ?? {};
+    const chain: DispatchedSignals[] = [];
+    for (let klass: unknown = el.constructor; typeof klass === 'function'; klass = Object.getPrototypeOf(klass)) {
+        const own = Object.getOwnPropertyDescriptor(klass, 'signals')?.value as DispatchedSignals | undefined;
+        if (own !== undefined) chain.unshift(own);
+    }
+    return Object.assign({}, ...chain) as DispatchedSignals;
 }

package/src/slotted-children.spec.ts

@@ -113,6 +113,30 @@ export const AdwSlottedChildrenTest = async () => {
             expect(report).toBe('[1]');
         });
 
+        // The DECLARED twin of the case above. `install()` replaces the host's children with
+        // its structure, and a child no slot took used to go with them — gone without a word.
+        await it('keeps a declared child no slot takes, and warns that it was not placed', () => {
+            const host = document.createElement('div');
+            const typo = probe('sied', 'a');
+            host.append(document.createTextNode('\n  '), typo);
+            mounted(host);
+            const side = document.createElement('div');
+            side.className = 'side';
+
+            const warned: string[] = [];
+            const warn = console.warn;
+            console.warn = (...args: unknown[]) => void warned.push(args.join(' '));
+            try {
+                bindSlottedChildren(host, [{ name: 'side', into: side }]).install(side);
+            } finally {
+                console.warn = warn;
+            }
+
+            const report = `${placement(host, typo)} | ${warned.join()}`;
+            host.remove();
+            expect(report).toBe("[1] | 'sied' is not a valid child type of 'div'");
+        });
+
         await it('re-adopts a child that was appended, removed and appended again', async () => {
             const host = mounted(document.createElement('div'));
             const side = document.createElement('div');

package/src/slotted-children.ts

@@ -113,6 +113,12 @@ export interface AdwSlottedChildren {
 /** Where a bound host's slots can be read back from — see {@link slottedChildrenOf}. */
 const BOUND = new WeakMap<Element, AdwSlottedChildren>();
 
+/** An element or a text node with something in it — markup's indentation and comments are not. */
+function isContent(node: Node): boolean {
+    if (node instanceof Element) return true;
+    return node.nodeType === Node.TEXT_NODE && (node.textContent ?? '').trim() !== '';
+}
+
 /**
  * The slot binding `host` installed, if it has one.
  *
@@ -184,9 +190,19 @@ export function bindSlottedChildren(
         slots,
         slotFor,
         install(...nodes: readonly Node[]) {
-            for (const node of Array.from(host.childNodes)) route(node);
+            const unplaced: Node[] = [];
+            for (const node of Array.from(host.childNodes)) {
+                if (route(node) !== null || node.parentNode !== host || !isContent(node)) continue;
+                // `replaceChildren` below would delete it, and a child the author wrote that
+                // vanishes without a word is the silent drop this used to be. It stays beside
+                // the structure, as a late child with the same slot does, and says so the
+                // way GtkBuilder does (GTK_BUILDER_WARN_INVALID_CHILD_TYPE).
+                unplaced.push(node);
+                const type = node instanceof Element ? (node.getAttribute('slot') ?? '') : '';
+                console.warn(`'${type}' is not a valid child type of '${host.localName}'`);
+            }
             structure = new Set(nodes);
-            host.replaceChildren(...nodes);
+            host.replaceChildren(...nodes, ...unplaced);
             // Armed AFTER `replaceChildren`, so its own records are never delivered: an
             // observer armed first would see the whole of `structure` as added nodes and
             // spend a microtask rejecting them.

package/src/source-view/adw-source-view.ts

@@ -36,13 +36,14 @@ import { adwaitaEditorTheme, adwaitaHighlightStyle, ensureSourceViewStyleInjecte
 import { formatHexAddress, formatLineNumber, stripSourceWhitespace } from '@gjsify/adwaita-core';
 import { createGtkImage } from '../elements/gtk-image.js';
 import { createCopyGlyph } from './copy-glyph.js';
+import { WidgetElement } from '../widget-element.js';
 
 /** Parse a boolean attribute: present (any value but "false") ⇒ true. */
 function boolAttr(value: string | null): boolean {
     return value !== null && value !== 'false';
 }
 
-export class AdwSourceView extends HTMLElement {
+export class AdwSourceView extends WidgetElement {
     private _view?: EditorView;
     private _editorHost!: HTMLDivElement;
     private _copyButton!: HTMLButtonElement;

package/src/split-button.spec.ts

@@ -20,7 +20,7 @@ import {
 import { ADW_MENU_SURFACE_WEB, flattenMenu, menuRefusals } 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-registry.spec.js';
+import { fallbackMask, maskOf } from './icon-masks.spec.js';
 
 /** The GObject properties the element re-emits as `notify::*` CustomEvents. */
 const NOTIFY_PROPERTIES: readonly SplitButtonProperty[] = [

package/src/style-manager.spec.ts

@@ -6,6 +6,7 @@ import { STYLE_MANAGER_VECTORS, driveStyleManagerVectors, type AdwStyleLike } fr
 import { describe, expect, it } from '@gjsify/unit';
 
 import * as Adw from './namespace/adw.js';
+import { webStyleSource } from './style-manager.js';
 
 export const StyleManagerTest = async () => {
     const root = document.documentElement;
@@ -26,6 +27,18 @@ export const StyleManagerTest = async () => {
             { describe, it, expect },
         );
         await describe('adwaita-web: Adw.StyleManager door', async () => {
+            await it('system_supports_color_schemes is true where prefers-color-scheme is known', () => {
+                expect(Adw.StyleManager.get_default().system_supports_color_schemes).toBe(true);
+            });
+            await it('a browser that matches neither scheme does not support them', () => {
+                const real = globalThis.matchMedia;
+                globalThis.matchMedia = ((query: string) => ({ matches: false, media: query })) as never;
+                try {
+                    expect(webStyleSource.supportsColorSchemes?.()).toBe(false);
+                } finally {
+                    globalThis.matchMedia = real;
+                }
+            });
             await it('has a vector row for every vector', () => {
                 expect(STYLE_MANAGER_VECTORS.length > 0).toBe(true);
             });

package/src/style-manager.ts

@@ -2,6 +2,8 @@
 // on the root outranks `prefers-color-scheme` (ADR 0078, `isAdwaitaDark`). The behaviour is the
 // core's (`style-manager.ts`); this file is the SOURCE: the root's `class` attribute and the media
 // query are the two things that can flip it. Without a `document` (SSR) it is light and never changes.
+// The system supports color schemes when the browser knows `prefers-color-scheme`: then one of its
+// two values matches; a browser without the feature matches neither.
 
 import { ColorScheme, StyleManagerBase, type StyleSource } from '@gjsify/adwaita-core';
 
@@ -20,6 +22,10 @@ export const webStyleSource: StyleSource = {
             observer.disconnect();
         };
     },
+    supportsColorSchemes() {
+        const matches = (query: string) => globalThis.matchMedia?.(query).matches === true;
+        return matches('(prefers-color-scheme: dark)') || matches('(prefers-color-scheme: light)');
+    },
 };
 
 // FORCE_DARK / FORCE_LIGHT write the same root class an app writes by hand; DEFAULT takes it away.