@gjsify/adwaita-web 0.64.1 → 0.64.2-next.252

package/src/elements/adw-toast-overlay.ts

@@ -2,44 +2,34 @@
 // content and shows transient toast strips (title, optional action button, close
 // affordance) layered over the bottom of its own bounds.
 //
-// The QUEUE — the one-at-a-time policy, FIFO ordering and auto-dismiss lifecycle —
-// is HEADLESS and lives in `@gjsify/adwaita-core` (ADR 0004) as {@link AdwToastQueue};
-// this element composes it and keeps only the DOM half: build the strip on `onShow`,
-// tear it down on `onHide`, run the enter/exit transitions.
+// A toast is an `Adw.Toast` and goes in through `add_toast(toast)`, exactly as on GTK, so a
+// GNOME app's toast code runs here unchanged. The QUEUE — one toast at a time, priority,
+// re-add, auto-dismiss — is HEADLESS and lives in `@gjsify/adwaita-core` (ADR 0004) as
+// {@link ToastOverlayQueue}; this element keeps only the DOM half: build the strip on
+// `onShow`, tear it down on `onHide`, run the enter/exit transitions.
 //
 // Adapted from Adwaita Web UI Framework (https://github.com/mclellac/adwaita-web).
 // Reference: refs/adwaita-web/adwaita-web/scss/_toast.scss, _toast_overlay.scss
-// Reference: refs/libadwaita/src/adw-toast-overlay.c, adw-toast.c (add_toast queues,
-//   one toast is shown at a time, dismissing advances to the next)
+// Reference: refs/libadwaita/src/adw-toast-overlay.c, adw-toast-widget.c (add_toast queues,
+//   one toast is shown at a time, the button emits button-clicked, activates the action and
+//   dismisses)
 // Copyright (c) 2025 csm (adwaita-web). MIT License.
 // Copyright (c) GNOME contributors (libadwaita). LGPLv2.1+.
-// Modifications: Reimplemented as Web Component for @gjsify/adwaita-web;
-// extended addToast() with action button + close button + options API; the
+// Modifications: Reimplemented as Web Component for @gjsify/adwaita-web; the
 // queue/auto-dismiss state machine composed from @gjsify/adwaita-core.
 
-import { AdwToast, AdwToastQueue } from '@gjsify/adwaita-core';
+import { ToastOverlayQueue } from '@gjsify/adwaita-core';
 
+import { activateWidgetAction } from '../application.js';
+import { renderPangoMarkup } from '../pango-markup.js';
 import { bindSlottedChildren } from '../slotted-children.js';
 import { createGtkImage } from './gtk-image.js';
-import type { ToastScheduler, ToastTimerHandle } from '@gjsify/adwaita-core';
+import type { Toast, ToastScheduler, ToastTimerHandle } from '@gjsify/adwaita-core';
 
 // The timing seam is re-exported so a consumer can type a custom scheduler for
 // {@link AdwToastOverlay.scheduler} without depending on the core package.
 export type { ToastScheduler, ToastTimerHandle } from '@gjsify/adwaita-core';
 
-/** Options for {@link AdwToastOverlay.addToast}, mirroring Adw.Toast's properties. */
-export interface AdwToastOptions {
-    /** Seconds before the toast auto-dismisses; `0` keeps it until dismissed. Mirrors Adw.Toast:timeout (default 5). */
-    timeout?: number;
-    /** Label for the action button; omitted/empty means no button. Mirrors Adw.Toast:button-label. */
-    buttonLabel?: string;
-    /** Invoked when the action button is pressed. Mirrors the activation of Adw.Toast:action-name. */
-    onAction?: () => void;
-}
-
-/** Default toast lifetime in SECONDS — this element's public unit (Adw.Toast:timeout). */
-const DEFAULT_TIMEOUT_SECONDS = 5;
-
 /**
  * Fallback budget in ms for the exit transition: must stay at or above the
  * `.adw-toast.hiding` transition-duration in `_toast.scss` (0.15s today), because it
@@ -56,18 +46,16 @@ const domScheduler: ToastScheduler = {
 export class AdwToastOverlay extends HTMLElement {
     private _toasts!: HTMLDivElement;
     private _initialized = false;
-    /** The headless one-at-a-time + FIFO + auto-dismiss state machine (ADR 0004). */
-    private readonly _queue: AdwToastQueue;
+    /** The headless queue of `adw-toast-overlay.c` (ADR 0004). */
+    private readonly _queue: ToastOverlayQueue;
     /** The timing source the queue's auto-dismiss runs on — swappable, see {@link scheduler}. */
     private _scheduler: ToastScheduler = domScheduler;
