@gjsify/adwaita-web 0.54.0 → 0.56.0

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

@@ -10,8 +10,8 @@
 // held to one table (`@gjsify/adwaita-core/conformance`).
 //
 // Attributes: title, text, editable, max-length, show-apply-button,
-//   activates-default. `text-length` is REFLECTED (read-only, mirrors
-//   `Adw.EntryRow:text-length`).
+//   activates-default, tooltip-text (`Gtk.Widget:tooltip-text`). `text-length` is
+//   REFLECTED (read-only, mirrors `Adw.EntryRow:text-length`).
 // Properties: text, editable, maxLength, textLength, showApplyButton,
 //   activatesDefault, editing.
 // Events:
@@ -37,6 +37,8 @@ import {
     type EntryRowRenderState,
 } from '@gjsify/adwaita-core';
 
+import { booleanAttribute } from '../attributes.js';
+import { applyRowTooltip } from '../row-tooltip.js';
 import { bindSlottedChildren, type AdwSlottedChildren } from '../slotted-children.js';
 import { type GtkImage, createGtkImage } from './gtk-image.js';
 
@@ -51,11 +53,6 @@ function setPartVisible(part: HTMLElement, visible: boolean): void {
     part.style.display = visible ? '' : 'none';
 }
 
-/** Read a boolean attribute the HTML way, with an explicit `="false"` opt-out. */
-function boolAttribute(value: string | null): boolean {
-    return value !== null && value !== 'false';
-}
-
 export class AdwEntryRow extends HTMLElement {
     /** The headless `update_empty` derivation + apply latch (ADR 0004). */
     protected readonly _state = new EntryRowState();
@@ -81,7 +78,7 @@ export class AdwEntryRow extends HTMLElement {
     private _lastLength = 0;
 
     static get observedAttributes(): string[] {
-        return ['title', 'text', 'editable', 'max-length', 'show-apply-button', 'activates-default'];
+        return ['title', 'text', 'editable', 'max-length', 'show-apply-button', 'activates-default', 'tooltip-text'];
     }
 
     /**
@@ -158,8 +155,8 @@ export class AdwEntryRow extends HTMLElement {
         // before the element was connected survives.
         this._state.setMaxLength(Number.parseInt(this.getAttribute('max-length') ?? '', 10));
         this._state.setEditable(this.getAttribute('editable') !== 'false');
-        this._state.setShowApplyButton(boolAttribute(this.getAttribute('show-apply-button')));
-        this._state.setActivatesDefault(boolAttribute(this.getAttribute('activates-default')));
+        this._state.setShowApplyButton(booleanAttribute(this.getAttribute('show-apply-button'), false));
+        this._state.setActivatesDefault(booleanAttribute(this.getAttribute('activates-default'), false));
         if (this.hasAttribute('text')) this._state.setText(this.getAttribute('text') ?? '');
         this._renderTitle();
 
@@ -181,6 +178,7 @@ export class AdwEntryRow extends HTMLElement {
         this._lastText = this._state.text;
         this._lastLength = this._state.textLength;
         this._render(this._state.state);
+        applyRowTooltip(this, this._tooltipParts());
         this._state.subscribe((state) => this._onStateChanged(state));
     }
 
@@ -200,14 +198,26 @@ export class AdwEntryRow extends HTMLElement {
                 this._state.setMaxLength(Number.parseInt(value ?? '', 10));
                 break;
             case 'show-apply-button':
-                this._state.setShowApplyButton(boolAttribute(value));
+                this._state.setShowApplyButton(booleanAttribute(value, false));
                 break;
             case 'activates-default':
-                this._state.setActivatesDefault(boolAttribute(value));
+                this._state.setActivatesDefault(booleanAttribute(value, false));
+                break;
+            case 'tooltip-text':
+                applyRowTooltip(this, this._tooltipParts());
                 break;
         }
     }
 
+    /**
+     * The parts `tooltip-text` lands on: the two slots and the editable area — NOT the
+     * apply button or the indicator, which carry tooltips of their own that the consumer
+     * reads for what they are.
+     */
+    private _tooltipParts(): readonly Element[] {
+        return [this._prefixes, this._area, this._suffixes];
+    }
+
     /**
      * Add a widget after the editable area — `adw_entry_row_add_suffix`, which APPENDS
      * into a box, so several suffixes coexist and the password row's own peek toggle

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

@@ -1,6 +1,12 @@
 // <adw-expander-row> — a boxed-list row that discloses nested rows when expanded,
 // with an optional enable switch. Mirrors Adw.ExpanderRow.
 //
+// ATTRIBUTES: `title`, `subtitle`, `expanded`, `enable-expansion`, `show-enable-switch`,
+// and `title-lines` / `subtitle-lines` — clamp either label to N lines, `0` = unlimited,
+// the AdwActionRow pspec's sentinel (`@girs/adw-1`, min 0, default 0).
+// `tooltip-text` (`Gtk.Widget:tooltip-text`) — on the HEADER row alone, which is the
+// part that is the row libadwaita draws.
+//
 // Slots: `slot="prefix"` / `slot="suffix"` children sit in the HEADER row beside the
 // title (before the enable switch and disclosure chevron), like Adw.ExpanderRow's
 // add_prefix/add_suffix; every other child is moved into the disclosed content
@@ -22,7 +28,9 @@
 import { ExpanderState, deriveRowLabels } from '@gjsify/adwaita-core';
 
 import { bindEmptySections } from '../empty-sections.js';
+import { applyRowTooltip } from '../row-tooltip.js';
 import { bindSlottedChildren } from '../slotted-children.js';
+import { applyRowLineClamp, parseRowLinesAttribute } from '../row-line-clamp.js';
 
 // SIDE-EFFECT import, deliberately separate from the type import below: it guarantees
 // `gtk-switch` is defined before this module's `customElements.define` can upgrade a
@@ -68,7 +76,16 @@ export class AdwExpanderRow extends HTMLElement {
     }
 
     static get observedAttributes() {
-        return ['title', 'subtitle', 'expanded', 'enable-expansion', 'show-enable-switch'];
+        return [
+            'title',
+            'subtitle',
+            'expanded',
+            'enable-expansion',
+            'show-enable-switch',
+            'tooltip-text',
+            'title-lines',
+            'subtitle-lines',
+        ];
     }
 
     get expanded(): boolean {
@@ -224,6 +241,22 @@ export class AdwExpanderRow extends HTMLElement {
         // step with the flag; `aria-expanded` is the same statement to the same reader.
         this._headerEl.setAttribute('aria-expanded', String(this.expanded));
         this._contentEl.classList.toggle('expanded', this.expanded);
+        // The HEADER only, not the disclosure: libadwaita's tooltip belongs to the row, and
+        // the content box is where the disclosed rows live — a child row's own tooltip is
+        // what the browser should offer there.
+        applyRowTooltip(this, [this._headerEl]);
+        this._applyLineClamping();
+    }
+
+    /** Apply CSS line-clamping based on title-lines/subtitle-lines attributes. */
+    private _applyLineClamping(): void {
+        applyRowLineClamp({
+            titleEl: this._titleEl,
+            subtitleEl: this._subtitleEl,
+            textContainerEl: this._titleEl.parentElement!,
+            getTitleLines: () => parseRowLinesAttribute(this.getAttribute('title-lines')),
+            getSubtitleLines: () => parseRowLinesAttribute(this.getAttribute('subtitle-lines')),
+        });
     }
 }
 

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

@@ -53,6 +53,12 @@ export class AdwHeaderBar extends HTMLElement {
      * bare `Adw.HeaderBar {}` in a `.blp` page shows "Mailboxes" with no title of its own.
      */
     private _page: Element | null = null;
+    /**
+     * The window the bar sits in: `update_title`'s last stop before the application name
+     * (`gtk_window_get_title` of the root), so a bar with no title of its own, under no titled
+     * page, shows the window's.
+     */
+    private _window: Element | null = null;
     private _pageObserver: MutationObserver | null = null;
 
     static get observedAttributes() {
@@ -136,6 +142,7 @@ export class AdwHeaderBar extends HTMLElement {
         this._pageObserver?.disconnect();
         this._pageObserver = null;
         this._page = null;
+        this._window = null;
     }
 
     /**
@@ -146,9 +153,12 @@ export class AdwHeaderBar extends HTMLElement {
      */
     private _followPage() {
         this._page = this.closest('adw-navigation-page');
-        if (this._page === null) return;
+        this._window = this.closest('adw-window, adw-application-window');
         this._pageObserver ??= new MutationObserver(() => this._renderTitle());
-        this._pageObserver.observe(this._page, { attributes: true, attributeFilter: ['title'] });
+        for (const ancestor of [this._page, this._window]) {
+            if (ancestor !== null)
+                this._pageObserver.observe(ancestor, { attributes: true, attributeFilter: ['title'] });
+        }
     }
 
     /**
@@ -188,9 +198,13 @@ export class AdwHeaderBar extends HTMLElement {
         // keeps "unset" distinguishable from "set to empty" on the child.
         for (const name of ['title', 'subtitle']) {
             // 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.
+            // wins; without one, the page's title is the first answer `update_title` has, then
+            // the window's.
             const value =
-                this.getAttribute(name) ?? (name === 'title' ? (this._page?.getAttribute('title') ?? null) : null);
+                this.getAttribute(name) ??
+                (name === 'title'
+                    ? (this._page?.getAttribute('title') ?? this._window?.getAttribute('title') ?? null)
+                    : null);
             if (value === null) this._titleEl.removeAttribute(name);
             else this._titleEl.setAttribute(name, value);
         }

package/src/elements/adw-layout-slot.ts

@@ -0,0 +1,95 @@
+// <adw-layout-slot> — one named hole inside a layout of an `Adw.MultiLayoutView`.
+//
+// `AdwLayoutSlot` is a bin with an ID and nothing else: it takes a child when the view
+// inserts the child whose ID matches, and its `visible` property is bound to that
+// child's so hiding the child hides the hole (:151). The ID is what pairs the two
+// sides — `adw_multi_layout_view_set_child(id, widget)` finds the layout's slots by
+// `g_hash_table_lookup (self->slots, id)` (:139) — and it is CONSTRUCT-ONLY
+// (adw-layout-slot.c:145), so it is read once and never written.
+//
+// DUPLICATE IDs ACROSS LAYOUTS ARE THE WIDGET'S OWN MODEL, not a mistake here: the
+// canonical example in the C documentation puts an `AdwLayoutSlot` with `id="primary"`
+// in BOTH layouts of one view, because that is how a child follows a layout change. The
+// element never resolves a slot by document lookup, only from the subtree of the layout
+// it is currently mounting, so two of them with one ID are ordinary.
+//
+// Attributes:
+//   id  (`AdwLayoutSlot:id` — the slot ID. Construct-only upstream, so changing it here
+//        after connect re-registers the slot and warns, as `g_error` does for a slot
+//        constructed without one (adw-layout-slot.c:68).)
+//
+// A11Y: `role="group"`, the accessible role libadwaita installs on the class
+// (adw-layout-slot.c:131).
+//
+// There is no box of its own (`display: contents`, so the child takes the allocation the
+// container would have given the slot) and libadwaita ships NO rule for this widget —
+// `src/stylesheet/widgets/` has no `layout-slot` partial and no selector names the node,
+// so there is nothing to port and nothing invented to replace it.
+//
+// Reference: refs/libadwaita/src/adw-layout-slot.c
+// Copyright (c) 2023-2024 Purism SPC / GNOME Foundation Inc. (libadwaita). LGPLv2.1+.
+// Modifications: Implemented as a Web Component for @gjsify/adwaita-web.
+
+import { AdwMultiLayoutView } from './adw-multi-layout-view.js';
+
+export class AdwLayoutSlot extends HTMLElement {
+    private _registered = false;
+
+    static get observedAttributes() {
+        return ['id'];
+    }
+
+    /** `adw_layout_slot_get_slot_id()` (:184), read under its property's name. */
+    get slotId(): string | null {
+        return this.getAttribute('id');
+    }
+
+    connectedCallback() {
+        this.setAttribute('role', 'group');
+        // `display: contents` inline rather than in a partial: libadwaita styles nothing
+        // here, and a host page that wants the slot to box its child sets one rule.
+        this.style.display = 'contents';
+        this._register();
+    }
+
+    disconnectedCallback() {
+        this._registered = false;
+    }
+
+    attributeChangedCallback(name?: string) {
+        if (!this.isConnected || name !== 'id') return;
+        if (this._registered) {
+            // `G_PARAM_CONSTRUCT_ONLY`: upstream cannot change a slot's ID either, and
+            // the bin's `slots` table is keyed by it — `register_slot` refuses a second
+            // entry under one ID (adw-multi-layout-view.c:693). Saying so beats
+            // silently leaving the view holding the old pairing.
+            console.warn('<adw-layout-slot>: `id` is construct-only upstream; re-registering the slot.');
+        }
+        this._register();
+    }
+
+    /**
+     * Hand this slot to the nearest `<adw-multi-layout-view>` ancestor.
+     *
+     * `adw_layout_slot_root` walks up for the view and calls
+     * `adw_multi_layout_view_register_slot` (adw-layout-slot.c:55). The view's own
+     * mount path is the authority — it registers only while it is building a layout —
+     * so a call arriving outside that window is refused there, exactly as
+     * `accepting_slots` refuses it upstream.
+     */
+    private _register(): void {
+        const id = this.slotId;
+        if (id === null || id === '') {
+            console.error('<adw-layout-slot> created without an `id` — libadwaita refuses this with g_error.');
+            return;
+        }
+        // `instanceof` rather than a cast on `closest(…)`: an ancestor that is present
+        // but not upgraded yet satisfies a cast and fails at the call, and this is on the
+        // connect path of every slot.
+        const view = this.closest('adw-multi-layout-view');
+        if (view instanceof AdwMultiLayoutView) view.registerSlot(id, this);
+        this._registered = true;
+    }
+}
+
+customElements.define('adw-layout-slot', AdwLayoutSlot);

package/src/elements/adw-multi-layout-view.ts

@@ -0,0 +1,326 @@
+// <adw-multi-layout-view> — one set of children, several arrangements of them.
+//
+// Each child has an ID, each layout has slots, each slot has an ID; switching layouts
+// re-inserts every child into the slot of the SAME ID (adw-multi-layout-view.c:16-26).
+// That is what lets a secondary pane be a sidebar in one layout and a bottom bar in
+// another without the application moving anything: the children are declared once and
+// the view decides where they sit.
+//
+// THE MARKUP FORM, because two of the three objects have no tag. `Adw.Layout` is a
+// GObject (`G_DEFINE_TYPE… G_TYPE_OBJECT`, adw-layout.c:37), so it is not in a table of
+// concrete widgets and has no element of its own; `Adw.Breakpoint`-style GObjects in this
+// package became markup children, and so does this one:
+//
+//   * a direct child carrying `name` is a LAYOUT, and that element is its content —
+//     `AdwLayout:content` is construct-only (adw-layout.c:144), so the layout IS the
+//     tree rather than a wrapper around one;
+//   * any other direct child is a CHILD, keyed by its `slot` attribute, which is the
+//     GtkBuilder `<child type="ID">` of adw-multi-layout-view.c:88;
+//   * an `<adw-layout-slot id="…">` inside a layout is where a child with that ID lands.
+//
+// Attributes:
+//   layout-name  (`Adw.MultiLayoutView:layout-name` — the name of the layout in use.
+//                Setting a name no layout carries logs the C's `g_critical` text
+//                (adw-multi-layout-view.c:520) and leaves the current layout alone.)
+//
+// Methods:
+//   `getChild(id)` — `adw_multi_layout_view_get_child` (:635).
+//   `getLayoutByName(name)` — `adw_multi_layout_view_get_layout_by_name` (:605).
+//   `registerSlot(id, slot)` — `adw_multi_layout_view_register_slot` (:682), which every
+//     `<adw-layout-slot>` calls on itself once it is rooted.
+//
+// THERE IS NO `addLayout()`, because in this port the MARKUP is `add_layout()`: the
+// declared child carrying `name` is the layout, and the first declared one is made
+// current the way `adw_multi_layout_view_add_layout` makes it (:553). An imperative list
+// beside a declarative one would be two sources for the same table, and the derived one
+// would silently win.
+//
+// Events:
+//   `notify::layout` and `notify::layout-name` (CustomEvent, bubbles,
+//     `detail = { layout }` / `{ layoutName }`) on every change — `set_layout` notifies
+//     BOTH (:263), so switching layouts is two signals even when only the name moved.
+//
+// A11Y: `role="group"`, the accessible role libadwaita installs on the class (:386).
+// `visible` is bound one way, child to slot (`G_BINDING_SYNC_CREATE` alone,
+// adw-multi-layout-view.c:151), so hiding a child hides the hole and nothing more.
+//
+// NOT PORTED: the focus save/restore around a rebuild (`rebuild_current_layout`, :200)
+// and the delayed-focus queue (`delayed_focus`, :159). Both are a GTK frame-clock
+// concern — the whole widget is snapshotted into a render node, hidden, rewritten and
+// shown on the next tick, which is what makes focus observable in between. A browser
+// element moves nodes synchronously, so focus is never lost across a layout change; the
+// consequence is that this port has nothing to restore.
+//
+// Reference: refs/libadwaita/src/adw-multi-layout-view.c
+// Reference: refs/libadwaita/src/adw-layout.c
+// Copyright (c) 2023-2024 Purism SPC / GNOME Foundation Inc. (libadwaita). LGPLv2.1+.
+// Modifications: Implemented as a Web Component for @gjsify/adwaita-web.
+
+import type { AdwLayoutSlot } from './adw-layout-slot.js';
+
+/** One layout: the element itself, plus the name `AdwLayout:name` carries. */
+interface Layout {
+    readonly name: string;
+    readonly content: Element;
+}
+
+export class AdwMultiLayoutView extends HTMLElement {
+    /** The C's own tables: layouts in order, children by id, and the current layout. */
+    private _layouts: Layout[] = [];
+    private _children = new Map<string, Element>();
+    /** `slots` — the current layout's holes, which are cleared on every rebuild. */
+    private _slots = new Map<string, AdwLayoutSlot>();
+    private _current: Layout | null = null;
+    /** `accepting_slots` — only TRUE while a layout is being mounted (:116, :690). */
+    private _acceptingSlots = false;
+    private _observer: MutationObserver | null = null;
+
+    static get observedAttributes() {
+        return ['layout-name'];
+    }
+
+    /** `adw_multi_layout_view_get_layout_name()` (:485), read under its property's name. */
+    get layoutName(): string | null {
+        return this._current?.name ?? null;
+    }
+
+    /**
+     * `adw_multi_layout_view_set_layout_name()` (:507) — writable, unlike `layout`.
+     *
+     * The property is written, not the layout: the C looks the name up and refuses a
+     * name no layout carries, and the lookup is what makes the ORDER of declaration
+     * irrelevant here.
+     */
+    set layoutName(value: string | null) {
+        if (value === null) return;
+        this.setAttribute('layout-name', value);
+    }
+
+    /** The element `Adw.MultiLayoutView:layout` points at, or null. */
+    get layout(): Element | null {
+        return this._current?.content ?? null;
+    }
+
+    connectedCallback() {
+        this.setAttribute('role', 'group');
+        // A GTK widget is a box and an unknown custom element is `inline`. libadwaita
+        // ships no rule for this widget — its CSS node is `multi-layout-view` and no
+        // partial names it — so the box model is set here rather than invented.
+        this.style.display = 'block';
+        this._observer?.disconnect();
+        // A layout or child appended after connect has to be picked up: the authored tree
+        // is the whole vocabulary of this widget, and a slot is read from the DOM.
+        this._observer = new MutationObserver(() => this._rebuild());
+        this._observer.observe(this, { childList: true });
+        this._rebuild();
+    }
+
+    disconnectedCallback() {
+        this._observer?.disconnect();
+        this._observer = null;
+    }
+
+    attributeChangedCallback(name?: string) {
+        if (!this.isConnected || name !== 'layout-name') return;
+        this._setLayoutByName(this.getAttribute('layout-name'));
+    }
+
+    /** `adw_multi_layout_view_get_child(id)` (:635). */
+    getChild(id: string): Element | null {
+        return this._children.get(id) ?? null;
+    }
+
+    /** `adw_multi_layout_view_get_layout_by_name(name)` (:605). */
+    getLayoutByName(name: string): Element | null {
+        return this._layouts.find((layout) => layout.name === name)?.content ?? null;
+    }
+
+    /**
+     * `adw_multi_layout_view_add_layout()` (:538), over the declared children.
+     *
+     * The rules it carries are the ones a reader of the markup would otherwise have to
+     * infer: the FIRST layout becomes current when the list is built (:553), and a
+     * duplicate name is a warning rather than a shadowed entry (:549).
+     */
+
+    /**
+     * `adw_multi_layout_view_register_slot()` (:682), called by every `<adw-layout-slot>`
+     * that becomes rooted.
+     *
+     * Refused outside a mount, which is what `accepting_slots` is for: a slot in a layout
+     * that is not current has no business in the table.
+     *
+     * A REPEAT registration by the SAME element is not a duplicate and says nothing. A DOM
+     * move fires `connectedCallback` again — and moving a slot is ordinary here, because
+     * the container it sits in re-homes its own slotted children when it builds its
+     * internals. `g_hash_table_insert` upstream would overwrite with the same pointer, so
+     * the C never notices; the warning is for two DIFFERENT slots under one ID, and
+     * reporting a re-registration would train a reader to ignore it (adw-multi-layout-view.c:693).
+     */
+    registerSlot(id: string, slot: AdwLayoutSlot): void {
+        if (!this._acceptingSlots) return;
+        if (this._slots.get(id) === slot) return;
+        if (this._slots.has(id)) {
+            console.warn(`Duplicate slot ID in AdwLayout ${this.layoutName}: ${id}`);
+            return;
+        }
+        this._slots.set(id, slot);
+    }
+
+    /**
+     * Read the authored tree and mount the layout it names.
+     *
+     * A direct child with `name` is a layout; anything else is a child, keyed by `slot`.
+     * Reading it from the DOM rather than from a list is what makes a child appended
+     * after connect work, which is the whole of `bindSlottedChildren`'s contract for the
+     * elements that use it.
+     */
+    private _rebuild(): void {
+        if (!this.isConnected) return;
+        // THE MOUNT IS A CHILD-LIST CHANGE OF THIS ELEMENT, and re-reading it is a loop:
+        // `_rebuild` → `_mount` → `replaceChildren` → a record → `_rebuild` → … The
+        // observer is therefore OFF for the duration, which drops those records and any
+        // the previous mount already queued, and re-armed below. Without this the widget
+        // spins a microtask cycle forever and takes the page with it — measured, and the
+        // measurement is why this is a comment rather than a boolean.
+        this._observer?.disconnect();
+        try {
+            this._readAuthoredTree();
+        } finally {
+            if (this.isConnected) this._observer?.observe(this, { childList: true });
+        }
+    }
+
+    /** The C's three tables, read off the declared children. */
+    private _readAuthoredTree(): void {
+        const layouts: Layout[] = [];
+        // ACCUMULATED, not replaced: while a layout is mounted the children this view has
+        // taken into its slots are no longer children of the HOST, so a fresh map would
+        // drop every one of them and the next mount would parent nothing. `set_child`
+        // upserts by id too (adw-multi-layout-view.c:675).
+        for (const node of Array.from(this.children)) {
+            const name = node.getAttribute('name');
+            if (name !== null) {
+                layouts.push({ name, content: node });
+                continue;
+            }
+            const id = node.getAttribute('slot');
+            // No `slot=` is the DEFAULT child, and GtkBuilder's `<child>` with no type
+            // is a deprecation warning upstream (adw-breakpoint-bin.c:679 is the same
+            // rule for the bin); this port keeps the node where it is rather than
+            // losing it, which is the browser shape of "not our child".
+            if (id === null || id === '') continue;
+            if (this._children.has(id)) {
+                // `set_child` replaces the child of an id rather than adding a second.
+                console.warn(`While adding child: duplicate slot ${id} in AdwMultiLayoutView; kept the first`);
+            }
+            this._children.set(id, node);
+        }
+        this._layouts = layouts;
+        const wanted = this.getAttribute('layout-name');
+        // A declared `layout-name` is `set_layout_name`, which REFUSES a name no layout
+        // carries rather than falling back; an absent one takes the first, which is what
+        // `add_layout` makes current when the list is built (:553).
+        if (wanted !== null) this._setLayoutByName(wanted);
+        else this._setLayout(layouts[0] ?? null);
+    }
+
+    /** `set_layout()` (:252): the same layout is not a change, and both properties notify. */
+    private _setLayout(layout: Layout | null): void {
+        if (layout === this._current) {
+            // A rebuild still has to re-mount: the content's slots are rebuilt from the
+            // DOM every time, so `_current` being unchanged says nothing about the tree.
+            if (layout !== null) this._mount(layout);
+            return;
+        }
+        this._current = layout;
+        if (layout === null) this._destroy();
+        else this._mount(layout);
+        this.dispatchEvent(new CustomEvent('notify::layout', { bubbles: true, detail: { layout: this.layoutName } }));
+        this.dispatchEvent(
+            new CustomEvent('notify::layout-name', { bubbles: true, detail: { layoutName: this.layoutName } }),
+        );
+    }
+
+    /**
+     * `set_layout_name()` (:507): look the name up, refuse an unknown one, then switch.
+     *
+     * The refusal is C's, in its own shape — `g_critical` and `return`, with no call to
+     * `set_layout` at all (:519), so the current layout is UNCHANGED rather than emptied.
+     * That is why the lookup is not folded into `_setLayout`: it answers the question
+     * first, and an unknown name is not a switch to nothing.
+     */
+    private _setLayoutByName(name: string | null): void {
+        if (name === null) return;
+        const layout = this._layouts.find((candidate) => candidate.name === name);
+        if (layout === undefined) {
+            console.error(`Layout name '${name}' not found in AdwMultiLayoutView`);
+            return;
+        }
+        this._setLayout(layout);
+    }
+
+    /**
+     * `destroy_current_layout()` (:192): forget every slot and unparent the content.
+     *
+     * The children are simply LEFT, which is what upstream does: a child whose id the
+     * OUTGOING layout had no slot for is not unparented by `unparent_child`
+     * (adw-multi-layout-view.c:175) and rides out with the content it was in. They stay
+     * alive in `_children`, which is where this port remembers the declaration.
+     */
+    private _destroy(): void {
+        this._slots.clear();
+        this.replaceChildren();
+    }
+
+    /**
+     * `rebuild_current_layout()` (:200), minus the render-node snapshot.
+     *
+     * The do/while is C's own: parenting a child can root a slot of its own, which grows
+     * the table, which may make another child land. `slotCount` is what the loop compares
+     * against — the C's `g_hash_table_size`.
+     */
+    private _mount(layout: Layout): void {
+        this._destroy();
+        this._acceptingSlots = true;
+        // APPENDED, not `replaceChildren`: `_destroy` has already emptied the host, and
+        // an unmatched child must not be a reason to drop the layout on the floor.
+        this.appendChild(layout.content);
+        // Re-register what is already in the mounted layout's own subtree, then let each
+        // child's mount register more. The loop is `old_size` again.
+        for (;;) {
+            const before = this._slots.size;
+            for (const slot of layout.content.querySelectorAll('adw-layout-slot')) {
+                const id = slot.getAttribute('id');
+                if (id !== null && id !== '' && !this._slots.has(id)) this.registerSlot(id, slot as AdwLayoutSlot);
+            }
+            for (const [id, child] of this._children) this._parent(id, child);
+            if (this._slots.size === before) break;
+        }
+        this._acceptingSlots = false;
+    }
+
+    /** `parent_child()` (:136): bind `visible`, then insert. */
+    private _parent(id: string, child: Element): void {
+        const slot = this._slots.get(id);
+        if (slot === undefined) return;
+        if (child.parentElement === slot) return;
+        this._mirrorVisible(slot, child);
+        slot.appendChild(child);
+    }
+
+    /**
+     * The one-way `visible` binding (:151), which CSS cannot express: the SLOT follows
+     * the CHILD. `hidden` is observed rather than polled so a child hidden AFTER it
+     * landed still hides the hole.
+     */
+    private _mirrorVisible(slot: Element, child: Element): void {
+        const apply = () => {
+            slot.toggleAttribute('hidden', (child as HTMLElement).hidden === true);
+        };
+        apply();
+        new MutationObserver(apply).observe(child, { attributes: true, attributeFilter: ['hidden'] });
+    }
+}
+
+customElements.define('adw-multi-layout-view', AdwMultiLayoutView);