@gjsify/adwaita-web 0.22.0 → 0.23.0

package/lib/types/adw-row-state.spec.d.ts

@@ -0,0 +1 @@
+export declare const AdwRowStateTest: () => Promise<void>;

package/lib/types/adw-toast-overlay.spec.d.ts

@@ -0,0 +1 @@
+export declare const AdwToastOverlayTest: () => Promise<void>;

package/lib/types/elements/adw-alert-dialog.d.ts

@@ -1,5 +1,6 @@
+import type { AdwResponseAppearance } from '@gjsify/adwaita-core';
 /** Response button appearance — mirrors Adw.ResponseAppearance. */
-export type AdwResponseAppearance = 'default' | 'suggested' | 'destructive';
+export type { AdwResponseAppearance } from '@gjsify/adwaita-core';
 /**
  * A single response declared in markup. Child of <adw-alert-dialog>; its `id`
  * attribute is the response ID, its text content the label. Optional
@@ -17,10 +18,10 @@ export declare class AdwAlertDialog extends HTMLElement {
     private _bodyEl;
     private _childEl;
     private _responseAreaEl;
-    private _responses;
-    private _byId;
-    private _defaultResponse;
-    private _closeResponse;
+    /** The headless response registry + default/close semantics + resolution (ADR 0004). */
+    private _model;
+    /** The rendered button per registered response id (the DOM half of the model). */
+    private readonly _buttons;
     private _blockCloseResponse;
     static get observedAttributes(): string[];
     /** The heading of the dialog. */

package/lib/types/elements/adw-combo-row.d.ts

