@gjsify/adwaita-web 0.21.0 → 0.23.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/adwaita-web",
-    "version": "0.21.0",
+    "version": "0.23.0",
     "description": "Adwaita/Libadwaita web components for browser targets",
     "type": "module",
     "main": "./src/index.ts",
@@ -41,13 +41,14 @@
         "@codemirror/language": "^6.12.4",
         "@codemirror/state": "^6.7.0",
         "@codemirror/view": "^6.43.4",
-        "@gjsify/adwaita-fonts": "^0.21.0",
-        "@gjsify/adwaita-icons": "^0.21.0",
+        "@gjsify/adwaita-core": "^0.23.0",
+        "@gjsify/adwaita-fonts": "^0.23.0",
+        "@gjsify/adwaita-icons": "^0.23.0",
         "@lezer/highlight": "^1.2.3"
     },
     "devDependencies": {
-        "@gjsify/cli": "^0.21.0",
-        "@gjsify/unit": "^0.21.0",
+        "@gjsify/cli": "^0.23.0",
+        "@gjsify/unit": "^0.23.0",
         "sass": "^1.101.0",
         "typescript": "^6.0.3"
     },

package/scss/_reset.scss

@@ -0,0 +1,69 @@
+// _reset.scss — style-isolation boundary for embedding in arbitrary host pages.
+//
+// adwaita-web renders as LIGHT-DOM custom elements (by design: the widgets
+// compose with the page and stay overridable via the `--adw-*` / `--*` design
+// tokens). The trade-off of light DOM is that a host page's *inherited*
+// typography — `font-family`, `color`, `line-height`, `letter-spacing`, … — and
+// generic element resets can leak into the widgets.
+//
+// This partial establishes an Adwaita typographic + box-model context at EVERY
+// component boundary, so inheritance from the host stops at the widget. It sets
+// only a FLOOR: it is `@use`d before the component partials, so each component's
+// own rules override it, and consumers keep full control through the tokens and
+// ordinary higher-specificity rules (isolation without giving up overriding).
+//
+// The box battles (borders, backgrounds) are already won by the components'
+// class-scoped rules against realistic element-level host CSS; the real leak is
+// inherited typography + a host `* {}` box-sizing reset, which is what this
+// neutralises.
+
+// Every custom element adwaita-web defines. Keep in sync with
+// `src/elements/*` (the `customElements.define('adw-…')` calls).
+$adw-components:
+  adw-about-dialog, adw-action-row, adw-alert-dialog, adw-alert-response,
+  adw-avatar, adw-banner, adw-bottom-sheet, adw-bottom-sheet-content,
+  adw-bottom-sheet-sheet, adw-button, adw-button-content, adw-button-row,
+  adw-card, adw-carousel, adw-carousel-indicator-dots,
+  adw-carousel-indicator-lines, adw-clamp, adw-combo-row, adw-data-grid,
+  adw-dialog, adw-drop-down, adw-entry, adw-entry-row, adw-expander-row,
+  adw-header-bar, adw-inline-view-switcher, adw-menu-button, adw-navigation-page,
+  adw-navigation-split-view, adw-navigation-view, adw-overlay-split-view,
+  adw-password-entry-row, adw-preferences-dialog, adw-preferences-group,
+  adw-preferences-page, adw-sidebar, adw-sidebar-item, adw-sidebar-section,
+  adw-spinner, adw-spin-row, adw-split-button, adw-status-page, adw-switch-row,
+  adw-tab-page, adw-tab-view, adw-toast-overlay, adw-toggle, adw-toggle-group,
+  adw-toolbar-view, adw-view-stack, adw-view-stack-page, adw-view-switcher,
+  adw-view-switcher-bar, adw-view-switcher-page, adw-window, adw-window-title,
+  adw-wrap-box;
+
+// Roots: re-root the inherited typographic properties (and the box model) so a
+// host page's font / colour / spacing cannot flow into the widget. Every value
+// is the Adwaita default; a component that wants something else overrides it on
+// its own element (this rule is emitted first).
+#{$adw-components} {
+  box-sizing: border-box;
+  color: var(--window-fg-color);
+  font-family: var(--font-family);
+  font-size: var(--font-size-base);
+  font-weight: 400;
+  font-style: normal;
+  font-variant: normal;
+  line-height: normal;
+  letter-spacing: normal;
+  word-spacing: normal;
+  text-align: start;
+  text-indent: 0;
+  text-transform: none;
+  text-shadow: none;
+}
+
+// Descendants: `box-sizing` does not inherit, so a host `*, *::before {
+// box-sizing: content-box }` reset would still reach internal elements. Pin it
+// to `border-box` (adwaita's model throughout) inside every component.
+@each $c in $adw-components {
+  #{$c} *,
+  #{$c} *::before,
+  #{$c} *::after {
+    box-sizing: border-box;
+  }
+}

