@gjsify/adwaita-web 0.31.0 → 0.32.0

package/src/adw-icon.spec.ts

@@ -0,0 +1,167 @@
+// DOM-level tests for <adw-icon>, driven by the SAME `normalizeIconName` vectors
+// the core suite asserts against (`@gjsify/adwaita-core/conformance`), plus the
+// REGRESSION PROOF for the drift the element was extracted to close.
+//
+// The drift: `<span class="adw-icon adw-icon--<name>" aria-hidden="true">` was
+// built by hand at twenty-three sites across seventeen files, nine of them
+// re-deriving `name.replace(/-symbolic$/, '')` on the spot. Exactly ONE site —
+// `<adw-split-button>` — also checked the result was a single CSS token. So
+// `icon-name="a b"` interpolated into `class="adw-icon adw-icon--a b"` and shipped
+// a stray `b` class through `<adw-menu-button>`, for its own icon AND for every
+// JSON menu entry's, while the one element that guarded kept passing its spec.
+// The vectors below now run against the ELEMENT, so a renderer that starts
+// building the class by hand again fails naming the input.
+import { describe, expect, it } from '@gjsify/unit';
+
+import { VIEW_STACK_ICON_NAME_VECTORS } from '@gjsify/adwaita-core/conformance';
+
+import type { AdwIcon } from './elements/adw-icon.js';
+import type { AdwMenuButton } from './elements/adw-menu-button.js';
+
+function mount<T extends HTMLElement>(tag: string): { el: T; host: HTMLElement } {
+    const host = document.createElement('div');
+    document.body.appendChild(host);
+    const el = document.createElement(tag) as T;
+    host.appendChild(el);
+    return { el, host };
+}
+
+/** Every class on the node that is not the base `.adw-icon`. */
+function extraClasses(el: HTMLElement): string[] {
+    return [...el.classList].filter((c) => c !== 'adw-icon').sort();
+}
+
+export const AdwIconTest = async () => {
+    await describe('<adw-icon> mask class (normalizeIconName vectors)', async () => {
+        for (const { icon, normalized, rule } of VIEW_STACK_ICON_NAME_VECTORS) {
+            await it(`${JSON.stringify(icon)} → ${JSON.stringify(normalized)} — ${rule}`, () => {
+                const { el, host } = mount<AdwIcon>('adw-icon');
+                el.iconName = icon ?? null;
+
+                expect(el.resolvedIconName).toBe(normalized);
+                // The base class is unconditional — a nameless icon is still an
+                // icon box, which is what `<adw-status-page>` hides rather than
+                // omits.
+                expect(el.classList.contains('adw-icon')).toBe(true);
+                // …and NOTHING else is on the node. This is the assertion the
+                // hand-rolled copies could not make: `icon-name="a b"` used to
+                // leave a stray `b` here.
+                expect(extraClasses(el)).toStrictEqual(normalized === '' ? [] : [`adw-icon--${normalized}`]);
+                host.remove();
+            });
+        }
+    });
+
+    await describe('<adw-icon> node contract', async () => {
+        await it('is decorative — the accessible name belongs to the host control', () => {
+            const { el, host } = mount<AdwIcon>('adw-icon');
+            expect(el.getAttribute('aria-hidden')).toBe('true');
+            host.remove();
+        });
+
+        await it('swaps ONLY the mask class, keeping the caller position classes', () => {
+            const { el, host } = mount<AdwIcon>('adw-icon');
+            el.classList.add('adw-drop-down-arrow', 'start');
+            el.iconName = 'go-down';
+            expect(extraClasses(el)).toStrictEqual(['adw-drop-down-arrow', 'adw-icon--go-down', 'start']);
+
+            el.iconName = 'go-next';
+            // Exactly one mask class at a time, and the caller's are untouched —
+            // a `className =` assignment would have taken them with it.
+            expect(extraClasses(el)).toStrictEqual(['adw-drop-down-arrow', 'adw-icon--go-next', 'start']);
+
+            el.iconName = null;
+            expect(extraClasses(el)).toStrictEqual(['adw-drop-down-arrow', 'start']);
+            host.remove();
+        });
+
+        await it('sizes the box AND the mask together', () => {
+            const { el, host } = mount<AdwIcon>('adw-icon');
+            el.iconName = 'go-next';
+            // Unset: the stylesheet's 16px.
+            expect(el.size).toBe(null);
+            expect(getComputedStyle(el).width).toBe('16px');
+
+            el.size = 32;
+            const styled = getComputedStyle(el);
+            expect(styled.width).toBe('32px');
+            expect(styled.height).toBe('32px');
+            // Sizing only the box would leave a 16px glyph floating in it. Only
+            // the axis we set is asserted: `mask-size: 32px` means "32px wide,
+            // height from the aspect ratio", and the CSSOM re-serializes the
+            // omitted half (Firefox reports `32px auto`, in the inline style too).
+            expect(styled.maskSize.split(' ')[0]).toBe('32px');
+            expect(styled.webkitMaskSize.split(' ')[0]).toBe('32px');
+
+            el.size = null;
+            expect(getComputedStyle(el).width).toBe('16px');
+            host.remove();
+        });
+
+        await it('paints in the INHERITED colour, not the boundary reset colour', () => {
+            // `.adw-icon` masks with `currentColor`, and <adw-icon> is a custom
+            // element — so the ADR-0010 `$adw-components` reset re-roots `color`
+            // on it. Without `color: inherit` in `_icon.scss` every icon would
+            // repaint in `--window-fg-color` regardless of the button it sits in.
+            const { el: box, host } = mount<HTMLElement>('div');
+            box.style.color = 'rgb(255, 0, 0)';
+            const icon = document.createElement('adw-icon') as AdwIcon;
+            icon.iconName = 'go-next';
+            box.appendChild(icon);
+            expect(getComputedStyle(icon).backgroundColor).toBe('rgb(255, 0, 0)');
+            host.remove();
+        });
+    });
+
+    await describe('the hand-rolled copies are gone', async () => {
+        await it('<adw-menu-button> no longer injects a stray class from its icon-name', () => {
+            const { el, host } = mount<AdwMenuButton>('adw-menu-button');
+            el.setAttribute('icon-name', 'a b');
+            const icon = el.querySelector('.adw-icon') as HTMLElement;
+            // `adw-icon--a b` would have added a second, unrelated `b` class.
+            expect(extraClasses(icon)).toStrictEqual(['adw-menu-button-icon']);
+            host.remove();
+        });
+
+        await it('<adw-menu-button> menu entries guard their icons too', () => {
+            const { el, host } = mount<AdwMenuButton>('adw-menu-button');
+            el.menuItems = [
+                { label: 'Bad', icon: 'a b' },
+                { label: 'Good', icon: 'view-refresh-symbolic' },
+                { label: 'None' },
+            ];
+            const items = [...el.querySelectorAll('.adw-menu-button-item')];
+            expect(items.length).toBe(3);
+            // An unusable name draws nothing rather than injecting markup, and
+            // an entry with no icon still gets no icon node at all.
+            expect(items[0].querySelector('.adw-icon')).toBe(null);
+            expect(items[2].querySelector('.adw-icon')).toBe(null);
+            const good = items[1].querySelector('.adw-icon') as HTMLElement;
+            expect(extraClasses(good)).toStrictEqual(['adw-icon--view-refresh', 'adw-menu-button-item-icon']);
+            host.remove();
+        });
+
+        await it('every icon in the package is an <adw-icon>', () => {
+            // The point of the extraction, asserted structurally: build a page of
+            // the widgets that draw icons and check no bare span carries the
+            // base class. A new hand-rolled `<span class="adw-icon …">` fails
+            // here even if it happens to guard its own name correctly.
+            const { el: page, host } = mount<HTMLElement>('div');
+            page.innerHTML = `
+                <adw-button icon="go-next" label="Next"></adw-button>
+                <adw-button-row title="Row" start-icon-name="list-add" end-icon-name="go-next"></adw-button-row>
+                <adw-status-page icon="folder" title="Empty"></adw-status-page>
+                <adw-split-button label="Save" menu='[{"label":"Save As"}]'></adw-split-button>
+                <adw-drop-down options='["a","b"]'></adw-drop-down>
+                <adw-expander-row title="More" show-enable-switch></adw-expander-row>
+                <adw-avatar text="Ada" icon="avatar-default"></adw-avatar>
+                <adw-toggle-group><adw-toggle icon-name="view-list"></adw-toggle></adw-toggle-group>
+            `;
+            const bareSpans = [...host.querySelectorAll('span.adw-icon')];
+            expect(bareSpans.length).toBe(0);
+            // …and the icons really are there, so the check is not vacuous.
+            expect(host.querySelectorAll('adw-icon.adw-icon').length > 5).toBe(true);
+            host.remove();
+        });
+    });
+};

