@gjsify/adwaita-web 0.41.0 → 0.42.0

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

@@ -1,7 +1,7 @@
-// <adw-menu-button> — the web counterpart of Adw.MenuButton / Gtk.MenuButton: by
-// default the flat `open-menu-symbolic` app-menu button used at the end of a header
-// bar. Clicking it toggles an Adwaita-styled popover under the button, dismissed on
-// an outside click or Escape, with arrow-key navigation.
+// <adw-menu-button> — the web counterpart of Gtk.MenuButton, which libadwaita styles
+// but never subclassed: by default the flat `open-menu-symbolic` app-menu button used
+// at the end of a header bar. Clicking it toggles an Adwaita-styled popover under the
+// button, dismissed on an outside click or Escape, with arrow-key navigation.
 //
 // The popover is `<adw-popover>` and the dismissal/keyboard machine is
 // `@gjsify/adwaita-core`'s (ADR 0004); this element keeps only what is a menu button:
@@ -14,13 +14,19 @@
 // detail `{ id, label, index }`) with `id` falling back to `label`, matching the NS
 // twin.
 //
-// Reference: refs/libadwaita/src/adw-menu-button.c (AdwMenuButton)
+// Reference: refs/gtk/gtk/gtkmenubutton.c (GtkMenuButton)
+// Reference: refs/libadwaita/src/stylesheet/widgets/_buttons.scss (menubutton)
 // Reference: refs/libadwaita/src/stylesheet/widgets/_menus.scss (popover.menu / modelbutton)
 // Reference: packages/nativescript-bridge/adwaita/src/widgets/adw-menu-button.ts (NS twin)
 // Copyright (c) GNOME contributors (libadwaita). LGPLv2.1+.
 // Modifications: Implemented as a Web Component for @gjsify/adwaita-web.
 
-import { isSplitButtonDirection, menuButtonPopupDirection, parseMenuEntries } from '@gjsify/adwaita-core';
+import {
+    isSplitButtonDirection,
+    menuButtonPopupDirection,
+    parseMenuEntries,
+    stringIsNotEmpty,
+} from '@gjsify/adwaita-core';
 import type { AdwMenuEntry, SplitButtonDirection } from '@gjsify/adwaita-core';
 
 // SIDE-EFFECT import, deliberately separate from the type import below: it guarantees
