@gjsify/adwaita-web 0.42.0 → 0.44.0

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

@@ -14,9 +14,21 @@
 // Attributes:
 //   heading    (the bold heading text)
 //   body       (the body text below the heading)
+//   heading-use-markup (boolean — read `heading` as markup rather than plain text)
+//   body-use-markup    (boolean — read `body` as markup rather than plain text)
+//   close-response     (the response ID emitted on dismissal; default `close`)
+//   default-response   (the response ID whose button is highlighted and focused)
 //   open       (boolean — whether the dialog is shown; default closed)
 //   prefer-wide-layout (boolean — lay responses out horizontally when they fit)
 //
+// MARKUP IS OPT-IN, and here that MATCHES libadwaita rather than departing from it:
+// `Adw.AlertDialog:heading-use-markup` and `:body-use-markup` both default to FALSE
+// (`Adw.Banner:use-markup` is the one that defaults to TRUE, which is why
+// `adw-banner.ts` documents a deliberate departure and this file does not need to).
+// Opting in renders through `innerHTML`, which is the author asserting the string is
+// trusted — Pango markup has a fixed tag set and no scripting, HTML has neither
+// property.
+//
 // Buttons are stacked vertically by default (the Adw.AlertDialog default at medium
 // sizes) and laid out horizontally when prefer-wide-layout is set and there are no more
 // than two of them — the libadwaita measure/allocate heuristic in spirit, not to the px.
@@ -45,6 +57,7 @@ import { AdwAlertResponses } from '@gjsify/adwaita-core';
 import type { AdwResponseAppearance } from '@gjsify/adwaita-core';
 
 import { bindEmptySections } from '../empty-sections.js';
+import { bindSlottedChildren } from '../slotted-children.js';
 import { AdwModalSurface } from './modal-surface.js';
 
 /** Response button appearance — mirrors Adw.ResponseAppearance. */