package/src/adw-progress-bar.spec.ts

@@ -0,0 +1,173 @@
+// DOM-level tests for <adw-progress-bar>.
+//
+// Three things here are worth more than the attribute round-trips: the CLAMP is
+// GLib's (`glibClamp`, shared from `@gjsify/adwaita-core`, not a local
+// `Math.min/max`), the ZERO fraction has to make the indicator VANISH rather
+// than draw a rounded stub (`> trough.empty > progress { all: unset }`,
+// _progress-bar.scss:85), and the text node has to actually PICK UP `.dimmed` +
+// `.numeric` from `_labels.scss` — that composition is the reason those classes
+// exist, and a `@extend` that silently reached nothing would look identical in
+// the source.
+
+import { describe, expect, it } from '@gjsify/unit';
+
+import type { AdwProgressBar } from './elements/adw-progress-bar.js';
+
+function mount(): { el: AdwProgressBar; host: HTMLElement } {
+    const host = document.createElement('div');
+    document.body.appendChild(host);
+    const el = document.createElement('adw-progress-bar') as AdwProgressBar;
+    host.appendChild(el);
+    return { el, host };
+}
+
+/** The parts, by the markup contract the stylesheet selects on. */
+function parts(bar: AdwProgressBar): { trough: HTMLElement; progress: HTMLElement; text: HTMLElement } {
+    return {
+        trough: bar.querySelector('.adw-progress-bar-trough') as HTMLElement,
+        progress: bar.querySelector('.adw-progress-bar-progress') as HTMLElement,
+        text: bar.querySelector('.adw-progress-bar-text') as HTMLElement,
+    };
+}
+
+export const AdwProgressBarTest = async () => {
+    await describe('<adw-progress-bar> fraction', async () => {
+        await it('starts empty, with the trough flagged so the indicator disappears', () => {
+            const { el, host } = mount();
+            const { trough, progress } = parts(el);
+            expect(el.fraction).toBe(0);
+            expect(trough).toBeTruthy();
+            expect(progress).toBeTruthy();
+            expect(trough.classList.contains('empty')).toBe(true);
+            expect(el.getAttribute('role')).toBe('progressbar');
+            expect(el.getAttribute('aria-valuenow')).toBe('0');
+            host.remove();
+        });
+
+        await it('fills to the fraction and drops the empty flag', () => {
+            const { el, host } = mount();
+            el.fraction = 0.25;
+            const { trough, progress } = parts(el);
+            expect(trough.classList.contains('empty')).toBe(false);
+            expect(progress.style.width).toBe('25%');
+            expect(el.getAttribute('aria-valuenow')).toBe('0.25');
+            host.remove();
+        });
+
+        await it('clamps out-of-range and unusable fractions', () => {
+            const { el, host } = mount();
+            el.fraction = 1.5;
+            expect(el.fraction).toBe(1);
+            expect(parts(el).progress.style.width).toBe('100%');
+            el.fraction = -3;
+            expect(el.fraction).toBe(0);
+            // A garbage attribute is GtkProgressBar's default 0, never NaN —
+            // NaN would reach both the width and `aria-valuenow`.
+            el.setAttribute('fraction', 'later');
+            expect(el.fraction).toBe(0);
+            expect(el.getAttribute('aria-valuenow')).toBe('0');
+            host.remove();
+        });
+    });
+
+    await describe('<adw-progress-bar> indeterminate', async () => {
+        await it('pulse() enters the pulsing state and drops aria-valuenow', () => {
+            const { el, host } = mount();
+            el.fraction = 0.4;
+            expect(el.getAttribute('aria-valuenow')).toBe('0.4');
+
+            el.pulse();
+
+            expect(el.pulsing).toBe(true);
+            expect(el.hasAttribute('pulsing')).toBe(true);
+            // ARIA spells "indeterminate" as an ABSENT valuenow; a stale 0.4
+            // would be announced as real progress.
+            expect(el.hasAttribute('aria-valuenow')).toBe(false);
+            // A pulsing bar is never `.empty` — the bouncing block is what says
+            // "working", so it must not be unset away.
+            expect(parts(el).trough.classList.contains('empty')).toBe(false);
+            host.remove();
+        });
+
+        await it('leaving the pulsing state restores the determinate value', () => {
+            const { el, host } = mount();
+            el.fraction = 0;
+            el.pulse();
+            el.pulsing = false;
+            expect(el.getAttribute('aria-valuenow')).toBe('0');
+            expect(parts(el).trough.classList.contains('empty')).toBe(true);
+            host.remove();
+        });
+    });
+
+    await describe('<adw-progress-bar> text', async () => {
+        await it('hides the text node until show-text, then shows the percentage', () => {
+            const { el, host } = mount();
+            expect(parts(el).text.hidden).toBe(true);
+
+            el.fraction = 0.42;
+            el.showText = true;
+
+            expect(parts(el).text.hidden).toBe(false);
+            expect(parts(el).text.textContent).toBe('42%');
+            host.remove();
+        });
+
+        await it('an explicit text wins over the percentage', () => {
+            const { el, host } = mount();
+            el.showText = true;
+            el.fraction = 0.5;
+            el.text = 'Copying 3 of 6';
+            expect(el.text).toBe('Copying 3 of 6');
+            expect(parts(el).text.textContent).toBe('Copying 3 of 6');
+            host.remove();
+        });
+
+        await it('the text node composes .dimmed and .numeric from _labels.scss', () => {
+            // `> text { @extend .dimmed; @extend .numeric; }`
+            // (_progress-bar.scss:17-21) — this asserts the extends actually
+            // REACHED the utility classes, which a source read cannot tell.
+            const { el, host } = mount();
+            el.showText = true;
+            const style = getComputedStyle(parts(el).text);
+            expect(style.getPropertyValue('font-variant-numeric')).toBe('tabular-nums');
+            expect(Number.parseFloat(style.opacity)).toBeLessThan(1);
+            host.remove();
+        });
+    });
+
+    await describe('<adw-progress-bar> variants', async () => {
+        await it('is an 8px trough by default and a 2px hairline with osd', () => {
+            // The 8px is libadwaita's (_progress-bar.scss:6) and the 2px is its
+            // `.osd` variant (:59-83) — NOT the vendored web port's 6px, which
+            // has no OSD variant at all.
+            //
+            // TWO bars rather than one flipped in place, on purpose: the trough
+            // TRANSITIONS `background`, so a computed read taken right after an
+            // attribute flip returns the INTERPOLATED colour — i.e. still the
+            // old one — and the assertion would be timing-dependent. Setting the
+            // state before the element's first style resolution leaves no
+            // transition to be part-way through.
+            const host = document.createElement('div');
+            document.body.appendChild(host);
+            const plain = document.createElement('adw-progress-bar') as AdwProgressBar;
+            const osd = document.createElement('adw-progress-bar') as AdwProgressBar;
+            osd.setAttribute('osd', '');
+            host.append(plain, osd);
+
+            expect(getComputedStyle(parts(plain).trough).height).toBe('8px');
+            const osdTrough = getComputedStyle(parts(osd).trough);
+            expect(osdTrough.height).toBe('2px');
+            expect(osdTrough.backgroundColor).toBe('rgba(0, 0, 0, 0)');
+            host.remove();
+        });
+
+        await it('inverted fills from the far end', () => {
+            const { el, host } = mount();
+            expect(getComputedStyle(parts(el).trough).justifyContent).toBe('normal');
+            el.inverted = true;
+            expect(getComputedStyle(parts(el).trough).justifyContent).toBe('flex-end');
+            host.remove();
+        });
+    });
+};

