@lavalogic/scoria 0.35.0 → 0.37.0

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

@@ -1,51 +1,135 @@
+/**
+ * Application context driving the global `AlertModal` host.
+ *
+ * The class exposes two public entry points - {@link AlertContext.alert}
+ * and {@link AlertContext.prompt} - each of which configures the modal
+ * labels, body and callbacks then flips `showModal` to `true`. The
+ * visual host (`Components/Contexts/AlertModal.svelte`, mounted by
+ * `Components/Base/ContextWrapper.svelte`) renders the modal and
+ * wires the three button callbacks (`onYes`, `onNo`, `onOther`).
+ *
+ * Conforms to the canonical scoria context pattern:
+ * - `static readonly identifier = Symbol()` registered through
+ *   `setContext`/`getContext`.
+ * - Private runes-backed fields (`_x = $state(...)`) exposed via
+ *   getter / private setter pairs.
+ *
+ * Note: `onYes`/`onNo`/`onOther` are public arrow-typed class fields.
+ * The arrows re-bind `this`, so they may safely reassign
+ * `this.showModal = false` via the private setter even when invoked
+ * detached from the instance (e.g. as event handlers).
+ */
 export declare class AlertContext {
+    /** Stable lookup symbol used by `getContext`/`setContext`. */
     static readonly identifier: unique symbol;
     private _header;
+    /** Modal header text. Defaults to `'Confirmation'`. */
     get header(): string;
     private set header(value);
     private _body;
+    /** Modal body text. Set by {@link AlertContext.alert} / {@link AlertContext.prompt}. */
     get body(): string;
     private set body(value);
     private _footer;
+    /** Optional modal footer. `null` hides the footer slot. */
     get footer(): string | null;
     private set footer(value);
     private _yesLabel;
+    /** Confirm-button label. Default is `'Yes'` for prompts, `'Okay'` for alerts. */
     get yesLabel(): string;
     private set yesLabel(value);
     private _noLabel;
+    /** Cancel-button label. `null` hides the button (alert-only mode). */
     get noLabel(): string | null;
     private set noLabel(value);
     private _otherLabel;
+    /** Tertiary-button label. `null` hides the button. */
     get otherLabel(): string | null;
     private set otherLabel(value);
     private _showModal;
+    /** Whether the modal is currently visible. */
     get showModal(): boolean;
     private set showModal(value);
     private _mandatory;
+    /**
+     * If `true`, the modal cannot be dismissed via Escape or
+     * background click. The host must reply through one of the
+     * configured buttons.
+     */
     get mandatory(): boolean;
     private set mandatory(value);
     private _onYes;
+    /**
+     * Click handler for the confirm button. Closes the modal, invokes
+     * the consumer-supplied callback if any, then clears the stored
+     * callbacks so the closures (and anything they captured) can be
+     * garbage-collected. Async consumer callbacks are awaited
+     * implicitly via `void`.
+     */
     onYes: () => void;
     private _onNo;
+    /** Click handler for the cancel button. See {@link AlertContext.onYes}. */
     onNo: () => void;
     private _onOther;
+    /** Click handler for the tertiary button. See {@link AlertContext.onYes}. */
     onOther: () => void;
     private resetState;
-    alert: (body: string, props?: IAlertProps) => void;
-    prompt: (body: string, props: IPromptProps) => void;
+    /**
+     * Shows an alert modal (single confirm button). Resets all prior
+     * state, then applies the supplied {@link AlertProps}.
+     */
+    alert: (body: string, props?: AlertProps) => void;
+    /**
+     * Shows a prompt modal (confirm + cancel + optional tertiary).
+     * Resets all prior state, then applies the supplied
+     * {@link PromptProps}.
+     */
+    prompt: (body: string, props: PromptProps) => void;
 }