@@ -210,11 +216,12 @@ export class AdwMenuButton extends HTMLElement {
             item.setAttribute('role', 'menuitem');
             item.tabIndex = -1;
 
-            // An entry with no USABLE icon gets no icon node at all rather than an empty
-            // 16px box; `<adw-icon>` itself answers whether the name resolved, so the
-            // `-symbolic`-only and bad-token cases agree.
+            // An entry that asked for NO icon gets no icon node — the emptiness of the
+            // declared name, not whether it resolved. Testing `resolvedIconName` dropped
+            // the node for a name that was given and merely undrawable, which is the one
+            // case a reader needs to SEE; `<adw-icon>` draws `image-missing` there.
             const entryIcon = createAdwIcon(entry.icon ?? null, 'adw-menu-button-item-icon');
-            if (entryIcon.resolvedIconName !== '') item.appendChild(entryIcon);
+            if (stringIsNotEmpty(entry.icon)) item.appendChild(entryIcon);
             const labelEl = document.createElement('span');
             labelEl.className = 'adw-menu-button-item-label';
             labelEl.textContent = entry.label;

package/src/elements/adw-navigation-split-view.ts

@@ -50,6 +50,12 @@ export class AdwNavigationSplitView extends HTMLElement {
     private _contentEl!: HTMLDivElement;
     private _initialized = false;
     private _disposeBreakpoint: (() => void) | undefined;
+    /**
+     * What the breakpoint last SET, carried across every rebind. Not read off the
+     * attribute: a `collapsed` the markup declared was never this breakpoint's doing,
+     * and unapplying it at connect would undo the author.
+     */
+    private _breakpointApplied = false;
     /** The ordering table, the tag guard and the action routing (ADR 0004). */
     private _state = new NavigationSplitViewState();
     /** Re-entrancy guard for the `show-content` reflection. */
@@ -118,6 +124,21 @@ export class AdwNavigationSplitView extends HTMLElement {
     }
 
     connectedCallback() {
+        this._buildOnce();
+        // `_syncBreakpoint` is the one that HAS to run on EVERY connect: it re-establishes
+        // the ResizeObserver `disconnectedCallback` disposed, and without it a view MOVED
+        // between parents (a slideshow slide, a client-side route change) stops tracking
+        // its condition for good — `<adw-navigation-split-view breakpoint="max-width: 720px">`
+        // never collapses again however narrow the page gets. The three above it are the
+        // post-build derivations, idempotent on a later connect and left in the order
+        // `<adw-overlay-split-view>` runs them so the two views read alike.
+        this._reflectShowContent();
+        this._syncWidth();
+        this._syncClasses();
+        this._syncBreakpoint();
+    }
+
+    private _buildOnce() {
         if (this._initialized) return;
         this._initialized = true;
 
@@ -160,10 +181,6 @@ export class AdwNavigationSplitView extends HTMLElement {
             this._reflectShowContent();
             this._syncClasses();
         });
-
-        this._syncWidth();
-        this._syncClasses();
-        this._syncBreakpoint();
     }
 
     /** `Adw.NavigationPage:tag` off the slotted pane, or `null` when untagged. */
@@ -284,9 +301,15 @@ export class AdwNavigationSplitView extends HTMLElement {
 
     private _syncBreakpoint() {
         this._disposeBreakpoint?.();
-        this._disposeBreakpoint = bindBreakpointSetter(this, this.getAttribute('breakpoint'), (active) => {
-            this.collapsed = active;
-        });
+        this._disposeBreakpoint = bindBreakpointSetter(
+            this,
+            this.getAttribute('breakpoint'),
+            (active) => {
+                this._breakpointApplied = active;
+                this.collapsed = active;
+            },
+            this._breakpointApplied,
+        );
     }
 }
 

package/src/elements/adw-overlay-split-view.ts

@@ -84,6 +84,12 @@ export class AdwOverlaySplitView extends HTMLElement {
     private _contentEl!: HTMLDivElement;
     private _backdropEl!: HTMLDivElement;
     private _disposeBreakpoint: (() => void) | undefined;
+    /**
+     * What the breakpoint last SET, carried across every rebind. Not read off the
+     * attribute: a `collapsed` the markup declared was never this breakpoint's doing,
+     * and unapplying it at connect would undo the author.
+     */
+    private _breakpointApplied = false;
     /**
      * The property interplay, shared with the NativeScript renderer (ADR 0004): the
      * element owns the attributes and the painting, core owns what `collapsed` +
@@ -335,9 +341,15 @@ export class AdwOverlaySplitView extends HTMLElement {
 
     private _syncBreakpoint() {
         this._disposeBreakpoint?.();
-        this._disposeBreakpoint = bindBreakpointSetter(this, this.getAttribute('breakpoint'), (active) => {
-            this.collapsed = active;
-        });
+        this._disposeBreakpoint = bindBreakpointSetter(
+            this,
+            this.getAttribute('breakpoint'),
+            (active) => {
+                this._breakpointApplied = active;
+                this.collapsed = active;
+            },
+            this._breakpointApplied,
+        );
     }
 
     openSidebar() {

package/src/elements/adw-popover.ts

@@ -160,6 +160,17 @@ export class AdwPopover extends HTMLElement {
     }
 
     connectedCallback() {
+        this._buildOnce();
+        // EVERY connect, not only the first. The document listeners are bound from
+        // `_onStateChange` and released by `disconnectedCallback`, so a popover that was
+        // OPEN when it moved — a slideshow slide, a client-side route change — comes back
+        // visible with neither outside-click nor Escape dismissal, and no state change
+        // left to re-arm them: the only ways out are the two that just died. Idempotent
+        // by construction, the same function references and capture flag the unbind uses.
+        if (this._state.open) this._bindDocument();
+    }
+
+    private _buildOnce() {
         if (this._initialized) return;
         this._initialized = true;
 

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

@@ -50,6 +50,7 @@
 
 import type { PreferencesSearchResult, SearchPreferencesOptions } from '@gjsify/adwaita-core';
 import { searchPreferencesDom } from '../preferences-search.js';
+import { AdwModalSurface } from './modal-surface.js';
 
 const DEFAULT_CONTENT_WIDTH = 640;
 
@@ -106,6 +107,7 @@ export class AdwPreferencesDialog extends HTMLElement {
     private _bodyEl!: HTMLDivElement;
     private _pagesEl!: HTMLDivElement;
     private _closeBtn!: HTMLButtonElement;
+    private _modal!: AdwModalSurface;
 
     static get observedAttributes() {
         return ['title', 'open', 'can-close', 'content-width'];
@@ -218,8 +220,6 @@ export class AdwPreferencesDialog extends HTMLElement {
 
         this._dialogEl = document.createElement('div');
         this._dialogEl.className = 'adw-preferences-dialog-box';
-        this._dialogEl.setAttribute('role', 'dialog');
-        this._dialogEl.setAttribute('aria-modal', 'true');
         // Clicks inside the dialog must not bubble to the scrim's dismiss handler.
         this._dialogEl.addEventListener('click', (event) => event.stopPropagation());
 
@@ -241,8 +241,8 @@ export class AdwPreferencesDialog extends HTMLElement {
         this._closeBtn.type = 'button';
         this._closeBtn.className = 'adw-preferences-dialog-close';
         this._closeBtn.setAttribute('aria-label', 'Close');
-        // The "×" is a CSS glyph: `window-close` has no mask class, because it is not in
-        // the ICONS map in `scripts/build-scss.mjs` that generates them.
+        // The "×" is a CSS glyph, for the sizing reason adw-tab-view's close affordance
+        // records — not for want of a mask class, which `window-close` has.
         this._closeBtn.addEventListener('click', () => this._attemptClose());
         trailing.appendChild(this._closeBtn);
 
@@ -260,14 +260,14 @@ export class AdwPreferencesDialog extends HTMLElement {
 
         this.replaceChildren(this._scrimEl, this._dialogEl);
 
-        // Escape closes the dialog while open (Adw.Dialog's Escape shortcut →
-        // `maybe_close_cb`). The element is focusable so it can receive the key event.
-        if (!this.hasAttribute('tabindex')) this.tabIndex = -1;
-        this.addEventListener('keydown', (event) => {
-            if (event.key === 'Escape' && this.open) {
-                event.stopPropagation();
-                this._attemptClose();
-            }
+        // The role, `aria-modal`, Escape (Adw.Dialog's shortcut → `maybe_close_cb`), the
+        // Tab trap and the return-focus.
+        this._modal = new AdwModalSurface({
+            host: this,
+            surface: this._dialogEl,
+            role: 'dialog',
+            isOpen: () => this.open,
+            onEscape: () => this._attemptClose(),
         });
 
         this._render();
@@ -279,7 +279,12 @@ export class AdwPreferencesDialog extends HTMLElement {
         this._render();
         if (name === 'open') {
             this.dispatchEvent(new CustomEvent('notify::open', { bubbles: true, detail: { open: this.open } }));
-            if (!this.open) this.dispatchEvent(new CustomEvent('closed', { bubbles: true }));
+            if (this.open) {
+                this._modal.present();
+            } else {
+                this.dispatchEvent(new CustomEvent('closed', { bubbles: true }));
+                this._modal.dismiss();
+            }
         }
     }
 
@@ -304,9 +309,6 @@ export class AdwPreferencesDialog extends HTMLElement {
         const locked = !this.canClose;
         this._closeBtn.disabled = locked;
         this._closeBtn.classList.toggle('locked', locked);
-
-        // Move focus into the dialog on present so Escape works immediately.
-        if (this.open) this.focus();
     }
 }
 

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

@@ -115,6 +115,10 @@ export class AdwPreferencesGroup extends HTMLElement {
         for (const child of rowChildren) this._listboxEl.appendChild(child);
 
         this.replaceChildren(this._headerEl, this._listboxEl);
+        // adw-preferences-group.c:319 — GTK_ACCESSIBLE_ROLE_GROUP. A GROUP, not a list:
+        // that is why the rows inside carry no `listitem` role, which outside a list
+        // would be worse than none.
+        this.setAttribute('role', 'group');
 
         this._renderHeader();
         this._observeHost();
@@ -158,6 +162,9 @@ export class AdwPreferencesGroup extends HTMLElement {
         });
         this._observer.observe(this, { childList: true });
         this._observer.observe(this._listboxEl, { childList: true });
+        // The suffix too: `hasHeaderSuffix` is an INPUT to the header derivation, so a
+        // suffix appended after connect left the header hidden on a group with no title.
+        this._observer.observe(this._suffixEl, { childList: true });
     }
 
     private _renderHeader() {

package/src/elements/adw-sidebar.ts

@@ -57,6 +57,7 @@ import {
 } from '@gjsify/adwaita-core';
 
 import { createAdwIcon } from './adw-icon.js';
+import { attachRovingFocus } from './roving-focus.js';
 
 // The sidebar consumes its declared children and drops them from the tree, so a later
 // `setAttribute` on one cannot find its sidebar with `closest()`. These keep the link —
@@ -161,6 +162,20 @@ export class AdwSidebar extends HTMLElement {
         this._listEl = document.createElement('div');
         this._listEl.className = 'adw-sidebar-list';
         this._listEl.setAttribute('role', 'listbox');
+        // What makes the roving tabindex in `_applySelection` navigable: without it the
+        // unselected rows are reachable by no key at all. `setSelected` and NOT
+        // `_activate`: an arrow key is `GtkListBox`'s `row-selected`, and firing
+        // `activated` on every press would navigate a split view on each keystroke.
+        // Enter and Space still activate — the row IS a <button>.
+        attachRovingFocus({
+            host: this,
+            orientation: 'vertical',
+            items: () => this._rows.filter((row) => !row.el.hidden && !row.el.disabled).map((row) => row.el),
+            select: (item) => {
+                const row = this._rows.find((candidate) => candidate.el === item);
+                if (row !== undefined) this._state.setSelected(row.index);
+            },
+        });
 
         // Seed the model BEFORE subscribing: connecting is not a change anyone
         // asked to hear about, and `setSections` runs the 0 → n auto-select.

package/src/elements/adw-status-page.ts

@@ -2,13 +2,14 @@
 // icon, a title, a description and an optional action (slotted child).
 // Attributes: icon (symbolic name, with or without -symbolic), title, description.
 // Reference: refs/adwaita-web/adwaita-web/scss/_status_page.scss
-// Reference: refs/libadwaita/src/stylesheet/widgets/_status-page.scss
+// Reference: refs/libadwaita/src/stylesheet/widgets/_misc.scss (AdwStatusPage)
 // Copyright (c) GNOME contributors (libadwaita). LGPLv2.1+.
 // Modifications: Implemented as a Web Component for @gjsify/adwaita-web; the
 // icon node is <adw-icon>.
 
 import { stringIsNotEmpty } from '@gjsify/adwaita-core';
 
+import { bindEmptySections } from '../empty-sections.js';
 import { type AdwIcon, createAdwIcon } from './adw-icon.js';
 
 export class AdwStatusPage extends HTMLElement {
@@ -41,6 +42,9 @@ export class AdwStatusPage extends HTMLElement {
         for (const child of children) this._childEl.appendChild(child);
 
         this.replaceChildren(this._iconEl, this._titleEl, this._descEl, this._childEl);
+        // `_render` only ever runs from `attributeChangedCallback`, which an action
+        // appended into the child slot after connect does not trigger.
+        bindEmptySections(this._childEl);
         this._render();
     }
 
@@ -51,7 +55,13 @@ export class AdwStatusPage extends HTMLElement {
     private _render() {
         // The element swaps the mask class and keeps the size class.
         this._iconEl.iconName = this.getAttribute('icon');
-        this._iconEl.hidden = this._iconEl.resolvedIconName === '';
+        // `has_image`: `paintable || (icon_name && icon_name[0])` — a name that was GIVEN
+        // shows the image whether or not the theme can resolve it, and GTK draws
+        // `image-missing` in it. Reading `resolvedIconName` instead hid the slot for every
+        // name that is not one CSS token, a branch the C does not have.
+        // Reference: refs/libadwaita/src/adw-status-page.c:88 (has_image), bound from
+        //   `<binding name="visible">` in adw-status-page.ui:27-31.
+        this._iconEl.hidden = !stringIsNotEmpty(this.getAttribute('icon'));
 
         // `string_is_not_empty` from the core, not a local `.length === 0`: the same
         // closure the NativeScript port binds its labels to, and the reason a title of
@@ -63,8 +73,6 @@ export class AdwStatusPage extends HTMLElement {
         const description = this.getAttribute('description') ?? '';
         this._descEl.textContent = description;
         this._descEl.hidden = !stringIsNotEmpty(description);
-
-        this._childEl.hidden = this._childEl.childElementCount === 0;
     }
 }
 

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

@@ -25,6 +25,7 @@ import { SwitchRowState, deriveRowLabels } from '@gjsify/adwaita-core';
 // without `verbatimModuleSyntax`, so TypeScript would elide the statement and take the
 // registration with it.
 import './adw-switch.js';
+import { attachRowActivation } from './row-activation.js';
 import type { AdwSwitch } from './adw-switch.js';
 
 export class AdwSwitchRow extends HTMLElement {
@@ -62,6 +63,8 @@ export class AdwSwitchRow extends HTMLElement {
         text.append(this._titleEl, this._subtitleEl);
 
         this._switchEl = document.createElement('adw-switch') as AdwSwitch;
+        // adw-switch-row.c:159 — the slider is not a focus target; the ROW is.
+        this._switchEl.unfocusable = true;
 
         this.replaceChildren(text, this._switchEl);
 
@@ -86,6 +89,10 @@ export class AdwSwitchRow extends HTMLElement {
             this._apply(this._state.activate());
         });
 
+        // adw-switch-row.c:160 makes the row itself activatable. Enter and Space run the
+        // same transition a click does, through the row's own click handler.
+        attachRowActivation({ row: this, activatable: () => true });
+
         this._renderText();
     }
 

package/src/elements/adw-switch.ts

@@ -35,7 +35,23 @@ export class AdwSwitch extends HTMLElement {
     private _initialized = false;
 
     static get observedAttributes() {
-        return ['active', 'disabled'];
+        return ['active', 'disabled', 'unfocusable'];
+    }
+
+    /**
+     * `Gtk.Widget:can-focus` on the slider, inverted so the default stays "yes".
+     *
+     * `adw_switch_row_init` does `gtk_widget_set_can_focus (self->slider, FALSE)`
+     * (adw-switch-row.c:159) and makes the ROW activatable instead, so a switch row is ONE
+     * tab stop announced as its own title — not a bare checkbox followed by a label that
+     * cannot be reached. A standalone `<adw-switch>` keeps its checkbox focusable.
+     */
+    get unfocusable(): boolean {
+        return this.hasAttribute('unfocusable');
+    }
+
+    set unfocusable(value: boolean) {
+        this.toggleAttribute('unfocusable', !!value);
     }
 
     /** Whether the switch is on. */
@@ -103,6 +119,8 @@ export class AdwSwitch extends HTMLElement {
         const disabled = this.disabled;
         this._input.checked = this.active;
         this._input.disabled = disabled;
+        if (this.unfocusable) this._input.tabIndex = -1;
+        else this._input.removeAttribute('tabindex');
         this.classList.toggle('disabled', disabled);
     }
 }

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

@@ -500,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';

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,7 @@ import {
     parseToolbarStyle,
     toolbarViewClasses,
 } from '@gjsify/adwaita-core';
+import { bindEmptySections } from '../empty-sections.js';
 import { AdwScrollShading } from '../scroll-shading.js';
 
 export class AdwToolbarView extends HTMLElement {
@@ -88,8 +89,11 @@ 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);
         }