@lavalogic/scoria 0.36.0 → 0.37.0

package/dist/Helpers/useTooltip.svelte.js

@@ -0,0 +1,62 @@
+import { TooltipContext } from '../Contexts/TooltipContext.svelte.js';
+import { Delay } from '../Delay/Delay.js';
+import { Side } from '../Types/Internal/Side.js';
+import { getContext } from 'svelte';
+/**
+ * Shared lifecycle for `TooltipContext`-driven tooltips. Centralises the
+ * `showTooltip` / `hideTooltip` calls on hover, the
+ * `hideTooltip`-on-click race-guard, and the unmount-time teardown that
+ * prevents a stuck tooltip when the anchor element churns mid-hover.
+ *
+ * Looks up `TooltipContext` once at initialisation time. When no context
+ * is mounted (or `text()` returns `undefined`), all handlers are no-ops.
+ *
+ * Must be called during component initialisation so it can register its
+ * `$effect` cleanup hook.
+ *
+ * @param options Thunks describing the tooltip text, arrow side, and delay.
+ * @returns A bundle of `onmouseenter` / `onmouseleave` / `onclick`
+ *          handlers ready to wire onto the anchor element.
+ */
+export function useTooltip(options) {
+    const tooltipContext = getContext(TooltipContext.identifier);
+    function hide() {
+        const t = options.text();
+        if (tooltipContext && t) {
+            tooltipContext.hideTooltip(t);
+        }
+    }
+    // Hide any tooltip we may have shown when the host component unmounts.
+    // Without this teardown a rapidly-churning host (toolbar, table row)
+    // can leave the global tooltip painting against a node that no longer
+    // exists.
+    $effect(() => {
+        return () => {
+            hide();
+        };
+    });
+    return {
+        onmouseenter: (e) => {
+            const t = options.text();
+            if (!tooltipContext || !t) {
+                return;
+            }
+            const rect = e.target?.getBoundingClientRect();
+            if (!rect) {
+                return;
+            }
+            tooltipContext.showTooltip({
+                text: t,
+                arrow: options.arrow?.() ?? Side.Top,
+                delay: options.delay?.() ?? Delay.Default,
+                rect,
+            });
+        },
+        onmouseleave: () => {
+            hide();
+        },
+        onclick: () => {
+            hide();
+        },
+    };
+}

package/dist/Types/Examples/ExampleModal.svelte

@@ -2,6 +2,7 @@
 
 <script lang="ts">
 	import DesktopModal from '../../Components/DesktopModal.svelte';
+	import { cssLength } from '../../Helpers/Helpers.svelte.js';
 	import Switch from '../../Components/Switch.svelte';
 	import type { DisplayDefModalProps } from '../../Components/Table/Types/Columns/Definitions/Display/AbstractDisplayDef.svelte.js';
 	import type { ExampleItem } from './ExampleItem.js';
@@ -10,7 +11,7 @@
 </script>
 
 <DesktopModal
-	width="1220px"
+	width={cssLength('1220px')}
 	headerLabel="Hello World"
 	{onclose}
 	{onsubmit}

package/dist/Types/Examples/ExampleSelectEnum.js

@@ -2,6 +2,6 @@ export const ExampleSelectEnum = {
     FirstOption: 'FirstOption',
     SecondOption: 'SecondOption',
     ThirdOption: 'ThirdOption',
-    FourthOption: 'FourthOption'
+    FourthOption: 'FourthOption',
 };
 Object.freeze(ExampleSelectEnum);

package/dist/Types/Internal/AsyncFlag.d.ts

@@ -0,0 +1,7 @@
+/**
+ * A prop that may be a bare value or a Promise of that value. Resolved at
+ * read-time by {@link useAsyncFlag}. Used pervasively across scoria's button,
+ * tab, and modal families for `isValid`, `disabled`, `visible`, and similar
+ * flag-style props.
+ */
+export type AsyncFlag<T> = T | Promise<T>;

package/dist/Types/Internal/AsyncFlag.js

@@ -0,0 +1 @@
+export {};

package/dist/Types/Internal/BigRadioOption.d.ts

