@gjsify/adwaita-web 0.53.0 → 0.55.0

package/src/elements/adw-breakpoint-bin.ts

@@ -0,0 +1,287 @@
+// <adw-breakpoint-bin> — a bin whose one child rearranges itself at size thresholds.
+// `Adw.BreakpointBin` gives breakpoints a home without a window: it holds a list of
+// `Adw.Breakpoint`s, and on every allocation the LAST one whose condition holds is
+// picked and its setters written. If none holds, the child's original values stand.
+//
+// The picking, the restore order and what a restore restores to are all
+// `@gjsify/adwaita-core`'s `BreakpointBinState` (ADR 0004), driven from real
+// `ResizeObserver` deliveries — the four rules it encodes are quoted at the top of
+// `packages/web/adwaita-core/src/breakpoint-bin.ts`, each with its `file:lines`.
+//
+// WHAT THE ATTRIBUTE CARRIES. `Adw.Breakpoint` is a GObject, not a widget, and
+// `adw_breakpoint_bin_add_breakpoint()` is the whole API — so a browser port needs a
+// MARKUP form and there is no GIR property for one. `breakpoints` is a JSON array of
+// `{ condition, setters: [{ target, property, value }] }`:
+//
+//   * `condition` is an Adwaita condition string, parsed by the same grammar as every
+//     other breakpoint in this package (`max-width: 720px`).
+//   * `target` is a CSS selector for a DESCENDANT. The C says it in the docs —
+//     "Breakpoints are only allowed to modify widgets inside the AdwBreakpointBin, but
+//     not on the AdwBreakpointBin itself" — and the selector cannot escape the subtree
+//     because it is resolved with `querySelector` on this element.
+//   * `property` is an ATTRIBUTE name and `value` its value. An attribute is the only
+//     thing a browser can write on another custom element portably, and this package's
+//     own properties ARE attributes (`<adw-label label>` above).
+//   * `originalValue` is read ONCE, when the setter is registered, exactly as
+//     `g_object_get_property` is at `adw_breakpoint_add_setter` (adw-breakpoint.c:1627).
+//     An attribute the element did not have is restored by REMOVING it.
+//
+// `Adw.BreakpointBin` also measures itself differently once it holds a breakpoint:
+// `adw_breakpoint_bin_measure` forces its MINIMUM to 0 (:388) and
+// `adw_breakpoint_bin_get_request_mode` answers CONSTANT_SIZE (:362). That is the
+// documented rule — "Adding a breakpoint to AdwBreakpointBin will result in it having
+// no minimum size" — and it is why the element sets `min-width`/`min-height` to 0 and
+// `overflow: hidden` (the C's own `gtk_widget_set_overflow(…, GTK_OVERFLOW_HIDDEN)`,
+// :669) while a `breakpoints` attribute is present.
+//
+// Attributes:
+//   breakpoints  (JSON — the breakpoints to add, in ORDER: a later one beats an earlier
+//                  one when both match. `current-breakpoint` is reported as the index.)
+//
+// Events:
+//   `notify::current-breakpoint` (CustomEvent, bubbles, `detail = { currentBreakpoint }`)
+//     when the picked breakpoint changes — mirrors the GObject property of that name,
+//     which is read-only and notified on every change (adw-breakpoint-bin.c:477).
+//   `breakpoint-unapply` (CustomEvent, bubbles, `detail = { index }`) BEFORE the writes,
+//     `breakpoint-apply` (CustomEvent, bubbles, `detail = { index }`) AFTER them — the
+//     order of `adw_breakpoint_transition` (adw-breakpoint.c:1793, :1819). A listener on
+//     the apply end therefore sees the INCOMING values and one on the unapply end the
+//     OUTGOING ones; neither ever sees the restore in between.
+//
+// A11Y: `role="group"`. There is no box of its own: GTK clips overflow and gives the
+// child the allocation, which a light-DOM passthrough already is.
+//
+// NOT PORTED: `adw_breakpoint_bin_set_pass_through()` (:893). It makes `contains()`
+// return FALSE so the bin claims no event of its own (adw-breakpoint-bin.c:327); a
+// browser has no `contains` override for that, and the property is private API besides.
+// `adw_breakpoint_bin_set_natural_size()` (:906) and
+// `adw_breakpoint_bin_set_warnings()` (:853) are the same shape — private helpers with
+// no GIR property, no attribute, and nothing for a page to set.
+//
+// Reference: refs/libadwaita/src/adw-breakpoint-bin.c
+// Reference: refs/libadwaita/src/adw-breakpoint.c (adw_breakpoint_transition)
+// Copyright (c) 2023 Purism SPC (libadwaita). LGPLv2.1+.
+// Modifications: Implemented as a Web Component for @gjsify/adwaita-web.
+
+import { BreakpointBinState } from '@gjsify/adwaita-core';
+import type { BreakpointSetter } from '@gjsify/adwaita-core';
+
+import { observeAdaptiveSize } from '../breakpoints.js';
+
+/** One authored setter, as it reads in the `breakpoints` attribute. */
+interface AuthoredSetter {
+    readonly target: string;
+    readonly property: string;
+    readonly value: string;
+}
+
+/** One authored breakpoint, as it reads in the `breakpoints` attribute. */
+interface AuthoredBreakpoint {
+    readonly condition: string;
+    readonly setters: readonly AuthoredSetter[];
+}
+
+/** `breaks` parsed, or `[]` for anything that is not an array of breakpoints. */
+function parseBreakpoints(raw: string | null): AuthoredBreakpoint[] {
+    if (!raw) return [];
+    let parsed: unknown;
+    try {
+        parsed = JSON.parse(raw);
+    } catch {
+        // A typo in a condition must not empty the bin: `adw_breakpoint_check_condition`
+        // returns FALSE for an unparseable condition (adw-breakpoint.c:1831), so C drops
+        // that ONE breakpoint. Silently losing all of them would be a different widget.
+        console.error('<adw-breakpoint-bin>: `breakpoints` is not JSON; no breakpoint is applied.');
+        return [];
+    }
+    if (!Array.isArray(parsed)) return [];
+    return parsed.flatMap((entry) => {
+        if (typeof entry !== 'object' || entry === null) return [];
+        const { condition, setters } = entry as Partial<AuthoredBreakpoint>;
+        if (typeof condition !== 'string') return [];
+        return [{ condition, setters: Array.isArray(setters) ? setters : [] }];
+    });
+}
+
+export class AdwBreakpointBin extends HTMLElement {
+    /** The C's own structure: a list of breakpoints, and at most one picked. */
+    private _state = new BreakpointBinState<Element>();
+    private _dispose: (() => void) | undefined;
+    /**
+     * What the last binding applied, carried across every rebind.
+     *
+     * `BreakpointBinState.inherit` exists for exactly this and its docblock records the
+     * measurement: a browser element rebinds on every `connectedCallback`, and a bin that
+     * restarts at "none applied" reads the size that LEFT the old breakpoint's range as
+     * no change at all and leaves the child holding what the old bin wrote.
+     */
+    private _applied: number | null = null;
+    /** Registration is deferred to the first allocation; see `_observe`. */
+    private _pendingSync = false;
+    /**
+     * What each setter's target held when the setter was FIRST registered, keyed by
+     * target + property + value.
+     *
+     * Carried across a REBIND because a rebind is not a re-registration. Upstream
+     * `adw_breakpoint_add_setter` captures the original once, at the call
+     * (`g_object_get_property`, adw-breakpoint.c:1627), and the widget outlives every
+     * resize; a browser element rebinds on every connect, and re-reading the original
+     * then would capture the value the OUTGOING breakpoint had already written — so the
+     * restore would write back the applied value and the widget would never recover.
+     * Measured: a bin applied at 400px, moved to a 500px parent and widened to 900px
+     * kept its narrow label for good.
+     *
+     * Cleared when the AUTHOR rewrites `breakpoints`, which is a new
+     * `add_breakpoint`/`add_setters` sequence and captures new originals.
+     */
+    private _originals = new Map<string, string | null>();
+
+    static get observedAttributes() {
+        return ['breakpoints'];
+    }
+
+    /** `Adw.BreakpointBin:current-breakpoint` — the picked index, or null. Read-only. */
+    get currentBreakpoint(): number | null {
+        return this._state.current;
+    }
+
+    /** `adw_breakpoint_bin_get_current_breakpoint()` (:841), under its property name. */
+    get currentBreakpointAttribute(): string | null {
+        const current = this._state.current;
+        return current === null ? null : String(current);
+    }
+
+    /** `Adw.BreakpointBin:child` — the bin has one child, the one every breakpoint writes. */
+    get child(): Element | null {
+        return this.firstElementChild;
+    }
+
+    connectedCallback() {
+        this.setAttribute('role', 'group');
+        // A GTK widget is a box and an unknown custom element is `inline`, which measures
+        // zero — and a bin measuring zero matches every condition forever. libadwaita
+        // ships no rule for this widget, so the box model is set here rather than
+        // invented in a partial.
+        this.style.display = 'block';
+        this._syncSizing();
+        // Registration waits for the first allocation: `connectedCallback` of a bin fires
+        // while its OWN markup is still being parsed, so `#caption` below it does not
+        // exist yet and a setter resolved here would be dropped rather than restored.
+        // `ResizeObserver` delivers its first observation after layout, by which time the
+        // tree is whole and nothing has been written yet — so the originals are still the
+        // ones `adw_breakpoint_add_setter` would have captured.
+        this._pendingSync = true;
+        this._observe();
+    }
+
+    disconnectedCallback() {
+        this._dispose?.();
+        this._dispose = undefined;
+    }
+
+    attributeChangedCallback(name?: string) {
+        if (name !== 'breakpoints' || !this.isConnected) return;
+        // The tree IS whole by the time anything rewrites the attribute, so a change
+        // registers immediately rather than one allocation later — and it is a NEW
+        // sequence of `add_breakpoint` calls, so the originals are captured afresh.
+        this._originals.clear();
+        this._syncBreakpoints();
+    }
+
+    /**
+     * Rebuild the state from the attribute, keeping the applied breakpoint.
+     *
+     * The originals are read on the way, because `inherit` restores what the NEW
+     * definitions captured: a restore read off a child the outgoing breakpoint already
+     * changed would restore it to the applied value, which is no restore at all.
+     */
+    private _syncBreakpoints(): void {
+        this._pendingSync = false;
+        const authored = parseBreakpoints(this.getAttribute('breakpoints'));
+        this._state = new BreakpointBinState<Element>();
+        for (const breakpoint of authored) {
+            const setters: BreakpointSetter<Element>[] = [];
+            for (const setter of breakpoint.setters) {
+                if (typeof setter?.target !== 'string' || typeof setter.property !== 'string') continue;
+                const target = this.querySelector(setter.target);
+                // An unmatched selector is a setter that would write to nothing; C's
+                // `add_setters` needs a live object and refuses one that is not.
+                if (target === null) continue;
+                const key = `${setter.target}\u0000${setter.property}\u0000${setter.value}`;
+                if (!this._originals.has(key)) this._originals.set(key, target.getAttribute(setter.property));
+                setters.push({
+                    object: target,
+                    property: setter.property,
+                    value: setter.value,
+                    originalValue: this._originals.get(key) ?? null,
+                });
+            }
+            this._state.add({ condition: breakpoint.condition, setters });
+        }
+        this._state.inherit(this._applied);
+        this._state.setHasChild(this.child !== null);
+        this._write(this._state.current);
+        this._syncSizing();
+    }
+
+    /**
+     * The size source. `ResizeObserver` delivers an initial observation, so the pick is
+     * settled before first paint — the same seam `src/breakpoints.ts` gives every other
+     * adaptive element, re-created on every connect so a widget MOVED between parents
+     * tracks its conditions again.
+     *
+     * The CHILD is read here rather than cached, because
+     * `adw_breakpoint_bin_size_allocate` tests it on every allocation (:427) and a child
+     * appended after connect is then a child.
+     */
+    private _observe(): void {
+        this._dispose?.();
+        this._dispose = observeAdaptiveSize(this, (size) => {
+            if (this._pendingSync) this._syncBreakpoints();
+            this._state.setHasChild(this.child !== null);
+            const transition = this._state.evaluate(size);
+            if (transition === null) return;
+            this._emit(transition.from, 'breakpoint-unapply');
+            this._perform(transition.writes);
+            this._write(transition.to);
+            this._emit(transition.to, 'breakpoint-apply');
+            this.dispatchEvent(
+                new CustomEvent('notify::current-breakpoint', {
+                    bubbles: true,
+                    detail: { currentBreakpoint: this.currentBreakpointAttribute },
+                }),
+            );
+        });
+    }
+
+    private _perform(writes: readonly { object: Element; property: string; value: unknown }[]): void {
+        for (const write of writes) {
+            // A `null` original is an attribute that was ABSENT, and `removeAttribute`
+            // is its restore — the one that makes unapply the exact inverse of apply.
+            if (write.value === null) write.object.removeAttribute(write.property);
+            else write.object.setAttribute(write.property, String(write.value));
+        }
+    }
+
+    private _write(index: number | null): void {
+        this._applied = index;
+    }
+
+    private _emit(index: number | null, type: string): void {
+        if (index === null) return;
+        this.dispatchEvent(new CustomEvent(type, { bubbles: true, detail: { index } }));
+    }
+
+    /** The measure rules of a bin that holds breakpoints (:356, :388, :669). */
+    private _syncSizing(): void {
+        const adaptive = this._state.length > 0;
+        // `display` and the clip are left to the author's stylesheet on purpose: the
+        // MINIMUM is the documented rule, and writing `display` from here would fight a
+        // host page that lays the bin out in a grid.
+        this.style.minWidth = adaptive ? '0px' : '';
+        this.style.minHeight = adaptive ? '0px' : '';
+        if (adaptive) this.style.overflow = 'hidden';
+    }
+}
+
+customElements.define('adw-breakpoint-bin', AdwBreakpointBin);

