@gjsify/adwaita-web 0.54.0 → 0.56.0

package/src/gtk-window-handle.spec.ts

@@ -0,0 +1,158 @@
+// DOM-level tests for <gtk-window-handle>: the three titlebar gestures and what they raise.
+// The gestures are the whole widget — it has one property, a `child` slot, and no box of its
+// own — so what is asserted here is the ACTIONS, in the vocabulary
+// `perform_titlebar_action_fallback` uses when a compositor has no opinion.
+import { describe, expect, it } from '@gjsify/unit';
+
+import type { GtkWindowHandle } from './elements/gtk-window-handle.js';
+
+function mount(): { el: GtkWindowHandle; host: HTMLElement } {
+    const host = document.createElement('div');
+    host.style.width = '400px';
+    host.style.height = '40px';
+    document.body.appendChild(host);
+    const el = document.createElement('gtk-window-handle') as GtkWindowHandle;
+    el.style.display = 'contents';
+    const title = document.createElement('gtk-label');
+    title.setAttribute('label', 'Untitled');
+    el.appendChild(title);
+    host.appendChild(el);
+    return { el, host };
+}
+
+/** Every `event` name dispatched on `el`, with its `detail`. */
+function record(el: HTMLElement, ...events: string[]): Map<string, unknown[]> {
+    const seen = new Map<string, unknown[]>();
+    for (const name of events) {
+        const details: unknown[] = [];
+        seen.set(name, details);
+        el.addEventListener(name, (e) => details.push((e as CustomEvent).detail));
+    }
+    return seen;
+}
+
+const click = (el: HTMLElement, init: MouseEventInit = {}): void => {
+    el.dispatchEvent(new MouseEvent('click', { bubbles: true, cancelable: true, ...init }));
+};
+
+const pointer = (el: HTMLElement, type: string, init: PointerEventInit = {}): void => {
+    el.dispatchEvent(new PointerEvent(type, { bubbles: true, cancelable: true, ...init }));
+};
+
+export const GtkWindowHandleTest = async () => {
+    await describe('<gtk-window-handle> the titlebar actions', async () => {
+        await it('is a generic role and contributes no box of its own', async () => {
+            const { el, host } = mount();
+            expect(el.getAttribute('role')).toBe('generic');
+            // `display: contents` IS `GtkBinLayout`'s "the child takes the whole
+            // allocation", and what makes a handle usable as a titlebar strip.
+            expect(getComputedStyle(el).display).toBe('contents');
+            host.remove();
+        });
+
+        await it('turns a DOUBLE CLICK into toggle-maximize, and a single click into nothing', async () => {
+            const { el, host } = mount();
+            const seen = record(el, 'titlebar-action', 'window.toggle-maximized');
+            click(el, { button: 0, detail: 1 });
+            expect(seen.get('titlebar-action')?.length).toBe(0);
+            click(el, { button: 0, detail: 2 });
+            expect(seen.get('titlebar-action')?.length).toBe(1);
+            expect(seen.get('window.toggle-maximized')?.length).toBe(1);
+            const detail = seen.get('titlebar-action')?.[0] as {
+                action: string;
+                gesture: string;
+                windowAction: string;
+            };
+            expect(detail.action).toBe('toggle-maximize');
+            expect(detail.gesture).toBe('double-click');
+            expect(detail.windowAction).toBe('window.toggle-maximized');
+            host.remove();
+        });
+
+        await it('turns a right click into the window menu, as its setting says', async () => {
+            const { el, host } = mount();
+            const seen = record(el, 'window.menu', 'window-move');
+            click(el, { button: 2 });
+            expect(seen.get('window.menu')?.length).toBe(1);
+            host.remove();
+        });
+
+        await it('reads each gesture off its OWN setting default, and refuses a value GTK does not know', async () => {
+            const { el, host } = mount();
+            // The three pspecs are not the same (gtksettings.c:868-896): a middle click does
+            // NOTHING by default, which is the whole point of there being three settings.
+            expect(el.actionFor('double-click')).toBe('toggle-maximize');
+            expect(el.actionFor('middle-click')).toBe('none');
+            expect(el.actionFor('right-click')).toBe('menu');
+            el.setAttribute('double-click-action', 'minimize');
+            expect(el.actionFor('double-click')).toBe('minimize');
+            const seen = record(el, 'window.minimize');
+            click(el, { button: 0, detail: 2 });
+            expect(seen.get('window.minimize')?.length).toBe(1);
+            // An unknown value is `none`, which is the C's own refusal branch — a typo must
+            // not minimize a window.
+            el.setAttribute('double-click-action', 'minimise');
+            expect(el.actionFor('double-click')).toBe('none');
+            const none = record(el, 'window.minimize');
+            click(el, { button: 0, detail: 2 });
+            expect(none.get('window.minimize')?.length).toBe(0);
+            // A maximization VARIANT maximizes: `perform_titlebar_action_fallback` matches
+            // `toggle-maximize` by prefix, "treat all maximization variants the same"
+            // (gtkwindowhandle.c:311-315).
+            el.setAttribute('double-click-action', 'toggle-maximize-fullscreen');
+            expect(el.actionFor('double-click')).toBe('toggle-maximize');
+            host.remove();
+        });
+
+        await it('reports `none` on titlebar-action all the same, which is the gesture itself', async () => {
+            const { el, host } = mount();
+            const seen = record(el, 'titlebar-action', 'window.menu');
+            // A middle click, which is `none` by default (gtksettings.c:881-883) — the gesture
+            // still happened, so it is still reported, and nothing else fires.
+            click(el, { button: 1 });
+            expect(seen.get('titlebar-action')?.length).toBe(1);
+            expect(seen.get('window.menu')?.length).toBe(0);
+            // Taken apart before the property is read: `(x?.[0] as T).gesture` would throw
+            // a TypeError instead of failing the assertion if the array were empty.
+            const middle = seen.get('titlebar-action')?.[0] as { gesture: string } | undefined;
+            expect(middle?.gesture).toBe('middle-click');
+            el.setAttribute('right-click-action', 'none');
+            const right = record(el, 'titlebar-action', 'window.menu');
+            click(el, { button: 2 });
+            expect(right.get('titlebar-action')?.length).toBe(1);
+            expect(right.get('window.menu')?.length).toBe(0);
+            host.remove();
+        });
+    });
+
+    await describe('<gtk-window-handle> the drag', async () => {
+        await it('raises window-move once the pointer passes the drag threshold', async () => {
+            const { el, host } = mount();
+            const seen = record(el, 'window-move');
+            pointer(el, 'pointerdown', { pointerId: 1, clientX: 10, clientY: 20 });
+            // Under the threshold nothing has happened, which is `gtk_drag_check_threshold_double`.
+            pointer(el, 'pointermove', { pointerId: 1, clientX: 10, clientY: 21 });
+            expect(seen.get('window-move')?.length).toBe(0);
+            pointer(el, 'pointermove', { pointerId: 1, clientX: 60, clientY: 20 });
+            expect(seen.get('window-move')?.length).toBe(1);
+            // The sequence is reset afterwards, so the gesture does not repeat.
+            pointer(el, 'pointermove', { pointerId: 1, clientX: 90, clientY: 20 });
+            expect(seen.get('window-move')?.length).toBe(1);
+            host.remove();
+        });
+
+        await it('denies the drag once a multi-click has claimed the sequence', async () => {
+            const { el, host } = mount();
+            const seen = record(el, 'window-move');
+            pointer(el, 'pointerdown', { pointerId: 1, clientX: 10, clientY: 20 });
+            pointer(el, 'pointerdown', { pointerId: 1, clientX: 10, clientY: 20 });
+            // The second press of a double click: the click gesture claims the sequence and
+            // `gtk_event_controller_reset` denies the drag with it (gtkwindowhandle.c:400-406),
+            // which is where a browser knows the press count.
+            click(el, { button: 0, detail: 2 });
+            pointer(el, 'pointermove', { pointerId: 1, clientX: 90, clientY: 20 });
+            expect(seen.get('window-move')?.length).toBe(0);
+            host.remove();
+        });
+    });
+};

