@gjsify/adwaita-web 0.53.0 → 0.55.0

package/src/elements/gtk-level-bar.ts

@@ -0,0 +1,323 @@
+// <gtk-level-bar> — a filled portion of a bounded range: a password strength meter, a
+// battery. It is NOT a progress bar: the value may go DOWN, and it is drawn in
+// PROPORTION to an interval (`min-value`…`max-value`), not to a 0…1 fraction.
+//
+// CSS NODES, PORTED VERBATIM (gtklevelbar.c:99-116):
+//   levelbar[.discrete] ─╮
+//     ├── trough         │
+//     │   ├── block.filled.level-name
+//     │   └── block.empty
+// The `level-name` class on a filled block IS the public API for colouring a bar —
+// libadwaita paints `.low` warning, `.high`/`:not(.empty)` accent and `.full` success
+// off it (refs/libadwaita/src/stylesheet/widgets/_level-bar.scss:71-93), and an
+// application adds its own offset to add its own class (gtklevelbar.c:59-76).
+//
+// WHICH CLASS, FROM THE OFFSETS. `update_level_style_classes` walks the offsets in
+// ASCENDING order and stops at the first one that can name the current value
+// (gtklevelbar.c:604-625): the lowest offset at or above the value wins, and the lowest
+// one of all wins even when the value sits below it. Three offsets exist before any
+// code runs — `low` 0.25, `high` 0.75, `full` 1.0 (gtklevelbar.c:1058-1060) — so
+// `value = 0` already reads `low`, exactly as it does in GTK.
+//
+// HOW MANY BLOCKS. Continuous is ONE drawn level with two nodes under the trough (the
+// empty one and the filled one painted on top, gtklevelbar.c:344-362); discrete is
+// `MAX(1, round(max) − round(min))` drawn blocks (gtklevelbar.c:285-294) of which
+// `MIN(blocks, round(value) − round(min))` are filled (gtklevelbar.c:630-633). `inverted`
+// counts from the other end — it reverses which block index is filled, it does not
+// reverse the DOM (gtklevelbar.c:637, 648).
+//
+// SETTING AN END MOVES THE VALUE. `set_min_value` pushes `value` up to the new minimum
+// and `set_max_value` pushes it down to the new maximum (gtklevelbar.c:1191-1192,
+// :1229-1230), and the maximum additionally CLAMPS every offset into the new interval
+// (:1234, :667-682) — the minimum deliberately does not. Both are GObject property
+// setters, so each fires `notify::` for the value it moved as well as its own.
+//
+// A11Y: `role="meter"`, which is GtkLevelBar's own accessible role
+// (gtklevelbar.c:1033), with `aria-valuemin` / `aria-valuemax` / `aria-valuenow` over
+// the REAL interval rather than 0…1 (gtklevelbar.c:1070-1074, :1199-1202, :1238-1241,
+// :1266-1268).
+//
+// Events: `notify::<prop>` (CustomEvent, bubbles, detail `{ <prop>: value }`) on every
+// real change, and `offset-changed` (CustomEvent, bubbles, detail `{ name }`), GtkLevelBar's
+// own DETAILED signal (gtklevelbar.c:936-958, :1410) — the browser has no per-name signal
+// channel, so the name rides in the detail.
+//
+// Reference: refs/gtk/gtk/gtklevelbar.c
+// Copyright (c) The GTK Team. LGPLv2.1+.
+// Modifications: Implemented as a Web Component for @gjsify/adwaita-web.
+
+import { normalizeBoxOrientation, type BoxOrientation } from '@gjsify/adwaita-core';
+
+/** `GtkLevelBarMode`, spelled as the GIR's enum nicks (:1004-1008). */
+type LevelBarMode = 'continuous' | 'discrete';
+
+/** The offsets GTK installs before any application code runs (gtklevelbar.c:1058-1060). */
+const DEFAULT_OFFSETS: readonly (readonly [string, number])[] = [
+    ['low', 0.25],
+    ['high', 0.75],
+    ['full', 1.0],
+];
+
+/**
+ * The offset that names `value`, transcribed from `update_level_style_classes`
+ * (gtklevelbar.c:604-625): ascending, first offset at or above the value wins, and an
+ * offset whose PREDECESSOR is not below the value names nothing — the walk continues.
+ * Keeping the `previous < value` test rather than simplifying it away is the point:
+ * two offsets sharing a value make the two spellings disagree, and only one is C.
+ */
+function levelClassFor(offsets: readonly (readonly [string, number])[], value: number): string | null {
+    for (let i = 0; i < offsets.length; i++) {
+        const [name, threshold] = offsets[i];
+        if (value > threshold) continue;
+        const previous = i === 0 ? null : offsets[i - 1][1];
+        if (previous === null || previous < value) return name;
+    }
+    return null;
+}
+
+/** A missing or unparseable attribute is `fallback`, which is also the GIR default. */
+function numberAttribute(element: HTMLElement, name: string, fallback: number): number {
+    const raw = Number.parseFloat(element.getAttribute(name) ?? '');
+    return Number.isFinite(raw) ? raw : fallback;
+}
+
+export class GtkLevelBar extends HTMLElement {
+    private _trough!: HTMLSpanElement;
+    private _initialized = false;
+    /** Offset name → value, kept sorted ascending exactly as the C's `GList` is. */
+    private _offsets: (readonly [string, number])[] = DEFAULT_OFFSETS.map((entry) => [...entry] as const);
+
+    static get observedAttributes() {
+        return ['value', 'min-value', 'max-value', 'mode', 'inverted', 'orientation', 'disabled'];
+    }
+
+    /** `Gtk.LevelBar:value` — the filled level. */
+    get value(): number {
+        return numberAttribute(this, 'value', 0);
+    }
+
+    set value(v: number) {
+        this._write('value', String(v));
+    }
+
+    /** `Gtk.LevelBar:min-value` — the low end of the interval. Defaults to 0. */
+    get minValue(): number {
+        return numberAttribute(this, 'min-value', 0);
+    }
+
+    set minValue(v: number) {
+        this._write('min-value', String(v));
+    }
+
+    /** `Gtk.LevelBar:max-value` — the high end of the interval. Defaults to 1. */
+    get maxValue(): number {
+        return numberAttribute(this, 'max-value', 1);
+    }
+
+    set maxValue(v: number) {
+        this._write('max-value', String(v));
+    }
+
+    /** `Gtk.LevelBar:mode` — one filled block, or one per unit of the interval. */
+    get mode(): LevelBarMode {
+        return this.getAttribute('mode') === 'discrete' ? 'discrete' : 'continuous';
+    }
+
+    set mode(v: LevelBarMode) {
+        this._write('mode', v);
+    }
+
+    /** `Gtk.LevelBar:inverted` — grow from the far end. */
+    get inverted(): boolean {
+        return this.hasAttribute('inverted');
+    }
+
+    set inverted(v: boolean) {
+        this.toggleAttribute('inverted', !!v);
+    }
+
+    /** `GtkOrientable:orientation` (gtklevelbar.c:825-835). Horizontal fills rightwards. */
+    get orientation(): BoxOrientation {
+        return normalizeBoxOrientation(this.getAttribute('orientation'));
+    }
+
+    set orientation(v: BoxOrientation) {
+        this._write('orientation', v);
+    }
+
+    /**
+     * `setAttribute` runs the custom-element reaction for a write that changes nothing,
+     * while every GObject setter here returns early when the value is already right
+     * (gtklevelbar.c:1186-1187, :1224-1225, :1300-1301, :1260-1261). This is the guard
+     * that makes "notify only on a real change" true for the numeric and enum half.
+     */
+    private _write(name: string, value: string): void {
+        if (this.getAttribute(name) !== value) this.setAttribute(name, value);
+    }
+
+    get disabled(): boolean {
+        return this.hasAttribute('disabled');
+    }
+
+    set disabled(v: boolean) {
+        this.toggleAttribute('disabled', !!v);
+    }
+
+    /**
+     * `gtk_level_bar_add_offset_value` (gtklevelbar.c:1395-1411): replaces the value of
+     * an offset of the same name, keeps the list sorted, refuses a value outside the
+     * interval (`g_return_if_fail (gtk_level_bar_value_in_interval (…))`, :1403), and
+     * emits `offset-changed` — but only when the value actually moved (:259-260).
+     */
+    addOffsetValue(name: string, value: number): void {
+        if (value < this.minValue || value > this.maxValue) return;
+        const existing = this._offsets.findIndex(([key]) => key === name);
+        if (existing !== -1 && this._offsets[existing][1] === value) return;
+        if (existing !== -1) this._offsets.splice(existing, 1);
+        this._offsets.push([name, value]);
+        this._offsets.sort((a, b) => a[1] - b[1]);
+        this._render();
+        this.dispatchEvent(new CustomEvent('offset-changed', { bubbles: true, detail: { name } }));
+    }
+
+    /** `gtk_level_bar_remove_offset_value` (gtklevelbar.c:1362-1377). */
+    removeOffsetValue(name: string): void {
+        const existing = this._offsets.findIndex(([key]) => key === name);
+        if (existing === -1) return;
+        this._offsets.splice(existing, 1);
+        this._render();
+    }
+
+    /** `gtk_level_bar_get_offset_value` (gtklevelbar.c:1423-1443) — `null` when absent. */
+    offsetValue(name: string): number | null {
+        return this._offsets.find(([key]) => key === name)?.[1] ?? null;
+    }
+
+    connectedCallback() {
+        if (this._initialized) {
+            this._render();
+            return;
+        }
+        this._initialized = true;
+
+        this._trough = document.createElement('span');
+        this._trough.className = 'adw-level-bar-trough';
+        this.replaceChildren(this._trough);
+
+        this.setAttribute('role', 'meter');
+        this._render();
+    }
+
+    attributeChangedCallback(name: string) {
+        if (!this._initialized || name === 'disabled') return;
+        // A NEW interval endpoint drags the value with it (gtklevelbar.c:1191-1192,
+        // :1229-1230); writing the clamped value back re-enters here as a `value` change,
+        // so the value notifies first and the endpoint second — the C's order, where
+        // `set_value_internal` runs before the endpoint's own `g_object_notify_by_pspec`
+        // (:1164 before :1204, :1243). `set_max_value` clamps the OFFSETS as well, and on
+        // both paths.
+        if (name === 'min-value' && this.value < this.minValue) {
+            this._write('value', String(this.minValue));
+            this._notify(name);
+            return;
+        }
+        if (name === 'max-value') {
+            this._clampOffsets();
+            if (this.value > this.maxValue) {
+                this._write('value', String(this.maxValue));
+                this._notify(name);
+                return;
+            }
+        }
+        this._render();
+        this._notify(name);
+    }
+
+    private _notify(name: string): void {
+        this.dispatchEvent(
+            new CustomEvent(`notify::${name}`, { bubbles: true, detail: { [name]: this._property(name) } }),
+        );
+    }
+
+    /** One interval endpoint CLAMPS every offset into the new range — the other does not. */
+    private _clampOffsets(): void {
+        for (let i = 0; i < this._offsets.length; i++) {
+            const [name, value] = this._offsets[i];
+            if (value < this.minValue) this._offsets[i] = [name, this.minValue];
+            else if (value > this.maxValue) this._offsets[i] = [name, this.maxValue];
+        }
+    }
+
+    /** The `notify::` detail for `name`: the PROPERTY, parsed, not the raw attribute. */
+    private _property(name: string): string | number | boolean {
+        switch (name) {
+            case 'value':
+                return this.value;
+            case 'min-value':
+                return this.minValue;
+            case 'max-value':
+                return this.maxValue;
+            case 'mode':
+                return this.mode;
+            case 'inverted':
+                return this.inverted;
+            default:
+                return this.orientation;
+        }
+    }
+
+    private _render(): void {
+        if (!this._trough) return;
+        const discrete = this.mode === 'discrete';
+        const vertical = this.orientation === 'vertical';
+        // `update_mode_style_classes` puts exactly one of the two on the node
+        // (gtklevelbar.c:574-590), and libadwaita's `levelbar.horizontal` /
+        // `levelbar.vertical` selectors are what read them.
+        this.classList.toggle('continuous', !discrete);
+        this.classList.toggle('discrete', discrete);
+        this.classList.toggle('vertical', vertical);
+        this.classList.toggle('horizontal', !vertical);
+
+        const min = this.minValue;
+        const max = this.maxValue;
+        const value = this.value;
+        // `gtk_level_bar_get_num_blocks` (gtklevelbar.c:285-294) — the node count is one
+        // MORE than the block count in continuous mode: the empty level is its own node.
+        const blocks = discrete ? Math.max(1, Math.round(max) - Math.round(min)) : 1;
+        const level = levelClassFor(this._offsets, value);
+
+        this._trough.replaceChildren();
+        if (!discrete) {
+            // The empty level is allocated full size and the filled one painted over it
+            // (gtklevelbar.c:344-362); at value 0 the filled node is never allocated at
+            // all (:429-430), which is what `hidden` stands for here.
+            const empty = this._block('empty', null);
+            const filled = this._block('filled', level);
+            filled.style.setProperty('--level-fraction', String(max > min ? (value - min) / (max - min) : 0));
+            filled.hidden = value === 0;
+            this._trough.append(empty, filled);
+        } else {
+            const count = Math.min(blocks, Math.max(0, Math.round(value) - Math.round(min)));
+            for (let i = 0; i < blocks; i++) {
+                // `inverted` fills from the far end by reversing the INDEX, so the first
+                // DOM block is filled last (gtklevelbar.c:637, 648).
+                const isFilled = this.inverted ? i >= blocks - count : i < count;
+                this._trough.append(this._block(isFilled ? 'filled' : 'empty', isFilled ? level : null));
+            }
+        }
+
+        this.setAttribute('aria-valuemin', String(min));
+        this.setAttribute('aria-valuemax', String(max));
+        this.setAttribute('aria-valuenow', String(value));
+    }
+
+    /** One `block` node, `filled` or `empty`, wearing the offset's class (:635-652). */
+    private _block(state: 'filled' | 'empty', level: string | null): HTMLSpanElement {
+        const block = document.createElement('span');
+        block.className = `adw-level-bar-block ${state}`;
+        if (state === 'filled' && level) block.classList.add(level);
+        return block;
+    }
+}
+
+customElements.define('gtk-level-bar', GtkLevelBar);

