@gjsify/adwaita-web 0.40.0 → 0.42.0

package/src/elements/adw-tab-view.ts

@@ -57,6 +57,9 @@ export type AdwTabViewPageSpec = AdwTabPageSpec<HTMLElement>;
 /** The live `<adw-tab-page>` properties, each mapped onto a state setter. */
 const PAGE_ATTRIBUTES = ['title', 'tooltip', 'icon', 'indicator-icon', 'loading', 'needs-attention', 'pinned'];
 
+/** `SPACING`: the slack `scroll_to_tab_full` allows before it scrolls (adw-tab-box.c:24). */
+const TAB_SPACING = 5;
+
 /**
  * A single page. Declared as a child of <adw-tab-view>; the element itself becomes the
  * page panel, so its attributes keep driving the tab after connect — a renderer that
@@ -497,10 +500,13 @@ export class AdwTabView extends HTMLElement {
 
         tab.appendChild(createAdwIcon(null, 'adw-tab-indicator'));
 
-        // Close affordance — a small flat button drawn with a CSS "×" glyph, because
-        // `window-close` has no mask class: it is not in the ICONS map in
-        // `scripts/build-scss.mjs` that generates them. `can-focus=False` in C, so it
-        // stays out of the tab order here too.
+        // Close affordance — a small flat button drawn with a CSS "×" glyph. NOT because
+        // the glyph is unavailable: `window-close` is in the ICONS map and has a mask class
+        // (the comment that used to stand here said otherwise, and was read by two more
+        // widgets). It is a SIZING difference — upstream's close button is 24px around a
+        // 16px symbolic (adw-tab.ui:77), this strip's chip budgets 18px, and a 16px-grid
+        // symbolic scaled into it is a design change, not a rename.
+        // `can-focus=False` in C, so it stays out of the tab order here too.
         const close = document.createElement('button');
         close.type = 'button';
         close.className = 'adw-tab-close';
@@ -581,6 +587,20 @@ export class AdwTabView extends HTMLElement {
         this._refreshCloseVisibility(id);
     }
 
+    /**
+     * `get_tab_position` in the BAR's scroll space: how far the chip sits from the
+     * strip's scroll origin, the one coordinate both `scroll_to_tab_full` and
+     * `update_visible` compare against the adjustment.
+     *
+     * Never `offsetLeft`. Nothing in this widget is positioned, so a chip's offsetParent
+     * is whichever positioned ancestor the HOST page happens to have; a tab view that
+     * merely sits indented then measured every chip against the wrong origin and
+     * reported all of them clipped.
+     */
+    private _tabPosition(tab: HTMLElement): number {
+        return tab.getBoundingClientRect().left - this._barEl.getBoundingClientRect().left + this._barEl.scrollLeft;
+    }
+
     /**
      * `tabCloseVisible`, with its pinned gate. `dragging` is constantly false — tab
      * drag-and-drop is compositor work and is not modelled — and `fullyVisible` is
@@ -595,8 +615,14 @@ export class AdwTabView extends HTMLElement {
         if (!close) return;
 
         const barLeft = this._barEl.scrollLeft;
-        const fullyVisible =
-            tab.offsetLeft >= barLeft && tab.offsetLeft + tab.offsetWidth <= barLeft + this._barEl.clientWidth;
+        const pos = this._tabPosition(tab);
+        // `update_visible` (adw-tab-box.c:769-797). C also demands SPACING of slack on
+        // both sides; that term is deliberately NOT transplanted, because it is not
+        // slack there either: the allocation loop starts the first tab at `pos = SPACING`
+        // and puts SPACING between tabs (:3270-3286), so `pos - SPACING >= value` is
+        // exactly "flush against the leading edge". This strip has no such gaps, so the
+        // same term would report the first chip clipped and hide its close button.
+        const fullyVisible = pos >= barLeft && pos + tab.offsetWidth <= barLeft + this._barEl.clientWidth;
         close.hidden = !tabCloseVisible({
             hovering: this._hovered.has(id),
             fullyVisible,
@@ -608,6 +634,7 @@ export class AdwTabView extends HTMLElement {
 
     private _onSelectionChange(change: TabViewSelectionChange): void {
         this._applyActiveState();
+        this._scrollSelectedTabIntoBar();
         this._reflectSelected();
         this.dispatchEvent(
             new CustomEvent('notify::selected-page', {
@@ -641,6 +668,34 @@ export class AdwTabView extends HTMLElement {
         }
     }
 
+    /**
+     * `scroll_to_tab_full` (adw-tab-box.c:928-961), called on every selection the way
+     * `select_page` calls it (:1728): bring the selected chip inside the BAR's own
+     * scroll window, padded by half of whichever is smaller, the chip or the leftover.
+     *
+     * The bar is the only thing C ever scrolls for a tab: `scroll_to_tab_full` writes
+     * `self->adjustment`, the strip's own adjustment, and nothing else. The DOM has no
+     * such narrow API: `focus()` and `scrollIntoView()` both walk EVERY scrollable
+     * ancestor up to the window. So this moves `scrollLeft` by hand, and the focus call
+     * below passes `preventScroll`.
+     */
+    private _scrollSelectedTabIntoBar(): void {
+        const id = this._state.selectedId;
+        const tab = id === null ? undefined : this._tabs.get(id);
+        if (!tab) return;
+        const pageSize = this._barEl.clientWidth;
+        const width = tab.offsetWidth;
+        // Unmeasured (detached, or still inside connectedCallback): nothing to scroll to.
+        if (pageSize <= 0 || width <= 0) return;
+
+        const value = this._barEl.scrollLeft;
+        const pos = this._tabPosition(tab);
+        const padding = Math.min(width, pageSize - width) / 2;
+        if (pos - TAB_SPACING < value) this._barEl.scrollLeft = pos - padding;
+        else if (pos + width + TAB_SPACING > value + pageSize)
+            this._barEl.scrollLeft = pos + width + padding - pageSize;
+    }
+
     private _applyBarVisibility(): void {
         const revealed = tabsRevealed({
             autohide: this.autohide,
@@ -710,9 +765,17 @@ export class AdwTabView extends HTMLElement {
         event.preventDefault();
         // Roving tabindex: the newly-active tab is the only focusable one, so
         // focus has to travel with it or the next keypress goes nowhere.
+        //
+        // `preventScroll` because a bare `focus()` scrolls every scrollable ancestor
+        // up to and including the WINDOW, while C only ever moves the tab strip
+        // (`scroll_to_tab_full` writes `self->adjustment`, adw-tab-box.c:928-961).
+        // Measured in a long documentation page: one ArrowRight took the window from
+        // y=1800 to y=8367, i.e. switching a tab yanked the whole document to the widget.
+        // `_scrollSelectedTabIntoBar` (already run by the selection change) is the
+        // strip-local scroll that is supposed to happen instead.
         if (inBar) {
             const id = this._state.selectedId;
-            if (id !== null) this._tabs.get(id)?.focus();
+            if (id !== null) this._tabs.get(id)?.focus({ preventScroll: true });
         }
     }
 

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

@@ -18,6 +18,8 @@
 // queue/auto-dismiss state machine composed from @gjsify/adwaita-core.
 
 import { AdwToast, AdwToastQueue } from '@gjsify/adwaita-core';
+
+import { createAdwIcon } from './adw-icon.js';
 import type { ToastScheduler, ToastTimerHandle } from '@gjsify/adwaita-core';
 
 // The timing seam is re-exported so a consumer can type a custom scheduler for
@@ -183,11 +185,16 @@ export class AdwToastOverlay extends HTMLElement {
             el.appendChild(button);
         }
 
-        // Close affordance: a CSS-drawn "×", as in adw-tab-view's close button.
+        // Close affordance — the real `window-close` glyph, which is what upstream puts
+        // here (adw-toast-widget.ui:64) and what this port drew with two rotated CSS bars
+        // under a comment claiming no such icon shipped. It does, and the toast is the one
+        // close button in the package already sized the way upstream sizes it: a 16px
+        // symbolic in a 24px circle, so the swap is the name and nothing else.
         const close = document.createElement('button');
         close.type = 'button';
         close.className = 'adw-toast-close-button';
         close.setAttribute('aria-label', 'Close');
+        close.appendChild(createAdwIcon('window-close'));
         close.addEventListener('click', () => this._queue.dismiss());
         el.appendChild(close);
 

package/src/elements/adw-toggle-group.ts

@@ -7,7 +7,44 @@
 // The SELECTION state machine (the segment list plus the guarded, no-op-on-same active
 // index) is HEADLESS and lives in `@gjsify/adwaita-core` (ADR 0004) as
 // {@link ToggleGroupState}; this element keeps only the DOM half — the buttons, the active
-// pill / `aria-pressed` reflection and the event.
+// pill / checked reflection, the keyboard and the event.
+//
+// THE ROLE IS A RADIO GROUP, not a tab list, and the element had neither. Upstream
+// declares `GTK_ACCESSIBLE_ROLE_RADIO_GROUP` (adw-toggle-group.c:1191) and reads the
+// group's CURRENT role when it builds each toggle: a group already declared a tab list
+// gets `GTK_ACCESSIBLE_ROLE_TAB` children, everything else `GTK_ACCESSIBLE_ROLE_RADIO`
+// (:857-865, under the comment "Special case for AdwInlineViewSwitcher" — that switcher
+// builds exactly this widget with `TAB_LIST`, adw-inline-view-switcher.c:702). Both
+// branches are ported, in the same order, because a consumer that declares the tab list
+// upstream sanctions would otherwise get radios inside it.
+//
+// `aria-pressed` was the state before, and it belongs to NEITHER role — it is the
+// toolbar toggle-button pattern, where each button is independent. The state of one of
+// N mutually exclusive choices is `aria-checked` under `radio` and `aria-selected` under
+// `tab`, so a screen reader was told these were three separate on/off buttons.
+//
+// THE KEYBOARD is one tab stop and arrows inside, which is the roving tabindex
+// `elements/roving-focus.ts` implements — and `adw_toggle_group_focus`
+// (adw-toggle-group.c:1045) is the citation that module is built on. Tab in either
+// direction is PROPAGATED (:1059-1060), i.e. focus leaves the group; every other
+// direction goes to `adw_widget_focus_child` (:1062), i.e. moves within it. Which button
+// Tab enters on is `adw_toggle_group_grab_focus` (:1066): the ACTIVE toggle's button,
+// never the first. The web element had three plain tab stops and no arrow keys at all,
+// so it stayed operable — this change turns those three stops into one, which is visible
+// to anything that tabs through a toggle group.
+//
+// HORIZONTAL ONLY, and the reason is not the missing `orientation` property. The C looks
+// orientation-blind — `adw_toggle_group_focus` filters the two Tab directions and hands
+// every other one on without consulting `self->orientation` — but the axis is decided
+// one level down, GEOMETRICALLY. `adw_widget_focus_child` is `focus_move`
+// (adw-widget-utils.c:428), which sorts through `focus_sort` (:388), which dispatches
+// UP/DOWN into `focus_sort_up_down` (:298). That sorter DELETES every sibling with no
+// horizontal overlap with the focused child (:339-342) — which, in a row of toggles, is
+// all of them. The list is left holding only the focused button, `gtk_widget_child_focus`
+// on a leaf that already has focus returns FALSE, and the press PROPAGATES: upstream,
+// ArrowDown in a horizontal toggle group leaves the group. So `'horizontal'` is what the
+// C does for the only layout this element has, it matches the three sibling tab lists,
+// and it leaves ArrowUp/ArrowDown to the page instead of swallowing a scroll.
 //
 // Reference: refs/libadwaita/src/adw-toggle-group.c (AdwToggleGroup behaviour)
 // Reference: refs/libadwaita/src/stylesheet/widgets/_toggle-group.scss
@@ -20,6 +57,7 @@
 import { ToggleGroupState } from '@gjsify/adwaita-core';
 
 import { createAdwIcon } from './adw-icon.js';
+import { attachRovingFocus } from './roving-focus.js';
 
 /** A single toggle. Children of <adw-toggle-group>; consumed at connect time. */
 export class AdwToggle extends HTMLElement {
@@ -34,6 +72,8 @@ export class AdwToggleGroup extends HTMLElement {
     /** The headless segment list + guarded selection state machine (ADR 0004). */
     private readonly _state = new ToggleGroupState();
     private _initialized = false;
+    /** `aria-checked` under `radio`, `aria-selected` under `tab` — decided at connect. */
+    private _stateAttr: 'aria-checked' | 'aria-selected' = 'aria-checked';
 
     static get observedAttributes() {
         return ['active', 'flat', 'round'];
@@ -56,13 +96,48 @@ export class AdwToggleGroup extends HTMLElement {
         // subtree — their label / icon-name become the rendered buttons.
         const toggles = Array.from(this.querySelectorAll('adw-toggle')) as AdwToggle[];
 
+        // `gtk_widget_class_set_accessible_role` sets a CLASS DEFAULT that an instance's
+        // construct-time `accessible-role` overrides, and `add_toggle` then reads
+        // whatever the instance actually has. So a declared role is kept — only an
+        // undeclared one is filled in — and `tablist` is the single branch, exactly as
+        // in the C: any other role still gets radio children.
+        // `|| null`, not `?? null`: `role=""` is not a declared role, and treating it as
+        // one left the group with no role at all while its children were radios.
+        const declared = this.getAttribute('role')?.trim() || null;
+        if (declared === null) this.setAttribute('role', 'radiogroup');
+        const isTabList = declared === 'tablist';
+        const toggleRole = isTabList ? 'tab' : 'radio';
+        this._stateAttr = isTabList ? 'aria-selected' : 'aria-checked';
+        // Read ONCE, which is what upstream allows: `GtkAccessible:accessible-role` is
+        // writable but documented "The accessible role cannot be changed once set", and
+        // the only public setter is the CLASS-level `gtk_widget_class_set_accessible_role`
+        // — there is no instance setter at all. So a later `role=` change has no upstream
+        // meaning, and re-labelling the toggles on it would be behaviour this port
+        // invented. Declare it in markup, or before the element is connected.
+        //
+        // (It is NOT construct-only, which an earlier draft of this comment claimed:
+        // `Gtk-4.0.gir` marks the property `writable` with no construct flag at all. The
+        // rule is the documented one above, which is the stronger citation anyway.)
+
         this._innerEl = document.createElement('div');
         this._innerEl.className = 'adw-toggle-group-inner';
+        // The toggles are this element's own children upstream; the wrapper is a web-only
+        // flex box with no counterpart in the C at all. Without a role it is a `generic`
+        // sitting between a radio group and its radios, so it declares itself away.
+        //
+        // NO upstream precedent is claimed for this, and an earlier draft of this comment
+        // invented one: every `GTK_ACCESSIBLE_ROLE_PRESENTATION` in libadwaita is a leaf
+        // decoration (an icon, a gizmo), never a layout container between a role-bearing
+        // parent and role-bearing children — because GTK has no such container here to
+        // annotate. That is exactly why the attribute is needed on this side and nowhere
+        // in the C.
+        this._innerEl.setAttribute('role', 'none');
 
         this._buttons = toggles.map((toggle, index) => {
             const btn = document.createElement('button');
             btn.type = 'button';
             btn.className = 'adw-toggle';
+            btn.setAttribute('role', toggleRole);
 
             const label = toggle.getAttribute('label') ?? '';
             const icon = toggle.getAttribute('icon-name') ?? '';
@@ -87,6 +162,20 @@ export class AdwToggleGroup extends HTMLElement {
         this._state.subscribe(() => this._render());
         this._state.setSelected(this._readActiveAttr());
         this._render();
+
+        // No `disabled`/`hidden` filter, because no `<adw-toggle>` attribute can produce
+        // either — upstream's per-toggle `enabled` (adw-toggle-group.c:871) has no web
+        // counterpart yet, and a filter for a state this element cannot reach would be
+        // untestable. `AdwToggle.observedAttributes` is pinned in
+        // `keyboard-operable.spec.ts` so the day it grows, this decision has to be
+        // revisited instead of silently becoming a focus trap.
+        attachRovingFocus({
+            host: this,
+            orientation: 'horizontal',
+            items: () => this._buttons,
+            // Same path a click takes, so an arrow key cannot drift from a press.
+            select: (item) => this._selectIndex(this._buttons.findIndex((btn) => btn === item)),
+        });
     }
 
     attributeChangedCallback(name: string) {
@@ -124,7 +213,10 @@ export class AdwToggleGroup extends HTMLElement {
         this._buttons.forEach((btn, index) => {
             const isActive = index === active;
             btn.classList.toggle('active', isActive);
-            btn.setAttribute('aria-pressed', String(isActive));
+            btn.setAttribute(this._stateAttr, String(isActive));
+            // The roving tabindex: Tab enters on the ACTIVE toggle, the way
+            // `adw_toggle_group_grab_focus` grabs it, and leaves the group from there.
+            btn.tabIndex = isActive ? 0 : -1;
         });
     }
 }

package/src/elements/adw-toolbar-view.ts

@@ -30,6 +30,8 @@ import {
     parseToolbarStyle,
     toolbarViewClasses,
 } from '@gjsify/adwaita-core';
+import { bindEmptySections } from '../empty-sections.js';
+import { AdwScrollShading } from '../scroll-shading.js';
 
 export class AdwToolbarView extends HTMLElement {
     private _topEl!: HTMLDivElement;
@@ -37,6 +39,14 @@ export class AdwToolbarView extends HTMLElement {
     private _bottomEl!: HTMLDivElement;
     private _initialized = false;
     private _resize: ResizeObserver | null = null;
+    /**
+     * The scroll indicators for every scroller under this view.
+     *
+     * Owned HERE and not by a scroller widget, because upstream scopes them here:
+     * `toolbarview.undershoot-top scrolledwindow` shades whatever scrolls inside,
+     * however deeply nested — a split view's two panes included.
+     */
+    private _shading: AdwScrollShading | null = null;
 
     static get observedAttributes() {
         return ['top-bar-style', 'bottom-bar-style', 'extend-content-to-top-edge', 'extend-content-to-bottom-edge'];
@@ -79,14 +89,21 @@ export class AdwToolbarView extends HTMLElement {
             this._bottomEl.className = 'adw-toolbar-view-bottom';
             for (const child of bottomChildren) this._bottomEl.appendChild(child);
 
-            this._topEl.hidden = this._topEl.childElementCount === 0;
-            this._bottomEl.hidden = this._bottomEl.childElementCount === 0;
+            // A bar appended imperatively — which `topBar` invites — is a childList
+            // change, not an attribute one, so the empty/non-empty decision cannot be a
+            // one-shot read here. The ResizeObserver below then sees the bar go 0 → 48
+            // and the undershoot classes follow on their own.
+            bindEmptySections(this._topEl, this._bottomEl);
 
             this.replaceChildren(this._topEl, this._contentEl, this._bottomEl);
         }
 
         // `update_undershoots` runs from size_allocate, so the classes have to
         // follow the bars' real heights rather than a one-shot read.
+        // Before `_syncClasses`, which hands it the two undershoot flags it gates on.
+        this._shading = new AdwScrollShading(this._contentEl);
+        this._shading.connect();
+
         this._resize = new ResizeObserver(() => this._syncClasses());
         this._resize.observe(this._topEl);
         this._resize.observe(this._bottomEl);
@@ -96,6 +113,8 @@ export class AdwToolbarView extends HTMLElement {
     disconnectedCallback() {
         this._resize?.disconnect();
         this._resize = null;
+        this._shading?.disconnect();
+        this._shading = null;
     }
 
     attributeChangedCallback() {
@@ -117,6 +136,13 @@ export class AdwToolbarView extends HTMLElement {
             this._topEl.classList.toggle(cls, topBar.includes(cls));
             this._bottomEl.classList.toggle(cls, bottomBar.includes(cls));
         }
+
+        // The same two flags reach the scrollers, where the shade is actually
+        // drawn — a raised bar brings its own shadow and must not get a second one.
+        this._shading?.setUndershootEdges({
+            top: view.includes('undershoot-top'),
+            bottom: view.includes('undershoot-bottom'),
+        });
     }
 }
 

package/src/elements/adw-view-switcher-bar.ts

@@ -24,6 +24,7 @@ import { ViewSwitcherBarState, buildViewSwitcherButtons, viewSwitcherPagesFromSt
 import type { AdwViewStack } from './adw-view-stack.js';
 import { applyDescription, applyIndicator, applySwitcherIcon } from './view-switcher-dom.js';
 import { type AdwIcon, createAdwIcon } from './adw-icon.js';
+import { attachRovingFocus } from './roving-focus.js';
 
 /** The DOM nodes one bar button owns — the bar paints the derived model onto them. */
 interface BarButtonNodes {
@@ -88,6 +89,20 @@ export class AdwViewSwitcherBar extends HTMLElement {
             this._barEl.className = 'adw-view-switcher-bar-box';
             this._barEl.setAttribute('role', 'tablist');
             this.replaceChildren(this._barEl);
+            // What makes the roving tabindex below navigable: without it the unselected
+            // buttons are reachable by no key at all.
+            attachRovingFocus({
+                host: this,
+                orientation: 'horizontal',
+                items: () => this._nodes.map((nodes) => nodes.button).filter((button) => !button.hidden),
+                select: (item) => {
+                    const stack = this._stack;
+                    if (!stack) return;
+                    const index = Number(item.dataset.pageIndex);
+                    // Re-assigning the current index would re-run the stack's transition.
+                    if (stack.visibleChildIndex !== index) stack.visibleChildIndex = index;
+                },
+            });
         }
         this._barState.setReveal(this._readReveal());
 
@@ -208,6 +223,9 @@ export class AdwViewSwitcherBar extends HTMLElement {
         button.type = 'button';
         button.className = 'adw-view-switcher-bar-button';
         button.setAttribute('role', 'tab');
+        // The page index, so a keyboard move resolves an item back to a page without
+        // recomputing the mapping — the spelling `<adw-inline-view-switcher>` uses.
+        button.dataset.pageIndex = String(pageIndex);
 
         const icon = createAdwIcon(null, 'adw-view-switcher-bar-icon');
 

package/src/elements/adw-view-switcher.ts

@@ -55,6 +55,7 @@ import {
     readSwitcherPage,
 } from './view-switcher-dom.js';
 import { type AdwIcon, createAdwIcon } from './adw-icon.js';
+import { attachRovingFocus } from './roving-focus.js';
 
 /** The DOM nodes one page owns — the switcher paints the derived model onto them. */
 interface PageNodes {
@@ -171,6 +172,16 @@ export class AdwViewSwitcher extends HTMLElement {
         this._barEl = document.createElement('div');
         this._barEl.className = 'adw-view-switcher-bar';
         this._barEl.setAttribute('role', 'tablist');
+        // What makes the roving tabindex below navigable: without it the unselected
+        // buttons are reachable by no key at all.
+        attachRovingFocus({
+            host: this,
+            orientation: 'horizontal',
+            items: () => this._nodes.map((nodes) => nodes.button).filter((button) => !button.hidden),
+            select: (item) => {
+                this._state.setSelected(Number(item.dataset.pageIndex));
+            },
+        });
 
         this._contentEl = document.createElement('div');
         this._contentEl.className = 'adw-view-switcher-content';
@@ -254,6 +265,9 @@ export class AdwViewSwitcher extends HTMLElement {
         button.type = 'button';
         button.className = 'adw-view-switcher-button';
         button.setAttribute('role', 'tab');
+        // The page index, so a keyboard move resolves an item back to a page without
+        // recomputing the mapping — the spelling `<adw-inline-view-switcher>` uses.
+        button.dataset.pageIndex = String(index);
 
         // Both children always exist, as in AdwViewSwitcherButton's template — the icon
         // carries `image-missing` rather than disappearing.

package/src/elements/modal-surface.ts

@@ -0,0 +1,180 @@
+// The one focus trap behind every `aria-modal="true"` surface in this package.
+//
+// THE INCIDENT
+//
+// Four elements set `aria-modal="true"`. One of them honoured it. Measured in Firefox
+// on a page whose next tabbable element was a view-switcher button: focus the last
+// control inside `<adw-alert-dialog>`, press Tab once, and focus landed on
+// `.adw-view-switcher-bar-button` — outside the dialog, behind its own scrim, on a
+// control the user cannot see. `<adw-about-dialog>` and `<adw-preferences-dialog>` did
+// the same. Closing the dialog then left focus there: none of the three returned it to
+// whatever opened them, so a keyboard user finished the interaction somewhere they never
+// asked to be. `aria-modal` tells assistive technology the rest of the page is inert; it
+// changes NOTHING about where the browser sends Tab. Only `<adw-dialog>` implemented the
+// half that is not free, and this module is that half, lifted out of it verbatim.
+//
+// WHY IT IS A MODULE AND NOT A COPY
+//
+// `aria-modal` — the attribute and the reflected `.ariaModal` property alike — now lives
+// HERE and nowhere else, held by the `[trap]` arm of
+// `scripts/check-adwaita-keyboard-contract.mjs`. That is what makes a fifth modal surface
+// impossible to add without a trap: the declaration and the behaviour it promises are
+// the same call.
+//
+// Reference: refs/libadwaita/src/adw-dialog.c — GTK_ACCESSIBLE_ROLE_DIALOG (:1290) and
+// the dialog's own focus handling, which cannot leave the widget because GTK confines
+// focus to the presented dialog by construction. The DOM has no such confinement, so it
+// is spelled out.
+// Reference: refs/libadwaita/src/adw-alert-dialog.c:1103 — GTK_ACCESSIBLE_ROLE_ALERT_DIALOG.
+// Reference: https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/ — the Tab/Shift+Tab
+// wrap and the return-focus rule, for the part upstream leaves to the platform.
+
+/**
+ * Everything the browser will hand focus to on Tab. `[tabindex="-1"]` is excluded
+ * deliberately: it is programmatically focusable and NOT in the tab order, so treating
+ * it as a trap boundary would make Tab stop on a scrim.
+ */
+const FOCUSABLE_SELECTOR = [
+    'a[href]',
+    'button:not([disabled])',
+    'input:not([disabled])',
+    'select:not([disabled])',
+    'textarea:not([disabled])',
+    '[tabindex]:not([tabindex="-1"])',
+].join(',');
+
+/** The two roles a modal surface in this package declares. */
+export type AdwModalRole = 'dialog' | 'alertdialog';
+
+export interface AdwModalSurfaceInit {
+    /**
+     * The custom element itself. It receives the keydown listener, because a dialog that
+     * moves focus to its HOST — `<adw-preferences-dialog>` does — would otherwise press
+     * Tab against a listener on a descendant that never sees the event.
+     */
+    host: HTMLElement;
+    /** The element carrying the role, `aria-modal`, and the boundary focus may not cross. */
+    surface: HTMLElement;
+    /** The WAI-ARIA role for {@link AdwModalSurfaceInit.surface}. */
+    role: AdwModalRole;
+    /** Whether the dialog is presented right now. */
+    isOpen: () => boolean;
+    /** Escape while open. Dismissal is the element's own business (`can-close`, close-response). */
+    onEscape: () => void;
+    /**
+     * Where focus goes on present, when the element wants something other than the first
+     * focusable control — `<adw-alert-dialog>` starts on its DEFAULT response, not on the
+     * leftmost button. It is handed {@link AdwModalSurface.focusables}, so a rule like
+     * "the first control in the content area" is a `find` over that list rather than a
+     * second copy of the filter.
+     *
+     * Returning nothing — or an element that is not in that list — falls back to the
+     * first focusable, then to the surface itself.
+     */
+    initialFocus?: (focusables: readonly HTMLElement[]) => HTMLElement | null | undefined;
+}
+
+/**
+ * A modal surface: it declares `aria-modal`, keeps Tab inside itself, and gives focus
+ * back to whatever had it when the dialog appeared.
+ *
+ * The element drives it with two calls — {@link present} when it opens and
+ * {@link dismiss} when it closes — and keeps its own dismissal rules.
+ */
+export class AdwModalSurface {
+    private readonly _init: AdwModalSurfaceInit;
+    /** Focused before `present()`, restored by `dismiss()`. */
+    private _previouslyFocused: HTMLElement | null = null;
+
+    constructor(init: AdwModalSurfaceInit) {
+        this._init = init;
+        init.surface.setAttribute('role', init.role);
+        init.surface.setAttribute('aria-modal', 'true');
+        // The surface is the fallback focus target, so it has to be able to hold focus
+        // even when it contains no control at all. Not in the tab order: -1.
+        if (!init.surface.hasAttribute('tabindex')) init.surface.tabIndex = -1;
+        init.host.addEventListener('keydown', (event) => this._onKeyDown(event));
+    }
+
+    /** The controls inside the surface, in tab order, that a `focus()` can actually reach. */
+    focusables(): HTMLElement[] {
+        return Array.from(this._init.surface.querySelectorAll<HTMLElement>(FOCUSABLE_SELECTOR)).filter(
+            // `getClientRects()` and not `hidden`: `<adw-about-dialog>` keeps every
+            // navigation page in the DOM and shows one, so the non-visible pages'
+            // buttons match the selector, are not `[hidden]`, and cannot take focus.
+            // Tabbing onto one silently leaves focus where it was — a trap that lets go.
+            (el) => !el.hasAttribute('disabled') && !el.hidden && el.getClientRects().length > 0,
+        );
+    }
+
+    /**
+     * Remember where focus was, then move it inside.
+     *
+     * SYNCHRONOUS, and that was measured rather than assumed. `<adw-about-dialog>` used to
+     * defer this by a `requestAnimationFrame`, which reads as "the sheet is not laid out
+     * yet" — it is not. Every element here toggles its `open` class before calling this,
+     * so the surface is already displayed; reading `document.activeElement` in the same
+     * task that sets `open` finds it inside the dialog for all four. A retry frame would
+     * be a branch nothing can reach, and a spec asserting focus one frame late would pass
+     * over a dialog that never focused anything at all.
+     */
+    present(): void {
+        const active = document.activeElement;
+        this._previouslyFocused = active instanceof HTMLElement && active !== this._init.host ? active : null;
+        const focusables = this.focusables();
+        // A `??` chain falls through when the element asks for NOTHING, never when it asks
+        // for something the browser refuses — so a request is honoured only if it is in the
+        // list, the same test the trap uses for its edges. Measured in Firefox before this
+        // filter: an `<adw-alert-dialog>` whose default response was DISABLED handed that
+        // button back, `focus()` on it was a no-op, and the dialog opened with
+        // `document.activeElement` still on the opener OUTSIDE it. The keydown listener
+        // sits on the host, so focus never entered, no key ever reached the trap, and a
+        // real Escape left `open` true — unreachable and undismissable at once.
+        const wanted = this._init.initialFocus?.(focusables);
+        const target =
+            (wanted && focusables.includes(wanted) ? wanted : undefined) ?? focusables[0] ?? this._init.surface;
+        target.focus();
+    }
+
+    /** Give focus back to whatever had it before `present()`. */
+    dismiss(): void {
+        const restore = this._previouslyFocused;
+        this._previouslyFocused = null;
+        if (restore && restore.isConnected) restore.focus();
+    }
+
+    private _onKeyDown(event: KeyboardEvent): void {
+        if (!this._init.isOpen()) return;
+        if (event.key === 'Escape') {
+            event.stopPropagation();
+            this._init.onEscape();
+            return;
+        }
+        if (event.key !== 'Tab') return;
+
+        // The INNERMOST open surface owns Tab: a dialog presented from inside another one
+        // bubbles its keydown to the outer host, which would re-run this wrap against its
+        // own edges and undo the move that just happened.
+        event.stopPropagation();
+
+        const focusables = this.focusables();
+        if (focusables.length === 0) {
+            // Nothing tabbable inside — Tab would leave immediately, so it goes nowhere.
+            event.preventDefault();
+            this._init.surface.focus();
+            return;
+        }
+        const first = focusables[0];
+        const last = focusables[focusables.length - 1];
+        const active = document.activeElement;
+        // The wrap is asserted at the EDGES only: in between, the browser's own tab order
+        // is already correct and intercepting it would break Shift+Tab through a form.
+        if (event.shiftKey && (active === first || active === this._init.surface || active === this._init.host)) {
+            event.preventDefault();
+            last.focus();
+        } else if (!event.shiftKey && (active === last || active === this._init.host)) {
+            event.preventDefault();
+            first.focus();
+        }
+    }
+}