@gjsify/adwaita-web 0.31.0 → 0.32.0

package/src/adw-checks.spec.ts

@@ -0,0 +1,368 @@
+// DOM-level tests for <adw-checkbox> and <adw-radio>, plus the browser side of
+// the `RADIO_GROUP_VECTORS` conformance table.
+//
+// THE ONE CLAIM WORTH THE MOST HERE: the browser's native radio exclusivity is
+// NOT enough. `<input type="radio" name="g">` unchecks its sibling INPUT and
+// stops there — the sibling `<adw-radio>` HOST keeps its `checked` attribute,
+// which is the element's published state AND the selector `_checks.scss` paints
+// from, so a group left to the browser draws two selected radios. Every vector
+// below reads back the HOST attribute of every member for exactly that reason.
+//
+// The vectors run under a per-scenario group-name prefix: `RadioGroupState` is
+// document-global by design (as a bare `<input type=radio name=x>` outside a
+// form is), so two scenarios sharing the literal name `colour` would share a
+// selection. The prefix is the isolation, not a change to what is being tested.
+
+import { describe, expect, it } from '@gjsify/unit';
+import { RADIO_GROUP_VECTORS } from '@gjsify/adwaita-core/conformance';
+
+import type { AdwCheckbox, AdwRadio } from './elements/adw-checks.js';
+
+function host(): HTMLElement {
+    const el = document.createElement('div');
+    document.body.appendChild(el);
+    return el;
+}
+
+function mountCheckbox(): { el: AdwCheckbox; parent: HTMLElement } {
+    const parent = host();
+    const el = document.createElement('adw-checkbox') as AdwCheckbox;
+    parent.appendChild(el);
+    return { el, parent };
+}
+
+/** The parts, by the markup contract the stylesheet selects on. */
+function parts(check: HTMLElement): { input: HTMLInputElement; indicator: HTMLElement; label: HTMLElement } {
+    return {
+        input: check.querySelector('input.adw-check-input') as HTMLInputElement,
+        indicator: check.querySelector('.adw-check-indicator') as HTMLElement,
+        label: check.querySelector('.adw-check-label') as HTMLElement,
+    };
+}
+
+/** Collect the `detail` of every `event` bubbling to `el`. */
+function record(el: HTMLElement, event: string): unknown[] {
+    const details: unknown[] = [];
+    el.addEventListener(event, (e) => details.push((e as CustomEvent).detail));
+    return details;
+}
+
+/** The glyph the indicator's mask is currently painting. */
+function glyph(check: HTMLElement): string {
+    return getComputedStyle(parts(check).indicator, '::after').getPropertyValue('mask-image');
+}
+
+export const AdwChecksTest = async () => {
+    await describe('<adw-checkbox> state', async () => {
+        await it('builds the input + indicator + label markup', () => {
+            const { el, parent } = mountCheckbox();
+            const { input, indicator, label } = parts(el);
+            expect(input).toBeTruthy();
+            expect(input.type).toBe('checkbox');
+            expect(indicator).toBeTruthy();
+            // The focus ring is `input:focus-visible ~ .adw-check-indicator`, so
+            // the input MUST precede the indicator.
+            expect(input.nextElementSibling).toBe(indicator);
+            expect(el.checked).toBe(false);
+            expect(input.getAttribute('aria-checked')).toBe('false');
+            // An empty label takes no space.
+            expect(label.hidden).toBe(true);
+            parent.remove();
+        });
+
+        await it('adopts authored child nodes as the label, and the attribute wins', () => {
+            const parent = host();
+            const authored = document.createElement('adw-checkbox') as AdwCheckbox;
+            authored.textContent = 'Enable';
+            parent.appendChild(authored);
+            expect(parts(authored).label.textContent).toBe('Enable');
+            expect(parts(authored).label.hidden).toBe(false);
+
+            const labelled = document.createElement('adw-checkbox') as AdwCheckbox;
+            labelled.setAttribute('label', 'From the attribute');
+            labelled.textContent = 'ignored';
+            parent.appendChild(labelled);
+            expect(parts(labelled).label.textContent).toBe('From the attribute');
+            parent.remove();
+        });
+
+        await it('a programmatic set notifies, and re-setting the same value does not', () => {
+            const { el, parent } = mountCheckbox();
+            const events = record(el, 'notify::checked');
+            el.checked = true;
+            expect(events).toStrictEqual([{ checked: true }]);
+            expect(parts(el).input.checked).toBe(true);
+            el.checked = true;
+            expect(events.length).toBe(1);
+            el.checked = false;
+            expect(events.length).toBe(2);
+            parent.remove();
+        });
+
+        await it('a click toggles exactly once', () => {
+            const { el, parent } = mountCheckbox();
+            const events = record(el, 'notify::checked');
+            el.click();
+            expect(el.checked).toBe(true);
+            expect(el.hasAttribute('checked')).toBe(true);
+            expect(events.length).toBe(1);
+            parent.remove();
+        });
+
+        await it('a click on the hidden input toggles exactly once', () => {
+            // The input is 0x0 so a pointer never reaches it, but keyboard
+            // activation and `input.click()` do — and the host listener must not
+            // toggle a second time on the way out.
+            const { el, parent } = mountCheckbox();
+            const events = record(el, 'notify::checked');
+            parts(el).input.click();
+            expect(el.checked).toBe(true);
+            expect(events.length).toBe(1);
+            parent.remove();
+        });
+
+        await it('a disabled checkbox does not toggle on a click', () => {
+            const { el, parent } = mountCheckbox();
+            el.disabled = true;
+            const events = record(el, 'notify::checked');
+            el.click();
+            expect(el.checked).toBe(false);
+            expect(events.length).toBe(0);
+            expect(parts(el).input.disabled).toBe(true);
+            // …but it is not frozen: a programmatic set still applies, matching
+            // GObject property semantics (sensitivity gates INPUT, not value).
+            el.checked = true;
+            expect(events).toStrictEqual([{ checked: true }]);
+            parent.remove();
+        });
+    });
+
+    await describe('<adw-checkbox> indeterminate', async () => {
+        await it('announces as mixed and outranks checked', () => {
+            const { el, parent } = mountCheckbox();
+            el.checked = true;
+            el.indeterminate = true;
+            const { input } = parts(el);
+            // HTML has a native mixed CHECKBOX, and an explicit aria-checked so
+            // the radio (which has no native mixed) reads the same way.
+            expect(input.indeterminate).toBe(true);
+            expect(input.getAttribute('aria-checked')).toBe('mixed');
+            parent.remove();
+        });
+
+        await it('draws the dash even when also checked', () => {
+            // `check, radio { &:indeterminate { … dash.svg } }`
+            // (_checks.scss:79-81) is re-declared AFTER both `:checked` rules at
+            // equal specificity, so the dash wins. Comparing the three states
+            // against each other proves the cascade, not just that a mask exists.
+            const parent = host();
+            const make = (attrs: string[]) => {
+                const el = document.createElement('adw-checkbox') as AdwCheckbox;
+                for (const attr of attrs) el.setAttribute(attr, '');
+                parent.appendChild(el);
+                return el;
+            };
+            const checked = make(['checked']);
+            const mixed = make(['indeterminate']);
+            const both = make(['checked', 'indeterminate']);
+
+            expect(glyph(both)).toBe(glyph(mixed));
+            expect(glyph(both)).not.toBe(glyph(checked));
+            parent.remove();
+        });
+
+        await it('activating an indeterminate checkbox clears it and checks', () => {
+            // HTML's pre-click activation steps, not a reading of
+            // GtkCheckButton:inconsistent — GTK's is not verifiable in this tree.
+            const { el, parent } = mountCheckbox();
+            el.indeterminate = true;
+            el.click();
+            expect(el.indeterminate).toBe(false);
+            expect(el.checked).toBe(true);
+            parent.remove();
+        });
+    });
+
+    await describe('check and radio share one stylesheet', async () => {
+        await it('both draw the 14px + 3px indicator, differing only in the radius', () => {
+            const parent = host();
+            const check = document.createElement('adw-checkbox') as AdwCheckbox;
+            const radio = document.createElement('adw-radio') as AdwRadio;
+            parent.append(check, radio);
+
+            for (const el of [check, radio]) {
+                const style = getComputedStyle(parts(el).indicator);
+                // GTK sizes the CONTENT box at 14px and grows the drawn control
+                // with `padding: 3px` (_checks.scss:22-26) — content-box, not
+                // the ADR-0010 descendant border-box pin.
+                expect(style.width).toBe('14px');
+                expect(style.height).toBe('14px');
+                expect(style.paddingTop).toBe('3px');
+            }
+
+            // `check { border-radius: 6px }` (:67-68) vs
+            // `radio { border-radius: 100% }` (:73-74).
+            expect(getComputedStyle(parts(check).indicator).borderTopLeftRadius).toBe('6px');
+            expect(getComputedStyle(parts(radio).indicator).borderTopLeftRadius).toContain('%');
+            parent.remove();
+        });
+
+        await it('a checked radio FILLS, with the SAME accent background as a checked check', () => {
+            // refs/adwaita-web's `_radio.scss:22-33` colours only the border and
+            // the dot, leaving the indicator on the view background; libadwaita
+            // fills the whole control from the block it SHARES with the checkbox
+            // (:52-60). libadwaita wins — so the two fills must be identical.
+            //
+            // THREE elements rather than one flipped in place: the indicator
+            // TRANSITIONS `background`, so a computed read taken right after
+            // `checked = true` returns the INTERPOLATED colour — still the old
+            // one. Declaring the state before insertion leaves no transition to
+            // be part-way through. The names are distinct so seeding one group
+            // cannot reach the reference radio.
+            const parent = host();
+            const plain = document.createElement('adw-radio') as AdwRadio;
+            plain.setAttribute('name', 'fill-plain');
+            const radio = document.createElement('adw-radio') as AdwRadio;
+            radio.setAttribute('name', 'fill-checked');
+            radio.setAttribute('value', 'x');
+            radio.setAttribute('checked', '');
+            const check = document.createElement('adw-checkbox') as AdwCheckbox;
+            check.setAttribute('checked', '');
+            parent.append(plain, radio, check);
+
+            const before = getComputedStyle(parts(plain).indicator).backgroundColor;
+            const after = getComputedStyle(parts(radio).indicator).backgroundColor;
+
+            expect(after).not.toBe(before);
+            expect(after).toBe(getComputedStyle(parts(check).indicator).backgroundColor);
+            parent.remove();
+        });
+    });
+
+    await describe('<adw-radio> group exclusivity (conformance vectors)', async () => {
+        for (const [index, vector] of RADIO_GROUP_VECTORS.entries()) {
+            await it(`${vector.name} — ${vector.rule}`, () => {
+                const parent = host();
+                // Per-scenario prefix: the registry is document-global, so two
+                // scenarios sharing a literal group name would share a selection.
+                const scope = (name: string) => `v${index}-${name}`;
+
+                const members = vector.members.map(([name, value]) => {
+                    const el = document.createElement('adw-radio') as AdwRadio;
+                    el.setAttribute('name', scope(name));
+                    el.setAttribute('value', value);
+                    parent.appendChild(el);
+                    return el;
+                });
+                const events = record(parent, 'notify::checked');
+
+                for (const step of vector.steps) {
+                    const target = members.find((el) => el.name === scope(step.name) && el.value === step.value);
+                    expect(target).toBeTruthy();
+                    (target as AdwRadio).click();
+                }
+
+                const expected = new Map(vector.selected.map(([name, value]) => [scope(name), value]));
+                for (const [i, el] of members.entries()) {
+                    const [name, value] = vector.members[i];
+                    const shouldHold = expected.get(scope(name)) === value;
+                    // The HOST attribute, not the input: this is precisely what
+                    // the browser's own exclusivity leaves stale.
+                    expect(el.hasAttribute('checked')).toBe(shouldHold);
+                    expect(parts(el).input.checked).toBe(shouldHold);
+                }
+
+                // Every emitted change repaints the winner, and the loser too
+                // when there was one — that second repaint is the whole reason
+                // the group state exists.
+                const expectedEvents = vector.emitted.reduce(
+                    (total, change) => total + (change.deselected === null ? 1 : 2),
+                    0,
+                );
+                expect(events.length).toBe(expectedEvents);
+                parent.remove();
+            });
+        }
+    });
+
+    await describe('<adw-radio> group behaviour the browser alone gets wrong', async () => {
+        await it('picking a second member clears the first HOST attribute', () => {
+            const parent = host();
+            const first = document.createElement('adw-radio') as AdwRadio;
+            first.setAttribute('name', 'stale-check');
+            first.setAttribute('value', 'a');
+            first.setAttribute('checked', '');
+            const second = document.createElement('adw-radio') as AdwRadio;
+            second.setAttribute('name', 'stale-check');
+            second.setAttribute('value', 'b');
+            parent.append(first, second);
+
+            second.click();
+
+            expect(second.checked).toBe(true);
+            expect(first.checked).toBe(false);
+            expect(first.hasAttribute('checked')).toBe(false);
+            expect(parts(first).input.checked).toBe(false);
+            parent.remove();
+        });
+
+        await it('groups are scoped by name', () => {
+            const parent = host();
+            const make = (name: string, value: string) => {
+                const el = document.createElement('adw-radio') as AdwRadio;
+                el.setAttribute('name', name);
+                el.setAttribute('value', value);
+                parent.appendChild(el);
+                return el;
+            };
+            const left = make('scoped-a', 'x');
+            const right = make('scoped-b', 'x');
+
+            left.click();
+            right.click();
+
+            expect(left.checked).toBe(true);
+            expect(right.checked).toBe(true);
+            parent.remove();
+        });
+
+        await it('a NAMELESS radio is not in a group', () => {
+            // HTML forms a radio button group only from a non-empty `name`.
+            // Without that rule every nameless radio in the document would land
+            // in one `''` group and fight over it — which is exactly what a
+            // registry keyed by name does if nothing guards the empty key.
+            const parent = host();
+            const first = document.createElement('adw-radio') as AdwRadio;
+            const second = document.createElement('adw-radio') as AdwRadio;
+            parent.append(first, second);
+
+            first.click();
+            second.click();
+
+            expect(first.checked).toBe(true);
+            expect(second.checked).toBe(true);
+            parent.remove();
+        });
+
+        await it('a value falls back to the label text so a bare group still works', () => {
+            const parent = host();
+            const make = (text: string) => {
+                const el = document.createElement('adw-radio') as AdwRadio;
+                el.setAttribute('name', 'bare');
+                el.setAttribute('label', text);
+                parent.appendChild(el);
+                return el;
+            };
+            const red = make('Red');
+            const green = make('Green');
+
+            expect(red.value).toBe('Red');
+            red.click();
+            green.click();
+
+            expect(red.checked).toBe(false);
+            expect(green.checked).toBe(true);
+            parent.remove();
+        });
+    });
+};

