@lavalogic/scoria 0.36.0 → 0.37.1

package/dist/Helpers/Helpers.svelte.d.ts

@@ -1,25 +1,159 @@
-import type { DefsWrapper } from '../Components/Table/Types/Columns/DefsWrapper.js';
-import { TableContext } from '../Components/Table/Types/Context/TableContext.svelte.js';
-import type { Primitive } from '../Components/Table/Types/Context/TableInitOptions.js';
-import type { CustomFilter } from '../Components/Table/Types/Filtering/CustomFilter.js';
-import type { InputDate, InputDateWithTime, SQLDate } from '../Types/Internal/Misc.js';
+import type { CssLength, InputDate, InputDateWithTime, ScoriaStorageKey, SQLDate, SyntheticColumnId, Uuid } from '../Types/Internal/Misc.js';
 import type { RefWrapper } from '../Types/Internal/RefWrapper.js';
 import type { Validity } from '../Types/Internal/Validity.js';
 import type { ValidityWrapper } from '../Types/Internal/ValidityWrapper.js';
 import { SvelteSet } from 'svelte/reactivity';
+/**
+ * Returns the singular or plural form of `text` based on `quantity`.
+ * Handles common English suffix rules (`-s`, `-x`, `-z`, `-ch`,
+ * `-sh` -> `-es`; everything else -> `-s`). Set `capitalise` when
+ * the surrounding copy is upper-case (e.g. table headers).
+ *
+ * @param text - The singular form.
+ * @param quantity - When equal to `1`, the singular form is returned unchanged. Defaults to `2`.
+ * @param options.capitalise - When `true`, the appended suffix is upper-case.
+ */
 export declare function autoPluralise(text: string, quantity?: number, { capitalise }?: {
     capitalise?: boolean | undefined;
 }): string;
+/** Reactive set of lower-case English vowels; useful for "a" vs "an" decisions. */
 export declare const vowels: SvelteSet<string>;
+/**
+ * Returns the first 13 characters of a freshly generated v4 UUID.
+ *
+ * Inherits the entropy source of `generateUUID` (cryptographic when
+ * available, see that function's docstring), so the underlying random
+ * draw is strong. However, truncating a 128-bit UUID to 13 hex
+ * characters reduces it to roughly 52 bits of entropy, which makes
+ * collisions plausible at scale and renders the value vulnerable to
+ * brute-force guessing.
+ *
+ * WARNING: do NOT use `generateWeakId` for security-sensitive
+ * identifiers (CSRF tokens, session keys, password-reset codes,
+ * idempotency tokens). It is intended for short DOM `id` attributes
+ * and similar low-collision, non-secret labels only. For any
+ * security-sensitive identifier use `generateUUID` (or, in new code,
+ * `globalThis.crypto.randomUUID()` directly).
+ *
+ * The `<T extends string>` generic preserves the `BrandedString`
+ * ergonomics used by the rest of the helpers. Unlike `generateUUID`
+ * the brand parameter has no default - callers must opt in to a brand
+ * explicitly because the value is NOT a full UUID.
+ */
+export declare function generateWeakId<T extends string>(): T;
+/**
+ * @deprecated - use `generateWeakId`; the short form trades collision
+ * resistance for brevity and is NOT suitable for security tokens. The
+ * rename is part of the SecureUUIDs follow-up; this alias is preserved
+ * to avoid breaking existing consumers in the same release.
+ */
 export declare function generateShortUUID<T extends string>(): T;
