@gjsify/adwaita-web 0.42.0 → 0.44.0

package/src/elements/adw-navigation-split-view.ts

@@ -36,6 +36,7 @@ import {
 } from '@gjsify/adwaita-core';
 
 import { bindBreakpointSetter } from '../breakpoints.js';
+import { bindSlottedChildren } from '../slotted-children.js';
 
 /** Detail of the `navigation-push` / `navigation-pop` delegation event. */
 export interface NavigationDelegateDetail {
@@ -142,18 +143,24 @@ export class AdwNavigationSplitView extends HTMLElement {
         if (this._initialized) return;
         this._initialized = true;
 
-        const sidebarChildren = Array.from(this.querySelectorAll(':scope > [slot="sidebar"]'));
-        const contentChildren = Array.from(this.querySelectorAll(':scope > [slot="content"]'));
-
         this._sidebarEl = document.createElement('div');
         this._sidebarEl.className = 'adw-nsv-sidebar';
-        for (const child of sidebarChildren) this._sidebarEl.appendChild(child);
 
         this._contentEl = document.createElement('div');
         this._contentEl.className = 'adw-nsv-content';
-        for (const child of contentChildren) this._contentEl.appendChild(child);
 
-        this.replaceChildren(this._sidebarEl, this._contentEl);
+        // Both panes stay LIVE. `adw_navigation_split_view_set_sidebar` is a property
+        // setter, callable whenever, so a pane appended after connect has to reach the
+        // pane box AND the state that decides the stack — which is what `_mountPane` does
+        // on the way. `src/slotted-children.ts` has the incident.
+        bindSlottedChildren(
+            this,
+            [
+                { name: 'sidebar', into: this._sidebarEl },
+                { name: 'content', into: this._contentEl },
+            ],
+            (_node, slot) => this._mountPane(slot.name === 'sidebar' ? 'sidebar' : 'content'),
+        ).install(this._sidebarEl, this._contentEl);
 
         // Parse-time attributes are the CONSTRUCTION properties, as in the overlay view:
         // applying them as sequential setters emits a transition for a state the markup
@@ -175,14 +182,30 @@ export class AdwNavigationSplitView extends HTMLElement {
         // Which children EXIST decides the stack, so the panes are mounted into the state
         // and not merely into the DOM — a lone child stays visible whatever
         // `show-content` says, which two CSS classes cannot express.
-        this._state.setSidebar(sidebarChildren.length > 0 ? { tag: this._tagOf(sidebarChildren) } : null);
-        this._state.setContent(contentChildren.length > 0 ? { tag: this._tagOf(contentChildren) } : null);
+        this._mountPane('sidebar');
+        this._mountPane('content');
         this._state.subscribe(() => {
             this._reflectShowContent();
             this._syncClasses();
         });
     }
 
+    /**
+     * 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(pane: 'sidebar' | 'content'): void {
+        const box = pane === 'sidebar' ? this._sidebarEl : this._contentEl;
+        const children = Array.from(box.children);
+        const page = children.length > 0 ? { tag: this._tagOf(children) } : null;
+        if (pane === 'sidebar') this._state.setSidebar(page);
+        else this._state.setContent(page);
+    }
+
     /** `Adw.NavigationPage:tag` off the slotted pane, or `null` when untagged. */
     private _tagOf(children: readonly Element[]): string | null {
         for (const child of children) {

package/src/elements/adw-overlay-split-view.ts

@@ -26,6 +26,7 @@ import {
 } from '@gjsify/adwaita-core';
 
 import { bindBreakpointSetter } from '../breakpoints.js';
+import { bindSlottedChildren } from '../slotted-children.js';
 
 /**
  * The reveal spring, as a CSS-timed animator: libadwaita animates with a spring
@@ -173,28 +174,26 @@ export class AdwOverlaySplitView extends HTMLElement {
         if (this._initialized) return;
         this._initialized = true;
 
-        const sidebarChildren = Array.from(this.querySelectorAll('[slot="sidebar"]'));
-        const contentChildren = Array.from(this.querySelectorAll('[slot="content"]'));
-        const unslotted = Array.from(this.childNodes).filter(
-            (n) => !sidebarChildren.includes(n as Element) && !contentChildren.includes(n as Element),
-        );
-
-        this.replaceChildren();
-
         this._sidebarEl = document.createElement('div');
         this._sidebarEl.className = 'adw-osv-sidebar';
-        sidebarChildren.forEach((c) => this._sidebarEl.appendChild(c));
 
         this._contentEl = document.createElement('div');
         this._contentEl.className = 'adw-osv-content';
-        contentChildren.forEach((c) => this._contentEl.appendChild(c));
-        unslotted.forEach((c) => this._contentEl.appendChild(c));
 
         this._backdropEl = document.createElement('div');
         this._backdropEl.className = 'adw-osv-backdrop';
         this._backdropEl.addEventListener('click', () => this.hideSidebar());
 
-        this.append(this._sidebarEl, this._contentEl, this._backdropEl);
+        // Both panes stay LIVE, and the unnamed slot is the content — the
+        // Adw.OverlaySplitView buildable default. `src/slotted-children.ts` has the
+        // incident. The routing also stops at the DIRECT children, which the two
+        // selectors here did not: `[slot="sidebar"]` matched at any depth, so a nested
+        // split view's sidebar was stolen into the outer one's pane.
+        bindSlottedChildren(this, [
+            { name: 'sidebar', into: this._sidebarEl },
+            { name: 'content', into: this._contentEl },
+            { into: this._contentEl },
+        ]).install(this._sidebarEl, this._contentEl, this._backdropEl);
 
         // The attributes present at parse time ARE the construction options —
         // `Adw.OverlaySplitView` is built with its properties, not built and then

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

@@ -50,6 +50,7 @@
 
 import type { PreferencesSearchResult, SearchPreferencesOptions } from '@gjsify/adwaita-core';
 import { searchPreferencesDom } from '../preferences-search.js';
+import { bindSlottedChildren } from '../slotted-children.js';
 import { AdwModalSurface } from './modal-surface.js';
 
 const DEFAULT_CONTENT_WIDTH = 640;
@@ -207,12 +208,6 @@ export class AdwPreferencesDialog extends HTMLElement {
         if (this._initialized) return;
         this._initialized = true;
 
-        // The page ELEMENTS move into the body intact — their title / name / icon-name
-        // are what a search result subtitle and a view switcher read — and any unwrapped
-        // children follow them (Adw.PreferencesDialog's buildable default adds a child
-        // as a page).
-        const declared = Array.from(this.childNodes);
-
         // Clicking the scrim dismisses the dialog, or raises close-attempt when locked.
         this._scrimEl = document.createElement('div');
         this._scrimEl.className = 'adw-preferences-dialog-scrim';
@@ -253,12 +248,16 @@ export class AdwPreferencesDialog extends HTMLElement {
 
         this._pagesEl = document.createElement('div');
         this._pagesEl.className = 'adw-preferences-dialog-pages';
-        for (const child of declared) this._pagesEl.appendChild(child);
         this._bodyEl.appendChild(this._pagesEl);
 
         this._dialogEl.append(header, this._bodyEl);
 
-        this.replaceChildren(this._scrimEl, this._dialogEl);
+        // The page ELEMENTS move into the body intact — their title / name / icon-name are
+        // what a search result subtitle and a view switcher read — and any unwrapped child
+        // follows them (the Adw.PreferencesDialog buildable default adds a child as a
+        // page). LIVE, because `adw_preferences_dialog_add` works at any point in the
+        // dialog's life. `src/slotted-children.ts` has the incident.
+        bindSlottedChildren(this, [{ into: this._pagesEl }]).install(this._scrimEl, this._dialogEl);
 
         // The role, `aria-modal`, Escape (Adw.Dialog's shortcut → `maybe_close_cb`), the
         // Tab trap and the return-focus.

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