package/src/gtk-window.spec.ts

@@ -0,0 +1,202 @@
+// DOM-level tests for <gtk-window>. A window in a page is a FRAME, and this file holds that
+// honest: the two shapes its titlebar strip can be in (the application's `titlebar` slot, or
+// the server-side decoration a page has to draw for itself), the four properties that decide
+// which frame buttons appear, and the two branches of `gtk_window_close`
+// (gtkwindow.c:1274-1287).
+import { describe, expect, it } from '@gjsify/unit';
+
+import type { GtkWindow } from './elements/gtk-window.js';
+
+function mount(attrs: Record<string, string> = {}): { el: GtkWindow; host: HTMLElement } {
+    const host = document.createElement('div');
+    document.body.appendChild(host);
+    const el = document.createElement('gtk-window') as GtkWindow;
+    for (const [name, value] of Object.entries(attrs)) el.setAttribute(name, value);
+    host.appendChild(el);
+    return { el, host };
+}
+
+function content(el: GtkWindow): HTMLElement {
+    return el.querySelector('.adw-gtk-window-content') as HTMLElement;
+}
+
+function titlebar(el: GtkWindow): HTMLElement {
+    return el.querySelector('.adw-gtk-window-titlebar') as HTMLElement;
+}
+
+export const GtkWindowTest = async () => {
+    await describe('<gtk-window> structure', async () => {
+        await it('is a titlebar strip over a content box', async () => {
+            // The two strips `connectedCallback` installs, in `strips()` order.
+            const { el, host } = mount();
+            expect([...el.children].map((node) => node.className)).toStrictEqual([
+                'adw-gtk-window-titlebar',
+                'adw-gtk-window-content',
+            ]);
+            expect(titlebar(el).hidden).toBe(false);
+            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');
+            first.textContent = 'a';
+            const second = document.createElement('span');
+            second.textContent = 'b';
+            el.append(first, second);
+            await Promise.resolve();
+            expect([...content(el).children]).toStrictEqual([first, second]);
+            host.remove();
+        });
+
+        await it('a `titlebar` child takes the whole strip, decorations and all', async () => {
+            // GTK hands the titlebar the window's decorations; a `Gtk.HeaderBar` brings its
+            // own window controls with it.
+            const { el, host } = mount();
+            const bar = document.createElement('gtk-header-bar');
+            // `titlebar` is a PROPERTY on Gtk.Window (gtkwindow.c:1138) and the buildable's
+            // single child is something else, so the slot name is how the markup spells it.
+            bar.setAttribute('slot', 'titlebar');
+            el.appendChild(bar);
+            await Promise.resolve();
+            await Promise.resolve();
+            expect(bar.parentElement).toBe(titlebar(el));
+            // The WINDOW's own two are gone, and the bar brings its own pair instead — which is
+            // what `show-title-buttons` is for (gtkheaderbar.c:198-249).
+            expect([...titlebar(el).children]).toStrictEqual([bar]);
+            expect(el.querySelectorAll('gtk-window-controls').length).toBe(2);
+            host.remove();
+        });
+
+        await it('with no titlebar it draws the SSD a window manager would have', async () => {
+            const { el, host } = mount({ title: 'Documents' });
+            expect([...titlebar(el).children].map((node) => node.localName)).toStrictEqual([
+                'gtk-window-controls',
+                'span',
+                'gtk-window-controls',
+            ]);
+            expect(titlebar(el).querySelector('.adw-gtk-window-title')?.getAttribute('title')).toBe('Documents');
+            host.remove();
+        });
+
+        await it('`decorated="false"` HIDES the strip, frame buttons and all', async () => {
+            // gtk_window_set_decorated (gtkwindow.c:1014) takes the titlebar OUT OF THE FRAME,
+            // which is not the same as discarding it: the window keeps the widget and an
+            // undecorating write puts it back. So the strip is hidden, not emptied.
+            const { el, host } = mount();
+            el.decorated = false;
+            expect(titlebar(el).hidden).toBe(true);
+            expect(el.querySelector('gtk-window-controls')).not.toBe(null);
+            el.decorated = true;
+            expect(titlebar(el).hidden).toBe(false);
+            host.remove();
+        });
+    });
+
+    await describe('<gtk-window> frame properties', async () => {
+        await it('`maximized` and `fullscreened` square the frame off', async () => {
+            // _window.scss:66-72 — the two states with no corners and no shadow.
+            const { el, host } = mount();
+            el.maximized = true;
+            expect(el.classList.contains('maximized')).toBe(true);
+            el.maximized = false;
+            el.setAttribute('fullscreened', '');
+            expect(el.classList.contains('fullscreen')).toBe(true);
+            host.remove();
+        });
+
+        await it('`default-width`/`default-height` size the frame, and an absent one clears it', async () => {
+            const { el, host } = mount({ 'default-width': '480', 'default-height': '320' });
+            expect(el.style.width).toBe('480px');
+            expect(el.style.height).toBe('320px');
+            el.removeAttribute('default-width');
+            expect(el.style.width).toBe('');
+            host.remove();
+        });
+
+        await it("`title` is the window's accessible name", async () => {
+            const { el, host } = mount({ title: 'Documents' });
+            expect(el.getAttribute('aria-label')).toBe('Documents');
+            el.removeAttribute('title');
+            expect(el.hasAttribute('aria-label')).toBe(false);
+            host.remove();
+        });
+
+        await it('the frame buttons follow `deletable` and `resizable`', async () => {
+            // One read each, through the controls the window draws.
+            const { el, host } = mount();
+            el.deletable = false;
+            el.resizable = false;
+            await Promise.resolve();
+            await Promise.resolve();
+            expect(el.querySelector('.adw-window-controls-button.close')).toBe(null);
+            expect(el.querySelector('.adw-window-controls-button.maximize')).toBe(null);
+            expect(el.querySelector('.adw-window-controls-button.minimize')).not.toBe(null);
+            host.remove();
+        });
+
+        await it('the maximize button toggles `maximized` and says so', async () => {
+            const { el, host } = mount();
+            const button = el.querySelector('.adw-window-controls-button.maximize') as HTMLButtonElement;
+            expect(button.getAttribute('aria-label')).toBe('Maximize');
+            button.click();
+            expect(el.maximized).toBe(true);
+            host.remove();
+        });
+
+        await it('notifies once per real change', async () => {
+            const { el, host } = mount();
+            const events: unknown[] = [];
+            el.addEventListener('notify::resizable', (e) => events.push((e as CustomEvent).detail));
+            el.resizable = false;
+            el.resizable = false;
+            expect(events).toStrictEqual([{ resizable: false }]);
+            host.remove();
+        });
+    });
+
+    await describe('<gtk-window> close', async () => {
+        await it("detaches the frame, which is GTK's destroy branch", async () => {
+            // gtkwindow.c:1282-1285 — no hide-on-close, so `gtk_window_destroy`.
+            const { el, host } = mount();
+            let seen = 0;
+            el.addEventListener('close-request', () => {
+                seen += 1;
+            });
+            expect(el.close()).toBe(true);
+            expect(seen).toBe(1);
+            expect(el.isConnected).toBe(false);
+            host.remove();
+        });
+
+        await it('hides the frame when `hide-on-close` is set', async () => {
+            // gtkwindow.c:945 and the first branch of :1282.
+            const { el, host } = mount({ 'hide-on-close': 'true' });
+            el.close();
+            expect(el.isConnected).toBe(true);
+            expect(el.hidden).toBe(true);
+            host.remove();
+        });
+
+        await it('a handler that cancels `close-request` takes the whole thing over', async () => {
+            // gtkwindow.c:1300-1320 — `g_signal_stop_emission_by_name` on the default handler.
+            const { el, host } = mount();
+            el.addEventListener('close-request', (e) => e.preventDefault());
+            expect(el.close()).toBe(false);
+            expect(el.isConnected).toBe(true);
+            host.remove();
+        });
+    });
+};

