@gjsify/adwaita-web 0.55.0 → 0.56.0

package/src/elements/gtk-scrolled-window.ts

@@ -91,7 +91,7 @@ import type { AdwAdjustment } from '@gjsify/adwaita-core';
 import { AdwScrollShading } from '../scroll-shading.js';
 import { bindSlottedChildren } from '../slotted-children.js';
 import type { GtkScrollType } from './gtk-scrollbar.js';
-import { GtkViewport } from './gtk-viewport.js';
+import type { GtkViewport } from './gtk-viewport.js';
 
 /**
  * `INDICATOR_FADE_OUT_DELAY` — how long an indicator waits, after the last scroll, before
@@ -198,6 +198,8 @@ function resolveScrollKey(event: KeyboardEvent): { scroll: GtkScrollType; horizo
 export class GtkScrolledWindow extends HTMLElement {
     private _viewport!: GtkViewport;
     private _bars: Record<'horizontal' | 'vertical', HTMLElement> | null = null;
+    /** The size clamps `_writeSize` last wrote, which are the only ones it may clear. */
+    private readonly _wroteSizes = new Set<string>();
     private _shading: AdwScrollShading | null = null;
     private _observer: ResizeObserver | null = null;
     private _hoverable: MediaQueryList | null = null;
@@ -447,10 +449,10 @@ export class GtkScrolledWindow extends HTMLElement {
         this.classList.toggle('overlay-scrolling', indicators);
         // `gtk_scrolled_window_measure`'s four clamps, as the four CSS size requests they
         // are: an unwritten one (-1) sets nothing at all.
-        this.style.minWidth = this._size('min-content-width');
-        this.style.minHeight = this._size('min-content-height');
-        this.style.maxWidth = this._size('max-content-width');
-        this.style.maxHeight = this._size('max-content-height');
+        this._writeSize('min-width', 'min-content-width');
+        this._writeSize('min-height', 'min-content-height');
+        this._writeSize('max-width', 'max-content-width');
+        this._writeSize('max-height', 'max-content-height');
         for (const axis of AXES) {
             const bar = bars[axis.bar];
             const policy = normalizePolicy(this.getAttribute(axis.policy));
@@ -481,9 +483,18 @@ export class GtkScrolledWindow extends HTMLElement {
         if (!indicators) this._clearFade();
     }
 
-    private _size(attribute: string): string {
+    /**
+     * One of the four clamps as inline style. An unwritten clamp clears only what THIS element
+     * wrote: `min-width` / `min-height` are also where a tree's `width-request` /
+     * `height-request` land (`GTK_WIDGET_SIZE_CSS`), and assigning '' unconditionally erased it.
+     * Where both are set the content clamp wins, which is the one the widget measures itself.
+     */
+    private _writeSize(property: string, attribute: string): void {
         const size = sizeRequest(this.getAttribute(attribute));
-        return size === null ? '' : `${size}px`;
+        if (size !== null) this.style.setProperty(property, `${size}px`);
+        else if (this._wroteSizes.has(property)) this.style.removeProperty(property);
+        if (size !== null) this._wroteSizes.add(property);
+        else this._wroteSizes.delete(property);
     }
 
     /** The viewport's adjustment for one axis, which is where GTK reads the scrollbar's. */

package/src/elements/gtk-window.ts

@@ -106,9 +106,15 @@ export class GtkWindow extends HTMLElement {
         ];
     }
 
-    /** `Gtk.Window:title` — the window's title. */
-    get title(): string | null {
-        return this.getAttribute('title');
+    /**
+     * `Gtk.Window:title` — the window's title.
+     *
+     * The getter answers `''` for no title, not `null`: a `string | null` getter is not assignable to
+     * `HTMLElement.title`, and the emitted `.d.ts` then fails every consumer that does not set
+     * `skipLibCheck`. The setter still takes `null` to clear it, as GTK does.
+     */
+    get title(): string {
+        return this.getAttribute('title') ?? '';
     }
 
     set title(value: string | null) {

package/src/gtk-window.spec.ts

@@ -37,6 +37,18 @@ export const GtkWindowTest = async () => {
             host.remove();
         });
 
+        await it('answers an unset title as a string and clears it with null', async () => {
+            // `HTMLElement.title` is a `string`; a `string | null` getter broke every consumer's
+            // type check of the emitted `.d.ts`.
+            const { el, host } = mount();
+            expect(el.title).toBe('');
+            el.title = 'Learn6502';
+            expect(el.title).toBe('Learn6502');
+            el.title = null;
+            expect(el.title).toBe('');
+            host.remove();
+        });
+
         await it('routes every unslotted child into the content box, in document order', async () => {
             const { el, host } = mount();
             const first = document.createElement('span');

package/src/index.ts

@@ -81,7 +81,7 @@ export type { AdwUndershootEdges } from './scroll-shading.js';
 // spec itself — has a route to it that is not a `.spec.ts` import; see that file's header
 // for why `mountSharedTree` and not `buildSharedTree` alone is the instantiation half.
 export { buildSharedTree, mountSharedTree } from './shared-tree-builder.js';
-export type { MountedSharedTree, SizeSource } from './shared-tree-builder.js';
+export type { MountOptions, MountedSharedTree, SizeSource } from './shared-tree-builder.js';
 export { registerTemplateClass } from './template-classes.js';
 
 // The stylesheet compiles a chosen SUBSET of `@gjsify/adwaita-icons` (the whole set is

package/src/keyboard-operable.spec.ts

@@ -622,21 +622,57 @@ export const AdwKeyboardOperableTest = async () => {
             // Prose cannot hold that: this line fails the commit that adds it.
             // `<adw-inline-view-switcher>` has the same gap (status/open-todos/README.md).
             // `active-name` joined the list without touching the axis: it picks a toggle.
-            expect([...AdwToggleGroup.observedAttributes]).toStrictEqual(['active', 'active-name', 'flat', 'round']);
+            // `sensitive` joined it for the same reason — it gates every button's `disabled`,
+            // never the axis. `keyboard-operable.spec.ts` below now pins the roving walk
+            // against a disabled toggle, which is what made that attribute safe to add.
+            expect([...AdwToggleGroup.observedAttributes]).toStrictEqual([
+                'active',
+                'active-name',
+                'flat',
+                'round',
+                'sensitive',
+            ]);
         });
 
         await it('adw-toggle has no state a roving walk would have to skip', async () => {
-            // `<adw-toggle-group>` passes its buttons to `attachRovingFocus` UNFILTERED,
-            // which is only safe while no `<adw-toggle>` attribute can produce a disabled
-            // or hidden button. That is a decision recorded in two comments and a ledger
-            // entry, and this is the line that fails when it stops being true — the first
-            // disabled toggle is otherwise a `focus()` the browser refuses, with nothing
-            // in the walk to step over it. Grow this list and add the filter and its spec
-            // in the same change (status/open-todos/README.md, `<adw-toggle>` has no `enabled`).
+            // `<adw-toggle-group>` FILTERS its buttons for `attachRovingFocus`, which is only
+            // necessary once some `<adw-toggle>` attribute can produce a disabled button.
+            // `enabled` is that attribute (`AdwToggle:enabled`), so this list is now the
+            // record of WHICH attributes can — `hidden` cannot, and no other one can.
+            // Grow it and the filter has to grow with it: an unskipped disabled toggle is a
+            // `focus()` the browser refuses, with nothing in the walk to step over it. The
+            // skip itself is pinned in the case below.
             //
-            // `tooltip` joined the list and is NOT a counterexample: it sets `title` and
-            // `aria-label`, which change neither reachability nor rendering.
-            expect([...AdwToggle.observedAttributes]).toStrictEqual(['label', 'icon-name', 'tooltip']);
+            // `tooltip` is not a counterexample: it sets `title` and `aria-label`, which
+            // change neither reachability nor rendering.
+            expect([...AdwToggle.observedAttributes]).toStrictEqual(['label', 'icon-name', 'tooltip', 'enabled']);
+        });
+
+        await it('adw-toggle-group arrow skips a disabled toggle', async () => {
+            // `AdwToggle:enabled` reached the web element with #1818, and the filter
+            // `roving-focus.ts` asks of every caller is the price of it — the same obligation
+            // `<adw-sidebar>` already pays ("arrow skips a disabled row", above). A disabled
+            // `<button>` cannot take focus, so leaving it in the walk strands the user on a
+            // `focus()` the browser refuses.
+            withWidget(
+                () => {
+                    const el = document.createElement('adw-toggle-group');
+                    el.innerHTML =
+                        '<adw-toggle label="One"></adw-toggle>' +
+                        '<adw-toggle label="Two" enabled="false"></adw-toggle>' +
+                        '<adw-toggle label="Three"></adw-toggle>';
+                    return el;
+                },
+                (el) => {
+                    const items = rovingCase('adw-toggle-group').items(el);
+                    expect(items.length).toBe(3);
+                    expect((items[1] as HTMLButtonElement).disabled).toBe(true);
+
+                    items[0].focus();
+                    press(items[0], 'ArrowRight');
+                    expect(document.activeElement).toBe(items[2]);
+                },
+            );
         });
 
         await it('adw-toggle-group notifies once per arrow, through the click path', async () => {

package/src/row-line-clamp.ts

@@ -0,0 +1,74 @@
+// Row line-clamping utilities — shared by adw-action-row, adw-switch-row,
+// adw-combo-row, adw-spin-row, adw-expander-row.
+//
+// The clamping uses the package's established pattern: CSS custom properties
+// (--adw-row-title-lines, --adw-row-subtitle-lines) + a class toggle
+// (.adw-row-clamp on the text container). See gtk-label.ts for the same
+// pattern with --gtk-label-lines and .adw-label-clamp.
+//
+// Upstream semantics (AdwActionRow, AdwExpanderRow):
+//   - title-lines / subtitle-lines default to 0
+//   - 0 = unlimited lines (wrap freely, no ellipsis)
+//   - n > 0 = clamp to n lines with ellipsis
+//   - Negative values are invalid per the pspec (range 0..G_MAXINT) and
+//     treated as 0 (unlimited) — the property system clamps them.
+
+export interface RowLineClampConfig {
+    titleEl: HTMLElement;
+    subtitleEl: HTMLElement;
+    textContainerEl: HTMLElement; // The element that gets .adw-row-clamp
+    getTitleLines: () => number;
+    getSubtitleLines: () => number;
+}
+
+/**
+ * Apply or remove line clamping based on title-lines/subtitle-lines values.
+ * Uses CSS custom properties and class toggle (not inline styles).
+ */
+export function applyRowLineClamp(config: RowLineClampConfig): void {
+    const { titleEl, subtitleEl, textContainerEl, getTitleLines, getSubtitleLines } = config;
+
+    const titleLines = getTitleLines();
+    const subtitleLines = getSubtitleLines();
+
+    const titleClamped = titleLines > 0;
+    const subtitleClamped = subtitleLines > 0;
+    const anyClamped = titleClamped || subtitleClamped;
+
+    // Toggle the clamping class on the text container
+    textContainerEl.classList.toggle('adw-row-clamp', anyClamped);
+
+    // Set custom properties for the clamp line counts
+    if (titleClamped) {
+        titleEl.style.setProperty('--adw-row-title-lines', String(titleLines));
+    } else {
+        titleEl.style.removeProperty('--adw-row-title-lines');
+    }
+
+    if (subtitleClamped) {
+        subtitleEl.style.setProperty('--adw-row-subtitle-lines', String(subtitleLines));
+    } else {
+        subtitleEl.style.removeProperty('--adw-row-subtitle-lines');
+    }
+
+    // The ellipsize overflow is shared (end ellipsis for all non-none modes)
+    // Set it on the text container so the clamp rule can read it
+    if (anyClamped) {
+        textContainerEl.style.setProperty('--adw-row-ellipsize-overflow', 'ellipsis');
+    } else {
+        textContainerEl.style.removeProperty('--adw-row-ellipsize-overflow');
+    }
+}
+
+/**
+ * Parse a lines attribute value following AdwActionRow semantics:
+ * - Missing/null/empty → 0 (unlimited)
+ * - Invalid/non-numeric → 0 (unlimited)
+ * - n > 0 → n (clamp to n lines)
+ * - n <= 0 → 0 (unlimited; pspec range is 0..G_MAXINT)
+ */
+export function parseRowLinesAttribute(value: string | null): number {
+    if (value === null || value === '') return 0;
+    const parsed = Number.parseInt(value, 10);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : 0;
+}

package/src/row-tooltip.spec.ts

@@ -0,0 +1,313 @@
+// `Gtk.Widget:tooltip-text` on the boxed-list rows, and the two sensitivity doors
+// `<adw-toggle-group>` gained with it.
+//
+// THE COLLISION THESE TESTS EXIST FOR: a row's `title` attribute is its LABEL
+// (`Adw.PreferencesRow:title`), and `HTMLElement.title` reflects the same attribute — so
+// the browser's own tooltip channel cannot be written on the host without blanking the
+// label. `src/row-tooltip.ts` puts it on the row's PARTS instead, and Firefox resolves a
+// tooltip by walking up from the hovered node until an element carries a non-empty
+// `title`. What the tests pin is that consequence: the parts carry the text, the host's
+// label survives, and a part the element gave a tooltip of its own keeps it.
+import { describe, expect, it } from '@gjsify/unit';
+
+import type { AdwToggleGroup } from './elements/adw-toggle-group.js';
+
+/** Connect, run, disconnect — the same helper `keyboard-operable.spec.ts` drives with. */
+function withWidget(make: () => HTMLElement, body: (el: HTMLElement) => void): void {
+    const el = make();
+    document.body.appendChild(el);
+    try {
+        body(el);
+    } finally {
+        el.remove();
+    }
+}
+
+/** The parts `applyRowTooltip` is expected to have written `tooltip-text` onto. */
+const TOOLTIPPED_PARTS: Record<string, string[]> = {
+    'adw-action-row': ['.adw-action-row-prefix', '.adw-row-text', '.adw-action-row-suffix'],
+    'adw-button-row': ['.adw-button-row-contents'],
+    'adw-combo-row': ['.adw-row-text', '.adw-row-value', 'select'],
+    'adw-expander-row': ['.adw-expander-row-header'],
+    'adw-preferences-row': ['.adw-row-title', '.adw-preferences-row-content'],
+    'adw-spin-row': ['.adw-row-text', '.adw-spin-control'],
+    'adw-switch-row': ['.adw-switch-row-prefix', '.adw-row-text'],
+};
+
+/** Every `title` attribute inside `el`, as `selector → value`, absent ones as `null`. */
+function partTitles(el: Element): Record<string, string | null> {
+    const titles: Record<string, string | null> = {};
+    for (const selector of TOOLTIPPED_PARTS[el.localName]) {
+        titles[selector] = el.querySelector(selector)?.getAttribute('title') ?? null;
+    }
+    return titles;
+}
+
+/**
+ * Measure the vertical coverage of tooltip-marked parts against the row's bounding box.
+ * Returns the ratio of covered height to row height (1.0 = full coverage).
+ */
+function tooltipCoverageRatio(el: HTMLElement): number {
+    const rowRect = el.getBoundingClientRect();
+    const parts = TOOLTIPPED_PARTS[el.localName] ?? [];
+    if (parts.length === 0) return 0;
+
+    // Union of all tooltip parts' bounding boxes
+    let top = Infinity;
+    let bottom = -Infinity;
+    for (const selector of parts) {
+        const part = el.querySelector(selector) as HTMLElement | null;
+        if (!part) continue;
+        const rect = part.getBoundingClientRect();
+        top = Math.min(top, rect.top);
+        bottom = Math.max(bottom, rect.bottom);
+    }
+    if (!isFinite(top) || !isFinite(bottom)) return 0;
+    const covered = bottom - top;
+    return covered / rowRect.height;
+}
+
+export const AdwRowTooltipTest = async () => {
+    await describe('row tooltip-text (Gtk.Widget:tooltip-text)', async () => {
+        // One case per row family, and the assertion is the SAME for all of them: the
+        // parts carry the text and the host keeps its label. A row that wrote the tooltip
+        // on the host instead would blank `title` here, which is the whole failure mode.
+        for (const [tag, selectors] of Object.entries(TOOLTIPPED_PARTS)) {
+            await it(`${tag} puts tooltip-text on its parts and keeps its title label`, () => {
+                withWidget(
+                    () => {
+                        const el = document.createElement(tag);
+                        el.setAttribute('title', 'Wi-Fi');
+                        el.setAttribute('tooltip-text', 'Connects to the office network');
+                        return el;
+                    },
+                    (el) => {
+                        expect(el.getAttribute('title')).toBe('Wi-Fi');
+                        expect((el as HTMLElement & { title: string }).title).toBe('Wi-Fi');
+                        for (const selector of selectors) {
+                            expect(el.querySelector(selector)?.getAttribute('title')).toBe(
+                                'Connects to the office network',
+                            );
+                        }
+                    },
+                );
+            });
+
+            await it(`${tag} clears the tooltip when the attribute goes`, () => {
+                withWidget(
+                    () => {
+                        const el = document.createElement(tag);
+                        el.setAttribute('title', 'Wi-Fi');
+                        el.setAttribute('tooltip-text', 'Gone soon');
+                        return el;
+                    },
+                    (el) => {
+                        expect(partTitles(el)).toStrictEqual(
+                            Object.fromEntries(TOOLTIPPED_PARTS[tag].map((selector) => [selector, 'Gone soon'])),
+                        );
+
+                        el.removeAttribute('tooltip-text');
+                        for (const selector of selectors) {
+                            expect(el.querySelector(selector)?.hasAttribute('title')).toBe(false);
+                        }
+                        // The LABEL is untouched either way.
+                        expect(el.getAttribute('title')).toBe('Wi-Fi');
+                    },
+                );
+            });
+        }
+
+        await it('adw-entry-row leaves the apply button its own tooltip', () => {
+            withWidget(
+                () => {
+                    const el = document.createElement('adw-entry-row');
+                    el.setAttribute('text', 'query');
+                    el.setAttribute('show-apply-button', '');
+                    el.setAttribute('tooltip-text', 'The search term');
+                    return el;
+                },
+                (el) => {
+                    const apply = el.querySelector('button') as HTMLButtonElement;
+                    expect(apply.title).not.toBe('The search term');
+                    expect(apply.title.length).toBeGreaterThan(0);
+                    // The editable area is the part that takes the row's tooltip.
+                    expect(el.querySelector('.adw-entry-row-text')?.getAttribute('title')).toBe('The search term');
+                },
+            );
+        });
+
+        await it('adw-password-entry-row inherits the entry row tooltip', () => {
+            withWidget(
+                () => {
+                    const el = document.createElement('adw-password-entry-row');
+                    el.setAttribute('title', 'Password');
+                    el.setAttribute('tooltip-text', 'At least 12 characters');
+                    return el;
+                },
+                (el) => {
+                    expect(el.getAttribute('title')).toBe('Password');
+                    expect(el.querySelector('.adw-password-entry-row-text')?.getAttribute('title')).toBe(
+                        'At least 12 characters',
+                    );
+                },
+            );
+        });
+
+        // BLOCKER 1: the tooltip parts must cover the row's full hit area (height).
+        // GTK draws the tooltip over the whole widget; the port was only covering the
+        // label text's own height. The `[data-row-tooltip]` marker + `align-self: stretch`
+        // in `_row.scss` stretches the parts, and this assertion prevents regression.
+        await it("tooltip parts cover the row's full height (>= 0.95 of row height)", () => {
+            for (const [tag] of Object.entries(TOOLTIPPED_PARTS)) {
+                withWidget(
+                    () => {
+                        const el = document.createElement(tag);
+                        el.setAttribute('title', 'Wi-Fi');
+                        el.setAttribute('tooltip-text', 'Connects to the office network');
+                        return el;
+                    },
+                    (el) => {
+                        // Force layout so getBoundingClientRect is accurate
+                        el.style.position = 'absolute';
+                        el.style.top = '-9999px';
+                        document.body.appendChild(el);
+                        try {
+                            const ratio = tooltipCoverageRatio(el);
+                            expect(ratio).toBeGreaterThanOrEqual(0.95);
+                        } finally {
+                            el.remove();
+                        }
+                    },
+                );
+            }
+        });
+    });
+
+    await describe('adw-toggle-group sensitivity', async () => {
+        const group = (attrs: Record<string, string>, toggles: string[]) => () => {
+            const el = document.createElement('adw-toggle-group');
+            for (const [name, value] of Object.entries(attrs)) el.setAttribute(name, value);
+            el.innerHTML = toggles.join('');
+            return el;
+        };
+        const buttons = (el: Element) => Array.from(el.querySelectorAll<HTMLButtonElement>('button.adw-toggle'));
+
+        await it('defaults to sensitive, so a bare group is operable', () => {
+            withWidget(group({}, ['<adw-toggle label="One"></adw-toggle>']), (el) => {
+                const group = el as unknown as AdwToggleGroup;
+                expect(group.sensitive).toBe(true);
+                expect(el.hasAttribute('disabled')).toBe(false);
+                expect(buttons(el)[0].disabled).toBe(false);
+            });
+        });
+
+        await it('reads `sensitive` by VALUE, not by presence', () => {
+            // `GtkWidget:sensitive` defaults to TRUE. Read by presence, the bare element
+            // would be insensitive and every group on a page would be dimmed and dead.
+            withWidget(group({ sensitive: 'false' }, ['<adw-toggle label="One"></adw-toggle>']), (el) => {
+                const group = el as unknown as AdwToggleGroup;
+                expect(group.sensitive).toBe(false);
+                expect(el.getAttribute('disabled')).toBe('');
+                expect(buttons(el)[0].disabled).toBe(true);
+            });
+        });
+
+        await it('an explicit `sensitive="true"` is sensitive', () => {
+            withWidget(group({ sensitive: 'true' }, ['<adw-toggle label="One"></adw-toggle>']), (el) => {
+                expect((el as unknown as AdwToggleGroup).sensitive).toBe(true);
+                expect(el.hasAttribute('disabled')).toBe(false);
+            });
+        });
+
+        await it('sensitive is reachable as a property and takes effect live', () => {
+            withWidget(
+                group({}, ['<adw-toggle label="One"></adw-toggle>', '<adw-toggle label="Two"></adw-toggle>']),
+                (el) => {
+                    const group = el as unknown as AdwToggleGroup;
+                    expect(buttons(el).map((btn) => btn.disabled)).toStrictEqual([false, false]);
+
+                    group.sensitive = false;
+                    expect(buttons(el).map((btn) => btn.disabled)).toStrictEqual([true, true]);
+                    expect(el.getAttribute('disabled')).toBe('');
+
+                    group.sensitive = true;
+                    expect(buttons(el).map((btn) => btn.disabled)).toStrictEqual([false, false]);
+                    expect(el.hasAttribute('disabled')).toBe(false);
+                },
+            );
+        });
+
+        await it('one toggle takes `enabled="false"` and only that one', () => {
+            // `AdwToggle:enabled` — `add_toggle` spends it on the button it builds
+            // (adw-toggle-group.c:871). `boolAttribute` is not its reading: the property
+            // defaults TRUE, so a bare `<adw-toggle>` is enabled.
+            withWidget(
+                group({}, [
+                    '<adw-toggle label="One"></adw-toggle>',
+                    '<adw-toggle label="Two" enabled="false"></adw-toggle>',
+                ]),
+                (el) => {
+                    expect(buttons(el).map((btn) => btn.disabled)).toStrictEqual([false, true]);
+                    expect((el as unknown as AdwToggleGroup).isToggleEnabled(0)).toBe(true);
+                    expect((el as unknown as AdwToggleGroup).isToggleEnabled(1)).toBe(false);
+                },
+            );
+        });
+
+        await it('an insensitive toggle cannot be selected', () => {
+            // `set_active_toggle` refuses a toggle that is not enabled (:720), so a
+            // disabled button and an unreachable selection cannot disagree.
+            withWidget(
+                group({}, [
+                    '<adw-toggle label="One"></adw-toggle>',
+                    '<adw-toggle label="Two" enabled="false"></adw-toggle>',
+                ]),
+                (el) => {
+                    buttons(el)[1].click();
+                    expect((el as unknown as AdwToggleGroup).active).toBe(0);
+                    expect(buttons(el).map((btn) => btn.classList.contains('active'))).toStrictEqual([true, false]);
+                    // The reflected `active` is written only on a real CHANGE
+                    // (`_selectIndex`), and this press was not one — so it stays absent,
+                    // the way a group nobody has touched reads.
+                    expect(el.hasAttribute('active')).toBe(false);
+                },
+            );
+        });
+
+        await it('an active-but-insensitive toggle hands the selection to an enabled one', () => {
+            // `active="1"` beside `<adw-toggle enabled="false">` is a pair upstream cannot
+            // express — `adw_toggle_set_enabled` clears the selection instead (:1659). Left
+            // alone it would be a checked radio nothing can focus or click.
+            withWidget(
+                group({ active: '1' }, [
+                    '<adw-toggle label="One"></adw-toggle>',
+                    '<adw-toggle label="Two" enabled="false"></adw-toggle>',
+                ]),
+                (el) => {
+                    expect((el as unknown as AdwToggleGroup).active).toBe(0);
+                    expect(buttons(el).map((btn) => btn.classList.contains('active'))).toStrictEqual([true, false]);
+                    // And the group's ONE tab stop is on the toggle that can take it.
+                    expect(buttons(el).map((btn) => btn.tabIndex)).toStrictEqual([0, -1]);
+                },
+            );
+        });
+
+        await it('a group with no enabled toggle leaves the selection alone', () => {
+            withWidget(
+                group({}, [
+                    '<adw-toggle label="One" enabled="false"></adw-toggle>',
+                    '<adw-toggle label="Two" enabled="false"></adw-toggle>',
+                ]),
+                (el) => {
+                    // Nothing to move it to. The selection stays where the core put it
+                    // (index 0), so the first button gets tabIndex 0 (the group's one
+                    // tab stop) even though it is disabled — the roving filter will
+                    // skip it, but the attribute reflects the active index.
+                    expect((el as unknown as AdwToggleGroup).active).toBe(0);
+                    expect(buttons(el).every((btn) => btn.disabled)).toBe(true);
+                    expect(buttons(el).map((btn) => btn.tabIndex)).toStrictEqual([0, -1]);
+                },
+            );
+        });
+    });
+};

package/src/row-tooltip.ts

@@ -0,0 +1,52 @@
+// `Gtk.Widget:tooltip-text` on a boxed-list row.
+//
+// A BROWSER'S TOOLTIP IS THE `title` CONTENT ATTRIBUTE, and on a row that attribute is
+// already spoken for: `Adw.PreferencesRow:title` is the row's LABEL and is authored as
+// `title=`, which is the same attribute `HTMLElement.title` reflects. Writing the tooltip
+// to the host would blank the label, so it goes to the row's own parts instead — and the
+// browser then finds it FIRST. Firefox resolves a tooltip by walking UP from the hovered
+// node until an element carries a non-empty `title`, so one `title` per part covers
+// everything inside it. Two consequences, both wanted:
+//
+//   - a SLOTTED control that carries a tooltip of its own still wins, which is GTK's
+//     precedence too — `gtk_widget_set_tooltip_text` on a child replaces the parent's;
+//   - a part the element owns for its OWN tooltip keeps it, which is why the entry row
+//     hands over its prefixes / area / suffixes and not its apply button.
+//
+// A PART ONLY COUNTS IF IT COVERS THE ROW. Measured on the shipped row before the
+// `data-row-tooltip` marker existed: a 884x54 `adw-action-row` offered the LABEL over 36 of
+// its 54 rows of pixels and across its 24px of inline padding, and the tooltip only over the
+// 18px the label text happens to occupy — the label column is content-height in a 54px row,
+// so two thirds of the widget's own hit area fell through to the host and found the label.
+// The tooltip has to reach the whole widget the way GTK's does, so the marked part STRETCHES
+// (`scss/_row.scss`) and the row's inline padding is what is left; `row-tooltip.spec.ts`
+// measures the covered region against the row's box so this cannot come back.
+//
+// Upstream has no stylesheet rule for this: GTK draws the tooltip surface itself
+// (`refs/libadwaita/src/stylesheet/widgets/_tooltip.scss`), and `refs/adwaita-web` has no
+// `tooltip` anywhere. The browser's own tooltip IS the port.
+
+/**
+ * Apply `row`'s `tooltip-text` to `parts`, or clear it when the attribute is absent.
+ *
+ * `parts` are the row's OWN sections, never a slotted consumer widget — see the header.
+ * Each one is marked `data-row-tooltip`, which is the hook `scss/_row.scss` stretches so
+ * the tooltip covers the row rather than the label text inside it.
+ */
+export function applyRowTooltip(row: HTMLElement, parts: readonly Element[]): void {
+    const tooltip = row.getAttribute('tooltip-text') ?? '';
+    for (const part of parts) {
+        if (tooltip) {
+            // Only on a real change: `_render` runs on every unrelated attribute write, and
+            // `setAttribute` fires a mutation record even for the value already there.
+            if (part.getAttribute('title') !== tooltip) part.setAttribute('title', tooltip);
+            if (!part.hasAttribute(TOOLTIP_PART_ATTR)) part.setAttribute(TOOLTIP_PART_ATTR, '');
+        } else {
+            part.removeAttribute('title');
+            part.removeAttribute(TOOLTIP_PART_ATTR);
+        }
+    }
+}
+
+/** The hook `applyRowTooltip` marks its parts with, and `scss/_row.scss` selects on. */
+const TOOLTIP_PART_ATTR = 'data-row-tooltip';