package/src/elements/adw-clamp-scrollable.ts

@@ -0,0 +1,207 @@
+// <adw-clamp-scrollable> — the CLAMP whose child scrolls, and the widget
+// `AdwClamp`'s own header points at for anything that must scroll inside a readable
+// width (`adw-clamp-scrollable.c:20-27`: "The primary use case for AdwClampScrollable is
+// clamping Gtk.ListView").
+//
+// SAME ARITHMETIC AS `<adw-clamp>`, both halves of it: the allocation is
+// `clampAllocate` out of `@gjsify/adwaita-core` — `lower`/`max`/`upper`, the
+// ease-out-cubic tightening region and the `small`/`medium`/`large` class stamped on the
+// CHILD — reached through `normalizeClampSize` and the `AdwLengthUnit` conversion
+// `adw-clamp-layout.c:166-171` does per property. The difference is the ORIENTATION and
+// the scrolling.
+//
+// THE ORIENTATION IS THE WIDGET, NOT THE CLAMP'S. `set_orientation` forwards to the
+// layout manager (adw-clamp-scrollable.c:78-92) and the cap lands on the width for a
+// horizontal clamp and on the HEIGHT for a vertical one
+// (`child_size_from_clamp` measures along `self->orientation`). A vertical clamp
+// therefore centres on the block axis here, where `<adw-clamp>` has no axis to pick.
+//
+// THE SCROLLING MOVES FROM THE CHILD TO THE HOST, and that is the one deviation worth
+// naming. In C the child IS the `Gtk.Scrollable`: the widget binds its `hadjustment`,
+// `vadjustment`, `hscroll-policy` and `vscroll-policy` onto it
+// (adw-clamp-scrollable.c:440-455) and a child that is not scrollable is four
+// `gbinding` warnings at exit 0. A DOM element cannot hand its scrolling to a child that
+// does not know it is inside one, so the scrollport is this element (`overflow`) and the
+// child is what gets capped — the same visible contract, one level up. `hscroll-policy`
+// and `vscroll-policy` therefore land on the HOST's overflow, which is where the C's
+// policy ultimately decided whether the child ever scrolled.
+//
+// `hadjustment`/`vadjustment` have no attribute here: they are `Gtk.Adjustment`
+// objects (a widget-valued property on every renderer), and the browser's scroll
+// position is its own `scrollTop`/`scrollLeft`. That is a PORT-ONLY gap against the
+// `Gtk.Scrollable` interface rather than against `AdwClampScrollable`'s own property
+// list, which is why `check-adwaita-element-properties.mjs` has no entry for it.
+//
+// A11Y: no role. `adw_clamp_scrollable_class_init` sets none.
+//
+// Reference: refs/libadwaita/src/adw-clamp-scrollable.c (set_orientation, set_child,
+//   the four adjustment bindings, class_init's layout manager + `clamp` node)
+// Reference: refs/libadwaita/src/adw-clamp-layout.c (child_size_from_clamp, allocate)
+// Copyright (c) 2020 Purism SPC / GNOME contributors (libadwaita). LGPLv2.1+.
+// Modifications: Implemented as a Web Component for @gjsify/adwaita-web.
+
+import {
+    ADW_CLAMP_DEFAULTS,
+    ADW_CLAMP_SIZE_CLASSES,
+    type AdwLengthUnit,
+    adwLengthToPx,
+    clampAllocate,
+    normalizeBoxOrientation,
+    normalizeClampSize,
+    normalizeLengthUnit,
+    type BoxOrientation,
+} from '@gjsify/adwaita-core';
+
+import { bindSlottedChildren } from '../slotted-children.js';
+
+/** `Gtk.ScrollablePolicy`'s three nicks, in enum order. */
+export type ScrollPolicy = 'automatic' | 'always' | 'never';
+
+/** `adw_scrollable_policy_to_overflow` — the policy as the CSS `overflow` keyword. */
+const POLICY_OVERFLOW: Record<ScrollPolicy, string> = {
+    automatic: 'auto',
+    always: 'scroll',
+    never: 'hidden',
+};
+
+export class AdwClampScrollable extends HTMLElement {
+    private _resize: ResizeObserver | null = null;
+    private _mutations: MutationObserver | null = null;
+
+    static get observedAttributes() {
+        return ['maximum-size', 'tightening-threshold', 'unit', 'orientation', 'hscroll-policy', 'vscroll-policy'];
+    }
+
+    /** `AdwClampScrollable:maximum-size` — the cap, in `unit`. Default 600. */
+    get maximumSize(): number {
+        return normalizeClampSize(this.getAttribute('maximum-size'), ADW_CLAMP_DEFAULTS.maximumSize);
+    }
+
+    set maximumSize(value: number) {
+        this.setAttribute('maximum-size', String(value));
+    }
+
+    /** `AdwClampScrollable:tightening-threshold` — where the easing starts. Default 400. */
+    get tighteningThreshold(): number {
+        return normalizeClampSize(this.getAttribute('tightening-threshold'), ADW_CLAMP_DEFAULTS.tighteningThreshold);
+    }
+
+    set tighteningThreshold(value: number) {
+        this.setAttribute('tightening-threshold', String(value));
+    }
+
+    /** `AdwClampScrollable:unit` — the length unit both sizes are written in. Default `sp`. */
+    get unit(): AdwLengthUnit {
+        return normalizeLengthUnit(this.getAttribute('unit'), 'sp');
+    }
+
+    set unit(value: AdwLengthUnit) {
+        this.setAttribute('unit', value);
+    }
+
+    /** `GtkOrientable:orientation`, which this class overrides. Default horizontal. */
+    get orientation(): BoxOrientation {
+        return normalizeBoxOrientation(this.getAttribute('orientation'));
+    }
+
+    set orientation(value: BoxOrientation) {
+        this.setAttribute('orientation', value);
+    }
+
+    connectedCallback() {
+        // `AdwClampScrollable:child` is a widget PROPERTY, so a `.blp`'s `child: …`
+        // authors `slot="child"`. Every child here is already the content, so only the
+        // NAME is enrolled — the reason `adw-clamp.ts` gives for not calling
+        // `.install()`.
+        bindSlottedChildren(this, [{ name: 'child', into: this }]);
+
+        // ResizeObserver delivers an initial observation on `observe()`, so the first
+        // allocation lands before paint without a seeding pass.
+        this._resize = new ResizeObserver(() => this._allocate());
+        this._resize.observe(this);
+        // A child appended after connect is capped too; without this it keeps whatever
+        // width it arrived with.
+        this._mutations = new MutationObserver(() => this._allocate());
+        this._mutations.observe(this, { childList: true });
+
+        this._applyOverflow();
+        this._allocate();
+    }
+
+    disconnectedCallback() {
+        this._resize?.disconnect();
+        this._resize = null;
+        this._mutations?.disconnect();
+        this._mutations = null;
+    }
+
+    attributeChangedCallback() {
+        this._applyOverflow();
+        this._allocate();
+    }
+
+    /**
+     * `Gtk.Scrollable:hscroll-policy` / `vscroll-policy` — the two overrides the class
+     * re-declares (adw-clamp-scrollable.c:118-141) and then binds onto the child. They
+     * decide here whether this element scrolls at all, which is the question they answer
+     * in C.
+     */
+    private _applyOverflow(): void {
+        const horizontal = this.getAttribute('hscroll-policy') as ScrollPolicy | null;
+        const vertical = this.getAttribute('vscroll-policy') as ScrollPolicy | null;
+        this.style.overflowX = horizontal === null ? 'auto' : (POLICY_OVERFLOW[horizontal] ?? 'auto');
+        this.style.overflowY = vertical === null ? 'auto' : (POLICY_OVERFLOW[vertical] ?? 'auto');
+    }
+
+    /**
+     * `adw_clamp_layout_allocate`, against the AVAILABLE size on the clamped axis.
+     *
+     * The cap sits on the CHILD, never here: this element is the scrollport, so a cap on
+     * itself would feed its own capped width back into its ResizeObserver — a feedback
+     * loop rather than a measurement (the reasoning `<adw-clamp>` carries in full).
+     */
+    private _allocate(): void {
+        const vertical = this.orientation === 'vertical';
+        const unit = this.unit;
+        const available = vertical ? this.clientHeight : this.clientWidth;
+
+        // `childMin` is 0, as in `<adw-clamp>`: a child that declares a minimum keeps it
+        // (CSS 2.1 §10.4 lets `min-*` beat `max-*`), and one that declares none has a
+        // minimum of 0 — the value a synchronous re-measure would arrive at anyway.
+        const params = {
+            maximumSize: adwLengthToPx(unit, this.maximumSize),
+            tighteningThreshold: adwLengthToPx(unit, this.tighteningThreshold),
+            childMin: 0,
+            childNat: 0,
+        };
+
+        for (const child of Array.from(this.children) as HTMLElement[]) {
+            if (available <= 0) {
+                // GTK's equivalent is `for_size = -1`: leave the child alone rather than
+                // capping it at 0 and collapsing the page.
+                child.style.maxWidth = '';
+                child.style.maxHeight = '';
+                child.style.marginInline = '';
+                child.style.marginBlock = '';
+                for (const cls of ADW_CLAMP_SIZE_CLASSES) child.classList.remove(cls);
+                continue;
+            }
+
+            const { childSize, sizeClass } = clampAllocate(available, params);
+            if (vertical) {
+                child.style.maxWidth = '';
+                child.style.maxHeight = `${childSize}px`;
+                child.style.marginInline = '';
+                child.style.marginBlock = 'auto';
+            } else {
+                child.style.maxWidth = `${childSize}px`;
+                child.style.maxHeight = '';
+                child.style.marginInline = 'auto';
+                child.style.marginBlock = '';
+            }
+            for (const cls of ADW_CLAMP_SIZE_CLASSES) child.classList.toggle(cls, cls === sizeClass);
+        }
+    }
+}
+
+customElements.define('adw-clamp-scrollable', AdwClampScrollable);

