@gjsify/adwaita-web 0.41.0 → 0.43.0

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

@@ -68,6 +68,7 @@ import {
 } from '@gjsify/adwaita-core';
 
 import { createAdwIcon } from './adw-icon.js';
+import { AdwModalSurface } from './modal-surface.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 {
@@ -80,6 +81,7 @@ export class AdwAboutDialog extends HTMLElement {
     // Layout nodes (rebuilt from attributes on each render).
     private _scrimEl!: HTMLDivElement;
     private _sheetEl!: HTMLDivElement;
+    private _modal!: AdwModalSurface;
     private _navView!: HTMLElement;
     private _scrollEl!: HTMLDivElement;
     private _mainToolbarEl!: HTMLDivElement;
@@ -260,8 +262,6 @@ export class AdwAboutDialog extends HTMLElement {
 
         this._sheetEl = document.createElement('div');
         this._sheetEl.className = 'adw-about-dialog-sheet';
-        this._sheetEl.setAttribute('role', 'dialog');
-        this._sheetEl.setAttribute('aria-modal', 'true');
         // AdwDialog:title, whose template default is the bare word. The application
         // name is announced by the title-1 label inside, exactly as the header
         // revealer shows it separately in GTK.
@@ -269,12 +269,15 @@ export class AdwAboutDialog extends HTMLElement {
 
         this.replaceChildren(this._scrimEl, this._sheetEl);
 
-        // Escape dismisses while open (mirrors AdwDialog's close shortcut).
-        this.addEventListener('keydown', (event) => {
-            if (event.key === 'Escape' && this.open) {
-                event.stopPropagation();
-                this.close();
-            }
+        // The role, `aria-modal`, Escape, the Tab trap and the return-focus. No
+        // `initialFocus`: the sheet itself is the fallback, which is what this element
+        // used to focus by hand, and the navigation view's first control is better.
+        this._modal = new AdwModalSurface({
+            host: this,
+            surface: this._sheetEl,
+            role: 'dialog',
+            isOpen: () => this.open,
+            onEscape: () => this.close(),
         });
 
         this._render();
@@ -301,8 +304,9 @@ export class AdwAboutDialog extends HTMLElement {
             nav.replace?.(['main']);
             this._scrollEl.scrollTop = 0;
             this._updateHeaderTitle();
-            // Move focus into the sheet for keyboard dismissal.
-            requestAnimationFrame(() => this._sheetEl.focus());
+            this._modal.present();
+        } else {
+            this._modal.dismiss();
         }
     }
 
@@ -352,7 +356,6 @@ export class AdwAboutDialog extends HTMLElement {
         if (visibility.legalRow) this._navView.append(this._buildLegalPage());
 
         this._sheetEl.replaceChildren(this._navView);
-        this._sheetEl.tabIndex = -1;
 
         this.classList.toggle('open', this.open);
     }
@@ -382,10 +385,11 @@ export class AdwAboutDialog extends HTMLElement {
         header.setAttribute('title', headerTitle);
 
         if (showClose) {
-            // The close button — drawn with a CSS "×" glyph, the same approach as
-            // adw-tab-view's close affordance: `window-close` has no mask class,
-            // because it is not in the ICONS map in `scripts/build-scss.mjs` that
-            // generates them (`@gjsify/adwaita-icons` does export the SVG).
+            // The close button — drawn with a CSS "×" glyph, the same approach and the
+            // same reason as adw-tab-view's close affordance: `window-close` IS compiled
+            // and does have a mask class; what differs from upstream's
+            // `window-close-symbolic` (adw-sheet-controls.c:118) is the button size this
+            // header budgets for it.
             const close = document.createElement('button');
             close.type = 'button';
             close.className = 'adw-button flat circular adw-about-dialog-close';
@@ -430,9 +434,11 @@ export class AdwAboutDialog extends HTMLElement {
 
         // Only when one was given: GTK hides the image outright for an empty icon
         // name, and a generic glyph would show an icon for an application that asked
-        // for none. A reverse-DNS application id (`org.gnome.Builder`) is not one CSS
-        // token and resolves to no glyph rather than to three stray classes — see
-        // `normalizeIconName`.
+        // for none. A reverse-DNS application id (`org.gnome.Builder`) — what
+        // `adw_about_dialog_new_from_appdata` hands to `set_application_icon` in
+        // refs/libadwaita/src/adw-about-dialog.c — is not one CSS token, so it draws
+        // `image-missing` rather than three stray classes; that is also what GTK draws for
+        // it on a machine without the app installed.
         if (visibility.appIcon) {
             body.appendChild(createAdwIcon(this.applicationIcon, 'adw-about-dialog-icon'));
         }

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

@@ -16,6 +16,9 @@
 
 import { ActionRowState } from '@gjsify/adwaita-core';
 
+import { bindEmptySections } from '../empty-sections.js';
+import { type AdwRowActivation, attachRowActivation } from './row-activation.js';
+
 /**
  * Attributes whose change means the activatable widget's sensitivity may have
  * changed. `disabled` is the DOM's `GtkWidget:sensitive` for form controls;
@@ -39,6 +42,8 @@ export class AdwActionRow extends HTMLElement {
     /** Watches the activatable widget's `disabled`/`aria-disabled` — the live binding. */
     private _sensitivityObserver: MutationObserver | null = null;
     private _initialized = false;
+    /** Tab stop + Enter/Space, re-derived whenever `activatable` moves. */
+    private _activation?: AdwRowActivation;
 
     static get observedAttributes() {
         return ['title', 'subtitle', 'activatable'];
@@ -105,12 +110,20 @@ export class AdwActionRow extends HTMLElement {
         for (const child of suffixChildren) this._suffixEl.appendChild(child);
 
         this.replaceChildren(this._prefixEl, textEl, this._suffixEl);
+        // `_render` runs from `attributeChangedCallback`, which a control appended into
+        // `suffixSection` never triggers — the section stayed `hidden` and the control
+        // measured 0x0. The observer is what keeps the two sections in step with what
+        // they actually hold.
+        bindEmptySections(this._prefixEl, this._suffixEl);
         // `attributeChangedCallback` was guarded until now, so a parsed row would
         // otherwise start with a stale state.
         this._adoptAttributes();
         this._render();
 
         this.addEventListener('click', (event) => this._onClick(event));
+        // Only while `activatable` — a plain action row is a label, and a label that
+        // takes Tab makes every static row in a group a stop.
+        this._activation = attachRowActivation({ row: this, activatable: () => this._state.activatable });
     }
 
     /** Copy the declarative attributes into the headless state. */
@@ -178,9 +191,8 @@ export class AdwActionRow extends HTMLElement {
         this._titleEl.hidden = !titleVisible;
         this._subtitleEl.textContent = subtitle;
         this._subtitleEl.hidden = !subtitleVisible;
-        this._prefixEl.hidden = this._prefixEl.childElementCount === 0;
-        this._suffixEl.hidden = this._suffixEl.childElementCount === 0;
         this.classList.toggle('activatable', this._state.activatable);
+        this._activation?.sync();
     }
 }
 

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

@@ -44,6 +44,9 @@
 import { AdwAlertResponses } from '@gjsify/adwaita-core';
 import type { AdwResponseAppearance } from '@gjsify/adwaita-core';
 
+import { bindEmptySections } from '../empty-sections.js';
+import { AdwModalSurface } from './modal-surface.js';
+
 /** Response button appearance — mirrors Adw.ResponseAppearance. */
 export type { AdwResponseAppearance } from '@gjsify/adwaita-core';
 
@@ -67,6 +70,7 @@ export class AdwAlertDialog extends HTMLElement {
     private _bodyEl!: HTMLParagraphElement;
     private _childEl!: HTMLDivElement;
     private _responseAreaEl!: HTMLDivElement;
+    private _modal!: AdwModalSurface;
 
     /** The headless response registry + default/close semantics + resolution (ADR 0004). */
     private _model = new AdwAlertResponses();
@@ -149,10 +153,17 @@ export class AdwAlertDialog extends HTMLElement {
 
         this._dialogEl = document.createElement('div');
         this._dialogEl.className = 'adw-alert-dialog-box';
-        this._dialogEl.setAttribute('role', 'alertdialog');
-        this._dialogEl.setAttribute('aria-modal', 'true');
         // Clicks inside the box must not bubble to the scrim's dismiss handler.
         this._dialogEl.addEventListener('click', (event) => event.stopPropagation());
+        // The role, `aria-modal`, Escape, the Tab trap and the return-focus.
+        this._modal = new AdwModalSurface({
+            host: this,
+            surface: this._dialogEl,
+            role: 'alertdialog',
+            isOpen: () => this.open,
+            onEscape: () => this._dismiss(),
+            initialFocus: (focusables) => this._initialFocusTarget(focusables),
+        });
 
         const messageArea = document.createElement('div');
         messageArea.className = 'adw-alert-dialog-message';
@@ -168,6 +179,9 @@ export class AdwAlertDialog extends HTMLElement {
         for (const child of extraChildren) this._childEl.appendChild(child);
 
         messageArea.append(this._headingEl, this._bodyEl, this._childEl);
+        // `_render` runs from `attributeChangedCallback` and from the response API, and
+        // an extra child appended after connect triggers neither.
+        bindEmptySections(this._childEl);
 
         this._responseAreaEl = document.createElement('div');
         this._responseAreaEl.className = 'adw-alert-dialog-responses';
@@ -175,15 +189,6 @@ export class AdwAlertDialog extends HTMLElement {
         this._dialogEl.append(messageArea, this._responseAreaEl);
         this.replaceChildren(this._scrimEl, this._dialogEl);
 
-        // Escape dismisses the dialog when open (the AdwDialog Escape shortcut →
-        // close-response).
-        this.addEventListener('keydown', (event) => {
-            if (event.key === 'Escape' && this.open) {
-                event.stopPropagation();
-                this._dismiss();
-            }
-        });
-
         for (const el of declared) {
             const id = el.getAttribute('id');
             if (!id) continue;
@@ -217,7 +222,8 @@ export class AdwAlertDialog extends HTMLElement {
             this.dispatchEvent(new CustomEvent('notify::body', { bubbles: true, detail: { body: this.body } }));
         } else if (name === 'open') {
             this.dispatchEvent(new CustomEvent('notify::open', { bubbles: true, detail: { open: this.open } }));
-            if (this.open) this._focusInitial();
+            if (this.open) this._modal.present();
+            else this._modal.dismiss();
         }
     }
 
@@ -351,14 +357,29 @@ export class AdwAlertDialog extends HTMLElement {
         this.dispatchEvent(new CustomEvent('response', { bubbles: true, detail: { response } }));
     }
 
-    /** Move focus to the default response button (or the first enabled one). */
-    private _focusInitial(): void {
+    /**
+     * Where a presented alert puts focus, in the three steps `adw_alert_dialog_grab_focus`
+     * takes (refs/libadwaita/src/adw-alert-dialog.c:382): the CONTENT first
+     * (`adw_widget_grab_focus_child (priv->scrolled_window)`, :397), then the default
+     * widget (:406), then the first response whose `enabled` is set (:413). The default
+     * response is rarely the first button — a destructive alert opens on Cancel — and
+     * content beats it: an alert carrying an entry is answered by typing into it.
+     *
+     * `focusables` is the surface's own list, so what "focusable" means is decided once.
+     */
+    private _initialFocusTarget(focusables: readonly HTMLElement[]): HTMLElement | undefined {
+        return focusables.find((el) => this._childEl.contains(el)) ?? this._defaultResponseButton();
+    }
+
+    /** The default response button, or the first enabled one. */
+    private _defaultResponseButton(): HTMLElement | undefined {
         const defaultId = this._model.defaultResponse;
         const firstEnabledId = this._model.responses.find((response) => response.enabled)?.id;
-        const target =
-            (defaultId ? this._buttons.get(defaultId) : undefined) ??
-            (firstEnabledId ? this._buttons.get(firstEnabledId) : undefined);
-        target?.focus();
+        // The enabled check covers the DEFAULT too: `focus()` on a disabled button is a
+        // no-op, so handing one back left the dialog open with focus outside itself.
+        const defaultButton =
+            defaultId !== null && this._model.getResponseEnabled(defaultId) ? this._buttons.get(defaultId) : undefined;
+        return defaultButton ?? (firstEnabledId ? this._buttons.get(firstEnabledId) : undefined);
     }
 
     private _render(): void {
@@ -372,8 +393,6 @@ export class AdwAlertDialog extends HTMLElement {
         this._bodyEl.textContent = body;
         this._bodyEl.hidden = body.length === 0;
 
-        this._childEl.hidden = this._childEl.childElementCount === 0;
-
         // Horizontal only when prefer-wide-layout is set AND there are at most two
         // responses — the AdwAlertDialog heuristic for keeping wide buttons readable.
         const horizontal = this.preferWideLayout && this._model.responses.length <= 2;

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

@@ -22,6 +22,7 @@
 import { BUTTON_ROW_ACTIVATABLE, ButtonRowState } from '@gjsify/adwaita-core';
 
 import { type AdwIcon, createAdwIcon } from './adw-icon.js';
+import { attachRowActivation } from './row-activation.js';
 
 export class AdwButtonRow extends HTMLElement {
     private _contentsEl!: HTMLDivElement;
@@ -58,6 +59,8 @@ export class AdwButtonRow extends HTMLElement {
         this.addEventListener('click', () => {
             this.dispatchEvent(new CustomEvent('activated', { bubbles: true }));
         });
+        // `BUTTON_ROW_ACTIVATABLE`, not an attribute read: there is no opt-out to read.
+        attachRowActivation({ row: this, activatable: () => BUTTON_ROW_ACTIVATABLE });
     }
 
     attributeChangedCallback() {

package/src/elements/adw-carousel.ts

@@ -9,9 +9,14 @@
 // position compensation. This element is the DOM half only — scroll-snap strip,
 // offset↔position, DOM events.
 //
-// The three attribute defaults HTML cannot spell: `allow-scroll-wheel` and
-// `interactive` default TRUE, so `="false"` is the off switch; `allow-long-swipes`
-// is an ordinary presence attribute. `position` is the INITIAL page only —
+// The four attribute defaults HTML cannot spell: `allow-scroll-wheel`,
+// `allow-mouse-drag` and `interactive` default TRUE, so `="false"` is the off switch;
+// `allow-long-swipes` is an ordinary presence attribute.
+//
+// A MOUSE DRAG is `elements/swipe-drag.ts`, and it is the one gesture a browser gives
+// nothing for: touch and touchpad scroll this strip natively, a held mouse button does
+// not. Upstream turns it on in `init` (:1209) and exposes `allow-mouse-drag`, default
+// TRUE (:1091). Measured before: a 300 px drag moved `position` 0 → 0. `position` is the INITIAL page only —
 // write-only, with the live value on the `position` property and `notify::position`.
 //
 // `page-changed` (`detail = { index }`) fires on every settle, including back
@@ -27,9 +32,11 @@
 // Copyright (c) GNOME contributors (libadwaita). LGPLv2.1+.
 // Modifications: Implemented as Web Components for @gjsify/adwaita-web.
 
-import { CarouselState, carouselPageAllocation } from '@gjsify/adwaita-core';
+import { CarouselState, carouselClosestSnapPoint, carouselPageAllocation } from '@gjsify/adwaita-core';
 import type { CarouselScrollRequest, CarouselScrollSource, CarouselStateChange } from '@gjsify/adwaita-core';
 
+import { attachSwipeDrag, type AdwSwipeDrag } from './swipe-drag.js';
+
 /** Common surface an indicator binds to. The concrete element is AdwCarousel. */
 interface CarouselHost extends HTMLElement {
     readonly nPages: number;
@@ -94,9 +101,11 @@ export class AdwCarousel extends HTMLElement implements CarouselHost {
      * index while the target page stays the target.
      */
     private _scrollTargetId: string | null = null;
+    /** The pointer-drag gesture, asked whether it owns the strip. See `_onWheel`. */
+    private _drag: AdwSwipeDrag | undefined;
 
     static get observedAttributes() {
-        return ['allow-scroll-wheel', 'allow-long-swipes', 'interactive', 'spacing', 'position'];
+        return ['allow-scroll-wheel', 'allow-mouse-drag', 'allow-long-swipes', 'interactive', 'spacing', 'position'];
     }
 
     constructor() {
@@ -132,6 +141,18 @@ export class AdwCarousel extends HTMLElement implements CarouselHost {
         return this._state.pageAt(this._state.position);
     }
 
+    /**
+     * `AdwCarousel:allow-mouse-drag` — whether the strip can be dragged with the pointer.
+     * Defaults to TRUE, as in libadwaita, where FALSE leaves dragging to touch only.
+     */
+    get allowMouseDrag(): boolean {
+        return this._state.allowMouseDrag;
+    }
+
+    set allowMouseDrag(value: boolean) {
+        this.setAttribute('allow-mouse-drag', value ? 'true' : 'false');
+    }
+
     /** Whether the scroll wheel navigates between pages. Defaults to TRUE, as in libadwaita. */
     get allowScrollWheel(): boolean {
         return this._state.allowScrollWheel;
@@ -187,6 +208,7 @@ export class AdwCarousel extends HTMLElement implements CarouselHost {
         // Declared properties BEFORE children: `spacing` is part of the page pitch,
         // so a page added first would be measured against the wrong distance.
         this._applyAttribute('allow-scroll-wheel', this.getAttribute('allow-scroll-wheel'));
+        this._applyAttribute('allow-mouse-drag', this.getAttribute('allow-mouse-drag'));
         this._applyAttribute('allow-long-swipes', this.getAttribute('allow-long-swipes'));
         this._applyAttribute('interactive', this.getAttribute('interactive'));
         this._applyAttribute('spacing', this.getAttribute('spacing'));
@@ -200,6 +222,52 @@ export class AdwCarousel extends HTMLElement implements CarouselHost {
         this._trackEl.addEventListener('scroll', this._onScroll, { passive: true });
         this._trackEl.addEventListener('wheel', this._onWheel, { passive: false });
 
+        this._drag = attachSwipeDrag({
+            // On the TRACK, not on the host: the track is the scroll container the drag
+            // writes `scrollLeft` on, and it is what the pages live in.
+            host: this._trackEl,
+            orientation: 'horizontal',
+            // `interactive` gates it because that is exactly what it does upstream —
+            // `adw_carousel_set_interactive` is `adw_swipe_tracker_set_enabled` (:1705).
+            enabled: () => this._state.interactive && this._state.allowMouseDrag,
+            pitch: () => this._distance(),
+            points: () => this._state.snapPoints,
+            progress: () => this._state.position,
+            allowLongSwipes: () => this._state.allowLongSwipes,
+            // `adw_carousel_get_cancel_progress` is `get_closest_snap_point`
+            // (adw-carousel.c:1294-1299) — the page nearest where the gesture was
+            // interrupted, NOT the one it started from.
+            //
+            // `carouselClosestSnapPoint` and NOT `_state.pageAt`, for two reasons that
+            // both make the answer a different page. `pageAt` searches the VISIBLE snap
+            // points (it filters out children being removed) and returns an index into
+            // that filtered array, so subscripting the unfiltered list with it shifts by
+            // one for every removing child ahead of the target. And it is the
+            // `count_removing = FALSE` variant, while `get_closest_snap_point` passes
+            // TRUE (adw-carousel.c:1298) — this is the one call site that counts them.
+            //
+            // The POINT, not an index: a page mid-reveal has a fractional size, so
+            // `carouselSnapPoints` (cumulative size − 1) hands back non-integers.
+            cancelProgress: () => {
+                const points = this._state.snapPoints;
+                return points[carouselClosestSnapPoint(this._state.position, points)] ?? this._state.position;
+            },
+            // The DRAG writes the offset directly and the existing scroll handler reads
+            // the position back off it — the same path a touch scroll takes, so there is
+            // no second route into `position` to drift from this one.
+            onUpdate: (progress) => {
+                const distance = this._distance();
+                if (distance > 0) this._trackEl.scrollLeft = progress * distance;
+            },
+            // `scroll_to` with the swipe's velocity is what `end_swipe_cb` does (:434).
+            // Here the settle is the browser's smooth scroll, so the velocity is unused
+            // — snap is already restored, and `to` is a snap point by construction.
+            onEnd: (progress) => {
+                const distance = this._distance();
+                if (distance > 0) this._trackEl.scrollTo({ left: progress * distance });
+            },
+        });
+
         // Applied last, once the pages it names exist. Custom-element upgrade
         // delivers attributes BEFORE `connectedCallback`, so reading it here is the
         // only way `<adw-carousel position="2">` works at all.
@@ -246,6 +314,10 @@ export class AdwCarousel extends HTMLElement implements CarouselHost {
                 // usual "presence = on" spelling would invert it.
                 this._state.setAllowScrollWheel(value !== 'false');
                 return;
+            case 'allow-mouse-drag':
+                // Absent means TRUE, like `allow-scroll-wheel` and for the same reason.
+                this._state.setAllowMouseDrag(value !== 'false');
+                return;
             case 'allow-long-swipes':
                 this._state.setAllowLongSwipes(value !== null && value !== 'false');
                 this._applySnapStop();
@@ -546,6 +618,15 @@ export class AdwCarousel extends HTMLElement implements CarouselHost {
     };
 
     private _onWheel = (event: WheelEvent): void => {
+        // A drag owns the offset while it is claimed. Without this a single wheel notch
+        // mid-drag ran the whole paging path and moved `scrollLeft` a full page in one
+        // frame — measured 80 → 440 — which the next pointer move then yanked back, and
+        // it left `_scrollTargetId` pointing at a page the drag overrode. `GDK_EVENT_STOP`
+        // rather than propagate, because the gesture IS handling this widget's scrolling.
+        if (this._drag?.dragging === true) {
+            event.preventDefault();
+            return;
+        }
         const step = this._state.handleWheel({
             deltaX: event.deltaX,
             deltaY: event.deltaY,

package/src/elements/adw-clamp.ts

@@ -40,8 +40,9 @@ export class AdwClamp extends HTMLElement {
         this._resize = new ResizeObserver(() => this._allocate());
         this._resize.observe(this);
         // Children appended AFTER connect are clamped too. Without this they
-        // would keep whatever width they came with — the same "evaluated once at
-        // connect time" bug the toolbar view's empty-bar handling still has.
+        // would keep whatever width they came with — the "evaluated once at
+        // connect time" bug that cost six container getters their layout;
+        // `src/empty-sections.ts` is the same technique for the `hidden` half.
         this._mutations = new MutationObserver(() => this._allocate());
         this._mutations.observe(this, { childList: true });
         this._allocate();

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

@@ -52,8 +52,11 @@
 // column tracks, the cell classes, the two normalisers, the cell text and the activation
 // rule. `@gjsify/adwaita-nativescript` renders the same widget over `GridLayout`
 // `ItemSpec`s — NativeScript has no subgrid — so the TRACK rule is a renderer-neutral
-// descriptor and only the mapping onto `grid-template-columns` stays here. Both ports
-// are held to `@gjsify/adwaita-core/conformance`'s `DATA_GRID_*_VECTORS`.
+// descriptor and only the mapping onto `grid-template-columns` stays here. The NativeScript
+// suite is held to DATA_GRID_TRACK_VECTORS, DATA_GRID_COLUMN_CLASS_VECTORS,
+// DATA_GRID_VARIANT_VECTORS, DATA_GRID_CELL_TEXT_VECTORS and DATA_GRID_INTERACTIVE_VECTORS.
+// This element is held to none of them — the browser half of the shared derivation is
+// asserted only against itself, which is the gap, not the arrangement.
 // Reference: Gtk.Grid usage in the Buchhaltung BWA view (native financial grid).
 // Reference: refs/libadwaita/src/stylesheet/_colors.scss (separator / card tokens).
 // Copyright (c) GNOME contributors (libadwaita). LGPLv2.1+.

package/src/elements/adw-dialog.ts

@@ -24,21 +24,14 @@
 // Copyright (c) 2023-2024 GNOME Foundation Inc. (libadwaita). LGPLv2.1+.
 // Modifications: Implemented as a Web Component for @gjsify/adwaita-web.
 
+import { AdwModalSurface } from './modal-surface.js';
+
 /** Adaptive presentation of the dialog — mirrors Adw.DialogPresentationMode. */
 export type AdwDialogPresentationMode = 'auto' | 'floating' | 'bottom-sheet';
 
 const DEFAULT_CONTENT_WIDTH = 360;
 const PRESENTATION_MODES: readonly AdwDialogPresentationMode[] = ['auto', 'floating', 'bottom-sheet'];
 
-const FOCUSABLE_SELECTOR = [
-    'a[href]',
-    'button:not([disabled])',
-    'input:not([disabled])',
-    'select:not([disabled])',
-    'textarea:not([disabled])',
-    '[tabindex]:not([tabindex="-1"])',
-].join(',');
-
 export class AdwDialog extends HTMLElement {
     private _initialized = false;
     private _scrimEl!: HTMLDivElement;
@@ -47,8 +40,7 @@ export class AdwDialog extends HTMLElement {
     private _titleEl!: HTMLSpanElement;
     private _closeBtn!: HTMLButtonElement;
     private _contentEl!: HTMLDivElement;
-    // The element focused before present(), restored on close (return-focus).
-    private _previouslyFocused: HTMLElement | null = null;
+    private _modal!: AdwModalSurface;
 
     static get observedAttributes() {
         return ['title', 'open', 'can-close', 'content-width', 'content-height', 'presentation-mode', 'show-header'];
@@ -157,15 +149,19 @@ export class AdwDialog extends HTMLElement {
         this._scrimEl.className = 'adw-dialog-scrim';
         this._scrimEl.addEventListener('click', () => this._attemptClose());
 
-        // Focusable so the box receives keys even when the content has none, and clicks
-        // inside must not reach the scrim's dismiss handler.
+        // Clicks inside must not reach the scrim's dismiss handler. The role, `aria-modal`
+        // and the -1 tabindex that lets the box hold focus when its content has none all
+        // come from the modal surface below.
         this._boxEl = document.createElement('div');
         this._boxEl.className = 'adw-dialog-box';
-        this._boxEl.setAttribute('role', 'dialog');
-        this._boxEl.setAttribute('aria-modal', 'true');
-        this._boxEl.tabIndex = -1;
         this._boxEl.addEventListener('click', (event) => event.stopPropagation());
-        this._boxEl.addEventListener('keydown', (event) => this._onBoxKeyDown(event));
+        this._modal = new AdwModalSurface({
+            host: this,
+            surface: this._boxEl,
+            role: 'dialog',
+            isOpen: () => this.open,
+            onEscape: () => this._attemptClose(),
+        });
 
         this._headerEl = document.createElement('div');
         this._headerEl.className = 'adw-dialog-header';
@@ -206,7 +202,7 @@ export class AdwDialog extends HTMLElement {
         this._render();
         if (name === 'open') {
             this.dispatchEvent(new CustomEvent('notify::open', { bubbles: true, detail: { open: this.open } }));
-            if (this.open) this._onPresented();
+            if (this.open) this._modal.present();
             else this._onClosed();
         }
     }
@@ -222,53 +218,10 @@ export class AdwDialog extends HTMLElement {
         this.open = false;
     }
 
-    /** Focus trap + Escape while the box has focus. */
-    private _onBoxKeyDown(event: KeyboardEvent): void {
-        if (event.key === 'Escape' && this.open) {
-            event.stopPropagation();
-            this._attemptClose();
-            return;
-        }
-        if (event.key !== 'Tab') return;
-        const focusables = this._focusables();
-        if (focusables.length === 0) {
-            // Nothing tabbable inside — keep focus on the box.
-            event.preventDefault();
-            this._boxEl.focus();
-            return;
-        }
-        const first = focusables[0];
-        const last = focusables[focusables.length - 1];
-        const active = document.activeElement;
-        if (event.shiftKey && (active === first || active === this._boxEl)) {
-            event.preventDefault();
-            last.focus();
-        } else if (!event.shiftKey && active === last) {
-            event.preventDefault();
-            first.focus();
-        }
-    }
-
-    private _focusables(): HTMLElement[] {
-        return Array.from(this._boxEl.querySelectorAll<HTMLElement>(FOCUSABLE_SELECTOR)).filter(
-            (el) => !el.hasAttribute('disabled') && !el.hidden,
-        );
-    }
-
-    /** On present: remember focus, then move it into the dialog. */
-    private _onPresented(): void {
-        const active = document.activeElement;
-        this._previouslyFocused = active instanceof HTMLElement && active !== this ? active : null;
-        const target = this._focusables()[0] ?? this._boxEl;
-        target.focus();
-    }
-
-    /** On close: emit `closed` and return focus to where it was before present. */
+    /** On close: emit `closed`, then let the surface return focus to where it was. */
     private _onClosed(): void {
         this.dispatchEvent(new CustomEvent('closed', { bubbles: true }));
-        const restore = this._previouslyFocused;
-        this._previouslyFocused = null;
-        if (restore && restore.isConnected) restore.focus();
+        this._modal.dismiss();
     }
 
     private _render(): void {

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

@@ -13,7 +13,7 @@
 // the `expanded` attribute reflection and the event.
 //
 // Reference: refs/adwaita-web/adwaita-web/scss/_expander_row.scss
-// Reference: refs/libadwaita/src/stylesheet/widgets/_expander-row.scss
+// Reference: refs/libadwaita/src/stylesheet/widgets/_lists.scss (AdwExpanderRow)
 // Copyright (c) GNOME contributors (libadwaita). LGPLv2.1+.
 // Modifications: Implemented as a Web Component for @gjsify/adwaita-web; the
 // disclosure state machine composed from @gjsify/adwaita-core, the enable
@@ -21,6 +21,8 @@
 
 import { ExpanderState, deriveRowLabels } from '@gjsify/adwaita-core';
 
+import { bindEmptySections } from '../empty-sections.js';
+
 // SIDE-EFFECT import, deliberately separate from the type import below: it guarantees
 // `adw-switch` is defined before this module's `customElements.define` can upgrade a
 // server-rendered `<adw-expander-row>` and build one. A combined
@@ -30,6 +32,7 @@ import { ExpanderState, deriveRowLabels } from '@gjsify/adwaita-core';
 import './adw-switch.js';
 import type { AdwSwitch } from './adw-switch.js';
 import { type AdwIcon, createAdwIcon } from './adw-icon.js';
+import { attachRowActivation } from './row-activation.js';
 
 export class AdwExpanderRow extends HTMLElement {
     private _headerEl!: HTMLDivElement;
@@ -133,6 +136,12 @@ export class AdwExpanderRow extends HTMLElement {
         this._suffixEl.className = 'adw-expander-row-suffix';
         for (const child of suffixChildren) this._suffixEl.appendChild(child);
 
+        // Same reason as the action row's: `_render` is attribute-driven, and a widget
+        // appended into `prefixSection` after connect is a childList change nothing else
+        // hears. `contentSection` is NOT in here — an empty disclosure is still the
+        // disclosure, and `.expanded` alone decides whether it shows.
+        bindEmptySections(this._prefixEl, this._suffixEl);
+
         this._headerEl.append(this._prefixEl, textEl, this._suffixEl, this._enableSwitch, this._chevronEl);
 
         this._contentEl = document.createElement('div');
@@ -154,6 +163,11 @@ export class AdwExpanderRow extends HTMLElement {
             }
         });
 
+        // adw-expander-row.c:123 — `grab_focus` forwards to the header row, so the header
+        // is both the focus target and the disclosure control. Enter and Space go through
+        // its click handler, which is what a pointer already uses.
+        attachRowActivation({ row: this._headerEl, activatable: () => true });
+
         this._enableSwitch.addEventListener('notify::active', (event) => {
             // The switch's own notify stops at the row: the row publishes
             // `notify::enable-expansion`, and letting `notify::active` past would give
@@ -201,10 +215,10 @@ export class AdwExpanderRow extends HTMLElement {
         this._enableSwitch.active = this.enableExpansion;
         this._reflectingEnable = false;
 
-        this._prefixEl.hidden = this._prefixEl.childElementCount === 0;
-        this._suffixEl.hidden = this._suffixEl.childElementCount === 0;
-
         this.classList.toggle('expanded', this.expanded);
+        // adw-expander-row.c:657 keeps GTK_ACCESSIBLE_STATE_EXPANDED on the header row in
+        // step with the flag; `aria-expanded` is the same statement to the same reader.
+        this._headerEl.setAttribute('aria-expanded', String(this.expanded));
         this._contentEl.classList.toggle('expanded', this.expanded);
     }
 }