@@ -3,7 +3,8 @@ export declare class AdwComboRow extends HTMLElement {
     private _valueEl;
     private _titleEl;
     private _subtitleEl;
-    private _items;
+    /** The headless options list + selectedIndex↔selectedValue state machine (ADR 0004). */
+    private readonly _state;
     private _initialized;
     static get observedAttributes(): string[];
     get selected(): number;

package/lib/types/elements/adw-expander-row.d.ts

@@ -8,7 +8,10 @@ export declare class AdwExpanderRow extends HTMLElement {
     private _contentEl;
     private _prefixEl;
     private _suffixEl;
+    /** The headless expanded/collapsed disclosure state machine (ADR 0004). */
+    private readonly _state;
     private _initialized;
+    constructor();
     static get observedAttributes(): string[];
     get expanded(): boolean;
     set expanded(value: boolean);
@@ -21,6 +24,6 @@ export declare class AdwExpanderRow extends HTMLElement {
     /** The header prefix section — append icons/widgets here imperatively. */
     get prefixSection(): HTMLDivElement;
     connectedCallback(): void;
-    attributeChangedCallback(): void;
+    attributeChangedCallback(name: string): void;
     private _render;
 }

package/lib/types/elements/adw-spin-row.d.ts

@@ -2,10 +2,8 @@ export declare class AdwSpinRow extends HTMLElement {
     private _input;
     private _titleEl;
     private _subtitleEl;
-    private _min;
-    private _max;
-    private _step;
-    private _value;
+    /** The headless value/min/max/step adjustment with clamping (ADR 0004). */
+    private readonly _state;
     private _initialized;
     static get observedAttributes(): string[];
     get value(): number;
@@ -13,8 +11,12 @@ export declare class AdwSpinRow extends HTMLElement {
     connectedCallback(): void;
     attributeChangedCallback(name: string, _old: string | null, val: string | null): void;
     private _renderText;
+    /** A stepper press — the interactive path, so it emits `notify::value`. */
     private _adjust;
     private _emitChange;
+    /** Mirror the core value into the input display + the reflected attribute. */
+    private _syncValue;
+    private _roundToStep;
     private _countDecimals;
     private _formatValue;
 }

package/lib/types/elements/adw-toast-overlay.d.ts

@@ -1,3 +1,6 @@
+import { AdwToast } from '@gjsify/adwaita-core';
+import type { ToastScheduler } from '@gjsify/adwaita-core';
+export type { ToastScheduler, ToastTimerHandle } from '@gjsify/adwaita-core';
 /** Options for {@link AdwToastOverlay.addToast}, mirroring Adw.Toast's properties. */
 export interface AdwToastOptions {
     /** Seconds before the toast auto-dismisses; `0` keeps it until dismissed. Mirrors Adw.Toast:timeout (default 5). */
@@ -10,14 +13,52 @@ export interface AdwToastOptions {
 export declare class AdwToastOverlay extends HTMLElement {
     private _toasts;
     private _initialized;
+    /** The headless one-at-a-time + FIFO + auto-dismiss state machine (ADR 0004). */
+    private readonly _queue;
+    /** The timing source the queue's auto-dismiss runs on — swappable, see {@link scheduler}. */
+    private _scheduler;
+    /** The strip currently mounted for {@link AdwToastQueue.current}, if any. */
+    private _currentEl;
+    /** Per-toast action callbacks (the core toast descriptor carries only the label). */
+    private readonly _actions;
+    constructor();
     connectedCallback(): void;
+    /**
+     * The timing source driving the queue's auto-dismiss and the exit transition.
+     * Defaults to the browser's `setTimeout`/`clearTimeout`; swap it for a
+     * deterministic fake to drive toast lifetimes without real timers (the
+     * {@link ToastScheduler} seam `@gjsify/adwaita-core` defines).
+     */
+    get scheduler(): ToastScheduler;
+    set scheduler(scheduler: ToastScheduler);
+    /** The toast currently on screen, or `null` when nothing is shown. */
+    get currentToast(): AdwToast | null;
+    /** Number of toasts queued behind the visible one. */
+    get pendingToasts(): number;
     /**
      * Show a toast notification — the web equivalent of Adw.ToastOverlay.add_toast()
      * with a freshly-built Adw.Toast.
      *
+     * Like Adw.ToastOverlay, only ONE toast is visible at a time: this one shows
+     * immediately when the slot is free, otherwise it waits its turn behind the
+     * toasts already queued.
+     *
      * @param title   The text to display.
-     * @param options Either a timeout in seconds (legacy shorthand) or an
+     * @param options Either a timeout in milliseconds (legacy shorthand) or an
      *                {@link AdwToastOptions} bag (title text already supplied here).
      */
     addToast(title: string, options?: number | AdwToastOptions): void;
+    /** Dismiss the visible toast early; the next queued toast takes its place. */
+    dismiss(): void;
+    /** Dismiss the visible toast and discard everything still queued behind it. */
+    clearToasts(): void;
+    /** Build + attach the strip for `toast` — the DOM half of the queue's `onShow`. */
+    private _mountToast;
+    /**
+     * Detach the mounted strip — the DOM half of the queue's `onHide`.
+     *
+     * @param immediate Skip the exit transition because the next queued toast is
+     *                  about to take this slot (keeps exactly one strip mounted).
+     */
+    private _unmountToast;
 }

package/lib/types/elements/adw-toggle-group.d.ts

@@ -5,7 +5,8 @@ export declare class AdwToggle extends HTMLElement {
 export declare class AdwToggleGroup extends HTMLElement {
     private _innerEl;
     private _buttons;
-    private _active;
+    /** The headless segment list + guarded selection state machine (ADR 0004). */
+    private readonly _state;
     private _initialized;
     static get observedAttributes(): string[];
     /** Zero-based index of the active toggle. */

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/adwaita-web",
-    "version": "0.22.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.22.0",
-        "@gjsify/adwaita-icons": "^0.22.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.22.0",
-        "@gjsify/unit": "^0.22.0",
+        "@gjsify/cli": "^0.23.0",
+        "@gjsify/unit": "^0.23.0",
         "sass": "^1.101.0",
         "typescript": "^6.0.3"
     },

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/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();
+        });
+    });
+};