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

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

@@ -20,7 +20,7 @@
 // properties of the same name, hyphenated):
 //   application-name   the application's display name (shown as a title-1)
 //   application-icon   an icon name, by convention the application ID; drawn in
-//                        colour once `registerColorIcon(id, …)` registered it, else
+//                        colour from the app's GResource icons (ADR 0116), else
 //                        as a symbolic glyph or `image-missing` (`<gtk-image>`'s
 //                        lookup); absent one, no icon is drawn
 //   developer-name     the developer / vendor line below the name
@@ -34,16 +34,22 @@
 //   license            the license text/name (Legal page); with a `license-url`
 //                        the name becomes a link
 //   license-url        a URL the license name links to
+//   release-notes      AppStream release-notes markup — a What's New row + page,
+//                        the buffer from the core's `releaseNotesBuffer`
+//   release-notes-version  the version the What's New heading names, else `version`
+//   debug-info         an opaque blob — a Troubleshooting row + page with Copy Text
 //   open               (boolean) whether the dialog is presented
 //
 // List-valued credits are set via properties (string arrays), mirroring the
 // AdwAboutDialog `developers` / `designers` / `artists` / `documenters` properties
 // — entries may be `Name`, `Name <email>` or `Name https://url`, parsed by the
-// core's `parseCreditPerson` (`parse_person`).
+// core's `parseCreditPerson` (`parse_person`). `add_link (title, url)` appends a
+// Details-page link row, as on GTK.
 //
-// NOT implemented here, so the core derivations see them empty: `release-notes` +
-// the What's New page, `debug-info` + the Troubleshooting page, `add_link`,
-// `add_credit_section`, `translator-credits` and the Acknowledgements page.
+// NOT implemented here, so the core derivations see them empty: `add_credit_section`,
+// `translator-credits`, the Acknowledgements page, and the debug page's "Save As…"
+// button (`debug-info-filename`), which needs a file dialog. `new_from_appdata` is
+// refused by name: it needs an AppStream parser.
 //
 // Events (CustomEvent, bubbles): `notify::open` (detail `{ open }`), `closed`, and
 // `activate-link` (detail `{ uri }`, CANCELABLE — the signal's `true_handled`
@@ -63,21 +69,29 @@ import {
     ADW_ABOUT_DIALOG_LABELS,
     type AdwCreditPerson,
     GTK_LICENSE,
+    type ReleaseNotesSegment,
+    Toast,
     aboutDialogVisibility,
     creditsSections,
     legalSectionVisible,
+    refuseNewFromAppdata,
+    releaseNotesBuffer,
     stripMnemonic,
 } from '@gjsify/adwaita-core';
 
+import { webClipboardHost } from '../clipboard-host.js';
+import type { AdwToastOverlay } from './adw-toast-overlay.js';
+import './adw-toast-overlay.js';
 import { createGtkImage } from './gtk-image.js';
 import { AdwModalSurface } from './modal-surface.js';
+import { WidgetElement } from '../widget-element.js';
 
 /** A template label with its mnemonic marker removed — this renderer has no accelerator layer. */
 function rowLabel(key: keyof typeof ADW_ABOUT_DIALOG_LABELS): string {
     return stripMnemonic(ADW_ABOUT_DIALOG_LABELS[key]);
 }
 
