@lavalogic/scoria 0.36.0 → 0.37.0

package/dist/Contexts/TestContext.svelte.js

@@ -1,21 +1,49 @@
 import { refWrapper } from '../Helpers/Helpers.svelte.js';
 import { untrack } from 'svelte';
+/**
+ * Test-only fixture context demonstrating the `RefWrapper` +
+ * derived-effect pattern used elsewhere in scoria.
+ *
+ * Not part of the shipped public surface and not mounted by
+ * `ContextWrapper`. For a canonical context to copy from, see
+ * `AlertContext`, `ToastContext`, or `TooltipContext`.
+ *
+ * Non-canonical patterns intentionally present:
+ * - The `value2` field is initialised via `useTestEffect(value1)`
+ *   which calls `$effect`. `$effect` requires an active effect
+ *   scope. In real code, construct the context lazily inside the
+ *   consuming component (or `$effect.root`).
+ * - The setters on `value1`/`value2` are public for test
+ *   ergonomics. Real contexts keep their setters private.
+ */
 export class TestContext {
+    /** Stable lookup symbol used by `getContext`/`setContext`. */
     static identifier = Symbol();
     _value1 = $state(refWrapper(0));
+    /** Test-driver-visible reactive cell. */
     get value1() {
         return this._value1;
     }
     set value1(v) {
         this._value1 = v;
     }
-    _value2 = $state(this.useTestEffect(this.value1));
+    _value2;
+    /** Derived counter; accumulates `value1` whenever it is divisible by three. */
     get value2() {
         return this._value2;
     }
     set value2(v) {
         this._value2 = v;
     }
+    constructor() {
+        this._value2 = this.useTestEffect(this._value1);
+    }
+    /**
+     * Returns a `RefWrapper<number>` that accumulates the input
+     * `RefWrapper`'s `value` whenever the input becomes divisible by
+     * three. `untrack` keeps the write off the reactive dependency
+     * graph so the effect does not self-trigger.
+     */
     useTestEffect(sourceValue) {
         const internalState = refWrapper(0);
         $effect(() => {

package/dist/Contexts/ToastContext.svelte.d.ts

@@ -1,9 +1,37 @@
 import type { IdentifiableToastMessage } from '../Types/Internal/IdentifiableToastMessage.js';
+/**
+ * Application context driving the global `ToastContainer` host.
+ *
+ * The id counter is an instance field so multiple contexts (e.g.
+ * tests or HMR-reloaded hosts) do not collide. Verbose copy output
+ * (stack trace, cause chain) is gated on `$app/environment.dev`
+ * so production users cannot leak backend internals to the
+ * clipboard.
+ */
 export declare class ToastContext {
+    /** Stable lookup symbol used by `getContext`/`setContext`. */
     static readonly identifier: unique symbol;
+    private idIncrement;
     private _toasts;
-    get toasts(): Array<IdentifiableToastMessage>;
+    /**
+     * The currently visible toasts. Returned as a `ReadonlyArray` so
+     * consumers cannot mutate the internal queue; use {@link ToastContext.toast}
+     * to add and `IdentifiableToastMessage.close` to remove.
+     */
+    get toasts(): ReadonlyArray<IdentifiableToastMessage>;
     private set toasts(value);
+    private readonly timeoutHandles;
+    /**
+     * Queues a toast for display. Accepts `string`, `ReadonlyArray<string>`,
+     * `Error`, {@link ToastMessage}, the wrapped HTTP response shape, or
+     * anything else (rendered as "Unknown Error"). `null` / `undefined`
+     * are silently dropped.
+     */
     readonly toast: (message: unknown) => void;
+    /**
+     * Removes the toast with the given id from the visible queue and
+     * clears any pending auto-dismiss timer so the closure does not
+     * leak.
+     */
     private dismiss;
 }

package/dist/Contexts/ToastContext.svelte.js

@@ -1,6 +1,12 @@
+import { dev } from '$app/environment';
 import { getErrorMessage } from '../Helpers/Helpers.svelte.js';
 import { Validity } from '../Types/Internal/Validity.js';
-let idIncrement = 0;
+/**
+ * Narrows an unknown value to a wrapped-HTTP-response shape:
+ * `{ payload: { data: string } }`. Used by {@link ToastContext.toast}
+ * so that consumers can pass an unwrapped service response straight
+ * into the toast layer without an explicit cast.
+ */
 function isWrappedResponse(message) {
     return (message != null &&
         typeof message == 'object' &&
@@ -10,23 +16,73 @@ function isWrappedResponse(message) {
         'data' in message.payload &&
         typeof message.payload.data == 'string');
 }
+/**
+ * Narrows an object to {@link ToastMessage}: requires both a `result`
+ * field that is a recognised {@link Validity} value and a `message`
+ * field of type `string`. Previously this guard accepted any object
+ * with a `result` property; tightened to actually validate the shape.
+ */
+function isToastMessage(message) {
+    if (!('result' in message) || !('message' in message)) {
+        return false;
+    }
+    const m = message;
+    if (typeof m.message !== 'string') {
+        return false;
+    }
+    return (m.result === Validity.Invalid ||
+        m.result === Validity.Valid ||
+        m.result === Validity.Info ||
+        m.result === Validity.Warning ||
+        m.result === Validity.Neutral);
+}
+/**
+ * Default per-toast lifetime in milliseconds. Mirrors the value
+ * referenced from `ToastMessage.timeout` JSDoc.
+ */
+const DEFAULT_TOAST_TIMEOUT_MS = 10000;
+/**
+ * Application context driving the global `ToastContainer` host.
+ *
+ * The id counter is an instance field so multiple contexts (e.g.
+ * tests or HMR-reloaded hosts) do not collide. Verbose copy output
+ * (stack trace, cause chain) is gated on `$app/environment.dev`
+ * so production users cannot leak backend internals to the
+ * clipboard.
+ */
 export class ToastContext {
+    /** Stable lookup symbol used by `getContext`/`setContext`. */
     static identifier = Symbol();
+    idIncrement = 0;
     _toasts = $state([]);
+    /**
+     * The currently visible toasts. Returned as a `ReadonlyArray` so
+     * consumers cannot mutate the internal queue; use {@link ToastContext.toast}
+     * to add and `IdentifiableToastMessage.close` to remove.
+     */
     get toasts() {
         return this._toasts;
     }
     set toasts(v) {
-        this._toasts = v;
+        this._toasts = [...v];
     }
+    // The handles map is non-reactive bookkeeping; SvelteMap would just add overhead.
+    // eslint-disable-next-line svelte/prefer-svelte-reactivity
+    timeoutHandles = new Map();
+    /**
+     * Queues a toast for display. Accepts `string`, `ReadonlyArray<string>`,
+     * `Error`, {@link ToastMessage}, the wrapped HTTP response shape, or
+     * anything else (rendered as "Unknown Error"). `null` / `undefined`
+     * are silently dropped.
+     */
     toast = (message) => {
         if (message == null) {
             return;
         }
-        const id = idIncrement++;
+        const id = this.idIncrement++;
         const newMessage = (() => {
             const closeable = true;
-            const timeout = 10000;
+            const timeout = DEFAULT_TOAST_TIMEOUT_MS;
             if (Array.isArray(message)) {
                 return {
                     result: Validity.Info,
@@ -68,8 +124,8 @@ export class ToastContext {
                         },
                         getVerbose: () => getErrorMessage(message, {
                             includeUUID: true,
-                            includeCause: true,
-                            includeStack: true,
+                            includeCause: dev,
+                            includeStack: dev,
                         }),
                     };
                 }
@@ -86,18 +142,18 @@ export class ToastContext {
                         },
                     };
                 }
-            }
-            if (isWrappedResponse(message)) {
-                return {
-                    result: Validity.Info,
-                    closeable,
-                    timeout,
-                    message: message.payload.data,
-                    id,
-                    close: () => {
-                        this.dismiss(id);
-                    },
-                };
+                if (isWrappedResponse(message)) {
+                    return {
+                        result: Validity.Info,
+                        closeable,
+                        timeout,
+                        message: message.payload.data,
+                        id,
+                        close: () => {
+                            this.dismiss(id);
+                        },
+                    };
+                }
             }
             return {
                 result: Validity.Invalid,
@@ -108,17 +164,33 @@ export class ToastContext {
                 close: () => {
                     this.dismiss(id);
                 },
-                getVerbose: () => getErrorMessage(message),
+                getVerbose: () => getErrorMessage(message, {
+                    includeUUID: true,
+                    includeCause: dev,
+                    includeStack: dev,
+                }),
             };
         })();
-        this.toasts.push(newMessage);
+        this._toasts.push(newMessage);
         if (newMessage.timeout) {
-            setTimeout(() => {
+            const handle = setTimeout(() => {
+                this.timeoutHandles.delete(newMessage.id);
                 this.dismiss(newMessage.id);
             }, newMessage.timeout);
+            this.timeoutHandles.set(newMessage.id, handle);
         }
     };
+    /**
+     * Removes the toast with the given id from the visible queue and
+     * clears any pending auto-dismiss timer so the closure does not
+     * leak.
+     */
     dismiss(id) {
+        const handle = this.timeoutHandles.get(id);
+        if (handle !== undefined) {
+            clearTimeout(handle);
+            this.timeoutHandles.delete(id);
+        }
         const index = this._toasts.findIndex((it) => it.id === id);
         if (index != -1) {
             const [removed] = this._toasts.splice(index, 1);
@@ -126,6 +198,3 @@ export class ToastContext {
         }
     }
 }
-function isToastMessage(message) {
-    return 'result' in message;
-}

package/dist/Contexts/TooltipContext.svelte.d.ts

@@ -1,31 +1,98 @@
 import type { Delay } from '../Delay/Delay.js';
 import { Side } from '../Types/Internal/Side.js';
+/**
+ * Application context driving the global `Tooltip` host.
+ *
+ * The visual host (`Components/Contexts/Tooltip.svelte`, mounted by
+ * `Components/Base/ContextWrapper.svelte`) listens to `x`, `y`,
+ * `text`, `anchor`, and `isShowingTooltip` and renders the tooltip
+ * accordingly. Consumers (Button, Action, NavTab, ...) call
+ * {@link TooltipContext.showTooltip} on `mouseenter`/`focus` and
+ * {@link TooltipContext.hideTooltip} on `mouseleave`/`blur`/`click`
+ * and on component unmount.
+ *
+ * Conforms to the canonical scoria context pattern:
+ * - `static readonly identifier = Symbol()`.
+ * - Private runes-backed fields exposed via getter / private setter.
+ *
+ * Stale-tooltip cleanup contract: consumers are responsible for
+ * calling `hideTooltip` in their unmount handler when they have
+ * called `showTooltip` and the user has not yet moved focus or
+ * mouse away. Without this, a component that unmounts mid-hover
+ * leaves its tooltip visible indefinitely.
+ */
 export declare class TooltipContext {
+    /** Stable lookup symbol used by `getContext`/`setContext`. */
     static readonly identifier: unique symbol;
     private _x;
+    /** Tooltip x-coordinate in viewport-relative CSS pixels. */
     get x(): number;
     private set x(value);
     private _y;
+    /** Tooltip y-coordinate in viewport-relative CSS pixels. */
     get y(): number;
     private set y(value);
     private _text;
+    /**
+     * The text currently shown in the tooltip. `undefined` when the
+     * tooltip is hidden.
+     */
     get text(): string | undefined;
     private set text(value);
     private _anchor;
+    /** The side of the anchor element the tooltip arrow points to. */
     get anchor(): Side;
     private set anchor(value);
     private _isShowingTooltip;
+    /**
+     * Whether the visual host should render. The host treats this as
+     * a strict "draw / do not draw" toggle.
+     */
     get isShowingTooltip(): boolean;
     private set isShowingTooltip(value);
+    /**
+     * Tracks the pending show-tooltip debounce timer. Initialised to
+     * the sentinel value `undefined`; `clearTimeout(undefined)` is a
+     * documented no-op.
+     */
     private timeout;
+    /**
+     * Requests that the tooltip be shown with the given text, anchor
+     * side, and bounding rectangle. The actual draw is delayed by
+     * `props.delay` (typically `Delay.Default`) so transient hovers
+     * do not flash a tooltip.
+     *
+     * Any pending show-timer is cleared before scheduling the new
+     * one, so rapid hover transitions cancel cleanly.
+     */
     readonly showTooltip: (props: TooltipProps) => void;
-    hideTooltip: (value: string) => void;
+    /**
+     * Hides the tooltip if its current text matches the given value.
+     * The text-compare is a structural race-guard: when two
+     * consumers race show/hide on different labels, the wrong
+     * consumer's `hideTooltip` does not clobber the right
+     * consumer's `showTooltip`.
+     *
+     * Note: a future migration may switch this to a handle-based
+     * API returning an `Unsubscriber` from `showTooltip`. Tracked
+     * in the TooltipContext workorder.
+     */
+    readonly hideTooltip: (value: string) => void;
 }
+/**
+ * Configuration accepted by {@link TooltipContext.showTooltip}.
+ */
 export interface TooltipProps {
+    /** The visible tooltip text. */
     text: string;
+    /** Bounding rect of the anchor element (in viewport-relative pixels). */
     rect: DOMRect;
+    /** The side of the anchor the arrow points to. */
     arrow: Side;
+    /** Optional show-delay in milliseconds. */
     delay?: Delay;
+    /** Optional additional x-offset applied after anchor maths. */
     offsetX?: number;
+    /** Optional additional y-offset applied after anchor maths. */
     offsetY?: number;
 }

package/dist/Contexts/TooltipContext.svelte.js

@@ -1,7 +1,38 @@
 import { Side } from '../Types/Internal/Side.js';
+/**
+ * CSS arrow-half-width in pixels. Matches the `border-width` set
+ * on the `.arrow` pseudo-element in `Tooltip.svelte`. Centralised
+ * here so the layout maths and the visual styling cannot drift
+ * silently. When updating, also update the matching value in
+ * `Components/Contexts/Tooltip.svelte`.
+ */
+const ARROW_HALF_WIDTH_PX = 6;
+/**
+ * Application context driving the global `Tooltip` host.
+ *
+ * The visual host (`Components/Contexts/Tooltip.svelte`, mounted by
+ * `Components/Base/ContextWrapper.svelte`) listens to `x`, `y`,
+ * `text`, `anchor`, and `isShowingTooltip` and renders the tooltip
+ * accordingly. Consumers (Button, Action, NavTab, ...) call
+ * {@link TooltipContext.showTooltip} on `mouseenter`/`focus` and
+ * {@link TooltipContext.hideTooltip} on `mouseleave`/`blur`/`click`
+ * and on component unmount.
+ *
+ * Conforms to the canonical scoria context pattern:
+ * - `static readonly identifier = Symbol()`.
+ * - Private runes-backed fields exposed via getter / private setter.
+ *
+ * Stale-tooltip cleanup contract: consumers are responsible for
+ * calling `hideTooltip` in their unmount handler when they have
+ * called `showTooltip` and the user has not yet moved focus or
+ * mouse away. Without this, a component that unmounts mid-hover
+ * leaves its tooltip visible indefinitely.
+ */
 export class TooltipContext {
+    /** Stable lookup symbol used by `getContext`/`setContext`. */
     static identifier = Symbol();
     _x = $state(0);
+    /** Tooltip x-coordinate in viewport-relative CSS pixels. */
     get x() {
         return this._x;
     }
@@ -9,6 +40,7 @@ export class TooltipContext {
         this._x = v;
     }
     _y = $state(0);
+    /** Tooltip y-coordinate in viewport-relative CSS pixels. */
     get y() {
         return this._y;
     }
@@ -16,6 +48,10 @@ export class TooltipContext {
         this._y = v;
     }
     _text = $state();
+    /**
+     * The text currently shown in the tooltip. `undefined` when the
+     * tooltip is hidden.
+     */
     get text() {
         return this._text;
     }
@@ -23,6 +59,7 @@ export class TooltipContext {
         this._text = v;
     }
     _anchor = $state(Side.Top);
+    /** The side of the anchor element the tooltip arrow points to. */
     get anchor() {
         return this._anchor;
     }
@@ -30,27 +67,41 @@ export class TooltipContext {
         this._anchor = v;
     }
     _isShowingTooltip = $state(false);
+    /**
+     * Whether the visual host should render. The host treats this as
+     * a strict "draw / do not draw" toggle.
+     */
     get isShowingTooltip() {
         return this._isShowingTooltip;
     }
     set isShowingTooltip(v) {
         this._isShowingTooltip = v;
     }
-    timeout = -1;
+    /**
+     * Tracks the pending show-tooltip debounce timer. Initialised to
+     * the sentinel value `undefined`; `clearTimeout(undefined)` is a
+     * documented no-op.
+     */
+    timeout = undefined;
+    /**
+     * Requests that the tooltip be shown with the given text, anchor
+     * side, and bounding rectangle. The actual draw is delayed by
+     * `props.delay` (typically `Delay.Default`) so transient hovers
+     * do not flash a tooltip.
+     *
+     * Any pending show-timer is cleared before scheduling the new
+     * one, so rapid hover transitions cancel cleanly.
+     */
     showTooltip = (props) => {
         clearTimeout(this.timeout);
-        if (this.isShowingTooltip) {
-            this.isShowingTooltip = false;
-            this.text = undefined;
-        }
         this.text = props.text;
         this.anchor = props.arrow;
         const totalOffsetX = (props.offsetX ?? 0) +
             (props.arrow === Side.Top || props.arrow === Side.Bottom
                 ? props.rect.width / 2
                 : props.arrow === Side.Right
-                    ? -6 //  arrow width
-                    : props.rect.width + 6); // arrow width
+                    ? -ARROW_HALF_WIDTH_PX
+                    : props.rect.width + ARROW_HALF_WIDTH_PX);
         const totalOffsetY = (props.offsetY ?? 0) +
             (props.arrow === Side.Left || props.arrow === Side.Right
                 ? props.rect.height / 2
@@ -68,9 +119,21 @@ export class TooltipContext {
             this.isShowingTooltip = true;
         }
     };
+    /**
+     * Hides the tooltip if its current text matches the given value.
+     * The text-compare is a structural race-guard: when two
+     * consumers race show/hide on different labels, the wrong
+     * consumer's `hideTooltip` does not clobber the right
+     * consumer's `showTooltip`.
+     *
+     * Note: a future migration may switch this to a handle-based
+     * API returning an `Unsubscriber` from `showTooltip`. Tracked
+     * in the TooltipContext workorder.
+     */
     hideTooltip = (value) => {
         if (this.text === value) {
             clearTimeout(this.timeout);
+            this.timeout = undefined;
             this.isShowingTooltip = false;
             this.text = undefined;
         }

package/dist/Contexts/UntypedInputContext.svelte.d.ts

@@ -1,16 +1,65 @@
-export type StringCallback = (value: string) => boolean | Promise<boolean>;
 import type { Unsubscriber } from '../Types/Internal/Misc.js';
+/**
+ * Callback signature accepted by
+ * {@link UntypedInputContext.registerListener}. Returns - or
+ * resolves to - `true` to stop propagation, `false` to continue
+ * the chain.
+ */
+export type UntypedInputListener = (value: string) => boolean | Promise<boolean>;
+/**
+ * Legacy alias for {@link UntypedInputListener}. Prefer
+ * `UntypedInputListener` in new code; this re-export is kept for
+ * backwards compatibility with existing consumers.
+ */
+export type StringCallback = UntypedInputListener;
+/**
+ * Application context that buffers global keystrokes so a hardware
+ * barcode scanner (which delivers each character as a synthesised
+ * `keydown` and terminates with Enter) can be treated as a single
+ * "command" without occupying a visible focusable input.
+ *
+ * Security model:
+ * - Treats any sequence of keydowns terminated by `Enter`, while
+ *   focus is not inside an `INPUT`/`TEXTAREA`/`BUTTON`/`A`, as a
+ *   trusted command.
+ * - Synthetic events (`e.isTrusted === false`) are ignored to
+ *   blunt the easiest attack vector.
+ * - Listeners are run from most-recently registered to oldest,
+ *   and may short-circuit by returning `true`.
+ */
 export declare class UntypedInputContext {
-    private debug;
-    constructor(debug?: boolean);
+    private readonly debug;
+    /** Stable lookup symbol used by `getContext`/`setContext`. */
     static readonly identifier: unique symbol;
+    /**
+     * @param debug - When `true`, internal state transitions are
+     *   logged via `console.log`.
+     */
+    constructor(debug?: boolean);
     private readonly registeredListeners;
-    readonly registerListener: (listener: StringCallback) => Unsubscriber;
+    /**
+     * Registers a listener to receive each fully-buffered untyped
+     * value. Returns an {@link Unsubscriber} that removes it again.
+     */
+    readonly registerListener: (listener: UntypedInputListener) => Unsubscriber;
+    /**
+     * Fires the registered listeners in reverse-registration order
+     * with the current untyped value. Snapshots the listener array
+     * before iterating so a listener that mutates the registration
+     * set during its own invocation does not corrupt the loop.
+     * Short-circuits on the first listener that returns truthy.
+     */
     private readonly fire;
     private _untypedValue;
+    /** The current buffered untyped value. Cleared after fire and after debounce. */
     get untypedValue(): string;
     private set untypedValue(value);
     private debounceTimer;
-    private readonly tagNameSet;
+    /**
+     * Global `keydown` handler. Ignores synthetic events, passes
+     * through to inputs/buttons/links, buffers single-character
+     * keys, and fires the listener chain on `Enter` or after
+     * {@link UNTYPED_DEBOUNCE_MS} of idle.
+     */
     readonly handleGlobalKeydown: (e: KeyboardEvent) => void;
 }