@gjsify/adwaita-web 0.51.1 → 0.52.0

package/src/elements/adw-bottom-sheet.ts

@@ -15,19 +15,31 @@
 //     attribute to another truthy spelling notifies nobody.
 //   - the drag handle is decorative, not a close button — see below.
 //
-// Children are declared as <adw-bottom-sheet-content> (the persistent content)
-// and <adw-bottom-sheet-sheet> (the slide-up sheet); both are consumed at
-// connect time. Unslotted children fall back to the content, mirroring the
-// AdwBottomSheet GtkBuildable default (omitting the child type sets content).
+// Children are declared as <adw-bottom-sheet-content> (the persistent content),
+// <adw-bottom-sheet-sheet> (the slide-up sheet) and <adw-bottom-sheet-bottom-bar>
+// (the collapsed bar shown in its place); all three are consumed at connect time.
+// Unslotted children fall back to the content, mirroring the AdwBottomSheet
+// GtkBuildable default (omitting the child type sets content).
+//
+// THE BOTTOM BAR IS THE AFFORDANCE. It is the only thing libadwaita lets a user
+// click to OPEN a sheet, so an element without one can be opened by its owner and
+// by nobody else. It is a real <button>, because the bin upstream is a GtkButton
+// (adw-bottom-sheet.c:1203) — that is where the keyboard activation comes from.
 //
 // Attributes:
-//   open             (boolean — whether the sheet is revealed; default closed)
-//   modal            (boolean — dim + block the content while open; default on)
-//   can-close        (boolean — user can dismiss via the dimming / Esc / the
-//                       sheet.close action; default on. When off, a dismissal
-//                       raises `close-attempt` instead of closing — mirrors
-//                       Adw.BottomSheet:can-close)
-//   show-drag-handle (boolean — overlay the drag handle on the sheet; default on)
+//   open              (boolean — whether the sheet is revealed; default closed)
+//   modal             (boolean — dim + block the content while open; default on)
+//   can-close         (boolean — user can dismiss via the dimming / Esc / the
+//                        sheet.close action; default on. When off, a dismissal
+//                        raises `close-attempt` instead of closing — mirrors
+//                        Adw.BottomSheet:can-close)
+//   can-open          (boolean — user can open the sheet from the bottom bar;
+//                        default on. When off the bar stays on screen and gains
+//                        the `inert` class, because libadwaita refuses the click
+//                        without disabling the button — Adw.BottomSheet:can-open)
+//   reveal-bottom-bar (boolean — whether the bottom bar is shown at all while the
+//                        sheet is closed; default on)
+//   show-drag-handle  (boolean — overlay the drag handle on the sheet; default on)
 //
 // Events:
 //   `notify::open` (CustomEvent, bubbles, `detail = { open }`) when the revealed
@@ -44,7 +56,14 @@
 // Modifications: Implemented as a Web Component for @gjsify/adwaita-web.
 
 import { BottomSheetPresentation } from '@gjsify/adwaita-core';
-import type { BottomSheetCloseOutcome, BottomSheetCloseSource } from '@gjsify/adwaita-core';
+import type {
+    BottomSheetCloseOutcome,
+    BottomSheetCloseSource,
+    BottomSheetOpenOutcome,
+    BottomSheetOpenSource,
+} from '@gjsify/adwaita-core';
+
+import { bindSlottedChildren, type AdwSlot } from '../slotted-children.js';
 
 /** The persistent content. Child of <adw-bottom-sheet>; consumed at connect time. */
 export class AdwBottomSheetContent extends HTMLElement {}
@@ -52,19 +71,26 @@ export class AdwBottomSheetContent extends HTMLElement {}
 /** The slide-up sheet. Child of <adw-bottom-sheet>; consumed at connect time. */
 export class AdwBottomSheetSheet extends HTMLElement {}
 