-export declare function generateUUID<T extends string>(): T;
+/**
+ * Generates an RFC 4122 version 4 UUID.
+ *
+ * Entropy source cascade (in order of preference):
+ *   1. `globalThis.crypto.randomUUID()` - native v4 UUID with
+ *      cryptographically secure randomness. Available in all modern
+ *      evergreen browsers (since 2022) and Node 19+.
+ *   2. `globalThis.crypto.getRandomValues(new Uint8Array(16))` - fills
+ *      16 random bytes from the platform CSPRNG, then sets the
+ *      version (0x40) and variant (0x80) nibbles to produce a v4 UUID.
+ *      Used when `randomUUID` is missing (older Safari, some embedded
+ *      runtimes) but the Web Crypto API is otherwise present.
+ *   3. A `Math.random()`-based fallback that mixes in `Date.now()` and
+ *      `performance.now()`. Emits a one-time `console.warn` to signal
+ *      that the entropy is NOT cryptographically secure. Only reached
+ *      on very old environments where `globalThis.crypto` itself is
+ *      unavailable.
+ *
+ * The `<T extends string>` generic preserves the `BrandedString`
+ * ergonomics used by the rest of the helpers: callers may stamp the
+ * returned value with a brand without an explicit cast.
+ *
+ * @returns A v4 UUID string of the form
+ *   `xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx` where `y` is one of
+ *   `8`, `9`, `a`, `b`.
+ */
+export declare function generateUUID<T extends string = Uuid>(): T;
+/**
+ * Creates a `RefWrapper<T>` whose `value` is `$state`-backed.
+ * Used to pass mutable reactive references into contexts and
+ * across module boundaries without exposing the underlying rune.
+ */
 export declare function refWrapper<T>(initial: T): RefWrapper<T>;
+/**
+ * Ergonomic constructor for the {@link CssLength} brand. The runtime
+ * value is the raw string the caller supplied; the cast is purely a
+ * compile-time tag. There is intentionally no validation - the
+ * browser is the authoritative parser for CSS length tokens. Use
+ * this at the call-site so the brand is obvious in the diff.
+ *
+ * @example
+ * ```ts
+ * <Icon name="cog" float left={cssLength('10px')} />
+ * ```
+ */
+export declare function cssLength(value: string): CssLength;
+/**
+ * Ergonomic constructor for the {@link ScoriaStorageKey} brand. Use
+ * at the call-site of components that persist state to
+ * `sessionStorage` / `localStorage` (e.g. `StepForm`,
+ * `VerticalTabGroup`) so the brand is obvious in the diff.
+ */
+export declare function scoriaStorageKey(value: string): ScoriaStorageKey;
+/**
+ * Ergonomic constructor for the {@link SyntheticColumnId} brand.
+ * Use at the call-site of `ColumnDef` constructors whose `id` is not
+ * a key on the row type (e.g. `RowSelectionDef`, `ExpandDef`,
+ * `ActionsDef`, `FilterOnlyDef`) so the brand is obvious in the diff.
+ *
+ * @example
+ * ```ts
+ * super({
+ *   id: syntheticColumnId(`is-selectable-${generateUUID()}`),
+ *   ...
+ * });
+ * ```
+ */
+export declare function syntheticColumnId(value: string): SyntheticColumnId;
+/**
+ * Formats a date into the `YYYY-MM-DD 00:00:00` shape expected by
+ * the FloWMS SQL backend. Accepts bare `Date` objects or any
+ * branded date string scoria models elsewhere.
+ */
 export declare function SQLFriendly(date: InputDate | SQLDate | Date): SQLDate;
+/**
+ * Like {@link SQLFriendly} but keeps the local time component
+ * (`YYYY-MM-DDTHH:MM:SS±HH:MM`). Accepts an optional separate
+ * `timeDate` argument when the date and time-of-day need to come
+ * from different sources.
+ */
 export declare function SQLFriendlyWithLocalTime(date: InputDate | InputDateWithTime | SQLDate | Date, timeDate?: InputDate | InputDateWithTime | SQLDate | Date | null): SQLDate;
-export declare function SQLFriendlyWithLocalTime_new(date: InputDate | InputDateWithTime | SQLDate | Date, timeDate?: InputDate | InputDateWithTime | SQLDate | Date | null): SQLDate;
+/**
+ * Shared `Intl.DateTimeFormat` configured for UK locale, 24-hour
+ * clock, and the browser-resolved timezone. Useful for rendering
+ * timestamps consistently across scoria.
+ */
 export declare const localTimeFormat: Intl.DateTimeFormat;
+/**
+ * Default `onkeydown` handler that blurs the focused element when
+ * the user presses an alphanumeric key. Used on input wrappers
+ * and buttons so that scanner-driven barcode characters do not
+ * accumulate inside the focused field; instead the buffer goes
+ * to `UntypedInputContext`.
+ */
 export declare function passthrough(e: KeyboardEvent): void;