package/src/adw-drop-down.spec.ts

@@ -2,8 +2,21 @@
 // @gjsify/adwaita-web browser test axis. Asserts option parsing, selected↔value
 // sync, notify-on-change semantics, popover open/close, item selection, search
 // filtering and the disabled guard.
+//
+// The SELECTION half is driven by the SAME table the NativeScript renderer
+// asserts against (`COMBO_SELECTION_VECTORS`, `@gjsify/adwaita-core/conformance`)
+// — replayed against the real element through the API a consumer would use, and
+// read back as what a user would see: the button label, `selected`/`selectedValue`
+// and the `change` stream. `<adw-combo-row>` composes the same `ComboState` but
+// cannot drive the table, because two of its four step ops have no DOM spelling:
+// its options come from the `items` attribute at connect time only (`items` is not
+// even observed), and it publishes no select-by-value setter. So this element is
+// the browser's driver for both.
 import { describe, it, expect } from '@gjsify/unit';
 
+import { COMBO_SELECTION_VECTORS } from '@gjsify/adwaita-core/conformance';
+import type { ComboSelectionStep, ComboSelectionVector } from '@gjsify/adwaita-core/conformance';
+
 import type { AdwDropDown } from './elements/adw-drop-down.js';
 
 function makeDropDown(): AdwDropDown {
@@ -12,7 +25,117 @@ function makeDropDown(): AdwDropDown {
     return el;
 }
 
+/** The text the closed button shows — the rendered `selectedLabel`. */
+function labelText(dd: AdwDropDown): string {
+    return dd.querySelector('.adw-drop-down-label')?.textContent ?? '';
+}
+
+/** Open the chooser the way a user does. A no-op over an empty model, as the element guards. */
+function openChooser(dd: AdwDropDown): void {
+    (dd.querySelector('.adw-drop-down-button') as HTMLButtonElement).click();
+}
+
+/**
+ * Replay one vector step against the real element — property sets for the
+ * programmatic ops, a popover gesture for the interactive one.
+ */
+function applyStep(dd: AdwDropDown, step: ComboSelectionStep): void {
+    switch (step.op) {
+        case 'setOptions':
+            dd.options = step.options;
+            return;
+        case 'setSelectedIndex':
+            dd.selected = step.index;
+            return;
+        case 'setSelectedValue':
+            dd.selectedValue = step.value;
+            return;
+        case 'select':
+            openChooser(dd);
+            if (step.index < 0) {
+                // The dismissed chooser: the popover closes with nothing picked,
+                // which here is an outside pointerdown rather than a cancelled
+                // native sheet.
+                document.dispatchEvent(new PointerEvent('pointerdown', { bubbles: true }));
+                return;
+            }
+            (dd.querySelectorAll('.adw-drop-down-item')[step.index] as HTMLButtonElement | undefined)?.click();
+            return;
+    }
+}
+
+/**
+ * The ONE row this element answers differently, and does so on purpose: its
+ * published `selected` contract REJECTS an out-of-range set (`_selectIndex` gates
+ * on `ComboState.hasIndex`), where the core state accepts it and reports an empty
+ * value — the split `ComboState.hasIndex`'s doc comment records and
+ * `<adw-combo-row>` takes the other side of. The row is still driven below,
+ * against the element's answer rather than the state's, so neither policy can
+ * change silently.
+ */
+const DROP_DOWN_REJECTS = 'an index past the end';
+
+/** The named vector — a hard failure if the table renamed it out from under the carve-out. */
+function vectorNamed(name: string): ComboSelectionVector {
+    const vector = COMBO_SELECTION_VECTORS.find((v) => v.name === name);
+    if (!vector) throw new Error(`COMBO_SELECTION_VECTORS has no row "${name}" — this spec's carve-out is stale`);
+    return vector;
+}
+
+/** Mount a drop-down and record every `change` detail it dispatches. */
+function mountRecording(): { dd: AdwDropDown; changes: unknown[] } {
+    const dd = makeDropDown();
+    const changes: unknown[] = [];
+    dd.addEventListener('change', (event) => changes.push((event as CustomEvent).detail));
+    return { dd, changes };
+}
+
 export const AdwDropDownTest = async () => {
+    await describe('adw-drop-down selection (libadwaita conformance vectors)', async () => {
+        for (const vector of COMBO_SELECTION_VECTORS) {
+            if (vector.name === DROP_DOWN_REJECTS) continue;
+
+            await it(`${vector.name} — ${vector.rule}`, async () => {
+                const { dd, changes } = mountRecording();
+                for (const step of vector.steps) applyStep(dd, step);
+
+                expect(dd.selected).toBe(vector.selected);
+                expect(dd.selectedValue).toBe(vector.value);
+                expect(labelText(dd)).toBe(vector.label);
+                // `change` is this element's DOM spelling of the `interactive`
+                // flag: it fires for a user pick and never for a programmatic
+                // set, so the interactive frames of the emission stream ARE the
+                // events a listener sees.
+                expect(changes).toStrictEqual(
+                    vector.emitted
+                        .filter((change) => change.interactive)
+                        .map((change) => ({ index: change.selected, value: change.value, label: change.label })),
+                );
+                dd.remove();
+            });
+        }
+
+        await it(`${DROP_DOWN_REJECTS} — rejected here: the element's published contract, not the state's`, async () => {
+            const vector = vectorNamed(DROP_DOWN_REJECTS);
+            const { dd, changes } = mountRecording();
+
+            // Everything up to the out-of-range set…
+            for (const step of vector.steps.slice(0, -1)) applyStep(dd, step);
+            const before = { selected: dd.selected, value: dd.selectedValue, label: labelText(dd) };
+            // …and then the set itself, which the core state would accept and
+            // report as nothing-to-draw (`value`/`label` both empty below).
+            expect(vector.value).toBe('');
+            expect(vector.label).toBe('');
+            applyStep(dd, vector.steps[vector.steps.length - 1]);
+
+            // The element refused it: the selection did not move, and a refusal
+            // is not a change, so nothing was dispatched either.
+            expect({ selected: dd.selected, value: dd.selectedValue, label: labelText(dd) }).toStrictEqual(before);
+            expect(changes).toStrictEqual([]);
+            dd.remove();
+        });
+    });
+
     await describe('adw-drop-down options', async () => {
         await it('accepts a string[] (value === label)', async () => {
             const dd = makeDropDown();

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

@@ -0,0 +1,83 @@
+// DOM-level tests for <adw-header-bar>'s title.
+//
+// `title` was read exactly once, in `connectedCallback`, and the element declared
+// no `observedAttributes` at all — so every later write was a silent no-op. A
+// header bar whose title tracks the open document kept whatever it was created
+// with, and nothing in the build was in a position to notice: the attribute was
+// still THERE, and the element still rendered A title.
+//
+// `Adw.HeaderBar` builds its centre from `title`/`subtitle` through a derived
+// `AdwWindowTitle` bound to the properties, unless a `title-widget` replaces it
+// — which is the either/or the `slot="center"` case below asserts.
+
+import { describe, expect, it } from '@gjsify/unit';
+
+/** The rendered centre text of a mounted header bar. */
+function centerText(bar: HTMLElement): string {
+    return bar.querySelector('.adw-header-bar-center')?.textContent ?? '';
+}
+
+/** Mount a header bar with the given attributes and slotted children. */
+function mountHeaderBar(attrs: Record<string, string>, slotted: readonly HTMLElement[] = []): HTMLElement {
+    const bar = document.createElement('adw-header-bar');
+    for (const [name, value] of Object.entries(attrs)) bar.setAttribute(name, value);
+    for (const child of slotted) bar.appendChild(child);
+    document.body.appendChild(bar);
+    return bar;
+}
+
+/** A `slot="center"` title-widget, the equivalent of `Adw.HeaderBar:title-widget`. */
+function centerWidget(text: string): HTMLElement {
+    const widget = document.createElement('div');
+    widget.setAttribute('slot', 'center');
+    widget.id = 'url-entry';
+    widget.textContent = text;
+    return widget;
+}
+
+/** Remove every header bar a test mounted. */
+function unmountAll(): void {
+    for (const bar of Array.from(document.querySelectorAll('adw-header-bar'))) bar.remove();
+}
+
+export const AdwHeaderBarTest = async () => {
+    await describe('<adw-header-bar> title', async () => {
+        await it('renders the title it was created with', () => {
+            const bar = mountHeaderBar({ title: 'Documents' });
+            expect(centerText(bar)).toBe('Documents');
+            unmountAll();
+        });
+
+        await it('follows a LATER write, instead of freezing at connect time', () => {
+            const bar = mountHeaderBar({ title: 'Documents' });
+            bar.setAttribute('title', 'Pictures');
+            expect(centerText(bar)).toBe('Pictures');
+            unmountAll();
+        });
+
+        await it('clears when the attribute is removed', () => {
+            const bar = mountHeaderBar({ title: 'Documents' });
+            bar.removeAttribute('title');
+            expect(centerText(bar)).toBe('');
+            unmountAll();
+        });
+
+        await it('a title set before the element is connected still lands', () => {
+            const bar = document.createElement('adw-header-bar');
+            bar.setAttribute('title', 'Early');
+            document.body.appendChild(bar);
+            expect(centerText(bar)).toBe('Early');
+            unmountAll();
+        });
+
+        await it('a slot="center" widget wins, and a title write does not overwrite it', () => {
+            const bar = mountHeaderBar({ title: 'Ignored' }, [centerWidget('example.org')]);
+            expect(bar.querySelector('#url-entry')).toBeTruthy();
+            expect(centerText(bar)).toBe('example.org');
+
+            bar.setAttribute('title', 'Still ignored');
+            expect(centerText(bar)).toBe('example.org');
+            unmountAll();
+        });
+    });
+};