@gjsify/adwaita-web 0.22.0 → 0.23.0

package/src/elements/adw-spin-row.ts

@@ -1,19 +1,30 @@
 // <adw-spin-row> — Row with a title/subtitle and a numeric spin control (+/− buttons).
 // Attributes: title, subtitle, min, max, step, value
 // Events: notify::value (CustomEvent, mirrors GJS GObject signal naming)
+//
+// The ADJUSTMENT state machine (value/min/max/step plus the clamp-on-every-
+// mutation and the change detection) is HEADLESS and lives in
+// `@gjsify/adwaita-core` (ADR 0004) as {@link SpinState}; this element composes it
+// and keeps only the DOM render half — the −/input/+ control, the step-precision
+// display (the `Adw.SpinRow:digits` concern, which belongs to the widget, not to
+// the adjustment) and the `notify::value` event.
+// `@gjsify/adwaita-nativescript` composes the same state machine, so both ports
+// share one behaviour.
+//
 // Adapted from Adwaita Web UI Framework (https://github.com/mclellac/adwaita-web).
 // Copyright (c) 2025 csm. MIT License.
 // Modifications: Reimplemented as Web Component for @gjsify/adwaita-web;
-//   title/subtitle text column added to match Adw.SpinRow.
+//   title/subtitle text column added to match Adw.SpinRow; the adjustment state
+//   machine composed from @gjsify/adwaita-core.
+
+import { SpinState } from '@gjsify/adwaita-core';
 
 export class AdwSpinRow extends HTMLElement {
     private _input!: HTMLInputElement;
     private _titleEl!: HTMLSpanElement;
     private _subtitleEl!: HTMLSpanElement;
-    private _min = 0;
-    private _max = 100;
-    private _step = 1;
-    private _value = 0;
+    /** The headless value/min/max/step adjustment with clamping (ADR 0004). */
+    private readonly _state = new SpinState();
     private _initialized = false;
 
     static get observedAttributes() {
@@ -21,28 +32,26 @@ export class AdwSpinRow extends HTMLElement {
     }
 
     get value(): number {
-        return this._value;
+        return this._state.value;
     }
 
     set value(v: number) {
-        const clamped = Math.min(this._max, Math.max(this._min, v));
-        // Round to step precision to avoid floating-point drift
-        const decimals = this._countDecimals(this._step);
-        this._value = parseFloat(clamped.toFixed(decimals));
-        if (this._input) {
-            this._input.value = this._formatValue(this._value);
-        }
-        this.setAttribute('value', String(this._value));
+        // Round to step precision BEFORE the core clamp so repeated stepping
+        // cannot accumulate floating-point drift (0.1 + 0.2 → 0.30000000000000004).
+        this._state.setValue(this._roundToStep(v));
+        this._syncValue();
     }
 
     connectedCallback() {
         if (this._initialized) return;
         this._initialized = true;
 
-        this._min = parseFloat(this.getAttribute('min') || '0');
-        this._max = parseFloat(this.getAttribute('max') || '100');
-        this._step = parseFloat(this.getAttribute('step') || '1');
-        this._value = parseFloat(this.getAttribute('value') || String(this._min));
+        // Seed the headless adjustment BEFORE subscribing, so building the initial
+        // DOM below is not driven by a change notification.
+        this._state.setMin(parseFloat(this.getAttribute('min') || '0'));
+        this._state.setMax(parseFloat(this.getAttribute('max') || '100'));
+        this._state.setStep(parseFloat(this.getAttribute('step') || '1'));
+        this._state.setValue(this._roundToStep(parseFloat(this.getAttribute('value') || String(this._state.min))));
 
         const text = document.createElement('div');
         text.className = 'adw-row-text';
@@ -59,29 +68,34 @@ export class AdwSpinRow extends HTMLElement {
         const decBtn = document.createElement('button');
         decBtn.className = 'adw-spin-dec';
         decBtn.textContent = '−';
-        decBtn.addEventListener('click', () => this._adjust(-this._step));
+        decBtn.addEventListener('click', () => this._adjust(-this._state.step));
 
         const input = document.createElement('input');
         input.type = 'text';
-        input.value = this._formatValue(this._value);
+        input.value = this._formatValue(this._state.value);
         input.addEventListener('change', () => {
             const parsed = parseFloat(input.value);
             if (!Number.isNaN(parsed)) {
                 this.value = parsed;
                 this._emitChange();
             } else {
-                input.value = this._formatValue(this._value);
+                input.value = this._formatValue(this._state.value);
             }
         });
 
         const incBtn = document.createElement('button');
         incBtn.className = 'adw-spin-inc';
         incBtn.textContent = '+';
-        incBtn.addEventListener('click', () => this._adjust(this._step));
+        incBtn.addEventListener('click', () => this._adjust(this._state.step));
 
         control.append(decBtn, input, incBtn);
         this.replaceChildren(text, control);
         this._input = input;
+
+        // Every core change (a set, or a re-clamp after a bound moved) refreshes
+        // the display; `notify::value` is emitted at the interactive sites below.
+        this._state.subscribe(() => this._syncValue());
+
         this._renderText();
     }
 
@@ -94,19 +108,16 @@ export class AdwSpinRow extends HTMLElement {
         const num = parseFloat(val || '0');
         switch (name) {
             case 'value':
-                if (num !== this._value) {
-                    this._value = Math.min(this._max, Math.max(this._min, num));
-                    this._input.value = this._formatValue(this._value);
-                }
+                this._state.setValue(this._roundToStep(num));
                 break;
             case 'min':
-                this._min = num;
+                this._state.setMin(num);
                 break;
             case 'max':
-                this._max = num;
+                this._state.setMax(num);
                 break;
             case 'step':
-                this._step = num;
+                this._state.setStep(num);
                 break;
         }
     }
@@ -118,8 +129,9 @@ export class AdwSpinRow extends HTMLElement {
         this._subtitleEl.hidden = subtitle.length === 0;
     }
 
+    /** A stepper press — the interactive path, so it emits `notify::value`. */
     private _adjust(delta: number) {
-        this.value = this._value + delta;
+        this.value = this._state.value + delta;
         this._emitChange();
     }
 
@@ -127,11 +139,23 @@ export class AdwSpinRow extends HTMLElement {
         this.dispatchEvent(
             new CustomEvent('notify::value', {
                 bubbles: true,
-                detail: { value: this._value },
+                detail: { value: this._state.value },
             }),
         );
     }
 
+    /** Mirror the core value into the input display + the reflected attribute. */
+    private _syncValue() {
+        if (this._input) this._input.value = this._formatValue(this._state.value);
+        this.setAttribute('value', String(this._state.value));
+    }
+
+    private _roundToStep(n: number): number {
+        if (!Number.isFinite(n)) return n;
+        const decimals = this._countDecimals(this._state.step);
+        return decimals > 0 ? parseFloat(n.toFixed(decimals)) : n;
+    }
+
     private _countDecimals(n: number): number {
         const s = String(n);
         const dot = s.indexOf('.');
@@ -139,7 +163,7 @@ export class AdwSpinRow extends HTMLElement {
     }
 
     private _formatValue(v: number): string {
-        const decimals = this._countDecimals(this._step);
+        const decimals = this._countDecimals(this._state.step);
         return decimals > 0 ? v.toFixed(decimals) : String(v);
     }
 }

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

@@ -2,14 +2,31 @@
 // The web counterpart of Adw.ToastOverlay: it wraps arbitrary content and shows
 // transient `.adw-toast` banners (the Adw.Toast equivalent — a title, an
 // optional action button and a close affordance) layered over the bottom of its
-// own bounds, each auto-dismissing after a timeout.
+// own bounds.
+//
+// The QUEUE — Adw.ToastOverlay's one-at-a-time policy, the FIFO ordering and the
+// auto-dismiss lifecycle — is HEADLESS and lives in `@gjsify/adwaita-core` (ADR
+// 0004) as {@link AdwToastQueue}; this element composes it and keeps only the DOM
+// render half: building the `.adw-toast` strip on `onShow`, tearing it down on
+// `onHide`, and the enter/exit CSS transitions. `@gjsify/adwaita-nativescript`
+// composes the same core queue, so both ports share one behaviour.
+//
 // Adapted from Adwaita Web UI Framework (https://github.com/mclellac/adwaita-web).
 // Reference: refs/adwaita-web/adwaita-web/scss/_toast.scss, _toast_overlay.scss
-// Reference: refs/libadwaita/src/adw-toast-overlay.c, adw-toast.c (Adw.Toast.add_toast)
+// Reference: refs/libadwaita/src/adw-toast-overlay.c, adw-toast.c (add_toast queues,
+//   one toast is shown at a time, dismissing advances to the next)
 // Copyright (c) 2025 csm (adwaita-web). MIT License.
 // Copyright (c) GNOME contributors (libadwaita). LGPLv2.1+.
 // Modifications: Reimplemented as Web Component for @gjsify/adwaita-web;
-// extended addToast() with action button + close button + options API.
+// extended addToast() with action button + close button + options API; the
+// queue/auto-dismiss state machine composed from @gjsify/adwaita-core.
+
+import { AdwToast, AdwToastQueue } from '@gjsify/adwaita-core';
+import type { ToastScheduler, ToastTimerHandle } from '@gjsify/adwaita-core';
+
+// The timing seam is re-exported so a consumer can type a custom scheduler for
+// {@link AdwToastOverlay.scheduler} without depending on the core package.
+export type { ToastScheduler, ToastTimerHandle } from '@gjsify/adwaita-core';
 
 /** Options for {@link AdwToastOverlay.addToast}, mirroring Adw.Toast's properties. */
 export interface AdwToastOptions {
@@ -21,9 +38,47 @@ export interface AdwToastOptions {
     onAction?: () => void;
 }
 
+/** Default toast lifetime in SECONDS — this element's public unit (Adw.Toast:timeout). */
+const DEFAULT_TIMEOUT_SECONDS = 5;
+
+/** Exit-transition budget in ms; must stay in sync with `.adw-toast.hiding` in `_toast.scss`. */
+const TOAST_EXIT_MS = 300;
+
+/** The default timing seam: the browser's own timers. */
+const domScheduler: ToastScheduler = {
+    schedule: (callback, ms) => setTimeout(callback, ms) as unknown as ToastTimerHandle,
+    cancel: (handle) => clearTimeout(handle as ReturnType<typeof setTimeout>),
+};
+
 export class AdwToastOverlay extends HTMLElement {
     private _toasts!: HTMLDivElement;
     private _initialized = false;
+    /** The headless one-at-a-time + FIFO + auto-dismiss state machine (ADR 0004). */
+    private readonly _queue: AdwToastQueue;
+    /** The timing source the queue's auto-dismiss runs on — swappable, see {@link scheduler}. */
+    private _scheduler: ToastScheduler = domScheduler;
+    /** The strip currently mounted for {@link AdwToastQueue.current}, if any. */
+    private _currentEl: HTMLDivElement | null = null;
+    /** Per-toast action callbacks (the core toast descriptor carries only the label). */
+    private readonly _actions = new WeakMap<AdwToast, () => void>();
+
+    constructor() {
+        super();
+        this._queue = new AdwToastQueue({
+            // Indirect through `this._scheduler` so the timing source stays
+            // swappable after construction (the queue takes its scheduler once).
+            scheduler: {
+                schedule: (callback, ms) => this._scheduler.schedule(callback, ms),
+                cancel: (handle) => this._scheduler.cancel(handle),
+            },
+            onShow: (toast) => this._mountToast(toast),
+            // The core queue fires `onHide` BEFORE it shifts the next toast in, so
+            // `pending > 0` here means another toast takes this slot immediately:
+            // detach without the exit transition so exactly one strip is ever in
+            // the DOM. A last toast fades out instead.
+            onHide: () => this._unmountToast(this._queue.pending > 0),
+        });
+    }
 
     connectedCallback() {
         if (this._initialized) return;
@@ -41,12 +96,40 @@ export class AdwToastOverlay extends HTMLElement {
         this.replaceChildren(content, this._toasts);
     }
 
+    /**
+     * 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 {
+        return this._scheduler;
+    }
+
+    set scheduler(scheduler: ToastScheduler) {
+        this._scheduler = scheduler;
+    }
+
+    /** The toast currently on screen, or `null` when nothing is shown. */
+    get currentToast(): AdwToast | null {
+        return this._queue.current;
+    }
+
+    /** Number of toasts queued behind the visible one. */
+    get pendingToasts(): number {
+        return this._queue.pending;
+    }
+
     /**
      * 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 {
@@ -55,47 +138,53 @@ export class AdwToastOverlay extends HTMLElement {
         if (!this._toasts) this.connectedCallback();
 
         // Back-compat: the original signature was addToast(title, timeoutMs).
-        const opts: AdwToastOptions =
-            typeof options === 'number' ? { timeout: options / 1000 } : options;
-        const timeoutSeconds = opts.timeout ?? 5;
+        const opts: AdwToastOptions = typeof options === 'number' ? { timeout: options / 1000 } : options;
+
+        // This element's public timeout unit is SECONDS (Adw.Toast:timeout); the
+        // headless descriptor counts milliseconds.
+        const toast = new AdwToast(title, {
+            timeout: (opts.timeout ?? DEFAULT_TIMEOUT_SECONDS) * 1000,
+            buttonLabel: opts.buttonLabel,
+        });
+        if (opts.onAction) this._actions.set(toast, opts.onAction);
+
+        this._queue.add(toast);
+    }
+
+    /** Dismiss the visible toast early; the next queued toast takes its place. */
+    dismiss(): void {
+        this._queue.dismiss();
+    }
 
-        const toast = document.createElement('div');
-        toast.className = 'adw-toast';
+    /** Dismiss the visible toast and discard everything still queued behind it. */
+    clearToasts(): void {
+        this._queue.clear();
+    }
+
+    /** Build + attach the strip for `toast` — the DOM half of the queue's `onShow`. */
+    private _mountToast(toast: AdwToast): void {
+        const el = document.createElement('div');
+        el.className = 'adw-toast';
 
         const wrapper = document.createElement('div');
         wrapper.className = 'adw-toast-content-wrapper';
 
         const titleEl = document.createElement('span');
         titleEl.className = 'adw-toast-title';
-        titleEl.textContent = title;
+        titleEl.textContent = toast.title;
         wrapper.appendChild(titleEl);
-        toast.appendChild(wrapper);
-
-        let dismissTimer = 0;
-        const dismiss = (): void => {
-            if (dismissTimer) {
-                clearTimeout(dismissTimer);
-                dismissTimer = 0;
-            }
-            toast.classList.remove('visible');
-            toast.classList.add('hiding');
-            toast.addEventListener('transitionend', () => toast.remove(), { once: true });
-            // Fallback if transitionend doesn't fire (e.g. reduced motion).
-            setTimeout(() => {
-                if (toast.parentNode) toast.remove();
-            }, 300);
-        };
-
-        if (opts.buttonLabel) {
+        el.appendChild(wrapper);
+
+        if (toast.hasButton) {
             const button = document.createElement('button');
             button.type = 'button';
             button.className = 'adw-toast-action-button';
-            button.textContent = opts.buttonLabel;
+            button.textContent = toast.buttonLabel;
             button.addEventListener('click', () => {
-                opts.onAction?.();
-                dismiss();
+                this._actions.get(toast)?.();
+                this._queue.dismiss();
             });
-            toast.appendChild(button);
+            el.appendChild(button);
         }
 
         // Close affordance — a CSS-drawn "×" (no symbolic close icon ships in the
@@ -104,20 +193,43 @@ export class AdwToastOverlay extends HTMLElement {
         close.type = 'button';
         close.className = 'adw-toast-close-button';
         close.setAttribute('aria-label', 'Close');
-        close.addEventListener('click', dismiss);
-        toast.appendChild(close);
+        close.addEventListener('click', () => this._queue.dismiss());
+        el.appendChild(close);
 
-        this._toasts.appendChild(toast);
+        this._toasts.appendChild(el);
+        this._currentEl = el;
 
         // Trigger the enter animation on the next frame.
         requestAnimationFrame(() => {
-            toast.classList.add('visible');
+            el.classList.add('visible');
         });
+    }
 
-        // Auto-dismiss after the timeout (0 = stay until manually dismissed).
-        if (timeoutSeconds > 0) {
-            dismissTimer = setTimeout(dismiss, timeoutSeconds * 1000) as unknown as number;
+    /**
+     * 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(immediate: boolean): void {
+        const el = this._currentEl;
+        this._currentEl = null;
+        if (!el) return;
+
+        if (immediate) {
+            el.remove();
+            return;
         }
+
+        el.classList.remove('visible');
+        el.classList.add('hiding');
+        el.addEventListener('transitionend', () => el.remove(), { once: true });
+        // Fallback if transitionend doesn't fire (e.g. reduced motion). Routed
+        // through the injected scheduler so the whole lifecycle is deterministic
+        // when a fake clock is installed.
+        this._scheduler.schedule(() => {
+            if (el.parentNode) el.remove();
+        }, TOAST_EXIT_MS);
     }
 }
 

package/src/elements/adw-toggle-group.ts

@@ -8,11 +8,22 @@
 //   style classes).
 // Events: `notify::active` (CustomEvent, bubbles, `detail = { active }`) when the
 //   active toggle changes — mirrors the Adw.ToggleGroup `active` GObject property.
+//
+// The SELECTION state machine (the segment list plus the guarded, no-op-on-same
+// active index) is HEADLESS and lives in `@gjsify/adwaita-core` (ADR 0004) as
+// {@link ToggleGroupState}; this element composes it and keeps only the DOM render
+// half — building the buttons, the active pill / `aria-pressed` reflection, and
+// the `notify::active` event. `@gjsify/adwaita-nativescript` composes the same
+// state machine, so both ports share one behaviour.
+//
 // Reference: refs/libadwaita/src/adw-toggle-group.c (AdwToggleGroup behaviour)
 // Reference: refs/libadwaita/src/stylesheet/widgets/_toggle-group.scss
 // Reference: refs/adwaita-web/adwaita-web/scss/_toggle_group.scss
 // Copyright (c) GNOME contributors (libadwaita). LGPLv2.1+.
-// Modifications: Implemented as a Web Component for @gjsify/adwaita-web.
+// Modifications: Implemented as a Web Component for @gjsify/adwaita-web; the
+// selection state machine composed from @gjsify/adwaita-core.
+
+import { ToggleGroupState } from '@gjsify/adwaita-core';
 
 /** A single toggle. Children of <adw-toggle-group>; consumed at connect time. */
 export class AdwToggle extends HTMLElement {
@@ -24,7 +35,8 @@ export class AdwToggle extends HTMLElement {
 export class AdwToggleGroup extends HTMLElement {
     private _innerEl!: HTMLDivElement;
     private _buttons: HTMLButtonElement[] = [];
-    private _active = 0;
+    /** The headless segment list + guarded selection state machine (ADR 0004). */
+    private readonly _state = new ToggleGroupState();
     private _initialized = false;
 
     static get observedAttributes() {
@@ -33,7 +45,7 @@ export class AdwToggleGroup extends HTMLElement {
 
     /** Zero-based index of the active toggle. */
     get active(): number {
-        return this._active;
+        return this._state.selected;
     }
 
     set active(value: number) {
@@ -76,18 +88,21 @@ export class AdwToggleGroup extends HTMLElement {
         this._innerEl.append(...this._buttons);
         this.replaceChildren(this._innerEl);
 
-        this._active = this._readActiveAttr();
+        // Hand the segments to the headless state machine (it needs the count to
+        // bound the selection), then seed the active index from the attribute.
+        this._state.setLabels(
+            toggles.map((toggle) => toggle.getAttribute('label') || toggle.getAttribute('icon-name') || ''),
+        );
+        this._state.subscribe(() => this._render());
+        this._state.setSelected(this._readActiveAttr());
         this._render();
     }
 
     attributeChangedCallback(name: string) {
         if (!this._initialized) return;
         if (name === 'active') {
-            const next = this._readActiveAttr();
-            if (next !== this._active) {
-                this._active = next;
-                this._render();
-            }
+            // A no-op / out-of-range index is rejected by the core state machine.
+            this._state.setSelected(this._readActiveAttr());
             return;
         }
         // flat / round are styling-only.
@@ -97,25 +112,26 @@ export class AdwToggleGroup extends HTMLElement {
     private _readActiveAttr(): number {
         const raw = Number.parseInt(this.getAttribute('active') ?? '0', 10);
         if (Number.isNaN(raw)) return 0;
-        const max = Math.max(0, this._buttons.length - 1);
+        const max = Math.max(0, this._state.count - 1);
         return Math.min(Math.max(raw, 0), max);
     }
 
     private _selectIndex(index: number): void {
-        if (index === this._active) return;
-        this._active = index;
+        // The core state machine guards the no-op/out-of-range cases and notifies
+        // the subscriber (which re-renders) only on a real change.
+        if (!this._state.setSelected(index)) return;
         // Keep the attribute in sync without re-entering via the guarded
         // attributeChangedCallback (value already matches, so it no-ops).
         this.setAttribute('active', String(index));
-        this._render();
         this.dispatchEvent(new CustomEvent('notify::active', { bubbles: true, detail: { active: index } }));
     }
 
     private _render(): void {
         this.classList.toggle('flat', this.hasAttribute('flat'));
         this.classList.toggle('round', this.hasAttribute('round'));
+        const active = this._state.selected;
         this._buttons.forEach((btn, index) => {
-            const isActive = index === this._active;
+            const isActive = index === active;
             btn.classList.toggle('active', isActive);
             btn.setAttribute('aria-pressed', String(isActive));
         });

package/src/test.browser.mts

@@ -11,7 +11,9 @@ import { AdwButtonRowTest } from './adw-button-row.spec.js';
 import { AdwDataGridTest } from './adw-data-grid.spec.js';
 import { AdwDialogTest } from './adw-dialog.spec.js';
 import { AdwDropDownTest } from './adw-drop-down.spec.js';
+import { AdwRowStateTest } from './adw-row-state.spec.js';
 import { AdwTabViewTest } from './adw-tab-view.spec.js';
+import { AdwToastOverlayTest } from './adw-toast-overlay.spec.js';
 import { AdwViewSwitcherBarTest } from './adw-view-switcher-bar.spec.js';
 import { AdwStyleIsolationTest } from './style-isolation.spec.js';
 
@@ -20,7 +22,9 @@ run({
     AdwDataGridTest,
     AdwDialogTest,
     AdwDropDownTest,
+    AdwRowStateTest,
     AdwTabViewTest,
+    AdwToastOverlayTest,
     AdwViewSwitcherBarTest,
     AdwStyleIsolationTest,
 });