@gjsify/adwaita-web 0.43.0 → 0.44.0

package/README.md

@@ -53,6 +53,33 @@ Vite preset (or any Vite/bundler setup). Type declarations are shipped
 pre-built at `lib/types/index.d.ts`, so `gjsify tsc` consumers resolve the
 package's types without compiling its source.
 
+## Slots are live
+
+These are light-DOM custom elements, so `slot="…"` is emulated rather than native
+(see [ADR 0010](../../../docs/adr/0010-adwaita-web-style-isolation.md) for why the
+package stays out of the shadow DOM). The emulation is **live**: a child appended
+after the element is in the document lands in the same internal box as the
+identical child written in the markup.
+
+```typescript
+const row = document.querySelector('adw-action-row')!;
+const toggle = document.createElement('adw-switch');
+toggle.setAttribute('slot', 'suffix');
+row.append(toggle); // lands in the suffix section, exactly as a declared one does
+```
+
+Two limits are worth knowing:
+
+- **Append, not reorder.** A late child goes to the end of its slot's box. Once a
+  child has been adopted it is no longer a child of the host, so
+  `host.insertBefore(next, adopted)` throws in the DOM before this package sees
+  it — reorder inside the box you were handed (`row.prefixSection`,
+  `view.topBar`, …). Native `<slot>` is what would lift this, and it is part of
+  the shadow-DOM path ADR 0010 defers.
+- **An unknown slot name is assigned nowhere**, as in the native algorithm: a
+  `slot="sufix"` typo stays where you put it instead of quietly becoming default
+  content in the wrong box.
+
 ## Shared behaviour (`@gjsify/adwaita-core`)
 
 The widget *behaviour* — as opposed to the DOM rendering — comes from

package/lib/types/adw-alert-dialog.spec.d.ts

@@ -0,0 +1 @@
+export declare const AdwAlertDialogTest: () => Promise<void>;

package/lib/types/elements/adw-alert-dialog.d.ts