-export interface IAlertProps {
+/**
+ * Optional configuration for {@link AlertContext.alert}.
+ */
+export interface AlertProps {
+    /** Modal header text. Defaults to `'Confirmation'` if omitted. */
     header?: string;
+    /** Optional modal footer. */
     footer?: string;
-    onYes?: () => void;
+    /** Callback invoked when the user clicks the confirm button. */
+    onYes?: () => void | Promise<void>;
+    /** Confirm-button label. Defaults to `'Okay'` if omitted. */
     yesLabel?: string;
+    /** If `true`, the modal cannot be dismissed without clicking a button. */
     mandatory?: boolean;
 }
-export interface IPromptProps extends IAlertProps {
-    onYes: () => void;
-    onNo?: () => void;
-    onOther?: () => void;
+/**
+ * Required configuration for {@link AlertContext.prompt}. `onYes`
+ * is required (because a prompt without an explicit confirm path is
+ * meaningless); the cancel and tertiary buttons are independently
+ * optional.
+ */
+export interface PromptProps extends AlertProps {
+    /** Required confirm callback. */
+    onYes: () => void | Promise<void>;
+    /** Optional cancel callback. */
+    onNo?: () => void | Promise<void>;
+    /** Optional tertiary callback. */
+    onOther?: () => void | Promise<void>;
+    /** Cancel-button label. Defaults to `'No'` if omitted. */
     noLabel?: string;
+    /** Tertiary-button label. The button is hidden when omitted. */
     otherLabel?: string;
+    /** If `true`, the modal cannot be dismissed without clicking a button. */
     mandatory?: boolean;
 }
+/**
+ * Legacy `I`-prefixed alias for {@link AlertProps}. Prefer
+ * `AlertProps` in new code; this re-export is kept for backwards
+ * compatibility with existing consumers.
+ */
+export type IAlertProps = AlertProps;
+/**
+ * Legacy `I`-prefixed alias for {@link PromptProps}. Prefer
+ * `PromptProps` in new code; this re-export is kept for backwards
+ * compatibility with existing consumers.
+ */
+export type IPromptProps = PromptProps;

package/dist/Contexts/AlertContext.svelte.js

@@ -1,6 +1,29 @@
+/**
+ * Application context driving the global `AlertModal` host.
+ *
+ * The class exposes two public entry points - {@link AlertContext.alert}
+ * and {@link AlertContext.prompt} - each of which configures the modal
+ * labels, body and callbacks then flips `showModal` to `true`. The
+ * visual host (`Components/Contexts/AlertModal.svelte`, mounted by
+ * `Components/Base/ContextWrapper.svelte`) renders the modal and
+ * wires the three button callbacks (`onYes`, `onNo`, `onOther`).
+ *
+ * Conforms to the canonical scoria context pattern:
+ * - `static readonly identifier = Symbol()` registered through
+ *   `setContext`/`getContext`.
+ * - Private runes-backed fields (`_x = $state(...)`) exposed via
+ *   getter / private setter pairs.
+ *
+ * Note: `onYes`/`onNo`/`onOther` are public arrow-typed class fields.
+ * The arrows re-bind `this`, so they may safely reassign
+ * `this.showModal = false` via the private setter even when invoked
+ * detached from the instance (e.g. as event handlers).
+ */
 export class AlertContext {
+    /** Stable lookup symbol used by `getContext`/`setContext`. */
     static identifier = Symbol();
     _header = $state('Confirmation');
+    /** Modal header text. Defaults to `'Confirmation'`. */
     get header() {
         return this._header;
     }
@@ -8,6 +31,7 @@ export class AlertContext {
         this._header = v;
     }
     _body = $state('');
+    /** Modal body text. Set by {@link AlertContext.alert} / {@link AlertContext.prompt}. */
     get body() {
         return this._body;
     }
@@ -15,6 +39,7 @@ export class AlertContext {
         this._body = v;
     }
     _footer = $state(null);
+    /** Optional modal footer. `null` hides the footer slot. */
     get footer() {
         return this._footer;
     }
@@ -22,6 +47,7 @@ export class AlertContext {
         this._footer = v;
     }
     _yesLabel = $state('Yes');
+    /** Confirm-button label. Default is `'Yes'` for prompts, `'Okay'` for alerts. */
     get yesLabel() {
         return this._yesLabel;
     }
@@ -29,6 +55,7 @@ export class AlertContext {
         this._yesLabel = v;
     }
     _noLabel = $state(null);
+    /** Cancel-button label. `null` hides the button (alert-only mode). */
     get noLabel() {
         return this._noLabel;
     }
@@ -36,6 +63,7 @@ export class AlertContext {
         this._noLabel = v;
     }
     _otherLabel = $state(null);
+    /** Tertiary-button label. `null` hides the button. */
     get otherLabel() {
         return this._otherLabel;
     }
@@ -43,6 +71,7 @@ export class AlertContext {
         this._otherLabel = v;
     }
     _showModal = $state(false);
+    /** Whether the modal is currently visible. */
     get showModal() {
         return this._showModal;
     }
@@ -50,6 +79,11 @@ export class AlertContext {
         this._showModal = v;
     }
     _mandatory = $state(false);
+    /**
+     * If `true`, the modal cannot be dismissed via Escape or
+     * background click. The host must reply through one of the
+     * configured buttons.
+     */
     get mandatory() {
         return this._mandatory;
     }
@@ -57,19 +91,40 @@ export class AlertContext {
         this._mandatory = v;
     }
     _onYes = undefined;
+    /**
+     * Click handler for the confirm button. Closes the modal, invokes
+     * the consumer-supplied callback if any, then clears the stored
+     * callbacks so the closures (and anything they captured) can be
+     * garbage-collected. Async consumer callbacks are awaited
+     * implicitly via `void`.
+     */
     onYes = () => {
         this.showModal = false;
-        this._onYes?.();
+        const cb = this._onYes;
+        this._onYes = undefined;
+        this._onNo = undefined;
+        this._onOther = undefined;
+        void cb?.();
     };
     _onNo = undefined;
+    /** Click handler for the cancel button. See {@link AlertContext.onYes}. */
     onNo = () => {
         this.showModal = false;
-        this._onNo?.();
+        const cb = this._onNo;
+        this._onYes = undefined;
+        this._onNo = undefined;
+        this._onOther = undefined;
+        void cb?.();
     };
     _onOther = undefined;
+    /** Click handler for the tertiary button. See {@link AlertContext.onYes}. */
     onOther = () => {
         this.showModal = false;
-        this._onOther?.();
+        const cb = this._onOther;
+        this._onYes = undefined;
+        this._onNo = undefined;
+        this._onOther = undefined;
+        void cb?.();
     };
     resetState = () => {
         this._body = '';
@@ -82,8 +137,11 @@ export class AlertContext {
         this._onNo = undefined;
         this._onOther = undefined;
     };
+    /**
+     * Shows an alert modal (single confirm button). Resets all prior
+     * state, then applies the supplied {@link AlertProps}.
+     */
     alert = (body, props) => {
-        // debugger;
         this.resetState();
         this._body = body;
         if (props) {
@@ -93,7 +151,7 @@ export class AlertContext {
             if (props.footer) {
                 this._footer = props.footer;
             }
-            this._yesLabel = props.yesLabel || 'Okay';
+            this._yesLabel = props.yesLabel ?? 'Okay';
             this._onYes = props.onYes;
         }
         else {
@@ -102,6 +160,11 @@ export class AlertContext {
         this.mandatory = props?.mandatory ?? false;
         this.showModal = true;
     };
+    /**
+     * Shows a prompt modal (confirm + cancel + optional tertiary).
+     * Resets all prior state, then applies the supplied
+     * {@link PromptProps}.
+     */
     prompt = (body, props) => {
         this.resetState();
         this._body = body;
@@ -114,7 +177,7 @@ export class AlertContext {
         if (props.yesLabel) {
             this._yesLabel = props.yesLabel;
         }
-        this._noLabel = props.noLabel || 'No';
+        this._noLabel = props.noLabel ?? 'No';
         if (props.otherLabel) {
             this._otherLabel = props.otherLabel;
         }

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

@@ -1,22 +1,68 @@
+/**
+ * Application context driving the global `ContextMenu` host.
+ *
+ * The class exposes {@link ContextMenuContext.openContextMenu} and
+ * {@link ContextMenuContext.closeMenu} as the only public mutators.
+ * Position (`x`, `y`), `items`, and `showMenu` are read-only from
+ * outside the class to keep the open-flow centralised.
+ */
 export declare class ContextMenuContext {
+    /** Stable lookup symbol used by `getContext`/`setContext`. */
     static readonly identifier: unique symbol;
+    /**
+     * Monotonically increasing open-count used to bail out of stale
+     * {@link ContextMenuContext.openContextMenu} calls when the user
+     * opens a second menu before the first one's reopen-delay has
+     * elapsed.
+     */
+    private openVersion;
     private _x;
+    /** Menu x-coordinate in viewport-relative CSS pixels. */
     get x(): number;
-    set x(v: number);
+    private set x(value);
     private _y;
+    /** Menu y-coordinate in viewport-relative CSS pixels. */
     get y(): number;
-    set y(v: number);
+    private set y(value);
     private _items;
-    get items(): Array<IContextMenuOption>;
-    set items(v: Array<IContextMenuOption>);
+    /** The current menu items. Mutate only via {@link ContextMenuContext.openContextMenu}. */
+    get items(): ReadonlyArray<ContextMenuOption>;
+    private set items(value);
     private _showMenu;
+    /** Whether the menu is currently visible. */
     get showMenu(): boolean;
-    set showMenu(v: boolean);
-    readonly openContextMenu: (e: MouseEvent, options: Array<IContextMenuOption>) => Promise<void>;
+    private set showMenu(value);
+    /**
+     * Opens the context menu at the position of the supplied
+     * `MouseEvent` (`clientX`/`clientY`). If a menu is already
+     * visible, closes it, waits {@link REOPEN_DELAY_MS} for the
+     * close animation to play, then opens the new one.
+     *
+     * Concurrent calls are version-guarded: only the most recent
+     * call's open-state survives the post-await write phase.
+     */
+    readonly openContextMenu: (e: MouseEvent, options: Array<ContextMenuOption>) => Promise<void>;
+    /**
+     * Closes the menu and clears the item list. Increments the open
+     * version so any in-flight {@link ContextMenuContext.openContextMenu}
+     * call resolves to a no-op.
+     */
     closeMenu: () => void;
 }
-export interface IContextMenuOption {
-    callback: () => void;
+/**
+ * A single context-menu row.
+ */
+export interface ContextMenuOption {
+    /** Click handler. May be async; the menu does not await the result. */
+    callback: () => void | Promise<void>;
+    /** Visible row label. */
     text: string;
+    /** When `true`, the row is shown greyed-out and ignores clicks. */
     disabled?: boolean;
 }
+/**
+ * Legacy `I`-prefixed alias for {@link ContextMenuOption}. Prefer
+ * `ContextMenuOption` in new code; this re-export is kept for
+ * backwards compatibility with existing consumers.
+ */
+export type IContextMenuOption = ContextMenuOption;

package/dist/Contexts/ContextMenuContext.svelte.js

@@ -1,6 +1,30 @@
+import { asyncSleep } from '../Helpers/Helpers.svelte.js';
+/**
+ * Delay in milliseconds that {@link ContextMenuContext.openContextMenu}
+ * waits after closing a previous menu before opening the next one,
+ * giving the close animation time to complete.
+ */
+const REOPEN_DELAY_MS = 100;
+/**
+ * Application context driving the global `ContextMenu` host.
+ *
+ * The class exposes {@link ContextMenuContext.openContextMenu} and
+ * {@link ContextMenuContext.closeMenu} as the only public mutators.
+ * Position (`x`, `y`), `items`, and `showMenu` are read-only from
+ * outside the class to keep the open-flow centralised.
+ */
 export class ContextMenuContext {
+    /** Stable lookup symbol used by `getContext`/`setContext`. */
     static identifier = Symbol();
+    /**
+     * Monotonically increasing open-count used to bail out of stale
+     * {@link ContextMenuContext.openContextMenu} calls when the user
+     * opens a second menu before the first one's reopen-delay has
+     * elapsed.
+     */
+    openVersion = 0;
     _x = $state(0);
+    /** Menu x-coordinate in viewport-relative CSS pixels. */
     get x() {
         return this._x;
     }
@@ -8,6 +32,7 @@ export class ContextMenuContext {
         this._x = v;
     }
     _y = $state(0);
+    /** Menu y-coordinate in viewport-relative CSS pixels. */
     get y() {
         return this._y;
     }
@@ -15,30 +40,51 @@ export class ContextMenuContext {
         this._y = v;
     }
     _items = $state([]);
+    /** The current menu items. Mutate only via {@link ContextMenuContext.openContextMenu}. */
     get items() {
         return this._items;
     }
     set items(v) {
-        this._items = v;
+        this._items = [...v];
     }
     _showMenu = $state(false);
+    /** Whether the menu is currently visible. */
     get showMenu() {
         return this._showMenu;
     }
     set showMenu(v) {
         this._showMenu = v;
     }
+    /**
+     * Opens the context menu at the position of the supplied
+     * `MouseEvent` (`clientX`/`clientY`). If a menu is already
+     * visible, closes it, waits {@link REOPEN_DELAY_MS} for the
+     * close animation to play, then opens the new one.
+     *
+     * Concurrent calls are version-guarded: only the most recent
+     * call's open-state survives the post-await write phase.
+     */
     openContextMenu = async (e, options) => {
+        const version = ++this.openVersion;
         if (this.showMenu) {
             this.closeMenu();
-            await new Promise((res) => setTimeout(res, 100));
+            await asyncSleep(REOPEN_DELAY_MS);
+            if (version !== this.openVersion) {
+                return;
+            }
         }
         this.items = options;
         this.x = e.clientX;
         this.y = e.clientY;
         this.showMenu = true;
     };
+    /**
+     * Closes the menu and clears the item list. Increments the open
+     * version so any in-flight {@link ContextMenuContext.openContextMenu}
+     * call resolves to a no-op.
+     */
     closeMenu = () => {
+        this.openVersion++;
         this.showMenu = false;
         this.items = [];
     };

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

@@ -1,11 +1,37 @@
 import type { RefWrapper } from '../Types/Internal/RefWrapper.js';
+/**
+ * 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 declare class TestContext {
+    /** Stable lookup symbol used by `getContext`/`setContext`. */
     static readonly identifier: unique symbol;
     private _value1;
+    /** Test-driver-visible reactive cell. */
     get value1(): RefWrapper<number>;
     set value1(v: RefWrapper<number>);
     private _value2;
+    /** Derived counter; accumulates `value1` whenever it is divisible by three. */
     get value2(): RefWrapper<number>;
     set value2(v: RefWrapper<number>);
-    useTestEffect(sourceValue: RefWrapper<number>): RefWrapper<number>;
+    constructor();
+    /**
+     * 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.
+     */
+    private useTestEffect;
 }

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;
 }