-export class AdwAboutDialog extends HTMLElement {
+export class AdwAboutDialog extends WidgetElement {
     private _initialized = false;
 
     // Layout nodes (rebuilt from attributes on each render).
@@ -94,6 +108,15 @@ export class AdwAboutDialog extends HTMLElement {
     private _artists: string[] = [];
     private _documenters: string[] = [];
 
+    /** `add_link` rows, in order; `has_custom_links` latches with the first. */
+    private _links: { title: string; url: string }[] = [];
+    /**
+     * The What's New buffer. Only the two release-notes setters rebuild it, never
+     * `version` (`update_release_notes` is called from those two alone).
+     */
+    private _releaseNotesSegments: ReleaseNotesSegment[] = [];
+    private _toastOverlay!: AdwToastOverlay;
+
     static get observedAttributes() {
         return [
             'application-name',
@@ -107,10 +130,18 @@ export class AdwAboutDialog extends HTMLElement {
             'copyright',
             'license',
             'license-url',
+            'release-notes',
+            'release-notes-version',
+            'debug-info',
             'open',
         ];
     }
 
+    /** `adw_about_dialog_new_from_appdata`, refused by name. */
+    static new_from_appdata(_resourcePath: string, _releaseNotesVersion?: string | null): never {
+        refuseNewFromAppdata();
+    }
+
     get applicationName(): string {
         return this.getAttribute('application-name') ?? '';
     }
@@ -199,6 +230,36 @@ export class AdwAboutDialog extends HTMLElement {
         this.setAttribute('license-url', value);
     }
 
+    get releaseNotes(): string {
+        return this.getAttribute('release-notes') ?? '';
+    }
+
+    set releaseNotes(value: string) {
+        this.setAttribute('release-notes', value);
+    }
+
+    get releaseNotesVersion(): string {
+        return this.getAttribute('release-notes-version') ?? '';
+    }
+
+    set releaseNotesVersion(value: string) {
+        this.setAttribute('release-notes-version', value);
+    }
+
+    get debugInfo(): string {
+        return this.getAttribute('debug-info') ?? '';
+    }
+
+    set debugInfo(value: string) {
+        this.setAttribute('debug-info', value);
+    }
+
+    /** `adw_about_dialog_add_link`: a Details-page link row; `_` marks a mnemonic. */
+    add_link(title: string, url: string): void {
+        this._links.push({ title, url });
+        if (this._initialized) this._render();
+    }
+
     get open(): boolean {
         return this.hasAttribute('open');
     }
@@ -269,6 +330,11 @@ export class AdwAboutDialog extends HTMLElement {
         // revealer shows it separately in GTK.
         this._sheetEl.setAttribute('aria-label', ADW_ABOUT_DIALOG_LABELS.dialogTitle);
 
+        // The template's `toast_overlay`, around the navigation view: "Copied to
+        // clipboard" is shown inside the sheet.
+        this._toastOverlay = document.createElement('adw-toast-overlay') as AdwToastOverlay;
+        this._sheetEl.appendChild(this._toastOverlay);
+
         this.replaceChildren(this._scrimEl, this._sheetEl);
 
         // The role, `aria-modal`, Escape, the Tab trap and the return-focus. No
@@ -286,8 +352,19 @@ export class AdwAboutDialog extends HTMLElement {
     }
 
     attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null) {
-        if (!this._initialized) return;
         if (oldValue === newValue) return;
+        // Before the guard: the heading reads `version` as it is when the NOTES change.
+        if (name === 'release-notes' || name === 'release-notes-version') {
+            this._releaseNotesSegments = releaseNotesBuffer(
+                {
+                    releaseNotes: this.releaseNotes,
+                    releaseNotesVersion: this.releaseNotesVersion,
+                    version: this.version,
+                },
+                ADW_ABOUT_DIALOG_LABELS,
+            ).segments;
+        }
+        if (!this._initialized) return;
         if (name === 'open') {
             this._syncOpen();
             this.dispatchEvent(new CustomEvent('notify::open', { bubbles: true, detail: { open: this.open } }));
@@ -344,20 +421,31 @@ export class AdwAboutDialog extends HTMLElement {
             website: this.website,
             supportUrl: this.supportUrl,
             issueUrl: this.issueUrl,
+            debugInfo: this.debugInfo,
+            releaseNotes: this.releaseNotes,
+            hasCustomLinks: this._links.length > 0,
             hasCredits: sections.length > 0,
             hasLegal: this._hasLegal(),
         });
 
+        this._navView?.remove();
         this._navView = document.createElement('adw-navigation-view');
         this._navView.append(this._buildMainPage(visibility));
 
-        // The Details page exists exactly when its row does — `details_row` is
+        // A subpage exists exactly when its row does — `details_row` is
         // `has_comments || show_links`, i.e. "the page has content".
+        if (visibility.whatsNewRow) this._navView.append(this._buildWhatsNewPage());
         if (visibility.detailsRow) this._navView.append(this._buildDetailsPage(visibility));
+        if (visibility.troubleshootingRow) {
+            this._navView.append(this._buildTroubleshootingPage(), this._buildDebugInfoPage());
+        }
         if (visibility.creditsRow) this._navView.append(this._buildCreditsPage(sections));
         if (visibility.legalRow) this._navView.append(this._buildLegalPage());
 
-        this._sheetEl.replaceChildren(this._navView);
+        // Straight into the overlay's content box: appended to the overlay itself, the view
+        // is re-homed a microtask later, and that move drops the focus `present` put in it.
+        const content = this._toastOverlay.querySelector(':scope > .adw-toast-overlay-content');
+        (content ?? this._toastOverlay).appendChild(this._navView);
 
         this.classList.toggle('open', this.open);
     }
@@ -471,6 +559,9 @@ export class AdwAboutDialog extends HTMLElement {
         // support_group, credits_legal_group) — groups, not one list, and the
         // stylesheet already spaces consecutive `.adw-about-dialog-rows` apart.
         const detailsGroupRows: HTMLElement[] = [];
+        if (visibility.whatsNewRow) {
+            detailsGroupRows.push(this._buildNavRow(rowLabel('whatsNewRow'), 'whatsnew'));
+        }
         if (visibility.detailsRow) {
             detailsGroupRows.push(this._buildNavRow(rowLabel('detailsRow'), 'details'));
         }
@@ -485,6 +576,9 @@ export class AdwAboutDialog extends HTMLElement {
         if (visibility.issueRow) {
             supportGroupRows.push(this._buildLinkRow(rowLabel('issueRow'), this.issueUrl));
         }
+        if (visibility.troubleshootingRow) {
+            supportGroupRows.push(this._buildNavRow(rowLabel('troubleshootingRow'), 'troubleshooting'));
+        }
 
         const creditsLegalRows: HTMLElement[] = [];
         if (visibility.creditsRow) creditsLegalRows.push(this._buildNavRow(rowLabel('creditsRow'), 'credits'));
@@ -559,12 +653,61 @@ export class AdwAboutDialog extends HTMLElement {
             if (visibility.detailsWebsiteRow) {
                 rows.push(this._buildLinkRow(rowLabel('websiteRow'), this.website));
             }
+            for (const link of this._links) rows.push(this._buildLinkRow(stripMnemonic(link.title), link.url));
             body.appendChild(this._buildGroup('links', rows));
         }
 
         return page;
     }
 
+    /** The release-notes buffer as tagged runs, white space kept (a GtkTextView). */
+    private _buildWhatsNewPage(): HTMLElement {
+        const { page, body } = this._buildPage('whatsnew', ADW_ABOUT_DIALOG_LABELS.whatsNewPage, false);
+        const notes = document.createElement('div');
+        notes.className = 'adw-about-dialog-release-notes';
+        for (const segment of this._releaseNotesSegments) {
+            const span = document.createElement('span');
+            if (segment.tag !== null) span.dataset['tag'] = segment.tag;
+            span.textContent = segment.text;
+            notes.appendChild(span);
+        }
+        body.appendChild(notes);
+        return page;
+    }
+
+    private _buildTroubleshootingPage(): HTMLElement {
+        const { page, body } = this._buildPage('troubleshooting', ADW_ABOUT_DIALOG_LABELS.troubleshootingPage, false);
+        const intro = document.createElement('p');
+        intro.className = 'adw-about-dialog-comments';
+        intro.textContent = ADW_ABOUT_DIALOG_LABELS.troubleshootingIntro;
+        body.append(intro, this._buildGroup(null, [this._buildNavRow(rowLabel('debugInfoRow'), 'debuginfo')]));
+        return page;
+    }
+
+    /** The debug text and Copy Text — the `about.copy-property` action on `debug-info`. */
+    private _buildDebugInfoPage(): HTMLElement {
+        const { page, body } = this._buildPage('debuginfo', ADW_ABOUT_DIALOG_LABELS.debugInfoPage, false);
+        const text = document.createElement('pre');
+        text.className = 'adw-about-dialog-debug-info';
+        text.textContent = this.debugInfo;
+
+        const copy = document.createElement('button');
+        copy.type = 'button';
+        copy.className = 'adw-button pill adw-about-dialog-copy';
+        copy.textContent = rowLabel('copyText');
+        copy.addEventListener('click', () => this._copyProperty(this.debugInfo));
+
+        body.append(text, copy);
+        return page;
+    }
+
+    /** `copy_property_cb`: an empty value copies nothing and shows no toast. */
+    private _copyProperty(value: string): void {
+        if (value.length === 0) return;
+        void Promise.resolve(webClipboardHost.writeText(value)).catch(() => undefined);
+        this._toastOverlay.add_toast(new Toast({ title: ADW_ABOUT_DIALOG_LABELS.copiedToast }));
+    }
+
     private _buildLinkRow(title: string, uri: string): HTMLElement {
         const row = document.createElement('adw-action-row');
         row.setAttribute('title', title);

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

@@ -31,6 +31,7 @@ import { installElementApi } from '../gobject-elements.js';
 import type { DispatchedSignals } from '../signals.js';
 import { type AdwRowActivation, attachRowActivation } from './row-activation.js';
 import { applyRowLineClamp, parseRowLinesAttribute } from '../row-line-clamp.js';
+import { TooltipElement } from '../widget-element.js';
 
 /**
  * Attributes whose change means the activatable widget's sensitivity may have
@@ -45,7 +46,7 @@ function isSensitive(widget: HTMLElement): boolean {
     return widget.getAttribute('aria-disabled') !== 'true';
 }
 
-export class AdwActionRow extends HTMLElement {
+export class AdwActionRow extends TooltipElement {
     /** The GTK signals this element dispatches, each with the DOM event it arrives as (ADR 0093). */
     static readonly signals: DispatchedSignals = { activated: 'activated' };
 

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

@@ -75,6 +75,7 @@ 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';
@@ -85,7 +86,7 @@ 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'];
     }
@@ -107,7 +108,7 @@ export interface AdwAlertDialogProps {
     preferWideLayout?: boolean;
 }
 
-export class AdwAlertDialog extends HTMLElement {
+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',

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

@@ -68,6 +68,7 @@ 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 {
@@ -104,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;

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;
 

package/src/elements/adw-clamp.ts

@@ -27,8 +27,9 @@
 import { ADW_CLAMP_DEFAULTS, ADW_CLAMP_SIZE_CLASSES, clampAllocate, normalizeClampSize } from '@gjsify/adwaita-core';
 
 import { bindSlottedChildren } from '../slotted-children.js';
+import { WidgetElement } from '../widget-element.js';
 
-export class AdwClamp extends HTMLElement {
+export class AdwClamp extends WidgetElement {
     private _resize: ResizeObserver | null = null;
     private _mutations: MutationObserver | null = null;
 

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

@@ -65,8 +65,9 @@ import { applyRowTooltip } from '../row-tooltip.js';
 import { bindSlottedChildren } from '../slotted-children.js';
 import { stringListSlot } from '../string-list-slot.js';
 import { applyRowLineClamp, parseRowLinesAttribute } from '../row-line-clamp.js';
+import { TooltipElement } from '../widget-element.js';
 
-export class AdwComboRow extends HTMLElement {
+export class AdwComboRow extends TooltipElement {
     private _select!: HTMLSelectElement;
     private _valueEl!: HTMLSpanElement;
     /** The label column — kept for `tooltip-text`, which the browser reads off a PART. */
@@ -92,6 +93,11 @@ export class AdwComboRow extends HTMLElement {
         this._state.setModel(normalizeComboOptions(value));
     }
 
+    /** `adw_combo_row_set_model`. */
+    set_model(model: AdwListModelInput | null): void {
+        this.model = model ?? [];
+    }
+
     /**
      * The selected index (Adw.ComboRow:selected). PERMISSIVE: an index past the end is
      * accepted and reads back with an empty {@link selectedValue}, mirroring the `guint`
@@ -107,6 +113,14 @@ export class AdwComboRow extends HTMLElement {
         this.setAttribute('selected', String(value));
     }
 
+    get_selected(): number {
+        return this.selected;
+    }
+
+    set_selected(position: number): void {
+        this.selected = position;
+    }
+
     /**
      * The selected option's `value`, or '' when nothing is selected (Adw.ComboRow:selected-item).
      *

package/src/elements/adw-data-grid.ts

@@ -72,6 +72,7 @@ import {
     normalizeDataGridVariant,
 } from '@gjsify/adwaita-core';
 import type { AdwDataGridColumn, AdwDataGridRow } from '@gjsify/adwaita-core';
+import { WidgetElement } from '../widget-element.js';
 
 export type {
     AdwDataGridAlign,
@@ -81,7 +82,7 @@ export type {
     AdwDataGridRowVariant,
 } from '@gjsify/adwaita-core';
 
-export class AdwDataGrid extends HTMLElement {
+export class AdwDataGrid extends WidgetElement {
     private _captionEl!: HTMLDivElement;
     private _scrollEl!: HTMLDivElement;
     private _tableEl!: HTMLDivElement;