package/src/elements/gtk-link-button.ts

@@ -0,0 +1,138 @@
+// <gtk-link-button> — a button that follows a URI. `Gtk.LinkButton` IS a `Gtk.Button`
+// with two properties of its own, so this element extends `<gtk-button>` and inherits
+// its label, icon, child and style-class attributes unchanged; `uri` and `visited` are
+// the whole of the addition.
+//
+// `visited` is the state a browser already knows: once a link has been followed it is
+// drawn in the visited colour and announces as visited. GTK reaches that through two
+// state flags — `GTK_STATE_FLAG_LINK` when unvisited, `GTK_STATE_FLAG_VISITED` when
+// visited (gtklinkbutton.c:359, 742-749) — and here it is one `.visited` class on the
+// inner button, because the stylesheet has to be able to select on it.
+//
+// THE ORDER OF TWO OPERATIONS IS GTK'S, not ours. `gtk_link_button_set_uri()` ends with
+// `gtk_link_button_set_visited (link_button, FALSE)` (gtklinkbutton.c:695): pointing the
+// button somewhere else un-visits it, because the new target has not been seen. And
+// `gtk_link_button_activate_link()` — the DEFAULT handler of `::activate-link` — sets it
+// visited AFTER handing the URI to the launcher (:550). The state follows the click.
+//
+// `::activate-link` is a BOOLEAN-ACCUMULATOR signal: a handler returning TRUE stops the
+// default handler from running (gtklinkbutton.c:216-238). The DOM spelling of "return
+// TRUE" is `preventDefault()` on a cancelable event, so `activate-link` is dispatched
+// cancelable and the launch happens only when nothing cancelled it.
+//
+// WHAT THE LAUNCH IS HERE. GTK hands the URI to the desktop's handler
+// (`GtkUriLauncher`, gtklinkbutton.c:528-548), which opens it in ANOTHER application and
+// leaves the button's window standing. The browser's equivalent of "another
+// application" is another tab, so the URI goes to `window.open(uri, '_blank',
+// 'noopener')` — deliberately not `location.assign`, which would tear the page down the
+// way a desktop does not.
+//
+// NOT PORTED, and it is not a property: the CONTEXT MENU. `GtkLinkButton` installs
+// `clipboard.copy` and `menu.popup` actions and binds Shift+F10 / Menu to them
+// (gtklinkbutton.c:247-264), opening a `GtkPopoverMenu` with one entry. A browser
+// already owns the context menu on a button, and taking it over would remove the
+// platform's menu from every link on the page — so `::activate-link` is the whole of
+// the activation surface here.
+//
+// A11Y: GTK's role is LINK (gtklinkbutton.c:244). A native `<button>` keeps the button
+// role — a `<button role="link">` would stop being announced as pressable — and the URI
+// rides along in the tooltip exactly as `gtk_link_button_query_tooltip_cb` puts it there
+// when the button has no tooltip of its own and its label is not already the URI
+// (:646-672).
+//
+// Reference: refs/gtk/gtk/gtklinkbutton.c (uri, visited, activate-link, the tooltip)
+// Reference: refs/libadwaita/src/stylesheet/widgets/_links.scss (`button.link`)
+// Copyright (c) GNOME contributors (libadwaita). LGPLv2.1+.
+// Modifications: Implemented as a Web Component for @gjsify/adwaita-web.
+
+import { GtkButton } from './gtk-button.js';
+
+export class GtkLinkButton extends GtkButton {
+    private _wired = false;
+
+    static get observedAttributes() {
+        return [...GtkButton.observedAttributes, 'uri', 'visited'];
+    }
+
+    /** `Gtk.LinkButton:uri` — the address this button points at. */
+    get uri(): string {
+        return this.getAttribute('uri') ?? '';
+    }
+
+    set uri(value: string) {
+        this.setAttribute('uri', value);
+    }
+
+    /**
+     * `Gtk.LinkButton:visited` — whether the link has been followed. The state flag
+     * GTK swaps here is what the stylesheet paints as `:visited`, and the `VISITED`
+     * accessibility state beside it; see the header.
+     */
+    get visited(): boolean {
+        return this.hasAttribute('visited');
+    }
+
+    set visited(value: boolean) {
+        this.toggleAttribute('visited', !!value);
+    }
+
+    connectedCallback() {
+        super.connectedCallback();
+        if (this._wired) return;
+        this._wired = true;
+        this.button.addEventListener('click', () => this._activateLink());
+    }
+
+    // Optional because `GtkButton`'s own callback declares no parameter, and an override
+    // may not demand one the base signature does not pass.
+    attributeChangedCallback(name?: string) {
+        // A new destination has not been seen: `gtk_link_button_set_uri()` unsets
+        // `visited` itself (gtklinkbutton.c:695), and only for `uri` — writing `visited`
+        // directly is the author's own state change and has to survive.
+        if (name === 'uri' && this.isConnected) this.visited = false;
+        super.attributeChangedCallback();
+        if (name === 'visited' && this.isConnected) {
+            this.dispatchEvent(
+                new CustomEvent('notify::visited', { bubbles: true, detail: { visited: this.visited } }),
+            );
+        }
+    }
+
+    /**
+     * `::activate-link` — cancelable, because the signal is a boolean accumulator
+     * (gtklinkbutton.c:216-238) and `preventDefault()` is the DOM spelling of a handler
+     * returning TRUE. Nothing cancelled ⇒ the default handler runs.
+     */
+    private _activateLink(): void {
+        const event = new CustomEvent('activate-link', { bubbles: true, cancelable: true });
+        this.dispatchEvent(event);
+        if (event.defaultPrevented) return;
+        const { uri } = this;
+        // `gtk_link_button_new()` requires a URI (`g_return_val_if_fail (uri != NULL)`),
+        // so a button without one is half-written and there is nothing to launch.
+        if (uri === '') return;
+        this.launch(uri);
+        this.visited = true;
+    }
+
+    /**
+     * The launcher call, on its own method so a caller (or a spec) can stand in for the
+     * window the desktop would have opened.
+     */
+    protected launch(uri: string): void {
+        window.open(uri, '_blank', 'noopener');
+    }
+
+    protected override decorate(button: HTMLButtonElement): void {
+        button.classList.add('link');
+        button.classList.toggle('visited', this.visited);
+        const label = (this.getAttribute('label') ?? '').trim();
+        const tooltip = this.getAttribute('tooltip') ?? this.getAttribute('tooltip-text');
+        // `query_tooltip_cb` shows the URI only when the label would not repeat it.
+        if (tooltip === null && label !== '' && this.uri !== '' && this.uri !== label) {
+            button.title = this.uri;
+        }
+    }
+}
+
+customElements.define('gtk-link-button', GtkLinkButton);