@@ -1,5 +1,13 @@
+/**
+ * A single option in a `BigRadioSet`. The generic carries the
+ * concrete value type so the surrounding component can stay
+ * type-safe in its `onchange` callback.
+ */
 export interface BigRadioOption<T> {
+    /** Visible label. */
     label: string;
+    /** The option's value when selected. */
     value: T;
+    /** Optional helper text rendered alongside the label. */
     info?: string;
 }

package/dist/Types/Internal/ButtonProp.d.ts

@@ -1,11 +1,33 @@
+import type { AsyncFlag } from './AsyncFlag.js';
 import type { ColourSet } from '../../scss/colours.js';
 import type { HTMLButtonAttributes } from 'svelte/elements';
+/**
+ * Shape of a button-like configuration value used by modal footer
+ * arrays and similar config-driven button rows. Distinct from
+ * `ButtonProps` (the component prop interface for `Button.svelte`)
+ * and `CallbackButton` (the modal-callback variant carrying
+ * `left`/`disabled`).
+ */
 export interface ButtonProp {
+    /** Visible label; also wired through as `aria-label` / tooltip text. */
     label: string;
+    /** Optional colour bucket. Defaults to the consumer's surface default. */
     colourSet?: ColourSet;
-    callback?: () => void;
+    /** Click callback. May be async; consumers await the result. */
+    callback?: () => void | Promise<void>;
+    /** Native `type` attribute (`'button'` / `'submit'` / `'reset'`). */
     type?: HTMLButtonAttributes['type'];
+    /** Layout hint: push to one edge of the button row. */
     margin?: 'left' | 'right';
+    /**
+     * If set, the button can be activated remotely by typing the
+     * given barcode value through `UntypedInputContext`.
+     */
     barcodeValue?: string;
-    isValid?: boolean | Promise<boolean>;
+    /**
+     * AsyncFlag of a boolean. The button is rendered invalid when
+     * this resolves to false. Resolved through `useAsyncFlag` at
+     * the component level.
+     */
+    isValid?: AsyncFlag<boolean>;
 }

package/dist/Types/Internal/CallbackButton.d.ts

@@ -1,10 +1,22 @@
 import type { ButtonProps } from '../../Components/ButtonProps.js';
 import type { ColourSet } from '../../scss/colours.js';
+/**
+ * Button descriptor used by modal footers and similar
+ * callback-driven button arrays. Shares fields with `ButtonProp`
+ * but adds modal-specific `disabled` and `left` (left-aligned)
+ * affordances.
+ */
 export interface CallbackButton {
+    /** Visible label; also used as `aria-label`. */
     label: string;
+    /** Click callback. May be async; the modal awaits before closing. */
     callback?: () => void | Promise<void>;
+    /** Native `type` attribute (`'button'` / `'submit'` / `'reset'`). */
     type?: ButtonProps['type'];
+    /** Optional colour bucket. */
     colourSet?: ColourSet;
+    /** When `true`, the button is rendered disabled and ignores clicks. */
     disabled?: boolean;
+    /** When `true`, the button is laid out on the left edge of the footer. */
     left?: boolean;
 }

package/dist/Types/Internal/DateChange.d.ts

@@ -1,5 +1,13 @@
 import type { DatePickerType } from './DatePickerType.js';
+/**
+ * Granularity-tagged payload emitted by the date picker when the
+ * user updates a single component (year, month, day, ...). `type`
+ * identifies which component changed; `changedData` carries the
+ * new value at that granularity.
+ */
 export interface DateChange<T> {
+    /** Which granularity the change applies to. */
     type: DatePickerType;
+    /** The new value at the given granularity. */
     changedData: T;
 }

package/dist/Types/Internal/DatePickerType.d.ts

