@gjsify/adwaita-web 0.53.0 → 0.55.0

package/src/shared-tree-builder.ts

@@ -34,10 +34,15 @@
 // package's `exports` map ships only `.`, and a new subpath would buy nothing for a module
 // this small, most of which (the `SharedTreeNode` type) is erased at build anyway.
 
-import type { SharedTreeNode } from '@gjsify/adwaita-core/conformance';
+import { createBreakpointDriver, parseBreakpointCondition, type BreakpointSize } from '@gjsify/adwaita-core';
+import { assertTreeConstructs, type SharedTreeNode } from '@gjsify/adwaita-core/conformance';
 import { GTK_WIDGET_MARGIN_CSS, attributeOf, hostTagOf, propertyOf } from '@gjsify/adwaita-core/tags';
 
+import { observeAdaptiveSize } from './breakpoints.js';
+import { capabilities } from './capabilities.mjs';
+import { dispatchedSignalsOf } from './signals.js';
 import { slottedChildrenOf } from './slotted-children.js';
+import { templateTagFor } from './template-classes.js';
 
 /** One authored placement, kept so {@link mountSharedTree} can hold the renderer to it. */
 interface PlacedChild {
@@ -56,6 +61,29 @@ interface ExtendedNode {
 interface BuildRecord {
     placed: PlacedChild[];
     extended: ExtendedNode[];
+    /** Every authored id and the element it built, which a `bind` source is looked up in. */
+    ids: Map<string, HTMLElement>;
+    /** The `bindings` of every node, resolved once every id exists (a source may be built after its target). */
+    binds: PendingBind[];
+    /** The nodes that carry `breakpoints`, wired once every id exists (a setter may name a later sibling). */
+    breakpointHosts: { el: HTMLElement; node: SharedTreeNode }[];
+    /** Undoes what the build wired to the outside (the size observers); {@link mountSharedTree}'s `unmount` runs it. */
+    disposers: (() => void)[];
+    /** The size source a `breakpoints` node is driven from; a `ResizeObserver` unless the caller supplies one. */
+    observeSize?: SizeSource;
+    /** The object a signal handler's NAME is resolved against (ADR 0093 § 3), as `Gtk.BuilderScope` does. */
+    scope?: Readonly<Record<string, unknown>>;
+}
+
+/** Calls `onSize` with the host's measured size, now and on every change; returns its disposer. */
+export type SizeSource = (element: Element, onSize: (size: BreakpointSize) => void) => () => void;
+
+interface PendingBind {
+    el: HTMLElement;
+    property: string;
+    source: string;
+    sourceProperty: string;
+    flags: readonly string[];
 }
 
 /**
@@ -103,29 +131,175 @@ function isWritable(el: object, member: string): boolean {
  * container. A DETACHED build therefore cannot check a slot either: an element that has not
  * upgraded has declared no slots yet, so the refusal below belongs to the mount.
  */
-export function buildSharedTree(node: SharedTreeNode, record: BuildRecord = { placed: [], extended: [] }): HTMLElement {
-    const el = document.createElement(hostTagOf(node.tag));
+export function buildSharedTree(node: SharedTreeNode, record: BuildRecord = newRecord()): HTMLElement {
+    // 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);
+    const root = buildNode(node, record);
+    for (const bind of record.binds) bindProperty(bind, record);
+    for (const host of record.breakpointHosts) bindBreakpoints(host.el, host.node, record);
+    return root;
+}
+
+/** A fresh record, with the scope when the caller has one. */
+function newRecord(scope?: Readonly<Record<string, unknown>>, observeSize?: SizeSource): BuildRecord {
+    return {
+        placed: [],
+        extended: [],
+        ids: new Map(),
+        binds: [],
+        breakpointHosts: [],
+        disposers: [],
+        ...(scope === undefined ? {} : { scope }),
+        ...(observeSize === undefined ? {} : { observeSize }),
+    };
+}
+
+/** What a setter's target held before any breakpoint wrote it: the member's value or the attribute's. */
+type Original = { member: unknown } | { attribute: string | null };
+
+/**
+ * ADR 0093's `breakpoints`: each setter's `object` resolves to the element built for that id and
+ * the write is the one an authored prop takes. The parent's own box is the size source (a
+ * `ResizeObserver`; an Adwaita condition is written against the window, which a page rarely is),
+ * and `adwaita-core` picks the breakpoint and the restores.
+ *
+ * Refused by name, never dropped: a setter whose object is not an id of this tree (`template`
+ * included) and a condition the grammar cannot read, which libadwaita would drop silently.
+ */
+function bindBreakpoints(el: HTMLElement, node: SharedTreeNode, record: BuildRecord): void {
+    const definitions = (node.breakpoints ?? []).map((breakpoint) => {
+        if (parseBreakpointCondition(breakpoint.condition) === null) {
+            throw new Error(
+                `<${el.localName}> \`condition ("${breakpoint.condition}")\` is not an Adwaita breakpoint condition.`,
+            );
+        }
+        return {
+            condition: breakpoint.condition,
+            setters: breakpoint.setters.map((setter) => {
+                const object = record.ids.get(setter.object);
+                if (object === undefined) {
+                    throw new Error(
+                        `<${el.localName}> breakpoint setter \`${setter.object}.${setter.property}\` names no object: ` +
+                            `nothing in this tree has the id '${setter.object}'.`,
+                    );
+                }
+                return { object, property: setter.property, value: setter.value };
+            }),
+        };
+    });
+    const driver = createBreakpointDriver<HTMLElement>(definitions, {
+        read(target, property) {
+            const member = propertyOf(property);
+            const current = (target as unknown as Record<string, unknown>)[member];
+            if (typeof current === 'boolean' && isWritable(target, member))
+                return { member: current } satisfies Original;
+            return { attribute: target.getAttribute(attributeOf(property)) } satisfies Original;
+        },
+        write(target, property, value) {
+            const member = propertyOf(property);
+            if (typeof value === 'object' && value !== null && 'member' in value) {
+                (target as unknown as Record<string, unknown>)[member] = (value as { member: unknown }).member;
+            } else if (typeof value === 'object' && value !== null && 'attribute' in value) {
+                const attribute = (value as { attribute: string | null }).attribute;
+                if (attribute === null) target.removeAttribute(attributeOf(property));
+                else target.setAttribute(attributeOf(property), attribute);
+            } else if (typeof value === 'boolean' && isWritable(target, member)) {
+                (target as unknown as Record<string, unknown>)[member] = value;
+            } else writeProp(target, property, value as string | number | boolean);
+        },
+    });
+    record.disposers.push((record.observeSize ?? observeAdaptiveSize)(el, (size) => driver.evaluate(size)));
+}
+
+/**
+ * ADR 0093's `bindings`, the simple form: the target property takes the source's value now and
+ * again on every `notify::<property>` the source dispatches (`G_BINDING_SYNC_CREATE`, which is
+ * what GtkBuilder's `bind-flags` default means).
+ *
+ * Refused by name, never dropped: a source that is not an id of this tree (`template` included),
+ * a source element that does not dispatch `notify::<property>`, a target without a writable
+ * property, and any flag, which this first slice has not verified. An element dispatches
+ * `notify::…` only while connected, so a tree built but never attached follows once, at build.
+ */
+function bindProperty(bind: PendingBind, record: BuildRecord): void {
+    const { el, property, source, sourceProperty, flags } = bind;
+    const where = `<${el.localName}> \`${property}: bind ${source}.${sourceProperty}\``;
+    const from = record.ids.get(source);
+    if (from === undefined) {
+        throw new Error(`${where} names no object: nothing in this tree has the id '${source}'.`);
+    }
+    if (flags.length > 0) {
+        throw new Error(
+            `${where} carries ${flags.join(', ')}: adwaita-web binds the plain form only until each flag is ` +
+                'verified against GObject.',
+        );
+    }
+    const notification = `notify::${sourceProperty}`;
+    const declared = dispatchedSignalsOf(from);
+    const event = declared[notification];
+    if (event === undefined) {
+        throw new Error(
+            `${where}: <${from.localName}> dispatches no '${notification}', so the target would follow the source ` +
+                `once and never again. It dispatches: ${Object.keys(declared).join(', ') || 'none'}.`,
+        );
+    }
+    const targetMember = propertyOf(property);
+    const sourceMember = propertyOf(sourceProperty);
+    if (!isWritable(el, targetMember)) {
+        throw new Error(`${where}: <${el.localName}> has no writable property '${targetMember}'.`);
+    }
+    const follow = () => {
+        (el as unknown as Record<string, unknown>)[targetMember] = (from as unknown as Record<string, unknown>)[
+            sourceMember
+        ];
+    };
+    follow();
+    from.addEventListener(event, follow);
+}
+
+/** One authored property, written as the element reads it; a breakpoint setter takes the same door. */
+function writeProp(el: HTMLElement, prop: string, value: string | number | boolean): void {
+    const member = propertyOf(prop);
+    if (value === false && isWritable(el, member)) (el as unknown as Record<string, unknown>)[member] = false;
+    else if (typeof value === 'boolean') el.toggleAttribute(attributeOf(prop), value);
+    else el.setAttribute(attributeOf(prop), String(value));
+    // A margin is also inline style (`GTK_WIDGET_MARGIN_CSS` says why); the attribute
+    // stays, since it is what the tree authored and what a reader of the DOM looks for.
+    const margin = GTK_WIDGET_MARGIN_CSS[attributeOf(prop)];
+    if (margin !== undefined) el.style.setProperty(margin, `${Number(value)}px`);
+}
+
+function buildNode(node: SharedTreeNode, record: BuildRecord): HTMLElement {
+    // An `extern` node is built by the class the application registered under its name (ADR 0093).
+    const el = document.createElement(node.extern === true ? templateTagFor(node.tag) : hostTagOf(node.tag));
     // The id is how the TypeScript beside a `.blp` reaches this element
     // (`root.querySelector('#…')`), the counterpart of `InternalChildren` on GTK.
-    if (node.id !== undefined) el.id = node.id;
-    for (const [prop, value] of Object.entries(node.props ?? {})) {
-        const member = propertyOf(prop);
-        if (value === false && isWritable(el, member)) (el as unknown as Record<string, unknown>)[member] = false;
-        else if (typeof value === 'boolean') el.toggleAttribute(attributeOf(prop), value);
-        else el.setAttribute(attributeOf(prop), String(value));
-        // A margin is also inline style (`GTK_WIDGET_MARGIN_CSS` says why); the attribute
-        // stays, since it is what the tree authored and what a reader of the DOM looks for.
-        const margin = GTK_WIDGET_MARGIN_CSS[attributeOf(prop)];
-        if (margin !== undefined) el.style.setProperty(margin, `${Number(value)}px`);
+    if (node.id !== undefined) {
+        el.id = node.id;
+        record.ids.set(node.id, el);
     }
+    for (const [property, binding] of Object.entries(node.bindings ?? {})) {
+        record.binds.push({
+            el,
+            property,
+            source: binding.source,
+            sourceProperty: binding.property,
+            flags: binding.flags ?? [],
+        });
+    }
+    for (const [prop, value] of Object.entries(node.props ?? {})) writeProp(el, prop, value);
+    if (node.breakpoints !== undefined) record.breakpointHosts.push({ el, node });
     // `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
     // `.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);
+    bindSignals(el, node, record);
     if (node.extensions !== undefined) record.extended.push({ el, node });
     for (const child of node.children ?? []) {
-        const childEl = buildSharedTree(child, record);
+        const childEl = buildNode(child, record);
+        if (child.page !== undefined) writePage(el, childEl, child);
         if (child.slot !== undefined) {
             childEl.setAttribute('slot', child.slot);
             record.placed.push({ parent: el, child: childEl, slot: child.slot });
@@ -135,6 +309,43 @@ export function buildSharedTree(node: SharedTreeNode, record: BuildRecord = { pl
     return el;
 }
 
+/**
+ * ADR 0093's `signals`: each handler NAME is looked up on the scope the builder was handed and
+ * listened for as the DOM event the element declares for that GTK signal.
+ *
+ * Refused by name, never dropped: a missing scope or handler (as `Gtk.Builder` refuses one), a
+ * signal the element does not declare, and the `swapped`, `after` and `object` forms, which this
+ * first slice has not verified against GTK's argument order and emission phase.
+ */
+function bindSignals(el: HTMLElement, node: SharedTreeNode, record: BuildRecord): void {
+    const declared = dispatchedSignalsOf(el);
+    for (const signal of node.signals ?? []) {
+        const name = signal.detail === undefined ? signal.name : `${signal.name}::${signal.detail}`;
+        const event = declared[name];
+        if (event === undefined) {
+            throw new Error(
+                `<${el.localName}> declares no signal '${name}', so the handler '${signal.handler}' would never ` +
+                    `run. It dispatches: ${Object.keys(declared).join(', ') || 'none'}.`,
+            );
+        }
+        if (signal.object !== undefined || (signal.flags?.length ?? 0) > 0) {
+            throw new Error(
+                `the handler '${signal.handler}' for '${name}' uses ${signal.object === undefined ? '' : 'an object '}` +
+                    `${(signal.flags ?? []).join(', ')}: adwaita-web binds plain handlers only until each of those ` +
+                    'is verified against GTK.',
+            );
+        }
+        const handler = record.scope?.[signal.handler];
+        if (typeof handler !== 'function') {
+            throw new Error(
+                `the tree binds the handler '${signal.handler}' for '${name}', and the scope ` +
+                    `${record.scope === undefined ? 'was not given (pass `scope`)' : 'has no such function'}.`,
+            );
+        }
+        el.addEventListener(event, (domEvent) => handler.call(record.scope, domEvent));
+    }
+}
+
 /**
  * ADR 0072's `extensions`, written in the markup this package already reads for each.
  *
@@ -217,10 +428,12 @@ function refuseUnheldExtensions(extended: readonly ExtendedNode[]): void {
  * purpose. An undefined element has exactly ONE destination — itself — so a placement
  * cannot land anywhere but where the tree authored it; what such a tree is really missing
  * is the WIDGET, which is a wider gap than a slot and not this refusal's claim to make.
- * (`AdwApplicationWindow` is the live case: a real `.blp` roots at one and this package has
- * no element for it.) A DEFINED element that routes no named slot is refused like any
- * other: it built a structure and chose not to route into it, so a name it does not have
- * would leave the child beside that structure.
+ * (It was `AdwApplicationWindow`, which `showcases/gtk/effect-adw-services/src/window.blp`
+ * roots at while this package had no element for it. That element now exists, so the live
+ * case is the opposite one: `<adw-window>` and `<adw-application-window>` both declare
+ * `content`, which is what that file's `content:` becomes.) A DEFINED element that routes
+ * no named slot is refused like any other: it built a structure and chose not to route
+ * into it, so a name it does not have would leave the child beside that structure.
  */
 function refuseUnknownSlots(placed: readonly PlacedChild[]): void {
     for (const { parent, child, slot } of placed) {
@@ -249,9 +462,12 @@ export interface MountedSharedTree {
  * instantiation half a caller reading the corpus's elements normally wants; a bare
  * `buildSharedTree` is for a caller that already has somewhere of its own to attach it.
  */
-export function mountSharedTree(node: SharedTreeNode): MountedSharedTree {
+export function mountSharedTree(
+    node: SharedTreeNode,
+    options: { scope?: Readonly<Record<string, unknown>>; observeSize?: SizeSource } = {},
+): MountedSharedTree {
     const host = document.createElement('div');
-    const record: BuildRecord = { placed: [], extended: [] };
+    const record = newRecord(options.scope, options.observeSize);
     host.append(buildSharedTree(node, record));
     document.body.append(host);
     // After the append, because that is what upgrades the elements and runs the binds the
@@ -261,8 +477,34 @@ export function mountSharedTree(node: SharedTreeNode): MountedSharedTree {
         refuseUnknownSlots(record.placed);
         refuseUnheldExtensions(record.extended);
     } catch (error) {
+        for (const dispose of record.disposers) dispose();
         host.remove();
         throw error;
     }
-    return { root: host.firstElementChild as HTMLElement, unmount: () => host.remove() };
+    return {
+        root: host.firstElementChild as HTMLElement,
+        unmount: () => {
+            for (const dispose of record.disposers) dispose();
+            host.remove();
+        },
+    };
+}
+
+/**
+ * A `page` as the attributes `<gtk-notebook>` (`tab-label`) and `<gtk-stack>` (`name`, `title`)
+ * read off their children. Any other parent is refused by name: the attributes would be written
+ * and read by nobody.
+ */
+function writePage(parent: HTMLElement, child: HTMLElement, node: SharedTreeNode): void {
+    const { page } = node;
+    if (parent.localName === 'gtk-notebook') {
+        if (page?.label !== undefined) child.setAttribute('tab-label', page.label);
+    } else if (parent.localName === 'gtk-stack') {
+        if (page?.name !== undefined) child.setAttribute('name', page.name);
+        if (page?.label !== undefined) child.setAttribute('title', page.label);
+    } else {
+        throw new Error(
+            `adwaita-web's shared-tree builder: <${node.tag}> has a page, and <${parent.localName}> has no pages.`,
+        );
+    }
 }

package/src/signals.ts

@@ -0,0 +1,15 @@
+// The GTK signals an element dispatches, and the DOM event each one arrives as (ADR 0093 § 3).
+//
+// A GTK signal name is not a DOM event name — `clicked` is a native `click` here, `notify::active`
+// is a `CustomEvent` of that very name — so a `.blp`'s `clicked => $onClicked()` cannot be wired by
+// the name alone, and an element that dispatches nothing under it must not be wired silently. Each
+// element declares its signals in a `static signals` the way it declares its `slots`, and the
+// builder refuses a signal the element does not declare.
+
+/** 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. */
+export function dispatchedSignalsOf(el: Element): DispatchedSignals {
+    return (el.constructor as { signals?: DispatchedSignals }).signals ?? {};
+}

package/src/source-view/theme.ts

@@ -35,13 +35,19 @@ import {
  * `_variables.scss` is where that stack is argued about (it explains why
  * 'Cantarell' is dropped from it), so it is where it lives.
  *
- * The `var()` FALLBACK is a second copy by construction — it has to be, or a page
- * that loads the stylesheet without the theme tokens gets no stack at all — so it
- * is kept to the token's own value and nothing longer, and a tail entry landing in
- * `_variables.scss` (#1817 added 'Consolas') has to land here too.
+ * The repeat is still a SECOND COPY, and a copy of a value the conformance rule
+ * CAN see is the failure this constant was created to end — a tail edited in one
+ * place and not the other is an editor in one typeface and a label beside it in
+ * another, which is the same bug one argument shorter. It is a `var()` FALLBACK,
+ * so the token wins whenever the stylesheet is loaded and this only answers for a
+ * page that loaded the element without the theme. Nothing enforces the agreement:
+ * `stylesheet-font-families` reads `.css`/`.scss`, and reaching a TS string literal
+ * would make it a JS parser, which its own header rules out. So it stays a step of
+ * the same edit, and `status/open-todos/adwaita-web.md` § "`<adw-source-view>` has
+ * no browser suite" is where the missing check is tracked.
  */
 const MONO_FONT =
-    "var(--monospace-font-family, 'Adwaita Mono', ui-monospace, 'SF Mono', 'Menlo', 'Consolas', monospace)";
+    "var(--monospace-font-family, 'Adwaita Mono', ui-monospace, 'SF Mono', 'Cascadia Code', 'Consolas', 'Menlo', monospace)";
 
 /** The CodeMirror EditorView theme mapping `.cm-*` chrome to Adwaita tokens. */
 export const adwaitaEditorTheme = EditorView.theme({

package/src/style-classes.spec.ts

@@ -45,8 +45,10 @@ const SHIPPED = { shipped: true } as const;
 const deprecated = (replacement: string) =>
     ({ shipped: false, reason: `deprecated upstream — use ${replacement}` }) as const;
 
-/** No counterpart in this renderer (yet), with the reason. */
-const unported = (reason: string) => ({ shipped: false, reason }) as const;
+// There is no "no counterpart in this renderer YET" form any more: every class this ledger
+// documents either ships a rule or is deprecated upstream, the last of the unported ones
+// (`.inline`) becoming a rule with `<gtk-text-view>` and `<gtk-search-bar>`. An entry that
+// does need one gets its own form back, with the reason it has no rule.
 
 /**
  * Every class `style-classes.md` documents, and what this package does about it.
@@ -117,12 +119,11 @@ export const DOCUMENTED_STYLE_CLASSES: Record<string, { shipped: boolean; reason
     // Development window
     devel: SHIPPED,
     // Inline
-    inline: unported(
-        'applies to GtkSearchBar, AdwTabBar and GtkTextView. This renderer ports none of ' +
-            'the three — <adw-tab-view> is the tab CONTENT, not AdwTabBar — and upstream ' +
-            'excludes GtkSourceView, which is the one text widget here (<adw-source-view>). ' +
-            'The class ships with the first of those three widgets, not before.',
-    ),
+    // SHIPPED since `<gtk-text-view>` and `<gtk-search-bar>` arrived: upstream applies
+    // `.inline` to GtkTextView (`_views.scss:31-36`) and to GtkSearchBar
+    // (`_toolbars.scss:156-158`), and both elements carry the rule in `scss/_text.scss` and
+    // `scss/_search_bar.scss`. AdwTabBar and GtkSourceView still have no counterpart here.
+    inline: SHIPPED,
     // Undershoot indicators
     'undershoot-top': SHIPPED,
     'undershoot-bottom': SHIPPED,