@gjsify/adwaita-web 0.43.0 → 0.44.0

package/src/elements/adw-preferences-group.ts

@@ -24,6 +24,8 @@
 
 import { derivePreferencesGroupHeader } from '@gjsify/adwaita-core';
 
+import { bindSlottedChildren } from '../slotted-children.js';
+
 /** A child that asked to sit in the header rather than in the boxed list. */
 function isHeaderSuffix(node: Node): boolean {
     return node instanceof Element && node.getAttribute('slot') === 'header-suffix';
@@ -36,6 +38,12 @@ export class AdwPreferencesGroup extends HTMLElement {
     private _suffixEl!: HTMLDivElement;
     private _listboxEl!: HTMLDivElement;
     private _initialized = false;
+    /**
+     * 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: MutationObserver | null = null;
 
     static get observedAttributes() {
@@ -55,10 +63,11 @@ export 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 {
         if (isHeaderSuffix(child)) this._suffixEl.appendChild(child);
@@ -81,15 +90,11 @@ export class AdwPreferencesGroup extends HTMLElement {
 
     connectedCallback() {
         if (this._initialized) {
-            this._observeHost();
+            this._observeBoxes();
             return;
         }
         this._initialized = true;
 
-        const children = Array.from(this.childNodes);
-        const suffixChildren = children.filter(isHeaderSuffix);
-        const rowChildren = children.filter((child) => !suffixChildren.includes(child));
-
         this._headerEl = document.createElement('div');
         this._headerEl.className = 'adw-preferences-group-header';
 
@@ -106,26 +111,31 @@ export class AdwPreferencesGroup extends HTMLElement {
 
         this._suffixEl = document.createElement('div');
         this._suffixEl.className = 'adw-preferences-group-suffix';
-        for (const child of suffixChildren) this._suffixEl.appendChild(child);
 
         this._headerEl.append(labels, this._suffixEl);
 
         this._listboxEl = document.createElement('div');
         this._listboxEl.className = 'adw-preferences-group-listbox';
-        for (const child of rowChildren) this._listboxEl.appendChild(child);
 
-        this.replaceChildren(this._headerEl, this._listboxEl);
+        bindSlottedChildren(
+            this,
+            [{ name: 'header-suffix', into: this._suffixEl }, { into: this._listboxEl }],
+            // Redundant while this group is connected — the listbox record covers it — and
+            // the only thing that covers it while it is DETACHED, where `_observeBoxes` is
+            // deliberately off. A row appended to a parked group must be right when it
+            // comes back, not one derivation behind.
+            () => this._renderHeader(),
+        ).install(this._headerEl, this._listboxEl);
         // adw-preferences-group.c:319 — GTK_ACCESSIBLE_ROLE_GROUP. A GROUP, not a list:
         // that is why the rows inside carry no `listitem` role, which outside a list
         // would be worse than none.
         this.setAttribute('role', 'group');
 
-        this._renderHeader();
-        this._observeHost();
+        this._observeBoxes();
     }
 
     disconnectedCallback() {
-        // The observer holds this element alive through the host node; drop it
+        // The observer holds this element alive through the boxes it watches; drop it
         // with the connection that created it, not at some later "cleanup".
         this._observer?.disconnect();
         this._observer = null;
@@ -136,35 +146,26 @@ export class AdwPreferencesGroup extends HTMLElement {
     }
 
     /**
-     * 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(): void {
+    private _observeBoxes(): void {
         if (this._observer) return;
-        this._observer = new MutationObserver((records) => {
-            for (const record of records) {
-                // Only the HOST's own children need re-homing. Records from the listbox are
-                // the CONSEQUENCE of that move; re-adopting them would append each row a
-                // second time and reorder the list.
-                if (record.target !== this) continue;
-                for (const node of record.addedNodes) {
-                    if (!(node instanceof Element)) continue;
-                    if (node === this._headerEl || node === this._listboxEl) continue;
-                    this.addRow(node);
-                }
-            }
-            // A removal straight out of the listbox still changes the row count.
-            this._renderHeader();
-        });
-        this._observer.observe(this, { childList: true });
+        this._observer = new MutationObserver(() => this._renderHeader());
         this._observer.observe(this._listboxEl, { childList: true });
         // The suffix too: `hasHeaderSuffix` is an INPUT to the header derivation, so a
         // suffix appended after connect left the header hidden on a group with no title.
         this._observer.observe(this._suffixEl, { childList: true });
+        // Arming and deriving are ONE act, as in `src/empty-sections.ts`: a group that was
+        // parked, filled and re-attached would otherwise come back showing the header state
+        // it had when it left.
+        this._renderHeader();
     }
 
     private _renderHeader() {

package/src/elements/adw-status-page.ts

@@ -10,6 +10,7 @@
 import { stringIsNotEmpty } from '@gjsify/adwaita-core';
 
 import { bindEmptySections } from '../empty-sections.js';
+import { bindSlottedChildren } from '../slotted-children.js';
 import { type AdwIcon, createAdwIcon } from './adw-icon.js';
 
 export class AdwStatusPage extends HTMLElement {
@@ -27,8 +28,6 @@ export class AdwStatusPage extends HTMLElement {
         if (this._initialized) return;
         this._initialized = true;
 
-        const children = Array.from(this.childNodes);
-
         this._iconEl = createAdwIcon(null, 'adw-status-page-icon');
 
         this._titleEl = document.createElement('span');
@@ -39,9 +38,16 @@ export class AdwStatusPage extends HTMLElement {
 
         this._childEl = document.createElement('div');
         this._childEl.className = 'adw-status-page-child';
-        for (const child of children) this._childEl.appendChild(child);
 
-        this.replaceChildren(this._iconEl, this._titleEl, this._descEl, this._childEl);
+        // `Adw.StatusPage:child` is a property, so the action a status page offers can be
+        // set at any point — a button appended after connect has to land in the child box,
+        // not beside it. `src/slotted-children.ts` has the incident.
+        bindSlottedChildren(this, [{ into: this._childEl }]).install(
+            this._iconEl,
+            this._titleEl,
+            this._descEl,
+            this._childEl,
+        );
         // `_render` only ever runs from `attributeChangedCallback`, which an action
         // appended into the child slot after connect does not trigger.
         bindEmptySections(this._childEl);

package/src/elements/adw-toast-overlay.ts

@@ -19,6 +19,7 @@
 
 import { AdwToast, AdwToastQueue } from '@gjsify/adwaita-core';
 
+import { bindSlottedChildren } from '../slotted-children.js';
 import { createAdwIcon } from './adw-icon.js';
 import type { ToastScheduler, ToastTimerHandle } from '@gjsify/adwaita-core';
 
@@ -86,16 +87,17 @@ export class AdwToastOverlay extends HTMLElement {
         if (this._initialized) return;
         this._initialized = true;
 
-        // The declared children become the wrapped content (Adw.ToastOverlay:child);
-        // the toast container is layered over the bottom edge.
+        // The children become the wrapped content (Adw.ToastOverlay:child); the toast
+        // container is layered over the bottom edge. LIVE, because the overlay is the
+        // outermost widget of a window and the app it wraps is very often appended to it
+        // after it exists. `src/slotted-children.ts` has the incident.
         const content = document.createElement('div');
         content.className = 'adw-toast-overlay-content';
-        for (const child of Array.from(this.childNodes)) content.appendChild(child);
 
         this._toasts = document.createElement('div');
         this._toasts.className = 'adw-toast-overlay-toasts';
 
-        this.replaceChildren(content, this._toasts);
+        bindSlottedChildren(this, [{ into: content }]).install(content, this._toasts);
     }
 
     /**

package/src/elements/adw-toolbar-view.ts

@@ -32,6 +32,7 @@ import {
 } from '@gjsify/adwaita-core';
 import { bindEmptySections } from '../empty-sections.js';
 import { AdwScrollShading } from '../scroll-shading.js';
+import { bindSlottedChildren } from '../slotted-children.js';
 
 export class AdwToolbarView extends HTMLElement {
     private _topEl!: HTMLDivElement;
@@ -71,31 +72,35 @@ export class AdwToolbarView extends HTMLElement {
         if (!this._initialized) {
             this._initialized = true;
 
-            const topChildren = Array.from(this.querySelectorAll(':scope > [slot="top"]'));
-            const bottomChildren = Array.from(this.querySelectorAll(':scope > [slot="bottom"]'));
-            const contentChildren = Array.from(this.childNodes).filter(
-                (n) => !topChildren.includes(n as Element) && !bottomChildren.includes(n as Element),
-            );
-
             this._topEl = document.createElement('div');
             this._topEl.className = 'adw-toolbar-view-top';
-            for (const child of topChildren) this._topEl.appendChild(child);
 
             this._contentEl = document.createElement('div');
             this._contentEl.className = 'adw-toolbar-view-content';
-            for (const child of contentChildren) this._contentEl.appendChild(child);
 
             this._bottomEl = document.createElement('div');
             this._bottomEl.className = 'adw-toolbar-view-bottom';
-            for (const child of bottomChildren) this._bottomEl.appendChild(child);
+
+            // `topBar` invites an imperative append, and a DECLARED `slot="top"` bar has to
+            // reach the same box whenever it is written — including after connect, which a
+            // snapshot here cannot see. The unnamed slot is the content, the
+            // Adw.ToolbarView buildable default. `src/slotted-children.ts` has the incident.
+            bindSlottedChildren(this, [
+                { name: 'top', into: this._topEl },
+                { name: 'bottom', into: this._bottomEl },
+                { into: this._contentEl },
+            ]).install(this._topEl, this._contentEl, this._bottomEl);
 
             // A bar appended imperatively — which `topBar` invites — is a childList
             // change, not an attribute one, so the empty/non-empty decision cannot be a
             // one-shot read here. The ResizeObserver below then sees the bar go 0 → 48
             // and the undershoot classes follow on their own.
+            //
+            // AFTER the slot routing, and that order is load-bearing: this derives once
+            // SYNCHRONOUSLY, so on empty boxes it hides both and only un-hides them a
+            // microtask later — long after `_syncClasses` has measured a declared bar at
+            // `offsetHeight` 0 and dropped the undershoot classes for good.
             bindEmptySections(this._topEl, this._bottomEl);
-
-            this.replaceChildren(this._topEl, this._contentEl, this._bottomEl);
         }
 
         // `update_undershoots` runs from size_allocate, so the classes have to

package/src/slotted-children.spec.ts

@@ -0,0 +1,227 @@
+// Slot adoption, driven in both directions — declared at parse time and appended after
+// connect — and required to reach the SAME place.
+//
+// The invariant this file exists for is an EQUALITY, not a presence: "the child is
+// somewhere in the subtree" was true of the bug too. Before `src/slotted-children.ts` a
+// `slot="suffix"` control appended after connect stayed a direct child of the host,
+// beside the internal sections rather than inside one — still in the subtree, still
+// findable by `querySelector`, and laid out somewhere else entirely. So every assertion
+// below compares the declared placement against the appended one, box path AND index.
+//
+// The second half is DERIVED, for the reason `connect-lifecycle.spec.ts` gives about its
+// own driver: a per-widget slot spec is one more spec per widget to forget. It reads the
+// bindings back off the registered elements (`slottedChildrenOf`), so an element that
+// gains a slot enrols itself, and one that stops binding drops out of the driver visibly
+// instead of silently.
+import { describe, expect, it } from '@gjsify/unit';
+
+import * as adwaitaWeb from './index.js';
+import { bindSlottedChildren, slottedChildrenOf } from './slotted-children.js';
+
+/** One microtask checkpoint — where a MutationObserver callback lands. */
+const settle = () => Promise.resolve();
+
+/** A host mounted in the document, since adoption is only interesting where a widget is. */
+function mounted<T extends HTMLElement>(el: T): T {
+    document.body.appendChild(el);
+    return el;
+}
+
+/**
+ * WHERE inside `host` a node sits: the chain of boxes down to its parent, plus its index
+ * among that parent's child nodes.
+ *
+ * The index is half the point. Two children that both reached the right box in the wrong
+ * order share a path, and a driver that stopped at the path would call that agreement.
+ */
+function placement(host: Element, node: Node): string {
+    if (node.parentNode === null) return 'detached';
+    if (!host.contains(node)) return 'outside';
+    const steps: string[] = [];
+    for (let el = node.parentElement; el !== null && el !== host; el = el.parentElement) {
+        const classes = [...el.classList].sort().join('.');
+        steps.unshift(classes === '' ? el.localName : `${el.localName}.${classes}`);
+    }
+    const index = Array.from(node.parentNode.childNodes).indexOf(node as ChildNode);
+    return `${steps.join(' > ')}[${index}]`;
+}
+
+/** A probe carrying a slot name, or none at all for the default slot. */
+function probe(slot: string | undefined, id: string): HTMLElement {
+    const el = document.createElement('div');
+    if (slot !== undefined) el.setAttribute('slot', slot);
+    el.dataset.probe = id;
+    return el;
+}
+
+export const AdwSlottedChildrenTest = async () => {
+    await describe('bindSlottedChildren', async () => {
+        await it('routes the children it was installed over, in document order', async () => {
+            const host = mounted(document.createElement('div'));
+            const first = probe('side', 'a');
+            const second = probe(undefined, 'b');
+            const third = probe('side', 'c');
+            host.append(first, second, third);
+
+            const side = document.createElement('div');
+            side.className = 'side';
+            const body = document.createElement('div');
+            body.className = 'body';
+            bindSlottedChildren(host, [{ name: 'side', into: side }, { into: body }]).install(side, body);
+
+            const report = [first, second, third].map((el) => placement(host, el)).join(' | ');
+            host.remove();
+            expect(report).toBe('div.side[0] | div.body[0] | div.side[1]');
+        });
+
+        await it('routes a child APPENDED after install to the same box, at the next index', async () => {
+            const host = mounted(document.createElement('div'));
+            const declared = probe('side', 'a');
+            host.append(declared);
+
+            const side = document.createElement('div');
+            side.className = 'side';
+            bindSlottedChildren(host, [{ name: 'side', into: side }]).install(side);
+
+            const late = probe('side', 'b');
+            host.append(late);
+            await settle();
+
+            const report = `${placement(host, declared)} | ${placement(host, late)}`;
+            host.remove();
+            expect(report).toBe('div.side[0] | div.side[1]');
+        });
+
+        await it('leaves a child whose slot name nothing declares where the author put it', async () => {
+            const host = mounted(document.createElement('div'));
+            const side = document.createElement('div');
+            side.className = 'side';
+            // No default slot: with one, an unmatched NAME would silently become default
+            // content and render in the wrong box looking deliberate. The native assignment
+            // algorithm assigns it nowhere, and so does this.
+            bindSlottedChildren(host, [{ name: 'side', into: side }]).install(side);
+
+            const typo = probe('sied', 'a');
+            host.append(typo);
+            await settle();
+
+            const report = placement(host, typo);
+            host.remove();
+            expect(report).toBe('[1]');
+        });
+
+        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');
+            side.className = 'side';
+            bindSlottedChildren(host, [{ name: 'side', into: side }]).install(side);
+
+            const child = probe('side', 'a');
+            host.append(child);
+            await settle();
+            const first = `${placement(host, child)} n=${side.childElementCount}`;
+
+            child.remove();
+            await settle();
+            const gone = `${placement(host, child)} n=${side.childElementCount}`;
+
+            host.append(child);
+            await settle();
+            // n=1, not n=2: the node is MOVED back rather than copied, and the removal left
+            // no placeholder behind for it to be adopted alongside.
+            const again = `${placement(host, child)} n=${side.childElementCount}`;
+
+            host.remove();
+            expect(`${first} / ${gone} / ${again}`).toBe('div.side[0] n=1 / detached n=0 / div.side[0] n=1');
+        });
+
+        await it('hands a consumed child to the call and leaves nothing of it in the host', async () => {
+            const host = mounted(document.createElement('div'));
+            const taken: string[] = [];
+            const body = document.createElement('div');
+            body.className = 'body';
+            bindSlottedChildren(host, [
+                {
+                    claims: (node) => node instanceof Element && node.localName === 'meta',
+                    consume: (node) => taken.push((node as Element).getAttribute('name') ?? ''),
+                },
+                { into: body },
+            ]).install(body);
+
+            const data = document.createElement('meta');
+            data.setAttribute('name', 'late');
+            host.append(data);
+            await settle();
+
+            const report = `${taken.join(',')} | ${placement(host, data)} | body=${body.childElementCount}`;
+            host.remove();
+            expect(report).toBe('late | detached | body=0');
+        });
+    });
+
+    // Every registered element that binds a slot, both ways round. This is the driver the
+    // fix exists for: an element is asked for its own slots and then required to put a
+    // declared child and an appended one in the same place.
+    await describe('every slotted element adopts a late child where it adopts a declared one', async () => {
+        const tags: string[] = [];
+        for (const exported of Object.values(adwaitaWeb)) {
+            if (typeof exported !== 'function' || !(exported.prototype instanceof HTMLElement)) continue;
+            const tag = customElements.getName(exported as CustomElementConstructor);
+            if (tag !== null) tags.push(tag);
+        }
+        tags.sort();
+
+        /** The distinct slot names one element declares — `undefined` is its default slot. */
+        function slotNames(tag: string): Array<string | undefined> {
+            const el = mounted(document.createElement(tag));
+            const binding = slottedChildrenOf(el);
+            el.remove();
+            if (binding === undefined) return [];
+            const names = new Set<string | undefined>();
+            for (const slot of binding.slots) names.add(slot.name);
+            return [...names];
+        }
+
+        const slotted = tags.map((tag) => [tag, slotNames(tag)] as const).filter(([, names]) => names.length > 0);
+
+        await it('finds the elements that declare slots', () => {
+            // A driver that scans nothing passes vacuously and reports a green it never
+            // earned. A FLOOR, not an exact count: the point of deriving the list is that it
+            // grows without this file being edited.
+            expect(`slotted elements: ${slotted.length > 8}`).toBe('slotted elements: true');
+        });
+
+        for (const [tag, names] of slotted) {
+            for (const name of names) {
+                const label = name ?? '(default)';
+                await it(`<${tag}> slot="${label}"`, async () => {
+                    // TWO children per slot, so the comparison pins ORDER and not only the box.
+                    const declaredHost = document.createElement(tag);
+                    const declaredA = probe(name, 'a');
+                    const declaredB = probe(name, 'b');
+                    declaredHost.append(declaredA, declaredB);
+                    mounted(declaredHost);
+
+                    const lateHost = mounted(document.createElement(tag));
+                    const lateA = probe(name, 'a');
+                    const lateB = probe(name, 'b');
+                    lateHost.append(lateA);
+                    lateHost.append(lateB);
+                    await settle();
+
+                    const declared = [declaredA, declaredB].map((el) => placement(declaredHost, el)).join(' | ');
+                    const late = [lateA, lateB].map((el) => placement(lateHost, el)).join(' | ');
+                    // Measure, THEN tear down, THEN assert — the reason
+                    // `connect-lifecycle.spec.ts` gives: a host left on the page pushes every
+                    // later one down and turns one failure into a cascade naming the wrong
+                    // widget.
+                    declaredHost.remove();
+                    lateHost.remove();
+                    expect(`<${tag}> slot=${label} appended: ${late}`).toBe(
+                        `<${tag}> slot=${label} appended: ${declared}`,
+                    );
+                });
+            }
+        }
+    });
+};