-    /** The strip currently mounted for {@link AdwToastQueue.current}, if any. */
+    /** The strip currently mounted for {@link ToastOverlayQueue.current}, if any. */
     private _currentEl: HTMLDivElement | null = null;
-    /** Per-toast action callbacks (the core toast descriptor carries only the label). */
-    private readonly _actions = new WeakMap<AdwToast, () => void>();
 
     constructor() {
         super();
-        this._queue = new AdwToastQueue({
+        this._queue = new ToastOverlayQueue({
             // Indirect through `this._scheduler` so the timing source stays
             // swappable after construction (the queue takes its scheduler once).
             scheduler: {
@@ -97,7 +85,7 @@ export class AdwToastOverlay extends HTMLElement {
         this._toasts = document.createElement('div');
         this._toasts.className = 'adw-toast-overlay-toasts';
 
-        bindSlottedChildren(this, [{ into: content }]).install(content, this._toasts);
+        bindSlottedChildren(this, [{ name: 'child', into: content }, { into: content }]).install(content, this._toasts);
     }
 
     /**
@@ -115,7 +103,7 @@ export class AdwToastOverlay extends HTMLElement {
     }
 
     /** The toast currently on screen, or `null` when nothing is shown. */
-    get currentToast(): AdwToast | null {
+    get currentToast(): Toast | null {
         return this._queue.current;
     }
 
@@ -124,45 +112,21 @@ export class AdwToastOverlay extends HTMLElement {
         return this._queue.pending;
     }
 
-    /**
-     * Show a toast — the web equivalent of Adw.ToastOverlay.add_toast() with a
-     * freshly-built Adw.Toast. Only ONE toast is visible at a time; this one shows
-     * immediately when the slot is free, otherwise it waits its turn.
-     *
-     * `options` is either an {@link AdwToastOptions} bag or, as a legacy shorthand, a
-     * timeout in MILLISECONDS.
-     */
-    addToast(title: string, options: number | AdwToastOptions = {}): void {
-        // Ensure the toast container exists even if addToast() races a not-yet
+    /** `adw_toast_overlay_add_toast`: show `toast` now, or queue it by its priority. */
+    add_toast(toast: Toast): void {
+        // Ensure the toast container exists even if add_toast() races a not-yet
         // connected element (mirrors Adw.ToastOverlay queuing before realize).
         if (!this._toasts) this.connectedCallback();
-
-        // Back-compat: the original signature was addToast(title, timeoutMs).
-        const opts: AdwToastOptions = typeof options === 'number' ? { timeout: options / 1000 } : options;
-
-        // This element's public timeout unit is SECONDS (Adw.Toast:timeout); the
-        // headless descriptor counts milliseconds.
-        const toast = new AdwToast(title, {
-            timeout: (opts.timeout ?? DEFAULT_TIMEOUT_SECONDS) * 1000,
-            buttonLabel: opts.buttonLabel,
-        });
-        if (opts.onAction) this._actions.set(toast, opts.onAction);
-
-        this._queue.add(toast);
-    }
-
-    /** Dismiss the visible toast early; the next queued toast takes its place. */
-    dismiss(): void {
-        this._queue.dismiss();
+        this._queue.add_toast(toast);
     }
 
-    /** Dismiss the visible toast and discard everything still queued behind it. */
-    clearToasts(): void {
-        this._queue.clear();
+    /** `adw_toast_overlay_dismiss_all`: dismiss every queued toast, then the visible one. */
+    dismiss_all(): void {
+        this._queue.dismiss_all();
     }
 
     /** Build + attach the strip for `toast` — the DOM half of the queue's `onShow`. */
-    private _mountToast(toast: AdwToast): void {
+    private _mountToast(toast: Toast): void {
         const el = document.createElement('div');
         el.className = 'adw-toast';
 
@@ -171,18 +135,20 @@ export class AdwToastOverlay extends HTMLElement {
 
         const titleEl = document.createElement('span');
         titleEl.className = 'adw-toast-title';
-        titleEl.textContent = toast.title;
+        if (toast.use_markup) renderPangoMarkup(titleEl, toast.title);
+        else titleEl.textContent = toast.title;
         wrapper.appendChild(titleEl);
         el.appendChild(wrapper);
 
-        if (toast.hasButton) {
+        if (toast.button_label) {
             const button = document.createElement('button');
             button.type = 'button';
             button.className = 'adw-toast-action-button';
-            button.textContent = toast.buttonLabel;
+            button.textContent = toast.button_label;
             button.addEventListener('click', () => {
-                this._actions.get(toast)?.();
-                this._queue.dismiss();
+                toast.emit('button-clicked');
+                if (toast.action_name) activateWidgetAction(this, toast.action_name);
+                toast.dismiss();
             });
             el.appendChild(button);
         }
@@ -197,7 +163,7 @@ export class AdwToastOverlay extends HTMLElement {
         close.className = 'adw-toast-close-button';
         close.setAttribute('aria-label', 'Close');
         close.appendChild(createGtkImage('window-close'));
-        close.addEventListener('click', () => this._queue.dismiss());
+        close.addEventListener('click', () => toast.dismiss());
         el.appendChild(close);
 
         this._toasts.appendChild(el);

package/src/elements/adw-window-features.ts

@@ -23,6 +23,15 @@ function requested(host: HTMLElement, name: string, fallback: number): number {
     return Number.isFinite(value) && value >= 0 ? value : fallback;
 }
 
+/**
+ * A maximized or fullscreen `Gtk.Window` ignores its default size and fills the monitor's work
+ * area (gtkwindow.c: the default size is only the RESTORED size). The page's work area is the
+ * frame's containing block, which the skin sizes from these two attributes.
+ */
+export function fillsContainingBlock(host: HTMLElement): boolean {
+    return ['maximized', 'fullscreened'].some((name) => host.hasAttribute(name) && host.getAttribute(name) !== 'false');
+}
+
 export class AdwWindowFeatures {
     private _contentEl: HTMLDivElement | null = null;
     private _breakpoints: AdwBreakpoint[] = [];
@@ -128,13 +137,16 @@ export class AdwWindowFeatures {
      * size; `width-request`/`height-request` override it). `default-width/height` is only
      * a default: an authored size is the box, and an absent one leaves the box to the
      * stylesheet, which fills the viewport — a page has no window manager to pick a size.
+     * While maximized or fullscreened the default size is not applied at all: the stylesheet
+     * fills the containing block, and the minimum still holds.
      */
     applySizeRequest(): void {
         const host = this._host;
         host.style.minWidth = `${requested(host, 'width-request', DEFAULT_WIDTH)}px`;
         host.style.minHeight = `${requested(host, 'height-request', DEFAULT_HEIGHT)}px`;
-        const width = host.getAttribute('default-width') ?? host.getAttribute('width');
-        const height = host.getAttribute('default-height') ?? host.getAttribute('height');
+        const fills = fillsContainingBlock(host);
+        const width = fills ? null : (host.getAttribute('default-width') ?? host.getAttribute('width'));
+        const height = fills ? null : (host.getAttribute('default-height') ?? host.getAttribute('height'));
         if (width) host.style.width = `${width}px`;
         else host.style.removeProperty('width');
         if (height) host.style.height = `${height}px`;

package/src/elements/gtk-application-window.ts

@@ -16,7 +16,7 @@
 //
 // THE `win.` / `app.` PREFIXES. `GtkApplicationWindow` exports window actions under `win.` and
 // application-wide ones under `app.` (:48-56), and any `GtkActionable` inside the window can
-// activate either. `defineWindowApplication` installs the `Gio.ActionMap` half on the prototype
+// activate either. `installActionMap` installs the `Gio.ActionMap` half on the prototype
 // (`add_action`, `lookup_action`, `remove_action`, the `win.` registry); the `Gio.ActionGroup`
 // half stays off because a window's `activate_action` is the widget's. Plain `<gtk-window>` has
 // no ActionMap. What this element adds over it is that map, the strip and the property that shows it.
@@ -26,17 +26,12 @@
 // Copyright (c) The GTK Team. LGPLv2.1+.
 // Modifications: Implemented as a Web Component for @gjsify/adwaita-web.
 
-import type { ActionLike } from '@gjsify/adwaita-core';
-import type { GtkApplication } from '../application.js';
+import { installActionMap, type ActionLike } from '@gjsify/adwaita-core';
 import type { DispatchedSignals } from '../signals.js';
 import type { AdwSlot } from '../slotted-children.js';
 import { GtkWindow } from './gtk-window.js';
-import { defineWindowApplication } from '../application.js';
 
 export class GtkApplicationWindow extends GtkWindow {
-    /** `Gtk.Window:application`: setting it is `add_window` (ADR 0098), set by `defineWindowApplication`. */
-    declare application: GtkApplication | null;
-
     /** `Gio.ActionMap.add_action`: installed by `installActionMap`; the action is reachable as `win.<name>`. */
     declare add_action: (action: ActionLike) => void;
     /** `Gio.ActionMap.lookup_action`: the window's own action, or `null`. */
@@ -127,4 +122,4 @@ export class GtkApplicationWindow extends GtkWindow {
 
 customElements.define('gtk-application-window', GtkApplicationWindow);
 
-defineWindowApplication(GtkApplicationWindow.prototype);
+installActionMap(GtkApplicationWindow.prototype);

package/src/elements/gtk-drag-icon.ts

@@ -53,6 +53,8 @@
 // Copyright (c) GNOME contributors (libadwaita). LGPLv2.1+.
 // Modifications: Implemented as a Web Component for @gjsify/adwaita-web.
 
+import { bindSlottedChildren } from '../slotted-children.js';
+
 /** The `rgba()` string a `GdkRGBA` value paints, as the colour swatch shows it. */
 interface Rgba {
     readonly red: number;
@@ -166,6 +168,8 @@ export class GtkDragIcon extends HTMLElement {
         // `gtk_widget_set_can_target (self, FALSE)` (:386-390), in CSS: the icon is pointed
         // at, and takes no pointer event of any kind.
         this.style.pointerEvents = 'none';
+        // The NAME only, for the reason `adw-bin.ts` gives: the child already IS the content.
+        bindSlottedChildren(this, [{ name: 'child', into: this }]);
         if (this._dragging) this._observe();
     }
 

package/src/elements/gtk-emoji-chooser.ts

@@ -103,6 +103,11 @@ export class GtkEmojiChooser extends GtkPopover {
      */
     private _ctrl = false;
 
+    /** The chooser's template is the child (gtkemojichooser.ui). */
+    protected override takesChild(): boolean {
+        return false;
+    }
+
     connectedCallback(): void {
         super.connectedCallback();
         if (this._built) return;

package/src/elements/gtk-flow-box-child.ts

@@ -38,7 +38,9 @@ export class GtkFlowBoxChild extends HTMLElement {
         this._contentsEl = document.createElement('div');
         this._contentsEl.className = 'adw-flow-box-child-contents';
 
-        bindSlottedChildren(this, [{ into: this._contentsEl }]).install(this._contentsEl);
+        bindSlottedChildren(this, [{ name: 'child', into: this._contentsEl }, { into: this._contentsEl }]).install(
+            this._contentsEl,
+        );
 
         this.setAttribute('role', 'gridcell');
         // `gtk_flow_box_child_init` makes the cell focusable (:578-580) — the box's cursor

package/src/elements/gtk-graphics-offload.ts

@@ -98,7 +98,9 @@ export class GtkGraphicsOffload extends HTMLElement {
         this._childEl.className = 'adw-graphics-offload-child';
         // `GTK_TYPE_BIN_LAYOUT` gives the child the whole allocation, and `child` is the one
         // GtkBuildable slot the widget has, so it is the default one here.
-        bindSlottedChildren(this, [{ into: this._childEl }]).install(this._childEl);
+        bindSlottedChildren(this, [{ name: 'child', into: this._childEl }, { into: this._childEl }]).install(
+            this._childEl,
+        );
         this.replaceChildren(this._childEl);
         this._render();
     }

package/src/elements/gtk-list-box-row.ts

@@ -110,7 +110,9 @@ export class GtkListBoxRow extends HTMLElement {
         // `child` is a WIDGET property, so it is a slot here (gtklistbox.c:3307-3331): the
         // authored child lands in the same node `gtk_list_box_row_set_child` would put it in,
         // and a child appended after connect lands there too.
-        bindSlottedChildren(this, [{ into: this._contentsEl }]).install(this._contentsEl);
+        bindSlottedChildren(this, [{ name: 'child', into: this._contentsEl }, { into: this._contentsEl }]).install(
+            this._contentsEl,
+        );
 
         // GTK declares the accessible role unconditionally (gtklistbox.c:3955), so there is
         // no `selection-mode` to condition it on here.

package/src/elements/gtk-overlay.ts

@@ -98,10 +98,11 @@ export class GtkOverlay extends HTMLElement {
         // bare `<child>` — the default — is the main child, which is the pairing
         // `packages/framework/gtk-host/src/descriptors/gtk.ts` curates for `GtkOverlay`
         // (`slots: { child, overlay }`, `defaultSlot: 'child'`).
-        bindSlottedChildren(this, [{ into: this._childEl }, { name: 'overlay', into: this._layerEl }]).install(
-            this._childEl,
-            this._layerEl,
-        );
+        bindSlottedChildren(this, [
+            { name: 'child', into: this._childEl },
+            { into: this._childEl },
+            { name: 'overlay', into: this._layerEl },
+        ]).install(this._childEl, this._layerEl);
 
         this._observe();
     }

package/src/elements/gtk-paned.ts

@@ -278,7 +278,13 @@ export class GtkPaned extends HTMLElement {
         // (gtkpaned.c:816-826).
         bindSlottedChildren(
             this,
-            [{ into: this._startEl }, { name: 'start', into: this._startEl }, { name: 'end', into: this._endEl }],
+            [
+                { into: this._startEl },
+                { name: 'start', into: this._startEl },
+                { name: 'end', into: this._endEl },
+                { name: 'start-child', into: this._startEl },
+                { name: 'end-child', into: this._endEl },
+            ],
             () => this._observe(),
         ).install(this._startEl, this._handleEl, this._endEl);
 

package/src/elements/gtk-popover-bin.ts

@@ -75,6 +75,7 @@ import type { AdwMenuActions, AdwMenuInput, AdwMenuModel } from '@gjsify/adwaita
 import './gtk-popover-menu.js';
 
 import type { GtkPopoverMenu } from './gtk-popover-menu.js';
+import { bindSlottedChildren } from '../slotted-children.js';
 
 /** How long a press must last to count as a long press — GTK's own default. */
 const LONG_PRESS_MS = 500;
@@ -150,6 +151,8 @@ export class GtkPopoverBin extends HTMLElement {
         this._initialized = true;
         // `gtk_widget_class_set_css_name (widget_class, "popoverbin")` (gtkpopoverbin.c:382).
         this.classList.add('adw-popover-bin');
+        // The NAME only, for the reason `adw-bin.ts` gives: the child already IS the content.
+        bindSlottedChildren(this, [{ name: 'child', into: this }]);
         this.addEventListener('contextmenu', (event) => this._onContextMenu(event));
         this.addEventListener('keydown', (event) => this._onKeyDown(event));
         this._wireGestures();

package/src/elements/gtk-popover-menu.ts

@@ -161,6 +161,11 @@ export class GtkPopoverMenu extends GtkPopover {
         this.openSubmenu(value);
     }
 
+    /** The menu's own stack is the child (gtkpopovermenu.c `gtk_popover_menu_init`). */
+    protected override takesChild(): boolean {
+        return false;
+    }
+
     connectedCallback() {
         super.connectedCallback();
         if (this._menuInitialized) return;

package/src/elements/gtk-popover.ts

@@ -82,6 +82,8 @@
 
 import { PopoverState, resolvePopoverKey } from '@gjsify/adwaita-core';
 
+import { bindSlottedChildren } from '../slotted-children.js';
+
 /** Which side of the anchor the surface sits on. */
 export type GtkPopoverPosition = 'bottom' | 'top' | 'start' | 'end';
 
@@ -257,10 +259,20 @@ export class GtkPopover extends HTMLElement {
         if (this._state.open) this._bindDocument();
     }
 
+    /**
+     * Whether `Gtk.Popover:child` is the author's to set. A subclass that builds its own
+     * content (GtkPopoverMenu, GtkEmojiChooser) sets the child itself, as their C does.
+     */
+    protected takesChild(): boolean {
+        return true;
+    }
+
     private _buildOnce() {
         if (this._initialized) return;
         this._initialized = true;
 
+        // The NAME only, for the reason `adw-bin.ts` gives: the child already IS the content.
+        if (this.takesChild()) bindSlottedChildren(this, [{ name: 'child', into: this }]);
         this.classList.add('adw-popover');
         if (!this.hasAttribute('role')) this.setAttribute('role', 'menu');
         // The `menu` variant is NOT defaulted or inferred here — it is GTK's `.menu`

package/src/elements/gtk-search-bar.ts

@@ -37,6 +37,8 @@
 // Copyright (c) The GTK Team, GNOME contributors. LGPLv2.1+.
 // Modifications: Implemented as a Web Component for @gjsify/adwaita-web.
 
+import { bindSlottedChildren } from '../slotted-children.js';
+
 export class GtkSearchBar extends HTMLElement {
     private _box!: HTMLDivElement;
     private _center!: HTMLDivElement;
@@ -93,10 +95,6 @@ export class GtkSearchBar extends HTMLElement {
 
         this._center = document.createElement('div');
         this._center.className = 'adw-search-bar-center';
-        // Whatever the author put inside the bar is the child, moved into the box's centre —
-        // the `GtkCenterBox` the C builds around it (gtksearchbar.c:378-386).
-        this._center.append(...this.childNodes);
-
         this._close = document.createElement('button');
         this._close.className = 'adw-search-bar-close';
         this._close.type = 'button';
@@ -106,7 +104,9 @@ export class GtkSearchBar extends HTMLElement {
         this._box = document.createElement('div');
         this._box.className = 'adw-search-bar-box';
         this._box.append(this._center, this._close);
-        this.replaceChildren(this._box);
+        // Whatever the author put inside the bar is the child, moved into the box's centre —
+        // the `GtkCenterBox` the C builds around it (gtksearchbar.c:378-386).
+        bindSlottedChildren(this, [{ name: 'child', into: this._center }, { into: this._center }]).install(this._box);
 
         // `input-intercepted`: typing into the connected editable reveals the bar
         // (gtksearchbar.c:210-218). Captured, because the editable may be nested two

package/src/elements/gtk-stack-page.ts

@@ -0,0 +1,111 @@
+// <gtk-stack-page> — the page record a `<gtk-stack>` is AUTHORED with.
+//
+// NOT A WIDGET, AS UPSTREAM. `GtkStackPage` descends from `GObject.Object` (gtkstack.c:212-233):
+// it carries a page's `name`, `title`, `icon-name` and attention state beside the `child` that IS
+// the page. A Blueprint spells it `Stack { StackPage { name: "debugger"; child: … } }`, and
+// without an element for it the shared-tree builder refused every such `.blp`.
+//
+// THE STACK ADOPTS IT AND KEEPS NO RECORD, the shape `<adw-view-stack>` gives
+// `<adw-view-stack-page>`: `<gtk-stack>` already reads a page's six properties as attributes on
+// its CHILD (see `gtk-stack.ts`), so adopting a record copies them onto the child and puts the
+// child where the record was. The record leaves the tree, which is the browser half of what
+// `@gjsify/adwaita-nativescript`'s `stack-page.ts` refuses after adoption: a write to a record
+// the stack no longer reads would be a silent no-op.
+//   name / title / icon-name / needs-attention / use-underline — the same attributes
+//   visible — the DOM's own `hidden`, as on the child (`GtkStackPage:visible`, gtkstack.c:567)
+//   child   — the slot `child`, or the record's one element child (a bare child IS the page)
+//
+// Reference: refs/gtk/gtk/gtkstack.c (GtkStackPage)
+// Copyright (c) The GTK Team. LGPLv2.1+.
+// Modifications: Implemented as a Web Component for @gjsify/adwaita-web.
+
+import { bindSlottedChildren } from '../slotted-children.js';
+
+/** The attributes a record hands to its child on adoption — `GtkStackPage`'s string/boolean properties. */
+export const STACK_PAGE_ATTRIBUTES = ['name', 'title', 'icon-name', 'needs-attention', 'use-underline'] as const;
+
+export class GtkStackPage extends HTMLElement {
+    static get observedAttributes() {
+        return [...STACK_PAGE_ATTRIBUTES];
+    }
+
+    /** `GtkStackPage:name` — what `visible-child-name` selects by. */
+    get name(): string {
+        return this.getAttribute('name') ?? '';
+    }
+
+    set name(value: string | null) {
+        if (value === null) this.removeAttribute('name');
+        else this.setAttribute('name', value);
+    }
+
+    // `GtkStackPage:title` is `HTMLElement.title`, which already reflects the `title` attribute.
+
+    /** `GtkStackPage:icon-name`. */
+    get iconName(): string | null {
+        return this.getAttribute('icon-name');
+    }
+
+    set iconName(value: string | null) {
+        if (value === null) this.removeAttribute('icon-name');
+        else this.setAttribute('icon-name', value);
+    }
+
+    /** `GtkStackPage:needs-attention`. */
+    get needsAttention(): boolean {
+        return this.hasAttribute('needs-attention');
+    }
+
+    set needsAttention(value: boolean) {
+        this.toggleAttribute('needs-attention', !!value);
+    }
+
+    /** `GtkStackPage:use-underline`. */
+    get useUnderline(): boolean {
+        return this.hasAttribute('use-underline');
+    }
+
+    set useUnderline(value: boolean) {
+        this.toggleAttribute('use-underline', !!value);
+    }
+
+    /** `GtkStackPage:visible` — `hidden`, as on the child the stack reads it from. */
+    get visible(): boolean {
+        return !this.hasAttribute('hidden');
+    }
+
+    set visible(value: boolean) {
+        this.toggleAttribute('hidden', !value);
+    }
+
+    /** `GtkStackPage:child` — the element the stack shows for this page, while not yet adopted. */
+    get child(): HTMLElement | null {
+        return pageChildOf(this);
+    }
+
+    connectedCallback(): void {
+        // `child:` in a `.blp` authors `slot="child"`, and the mount refuses a name this element
+        // never declared. The stack adopts on ITS connect, which runs first, so by now this
+        // record is usually detached; enrolling the name is all that is left to do.
+        bindSlottedChildren(this, [{ name: 'child', into: this }]);
+    }
+}
+
+/**
+ * The one element a record holds: its `slot="child"` child or its only element child. A record
+ * with none, or with more than one, is refused by name — GtkStackPage has exactly one `child`.
+ */
+export function pageChildOf(page: HTMLElement): HTMLElement | null {
+    const elements = Array.from(page.children) as HTMLElement[];
+    const slotted = elements.filter((child) => child.getAttribute('slot') === 'child');
+    const candidates = slotted.length > 0 ? slotted : elements;
+    if (candidates.length > 1) {
+        throw new Error(
+            `<gtk-stack-page name="${page.getAttribute('name') ?? ''}"> holds ${candidates.length} children, ` +
+                'and a GtkStackPage has one `child`.',
+        );
+    }
+    return candidates[0] ?? null;
+}
+
+customElements.define('gtk-stack-page', GtkStackPage);