package/src/elements/gtk-list-box-row.ts

@@ -0,0 +1,195 @@
+// <gtk-list-box-row> — one row of a `Gtk.ListBox`: the `activatable` / `selectable` pair and
+// the child that fills it, the web counterpart of `Gtk.ListBoxRow`.
+//
+// BOTH PROPERTIES DEFAULT TRUE (gtklistbox.c:3961-3962), so on this element they are INVERTED
+// flags and the attribute is read as `activatable="false"` — the same convention
+// `<gtk-tree-expander>` uses for `indent-for-depth`, and for the same reason: a bare
+// `activatable` on an element whose GIR default is TRUE would mean the opposite of what it
+// reads like. The alternative — a present-means-true attribute — cannot express "true", which
+// is the DEFAULT case and therefore the common one.
+//
+// THE `.activatable` CLASS IS NOT `activatable`. `gtk_list_box_update_row`
+// (gtklistbox.c:3600-3624) sets it when the row is activatable OR when it is selectable and
+// the BOX is not in `GTK_SELECTION_NONE`, and removes it otherwise. So a row in a
+// `selection-mode="none"` box with `activatable="false"` carries no class, and the same row
+// in a `selection-mode="single"` box does. The row therefore asks its parent, and the parent
+// owns that answer for every row at once — which is what `<gtk-list-box>`'s `_syncRows`
+// calls down into here for.
+//
+// `aria-selected` IS THE PARENT'S TOO, for the same C line: the accessible state is only
+// published when `selectable && can_select`, so a row in a `none` box must NOT announce
+// itself as unselected, and this element sets nothing of its own — `<gtk-list-box>` writes
+// the attribute.
+//
+// ENTER AND SPACE ARE THE ROW'S, and the C says so twice: `attachRowActivation` is the
+// module that makes a `GtkListBoxRow` a tab stop, and `gtk_list_box_row_class_init` installs
+// the `activate` signal this row dispatches (gtklistbox.c:3905-3910).
+//
+// WHAT IS NOT HERE, and why: `action-name` / `action-target` are `g_param_spec_override`s of
+// `GtkActionable` (gtklistbox.c:3946-3950), a `GAction` name and a `GVariant` target over a
+// `GActionMap` — there is no map here to look a name up in, and a target is a value rather
+// than a string. `get_index()` and `is_selected()` are METHODS over the box's children
+// sequence and are answered from the DOM (`index`, `selected`), so a row moved by
+// `insert_child_before` keeps reporting where it IS. The GIR puts `action-name` and
+// `action-target` in the `GtkActionableProps` chain rather than in the row's own body, so
+// `check-adwaita-element-properties` reads the row's OWN surface — which is exactly the two
+// booleans this element observes, and neither has a gap entry.
+//
+// Reference: refs/gtk/gtk/gtklistbox.c:3307-3331 (child), :3594-3722 (activatable, selectable,
+//   the `.activatable` class and the accessible state), :3877-3966 (class init, the signal, the
+//   defaults and the css name)
+// Reference: refs/libadwaita/src/stylesheet/widgets/_lists.scss:16-19, :47-95 (row)
+// Copyright (c) GNOME contributors (GTK/libadwaita). LGPLv2.1+.
+// Modifications: Implemented as a Web Component for @gjsify/adwaita-web.
+
+import { bindSlottedChildren } from '../slotted-children.js';
+import { type AdwRowActivation, attachRowActivation } from './row-activation.js';
+
+export class GtkListBoxRow extends HTMLElement {
+    private _contentsEl!: HTMLDivElement;
+    private _activation?: AdwRowActivation;
+    private _initialized = false;
+
+    static get observedAttributes() {
+        return ['activatable', 'selectable'];
+    }
+
+    /**
+     * `GtkListBoxRow:activatable` — TRUE by default (gtklistbox.c:3961), so this is the OFF
+     * switch and the attribute is read as `activatable="false"`.
+     */
+    get activatable(): boolean {
+        return this.getAttribute('activatable') !== 'false';
+    }
+
+    set activatable(value: boolean) {
+        this.setAttribute('activatable', String(!!value));
+    }
+
+    /**
+     * `GtkListBoxRow:selectable` — TRUE by default (gtklistbox.c:3962), read the same way as
+     * `activatable`.
+     */
+    get selectable(): boolean {
+        return this.getAttribute('selectable') !== 'false';
+    }
+
+    set selectable(value: boolean) {
+        this.setAttribute('selectable', String(!!value));
+    }
+
+    /** Where this row sits in its box, or -1 while it has no box. */
+    get index(): number {
+        return this.parentElement ? [...this.parentElement.children].indexOf(this) : -1;
+    }
+
+    /**
+     * Whether this row is selected — `gtk_list_box_row_is_selected`, answered by the parent so
+     * a row moved between boxes never carries a stale answer.
+     */
+    get selected(): boolean {
+        return this.classList.contains('selected');
+    }
+
+    /** `GtkListBoxRow:child`, as the light-DOM child it already is. */
+    get child(): Element | null {
+        return this._contentsEl.firstElementChild;
+    }
+
+    connectedCallback() {
+        if (this._initialized) {
+            // Re-entering a document: nothing here is torn down, so only the parent's derived
+            // state needs re-asking, and it re-asks on its own child list change.
+            return;
+        }
+        this._initialized = true;
+
+        this._contentsEl = document.createElement('div');
+        this._contentsEl.className = 'adw-list-box-row-contents';
+
+        // `child` is a WIDGET property, so it is a slot here (gtklistbox.c:3307-3331): the
+        // authored child lands in the same node `gtk_list_box_row_set_child` would put it in,
+        // and a child appended after connect lands there too.
+        bindSlottedChildren(this, [{ into: this._contentsEl }]).install(this._contentsEl);
+
+        // GTK declares the accessible role unconditionally (gtklistbox.c:3955), so there is
+        // no `selection-mode` to condition it on here.
+        this.setAttribute('role', 'listitem');
+        // `gtk_list_box_row_init` adds `.activatable` and makes the row focusable BEFORE any
+        // box exists (gtklistbox.c:3959-3966), because both properties default TRUE — so the
+        // class is already right for a row nobody has adopted yet, and it is the tab stop. The
+        // box NARROWS it in `syncClasses`, which is where `can_select` enters — and it also
+        // takes the tab stop over, see {@link claim}.
+        //
+        // A custom element's connect reactions are enqueued PARENT FIRST, so a row inside a
+        // box reaches this line AFTER `<gtk-list-box>` has already answered for it, with
+        // `can_select` already answered from `selection-mode`. Deriving the pre-adoption
+        // answer here would put back what the box just removed: `.activatable` on every row
+        // of a `selection-mode="none"` box, and — because `syncClasses` also re-derives the
+        // tab stop — every row back in the Tab order under `tab-behavior`, which is the
+        // measured defect `gtk-list-box.spec.ts`'s tab-behavior block exists to catch.
+        if (this._claimed) this._syncActivation();
+        else this.syncClasses(true);
+    }
+
+    /**
+     * Hand this row's `.activatable` class and tab stop to its box.
+     *
+     * Both are the box's to derive and neither is derivable here: `can_select` is the BOX's
+     * `selection-mode` (gtklistbox.c:3606-3609) and the tab stop is `GtkListBox:tab-behavior`,
+     * where `all` gives every activatable row its own stop and `item`/`cell` hand out a
+     * roving one — the split `gtk_list_box_focus` draws by walking rows between Tab presses
+     * only under `GTK_LIST_TAB_ALL` (gtklistbox.c:2037, :2067). The keys stay the row's:
+     * Enter and Space are `GtkListBoxRow`'s own (see `row-activation.ts`).
+     */
+    claim(): void {
+        this._claimed = true;
+    }
+
+    /** Give the row back to itself, for a box that no longer manages it. */
+    release(): void {
+        this._claimed = false;
+        // `gtk_list_box_update_row (NULL, row)` answers `can_select = FALSE` (gtklistbox.c:3606-3609),
+        // so what is left is the row's own `activatable` flag.
+        this.syncClasses(false);
+    }
+
+    /** What the box last said about itself; TRUE until a box narrows it. */
+    private _canSelect = true;
+
+    /** Set by {@link claim}. While it is set the row derives neither class nor tab stop. */
+    private _claimed = false;
+
+    attributeChangedCallback() {
+        if (!this._initialized) return;
+        // Both flags feed the class, so a write to either re-derives it against the box's LAST
+        // answer — not against a fresh default, which would resurrect the class on a row whose
+        // box has `selection-mode="none"`.
+        this.syncClasses(this._canSelect);
+    }
+
+    /**
+     * Re-derive the tab stop and the `.activatable` class.
+     *
+     * Public because the box owns the second half of the class rule — it knows
+     * `selection-mode`, this row does not — and calls this for every row when that changes.
+     */
+    syncClasses(canSelect: boolean): void {
+        this._canSelect = canSelect;
+        // `gtk_list_box_update_row` :3611-3615.
+        this.classList.toggle('activatable', this.activatable || (this.selectable && canSelect));
+        this._syncActivation();
+    }
+
+    private _syncActivation(): void {
+        this._activation ??= attachRowActivation({
+            row: this,
+            activatable: () => this.classList.contains('activatable'),
+            activate: () => this.dispatchEvent(new CustomEvent('activate', { bubbles: true })),
+        });
+        // The KEYS are installed either way; only the tab stop belongs to a claimed row.
+        if (!this._claimed) this._activation.sync();
+    }
+}
+
+customElements.define('gtk-list-box-row', GtkListBoxRow);