package/src/adw-sidebar.spec.ts

@@ -0,0 +1,332 @@
+// DOM-level conformance tests for <adw-sidebar>, driven by the SAME vectors the
+// NativeScript renderer asserts against (`@gjsify/adwaita-core/conformance`).
+//
+// The two renderers used to carry independent selection logic, and it had
+// drifted apart AND away from libadwaita: `selected = 5` on a 3-item sidebar
+// gave "no selection" in GTK, `2` here (it clamped to the last row) and `0` on
+// NativeScript (it dropped the write). This element also keyed section headers
+// off the DECLARATION index, so an empty leading section drew a stray separator
+// and cost the next section its `.first` flush-to-top padding. Nothing failed,
+// because nothing compared them. This suite is that comparison.
+import { describe, expect, it } from '@gjsify/unit';
+
+import type { AdwSidebarItemSpec, AdwSidebarSectionSpec } from '@gjsify/adwaita-core';
+import {
+    SIDEBAR_ACTIVATION_VECTORS,
+    SIDEBAR_CLAMP_VECTORS,
+    SIDEBAR_FILTER_VECTORS,
+    SIDEBAR_ITEM_FLAG_VECTORS,
+    SIDEBAR_MODEL_VECTORS,
+    SIDEBAR_MODE_VECTORS,
+} from '@gjsify/adwaita-core/conformance';
+import type { AdwSidebar } from './elements/adw-sidebar.js';
+
+/**
+ * Mount a sidebar built from DECLARED children, the way an author writes it —
+ * the element consumes them at connect time, so they all have to exist before
+ * the host is appended.
+ */
+function mountSidebar(
+    sections: ReadonlyArray<AdwSidebarSectionSpec>,
+    attributes: { mode?: string; selected?: string } = {},
+): { sidebar: AdwSidebar; host: HTMLElement } {
+    const host = document.createElement('div');
+    document.body.appendChild(host);
+
+    const sidebar = document.createElement('adw-sidebar') as AdwSidebar;
+    if (attributes.mode !== undefined) sidebar.setAttribute('mode', attributes.mode);
+    if (attributes.selected !== undefined) sidebar.setAttribute('selected', attributes.selected);
+
+    for (const section of sections) {
+        const sectionEl = document.createElement('adw-sidebar-section');
+        if (section.title !== undefined) sectionEl.setAttribute('title', section.title);
+
+        for (const item of section.items) {
+            sectionEl.appendChild(createItem(item));
+        }
+        sidebar.appendChild(sectionEl);
+    }
+
+    host.appendChild(sidebar);
+    return { sidebar, host };
+}
+
+function createItem(item: AdwSidebarItemSpec): HTMLElement {
+    const el = document.createElement('adw-sidebar-item');
+    el.setAttribute('title', item.title);
+    if (item.subtitle !== undefined) el.setAttribute('subtitle', item.subtitle);
+    if (item.iconName !== undefined) el.setAttribute('icon-name', item.iconName);
+    if (item.enabled === false) el.setAttribute('disabled', '');
+    if (item.visible === false) el.setAttribute('hidden', '');
+    return el;
+}
+
+/** The rendered rows, in render order. */
+function rowsOf(sidebar: AdwSidebar): HTMLButtonElement[] {
+    return Array.from(sidebar.querySelectorAll('.adw-sidebar-item')) as HTMLButtonElement[];
+}
+
+/** The rendered headers, reduced to the three things the C source derives. */
+function headersOf(sidebar: AdwSidebar): { kind: string; title: string; first: boolean }[] {
+    return Array.from(sidebar.querySelectorAll('.adw-sidebar-section-header')).map((el) => ({
+        kind: el.classList.contains('has-title') ? 'title' : 'separator',
+        title: el.querySelector('.adw-sidebar-section-heading')?.textContent ?? '',
+        first: el.classList.contains('first'),
+    }));
+}
+
+/** A sidebar of `count` plain rows — the shape the clamp vectors are stated over. */
+function countedSections(count: number): AdwSidebarSectionSpec[] {
+    if (count === 0) return [];
+    return [{ items: Array.from({ length: count }, (_, i) => ({ title: `Item ${i}` })) }];
+}
+
+export const AdwSidebarTest = async () => {
+    await describe('adw-sidebar selection bounds (libadwaita conformance vectors)', async () => {
+        for (const { index, count, selected, rule } of SIDEBAR_CLAMP_VECTORS) {
+            await it(`selected="${index}" on ${count} rows → ${selected} — ${rule}`, () => {
+                const { sidebar, host } = mountSidebar(countedSections(count), { selected: String(index) });
+
+                expect(sidebar.selected).toBe(selected);
+                // The attribute is normalised back, so it never claims an index
+                // the property does not report.
+                expect(sidebar.getAttribute('selected')).toBe(String(selected));
+                expect(rowsOf(sidebar).filter((row) => row.classList.contains('selected'))).toHaveLength(
+                    selected === -1 ? 0 : 1,
+                );
+
+                host.remove();
+            });
+        }
+
+        await it('auto-selects the first row when no index is declared', () => {
+            const { sidebar, host } = mountSidebar(countedSections(3));
+            expect(sidebar.selected).toBe(0);
+            expect(rowsOf(sidebar)[0]!.classList.contains('selected')).toBe(true);
+            host.remove();
+        });
+
+        await it('notifies on a programmatic change, not only on a click', () => {
+            const { sidebar, host } = mountSidebar(countedSections(3));
+            const seen: { selected: number; interactive: boolean }[] = [];
+            sidebar.addEventListener('notify::selected', (event) => {
+                seen.push((event as CustomEvent).detail as { selected: number; interactive: boolean });
+            });
+
+            sidebar.selected = 2;
+            expect(seen).toHaveLength(1);
+            expect(seen[0]!.selected).toBe(2);
+            expect(seen[0]!.interactive).toBe(false);
+
+            host.remove();
+        });
+    });
+
+    await describe('adw-sidebar rows + headers (libadwaita conformance vectors)', async () => {
+        for (const vector of SIDEBAR_MODEL_VECTORS) {
+            await it(`${vector.name} — ${vector.rule}`, () => {
+                const { sidebar, host } = mountSidebar(vector.sections);
+
+                expect(rowsOf(sidebar)).toHaveLength(vector.count);
+                expect(
+                    rowsOf(sidebar).map((row) => row.querySelector('.adw-sidebar-item-title')?.textContent ?? ''),
+                ).toStrictEqual(vector.flat.map((entry) => entry.title));
+                expect(headersOf(sidebar)).toStrictEqual(
+                    vector.headers.map((header) => ({
+                        kind: header.kind as string,
+                        title: header.title,
+                        first: header.first,
+                    })),
+                );
+
+                host.remove();
+            });
+        }
+
+        await it('draws no section container for a section that renders no rows', () => {
+            // The old element appended a header AND an empty `.adw-sidebar-section`
+            // per DECLARED section, which in page mode is a visible empty card.
+            const { sidebar, host } = mountSidebar([{ title: 'Empty', items: [] }, { items: [{ title: 'A' }] }]);
+            expect(sidebar.querySelectorAll('.adw-sidebar-section')).toHaveLength(1);
+            expect(headersOf(sidebar)).toHaveLength(0);
+            host.remove();
+        });
+    });
+
+    await describe('adw-sidebar item labels (string_is_not_empty bindings)', async () => {
+        for (const vector of SIDEBAR_ITEM_FLAG_VECTORS) {
+            await it(`${JSON.stringify(vector.item)} — ${vector.rule}`, () => {
+                const { sidebar, host } = mountSidebar([{ items: [vector.item] }]);
+                const row = rowsOf(sidebar)[0]!;
+
+                expect((row.querySelector('.adw-sidebar-item-title') as HTMLElement).hidden).toBe(!vector.titleVisible);
+                expect((row.querySelector('.adw-sidebar-item-subtitle') as HTMLElement).hidden).toBe(
+                    !vector.subtitleVisible,
+                );
+                expect((row.querySelector('.adw-sidebar-item-icon') as HTMLElement).hidden).toBe(!vector.iconVisible);
+
+                host.remove();
+            });
+        }
+    });
+
+    await describe('adw-sidebar activation (row-selected then row-activated)', async () => {
+        for (const vector of SIDEBAR_ACTIVATION_VECTORS) {
+            await it(`${vector.name} — ${vector.rule}`, () => {
+                const { sidebar, host } = mountSidebar(vector.sections);
+                sidebar.selected = vector.initialSelected;
+
+                const activations: number[] = [];
+                const notifications: number[] = [];
+                sidebar.addEventListener('activated', (event) => {
+                    activations.push(((event as CustomEvent).detail as { index: number }).index);
+                });
+                sidebar.addEventListener('notify::selected', (event) => {
+                    notifications.push(((event as CustomEvent).detail as { selected: number }).selected);
+                });
+
+                const row = rowsOf(sidebar)[vector.activate];
+                if (row) row.click();
+                else expect(vector.activated).toBe(false);
+
+                expect(activations).toHaveLength(vector.activated ? 1 : 0);
+                expect(notifications).toHaveLength(vector.selectionChanged ? 1 : 0);
+                expect(sidebar.selected).toBe(vector.selected);
+
+                host.remove();
+            });
+        }
+
+        await it('re-clicking the selected row still fires activated — the split-view reveal', () => {
+            const { sidebar, host } = mountSidebar([{ items: [{ title: 'A' }, { title: 'B' }] }]);
+            const activations: number[] = [];
+            sidebar.addEventListener('activated', () => activations.push(1));
+
+            rowsOf(sidebar)[0]!.click();
+            rowsOf(sidebar)[0]!.click();
+            expect(activations).toHaveLength(2);
+            expect(sidebar.selected).toBe(0);
+
+            host.remove();
+        });
+
+        await it('tags a click as interactive and a property write as not', () => {
+            const { sidebar, host } = mountSidebar([{ items: [{ title: 'A' }, { title: 'B' }] }]);
+            const flags: boolean[] = [];
+            sidebar.addEventListener('notify::selected', (event) => {
+                flags.push(((event as CustomEvent).detail as { interactive: boolean }).interactive);
+            });
+
+            rowsOf(sidebar)[1]!.click();
+            sidebar.selected = 0;
+            expect(flags).toStrictEqual([true, false]);
+
+            host.remove();
+        });
+    });
+
+    await describe('adw-sidebar filter + empty state (Adw.Sidebar:filter / update_placeholder)', async () => {
+        for (const vector of SIDEBAR_FILTER_VECTORS) {
+            await it(`${vector.name} — ${vector.rule}`, () => {
+                const { sidebar, host } = mountSidebar(vector.sections);
+                sidebar.filter = (item) => vector.keepTitles.includes(item.title);
+
+                expect(rowsOf(sidebar)).toHaveLength(vector.visibleIndices.length);
+                expect(headersOf(sidebar)).toStrictEqual(
+                    vector.headers.map((header) => ({
+                        kind: header.kind as string,
+                        title: header.title,
+                        first: header.first,
+                    })),
+                );
+                expect(sidebar.classList.contains('empty')).toBe(vector.isEmpty);
+
+                host.remove();
+            });
+        }
+
+        await it('keeps the selection index in the UNFILTERED space', () => {
+            const { sidebar, host } = mountSidebar([{ items: [{ title: 'A' }, { title: 'B' }, { title: 'C' }] }]);
+            sidebar.selected = 2;
+            sidebar.filter = (item) => item.title !== 'A';
+
+            expect(sidebar.selected).toBe(2);
+            expect(sidebar.selectedItem?.title).toBe('C');
+            expect(rowsOf(sidebar)).toHaveLength(2);
+            expect(rowsOf(sidebar)[1]!.classList.contains('selected')).toBe(true);
+
+            host.remove();
+        });
+    });
+
+    await describe('adw-sidebar mode (adw_sidebar_set_mode)', async () => {
+        for (const { mode, selectionVisible, rule } of SIDEBAR_MODE_VECTORS) {
+            await it(`${mode} paints the selection: ${selectionVisible} — ${rule}`, () => {
+                const { sidebar, host } = mountSidebar(countedSections(3), { mode, selected: '1' });
+
+                expect(sidebar.mode).toBe(mode);
+                expect(sidebar.selected).toBe(1);
+                expect(rowsOf(sidebar)[1]!.classList.contains('selected')).toBe(selectionVisible);
+                // Tracked either way — aria still reports which item is current.
+                expect(rowsOf(sidebar)[1]!.getAttribute('aria-selected')).toBe('true');
+
+                host.remove();
+            });
+        }
+
+        await it('keeps the selection across a mode switch and back', () => {
+            const { sidebar, host } = mountSidebar(countedSections(3), { selected: '2' });
+
+            sidebar.mode = 'page';
+            expect(sidebar.selected).toBe(2);
+            expect(rowsOf(sidebar)[2]!.classList.contains('selected')).toBe(false);
+
+            sidebar.mode = 'sidebar';
+            expect(sidebar.selected).toBe(2);
+            expect(rowsOf(sidebar)[2]!.classList.contains('selected')).toBe(true);
+
+            host.remove();
+        });
+    });
+
+    await describe('adw-sidebar live model changes', async () => {
+        await it('rebuilds when the sections are replaced, re-running the 0 → n auto-select', () => {
+            const { sidebar, host } = mountSidebar([{ items: [{ title: 'A' }, { title: 'B' }] }]);
+            sidebar.selected = 1;
+
+            sidebar.sections = [{ title: 'New', items: [{ title: 'X' }, { title: 'Y' }, { title: 'Z' }] }];
+            expect(rowsOf(sidebar)).toHaveLength(3);
+            expect(sidebar.selected).toBe(0);
+            expect(headersOf(sidebar)).toStrictEqual([{ kind: 'title', title: 'New', first: true }]);
+
+            host.remove();
+        });
+
+        await it('follows a declared item attribute change without touching the selection', () => {
+            // <adw-sidebar-item> declared `observedAttributes` with no
+            // attributeChangedCallback behind it, so every post-construction
+            // change was silently lost. The declared element is detached once
+            // consumed, so the link back to its spec cannot be a DOM lookup.
+            const declared = createItem({ title: 'A' });
+            const sectionEl = document.createElement('adw-sidebar-section');
+            sectionEl.append(declared, createItem({ title: 'B' }));
+
+            const host = document.createElement('div');
+            document.body.appendChild(host);
+            const sidebar = document.createElement('adw-sidebar') as AdwSidebar;
+            sidebar.appendChild(sectionEl);
+            host.appendChild(sidebar);
+
+            sidebar.selected = 1;
+            declared.setAttribute('title', 'Renamed');
+            declared.setAttribute('icon-name', 'folder-symbolic');
+
+            const row = rowsOf(sidebar)[0]!;
+            expect(row.querySelector('.adw-sidebar-item-title')?.textContent).toBe('Renamed');
+            expect((row.querySelector('.adw-sidebar-item-icon') as HTMLElement).hidden).toBe(false);
+            expect(sidebar.selected).toBe(1);
+
+            host.remove();
+        });
+    });
+};