+/** The collapsed bar the sheet morphs out of. Child of <adw-bottom-sheet>. */
+export class AdwBottomSheetBottomBar extends HTMLElement {}
+
 export class AdwBottomSheet extends HTMLElement {
     private _initialized = false;
     private _contentEl!: HTMLDivElement;
     private _dimmingEl!: HTMLDivElement;
     private _sheetEl!: HTMLDivElement;
+    private _sheetBodyEl!: HTMLDivElement;
+    private _bottomBarEl!: HTMLButtonElement;
     private _dragHandleEl!: HTMLDivElement;
+    /** A bar set through {@link setBottomBar} before the element upgraded. */
+    private _pendingBottomBar: Node | null = null;
     /** The shared open/can-close model — the single source of truth for both. */
     private readonly _state = new BottomSheetPresentation();
     /** Set while the element writes `open` back, so the write does not re-enter. */
     private _reflecting = false;
 
     static get observedAttributes() {
-        return ['open', 'modal', 'can-close', 'show-drag-handle'];
+        return ['open', 'modal', 'can-close', 'can-open', 'reveal-bottom-bar', 'show-drag-handle'];
     }
 
     get open(): boolean {
@@ -75,8 +101,9 @@ export class AdwBottomSheet extends HTMLElement {
         this._setOpen(!!value);
     }
 
+    /** Whether the content is dimmed and blocked while the sheet is open (`AdwBottomSheet:modal`). */
     get modal(): boolean {
-        return this._boolAttr('modal', true);
+        return this._state.modal;
     }
 
     set modal(value: boolean) {
@@ -92,6 +119,24 @@ export class AdwBottomSheet extends HTMLElement {
         this._setBoolAttr('can-close', value);
     }
 
+    /** Whether the user can open the sheet from its bottom bar (`Adw.BottomSheet:can-open`). */
+    get canOpen(): boolean {
+        return this._state.canOpen;
+    }
+
+    set canOpen(value: boolean) {
+        this._setBoolAttr('can-open', value);
+    }
+
+    /** Whether the bottom bar is shown while the sheet is closed. */
+    get revealBottomBar(): boolean {
+        return this._state.revealBottomBar;
+    }
+
+    set revealBottomBar(value: boolean) {
+        this._setBoolAttr('reveal-bottom-bar', value);
+    }
+
     get showDragHandle(): boolean {
         return this._boolAttr('show-drag-handle', true);
     }
@@ -100,6 +145,38 @@ export class AdwBottomSheet extends HTMLElement {
         this._setBoolAttr('show-drag-handle', value);
     }
 
+    /** The bar's content, or `null` when the sheet has none — the read-back for {@link setBottomBar}. */
+    get bottomBar(): Node | null {
+        return this._initialized ? this._bottomBarEl.firstChild : this._pendingBottomBar;
+    }
+
+    /**
+     * Give the sheet a bottom bar, or take it away — `adw_bottom_sheet_set_bottom_bar`.
+     *
+     * Presence is an INPUT to the open gate, not decoration: removing the bar removes every
+     * way a user has of opening this sheet, which is why the state hears about it rather
+     * than only the DOM.
+     */
+    setBottomBar(child: Node | null): void {
+        this._state.setHasBottomBar(child !== null);
+        if (!this._initialized) {
+            this._pendingBottomBar = child;
+            return;
+        }
+        if (child) this._bottomBarEl.replaceChildren(child);
+        else this._bottomBarEl.replaceChildren();
+        this._render();
+    }
+
+    /**
+     * Route an open affordance through the shared gate. `'ignored'` is silent by design:
+     * libadwaita has no `open-attempt` counterpart to `close-attempt`, so a refused open
+     * emits nothing at all.
+     */
+    requestOpen(source: BottomSheetOpenSource): BottomSheetOpenOutcome {
+        return this._state.requestOpen(source);
+    }
+
     /**
      * Route a dismissal affordance through the shared gate and act on the verdict: close,
      * raise `close-attempt`, forward `sheet.close` to an ancestor, or do nothing. Called
@@ -123,17 +200,8 @@ export class AdwBottomSheet extends HTMLElement {
         if (this._initialized) return;
         this._initialized = true;
 
-        // The sheet and content are placed by slot; anything unslotted falls back to the
-        // content (the AdwBottomSheet GtkBuildable default).
-        const claimed = new Set<Node>();
-        const sheetChildren = this._collectSlot('adw-bottom-sheet-sheet', 'sheet', claimed);
-        const contentChildren = this._collectSlot('adw-bottom-sheet-content', 'content', claimed);
-        const unslotted = Array.from(this.childNodes).filter((n) => !claimed.has(n));
-
         this._contentEl = document.createElement('div');
         this._contentEl.className = 'adw-bottom-sheet-content';
-        for (const child of contentChildren) this._contentEl.appendChild(child);
-        for (const child of unslotted) this._contentEl.appendChild(child);
 
         this._dimmingEl = document.createElement('div');
         this._dimmingEl.className = 'adw-bottom-sheet-dimming';
@@ -151,13 +219,57 @@ export class AdwBottomSheet extends HTMLElement {
         this._dragHandleEl.className = 'adw-bottom-sheet-drag-handle';
         this._dragHandleEl.setAttribute('aria-hidden', 'true');
 
-        const sheetBody = document.createElement('div');
-        sheetBody.className = 'adw-bottom-sheet-sheet-body';
-        for (const child of sheetChildren) sheetBody.appendChild(child);
-
-        this._sheetEl.append(this._dragHandleEl, sheetBody);
-
-        this.replaceChildren(this._contentEl, this._dimmingEl, this._sheetEl);
+        this._sheetBodyEl = document.createElement('div');
+        this._sheetBodyEl.className = 'adw-bottom-sheet-sheet-body';
+
+        // A real <button>: the bin upstream is `gtk_button_new ()`
+        // (adw-bottom-sheet.c:1203), which is where its keyboard activation comes from
+        // (`bottom_bar_clicked_cb`, :402-407) — a div with a click handler would have the
+        // pointer door and not that one. It is the sheet bin's OTHER stack child, so it
+        // lives inside the sheet element and the two swap rather than stacking.
+        this._bottomBarEl = document.createElement('button');
+        this._bottomBarEl.type = 'button';
+        this._bottomBarEl.className = 'adw-bottom-sheet-bottom-bar';
+        this._bottomBarEl.addEventListener('click', () => this.requestOpen('bottom-bar'));
+
+        this._sheetEl.append(this._bottomBarEl, this._dragHandleEl, this._sheetBodyEl);
+
+        // The three layers are SLOTS, bound live (`slotted-children.ts`), under the names
+        // GtkBuilder gives the properties — `content`, `sheet`, `bottom-bar` — so a projected
+        // `.blp` places its children here, and the mount's refusal of an unknown slot can
+        // ask this element which names it has. The wrapper elements are the markup spelling
+        // of the same three: each is consumed and its children land in the layer. Anything
+        // unslotted is content, the AdwBottomSheet GtkBuildable default.
+        const layer = (tag: string, into: HTMLElement): AdwSlot => ({
+            claims: (node) => node instanceof Element && node.localName === tag,
+            consume: (node) => {
+                for (const child of Array.from(node.childNodes)) into.appendChild(child);
+            },
+        });
+        bindSlottedChildren(
+            this,
+            [
+                { name: 'sheet', into: this._sheetBodyEl },
+                { name: 'bottom-bar', into: this._bottomBarEl },
+                { name: 'content', into: this._contentEl },
+                layer('adw-bottom-sheet-sheet', this._sheetBodyEl),
+                layer('adw-bottom-sheet-bottom-bar', this._bottomBarEl),
+                layer('adw-bottom-sheet-content', this._contentEl),
+                { into: this._contentEl },
+            ],
+            (_node, slot) => {
+                // A bar adopted after connect is presence, which the open gate reads.
+                if (!('into' in slot) || slot.into !== this._bottomBarEl) return;
+                this._state.setHasBottomBar(true);
+                this._render();
+            },
+        ).install(this._contentEl, this._dimmingEl, this._sheetEl);
+
+        // A bar handed to `setBottomBar` before the upgrade wins over a declared one, as the
+        // later write does in GTK. `hasBottomBar` is re-seeded from the bin below, so the two
+        // cannot start out disagreeing about whether there is a bar.
+        if (this._pendingBottomBar) this._bottomBarEl.replaceChildren(this._pendingBottomBar);
+        this._pendingBottomBar = null;
 
         // Escape → `maybe_close_cb`. In GTK the shortcut sits on the sheet itself, so it
         // fires exactly while the sheet has focus — INCLUDING while the sheet is closed,
@@ -174,6 +286,10 @@ export class AdwBottomSheet extends HTMLElement {
         // Seeding BEFORE the subscription keeps the initial value silent, which is what
         // an attribute set during upgrade must be.
         this._state.setCanClose(this._boolAttr('can-close', true));
+        this._state.setCanOpen(this._boolAttr('can-open', true));
+        this._state.setRevealBottomBar(this._boolAttr('reveal-bottom-bar', true));
+        // A declared bar counts as present even where nothing called `setBottomBar`.
+        this._state.setHasBottomBar(this._bottomBarEl.childNodes.length > 0);
         this._state.setOpen(this._boolAttr('open', false));
         this._state.subscribe((open) => {
             this._render();
@@ -196,7 +312,10 @@ export class AdwBottomSheet extends HTMLElement {
             this._state.setOpen(this._boolAttr('open', false));
             return;
         }
+        if (name === 'modal') this._state.setModal(this._boolAttr('modal', true));
         if (name === 'can-close') this._state.setCanClose(this._boolAttr('can-close', true));
+        if (name === 'can-open') this._state.setCanOpen(this._boolAttr('can-open', true));
+        if (name === 'reveal-bottom-bar') this._state.setRevealBottomBar(this._boolAttr('reveal-bottom-bar', true));
         if (this._initialized) this._render();
     }
 
@@ -211,13 +330,25 @@ export class AdwBottomSheet extends HTMLElement {
 
     private _render(): void {
         const open = this._state.open;
+        const chrome = this._state.chrome;
+        const showsBar = chrome.layer === 'bottom-bar';
         this._reflectOpen(open);
         this.classList.toggle('open', open);
-        this.classList.toggle('modal', this.modal);
+        this.classList.toggle('modal', this._state.modal);
         this.classList.toggle('has-drag-handle', this.showDragHandle);
-
-        this._dimmingEl.classList.toggle('visible', open && this.modal);
-        this._dragHandleEl.hidden = !this.showDragHandle;
+        // `showing-bottom-bar` is what holds the sheet at translateY(0) with only the bar
+        // exposed; the CSS transform IS this port's `gtk_widget_set_child_visible`, so the
+        // bar being hidden and the sheet being off screen are two different states.
+        this.classList.toggle('showing-bottom-bar', showsBar && chrome.surfaceVisible);
+
+        this._dimmingEl.classList.toggle('visible', chrome.dimmed);
+        this._bottomBarEl.hidden = !showsBar;
+        // `inert` only paints. The button stays enabled and focusable exactly as upstream
+        // leaves it (adw-bottom-sheet.c:2033-2036); the gate is what refuses the click, and
+        // `disabled` here would take the focus stop away with it.
+        this._bottomBarEl.classList.toggle('inert', chrome.bottomBarInert);
+        this._sheetBodyEl.hidden = showsBar;
+        this._dragHandleEl.hidden = !this.showDragHandle || showsBar;
     }
 
     private _reflectOpen(open: boolean): void {
@@ -237,33 +368,9 @@ export class AdwBottomSheet extends HTMLElement {
         if (value) this.setAttribute(name, '');
         else this.setAttribute(name, 'false');
     }
-
-    /**
-     * Collect the nodes declared for one slot, in DOCUMENT order, marking every
-     * consumed child in `claimed`.
-     *
-     * The `<adw-bottom-sheet-sheet>` / `<adw-bottom-sheet-content>` wrappers are
-     * markup, not widgets — GtkBuilder's `<child type="sheet">` leaves nothing in
-     * the tree — so the wrapper itself is claimed
-     * too. It used to fall through to `unslotted` and be appended to the content
-     * layer, leaving an empty custom element behind after its children were
-     * pulled out.
-     */
-    private _collectSlot(tag: string, slot: string, claimed: Set<Node>): Node[] {
-        const nodes: Node[] = [];
-        for (const child of Array.from(this.children)) {
-            if (child.tagName.toLowerCase() === tag) {
-                claimed.add(child);
-                nodes.push(...Array.from(child.childNodes));
-            } else if (child.getAttribute('slot') === slot) {
-                claimed.add(child);
-                nodes.push(child);
-            }
-        }
-        return nodes;
-    }
 }
 
 customElements.define('adw-bottom-sheet-content', AdwBottomSheetContent);
 customElements.define('adw-bottom-sheet-sheet', AdwBottomSheetSheet);
+customElements.define('adw-bottom-sheet-bottom-bar', AdwBottomSheetBottomBar);
 customElements.define('adw-bottom-sheet', AdwBottomSheet);

package/src/elements/adw-carousel.ts

@@ -22,8 +22,8 @@
 // `page-changed` (`detail = { index }`) fires on every settle, including back
 // onto the same page, and reports -1 when empty.
 //
-// The indicators bind through their `carousel` property or a `for` attribute
-// naming the carousel's id.
+// The indicators bind through their `carousel` property, or a `carousel` (GTK's
+// name, what a projected `.blp` writes) or `for` attribute naming the carousel's id.
 //
 // Reference: refs/libadwaita/src/adw-carousel.c (AdwCarousel behaviour)
 // Reference: refs/libadwaita/src/adw-carousel-indicator-dots.c
@@ -678,7 +678,7 @@ abstract class AdwCarouselIndicator extends HTMLElement {
     protected _initialized = false;
 
     static get observedAttributes() {
-        return ['for'];
+        return ['for', 'carousel'];
     }
 
     /** The bound carousel. Mirrors AdwCarouselIndicator*'s `carousel` property. */
@@ -705,7 +705,7 @@ abstract class AdwCarouselIndicator extends HTMLElement {
     }
 
     attributeChangedCallback(name: string) {
-        if (name === 'for' && this._initialized) {
+        if ((name === 'for' || name === 'carousel') && this._initialized) {
             this._detach();
             this._carousel = null;
             this._resolveForAttr();
@@ -714,8 +714,13 @@ abstract class AdwCarouselIndicator extends HTMLElement {
         }
     }
 
+    /**
+     * The carousel named by id. `carousel` is the GTK property's own name, and what a
+     * projected `.blp` writes for `carousel: carousel`; `for` is the markup spelling this
+     * element had first, kept as the fallback.
+     */
     private _resolveForAttr(): void {
-        const id = this.getAttribute('for');
+        const id = this.getAttribute('carousel') ?? this.getAttribute('for');
         if (!id) return;
         const root = this.getRootNode() as Document | ShadowRoot;
         const el = root.getElementById?.(id) ?? document.getElementById(id);

package/src/elements/adw-clamp.ts

@@ -26,6 +26,8 @@
 
 import { ADW_CLAMP_DEFAULTS, ADW_CLAMP_SIZE_CLASSES, clampAllocate, normalizeClampSize } from '@gjsify/adwaita-core';
 
+import { bindSlottedChildren } from '../slotted-children.js';
+
 export class AdwClamp extends HTMLElement {
     private _resize: ResizeObserver | null = null;
     private _mutations: MutationObserver | null = null;
@@ -35,6 +37,16 @@ export class AdwClamp extends HTMLElement {
     }
 
     connectedCallback() {
+        // `Adw.Clamp:child` is a widget PROPERTY, so an authored `child: …` names the
+        // slot by that name (`shared-tree-builder.ts`'s `refuseUnknownSlots`) — and without
+        // a declaration for it, the placement was refused sight unseen. There is nowhere to
+        // ROUTE it to: every child here is already the placement, clamped in place, so this
+        // only enrols the NAME — `.install()` is never called, and nothing is moved. Calling
+        // it would be actively wrong: `into: this` would make the routed append a same-
+        // parent move, which the DOM still fires as a childList mutation, re-triggering the
+        // very MutationObserver that routes it.
+        bindSlottedChildren(this, [{ name: 'child', into: this }]);
+
         // ResizeObserver delivers an initial observation on observe(), so the
         // first allocation lands before paint without a separate seeding pass.
         this._resize = new ResizeObserver(() => this._allocate());

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

@@ -58,6 +58,9 @@
 import { ComboState, deriveRowLabels, normalizeComboOptions, parseListModel } from '@gjsify/adwaita-core';
 import type { AdwComboOption, AdwListItemsChanged, AdwListModelInput } from '@gjsify/adwaita-core';
 
+import { bindSlottedChildren } from '../slotted-children.js';
+import { stringListSlot } from '../string-list-slot.js';
+
 export class AdwComboRow extends HTMLElement {
     private _select!: HTMLSelectElement;
     private _valueEl!: HTMLSpanElement;
@@ -136,9 +139,6 @@ export class AdwComboRow extends HTMLElement {
         // Only when the PROPERTY was not already set, the rule `<adw-data-grid>` and
         // `<gtk-drop-down>` both follow: a model assigned to a detached element must
         // survive being attached, and an absent attribute must not blank it.
-        if (this._state.count === 0) this._state.setModel(parseListModel(this.getAttribute('model')));
-        this._state.setSelectedIndex(parseInt(this.getAttribute('selected') || '0', 10));
-
         const text = document.createElement('div');
         text.className = 'adw-row-text';
         this._titleEl = document.createElement('span');
@@ -152,7 +152,16 @@ export class AdwComboRow extends HTMLElement {
 
         this._select = document.createElement('select');
 
-        this.replaceChildren(text, this._valueEl, this._select);
+        // A `<gtk-string-list slot="model">` child is the list a `.blp` authored (ADR 0072),
+        // consumed here BEFORE the attribute seed below, so the seed sees a model and leaves
+        // it alone, and before the selection, so an authored index lands on the real list.
+        bindSlottedChildren(this, [stringListSlot((model) => this._state.setModel(model))]).install(
+            text,
+            this._valueEl,
+            this._select,
+        );
+        if (this._state.count === 0) this._state.setModel(parseListModel(this.getAttribute('model')));
+        this._state.setSelectedIndex(parseInt(this.getAttribute('selected') || '0', 10));
 
         // WHERE the model changed — applied before the selection change below, which is
         // the ordering that lets that subscriber's index write land on the new list.

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

@@ -47,6 +47,13 @@ export class AdwHeaderBar extends HTMLElement {
      * see the divergence at the top of this file.
      */
     private _titleEl: HTMLElement | null = null;
+    /**
+     * The `<adw-navigation-page>` this bar sits in, and the observer that follows its
+     * title. `update_title` (adw-header-bar.c:488) asks that page FIRST, which is how a
+     * bare `Adw.HeaderBar {}` in a `.blp` page shows "Mailboxes" with no title of its own.
+     */
+    private _page: Element | null = null;
+    private _pageObserver: MutationObserver | null = null;
 
     static get observedAttributes() {
         return ['title', 'subtitle'];
@@ -69,7 +76,11 @@ export class AdwHeaderBar extends HTMLElement {
     }
 
     connectedCallback() {
-        if (this._initialized) return;
+        if (this._initialized) {
+            this._followPage();
+            this._renderTitle();
+            return;
+        }
         this._initialized = true;
 
         this._startEl = document.createElement('div');
@@ -92,10 +103,19 @@ export class AdwHeaderBar extends HTMLElement {
             [
                 { name: 'start', into: this._startEl },
                 { name: 'center', into: this._centerEl },
+                // The SAME destination under the name GTK writes it at. This section has
+                // always documented itself as "the equivalent of Adw.HeaderBar's
+                // title-widget"; a tree authored at the property position (a Blueprint
+                // `title-widget: …`) carried exactly that name, found no destination for it
+                // and stayed a stray sibling — after which this element derived its own
+                // title into the centre, so the authored one was gone from the document.
+                // `center` stays because it is what this package published and what the
+                // gallery's own fences are written in.
+                { name: 'title-widget', into: this._centerEl },
                 { name: 'end', into: this._endEl },
             ],
             (_node, slot) => {
-                if (slot.name === 'center') this._dropDerivedTitle();
+                if ('into' in slot && slot.into === this._centerEl) this._dropDerivedTitle();
             },
         ).install(this._startEl, this._centerEl, this._endEl);
 
@@ -108,9 +128,29 @@ export class AdwHeaderBar extends HTMLElement {
             this._titleEl.className = 'adw-header-bar-title';
             this._centerEl.appendChild(this._titleEl);
         }
+        this._followPage();
         this._renderTitle();
     }
 
+    disconnectedCallback() {
+        this._pageObserver?.disconnect();
+        this._pageObserver = null;
+        this._page = null;
+    }
+
+    /**
+     * Find the enclosing navigation page and re-render when its title moves, as GTK does:
+     * `root` looks the ancestor up (adw-header-bar.c:586) and a `notify::title` on it re-runs
+     * `update_title`. Looked up on every connect, since a bar moved into another page has a
+     * new ancestor, which is why C does it in `root` and drops it in `unroot`.
+     */
+    private _followPage() {
+        this._page = this.closest('adw-navigation-page');
+        if (this._page === null) return;
+        this._pageObserver ??= new MutationObserver(() => this._renderTitle());
+        this._pageObserver.observe(this._page, { attributes: true, attributeFilter: ['title'] });
+    }
+
     /**
      * `title` used to be read ONCE, in `connectedCallback`, so every later write
      * was a silent no-op — a header bar whose title tracked the open document
@@ -147,7 +187,10 @@ export class AdwHeaderBar extends HTMLElement {
         // empty-string collapse do the work. Removing rather than writing `''`
         // keeps "unset" distinguishable from "set to empty" on the child.
         for (const name of ['title', 'subtitle']) {
-            const value = this.getAttribute(name);
+            // The bar's own `title` is this port's declarative divergence (see the header) and
+            // wins; without one, the page's title is the first answer `update_title` has.
+            const value =
+                this.getAttribute(name) ?? (name === 'title' ? (this._page?.getAttribute('title') ?? null) : null);
             if (value === null) this._titleEl.removeAttribute(name);
             else this._titleEl.setAttribute(name, value);
         }

package/src/elements/adw-inline-view-switcher.ts

@@ -55,6 +55,7 @@ import {
     domViewSwitcherScheduler,
     readSwitcherPage,
 } from './view-switcher-dom.js';
+import { bindSlottedChildren } from '../slotted-children.js';
 import { attachRovingFocus } from './roving-focus.js';
 
 /** A single page. Children of <adw-inline-view-switcher>; consumed at connect time. */
@@ -62,6 +63,16 @@ export class AdwViewStackPage extends HTMLElement {
     static get observedAttributes() {
         return ['name', 'title', 'icon-name', 'badge-number', 'needs-attention', 'use-underline'];
     }
+
+    connectedCallback(): void {
+        // `AdwViewStackPage:child` is a PROPERTY, so a `.blp`'s `child: …` authors
+        // `slot="child"`, and the mount refused the name this element never declared. The
+        // page's children already ARE its content — the stack or the switcher moves them
+        // out when it adopts the page — so this only enrols the name, as `<adw-tab-page>`
+        // does. The owner adopts on ITS connect, which runs first, so by now this page may
+        // be detached; enrolling is all that is left to do either way.
+        bindSlottedChildren(this, [{ name: 'child', into: this }]);
+    }
 }
 
 export class AdwInlineViewSwitcher extends HTMLElement {

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

@@ -54,6 +54,8 @@
 import { BACK_BUTTON_FALLBACK_TOOLTIP, NavigationViewState, describeNavigationDiagnostic } from '@gjsify/adwaita-core';
 import type { AdwNavigationPageProps, NavigationDiagnostic, NavigationStackChange } from '@gjsify/adwaita-core';
 
+import { bindSlottedChildren } from '../slotted-children.js';
+
 /** The page properties the core owns, read off the element's attributes. */
 function readPageProps(page: AdwNavigationPage): AdwNavigationPageProps {
     return { tag: page.tag, title: page.title, canPop: page.canPop };
@@ -68,6 +70,14 @@ export class AdwNavigationPage extends HTMLElement {
         return ['title', 'tag', 'can-pop', 'no-back-button'];
     }
 
+    connectedCallback(): void {
+        // `AdwNavigationPage:child` is a widget PROPERTY, so a `.blp`'s `child: …` authors
+        // `slot="child"`. The page's children already ARE its content, so this only enrols
+        // the name — nothing is routed, and `.install()` is never called, for the reason
+        // `adw-clamp.ts` gives: `into: this` would re-trigger the observer that routes it.
+        bindSlottedChildren(this, [{ name: 'child', into: this }]);
+    }
+
     get title(): string {
         return this.getAttribute('title') ?? '';
     }

package/src/elements/adw-sidebar.ts

@@ -72,6 +72,28 @@ export class AdwSidebarItem extends HTMLElement {
         return ['title', 'subtitle', 'icon-name', 'disabled', 'hidden'];
     }
 
+    /**
+     * `AdwSidebarItem:enabled`, under the GIR name — the `disabled` attribute inverted. The
+     * property is what lets an authored `enabled: false` reach this item through the
+     * shared-tree builder, which writes a `false` through the element's own property.
+     */
+    get enabled(): boolean {
+        return !this.hasAttribute('disabled');
+    }
+
+    set enabled(value: boolean) {
+        this.toggleAttribute('disabled', !value);
+    }
+
+    /** `AdwSidebarItem:visible` — the `hidden` attribute inverted, for the same reason. */
+    get visible(): boolean {
+        return !this.hasAttribute('hidden');
+    }
+
+    set visible(value: boolean) {
+        this.toggleAttribute('hidden', !value);
+    }
+
     attributeChangedCallback(name: string, _oldValue: string | null, newValue: string | null) {
         const binding = itemBindings.get(this);
         if (!binding) return;