package/src/index.ts

@@ -81,7 +81,8 @@ 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 } 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
 // ~1.07 MB of data-URI), so a name outside it draws the `image-missing` fallback. This is
@@ -156,6 +157,13 @@ export { AdwViewSwitcherPage } from './elements/adw-view-switcher.js';
 export { AdwViewStackPage } from './elements/adw-inline-view-switcher.js';
 export { AdwSidebarItem, AdwSidebarSection } from './elements/adw-sidebar.js';
 
+// The two halves of a shortcuts dialog, and the same objection the four above state:
+// `AdwShortcutsSection` and `AdwShortcutsItem` descend from `GObject.Object` (they are
+// `add()`ed to a dialog, not packed into one), so there is no GIR name to export them
+// under. `AdwShortcutsDialog` itself IS a widget and has its namespace member.
+export { AdwShortcutsSection } from './elements/adw-shortcuts-section.js';
+export { AdwShortcutsItem } from './elements/adw-shortcuts-item.js';
+
 // Slot wrappers and a declarative response: on GTK these are `set_content()`,
 // `set_sheet()` and `add_response()` — calls, not widgets.
 export { AdwBottomSheetBottomBar, AdwBottomSheetContent, AdwBottomSheetSheet } from './elements/adw-bottom-sheet.js';

