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

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

@@ -5,11 +5,20 @@
 // with a unique string ID and a label; one may carry the suggested or
 // destructive appearance.
 //
-// Responses are declared imperatively via add_response() / addResponse() (the
-// Adw.AlertDialog API), or via <adw-alert-response> children consumed at connect
-// time. The dialog is hidden until `present()` (or setting the `open` attribute)
-// reveals it; Escape / scrim-click dismiss it — respecting the `close-response`
-// — unless can-close is suppressed by the close response.
+// Responses are declared imperatively via add_response() (the Adw.AlertDialog API),
+// or via <adw-alert-response> children consumed at connect time. The dialog is
+// hidden until `present()` (or setting the `open` attribute) reveals it; Escape /
+// scrim-click dismiss it — respecting the `close-response` — unless can-close is
+// suppressed by the close response.
+//
+// THE GJS FORM RUNS AS WRITTEN: `new Adw.AlertDialog({ heading, close_response })`,
+// `add_response(id, label)`, `connect('response', (dialog, id) => …)`, `present(parent)`.
+// The response verbs carry libadwaita's snake_case names only — the camelCase
+// `addResponse` / `setDefaultResponse` … this element used to publish had no GIR
+// counterpart. `present()` attaches a detached dialog to the document: libadwaita adds it
+// to the dialog host of `parent`'s ROOT window, and the page is that root here. A dialog
+// `present()` attached leaves the document again when it closes, as `adw_dialog_close`
+// unparents it from the host; one placed in markup stays where its author put it.
 //
 // Attributes:
 //   heading    (the bold heading text)
@@ -35,12 +44,12 @@
 // sizes) and laid out horizontally when prefer-wide-layout is set and there are no more
 // than two of them — the libadwaita measure/allocate heuristic in spirit, not to the px.
 //
-// Events:
-//   `response` (CustomEvent, bubbles, `detail = { response }`) when a response
-//     button is activated OR the dialog is dismissed (then `response` is the
-//     close-response ID) — mirrors the Adw.AlertDialog::response signal.
-//   `notify::heading` / `notify::body` / `notify::open` (CustomEvent, bubbles)
-//     mirroring the matching GObject properties.
+// Signals (declared in `static signals`, reached with `connect`):
+//   `response (dialog, id)` when a response button is activated OR the dialog is
+//     dismissed (then `id` is the close-response) — Adw.AlertDialog::response. It
+//     arrives as a non-bubbling `response` DOM event whose `detail` is `[id]`.
+//   `notify::heading` / `notify::body` (CustomEvent, bubbles) mirroring the matching
+//     GObject properties; `notify::open` is the web-only `open` attribute's.
 //
 // The RESPONSE MODEL — the registry (id/label/appearance/enabled), the
 // default/close-response semantics and the resolve-to-chosen-id contract — is HEADLESS
@@ -57,12 +66,16 @@
 
 import { AdwAlertResponses } from '@gjsify/adwaita-core';
 import type { AdwResponseAppearance } from '@gjsify/adwaita-core';
+import { propertyOf } from '@gjsify/adwaita-core/tags';
 
+import { dispatchElement, installElementApi } from '../gobject-elements.js';
 import { renderPangoMarkup } from '../pango-markup.js';
+import type { DispatchedSignals } from '../signals.js';
 import { bindEmptySections } from '../empty-sections.js';
 import { bindSlottedChildren } from '../slotted-children.js';
 import { AdwModalSurface } from './modal-surface.js';
 import { booleanAttribute } from '../attributes.js';
+import { WidgetElement } from '../widget-element.js';
 
 /** Response button appearance — mirrors Adw.ResponseAppearance. */
 export type { AdwResponseAppearance } from '@gjsify/adwaita-core';
@@ -73,14 +86,61 @@ export type { AdwResponseAppearance } from '@gjsify/adwaita-core';
  * `appearance="suggested|destructive"` and `enabled="false"` mirror the
  * GtkBuildable `<response>` element attributes. Consumed at connect time.
  */
