@lavalogic/scoria 0.36.0 → 0.37.0

package/dist/Components/VerticalTabGroupButton.svelte

@@ -4,72 +4,33 @@
 	lang="ts"
 	generics="Args"
 >
-	import { devCatch } from '../Helpers/Helpers.svelte.js';
+	import { useAsyncFlag } from '../Helpers/AsyncFlag.svelte.js';
 	import { Colour } from '../scss/colours.js';
 	import { Size } from '../Types/Internal/Size.js';
 	import Icon from './Icon.svelte';
 	import type { TabGroupButtonProps } from './TabGroupButtonProps.js';
 
-	let { option, selected }: TabGroupButtonProps<Args> = $props();
+	const { option, selected }: TabGroupButtonProps<Args> = $props();
 
-	let disabled = $state(true);
-	let visible = $state(true);
-	let isValid = $state(true);
-
-	$effect(() => {
-		if (typeof option.isValid === 'boolean') {
-			isValid = option.isValid;
-		} else {
-			option.isValid
-				?.then((v) => {
-					isValid = v;
-				})
-				.catch(devCatch);
-		}
-	});
-	$effect(() => {
-		if (typeof option.disabled === 'boolean') {
-			disabled = option.disabled;
-		} else if (option.disabled == undefined) {
-			disabled = false;
-		} else {
-			option.disabled
-				.then((v) => {
-					disabled = v;
-				})
-				.catch(devCatch);
-		}
-	});
-
-	$effect(() => {
-		if (typeof option.visible === 'boolean') {
-			visible = option.visible;
-		} else if (option.visible == undefined) {
-			visible = true;
-		} else {
-			option.visible
-				.then((v) => {
-					visible = v;
-				})
-				.catch(devCatch);
-		}
-	});
+	const isValid = useAsyncFlag(() => option.isValid, true);
+	const disabled = useAsyncFlag(() => option.disabled, false);
+	const visible = useAsyncFlag(() => option.visible, true);
 </script>
 
 <button
 	class:selected
-	{disabled}
+	disabled={disabled.value}
 	onclick={() => {
 		option.onclick();
 	}}
 	type="button"
 	class="tab"
-	class:invalid={!isValid}
-	class:hidden={!visible}
+	class:invalid={!isValid.value}
+	class:hidden={!visible.value}
 >
 	<div
 		class="bordered"
-		class:invalid={!isValid}
+		class:invalid={!isValid.value}
 	>
 		{#if option.iconLeft}
 			<Icon
@@ -78,7 +39,7 @@
 			/>
 		{/if}
 		{option.label}
-		{#if !isValid}
+		{#if !isValid.value}
 			<Icon
 				name="error"
 				colour={Colour['$error-border']}
@@ -123,7 +84,7 @@
 .tab .bordered {
   border-radius: 4px;
   padding: 0.5rem 0.75rem;
-  margin-bottom: 0.25rem;
+  margin-bottom: 0.375rem;
   transition: border-color ease-out 0.15s 0s, background-color ease-out 0.15s 0s, color ease-out 0.15s 0s, fill ease-out 0.15s 0s;
   white-space: nowrap;
   display: flex;

package/dist/Components/VerticalTabGroupProps.d.ts

@@ -1,10 +1,23 @@
+import type { ScoriaStorageKey } from '../Types/Internal/Misc.js';
 import type { TabOption } from '../Types/Internal/TabOption.js';
+/**
+ * Props for VerticalTabGroup, the top-aligned tab strip with content
+ * pane below. Supports sessionStorage-backed history when `name` is set.
+ */
 export interface VerticalTabGroupProps<CommonDenominator> {
-    name?: string;
-    tabs: Array<TabOption<CommonDenominator>>;
+    /** When set, the last selected tab is persisted under
+     *  `scoria-vertical-tab-group:${name}:active-tab` in sessionStorage. */
+    name?: ScoriaStorageKey;
+    /** The tabs to render. Keyed by `option.label`. */
+    tabs: ReadonlyArray<TabOption<CommonDenominator>>;
+    /** Currently selected tab. */
     selected?: TabOption<CommonDenominator>;
+    /** Inline style passthrough; consider `style:` directives at call site instead. */
     style?: string;
+    /** Disable internal scroll containers. */
     noscroll?: boolean;
+    /** Empty-state message shown when no tab is selected. */
     noTabMessage?: string;
+    /** Suppress on-mount history restore even when `name` is set. */
     nohistory?: boolean;
 }

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