+/**
+ * Returns a shared, memoised 2D canvas context used for offscreen
+ * text measurement (column auto-sizing, ellipsis truncation, etc).
+ * Returns `null` when the environment cannot create a `<canvas>`.
+ */
 export declare function getCanvasContext(): CanvasRenderingContext2D | null;
+/**
+ * Shape of an HTTP-error response coming from the FloWMS backend.
+ * The `errors` field carries the user-displayable messages; the
+ * `uuid` is the server-side correlation id surfaced for support.
+ */
 export interface IErrorResponse {
     readonly errors: ReadonlyArray<{
         code: string;
@@ -30,40 +164,140 @@ export interface IErrorResponse {
     readonly statusCode: number;
     readonly uuid: string | null;
 }
+/** Type guard for {@link IErrorResponse}. */
 export declare function isErrorResponse(error: unknown): error is IErrorResponse;
+/**
+ * Type guard for the structural-`Error` shape. Returns `true` for
+ * any object with a `string` `message` property, which covers both
+ * native `Error` and cross-realm error-like objects.
+ */
 export declare function isJSError(error: object): error is Error;
+/**
+ * Options accepted by {@link getErrorMessage}. All flags default
+ * to safe-by-default values (no UUID exposure to clipboard, no
+ * stack, no cause).
+ */
 export type GetErrorMessageProps = {
+    /** Append the server-side error UUID for support correlation. */
     includeUUID?: boolean;
+    /** Append the JS stack trace. Caller is responsible for ensuring this is dev-only. */
     includeStack?: boolean;
+    /** Recurse into `error.cause` and append it. Caller is responsible for ensuring this is dev-only. */
     includeCause?: boolean;
 };
+/**
+ * Best-effort extraction of a user-displayable error message from
+ * an unknown error value. Handles {@link IErrorResponse}, plain JS
+ * `Error`, and arbitrary strings; falls back to the literal
+ * `'Unknown Error'` when no recognisable shape is found.
+ *
+ * Callers that surface the output to the clipboard (e.g.
+ * `ToastContext.toast`) must gate `includeStack` and `includeCause`
+ * on `dev` so production users cannot accidentally exfiltrate
+ * backend internals.
+ */
 export declare function getErrorMessage(error: unknown, { includeUUID, includeStack, includeCause }?: GetErrorMessageProps): string;
-export declare function isValidEmailAddress(emailAddress: string): RegExpMatchArray | null;
+/**
+ * Returns `true` when the supplied string parses as a plausible
+ * email address. Lower-cases first so address-portion comparisons
+ * are case-insensitive. Not RFC-5322 exhaustive; intended for
+ * UI-level pre-submission validation only.
+ */
+export declare function isValidEmailAddress(emailAddress: string): boolean;
+/**
+ * Svelte action that resizes a CSS grid item to span the row count
+ * required by its first child's height. Useful for masonry-style
+ * layouts where rows are uniform but content height is dynamic.
+ *
+ * Returns a teardown that disconnects the underlying
+ * `ResizeObserver` entirely; the previous implementation only
+ * unobserved the child, which left the observer registered with
+ * the browser and leaked the reference.
+ */
 export declare function gridItem(element: HTMLElement): (() => void) | undefined;
+/**
+ * Numeric milliseconds. Aliased rather than branded for now;
+ * elevation to `BrandedNumber<'Milliseconds'>` is tracked in the
+ * Types-Internal workorder so existing call sites passing bare
+ * numeric literals (e.g. `500`) keep compiling.
+ */
 export type Milliseconds = number;
+/**
+ * Resolves after `delay` milliseconds. The internal `setTimeout`
+ * call is wrapped in `untrack` so reactive scopes that `await`
+ * `asyncSleep` do not register the sleep as a dependency.
+ */
 export declare function asyncSleep(delay: Milliseconds): Promise<void>;
+/**
+ * Maps each element of `array` through `callback`, returning the
+ * result synchronously when every callback returns a non-Promise
+ * value and otherwise returning a `Promise<Array<R>>`.
+ *
+ * Tightening the return to `Promise<Array<R>>` unconditionally is
+ * tracked in the Helpers workorder; the union is preserved here to
+ * avoid microtask scheduling for purely-synchronous call sites.
+ */
 export declare function asyncMap<T, R>(array: Array<T>, callback: (item: T, index: number) => R | Promise<R>): Array<R> | Promise<Array<R>>;
+/**
+ * Calls `callback` on every element of `array`. Returns `void`
+ * when no callback returned a Promise; otherwise returns a
+ * `Promise<void>` that resolves once every pending callback has
+ * settled.
+ */
 export declare function asyncForEach<T>(array: Array<T>, callback: (item: T, index: number) => void | Promise<void>): void | Promise<void>;
+/**
+ * Maps each element to an array of `R` and concatenates the
+ * results. Sync fast-path matches {@link asyncMap}.
+ */
 export declare function asyncFlatMap<T, R>(array: Array<T>, callback: (item: T, index: number) => Array<R> | Promise<Array<R>>): Array<R> | Promise<Array<R>>;
+/**
+ * Returns `true` as soon as any callback returns truthy.
+ * Short-circuits on synchronous truthy returns.
+ */
 export declare function asyncSome<T>(array: Array<T>, callback: (item: T, index: number) => boolean | Promise<boolean>): boolean | Promise<boolean>;
+/**
+ * Returns `true` when every callback returns truthy.
+ * Short-circuits on the first synchronous falsy return.
+ */
 export declare function asyncAll<T>(array: Array<T>, callback: (item: T, index: number) => boolean | Promise<boolean>): boolean | Promise<boolean>;
+/** Alias of {@link asyncAll}. */
 export declare const asyncEvery: typeof asyncAll;
+/**
+ * Filters the array by the result of `callback`, returning the
+ * indices of matching elements (sorted ascending).
+ */
 export declare function asyncFilterIndices<T>(array: Array<T>, callback: (item: T, index: number) => boolean | Promise<boolean>): Array<number> | Promise<Array<number>>;
+/**
+ * Filters the array by the result of `callback`, returning the
+ * matching elements (sorted by their original index).
+ */
 export declare function asyncFilter<T>(array: Array<T>, callback: (item: T, index: number) => boolean | Promise<boolean>): Array<T> | Promise<Array<T>>;
+/**
+ * Promise-catch handler that logs in development and silently
+ * swallows in production. Intended for fire-and-forget tasks
+ * where the user-visible error path is already covered (e.g.
+ * `ToastContext.toast`).
+ */
 export declare function devCatch(e: unknown): void;
-export declare function hasQuery<FilterValueType>(customFilter: CustomFilter<FilterValueType> | undefined): customFilter is CustomFilter<FilterValueType> & Required<Pick<CustomFilter<FilterValueType>, 'query'>>;
+/** Type guard for the date-range tuple shape used by the date filter. */
 export declare function isDateTuple(value: unknown): value is [Date | null, Date | null];
+/**
+ * Type guard for the numeric-range array shape used by the number
+ * filter (single number, single null, or [min, max] tuple).
+ */
 export declare function isNumericArray(value: unknown): value is Array<number | null>;
+/**
+ * Type guard distinguishing a bare {@link Validity} value from a
+ * {@link ValidityWrapper} object carrying both `value` and `reason`.
+ */
 export declare function isValidityTuple(v: Validity | ValidityWrapper | undefined): v is ValidityWrapper;
+/** Unicode horizontal ellipsis (U+2026). */
 export declare const ellipses = "\u2026";
+/** Standard "loading..." placeholder text with U+2026 ellipsis. */
 export declare const loadingText = "loading\u2026";
+/**
+ * Type-safe `in` check: narrows `key` to a known key of `obj`.
+ * Useful for indexing into objects when the index variable is
+ * typed as plain `string`.
+ */
 export declare function isKeyOf<T extends object>(key: string, obj: T): key is string & keyof T;
-export interface ICreateTableArgs<T extends object, RowIdType extends Primitive> {
-    name: string;
-    defs: DefsWrapper<T>;
-    data: RefWrapper<Array<T>>;
-    getUserId: () => string | undefined;
-    selectionExtractor: (item: T) => RowIdType | Promise<RowIdType>;
-}
-export declare function createLocalTable<T extends object, RowIdType extends Primitive>(args: ICreateTableArgs<T, RowIdType>): TableContext<T, RowIdType>;
-export declare function getAccessorSortingFn<T, V>(accessorFn: (item: T) => V, desc: boolean): (a: T, b: T) => 1 | 0 | -1;