@@ -81,7 +94,16 @@ export class AdwAlertDialog extends HTMLElement {
     private _blockCloseResponse = false;
 
     static get observedAttributes() {
-        return ['heading', 'body', 'open', 'prefer-wide-layout'];
+        return [
+            'heading',
+            'body',
+            'heading-use-markup',
+            'body-use-markup',
+            'close-response',
+            'default-response',
+            'open',
+            'prefer-wide-layout',
+        ];
     }
 
     get heading(): string {
@@ -109,6 +131,26 @@ export class AdwAlertDialog extends HTMLElement {
         else this.removeAttribute('open');
     }
 
+    /** Whether {@link heading} is read as markup rather than plain text. */
+    get headingUseMarkup(): boolean {
+        return this.hasAttribute('heading-use-markup');
+    }
+
+    set headingUseMarkup(value: boolean) {
+        if (value) this.setAttribute('heading-use-markup', '');
+        else this.removeAttribute('heading-use-markup');
+    }
+
+    /** Whether {@link body} is read as markup rather than plain text. */
+    get bodyUseMarkup(): boolean {
+        return this.hasAttribute('body-use-markup');
+    }
+
+    set bodyUseMarkup(value: boolean) {
+        if (value) this.setAttribute('body-use-markup', '');
+        else this.removeAttribute('body-use-markup');
+    }
+
     /** Whether to prefer horizontal button layout when the buttons fit. */
     get preferWideLayout(): boolean {
         return this.hasAttribute('prefer-wide-layout');
@@ -141,12 +183,6 @@ export class AdwAlertDialog extends HTMLElement {
         if (this._initialized) return;
         this._initialized = true;
 
-        // Declared <adw-alert-response> children are snapshotted before the element takes
-        // over the subtree; everything else becomes the extra child.
-        const declared = Array.from(this.querySelectorAll(':scope > adw-alert-response')) as AdwAlertResponse[];
-        const declaredSet = new Set<Node>(declared);
-        const extraChildren = Array.from(this.childNodes).filter((n) => !declaredSet.has(n));
-
         this._scrimEl = document.createElement('div');
         this._scrimEl.className = 'adw-alert-dialog-scrim';
         this._scrimEl.addEventListener('click', () => this._dismiss());
@@ -176,36 +212,66 @@ export class AdwAlertDialog extends HTMLElement {
 
         this._childEl = document.createElement('div');
         this._childEl.className = 'adw-alert-dialog-child';
-        for (const child of extraChildren) this._childEl.appendChild(child);
 
         messageArea.append(this._headingEl, this._bodyEl, this._childEl);
-        // `_render` runs from `attributeChangedCallback` and from the response API, and
-        // an extra child appended after connect triggers neither.
-        bindEmptySections(this._childEl);
 
         this._responseAreaEl = document.createElement('div');
         this._responseAreaEl.className = 'adw-alert-dialog-responses';
 
         this._dialogEl.append(messageArea, this._responseAreaEl);
-        this.replaceChildren(this._scrimEl, this._dialogEl);
-
-        for (const el of declared) {
-            const id = el.getAttribute('id');
-            if (!id) continue;
-            const appearance = (el.getAttribute('appearance') ?? 'default') as AdwResponseAppearance;
-            this.addResponse(id, (el.textContent ?? '').trim());
-            if (appearance !== 'default') this.setResponseAppearance(id, appearance);
-            if (el.getAttribute('enabled') === 'false') this.setResponseEnabled(id, false);
-        }
+
+        // Two slots, both LIVE. An `<adw-alert-response>` is DATA — read for its id, label
+        // and appearance and then gone, as GtkBuilder leaves nothing of a `<responses>`
+        // entry in the widget tree — so it is consumed rather than re-homed, and
+        // `adw_alert_dialog_add_response` is callable at any point in the dialog's life.
+        // Everything else is the extra child. `src/slotted-children.ts` has the incident.
+        // Installed AFTER the response area exists, because consuming a response fills it.
+        bindSlottedChildren(this, [
+            {
+                claims: (node) => node instanceof Element && node.localName === 'adw-alert-response',
+                consume: (node) => this._adoptResponse(node as AdwAlertResponse),
+            },
+            { into: this._childEl },
+        ]).install(this._scrimEl, this._dialogEl);
+
+        // `_render` runs from `attributeChangedCallback` and from the response API, and an
+        // extra child appended after connect triggers neither. AFTER the routing: this
+        // derives once synchronously, and a `hidden` child area is not focusable, so
+        // deriving it on the not-yet-filled box sent the initial focus to the default
+        // response instead of into the content.
+        bindEmptySections(this._childEl);
 
         // Seed the headless model's text from the parsed markup; the attributes stay the
         // source of truth for what is rendered.
         this._model.heading = this.heading;
         this._model.body = this.body;
 
+        // And the two response IDs. `attributeChangedCallback` returns early until
+        // `_initialized`, so an attribute present in the MARKUP — the declarative case
+        // these attributes exist for — is never delivered to it. `heading` and `body`
+        // survive that only because `_render()` re-reads them from the attribute; these
+        // two live in the model and would simply be dropped.
+        const closeResponse = this.getAttribute('close-response');
+        if (closeResponse !== null) this._model.closeResponse = closeResponse;
+        this._model.defaultResponse = this.getAttribute('default-response');
+
         this._render();
     }
 
+    /**
+     * 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(el: AdwAlertResponse): void {
+        const id = el.getAttribute('id');
+        if (!id) return;
+        const appearance = (el.getAttribute('appearance') ?? 'default') as AdwResponseAppearance;
+        this.addResponse(id, (el.textContent ?? '').trim());
+        if (appearance !== 'default') this.setResponseAppearance(id, appearance);
+        if (el.getAttribute('enabled') === 'false') this.setResponseEnabled(id, false);
+    }
+
     attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null) {
         if (!this._initialized) return;
         if (oldValue === newValue) return;
@@ -220,6 +286,14 @@ export class AdwAlertDialog extends HTMLElement {
         } else if (name === 'body') {
             this._model.body = this.body;
             this.dispatchEvent(new CustomEvent('notify::body', { bubbles: true, detail: { body: this.body } }));
+        } else if (name === 'close-response') {
+            // The MODEL stays the source of truth for response semantics (see the
+            // header) — the attribute is a markup entry point that feeds it, so the
+            // setter is not mirrored back and there is no reflection loop. An absent
+            // attribute means "leave the model's default", not "reset to `close`".
+            if (newValue !== null) this.setCloseResponse(newValue);
+        } else if (name === 'default-response') {
+            this.setDefaultResponse(newValue);
         } else if (name === 'open') {
             this.dispatchEvent(new CustomEvent('notify::open', { bubbles: true, detail: { open: this.open } }));
             if (this.open) this._modal.present();
@@ -386,11 +460,13 @@ export class AdwAlertDialog extends HTMLElement {
         this.classList.toggle('open', this.open);
 
         const heading = this.heading;
-        this._headingEl.textContent = heading;
+        if (this.headingUseMarkup) this._headingEl.innerHTML = heading;
+        else this._headingEl.textContent = heading;
         this._headingEl.hidden = heading.length === 0;
 
         const body = this.body;
-        this._bodyEl.textContent = body;
+        if (this.bodyUseMarkup) this._bodyEl.innerHTML = body;
+        else this._bodyEl.textContent = body;
         this._bodyEl.hidden = body.length === 0;
 
         // Horizontal only when prefer-wide-layout is set AND there are at most two

package/src/elements/adw-carousel.ts

@@ -9,9 +9,14 @@
 // position compensation. This element is the DOM half only — scroll-snap strip,
 // offset↔position, DOM events.
 //
-// The three attribute defaults HTML cannot spell: `allow-scroll-wheel` and
-// `interactive` default TRUE, so `="false"` is the off switch; `allow-long-swipes`
-// is an ordinary presence attribute. `position` is the INITIAL page only —
+// The four attribute defaults HTML cannot spell: `allow-scroll-wheel`,
+// `allow-mouse-drag` and `interactive` default TRUE, so `="false"` is the off switch;
+// `allow-long-swipes` is an ordinary presence attribute.
+//
+// A MOUSE DRAG is `elements/swipe-drag.ts`, and it is the one gesture a browser gives
+// nothing for: touch and touchpad scroll this strip natively, a held mouse button does
+// not. Upstream turns it on in `init` (:1209) and exposes `allow-mouse-drag`, default
+// TRUE (:1091). Measured before: a 300 px drag moved `position` 0 → 0. `position` is the INITIAL page only —
 // write-only, with the live value on the `position` property and `notify::position`.
 //
 // `page-changed` (`detail = { index }`) fires on every settle, including back
@@ -27,9 +32,11 @@
 // Copyright (c) GNOME contributors (libadwaita). LGPLv2.1+.
 // Modifications: Implemented as Web Components for @gjsify/adwaita-web.
 
-import { CarouselState, carouselPageAllocation } from '@gjsify/adwaita-core';
+import { CarouselState, carouselClosestSnapPoint, carouselPageAllocation } from '@gjsify/adwaita-core';
 import type { CarouselScrollRequest, CarouselScrollSource, CarouselStateChange } from '@gjsify/adwaita-core';
 
+import { attachSwipeDrag, type AdwSwipeDrag } from './swipe-drag.js';
+
 /** Common surface an indicator binds to. The concrete element is AdwCarousel. */
 interface CarouselHost extends HTMLElement {
     readonly nPages: number;
@@ -94,9 +101,11 @@ export class AdwCarousel extends HTMLElement implements CarouselHost {
      * index while the target page stays the target.
      */
     private _scrollTargetId: string | null = null;
+    /** The pointer-drag gesture, asked whether it owns the strip. See `_onWheel`. */
+    private _drag: AdwSwipeDrag | undefined;
 
     static get observedAttributes() {
-        return ['allow-scroll-wheel', 'allow-long-swipes', 'interactive', 'spacing', 'position'];
+        return ['allow-scroll-wheel', 'allow-mouse-drag', 'allow-long-swipes', 'interactive', 'spacing', 'position'];
     }
 
     constructor() {
@@ -132,6 +141,18 @@ export class AdwCarousel extends HTMLElement implements CarouselHost {
         return this._state.pageAt(this._state.position);
     }
 
+    /**
+     * `AdwCarousel:allow-mouse-drag` — whether the strip can be dragged with the pointer.
+     * Defaults to TRUE, as in libadwaita, where FALSE leaves dragging to touch only.
+     */
+    get allowMouseDrag(): boolean {
+        return this._state.allowMouseDrag;
+    }
+
+    set allowMouseDrag(value: boolean) {
+        this.setAttribute('allow-mouse-drag', value ? 'true' : 'false');
+    }
+
     /** Whether the scroll wheel navigates between pages. Defaults to TRUE, as in libadwaita. */
     get allowScrollWheel(): boolean {
         return this._state.allowScrollWheel;
@@ -187,6 +208,7 @@ export class AdwCarousel extends HTMLElement implements CarouselHost {
         // Declared properties BEFORE children: `spacing` is part of the page pitch,
         // so a page added first would be measured against the wrong distance.
         this._applyAttribute('allow-scroll-wheel', this.getAttribute('allow-scroll-wheel'));
+        this._applyAttribute('allow-mouse-drag', this.getAttribute('allow-mouse-drag'));
         this._applyAttribute('allow-long-swipes', this.getAttribute('allow-long-swipes'));
         this._applyAttribute('interactive', this.getAttribute('interactive'));
         this._applyAttribute('spacing', this.getAttribute('spacing'));
@@ -200,6 +222,52 @@ export class AdwCarousel extends HTMLElement implements CarouselHost {
         this._trackEl.addEventListener('scroll', this._onScroll, { passive: true });
         this._trackEl.addEventListener('wheel', this._onWheel, { passive: false });
 
+        this._drag = attachSwipeDrag({
+            // On the TRACK, not on the host: the track is the scroll container the drag
+            // writes `scrollLeft` on, and it is what the pages live in.
+            host: this._trackEl,
+            orientation: 'horizontal',
+            // `interactive` gates it because that is exactly what it does upstream —
+            // `adw_carousel_set_interactive` is `adw_swipe_tracker_set_enabled` (:1705).
+            enabled: () => this._state.interactive && this._state.allowMouseDrag,
+            pitch: () => this._distance(),
+            points: () => this._state.snapPoints,
+            progress: () => this._state.position,
+            allowLongSwipes: () => this._state.allowLongSwipes,
+            // `adw_carousel_get_cancel_progress` is `get_closest_snap_point`
+            // (adw-carousel.c:1294-1299) — the page nearest where the gesture was
+            // interrupted, NOT the one it started from.
+            //
+            // `carouselClosestSnapPoint` and NOT `_state.pageAt`, for two reasons that
+            // both make the answer a different page. `pageAt` searches the VISIBLE snap
+            // points (it filters out children being removed) and returns an index into
+            // that filtered array, so subscripting the unfiltered list with it shifts by
+            // one for every removing child ahead of the target. And it is the
+            // `count_removing = FALSE` variant, while `get_closest_snap_point` passes
+            // TRUE (adw-carousel.c:1298) — this is the one call site that counts them.
+            //
+            // The POINT, not an index: a page mid-reveal has a fractional size, so
+            // `carouselSnapPoints` (cumulative size − 1) hands back non-integers.
+            cancelProgress: () => {
+                const points = this._state.snapPoints;
+                return points[carouselClosestSnapPoint(this._state.position, points)] ?? this._state.position;
+            },
+            // The DRAG writes the offset directly and the existing scroll handler reads
+            // the position back off it — the same path a touch scroll takes, so there is
+            // no second route into `position` to drift from this one.
+            onUpdate: (progress) => {
+                const distance = this._distance();
+                if (distance > 0) this._trackEl.scrollLeft = progress * distance;
+            },
+            // `scroll_to` with the swipe's velocity is what `end_swipe_cb` does (:434).
+            // Here the settle is the browser's smooth scroll, so the velocity is unused
+            // — snap is already restored, and `to` is a snap point by construction.
+            onEnd: (progress) => {
+                const distance = this._distance();
+                if (distance > 0) this._trackEl.scrollTo({ left: progress * distance });
+            },
+        });
+
         // Applied last, once the pages it names exist. Custom-element upgrade
         // delivers attributes BEFORE `connectedCallback`, so reading it here is the
         // only way `<adw-carousel position="2">` works at all.
@@ -246,6 +314,10 @@ export class AdwCarousel extends HTMLElement implements CarouselHost {
                 // usual "presence = on" spelling would invert it.
                 this._state.setAllowScrollWheel(value !== 'false');
                 return;
+            case 'allow-mouse-drag':
+                // Absent means TRUE, like `allow-scroll-wheel` and for the same reason.
+                this._state.setAllowMouseDrag(value !== 'false');
+                return;
             case 'allow-long-swipes':
                 this._state.setAllowLongSwipes(value !== null && value !== 'false');
                 this._applySnapStop();
@@ -546,6 +618,15 @@ export class AdwCarousel extends HTMLElement implements CarouselHost {
     };
 
     private _onWheel = (event: WheelEvent): void => {
+        // A drag owns the offset while it is claimed. Without this a single wheel notch
+        // mid-drag ran the whole paging path and moved `scrollLeft` a full page in one
+        // frame — measured 80 → 440 — which the next pointer move then yanked back, and
+        // it left `_scrollTargetId` pointing at a page the drag overrode. `GDK_EVENT_STOP`
+        // rather than propagate, because the gesture IS handling this widget's scrolling.
+        if (this._drag?.dragging === true) {
+            event.preventDefault();
+            return;
+        }
         const step = this._state.handleWheel({
             deltaX: event.deltaX,
             deltaY: event.deltaY,

package/src/elements/adw-dialog.ts

@@ -24,6 +24,7 @@
 // Copyright (c) 2023-2024 GNOME Foundation Inc. (libadwaita). LGPLv2.1+.
 // Modifications: Implemented as a Web Component for @gjsify/adwaita-web.
 
+import { bindSlottedChildren } from '../slotted-children.js';
 import { AdwModalSurface } from './modal-surface.js';
 
 /** Adaptive presentation of the dialog — mirrors Adw.DialogPresentationMode. */
@@ -141,10 +142,6 @@ export class AdwDialog extends HTMLElement {
 
         this.classList.add('adw-dialog');
 
-        // Snapshot before the subtree is replaced: everything the author placed inside
-        // becomes the dialog content.
-        const contentChildren = Array.from(this.childNodes);
-
         this._scrimEl = document.createElement('div');
         this._scrimEl.className = 'adw-dialog-scrim';
         this._scrimEl.addEventListener('click', () => this._attemptClose());
@@ -187,11 +184,13 @@ export class AdwDialog extends HTMLElement {
 
         this._contentEl = document.createElement('div');
         this._contentEl.className = 'adw-dialog-content';
-        for (const child of contentChildren) this._contentEl.appendChild(child);
 
         this._boxEl.append(this._headerEl, this._contentEl);
         this._scrimEl.appendChild(this._boxEl);
-        this.replaceChildren(this._scrimEl);
+        // Everything the author places inside is the dialog content — LIVE, because
+        // `Adw.Dialog:child` is a property and a dialog whose body is filled in after it
+        // was created is the ordinary case. `src/slotted-children.ts` has the incident.
+        bindSlottedChildren(this, [{ into: this._contentEl }]).install(this._scrimEl);
 
         this._render();
     }

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

@@ -37,6 +37,7 @@ import {
     type EntryRowRenderState,
 } from '@gjsify/adwaita-core';
 
+import { bindSlottedChildren, type AdwSlottedChildren } from '../slotted-children.js';
 import { type AdwIcon, createAdwIcon } from './adw-icon.js';
 
 /**
@@ -71,8 +72,11 @@ export class AdwEntryRow extends HTMLElement {
     protected _prefixes!: HTMLDivElement;
     protected _suffixes!: HTMLDivElement;
     protected _initialized = false;
-    /** Light-DOM children captured at build time, adopted after `_onConnected`. */
-    private _authored: Element[] = [];
+    /**
+     * The two slots, installed after `_onConnected` rather than inside `_build`: the order
+     * IS the contract — see the `install` call in `connectedCallback`.
+     */
+    private _slots!: AdwSlottedChildren;
     private _lastText = '';
     private _lastLength = 0;
 
@@ -159,11 +163,20 @@ export class AdwEntryRow extends HTMLElement {
         if (this.hasAttribute('text')) this._state.setText(this.getAttribute('text') ?? '');
         this._renderTitle();
 
-        // Subclass parts first, THEN the author's children: `AdwPasswordEntryRow`
-        // installs its peek toggle from its own `init`, so a consumer
-        // suffix lands after it and both remain.
+        // Subclass parts first, THEN the author's children: `AdwPasswordEntryRow` installs
+        // its peek toggle from its own `init`, so a consumer suffix lands after it and both
+        // remain. That ordering is why the structure is installed HERE and not at the end of
+        // `_build` — `install` routes the author's children on its way, and doing it a phase
+        // earlier would put every declared suffix in front of the password row's toggle.
         this._onConnected();
-        this._adoptAuthored();
+        this._slots.install(
+            this._prefixes,
+            this._area,
+            this._indicator,
+            this._applyButton,
+            this._editIcon,
+            this._suffixes,
+        );
 
         this._lastText = this._state.text;
         this._lastLength = this._state.textLength;
@@ -254,12 +267,6 @@ export class AdwEntryRow extends HTMLElement {
     private _build(): void {
         const prefix = this._classPrefix;
 
-        // Author-supplied light-DOM children are KEPT: `replaceChildren` used to
-        // discard them silently, so `<adw-entry-row><adw-button>Go</adw-button>`
-        // rendered without its button. Elements only — GtkBuildable also only
-        // ever adopts widgets, and keeping stray whitespace would make an empty
-        // affordance box measure as non-empty.
-        this._authored = [...this.children];
         this._prefixes = document.createElement('div');
         this._prefixes.className = `${prefix}-prefixes`;
         this._suffixes = document.createElement('div');
@@ -322,34 +329,26 @@ export class AdwEntryRow extends HTMLElement {
         this._editIcon = createAdwIcon('document-edit', 'adw-row-edit', `${prefix}-edit`);
         this._editIcon.dataset.iconName = ENTRY_ROW_EDIT_ICON_NAME;
 
-        // Snapshot order: indicator → apply → edit icon inside the editable area, with
-        // the prefixes/suffixes boxes outside it.
-        this.replaceChildren(
-            this._prefixes,
-            this._area,
-            this._indicator,
-            this._applyButton,
-            this._editIcon,
-            this._suffixes,
-        );
+        // Author-supplied light-DOM children are KEPT and stay LIVE: `replaceChildren` used
+        // to discard them silently, so `<adw-entry-row><adw-button>Go</adw-button>` rendered
+        // without its button, and the snapshot that fixed that was still a one-shot read — a
+        // suffix appended after connect sat outside the affordance box. ELEMENTS only, on
+        // both paths: GtkBuildable also only ever adopts widgets, and keeping stray
+        // whitespace would make an empty affordance box measure as non-empty. Consumed
+        // through the two `add*` methods, because their insertion rules differ —
+        // `addPrefix` PREPENDS, mirroring `gtk_box_prepend`. Structure order:
+        // indicator → apply → edit icon inside the editable area, prefixes/suffixes outside.
+        // `src/slotted-children.ts` has the incident.
+        this._slots = bindSlottedChildren(this, [
+            { name: 'prefix', consume: (node) => this.addPrefix(node) },
+            { name: 'suffix', claims: (node) => node instanceof Element, consume: (node) => this.addSuffix(node) },
+        ]);
         setPartVisible(this._prefixes, false);
         setPartVisible(this._suffixes, false);
 
         this.addEventListener('click', (event) => this._maybeFocus(event));
     }
 
-    /**
-     * 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(): void {
-        for (const node of this._authored) {
-            if (node.getAttribute('slot') === 'prefix') this.addPrefix(node);
-            else this.addSuffix(node);
-        }
-        this._authored = [];
-    }
-
     /**
      * `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/src/elements/adw-expander-row.ts

@@ -22,6 +22,7 @@
 import { ExpanderState, deriveRowLabels } from '@gjsify/adwaita-core';
 
 import { bindEmptySections } from '../empty-sections.js';
+import { bindSlottedChildren } from '../slotted-children.js';
 
 // SIDE-EFFECT import, deliberately separate from the type import below: it guarantees
 // `adw-switch` is defined before this module's `customElements.define` can upgrade a
@@ -105,11 +106,6 @@ export class AdwExpanderRow extends HTMLElement {
         if (this._initialized) return;
         this._initialized = true;
 
-        const prefixChildren = Array.from(this.querySelectorAll(':scope > [slot="prefix"]'));
-        const suffixChildren = Array.from(this.querySelectorAll(':scope > [slot="suffix"]'));
-        const claimed = new Set<Node>([...prefixChildren, ...suffixChildren]);
-        const rows = Array.from(this.childNodes).filter((node) => !claimed.has(node));
-
         this._headerEl = document.createElement('div');
         this._headerEl.className = 'adw-expander-row-header';
 
@@ -130,25 +126,33 @@ export class AdwExpanderRow extends HTMLElement {
 
         this._prefixEl = document.createElement('div');
         this._prefixEl.className = 'adw-expander-row-prefix';
-        for (const child of prefixChildren) this._prefixEl.appendChild(child);
 
         this._suffixEl = document.createElement('div');
         this._suffixEl.className = 'adw-expander-row-suffix';
-        for (const child of suffixChildren) this._suffixEl.appendChild(child);
-
-        // Same reason as the action row's: `_render` is attribute-driven, and a widget
-        // appended into `prefixSection` after connect is a childList change nothing else
-        // hears. `contentSection` is NOT in here — an empty disclosure is still the
-        // disclosure, and `.expanded` alone decides whether it shows.
-        bindEmptySections(this._prefixEl, this._suffixEl);
 
         this._headerEl.append(this._prefixEl, textEl, this._suffixEl, this._enableSwitch, this._chevronEl);
 
         this._contentEl = document.createElement('div');
         this._contentEl.className = 'adw-expander-row-content';
-        for (const row of rows) this._contentEl.appendChild(row);
 
-        this.replaceChildren(this._headerEl, this._contentEl);
+        // Three LIVE slots: the two header sections by name, and the disclosure rows as the
+        // unnamed default — `adw_expander_row_add_row` works at any point in the widget's
+        // life, so a row appended after connect must reach the content box rather than sit
+        // beside it. `src/slotted-children.ts` has the incident.
+        bindSlottedChildren(this, [
+            { name: 'prefix', into: this._prefixEl },
+            { name: 'suffix', into: this._suffixEl },
+            { into: this._contentEl },
+        ]).install(this._headerEl, this._contentEl);
+
+        // Same reason as the action row's: `_render` is attribute-driven, and a widget
+        // appended into `prefixSection` after connect is a childList change nothing else
+        // hears. `contentSection` is NOT in here — an empty disclosure is still the
+        // disclosure, and `.expanded` alone decides whether it shows.
+        //
+        // AFTER the routing: this derives once synchronously, so on a box the routing has
+        // not filled yet it hides a section that a declared child had already earned.
+        bindEmptySections(this._prefixEl, this._suffixEl);
 
         this._headerEl.addEventListener('click', (event) => {
             // Clicks on the enable switch toggle expansion-enable, not disclosure.

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

@@ -16,6 +16,8 @@
 // Copyright (c) 2025 csm. MIT License.
 // Modifications: Reimplemented as Web Component for @gjsify/adwaita-web.
 
+import { bindSlottedChildren } from '../slotted-children.js';
+
 // Registers <adw-window-title>: the derived centre is one, so importing the bar
 // alone must still define it.
 import './adw-window-title.js';
@@ -56,35 +58,41 @@ export class AdwHeaderBar extends HTMLElement {
         if (this._initialized) return;
         this._initialized = true;
 
-        // Capture any pre-existing slotted children before clearing
-        const startChildren = Array.from(this.querySelectorAll(':scope > [slot="start"]'));
-        const centerChildren = Array.from(this.querySelectorAll(':scope > [slot="center"]'));
-        const endChildren = Array.from(this.querySelectorAll(':scope > [slot="end"]'));
-
-        // Start section
         this._startEl = document.createElement('div');
         this._startEl.className = 'adw-header-bar-start';
-        for (const child of startChildren) this._startEl.appendChild(child);
 
-        // Center section — a `slot="center"` widget (title-widget) wins over the
-        // plain `title` text.
         this._centerEl = document.createElement('div');
         this._centerEl.className = 'adw-header-bar-center';
-        if (centerChildren.length > 0) {
-            for (const child of centerChildren) this._centerEl.appendChild(child);
-        } else {
-            this._titleEl = document.createElement('adw-window-title');
-            this._titleEl.className = 'adw-header-bar-title';
-            this._centerEl.appendChild(this._titleEl);
-        }
 
-        // End section
         this._endEl = document.createElement('div');
         this._endEl.className = 'adw-header-bar-end';
-        for (const child of endChildren) this._endEl.appendChild(child);
 
-        // Replace all children atomically
-        this.replaceChildren(this._startEl, this._centerEl, this._endEl);
+        // All three slots stay LIVE: a button appended with `slot="end"` after connect used
+        // to sit outside the end section, and `adw-header-bar.spec.ts` carried the
+        // workaround ("appended LAST") as a house rule. `src/slotted-children.ts` has the
+        // incident. The `onAdopt` hook keeps the title-widget either/or true afterwards —
+        // a centre widget that arrives late replaces the derived title, as setting
+        // `Adw.HeaderBar:title-widget` at any point does.
+        bindSlottedChildren(
+            this,
+            [
+                { name: 'start', into: this._startEl },
+                { name: 'center', into: this._centerEl },
+                { name: 'end', into: this._endEl },
+            ],
+            (_node, slot) => {
+                if (slot.name === 'center') this._dropDerivedTitle();
+            },
+        ).install(this._startEl, this._centerEl, this._endEl);
+
+        // Derived only when the centre is still free — the same either/or as
+        // `Adw.HeaderBar`, which builds an `AdwWindowTitle` exactly while no title-widget
+        // was given.
+        if (this._centerEl.childElementCount === 0) {
+            this._titleEl = document.createElement('adw-window-title');
+            this._titleEl.className = 'adw-header-bar-title';
+            this._centerEl.appendChild(this._titleEl);
+        }
         this._renderTitle();
     }
 
@@ -98,6 +106,17 @@ export class AdwHeaderBar extends HTMLElement {
         if (this._initialized) this._renderTitle();
     }
 
+    /**
+     * 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() {
+        this._titleEl?.remove();
+        this._titleEl = null;
+    }
+
     private _renderTitle() {
         // A `slot="center"` widget replaced the derived title, so there is
         // nothing for the attribute to write to — the same either/or as