@@ -31,6 +31,12 @@ export declare class AdwAlertDialog extends HTMLElement {
     set body(value: string);
     get open(): boolean;
     set open(value: boolean);
+    /** Whether {@link heading} is read as markup rather than plain text. */
+    get headingUseMarkup(): boolean;
+    set headingUseMarkup(value: boolean);
+    /** Whether {@link body} is read as markup rather than plain text. */
+    get bodyUseMarkup(): boolean;
+    set bodyUseMarkup(value: boolean);
     /** Whether to prefer horizontal button layout when the buttons fit. */
     get preferWideLayout(): boolean;
     set preferWideLayout(value: boolean);
@@ -41,6 +47,12 @@ export declare class AdwAlertDialog extends HTMLElement {
     get closeResponse(): string;
     set closeResponse(value: string);
     connectedCallback(): void;
+    /**
+     * Take one declared `<adw-alert-response>` as a response. An entry with no `id` is
+     * skipped rather than given a generated one: the id is what `response` events carry, so
+     * inventing one would hand the consumer a name it never wrote.
+     */
+    private _adoptResponse;
     attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
     /** Present the dialog. `parent` is accepted for API parity; unused. */
     present(_parent?: unknown): void;

package/lib/types/elements/adw-entry-row.d.ts

@@ -16,8 +16,11 @@ export declare class AdwEntryRow extends HTMLElement {
     protected _prefixes: HTMLDivElement;
     protected _suffixes: HTMLDivElement;
     protected _initialized: boolean;
-    /** Light-DOM children captured at build time, adopted after `_onConnected`. */
-    private _authored;
+    /**
+     * The two slots, installed after `_onConnected` rather than inside `_build`: the order
+     * IS the contract — see the `install` call in `connectedCallback`.
+     */
+    private _slots;
     private _lastText;
     private _lastLength;
     static get observedAttributes(): string[];
@@ -76,11 +79,6 @@ export declare class AdwEntryRow extends HTMLElement {
     /** Subclass hook: runs after the DOM exists and the state is seeded, before the first render. */
     protected _onConnected(): void;
     private _build;
-    /**
-     * Re-home the children the author wrote. libadwaita's buildable maps an untyped
-     * `<child>` to a suffix; `slot="prefix"` is the web spelling of `type="prefix"`.
-     */
-    private _adoptAuthored;
     /**
      * `pressed_cb`: a click landing on the row, the editable area, the indicator or
      * either affordance box grabs focus; anything else (a suffix control, the apply

package/lib/types/elements/adw-header-bar.d.ts

@@ -26,5 +26,12 @@ export declare class AdwHeaderBar extends HTMLElement {
      * is bound to the property and re-renders on every change.
      */
     attributeChangedCallback(): void;
+    /**
+     * Give the centre up to a title-widget. `adw_header_bar_set_title_widget` destroys the
+     * derived `AdwWindowTitle` rather than stacking the two, so the late case has to remove
+     * it too — a bar showing both would be a shape neither GTK nor the declared markup can
+     * produce.
+     */
+    private _dropDerivedTitle;
     private _renderTitle;
 }

package/lib/types/elements/adw-navigation-split-view.d.ts

@@ -45,6 +45,15 @@ export declare class AdwNavigationSplitView extends HTMLElement {
     pop(): NavigationActionResult;
     connectedCallback(): void;
     private _buildOnce;
+    /**
+     * Mount whatever a pane box currently HOLDS into the state — `null` while it is empty.
+     *
+     * Re-mounting an unchanged pane re-emits the plan, because the state compares the page
+     * ref by identity. Both subscribers are idempotent reflections (an attribute and a
+     * class list), so a second child in the same pane costs a repaint decision and never a
+     * navigation event.
+     */
+    private _mountPane;
     /** `Adw.NavigationPage:tag` off the slotted pane, or `null` when untagged. */
     private _tagOf;
     /**

package/lib/types/elements/adw-preferences-group.d.ts

@@ -5,6 +5,12 @@ export declare class AdwPreferencesGroup extends HTMLElement {
     private _suffixEl;
     private _listboxEl;
     private _initialized;
+    /**
+     * Watches the two BOXES, not the host: the routing of a host child is
+     * `src/slotted-children.ts`'s job now, and what is left here is the header derivation,
+     * whose inputs are the row count and whether a suffix exists. A removal straight out of
+     * the listbox changes both and reaches no other callback.
+     */
     private _observer;
     static get observedAttributes(): string[];
     get description(): string;
@@ -13,10 +19,11 @@ export declare class AdwPreferencesGroup extends HTMLElement {
      * `adw_preferences_group_add`: a row goes into the boxed list, a `header-suffix`
      * child into the header.
      *
-     * Exposed as a method AND wired to a `MutationObserver` on the host, because both
-     * spellings occur — `group.addRow(row)` in code, `group.append(row)` from a
-     * framework's rendering — and a bare child of the host would sit outside the card,
-     * invisible to the row count that decides whether the card is painted at all.
+     * Kept as a method as well as a slot, because both spellings occur —
+     * `group.addRow(row)` in code, `group.append(row)` from a framework's rendering — and a
+     * bare child of the host would sit outside the card, invisible to the row count that
+     * decides whether the card is painted at all. The `append` spelling is routed by
+     * `src/slotted-children.ts`, which every other slotted element now shares.
      */
     addRow(child: Node): void;
     /**
@@ -29,13 +36,15 @@ export declare class AdwPreferencesGroup extends HTMLElement {
     disconnectedCallback(): void;
     attributeChangedCallback(): void;
     /**
-     * Adopt children appended to the HOST after the subtree was built, so
-     * `group.append(row)` behaves like `adw_preferences_group_add`.
+     * Re-derive the header whenever the two boxes change, in EITHER direction.
      *
      * C gets this for free: `gtk_widget_observe_children` on the listbox drives
-     * `update_listbox_visibility` through `items-changed`. A DOM element needs the
-     * observer for the same rule to hold over time rather than only at connect.
+     * `update_listbox_visibility` through `items-changed`. A DOM element needs the observer
+     * for the same rule to hold over time rather than only at connect. Adoption is not what
+     * this watches — a row appended to the host reaches the listbox through the shared slot
+     * routing, and lands here as the listbox record it causes. A row REMOVED straight out
+     * of the listbox reaches no other callback at all, and it still changes the row count.
      */
-    private _observeHost;
+    private _observeBoxes;
     private _renderHeader;
 }

package/lib/types/slotted-children.d.ts

@@ -0,0 +1,65 @@
+export interface AdwSlotClaim {
+    /** The `slot="…"` value claimed. Omit for the DEFAULT slot — everything else. */
+    readonly name?: string;
+    /**
+     * Claim by NODE as well as by slot name, for the typed-child spelling
+     * (`<adw-alert-response>` IS the slot) and for a default that takes only some node
+     * kinds (`<adw-entry-row>` adopts elements and drops stray whitespace, as GtkBuildable
+     * does). Tried after an explicit `slot=` name and before the default, so a claim can
+     * never swallow a child that named a different slot.
+     */
+    readonly claims?: (node: Node) => boolean;
+}
+/** A destination that RE-HOMES what it claims — the ordinary slot. */
+export interface AdwSlotInto extends AdwSlotClaim {
+    readonly into: HTMLElement;
+}
+/**
+ * A slot whose child is consumed by a CALL rather than by a move: either data —
+ * `<adw-alert-response id="ok">` is read for its id, label and appearance and then gone,
+ * exactly as GtkBuilder leaves nothing of a `<responses>` entry in the widget tree — or a
+ * widget whose insertion rule is the element's own (`addPrefix` PREPENDS, mirroring
+ * `gtk_box_prepend`). A node the call did not move out of the host is dropped, so a
+ * data-only child cannot linger as a stray sibling of the internal structure.
+ */
+export interface AdwSlotConsume extends AdwSlotClaim {
+    readonly consume: (node: Node) => void;
+}
+export type AdwSlot = AdwSlotInto | AdwSlotConsume;
+export interface AdwSlottedChildren {
+    /** The declared slots, so a driver can probe them without a hand-written ledger. */
+    readonly slots: readonly AdwSlot[];
+    /**
+     * Route the host's CURRENT children into their slots, then make `structure` the
+     * host's own children, then stay live.
+     *
+     * The three steps are one call because their ORDER is the invariant: the author's
+     * children have to leave the host before it is emptied, or `replaceChildren` destroys
+     * them — the bug `<adw-entry-row>` records above its own `_authored` snapshot. Passing
+     * `structure` here also means the set this module must never route is DERIVED from the
+     * call that installs it, rather than a second list to keep in sync.
+     *
+     * Call once per built subtree; a second call replaces the observer rather than
+     * stacking one.
+     */
+    install(...structure: readonly Node[]): void;
+    /** The slot `node` belongs to, or `null` when none claims it. */
+    slotFor(node: Node): AdwSlot | null;
+}
+/**
+ * The slot binding `host` installed, if it has one.
+ *
+ * This is how `slotted-children.spec.ts` drives EVERY registered element rather than a
+ * list of the ones someone remembered: an element that binds a slot enrols itself in the
+ * placement driver, and one that stops binding drops out of it visibly.
+ */
+export declare function slottedChildrenOf(host: Element): AdwSlottedChildren | undefined;
+/**
+ * Bind `host`'s light-DOM children to `slots`.
+ *
+ * `onAdopt` fires for a child adopted AFTER {@link AdwSlottedChildren.install} and not
+ * during it: the install pass IS the element's own build, which seeds its state on the
+ * next line with everything that landed, so firing there would make every element's build
+ * order depend on how many children the author wrote.
+ */
+export declare function bindSlottedChildren(host: HTMLElement, slots: readonly AdwSlot[], onAdopt?: (node: Node, slot: AdwSlot) => void): AdwSlottedChildren;

package/lib/types/slotted-children.spec.d.ts

@@ -0,0 +1 @@
+export declare const AdwSlottedChildrenTest: () => Promise<void>;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/adwaita-web",
-    "version": "0.43.0",
+    "version": "0.44.0",
     "description": "Adwaita/Libadwaita web components for browser targets",
     "type": "module",
     "main": "./src/index.ts",
@@ -45,14 +45,14 @@
         "@codemirror/language": "^6.12.4",
         "@codemirror/state": "^6.7.0",
         "@codemirror/view": "^6.43.4",
-        "@gjsify/adwaita-core": "^0.43.0",
-        "@gjsify/adwaita-fonts": "^0.43.0",
-        "@gjsify/adwaita-icons": "^0.43.0",
+        "@gjsify/adwaita-core": "^0.44.0",
+        "@gjsify/adwaita-fonts": "^0.44.0",
+        "@gjsify/adwaita-icons": "^0.44.0",
         "@lezer/highlight": "^1.2.3"
     },
     "devDependencies": {
-        "@gjsify/cli": "^0.43.0",
-        "@gjsify/unit": "^0.43.0",
+        "@gjsify/cli": "^0.44.0",
+        "@gjsify/unit": "^0.44.0",
         "sass": "^1.101.0",
         "typescript": "^6.0.3"
     },

package/src/adw-alert-dialog.spec.ts

@@ -0,0 +1,146 @@
+// <adw-alert-dialog> against `Adw.AlertDialog`'s own property list.
+//
+// This element shipped with FOUR of its eight GIR properties reachable from markup —
+// `heading`, `body`, `open` (a web convention with no GIR counterpart) and
+// `prefer-wide-layout`. `close-response` and `default-response` existed as JS
+// properties but no attribute fed them, and `heading-use-markup`/`body-use-markup`
+// were absent entirely. The website's generated widget table read
+// `observedAttributes` and truthfully reported "takes 4 attributes", which is how the
+// gap became visible: the DOC was right and the ELEMENT was short.
+//
+// The markup pair defaults to FALSE here and in libadwaita alike — unlike
+// `Adw.Banner:use-markup`, whose C default is TRUE and which `adw-banner.ts` therefore
+// departs from on purpose. So these vectors pin a MATCH, not a departure, and the
+// negative case is the one that matters: tags must show literally until asked for.
+import { describe, expect, it } from '@gjsify/unit';
+
+import type { AdwAlertDialog } from './elements/adw-alert-dialog.js';
+
+/** Mount via `setAttribute` so an attribute value's exact text survives. */
+function mount(attributes: Record<string, string> = {}): { el: AdwAlertDialog; host: HTMLElement } {
+    const host = document.createElement('div');
+    document.body.appendChild(host);
+    const el = document.createElement('adw-alert-dialog') as AdwAlertDialog;
+    for (const [name, value] of Object.entries(attributes)) el.setAttribute(name, value);
+    host.appendChild(el);
+    return { el, host };
+}
+
+const headingEl = (el: AdwAlertDialog): HTMLElement => el.querySelector('.adw-alert-dialog-heading') as HTMLElement;
+const bodyEl = (el: AdwAlertDialog): HTMLElement => el.querySelector('.adw-alert-dialog-body') as HTMLElement;
+
+export const AdwAlertDialogTest = async () => {
+    await describe('adw-alert-dialog observes every Adw.AlertDialog property it can render', async () => {
+        // Named rather than counted: a count passes again the moment someone swaps one
+        // attribute for another, which is the drift this file exists to catch.
+        for (const name of [
+            'heading',
+            'body',
+            'heading-use-markup',
+            'body-use-markup',
+            'close-response',
+            'default-response',
+            'prefer-wide-layout',
+        ]) {
+            await it(`observes \`${name}\``, () => {
+                expect(
+                    (
+                        customElements.get('adw-alert-dialog') as typeof HTMLElement & {
+                            observedAttributes: string[];
+                        }
+                    ).observedAttributes,
+                ).toContain(name);
+            });
+        }
+    });
+
+    await describe('adw-alert-dialog markup is opt-in, matching the libadwaita default', async () => {
+        await it('a heading with tags shows them literally by default', () => {
+            const { el, host } = mount({ heading: '<b>Delete</b> file?' });
+            expect(headingEl(el).textContent).toBe('<b>Delete</b> file?');
+            expect(headingEl(el).querySelector('b')).toBe(null);
+            host.remove();
+        });
+
+        await it('heading-use-markup renders it, which is the author asserting it is trusted', () => {
+            const { el, host } = mount({ heading: '<b>Delete</b> file?', 'heading-use-markup': '' });
+            expect(headingEl(el).querySelector('b')?.textContent).toBe('Delete');
+            host.remove();
+        });
+
+        await it('a body with tags shows them literally by default', () => {
+            const { el, host } = mount({ body: 'Really delete <i>notes.txt</i>?' });
+            expect(bodyEl(el).textContent).toBe('Really delete <i>notes.txt</i>?');
+            expect(bodyEl(el).querySelector('i')).toBe(null);
+            host.remove();
+        });
+
+        await it('body-use-markup renders it', () => {
+            const { el, host } = mount({ body: 'Really delete <i>notes.txt</i>?', 'body-use-markup': '' });
+            expect(bodyEl(el).querySelector('i')?.textContent).toBe('notes.txt');
+            host.remove();
+        });
+
+        await it('toggling the attribute off returns to text', () => {
+            const { el, host } = mount({ heading: '<b>Delete</b>', 'heading-use-markup': '' });
+            el.headingUseMarkup = false;
+            expect(headingEl(el).textContent).toBe('<b>Delete</b>');
+            expect(headingEl(el).querySelector('b')).toBe(null);
+            host.remove();
+        });
+    });
+
+    await describe('adw-alert-dialog response IDs are reachable from markup', async () => {
+        await it('close-response defaults to `close`, as in Adw.AlertDialog', () => {
+            const { el, host } = mount();
+            expect(el.closeResponse).toBe('close');
+            host.remove();
+        });
+
+        await it('the attribute feeds the headless model', () => {
+            const { el, host } = mount({ 'close-response': 'cancel' });
+            expect(el.closeResponse).toBe('cancel');
+            host.remove();
+        });
+
+        await it('default-response defaults to null and the attribute sets it', () => {
+            const { el, host } = mount();
+            expect(el.defaultResponse).toBe(null);
+            el.setAttribute('default-response', 'delete');
+            expect(el.defaultResponse).toBe('delete');
+            host.remove();
+        });
+
+        await it('removing default-response clears it', () => {
+            const { el, host } = mount({ 'default-response': 'delete' });
+            el.removeAttribute('default-response');
+            expect(el.defaultResponse).toBe(null);
+            host.remove();
+        });
+
+        await it('a dismissal emits the close response the attribute named', () => {
+            // The scrim click, not `open = false`. `_dismiss()` SETS `open = false` and
+            // then emits, so the property is the lower-level state change and driving it
+            // directly would assert a contract this element does not have.
+            const { el, host } = mount({ 'close-response': 'cancel', open: '' });
+            let seen: string | null = null;
+            el.addEventListener('response', (event) => {
+                seen = (event as CustomEvent<{ response: string }>).detail.response;
+            });
+            (el.querySelector('.adw-alert-dialog-scrim') as HTMLElement).click();
+            expect(seen).toBe('cancel');
+            expect(el.open).toBe(false);
+            host.remove();
+        });
+
+        await it('removing close-response keeps the model value, unlike default-response', () => {
+            // An ASYMMETRY worth pinning rather than discovering: `close-response` has a
+            // non-null GIR default (`close`), so an absent attribute means "leave the
+            // model alone", while `default-response` defaults to null and clears.
+            const { el, host } = mount({ 'close-response': 'cancel' });
+            el.removeAttribute('close-response');
+            expect(el.closeResponse).toBe('cancel');
+            host.remove();
+        });
+    });
+};

package/src/adw-header-bar.spec.ts

@@ -68,8 +68,10 @@ function mountSizedHeaderBar(width: number): HTMLElement {
             bar.appendChild(button);
         }
     }
-    // Appended LAST: the sections are built in `connectedCallback`, so the slotted
-    // children have to be in place before the bar enters the document.
+    // The bar enters the document last, so this geometry is measured on the PARSE-TIME
+    // path. It used to be the only path that worked — the sections were built in
+    // `connectedCallback` from a one-shot snapshot — and that is no longer a constraint:
+    // `slotted-children.spec.ts` requires the appended path to place a child identically.
     host.appendChild(bar);
     return bar;
 }

package/src/elements/adw-action-row.ts

@@ -17,6 +17,7 @@
 import { ActionRowState } from '@gjsify/adwaita-core';
 
 import { bindEmptySections } from '../empty-sections.js';
+import { bindSlottedChildren } from '../slotted-children.js';
 import { type AdwRowActivation, attachRowActivation } from './row-activation.js';
 
 /**
@@ -90,12 +91,8 @@ export class AdwActionRow extends HTMLElement {
         }
         this._initialized = true;
 
-        const prefixChildren = Array.from(this.querySelectorAll(':scope > [slot="prefix"]'));
-        const suffixChildren = Array.from(this.querySelectorAll(':scope > [slot="suffix"]'));
-
         this._prefixEl = document.createElement('div');
         this._prefixEl.className = 'adw-action-row-prefix';
-        for (const child of prefixChildren) this._prefixEl.appendChild(child);
 
         const textEl = document.createElement('div');
         textEl.className = 'adw-action-row-text';
@@ -107,9 +104,14 @@ export class AdwActionRow extends HTMLElement {
 
         this._suffixEl = document.createElement('div');
         this._suffixEl.className = 'adw-action-row-suffix';
-        for (const child of suffixChildren) this._suffixEl.appendChild(child);
 
-        this.replaceChildren(this._prefixEl, textEl, this._suffixEl);
+        // The two slots stay LIVE — a control appended with `slot="suffix"` after connect
+        // has to land in the same section the declared one does, which a snapshot taken
+        // here cannot do. `src/slotted-children.ts` carries the incident.
+        bindSlottedChildren(this, [
+            { name: 'prefix', into: this._prefixEl },
+            { name: 'suffix', into: this._suffixEl },
+        ]).install(this._prefixEl, textEl, this._suffixEl);
         // `_render` runs from `attributeChangedCallback`, which a control appended into
         // `suffixSection` never triggers — the section stayed `hidden` and the control
         // measured 0x0. The observer is what keeps the two sections in step with what