package/scss/_toast.scss

@@ -20,8 +20,11 @@ adw-toast-overlay {
     height: 100%;
   }
 
-  // Toasts are layered over the bottom edge of the overlay, stacked newest-last
-  // and centered, the way AdwToastOverlay floats them above its child.
+  // The toast slot: layered over the bottom edge of the overlay and centered,
+  // the way AdwToastOverlay floats a toast above its child. Like
+  // Adw.ToastOverlay only ONE toast is mounted at a time (the queue lives in
+  // `@gjsify/adwaita-core`); the flex column keeps it centered and lets an
+  // outgoing `.hiding` strip finish its exit transition in place.
   .adw-toast-overlay-toasts {
     position: absolute;
     bottom: var(--spacing-m);

package/scss/_view_switcher_bar.scss

@@ -11,6 +11,16 @@
 
 adw-view-switcher-bar {
     display: block;
+
+    // `revealed` drives visibility by toggling the `hidden` attribute
+    // (_applyRevealed → this.hidden). Re-assert display:none for [hidden] as an
+    // AUTHOR rule: the UA `[hidden] { display: none }` loses to this block's own
+    // author `display: block` (cascade ORIGIN beats specificity), so without this
+    // an unrevealed bar would stay visible. Author + higher specificity → wins.
+    &[hidden] {
+        display: none;
+    }
+
     box-sizing: border-box;
     // The bottom bar over a headerbar-toned surface with a top hairline (the
     // libadwaita `actionbar` inset top border), NOT a bottom border.

package/scss/adwaita-skin.scss

@@ -10,6 +10,9 @@
 @use 'variables';
 @use 'theme';
 @use 'root';
+// Style-isolation boundary — emitted before the components so their own rules
+// override this typographic/box-model floor (see _reset.scss).
+@use 'reset';
 @use 'window';
 @use 'headerbar';
 @use 'window_title';

package/src/adw-row-state.spec.ts

@@ -0,0 +1,217 @@
+// DOM-level behaviour tests for the rows whose state machines now come from
+// `@gjsify/adwaita-core` (ADR 0004): <adw-combo-row> (ComboState),
+// <adw-spin-row> (SpinState), <adw-toggle-group> (ToggleGroupState) and
+// <adw-expander-row> (ExpanderState).
+//
+// They pin the contract the composition must preserve — most importantly the
+// programmatic-vs-interactive split this port has always had: a user interaction
+// emits the `notify::*` event, a programmatic property/attribute set updates the
+// display silently.
+import { describe, expect, it } from '@gjsify/unit';
+
+import type { AdwComboRow } from './elements/adw-combo-row.js';
+import type { AdwExpanderRow } from './elements/adw-expander-row.js';
+import type { AdwSpinRow } from './elements/adw-spin-row.js';
+import type { AdwToggleGroup } from './elements/adw-toggle-group.js';
+
+/** Parse markup so attributes are present when connectedCallback runs. */
+function parse<T extends HTMLElement>(html: string, selector: string): { el: T; host: HTMLElement } {
+    const host = document.createElement('div');
+    document.body.appendChild(host);
+    host.innerHTML = html;
+    return { el: host.querySelector(selector) as T, host };
+}
+
+/** Collect the `detail` of every `event` dispatched on `el` while `run()` executes. */
+function record(el: HTMLElement, event: string): { details: unknown[]; stop: () => void } {
+    const details: unknown[] = [];
+    const listener = (e: Event) => details.push((e as CustomEvent).detail);
+    el.addEventListener(event, listener);
+    return { details, stop: () => el.removeEventListener(event, listener) };
+}
+
+export const AdwRowStateTest = async () => {
+    await describe('adw-combo-row (ComboState)', async () => {
+        await it('renders the selected label and notifies only on a user pick', async () => {
+            const { el: row, host } = parse<AdwComboRow>(
+                `<adw-combo-row title="Colour" items='["Red","Green","Blue"]' selected="1"></adw-combo-row>`,
+                'adw-combo-row',
+            );
+            const select = row.querySelector('select') as HTMLSelectElement;
+            const value = row.querySelector('.adw-row-value') as HTMLSpanElement;
+            const events = record(row, 'notify::selected');
+
+            expect(row.selected).toBe(1);
+            expect(value.textContent).toBe('Green');
+            expect(select.selectedIndex).toBe(1);
+
+            // A user pick through the native <select>.
+            select.selectedIndex = 2;
+            select.dispatchEvent(new Event('change'));
+            expect(row.selected).toBe(2);
+            expect(value.textContent).toBe('Blue');
+            expect(row.getAttribute('selected')).toBe('2');
+            expect(events.details.length).toBe(1);
+            expect((events.details[0] as { selected: number }).selected).toBe(2);
+
+            // A programmatic set refreshes the display but stays silent.
+            row.selected = 0;
+            expect(value.textContent).toBe('Red');
+            expect(select.selectedIndex).toBe(0);
+            expect(events.details.length).toBe(1);
+
+            events.stop();
+            host.remove();
+        });
+
+        await it('renders an empty value for an out-of-range selection', async () => {
+            const { el: row, host } = parse<AdwComboRow>(
+                `<adw-combo-row title="Empty" items='[]' selected="3"></adw-combo-row>`,
+                'adw-combo-row',
+            );
+            expect((row.querySelector('.adw-row-value') as HTMLSpanElement).textContent).toBe('');
+            host.remove();
+        });
+    });
+
+    await describe('adw-spin-row (SpinState)', async () => {
+        await it('steps at step precision and notifies only on a stepper press', async () => {
+            const { el: row, host } = parse<AdwSpinRow>(
+                '<adw-spin-row title="Amount" min="0" max="10" step="0.1" value="0"></adw-spin-row>',
+                'adw-spin-row',
+            );
+            const input = row.querySelector('input') as HTMLInputElement;
+            const inc = row.querySelector('.adw-spin-inc') as HTMLButtonElement;
+            const events = record(row, 'notify::value');
+
+            expect(input.value).toBe('0.0');
+
+            inc.click();
+            inc.click();
+            inc.click();
+            // Without the step-precision rounding this drifts to 0.30000000000000004.
+            expect(row.value).toBe(0.3);
+            expect(input.value).toBe('0.3');
+            expect(events.details.length).toBe(3);
+
+            // A programmatic set clamps to max and stays silent.
+            row.value = 99;
+            expect(row.value).toBe(10);
+            expect(input.value).toBe('10.0');
+            expect(events.details.length).toBe(3);
+
+            events.stop();
+            host.remove();
+        });
+
+        await it('clamps to the lower bound and re-clamps when a bound moves', async () => {
+            const { el: row, host } = parse<AdwSpinRow>(
+                '<adw-spin-row title="Amount" min="2" max="8" step="1" value="5"></adw-spin-row>',
+                'adw-spin-row',
+            );
+            const input = row.querySelector('input') as HTMLInputElement;
+
+            row.value = -4;
+            expect(row.value).toBe(2);
+
+            // Moving the upper bound below the value pulls the value into range.
+            row.value = 8;
+            row.setAttribute('max', '6');
+            expect(row.value).toBe(6);
+            expect(input.value).toBe('6');
+
+            host.remove();
+        });
+    });
+
+    await describe('adw-toggle-group (ToggleGroupState)', async () => {
+        await it('tracks the active segment and notifies only on a click', async () => {
+            const { el: group, host } = parse<AdwToggleGroup>(
+                `<adw-toggle-group active="1">
+                    <adw-toggle label="One"></adw-toggle>
+                    <adw-toggle label="Two"></adw-toggle>
+                    <adw-toggle label="Three"></adw-toggle>
+                </adw-toggle-group>`,
+                'adw-toggle-group',
+            );
+            const buttons = Array.from(group.querySelectorAll('button.adw-toggle')) as HTMLButtonElement[];
+            const events = record(group, 'notify::active');
+
+            expect(buttons.length).toBe(3);
+            expect(group.active).toBe(1);
+            expect(buttons[1].classList.contains('active')).toBe(true);
+            expect(buttons[1].getAttribute('aria-pressed')).toBe('true');
+
+            buttons[2].click();
+            expect(group.active).toBe(2);
+            expect(buttons[2].classList.contains('active')).toBe(true);
+            expect(buttons[1].classList.contains('active')).toBe(false);
+            expect(group.getAttribute('active')).toBe('2');
+            expect(events.details.length).toBe(1);
+
+            // Re-clicking the active segment is a no-op.
+            buttons[2].click();
+            expect(events.details.length).toBe(1);
+
+            // A programmatic set moves the pill without notifying.
+            group.active = 0;
+            expect(group.active).toBe(0);
+            expect(buttons[0].classList.contains('active')).toBe(true);
+            expect(events.details.length).toBe(1);
+
+            events.stop();
+            host.remove();
+        });
+
+        await it('clamps an out-of-range active attribute to the last segment', async () => {
+            const { el: group, host } = parse<AdwToggleGroup>(
+                `<adw-toggle-group active="99">
+                    <adw-toggle label="One"></adw-toggle>
+                    <adw-toggle label="Two"></adw-toggle>
+                </adw-toggle-group>`,
+                'adw-toggle-group',
+            );
+            expect(group.active).toBe(1);
+            host.remove();
+        });
+    });
+
+    await describe('adw-expander-row (ExpanderState)', async () => {
+        await it('discloses on a header click and notifies only then', async () => {
+            const { el: row, host } = parse<AdwExpanderRow>(
+                '<adw-expander-row title="More"><adw-action-row title="Nested"></adw-action-row></adw-expander-row>',
+                'adw-expander-row',
+            );
+            const header = row.querySelector('.adw-expander-row-header') as HTMLDivElement;
+            const events = record(row, 'notify::expanded');
+
+            expect(row.expanded).toBe(false);
+            expect(row.classList.contains('expanded')).toBe(false);
+
+            header.click();
+            expect(row.expanded).toBe(true);
+            expect(row.hasAttribute('expanded')).toBe(true);
+            expect(row.classList.contains('expanded')).toBe(true);
+            expect(events.details.length).toBe(1);
+
+            // A programmatic collapse reflects to the attribute but stays silent.
+            row.expanded = false;
+            expect(row.hasAttribute('expanded')).toBe(false);
+            expect(row.classList.contains('expanded')).toBe(false);
+            expect(events.details.length).toBe(1);
+
+            events.stop();
+            host.remove();
+        });
+
+        await it('adopts a declarative expanded attribute', async () => {
+            const { el: row, host } = parse<AdwExpanderRow>(
+                '<adw-expander-row title="Open" expanded></adw-expander-row>',
+                'adw-expander-row',
+            );
+            expect(row.expanded).toBe(true);
+            expect(row.classList.contains('expanded')).toBe(true);
+            host.remove();
+        });
+    });
+};

package/src/adw-toast-overlay.spec.ts

@@ -0,0 +1,172 @@
+// DOM-level behaviour tests for <adw-toast-overlay>. Runs in a real browser via
+// the @gjsify/adwaita-web browser test axis.
+//
+// The regression these guard: the overlay used to append EVERY toast as its own
+// strip the moment `addToast()` was called, so three calls stacked three visible
+// toasts and each ran its own timer. `Adw.ToastOverlay` shows exactly ONE toast
+// at a time and queues the rest FIFO, advancing only when the visible one is
+// dismissed (manually or by its timeout) — the policy `AdwToastQueue` in
+// `@gjsify/adwaita-core` owns and this element now composes.
+//
+// Timing is driven through core's injected `ToastScheduler` seam (a virtual
+// clock), so the auto-dismiss lifecycle is asserted deterministically with no
+// real timers.
+import { describe, expect, it } from '@gjsify/unit';
+
+import type { AdwToastOverlay, ToastScheduler, ToastTimerHandle } from './elements/adw-toast-overlay.js';
+
+/** A deterministic {@link ToastScheduler}: timers fire only when time is advanced. */
+class VirtualClock implements ToastScheduler {
+    private _now = 0;
+    private _seq = 0;
+    private readonly _timers = new Map<number, { at: number; run: () => void }>();
+
+    schedule(callback: () => void, ms: number): ToastTimerHandle {
+        const handle = ++this._seq;
+        this._timers.set(handle, { at: this._now + ms, run: callback });
+        return handle;
+    }
+
+    cancel(handle: ToastTimerHandle): void {
+        this._timers.delete(handle as number);
+    }
+
+    /** Move the clock forward, draining every timer that comes due. */
+    advance(ms: number): void {
+        this._now += ms;
+        // A fired timer may schedule another one that is already due (the exit
+        // fallback of a toast dismissed mid-advance), so drain until settled.
+        for (let guard = 0; guard < 100; guard++) {
+            const due = [...this._timers].filter(([, timer]) => timer.at <= this._now);
+            if (due.length === 0) return;
+            for (const [handle, timer] of due) {
+                this._timers.delete(handle);
+                timer.run();
+            }
+        }
+        throw new Error('VirtualClock.advance did not settle — a timer keeps rescheduling itself');
+    }
+}
+
+/** Mount an overlay driven by a virtual clock instead of the browser's timers. */
+function mountOverlay(): { overlay: AdwToastOverlay; clock: VirtualClock; host: HTMLElement } {
+    const host = document.createElement('div');
+    document.body.appendChild(host);
+    host.innerHTML = '<adw-toast-overlay><p>content</p></adw-toast-overlay>';
+    const overlay = host.querySelector('adw-toast-overlay') as AdwToastOverlay;
+    const clock = new VirtualClock();
+    overlay.scheduler = clock;
+    return { overlay, clock, host };
+}
+
+/** The titles of every toast strip currently in the overlay's DOM. */
+function toastTitles(overlay: AdwToastOverlay): string[] {
+    return Array.from(overlay.querySelectorAll('.adw-toast .adw-toast-title')).map((el) => el.textContent ?? '');
+}
+
+export const AdwToastOverlayTest = async () => {
+    await describe('adw-toast-overlay', async () => {
+        await it('shows exactly one toast at a time, in FIFO order', async () => {
+            const { overlay, clock, host } = mountOverlay();
+
+            overlay.addToast('First', { timeout: 3 });
+            overlay.addToast('Second', { timeout: 3 });
+            overlay.addToast('Third', { timeout: 3 });
+
+            // BEFORE the fix this was ['First', 'Second', 'Third'] — all three
+            // strips mounted at once.
+            expect(toastTitles(overlay)).toStrictEqual(['First']);
+            expect(overlay.pendingToasts).toBe(2);
+            expect(overlay.currentToast?.title).toBe('First');
+
+            // The next toast appears only once the previous one timed out.
+            clock.advance(3000);
+            expect(toastTitles(overlay)).toStrictEqual(['Second']);
+            expect(overlay.pendingToasts).toBe(1);
+
+            clock.advance(3000);
+            expect(toastTitles(overlay)).toStrictEqual(['Third']);
+            expect(overlay.pendingToasts).toBe(0);
+
+            // The last one fades out; the exit fallback detaches the strip.
+            clock.advance(3000);
+            expect(overlay.currentToast).toBeNull();
+            clock.advance(300);
+            expect(toastTitles(overlay)).toStrictEqual([]);
+
+            host.remove();
+        });
+
+        await it('holds the queue while a sticky toast (timeout 0) is shown', async () => {
+            const { overlay, clock, host } = mountOverlay();
+
+            overlay.addToast('Sticky', { timeout: 0 });
+            overlay.addToast('Next', { timeout: 3 });
+
+            // No timer was scheduled for the sticky toast, so time does not advance it.
+            clock.advance(60_000);
+            expect(toastTitles(overlay)).toStrictEqual(['Sticky']);
+            expect(overlay.pendingToasts).toBe(1);
+
+            // Dismissing it hands the slot to the queued toast.
+            overlay.dismiss();
+            expect(toastTitles(overlay)).toStrictEqual(['Next']);
+            expect(overlay.pendingToasts).toBe(0);
+
+            host.remove();
+        });
+
+        await it('advances the queue when the close button is pressed', async () => {
+            const { overlay, host } = mountOverlay();
+
+            overlay.addToast('First', { timeout: 3 });
+            overlay.addToast('Second', { timeout: 3 });
+
+            const close = overlay.querySelector('.adw-toast-close-button') as HTMLButtonElement;
+            close.click();
+
+            expect(toastTitles(overlay)).toStrictEqual(['Second']);
+            expect(overlay.pendingToasts).toBe(0);
+
+            host.remove();
+        });
+
+        await it('runs the action callback and advances the queue', async () => {
+            const { overlay, host } = mountOverlay();
+
+            let undone = 0;
+            overlay.addToast('File moved to Trash', {
+                timeout: 3,
+                buttonLabel: 'Undo',
+                onAction: () => {
+                    undone += 1;
+                },
+            });
+            overlay.addToast('Second', { timeout: 3 });
+
+            const action = overlay.querySelector('.adw-toast-action-button') as HTMLButtonElement;
+            expect(action.textContent).toBe('Undo');
+            action.click();
+
+            expect(undone).toBe(1);
+            expect(toastTitles(overlay)).toStrictEqual(['Second']);
+
+            host.remove();
+        });
+
+        await it('drops the queued toasts on clearToasts()', async () => {
+            const { overlay, clock, host } = mountOverlay();
+
+            overlay.addToast('First', { timeout: 3 });
+            overlay.addToast('Second', { timeout: 3 });
+            overlay.clearToasts();
+
+            expect(overlay.currentToast).toBeNull();
+            expect(overlay.pendingToasts).toBe(0);
+            clock.advance(300);
+            expect(toastTitles(overlay)).toStrictEqual([]);
+
+            host.remove();
+        });
+    });
+};

package/src/adw-view-switcher-bar.spec.ts

@@ -0,0 +1,31 @@
+// adw-view-switcher-bar visibility regression (browser axis). Guards that the
+// `revealed` flag actually shows/hides the bar. The bar's base scss sets
+// `display: block`, an AUTHOR rule that would defeat the UA `[hidden]{display:none}`
+// the component relies on (cascade origin beats specificity) — so an unrevealed
+// bar rendered visible until scss/_view_switcher_bar.scss re-asserted
+// `&[hidden] { display: none }`. This test pins that fix.
+import { describe, expect, it } from '@gjsify/unit';
+
+export const AdwViewSwitcherBarTest = async () => {
+    await describe('adw-view-switcher-bar revealed → visibility', async () => {
+        await it('is display:none by default (not revealed) and block once revealed', async () => {
+            const bar = document.createElement('adw-view-switcher-bar');
+            document.body.appendChild(bar);
+
+            // Default: `revealed` absent → the component sets `hidden`, and the
+            // scss `[hidden]` author rule must win over the base `display: block`.
+            expect(bar.hasAttribute('revealed')).toBe(false);
+            expect(getComputedStyle(bar).display).toBe('none');
+
+            // Reveal it → shown.
+            bar.setAttribute('revealed', '');
+            expect(getComputedStyle(bar).display).toBe('block');
+
+            // Hide it again → back to none (the round-trip, not a one-way latch).
+            bar.removeAttribute('revealed');
+            expect(getComputedStyle(bar).display).toBe('none');
+
+            bar.remove();
+        });
+    });
+};