package/src/keyboard-operable.spec.ts

@@ -622,18 +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`).
-            expect([...AdwToggle.observedAttributes]).toStrictEqual(['label', 'icon-name']);
+            // `<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` 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 () => {
@@ -895,6 +934,35 @@ export const AdwKeyboardOperableTest = async () => {
             host.remove();
         });
 
+        // `<gtk-editable-label>` is the one GTK widget here whose focus moves WITH its
+        // state: the label is focusable and `editing` hands the focus to the entry
+        // (gtkeditablelabel.c:614,652), so the tab stop has to move with it or a Tab would
+        // reach a control the user cannot see.
+        await it('gtk-editable-label moves its tab stop with its state', () => {
+            const host = mount('<gtk-editable-label id="k-ed" text="Ada"></gtk-editable-label>');
+            const el = document.getElementById('k-ed') as HTMLElement & {
+                entry: HTMLInputElement;
+                startEditing: () => void;
+                stopEditing: (commit?: boolean) => void;
+            };
+
+            expect(el.getAttribute('tabindex')).toBe('0');
+            expect(el.entry.tabIndex).toBe(-1);
+            el.focus();
+            expect(document.activeElement).toBe(el);
+
+            el.startEditing();
+            expect(el.hasAttribute('tabindex')).toBe(false);
+            expect(document.activeElement).toBe(el.entry);
+
+            // …and back: the widget owns the focus once the edit is over, so the next Tab
+            // starts from the label rather than from inside a collapsed edit mode.
+            el.stopEditing(true);
+            expect(el.getAttribute('tabindex')).toBe('0');
+            expect(document.activeElement).toBe(el);
+            host.remove();
+        });
+
         await it('activates on Enter and Space, and lets a child keep its own keys', () => {
             const host = mount(
                 '<adw-action-row id="k-keys" title="Keys" activatable></adw-action-row>' +

package/src/list-view-dom.ts

@@ -0,0 +1,121 @@
+// What `<gtk-list-view>`, `<gtk-grid-view>` and `<gtk-column-view>` share in the DOM —
+// the default factory and the rubber band (ADR 0089).
+//
+// The three views derive from `GtkListBase` upstream and share its item manager, its
+// selection function and its rubberband gesture. The SELECTION half of that is portable
+// and lives in `@gjsify/adwaita-core`'s `ListViewState` (ADR 0004); what is left here is
+// genuinely a DOM job — a pointer drag, a rectangle, and the node a factory builds — and
+// is shared for the reason the second copy always is: three elements writing the same
+// hit test is three places for it to be subtly different.
+//
+// Reference: refs/gtk/gtk/gtklistbase.c (the rubberband gesture and its `rubberband` node)
+// Reference: refs/libadwaita/src/stylesheet/widgets/_views.scss:47-50 (`rubberband`)
+// Copyright (c) GNOME contributors (GTK/libadwaita). LGPLv2.1+.
+
+import type { AdwListItemContext, AdwListItemFactory } from '@gjsify/adwaita-core';
+
+/** The class every row/cell label carries, so one stylesheet rule reaches all three views. */
+export const LIST_ITEM_LABEL_CLASS = 'adw-list-item-label';
+
+/**
+ * What a view draws for an item when no `factory` was set.
+ *
+ * GTK HAS NO DEFAULT FACTORY — `gtk_list_view_new (model, NULL)` is legal and draws empty
+ * rows, which on a documentation surface is indistinguishable from a broken widget. So
+ * the port's default is the factory every upstream example writes by hand: a label bound
+ * to the item. Setting `factory` replaces it, and that is the only way to get GTK's own
+ * answer back.
+ */
+export const defaultListItemFactory: AdwListItemFactory<Node> = (context: AdwListItemContext) => {
+    const label = document.createElement('span');
+    label.className = LIST_ITEM_LABEL_CLASS;
+    label.textContent = context.item.label;
+    return label;
+};
+
+/** What {@link attachRubberBand} needs to know about the view it bands. */
+export interface AdwRubberBandInit {
+    /** The element the pointer listeners sit on. */
+    host: HTMLElement;
+    /** The positioned box the band is drawn inside — the row container. */
+    surface: HTMLElement;
+    /** Whether a drag may start right now: `enable-rubberband` AND a multiple selection. */
+    enabled: () => boolean;
+    /** The row elements, in model order. */
+    rows: () => readonly HTMLElement[];
+    /** Select every position the band covers, replacing the selection. */
+    selectPositions: (positions: readonly number[]) => void;
+}
+
+/**
+ * Rubberband selection — drag on the view's background to select what the rectangle
+ * covers.
+ *
+ * GTK runs this as a drag gesture on `GtkListBase` and draws a `rubberband` CSS node,
+ * which libadwaita styles as an accent border over a 20% accent fill
+ * (`_views.scss:47-50`); this builds the same node and lets that rule reach it.
+ *
+ * THE DRAG MUST START ON THE BACKGROUND. A press that lands on a row is that row's click
+ * — GTK's row gesture claims the sequence — so starting a band there would make every
+ * click a one-pixel drag and swallow the row's own selection step.
+ *
+ * The hit test is `getBoundingClientRect` per row against the band, which is the same
+ * question GTK answers against its tile areas. It is recomputed per pointermove rather
+ * than cached: a row's box can change mid-drag (a scroll, a factory that lays out late),
+ * and a cached rectangle would select the wrong rows without anything looking wrong.
+ */
+export function attachRubberBand(init: AdwRubberBandInit): void {
+    let band: HTMLElement | null = null;
+    let origin: { x: number; y: number } | null = null;
+    let pointerId: number | null = null;
+
+    const stop = () => {
+        band?.remove();
+        band = null;
+        origin = null;
+        if (pointerId !== null && init.host.hasPointerCapture(pointerId)) {
+            init.host.releasePointerCapture(pointerId);
+        }
+        pointerId = null;
+    };
+
+    init.host.addEventListener('pointerdown', (event) => {
+        if (event.button !== 0 || !init.enabled()) return;
+        const target = event.target as Node | null;
+        if (target !== null && init.rows().some((row) => row === target || row.contains(target))) return;
+
+        origin = { x: event.clientX, y: event.clientY };
+        pointerId = event.pointerId;
+        init.host.setPointerCapture(event.pointerId);
+        band = document.createElement('div');
+        band.className = 'adw-rubberband';
+        band.setAttribute('aria-hidden', 'true');
+        init.surface.appendChild(band);
+    });
+
+    init.host.addEventListener('pointermove', (event) => {
+        if (origin === null || band === null) return;
+        const box = init.surface.getBoundingClientRect();
+        const left = Math.min(origin.x, event.clientX);
+        const top = Math.min(origin.y, event.clientY);
+        const width = Math.abs(event.clientX - origin.x);
+        const height = Math.abs(event.clientY - origin.y);
+        band.style.left = `${left - box.left}px`;
+        band.style.top = `${top - box.top}px`;
+        band.style.width = `${width}px`;
+        band.style.height = `${height}px`;
+
+        const covered: number[] = [];
+        init.rows().forEach((row, position) => {
+            const rect = row.getBoundingClientRect();
+            const hit =
+                rect.right >= left && rect.left <= left + width && rect.bottom >= top && rect.top <= top + height;
+            if (hit) covered.push(position);
+        });
+        init.selectPositions(covered);
+    });
+
+    for (const name of ['pointerup', 'pointercancel', 'lostpointercapture']) {
+        init.host.addEventListener(name, stop);
+    }
+}