-export class AdwAlertResponse extends HTMLElement {
+export class AdwAlertResponse extends WidgetElement {
     static get observedAttributes() {
         return ['id', 'appearance', 'enabled'];
     }
 }
 
-export class AdwAlertDialog extends HTMLElement {
+/** The `Adw.AlertDialog` construct properties, in GJS's snake_case or the camelCase GJS also takes. */
+export interface AdwAlertDialogProps {
+    heading?: string;
+    body?: string;
+    heading_use_markup?: boolean;
+    headingUseMarkup?: boolean;
+    body_use_markup?: boolean;
+    bodyUseMarkup?: boolean;
+    close_response?: string;
+    closeResponse?: string;
+    default_response?: string | null;
+    defaultResponse?: string | null;
+    prefer_wide_layout?: boolean;
+    preferWideLayout?: boolean;
+}
+
+export class AdwAlertDialog extends WidgetElement {
+    /** The GTK signals this element dispatches, each with the DOM event it arrives as (ADR 0093). */
+    static readonly signals: DispatchedSignals = {
+        response: 'response',
+        ...Object.fromEntries(
+            [
+                'heading',
+                'body',
+                'heading-use-markup',
+                'body-use-markup',
+                'close-response',
+                'default-response',
+                'prefer-wide-layout',
+            ].map((name) => [`notify::${name}`, `notify::${name}`]),
+        ),
+    };
+
+    /** `GObject.Object.connect`: installed per instance by `installElementApi`; refuses an undeclared signal. */
+    declare connect: (signal: string, handler: (emitter: this, ...args: any[]) => unknown) => number;
+    /** `GObject.Object.disconnect`: throws for an id that is not connected. */
+    declare disconnect: (id: number) => void;
+    /** `GObject.Object.emit`. */
+    declare emit: (signal: string, ...args: unknown[]) => void;
+    /** `GObject.Object.notify`. */
+    declare notify: (name: string) => void;
+    /** `GObject.Object.get_property`, by GTK's dashed name. */
+    declare get_property: (name: string) => unknown;
+    /** `GObject.Object.set_property`. */
+    declare set_property: (name: string, value: unknown) => void;
+
     private _initialized = false;
+    /** Set when `present()` attached the dialog, so closing detaches it again. */
+    private _attachedByPresent = false;
     private _scrimEl!: HTMLDivElement;
     private _dialogEl!: HTMLDivElement;
     private _headingEl!: HTMLHeadingElement;
@@ -97,6 +157,22 @@ export class AdwAlertDialog extends HTMLElement {
     // also fire the close-response (AdwAlertDialog's `block_close_response`).
     private _blockCloseResponse = false;
 
+    /**
+     * `new Adw.AlertDialog({ heading, body, close_response, default_response })`, the GJS
+     * construct bag. Only the `new` form passes one: `document.createElement` and the
+     * parser call this with nothing, which is why writing attributes here is allowed.
+     */
+    constructor(props?: AdwAlertDialogProps) {
+        super();
+        installElementApi(this);
+        for (const [key, value] of Object.entries(props ?? {})) {
+            if (value === undefined) continue;
+            const member = propertyOf(key);
+            if (!(member in this)) throw new Error(`No property ${key} on <adw-alert-dialog>`);
+            (this as unknown as Record<string, unknown>)[member] = value;
+        }
+    }
+
     static get observedAttributes() {
         return [
             'heading',
@@ -171,7 +247,7 @@ export class AdwAlertDialog extends HTMLElement {
     }
 
     set defaultResponse(value: string | null) {
-        this.setDefaultResponse(value);
+        this.set_default_response(value);
     }
 
     /** The ID passed to `response` when the dialog is dismissed. */
@@ -180,7 +256,7 @@ export class AdwAlertDialog extends HTMLElement {
     }
 
     set closeResponse(value: string) {
-        this.setCloseResponse(value);
+        this.set_close_response(value);
     }
 
     connectedCallback() {
@@ -239,6 +315,7 @@ export class AdwAlertDialog extends HTMLElement {
                 claims: (node) => node instanceof Element && node.localName === 'adw-alert-response',
                 consume: (node) => this._adoptResponse(node as AdwAlertResponse),
             },
+            { name: 'extra-child', into: this._childEl },
             { into: this._childEl },
         ]).install(this._scrimEl, this._dialogEl);
 
@@ -261,7 +338,9 @@ export class AdwAlertDialog extends HTMLElement {
         // two live in the model and would simply be dropped.
         const closeResponse = this.getAttribute('close-response');
         if (closeResponse !== null) this._model.closeResponse = closeResponse;
-        this._model.defaultResponse = this.getAttribute('default-response');
+        // An absent attribute leaves a `default_response` the construct bag already set.
+        const defaultResponse = this.getAttribute('default-response');
+        if (defaultResponse !== null) this._model.defaultResponse = defaultResponse;
 
         this._render();
     }
@@ -275,11 +354,11 @@ export class AdwAlertDialog extends HTMLElement {
         const id = el.getAttribute('id');
         if (!id) return;
         const appearance = (el.getAttribute('appearance') ?? 'default') as AdwResponseAppearance;
-        this.addResponse(id, (el.textContent ?? '').trim());
-        if (appearance !== 'default') this.setResponseAppearance(id, appearance);
+        this.add_response(id, (el.textContent ?? '').trim());
+        if (appearance !== 'default') this.set_response_appearance(id, appearance);
         // `enabled` is a value-based boolean attribute (GTK property defaulting to TRUE).
         // Use the shared reader instead of a hand-rolled `=== 'false'` comparison.
-        if (!booleanAttribute(el.getAttribute('enabled'), true)) this.setResponseEnabled(id, false);
+        if (!booleanAttribute(el.getAttribute('enabled'), true)) this.set_response_enabled(id, false);
     }
 
     attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null) {
@@ -301,22 +380,38 @@ export class AdwAlertDialog extends HTMLElement {
             // header) — the attribute is a markup entry point that feeds it, so the
             // setter is not mirrored back and there is no reflection loop. An absent
             // attribute means "leave the model's default", not "reset to `close`".
-            if (newValue !== null) this.setCloseResponse(newValue);
+            if (newValue !== null) this.set_close_response(newValue);
         } else if (name === 'default-response') {
-            this.setDefaultResponse(newValue);
+            this.set_default_response(newValue);
         } else if (name === 'open') {
             this.dispatchEvent(new CustomEvent('notify::open', { bubbles: true, detail: { open: this.open } }));
-            if (this.open) this._modal.present();
-            else this._modal.dismiss();
+            if (this.open) {
+                this._modal.present();
+            } else {
+                this._modal.dismiss();
+                if (this._attachedByPresent) {
+                    this._attachedByPresent = false;
+                    this.remove();
+                }
+            }
         }
     }
 
-    /** Present the dialog. `parent` is accepted for API parity; unused. */
+    /**
+     * Present the dialog (`adw_dialog_present`). A detached dialog is attached to the document
+     * first and detached again when it closes; `parent` names the window it belongs to, and the
+     * page is that window's root here, so it does not change where the dialog goes.
+     */
     present(_parent?: unknown): void {
+        if (!this.isConnected) {
+            document.body.appendChild(this);
+            this._attachedByPresent = true;
+        }
         this.open = true;
     }
 
-    addResponse(id: string, label: string): void {
+    /** `adw_alert_dialog_add_response`: a duplicate id is refused, as libadwaita's g_critical does. */
+    add_response(id: string, label: string): void {
         // The core registry UPDATES a duplicate id in place; AdwAlertDialog refuses it,
         // so the guard stays here.
         if (this._model.hasResponse(id)) {
@@ -339,15 +434,14 @@ export class AdwAlertDialog extends HTMLElement {
         this._render();
     }
 
-    /** Adds multiple responses at once — id/label pairs (Adw.add_responses parity). */
-    addResponses(...idLabelPairs: string[]): void {
-        for (let i = 0; i + 1 < idLabelPairs.length; i += 2) {
-            this.addResponse(idLabelPairs[i], idLabelPairs[i + 1]);
+    /** `adw_alert_dialog_remove_response`. */
+    remove_response(id: string): void {
+        if (!this._model.hasResponse(id)) {
+            console.warn(
+                `[adw-alert-dialog] Trying to remove a response with id '${id}', but such a response does not exist`,
+            );
+            return;
         }
-    }
-
-    removeResponse(id: string): void {
-        if (!this._model.hasResponse(id)) return;
         this._buttons.get(id)?.remove();
         this._buttons.delete(id);
         // `AdwAlertResponses` exposes no removal (a gap against
@@ -367,15 +461,18 @@ export class AdwAlertDialog extends HTMLElement {
         this._render();
     }
 
-    hasResponse(id: string): boolean {
+    /** `adw_alert_dialog_has_response`. */
+    has_response(id: string): boolean {
         return this._model.hasResponse(id);
     }
 
-    getResponseLabel(id: string): string | null {
+    /** `adw_alert_dialog_get_response_label`; `null` for an unknown id, as the C returns NULL. */
+    get_response_label(id: string): string | null {
         return this._model.responses.find((response) => response.id === id)?.label ?? null;
     }
 
-    setResponseLabel(id: string, label: string): void {
+    /** `adw_alert_dialog_set_response_label`. */
+    set_response_label(id: string, label: string): void {
         const button = this._buttons.get(id);
         if (!button) return;
         // Re-adding a known id updates it in place (the core registry contract).
@@ -383,11 +480,13 @@ export class AdwAlertDialog extends HTMLElement {
         button.textContent = label;
     }
 
-    getResponseAppearance(id: string): AdwResponseAppearance | null {
+    /** `adw_alert_dialog_get_response_appearance`; `null` for an unknown id. */
+    get_response_appearance(id: string): AdwResponseAppearance | null {
         return this._model.hasResponse(id) ? this._model.getResponseAppearance(id) : null;
     }
 
-    setResponseAppearance(id: string, appearance: AdwResponseAppearance): void {
+    /** `adw_alert_dialog_set_response_appearance`. */
+    set_response_appearance(id: string, appearance: AdwResponseAppearance): void {
         const button = this._buttons.get(id);
         if (!button) return;
         this._model.setResponseAppearance(id, appearance);
@@ -395,31 +494,63 @@ export class AdwAlertDialog extends HTMLElement {
         button.classList.toggle('destructive-action', appearance === 'destructive');
     }
 
-    getResponseEnabled(id: string): boolean {
+    /** `adw_alert_dialog_get_response_enabled`; `false` for an unknown id, as the C returns FALSE. */
+    get_response_enabled(id: string): boolean {
         return this._model.hasResponse(id) ? this._model.getResponseEnabled(id) : false;
     }
 
-    /** Sets whether a response is enabled (disabled buttons can't be activated). */
-    setResponseEnabled(id: string, enabled: boolean): void {
+    /** `adw_alert_dialog_set_response_enabled`: a disabled button cannot be activated. */
+    set_response_enabled(id: string, enabled: boolean): void {
         const button = this._buttons.get(id);
         if (!button) return;
         this._model.setResponseEnabled(id, enabled);
         button.disabled = !enabled;
     }
 
-    /** Sets the default response — its button is highlighted as the suggested one. */
-    setDefaultResponse(id: string | null): void {
+    /** `adw_alert_dialog_get_default_response`. */
+    get_default_response(): string | null {
+        return this._model.defaultResponse;
+    }
+
+    /** `adw_alert_dialog_set_default_response`: its button is highlighted and takes the focus. */
+    set_default_response(id: string | null): void {
         this._model.defaultResponse = id;
         this._render();
     }
 
-    /** Sets the close response — emitted on dismissal (Escape / scrim click). */
-    setCloseResponse(id: string): void {
+    /** `adw_alert_dialog_get_close_response`. */
+    get_close_response(): string {
+        return this._model.closeResponse;
+    }
+
+    /** `adw_alert_dialog_set_close_response`: emitted on dismissal (Escape / scrim click). */
+    set_close_response(id: string): void {
         this._model.closeResponse = id;
     }
 
+    /** `adw_alert_dialog_get_heading`. */
+    get_heading(): string {
+        return this.heading;
+    }
+
+    /** `adw_alert_dialog_set_heading`. */
+    set_heading(heading: string): void {
+        this.heading = heading;
+    }
+
+    /** `adw_alert_dialog_get_body`. */
+    get_body(): string {
+        return this.body;
+    }
+
+    /** `adw_alert_dialog_set_body`. */
+    set_body(body: string): void {
+        this.body = body;
+    }
+
     private _activateResponse(id: string): void {
         if (!this._model.getResponseEnabled(id)) return;
+        // `emit_response`: block the close-response, close, then emit the chosen one.
         this._blockCloseResponse = true;
         this.open = false;
         this._blockCloseResponse = false;
@@ -438,7 +569,7 @@ export class AdwAlertDialog extends HTMLElement {
     }
 
     private _emitResponse(response: string): void {
-        this.dispatchEvent(new CustomEvent('response', { bubbles: true, detail: { response } }));
+        dispatchElement(this, 'response', [response]);
     }
 
     /**

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

@@ -45,7 +45,6 @@ import type { AdwBreakpoint } from '@gjsify/adwaita-core';
 import type { AdwSlot } from '../slotted-children.js';
 import { AdwWindowFeatures } from './adw-window-features.js';
 import { GtkApplicationWindow } from './gtk-application-window.js';
-import { defineWindowApplication } from '../application.js';
 
 export class AdwApplicationWindow extends GtkApplicationWindow {
     private readonly _features = new AdwWindowFeatures(this);
@@ -232,5 +231,3 @@ export class AdwApplicationWindow extends GtkApplicationWindow {
 }
 
 customElements.define('adw-application-window', AdwApplicationWindow);
-
-defineWindowApplication(AdwApplicationWindow.prototype);

package/src/elements/adw-avatar.ts

@@ -29,8 +29,9 @@ import {
 } from '@gjsify/adwaita-core';
 
 import { type GtkImage, createGtkImage } from './gtk-image.js';
+import { WidgetElement } from '../widget-element.js';
 
-export class AdwAvatar extends HTMLElement {
+export class AdwAvatar extends WidgetElement {
     private _textEl!: HTMLSpanElement;
     private _iconEl!: GtkImage;
     private _imageEl!: HTMLImageElement;

package/src/elements/adw-banner.ts

@@ -21,8 +21,9 @@ import {
 } from '@gjsify/adwaita-core';
 
 import { renderPangoMarkup } from '../pango-markup.js';
+import { WidgetElement } from '../widget-element.js';
 
-export class AdwBanner extends HTMLElement {
+export class AdwBanner extends WidgetElement {
     private _titleEl!: HTMLSpanElement;
     private _button!: HTMLButtonElement;
     private _initialized = false;

package/src/elements/adw-bin.ts

@@ -31,8 +31,9 @@
 // Modifications: Implemented as a Web Component for @gjsify/adwaita-web.
 
 import { bindSlottedChildren } from '../slotted-children.js';
+import { WidgetElement } from '../widget-element.js';
 
-export class AdwBin extends HTMLElement {
+export class AdwBin extends WidgetElement {
     private _observer: MutationObserver | null = null;
 
     /** `Adw.Bin:child` — the one child, or `null`. The last one appended is the one that stays. */

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

@@ -66,17 +66,18 @@ import type {
 import { bindSlottedChildren, type AdwSlot } from '../slotted-children.js';
 import { installElementApi } from '../gobject-elements.js';
 import type { DispatchedSignals } from '../signals.js';
+import { WidgetElement } from '../widget-element.js';
 
 /** The persistent content. Child of <adw-bottom-sheet>; consumed at connect time. */
-export class AdwBottomSheetContent extends HTMLElement {}
+export class AdwBottomSheetContent extends WidgetElement {}
 
 /** The slide-up sheet. Child of <adw-bottom-sheet>; consumed at connect time. */
-export class AdwBottomSheetSheet extends HTMLElement {}
+export class AdwBottomSheetSheet extends WidgetElement {}
 
 /** The collapsed bar the sheet morphs out of. Child of <adw-bottom-sheet>. */
-export class AdwBottomSheetBottomBar extends HTMLElement {}
+export class AdwBottomSheetBottomBar extends WidgetElement {}
 
-export class AdwBottomSheet extends HTMLElement {
+export class AdwBottomSheet extends WidgetElement {
     /** The GTK signals this element dispatches, each with the DOM event it arrives as (ADR 0093). */
     static readonly signals: DispatchedSignals = { 'notify::open': 'notify::open' };
 

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

@@ -67,6 +67,8 @@ import { BreakpointBinState } from '@gjsify/adwaita-core';
 import type { BreakpointSetter } from '@gjsify/adwaita-core';
 
 import { observeAdaptiveSize } from '../breakpoints.js';
+import { bindSlottedChildren } from '../slotted-children.js';
+import { WidgetElement } from '../widget-element.js';
 
 /** One authored setter, as it reads in the `breakpoints` attribute. */
 interface AuthoredSetter {
@@ -103,7 +105,7 @@ function parseBreakpoints(raw: string | null): AuthoredBreakpoint[] {
     });
 }
 
-export class AdwBreakpointBin extends HTMLElement {
+export class AdwBreakpointBin extends WidgetElement {
     /** The C's own structure: a list of breakpoints, and at most one picked. */
     private _state = new BreakpointBinState<Element>();
     private _dispose: (() => void) | undefined;
@@ -157,6 +159,8 @@ export class AdwBreakpointBin extends HTMLElement {
     }
 
     connectedCallback() {
+        // The NAME only, for the reason `adw-bin.ts` gives: the child already IS the content.
+        bindSlottedChildren(this, [{ name: 'child', into: this }]);
         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

package/src/elements/adw-button-content.ts

@@ -25,6 +25,7 @@
 import { BUTTON_CONTENT_STYLE_CLASS, buttonContentIconName, buttonContentLabelText } from '@gjsify/adwaita-core';
 
 import { type GtkImage, createGtkImage } from './gtk-image.js';
+import { WidgetElement } from '../widget-element.js';
 
 /**
  * What `gtk_widget_get_ancestor (…, GTK_TYPE_BUTTON)` looks like in the DOM: a native
@@ -36,7 +37,7 @@ const BUTTON_SELECTOR = 'button, .adw-button';
 /** The split-button node the class is RETARGETED to. */
 const SPLIT_BUTTON_SELECTOR = 'adw-split-button, .adw-split-button';
 
-export class AdwButtonContent extends HTMLElement {
+export class AdwButtonContent extends WidgetElement {
     private _boxEl!: HTMLDivElement;
     private _iconEl!: GtkImage;
     private _labelEl!: HTMLSpanElement;

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

@@ -27,8 +27,9 @@ import { BUTTON_ROW_ACTIVATABLE, ButtonRowState } from '@gjsify/adwaita-core';
 import { applyRowTooltip } from '../row-tooltip.js';
 import { type GtkImage, createGtkImage } from './gtk-image.js';
 import { attachRowActivation } from './row-activation.js';
+import { TooltipElement } from '../widget-element.js';
 
-export class AdwButtonRow extends HTMLElement {
+export class AdwButtonRow extends TooltipElement {
     private _contentsEl!: HTMLDivElement;
     private _startIconEl!: GtkImage;
     private _endIconEl!: GtkImage;

package/src/elements/adw-card.ts

@@ -5,8 +5,9 @@
 // Reference: refs/adwaita-web/adwaita-web/scss/_card.scss
 // Copyright (c) GNOME contributors (libadwaita). LGPLv2.1+.
 // Modifications: Implemented as Web Component for @gjsify/adwaita-web.
+import { WidgetElement } from '../widget-element.js';
 
-export class AdwCard extends HTMLElement {
+export class AdwCard extends WidgetElement {
     connectedCallback() {
         this.classList.add('adw-card');
     }

package/src/elements/adw-carousel.ts

@@ -36,9 +36,10 @@ import { CarouselState, carouselClosestSnapPoint, carouselPageAllocation } from
 import type { CarouselScrollRequest, CarouselScrollSource, CarouselStateChange } from '@gjsify/adwaita-core';
 
 import { attachSwipeDrag, type AdwSwipeDrag } from './swipe-drag.js';
+import { WidgetElement } from '../widget-element.js';
 
 /** Common surface an indicator binds to. The concrete element is AdwCarousel. */
-interface CarouselHost extends HTMLElement {
+interface CarouselHost extends WidgetElement {
     readonly nPages: number;
     readonly position: number;
     /** The page the current position settles on, `-1` when empty. */
@@ -70,7 +71,7 @@ function wheelSource(event: WheelEvent): CarouselScrollSource {
     return 'mouse';
 }
 
-export class AdwCarousel extends HTMLElement implements CarouselHost {
+export class AdwCarousel extends WidgetElement implements CarouselHost {
     private readonly _state = new CarouselState({
         // The DOM owns the scroll animation: `scrollTo` only asks, and the
         // scroll handler feeds the ramp back through `setPosition`.
@@ -103,6 +104,8 @@ export class AdwCarousel extends HTMLElement implements CarouselHost {
     private _scrollTargetId: string | null = null;
     /** The pointer-drag gesture, asked whether it owns the strip. See `_onWheel`. */
     private _drag: AdwSwipeDrag | undefined;
+    /** A `scroll_to` issued before the pages were adopted, run once they are. */
+    private _pendingScrollPage: HTMLElement | null = null;
 
     static get observedAttributes() {
         return ['allow-scroll-wheel', 'allow-mouse-drag', 'allow-long-swipes', 'interactive', 'spacing', 'position'];
@@ -272,6 +275,14 @@ export class AdwCarousel extends HTMLElement implements CarouselHost {
         // delivers attributes BEFORE `connectedCallback`, so reading it here is the
         // only way `<adw-carousel position="2">` works at all.
         this._applyAttribute('position', this.getAttribute('position'));
+
+        // Upstream defers a `scroll_to` that arrives before the first allocation to an
+        // idle (adw-carousel.c:1580-1595); the pages existing is the earliest this port
+        // can resolve one, and it lands where a declared `position` would.
+        const pending = this._pendingScrollPage;
+        this._pendingScrollPage = null;
+        const id = pending ? this._idOf(pending) : null;
+        if (id !== null) this._positionWhenMeasurable(this._state.indexOf(id));
     }
 
     attributeChangedCallback(name: string, _oldValue: string | null, newValue: string | null) {
@@ -450,6 +461,45 @@ export class AdwCarousel extends HTMLElement implements CarouselHost {
         return this._state.navigate(direction);
     }
 
+    /**
+     * `adw_carousel_scroll_to` — scroll to `widget`, one of the pages. A widget that is
+     * not one is refused, which is C's precondition; `animate = false` lands at once.
+     */
+    scroll_to(widget: HTMLElement, animate: boolean): void {
+        if (!this._initialized) {
+            if (widget.parentElement === this) this._pendingScrollPage = widget;
+            return;
+        }
+        const id = this._idOf(widget);
+        if (id === null) return;
+        this._state.scrollTo(this._state.indexOf(id), { animate });
+    }
+
+    /**
+     * `adw_carousel_get_nth_page` — the page at `n`. Past the last page C's precondition
+     * fails and returns NULL, so this returns `null`.
+     */
+    get_nth_page(n: number): HTMLElement | null {
+        if (!this._initialized) {
+            const declared = this.children[n];
+            return Number.isInteger(n) && declared instanceof HTMLElement ? declared : null;
+        }
+        if (!Number.isInteger(n) || n < 0 || n >= this._state.nPages) return null;
+        const id = this._state.ids[n];
+        const page = id === undefined ? null : this._slots.get(id)?.firstElementChild;
+        return page instanceof HTMLElement ? page : null;
+    }
+
+    /** `adw_carousel_get_n_pages`. */
+    get_n_pages(): number {
+        return this._initialized ? this._state.nPages : this.children.length;
+    }
+
+    /** `adw_carousel_get_position` — the {@link position} property. */
+    get_position(): number {
+        return this._state.position;
+    }
+
     private _insert(page: HTMLElement, position: number): boolean {
         const id = `page-${this._nextPageId++}`;
         if (!this._state.insertPage(id, position)) return false;
@@ -601,6 +651,15 @@ export class AdwCarousel extends HTMLElement implements CarouselHost {
         if (!this._trackEl) return;
         const distance = this._distance();
         if (!(distance > 0)) return;
+        // The model is already there (`adw_animation_skip`), so the offset follows at once
+        // and nothing waits for an arrival; a smooth scroll would feed the frames in
+        // between back into `position`.
+        if (!request.animate) {
+            this._pendingInteractive = null;
+            this._scrollTargetId = null;
+            this._trackEl.scrollTo({ left: request.index * distance, behavior: 'instant' });
+            return;
+        }
         this._pendingInteractive = request.interactive;
         this._scrollTargetId = this._state.ids[request.index] ?? null;
         // `offset = distance * position`, NOT `slot.offsetLeft` — that is measured from
@@ -673,7 +732,7 @@ export class AdwCarousel extends HTMLElement implements CarouselHost {
     }
 }
 
-abstract class AdwCarouselIndicator extends HTMLElement {
+abstract class AdwCarouselIndicator extends WidgetElement {
     protected _carousel: CarouselHost | null = null;
     protected _initialized = false;
 

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

@@ -53,6 +53,7 @@ import {
 } from '@gjsify/adwaita-core';
 
 import { bindSlottedChildren } from '../slotted-children.js';
+import { WidgetElement } from '../widget-element.js';
 
 /** `Gtk.ScrollablePolicy`'s three nicks, in enum order. */
 export type ScrollPolicy = 'automatic' | 'always' | 'never';
@@ -64,7 +65,7 @@ const POLICY_OVERFLOW: Record<ScrollPolicy, string> = {
     never: 'hidden',
 };
 
-export class AdwClampScrollable extends HTMLElement {
+export class AdwClampScrollable extends WidgetElement {
     private _resize: ResizeObserver | null = null;
     private _mutations: MutationObserver | null = null;