package/src/elements/adw-dialog.ts

@@ -19,6 +19,12 @@
 // Events, all bubbling CustomEvents: `notify::open` (detail `{ open }`), `closed`
 // (Adw.Dialog::closed), `close-attempt` (Adw.Dialog::close-attempt).
 //
+// SUBCLASSING: `decorateHeader(header)` is the one hook, and it exists for
+// `<gtk-about-dialog>`, whose headerbar carries a stack switcher in the title position
+// instead of a title (gtkaboutdialog.ui). Chrome, focus, Escape and dismissal stay here,
+// so a subclass that wants a different header adds to this one rather than building a
+// second scrim.
+//
 // Reference: refs/libadwaita/src/adw-dialog.c (present/close/can-close, Escape, focus)
 // Reference: refs/libadwaita/src/stylesheet/widgets/_dialogs.scss (floating sheet + bottom sheet)
 // Copyright (c) 2023-2024 GNOME Foundation Inc. (libadwaita). LGPLv2.1+.
@@ -223,6 +229,17 @@ export class AdwDialog extends HTMLElement {
         this._modal.dismiss();
     }
 
+    /**
+     * Add to the header bar, called at the end of every render.
+     *
+     * The hook is for a DIALOG whose header is not a title plus a close button, which is
+     * what `<gtk-about-dialog>` needs: `gtkaboutdialog.ui` puts a `GtkStackSwitcher` in
+     * the titlebar's title-widget position and no title text at all. An empty body is the
+     * default, so every other dialog is unaffected — and the header element is the one
+     * the base already owns, so a subclass never reaches into private state to get it.
+     */
+    protected decorateHeader(_header: HTMLElement): void {}
+
     private _render(): void {
         this.classList.toggle('open', this.open);
 
@@ -244,6 +261,8 @@ export class AdwDialog extends HTMLElement {
         const locked = !this.canClose;
         this._closeBtn.disabled = locked;
         this._closeBtn.classList.toggle('locked', locked);
+
+        this.decorateHeader(this._headerEl);
     }
 }
 

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);