@@ -1,3 +1,8 @@
+/**
+ * Discriminator for date-picker change events. Identifies which
+ * granularity the change applies to. Note: values are lower-case
+ * to match the matching HTML input attribute conventions.
+ */
 export declare const DatePickerType: {
     readonly Year: "year";
     readonly Month: "month";

package/dist/Types/Internal/DatePickerType.js

@@ -1,9 +1,14 @@
+/**
+ * Discriminator for date-picker change events. Identifies which
+ * granularity the change applies to. Note: values are lower-case
+ * to match the matching HTML input attribute conventions.
+ */
 export const DatePickerType = {
     Year: 'year',
     Month: 'month',
     Day: 'day',
     Hours: 'hours',
     Minutes: 'minutes',
-    Seconds: 'seconds'
+    Seconds: 'seconds',
 };
 Object.freeze(DatePickerType);

package/dist/Types/Internal/IdentifiableToastMessage.d.ts

@@ -1,5 +1,13 @@
 import type { ToastMessage } from './ToastMessage.js';
+/**
+ * A {@link ToastMessage} that has been queued by `ToastContext`.
+ * The context stamps a unique `id` and an instance-scoped
+ * `close()` handler before exposing the message to the visual
+ * host.
+ */
 export interface IdentifiableToastMessage extends ToastMessage {
+    /** Per-context unique identifier. */
     readonly id: number;
+    /** Imperatively close this toast. */
     readonly close?: () => void;
 }

package/dist/Types/Internal/InputVariant.d.ts

@@ -1,3 +1,8 @@
+/**
+ * Surface-context variant for inputs. Switches between the
+ * standard (form-page) styling and tighter variants used inside
+ * modals and table cells.
+ */
 export declare const InputVariant: {
     readonly Default: "Default";
     readonly Modal: "Modal";

package/dist/Types/Internal/InputVariant.js

@@ -1,7 +1,12 @@
+/**
+ * Surface-context variant for inputs. Switches between the
+ * standard (form-page) styling and tighter variants used inside
+ * modals and table cells.
+ */
 export const InputVariant = {
     Default: 'Default',
     Modal: 'Modal',
     ModalThin: 'ModalThin',
-    Table: 'Table'
+    Table: 'Table',
 };
 Object.freeze(InputVariant);

package/dist/Types/Internal/Misc.d.ts

@@ -1,17 +1,108 @@
+/**
+ * Constrains a generic type parameter to the string keys of `T`,
+ * excluding the `null` value. Used by the grid select types to
+ * pick a value-property from a record shape.
+ */
 export type NonNullableKey<T> = T extends null ? never : string & keyof T;
+/**
+ * Like {@link NonNullableKey} but accepts any non-null shape; the
+ * generic value-prop alias used across the grid family.
+ */
 export type ValueProp<V> = V extends null ? never : keyof V & string;
+/**
+ * Function returned by registration calls that allows the caller
+ * to unregister later. Convention: zero-arg, returns nothing.
+ */
 export type Unsubscriber = () => void;
+/**
+ * CSS pixel count. Currently a plain numeric alias; a future
+ * Types-Internal pass will promote this to
+ * `BrandedNumber<'Pixels'>` once consumers (sizing tokens,
+ * tooltip x/y, table column widths) are audited.
+ */
 export type Pixels = number;
+/**
+ * Brand helper: produces a `string` subtype that carries a phantom
+ * tag of type `T`. Two branded strings with different tags are
+ * mutually unassignable at compile time but indistinguishable at
+ * runtime.
+ */
 export type BrandedString<T> = string & {
     __brand: T;
 };
+/** Brand helper for `number` values. See {@link BrandedString}. */
 export type BrandedNumber<T> = number & {
     __brand: T;
 };
+/**
+ * Brand helper for `number` values that are integers. Same shape
+ * as {@link BrandedNumber} but documents the integer constraint.
+ */
 export type BrandedInteger<T> = number & {
     __brand: T;
 };
+/**
+ * Branded CSS length string (e.g. `'10px'`, `'1rem'`, `'-50%'`).
+ *
+ * Used by positioning and sizing props that interpolate user-supplied
+ * length values into `style="..."` attributes or CSS custom
+ * properties. Branding prevents accidentally passing an unrelated
+ * `string` (such as a colour token or arbitrary text) where a CSS
+ * length is required.
+ *
+ * Use the `cssLength` helper (re-exported from `$lib`) for
+ * ergonomic construction.
+ */
+export type CssLength = BrandedString<'CssLength'>;
+/**
+ * Branded key used to namespace browser-storage entries written from
+ * inside scoria components (e.g. `StepForm`, `VerticalTabGroup`'s
+ * remembered active-tab index).
+ *
+ * Branding the key prevents accidentally colliding with unrelated
+ * keys or passing arbitrary user input as a storage namespace. Use
+ * the `scoriaStorageKey` helper (re-exported from `$lib`) for
+ * ergonomic construction.
+ */
+export type ScoriaStorageKey = BrandedString<'ScoriaStorageKey'>;
+/** ISO date-only string of the form `YYYY-MM-DD`. */
 export type InputDate = BrandedString<'InputDate'>;
+/** ISO date-time string of the form `YYYY-MM-DDTHH:MM:SS`. */
 export type InputDateWithTime = BrandedString<'InputDateWithTime'>;
+/** Date string formatted for the FloWMS SQL backend. */
 export type SQLDate = BrandedString<'SQLDate'>;
+/** Integer centimetre count. Used by dimension inputs. */
 export type Centimetres = BrandedInteger<'Centimetres'>;
+/**
+ * Branded string carrying a `crypto.randomUUID()`-grade identifier
+ * (RFC 4122 v4). Use `generateUUID` to produce values of this
+ * type. For non-security-sensitive short identifiers prefer
+ * `generateWeakId` which returns an unbranded string.
+ */
+export type Uuid = BrandedString<'Uuid'>;
+/**
+ * Brand for synthetic column ids — those that do not correspond to a
+ * key on the row type. Used by `RowSelectionDef`, `ExpandDef`,
+ * `ActionsDef`, `FilterOnlyDef`, and any other `ColumnDef` whose `id`
+ * is generated rather than picked from a row field. Construct via
+ * the `syntheticColumnId` helper (re-exported from `$lib`).
+ */
+export type SyntheticColumnId = BrandedString<'SyntheticColumnId'>;
+/**
+ * Discriminated column id: either a string literal that is a key on
+ * the row type `T` (accessor-backed column) or a {@link SyntheticColumnId}
+ * (pseudo column with no row binding, e.g. row-selection / expand /
+ * actions). Used by `ColumnDef.id`; `AccessorDef.id` further narrows
+ * to `string & keyof T` so the id is usable as an accessor literal.
+ *
+ * @example Accessor column — id is a keyof T literal:
+ * ```ts
+ * new TextInputDef<MyRow>({ id: 'name', ... });
+ * ```
+ *
+ * @example Synthetic column — construct via `syntheticColumnId`:
+ * ```ts
+ * new RowSelectionDef<MyRow>(...) // internally uses syntheticColumnId
+ * ```
+ */
+export type ColumnId<T> = (string & keyof T) | SyntheticColumnId;

package/dist/Types/Internal/RefWrapper.d.ts

@@ -1,3 +1,9 @@
+/**
+ * Mutable container for a single value. Returned by `refWrapper`
+ * with `value` backed by `$state` for reactive consumers; used to
+ * pass mutable references across module boundaries without
+ * exposing the underlying rune.
+ */
 export interface RefWrapper<T> {
     value: T;
 }

package/dist/Types/Internal/SelectOption.d.ts

@@ -1,4 +1,12 @@
+/**
+ * A single option in a single/multi select dropdown. Generic
+ * `T` carries the value type so the surrounding component stays
+ * type-safe in `onchange`. `out T` is covariant so a
+ * `SelectOption<string>` is assignable to `SelectOption<unknown>`.
+ */
 export interface SelectOption<out T> {
+    /** Visible label. */
     label: string;
+    /** Concrete value emitted when the option is selected. */
     value: T;
 }

package/dist/Types/Internal/Shape.d.ts

@@ -1,3 +1,4 @@
+/** Outline shape used by Bubble and similar tag-like surfaces. */
 export declare const Shape: {
     readonly Rectangle: "Rectangle";
     readonly Circle: "Circle";

package/dist/Types/Internal/Shape.js

@@ -1,5 +1,6 @@
+/** Outline shape used by Bubble and similar tag-like surfaces. */
 export const Shape = {
     Rectangle: 'Rectangle',
-    Circle: 'Circle'
+    Circle: 'Circle',
 };
 Object.freeze(Shape);

package/dist/Types/Internal/Side.d.ts

@@ -1,3 +1,4 @@
+/** Four-direction enum used by tooltips, accordion arrows and similar. */
 export declare const Side: {
     readonly Top: "Top";
     readonly Right: "Right";

package/dist/Types/Internal/Side.js

@@ -1,7 +1,8 @@
+/** Four-direction enum used by tooltips, accordion arrows and similar. */
 export const Side = {
     Top: 'Top',
     Right: 'Right',
     Bottom: 'Bottom',
-    Left: 'Left'
+    Left: 'Left',
 };
 Object.freeze(Side);

package/dist/Types/Internal/Size.d.ts

@@ -1,3 +1,8 @@
+/**
+ * Discrete size token used across buttons, icons, modals, and
+ * cards. The value is the key by convention to make string-based
+ * SCSS lookups symmetrical.
+ */
 export declare const Size: {
     readonly Tiny: "Tiny";
     readonly Small: "Small";

package/dist/Types/Internal/Size.js

@@ -1,3 +1,8 @@
+/**
+ * Discrete size token used across buttons, icons, modals, and
+ * cards. The value is the key by convention to make string-based
+ * SCSS lookups symmetrical.
+ */
 export const Size = {
     Tiny: 'Tiny',
     Small: 'Small',
@@ -9,6 +14,6 @@ export const Size = {
     DoubleXLarge: 'DoubleXLarge',
     TripleXLarge: 'TripleXLarge',
     FillWidth: 'FillWidth',
-    FillHeight: 'FillHeight'
+    FillHeight: 'FillHeight',
 };
 Object.freeze(Size);

package/dist/Types/Internal/TabOption.d.ts

@@ -1,4 +1,5 @@
 import type { IconProps } from '../../Components/IconProps.js';
+import type { AsyncFlag } from './AsyncFlag.js';
 import type { Snippet } from 'svelte';
 export interface TabOption<Args> {
     label: string;
@@ -7,9 +8,18 @@ export interface TabOption<Args> {
     args: Args;
     iconLeft?: IconProps;
     iconRight?: IconProps;
-    isValid?: boolean | Promise<boolean>;
-    /** default false */
-    disabled?: boolean | Promise<boolean>;
-    /** default true */
-    visible?: boolean | Promise<boolean>;
+    /**
+     * AsyncFlag of a boolean. Tab is rendered invalid when this resolves to false.
+     */
+    isValid?: AsyncFlag<boolean>;
+    /**
+     * AsyncFlag of a boolean. Tab button is disabled when this resolves to true.
+     * Defaults to false.
+     */
+    disabled?: AsyncFlag<boolean>;
+    /**
+     * AsyncFlag of a boolean. Tab is hidden when this resolves to false.
+     * Defaults to true.
+     */
+    visible?: AsyncFlag<boolean>;
 }

package/dist/Types/Internal/Ternary.d.ts

@@ -1,3 +1,9 @@
+/**
+ * Three-valued boolean useful for ThreeStateRadio and similar
+ * inputs where "not yet answered" is a distinct, type-checkable
+ * state. Numeric values are deliberate so the underlying form
+ * value can be passed through `Number(...)` without conversion.
+ */
 export declare const Ternary: {
     readonly Neutral: -1;
     readonly False: 0;

package/dist/Types/Internal/Ternary.js

@@ -1,6 +1,12 @@
+/**
+ * Three-valued boolean useful for ThreeStateRadio and similar
+ * inputs where "not yet answered" is a distinct, type-checkable
+ * state. Numeric values are deliberate so the underlying form
+ * value can be passed through `Number(...)` without conversion.
+ */
 export const Ternary = {
     Neutral: -1,
     False: 0,
-    True: 1
+    True: 1,
 };
 Object.freeze(Ternary);

package/dist/Types/Internal/ToastMessage.d.ts

@@ -1,10 +1,38 @@
 import type { Validity } from './Validity.js';
+/**
+ * Shape of a toast message accepted by `ToastContext.toast`.
+ * Once queued, the context wraps this into an
+ * `IdentifiableToastMessage` by stamping a unique `id` and
+ * `close()` handler.
+ */
 export interface ToastMessage {
+    /** Severity / colour bucket. */
     readonly result: Validity;
+    /** Visible toast text. */
     readonly message: string;
+    /**
+     * Optional callback returning a more detailed string for the
+     * clipboard copy action. By convention, callers gate
+     * dev-revealing detail (stack traces, cause chains) on
+     * `$app/environment.dev`.
+     */
     readonly getVerbose?: () => string;
+    /**
+     * Auto-dismiss timeout in milliseconds. When omitted, the
+     * context applies its default of 10000ms (see
+     * `ToastContext.svelte.ts`).
+     *
+     * @default 10000
+     */
     readonly timeout?: number;
+    /**
+     * Whether the user can dismiss the toast manually.
+     *
+     * @default true
+     */
     readonly closeable?: boolean;
+    /** Whether the user can copy the verbose form to clipboard. */
     readonly copyable?: boolean;
+    /** Hook invoked when the toast is removed (auto or manual). */
     readonly onClose?: () => void;
 }

package/dist/Types/Internal/Validity.d.ts

@@ -1,3 +1,9 @@
+/**
+ * Severity bucket used by inputs, toasts, and validity wrappers
+ * to communicate the four-and-a-half states the design system
+ * recognises: hard-invalid, valid, informational, warning, and
+ * "no opinion yet" (Neutral).
+ */
 export declare const Validity: {
     readonly Invalid: "Invalid";
     readonly Valid: "Valid";

package/dist/Types/Internal/Validity.js

@@ -1,8 +1,14 @@
+/**
+ * Severity bucket used by inputs, toasts, and validity wrappers
+ * to communicate the four-and-a-half states the design system
+ * recognises: hard-invalid, valid, informational, warning, and
+ * "no opinion yet" (Neutral).
+ */
 export const Validity = {
     Invalid: 'Invalid',
     Valid: 'Valid',
     Info: 'Info',
     Warning: 'Warning',
-    Neutral: 'Neutral'
+    Neutral: 'Neutral',
 };
 Object.freeze(Validity);

package/dist/Types/Internal/ValidityWrapper.d.ts

@@ -1,5 +1,13 @@
 import type { Validity } from './Validity.js';
+/**
+ * Composite validity carrying both the {@link Validity} bucket and
+ * a human-readable explanation. Components that accept either a
+ * bare `Validity` or a wrapped form should narrow with
+ * `isValidityTuple` from `Helpers`.
+ */
 export interface ValidityWrapper {
+    /** Severity bucket. */
     value: Validity;
+    /** Optional explanation (tooltip / accessible-text). */
     reason?: string;
 }

package/dist/Types/Internal/Variant.d.ts

@@ -1,3 +1,8 @@
+/**
+ * Visual variant for surface-style components (cards, modals,
+ * toolbars). Members carry no inherent ordering; the value is the
+ * key by convention so the SCSS side can switch on either.
+ */
 export declare const Variant: {
     readonly Primary: "Primary";
     readonly CardInner: "CardInner";

package/dist/Types/Internal/Variant.js

@@ -1,3 +1,8 @@
+/**
+ * Visual variant for surface-style components (cards, modals,
+ * toolbars). Members carry no inherent ordering; the value is the
+ * key by convention so the SCSS side can switch on either.
+ */
 export const Variant = {
     Primary: 'Primary',
     CardInner: 'CardInner',
@@ -6,6 +11,6 @@ export const Variant = {
     Default: 'Default',
     Card: 'Card',
     Toolbar: 'Toolbar', // TODO style
-    HeaderIcon: 'HeaderIcon'
+    HeaderIcon: 'HeaderIcon',
 };
 Object.freeze(Variant);