@lavalogic/scoria 0.36.0 → 0.37.0

package/dist/Helpers/Storage.js

@@ -0,0 +1,138 @@
+import { dev } from '$app/environment';
+/**
+ * Internal sentinel used by {@link readJSON} to flag every branch in
+ * which validation, parsing, or storage access fails. The caller never
+ * sees this value: each call site falls back to its `fallback` argument.
+ */
+const FAILED = Symbol('readJSON failed');
+/**
+ * Attempt to load a key from `storage`, JSON-decode the slot, and pass
+ * the raw decoded value through `validator`. Returns the typed value on
+ * success or `fallback` on every failure path:
+ *
+ * - the slot is missing (`getItem` returned `null`);
+ * - the slot is not valid JSON (throws inside `JSON.parse` are caught);
+ * - the decoded value fails `validator`;
+ * - `storage` itself throws (private browsing, quota errors).
+ *
+ * All failure paths return `fallback`. When `dev` is true and a value is
+ * present but malformed, the helper emits a single `console.warn` so
+ * issues are visible during development without ever leaking into
+ * production logs.
+ *
+ * Storage is same-origin and writable by any script running in that
+ * origin, so any value retrieved here is untrusted: the validator is the
+ * only barrier between persisted data and downstream reactive state.
+ *
+ * @typeParam T The validated shape returned on success.
+ * @param storage `localStorage`, `sessionStorage`, or any `Storage`-shaped object.
+ * @param key The slot to read. Callers are responsible for namespacing.
+ * @param validator A type guard that decides whether `raw` is a `T`.
+ * @param fallback Value returned on every failure path.
+ * @returns The validated `T` on success, otherwise `fallback`.
+ */
+export function readJSON(storage, key, validator, fallback) {
+    const parsed = parseSlot(storage, key, validator);
+    if (parsed.ok) {
+        return parsed.value;
+    }
+    return fallback;
+}
+/**
+ * Persist `value` to `storage` as a JSON envelope of the shape
+ * `{ v: schemaVersion, value }`. The envelope lets readers
+ * (see {@link readVersionedJSON}) detect schema drift and drop entries
+ * written by an older or future build instead of feeding them into
+ * reactive state.
+ *
+ * Throws from `JSON.stringify` (circular references) or from `setItem`
+ * (quota errors, locked storage) are swallowed and logged via
+ * `console.warn` in `dev` only. Persistence failure is never fatal: the
+ * caller's in-memory state is the source of truth.
+ *
+ * @typeParam T The value type to persist.
+ * @param storage `localStorage`, `sessionStorage`, or any `Storage`-shaped object.
+ * @param key The slot to write. Callers are responsible for namespacing.
+ * @param value The value to serialise.
+ * @param schemaVersion An integer that bumps whenever the persisted
+ *                     shape changes in a backwards-incompatible way.
+ */
+export function writeJSON(storage, key, value, schemaVersion) {
+    try {
+        const envelope = { v: schemaVersion, value };
+        storage.setItem(key, JSON.stringify(envelope));
+    }
+    catch (e) {
+        if (dev) {
+            console.warn(`writeJSON failed for key "${key}":`, e);
+        }
+    }
+}
+/**
+ * Read an envelope written by {@link writeJSON} and unwrap its `value`
+ * if the recorded schema version matches `currentVersion` and the
+ * inner value satisfies `validator`.
+ *
+ * Returns `fallback` for every failure path: missing slot, malformed
+ * JSON, missing envelope shape, version mismatch, validator rejection,
+ * or storage throws. A version mismatch is treated as silent rejection
+ * so that callers can roll the schema forward without leaving stale
+ * shapes in user storage.
+ *
+ * @typeParam T The validated inner value type.
+ * @param storage `localStorage`, `sessionStorage`, or any `Storage`-shaped object.
+ * @param key The slot to read. Callers are responsible for namespacing.
+ * @param currentVersion The schema version this reader expects.
+ * @param validator A type guard applied to the unwrapped inner value.
+ * @param fallback Value returned on every failure path.
+ * @returns The validated `T` on success, otherwise `fallback`.
+ */
+export function readVersionedJSON(storage, key, currentVersion, validator, fallback) {
+    const envelopeGuard = (raw) => {
+        if (typeof raw !== 'object' || raw === null) {
+            return false;
+        }
+        const candidate = raw;
+        if (candidate.v !== currentVersion) {
+            return false;
+        }
+        return validator(candidate.value);
+    };
+    const parsed = parseSlot(storage, key, envelopeGuard);
+    if (parsed.ok) {
+        return parsed.value.value;
+    }
+    return fallback;
+}
+function parseSlot(storage, key, validator) {
+    let raw;
+    try {
+        raw = storage.getItem(key);
+    }
+    catch (e) {
+        if (dev) {
+            console.warn(`readJSON could not access storage for key "${key}":`, e);
+        }
+        return { ok: false, reason: FAILED };
+    }
+    if (raw === null) {
+        return { ok: false, reason: FAILED };
+    }
+    let decoded;
+    try {
+        decoded = JSON.parse(raw);
+    }
+    catch (e) {
+        if (dev) {
+            console.warn(`readJSON could not parse JSON for key "${key}":`, e);
+        }
+        return { ok: false, reason: FAILED };
+    }
+    if (!validator(decoded)) {
+        if (dev) {
+            console.warn(`readJSON rejected value for key "${key}":`, decoded);
+        }
+        return { ok: false, reason: FAILED };
+    }
+    return { ok: true, value: decoded };
+}

package/dist/Helpers/dropdownPortal.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Portal helper for Svelecte-style dropdowns.
+ *
+ * Svelecte renders its `.sv_dropdown` element inline as a sibling of the
+ * `.svelecte-control` trigger. That means the dropdown is clipped by
+ * any ancestor with `overflow: hidden` / `overflow: auto`, sits below
+ * any ancestor with a higher `z-index`, and is repositioned by any
+ * `transform` / `filter` / `will-change: transform` on the way up to
+ * the body.
+ *
+ * This helper sidesteps all of that:
+ *
+ *   1. On open, it reparents the dropdown to `document.body` (saving
+ *      the original parent + next-sibling so it can be restored on
+ *      close).
+ *   2. It switches the dropdown to `position: fixed` and sets
+ *      `top` / `left` / `width` / `bottom` from the trigger's
+ *      `getBoundingClientRect()`.
+ *   3. It picks `top` vs `bottom` based on available space below vs
+ *      above the trigger, so the dropdown auto-flips upwards when the
+ *      trigger sits near the bottom of the viewport.
+ *   4. It listens for capture-phase `scroll` events and for viewport
+ *      `resize` events so the position tracks the trigger while the
+ *      dropdown is open. Repositioning is rAF-throttled to keep the
+ *      cost off the scroll-event hot path.
+ *   5. On close, the dropdown is moved back to its original DOM slot
+ *      and the inline positioning styles are cleared, so Svelecte's
+ *      next open re-runs the same flow on a clean element.
+ *
+ * The helper deliberately does NOT add the `is-open` class or fight
+ * Svelecte's own state machine. Svelecte still owns open / closed
+ * lifecycle; the portal just intercepts the moment the class flips
+ * `is-open` on / off via a `MutationObserver`.
+ */
+export interface DropdownPortalOptions {
+    /** The Svelecte root wrapper `<div class="svelecte">`. Used as the
+     *  anchor for positioning the teleported dropdown. */
+    getTrigger: () => HTMLElement | null | undefined;
+    /** The `<div class="sv_dropdown">` Svelecte renders. The helper
+     *  watches this element's `class` attribute for `is-open` /
+     *  `:not(is-open)` transitions. */
+    getDropdown: () => HTMLElement | null | undefined;
+}
+/**
+ * Wire the portal behaviour onto a Svelecte instance. Returns a
+ * cleanup function that should be called on component destroy
+ * (typically from inside `onMount(() => { ... return cleanup; })`).
+ *
+ * Returns a no-op cleanup when called outside a browser (SSR) or when
+ * the trigger / dropdown nodes are not present.
+ */
+export declare function attachDropdownPortal(options: DropdownPortalOptions): () => void;

package/dist/Helpers/dropdownPortal.js

@@ -0,0 +1,232 @@
+/**
+ * Portal helper for Svelecte-style dropdowns.
+ *
+ * Svelecte renders its `.sv_dropdown` element inline as a sibling of the
+ * `.svelecte-control` trigger. That means the dropdown is clipped by
+ * any ancestor with `overflow: hidden` / `overflow: auto`, sits below
+ * any ancestor with a higher `z-index`, and is repositioned by any
+ * `transform` / `filter` / `will-change: transform` on the way up to
+ * the body.
+ *
+ * This helper sidesteps all of that:
+ *
+ *   1. On open, it reparents the dropdown to `document.body` (saving
+ *      the original parent + next-sibling so it can be restored on
+ *      close).
+ *   2. It switches the dropdown to `position: fixed` and sets
+ *      `top` / `left` / `width` / `bottom` from the trigger's
+ *      `getBoundingClientRect()`.
+ *   3. It picks `top` vs `bottom` based on available space below vs
+ *      above the trigger, so the dropdown auto-flips upwards when the
+ *      trigger sits near the bottom of the viewport.
+ *   4. It listens for capture-phase `scroll` events and for viewport
+ *      `resize` events so the position tracks the trigger while the
+ *      dropdown is open. Repositioning is rAF-throttled to keep the
+ *      cost off the scroll-event hot path.
+ *   5. On close, the dropdown is moved back to its original DOM slot
+ *      and the inline positioning styles are cleared, so Svelecte's
+ *      next open re-runs the same flow on a clean element.
+ *
+ * The helper deliberately does NOT add the `is-open` class or fight
+ * Svelecte's own state machine. Svelecte still owns open / closed
+ * lifecycle; the portal just intercepts the moment the class flips
+ * `is-open` on / off via a `MutationObserver`.
+ */
+/**
+ * Z-index applied to the teleported dropdown. Chosen so the dropdown
+ * sits above all sticky table strips (`z 5-11` in the table grid) and
+ * the side-panel chrome, but stays below modal overlays (`z 99999`
+ * in `Action`-based popovers).
+ */
+const PORTAL_Z_INDEX = 10000;
+/**
+ * Minimum free vertical space below the trigger before the dropdown
+ * is flipped to open upwards. Picked to fit the default Svelecte
+ * dropdown (six rows + search input + padding) plus a little air;
+ * dropdowns with longer option lists will still scroll internally
+ * inside their fixed-height box.
+ */
+const FLIP_THRESHOLD_PX = 240;
+/** Run a function on the next animation frame, coalescing repeat
+ *  calls so we don't queue dozens of layout reads per scroll burst. */
+function rafThrottle(fn) {
+    let handle = null;
+    return {
+        schedule() {
+            if (handle != null) {
+                return;
+            }
+            handle = requestAnimationFrame(() => {
+                handle = null;
+                fn();
+            });
+        },
+        cancel() {
+            if (handle != null) {
+                cancelAnimationFrame(handle);
+                handle = null;
+            }
+        },
+    };
+}
+/**
+ * Wire the portal behaviour onto a Svelecte instance. Returns a
+ * cleanup function that should be called on component destroy
+ * (typically from inside `onMount(() => { ... return cleanup; })`).
+ *
+ * Returns a no-op cleanup when called outside a browser (SSR) or when
+ * the trigger / dropdown nodes are not present.
+ */
+export function attachDropdownPortal(options) {
+    if (typeof window === 'undefined' || typeof document === 'undefined') {
+        return () => {
+            /* SSR / no-op */
+        };
+    }
+    const trigger = options.getTrigger();
+    const dropdown = options.getDropdown();
+    if (!trigger || !dropdown) {
+        return () => {
+            /* nothing wired up */
+        };
+    }
+    let originalParent = null;
+    let originalNextSibling = null;
+    let isPortalled = false;
+    const reposition = () => {
+        if (!isPortalled) {
+            return;
+        }
+        const tr = trigger.getBoundingClientRect();
+        // `offsetHeight` only reflects the actual rendered height once
+        // Svelecte has laid out the option list, so the first frame
+        // after open may read 0; fall back to the flip threshold so
+        // we still pick a sensible orientation in that case.
+        const dropdownHeight = dropdown.offsetHeight || FLIP_THRESHOLD_PX;
+        const viewportHeight = window.innerHeight;
+        const spaceBelow = viewportHeight - tr.bottom;
+        const spaceAbove = tr.top;
+        const openUp = spaceBelow < Math.min(dropdownHeight, FLIP_THRESHOLD_PX) && spaceAbove > spaceBelow;
+        dropdown.style.position = 'fixed';
+        dropdown.style.left = `${tr.left}px`;
+        dropdown.style.width = `${tr.width}px`;
+        // Override Svelecte's own `min-width: 100%` on `.sv_dropdown`.
+        // With `position: fixed` the percentage resolves against the
+        // initial containing block (the viewport), which would otherwise
+        // stretch the dropdown across the whole page. Pin the
+        // minimum to the trigger width so the dropdown stays the same
+        // width as the select that opened it.
+        dropdown.style.minWidth = `${tr.width}px`;
+        dropdown.style.maxWidth = `${tr.width}px`;
+        dropdown.style.zIndex = String(PORTAL_Z_INDEX);
+        // Bound the dropdown's max height to the available space so
+        // long option lists scroll internally rather than disappear
+        // past the viewport edge.
+        if (openUp) {
+            dropdown.style.top = '';
+            dropdown.style.bottom = `${viewportHeight - tr.top}px`;
+            dropdown.style.maxHeight = `${Math.max(spaceAbove - 8, 64)}px`;
+        }
+        else {
+            dropdown.style.top = `${tr.bottom}px`;
+            dropdown.style.bottom = '';
+            dropdown.style.maxHeight = `${Math.max(spaceBelow - 8, 64)}px`;
+        }
+    };
+    const throttled = rafThrottle(reposition);
+    const handleScroll = () => {
+        throttled.schedule();
+    };
+    const handleResize = () => {
+        throttled.schedule();
+    };
+    const portalOut = () => {
+        if (isPortalled) {
+            return;
+        }
+        originalParent = dropdown.parentNode;
+        originalNextSibling = dropdown.nextSibling;
+        document.body.appendChild(dropdown);
+        // Tag the teleported dropdown so any "click outside the
+        // panel" / "click outside the trigger" handler elsewhere in
+        // the codebase can recognise the dropdown as a logical
+        // extension of its trigger and ignore clicks landing inside
+        // it. The `TableSidebar` side-panel uses this marker (along
+        // with `closest('.sv_dropdown')`) so clicking an option in a
+        // teleported filter-row dropdown does not close the
+        // side-panel under it. Components that want to ignore
+        // portal clicks should check
+        // `el.closest('[data-scoria-portal-dropdown]')`.
+        dropdown.setAttribute('data-scoria-portal-dropdown', '');
+        isPortalled = true;
+        // First-frame measurement: lay out, then reposition again on
+        // the next frame so we measure the dropdown's real
+        // `offsetHeight` once it has options rendered.
+        reposition();
+        requestAnimationFrame(reposition);
+        // `capture: true` so scroll events on any ancestor (the
+        // filter-panel side pane, the page itself, the .datatable
+        // scroll container) reach this listener; without capture the
+        // listener would only fire when the document element scrolls.
+        window.addEventListener('scroll', handleScroll, { capture: true, passive: true });
+        window.addEventListener('resize', handleResize, { passive: true });
+    };
+    const portalIn = () => {
+        if (!isPortalled) {
+            return;
+        }
+        throttled.cancel();
+        window.removeEventListener('scroll', handleScroll, { capture: true });
+        window.removeEventListener('resize', handleResize);
+        // Strip the inline overrides so Svelecte's next open starts
+        // from a clean slate (and so a closed dropdown still occupies
+        // its Svelecte-managed `display: none` slot).
+        dropdown.style.position = '';
+        dropdown.style.top = '';
+        dropdown.style.left = '';
+        dropdown.style.bottom = '';
+        dropdown.style.width = '';
+        dropdown.style.minWidth = '';
+        dropdown.style.maxWidth = '';
+        dropdown.style.maxHeight = '';
+        dropdown.style.zIndex = '';
+        dropdown.removeAttribute('data-scoria-portal-dropdown');
+        if (originalParent != null) {
+            if (originalNextSibling != null && originalNextSibling.parentNode === originalParent) {
+                originalParent.insertBefore(dropdown, originalNextSibling);
+            }
+            else {
+                originalParent.appendChild(dropdown);
+            }
+        }
+        originalParent = null;
+        originalNextSibling = null;
+        isPortalled = false;
+    };
+    // Apply / unapply the portal whenever Svelecte toggles the
+    // `is-open` class on the dropdown. We watch class only because
+    // Svelecte's open state is exposed purely as a class flip.
+    const observer = new MutationObserver((mutations) => {
+        for (const mutation of mutations) {
+            if (mutation.attributeName !== 'class') {
+                continue;
+            }
+            if (dropdown.classList.contains('is-open')) {
+                portalOut();
+            }
+            else {
+                portalIn();
+            }
+        }
+    });
+    observer.observe(dropdown, { attributes: true, attributeFilter: ['class'] });
+    // Honour the dropdown's initial state in case it mounted already
+    // open (e.g. `focusOnLoad`).
+    if (dropdown.classList.contains('is-open')) {
+        portalOut();
+    }
+    return () => {
+        observer.disconnect();
+        portalIn();
+    };
+}

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

@@ -0,0 +1,2 @@
+export { attachDropdownPortal } from './dropdownPortal.js';
+export type { DropdownPortalOptions } from './dropdownPortal.js';

package/dist/Helpers/dropdownPortal.svelte.js

@@ -0,0 +1,5 @@
+// This module has been moved to `dropdownPortal.ts` because it does
+// not use any Svelte 5 runes. This re-export exists only to keep
+// older imports compiling if any consumer reached for the
+// `.svelte.ts` path during early development.
+export { attachDropdownPortal } from './dropdownPortal.js';

package/dist/Helpers/memoiseByRow.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Row-keyed memoisation helpers for ColumnDef accessors.
+ *
+ * The Table renders a fresh `$derived` graph per cell per render, and a
+ * 1000-row sort/filter pass will invoke `def.getDisplayValue(row)` /
+ * `def.getColour(row, index, value)` once per row per pass. For user
+ * callbacks that do non-trivial work (string concat, date formatting,
+ * colour lookup) this adds up.
+ *
+ * Strategy: attach a `WeakMap<TRow, Result>` cache to the Def class
+ * (one map per Def instance). When the underlying user callback is
+ * reassigned (e.g. caller rebuilt `columnDefs = [...]`), the wrapper is
+ * re-derived via `$derived`, which automatically discards the stale
+ * cache. When a row reference is GC'd the WeakMap entry follows.
+ *
+ * Async values: when the user callback returns a `Promise<T>`, the
+ * Promise itself is cached. Repeated reads return the same Promise so
+ * Svelte's `{#await}` resolves once. Failure is not specially handled:
+ * a rejected Promise stays cached; reassignment of the user callback
+ * clears it.
+ *
+ * The helpers are pure functions of `(rawFn) -> wrappedFn`. They are
+ * intended to be called from a `$derived` so that reassigning the user
+ * callback automatically invalidates the cache.
+ */
+/**
+ * Wrap a row-keyed accessor `(row, index) => V | Promise<V>` with a
+ * WeakMap cache keyed by row identity. Returns `undefined` when the
+ * input is `undefined` (passes through the optional contract).
+ *
+ * The `index` argument is intentionally NOT part of the cache key. Rows
+ * keep their identity across sort / filter passes; only their visible
+ * index changes. Caching by row identity gives the desired re-use.
+ */
+export declare function memoiseRowAccessor<TRow extends object, V>(rawFn: ((row: TRow, index: number) => V) | undefined): ((row: TRow, index: number) => V) | undefined;
+/**
+ * Wrap a per-cell value-keyed accessor `(row, index, value) => V` with
+ * a WeakMap<row, Map<value, V>> cache. Used by BubbleDef where the
+ * colour depends on both the row and a per-bubble string value.
+ *
+ * The inner Map is created lazily per row. Bubble counts per row are
+ * small (typically < 10) so the inner Map cost is dominated by the
+ * outer WeakMap.
+ */
+export declare function memoiseRowValueAccessor<TRow extends object, TValue, VRet>(rawFn: ((row: TRow, index: number, value: TValue) => VRet) | undefined): ((row: TRow, index: number, value: TValue) => VRet) | undefined;

package/dist/Helpers/memoiseByRow.js

@@ -0,0 +1,78 @@
+/**
+ * Row-keyed memoisation helpers for ColumnDef accessors.
+ *
+ * The Table renders a fresh `$derived` graph per cell per render, and a
+ * 1000-row sort/filter pass will invoke `def.getDisplayValue(row)` /
+ * `def.getColour(row, index, value)` once per row per pass. For user
+ * callbacks that do non-trivial work (string concat, date formatting,
+ * colour lookup) this adds up.
+ *
+ * Strategy: attach a `WeakMap<TRow, Result>` cache to the Def class
+ * (one map per Def instance). When the underlying user callback is
+ * reassigned (e.g. caller rebuilt `columnDefs = [...]`), the wrapper is
+ * re-derived via `$derived`, which automatically discards the stale
+ * cache. When a row reference is GC'd the WeakMap entry follows.
+ *
+ * Async values: when the user callback returns a `Promise<T>`, the
+ * Promise itself is cached. Repeated reads return the same Promise so
+ * Svelte's `{#await}` resolves once. Failure is not specially handled:
+ * a rejected Promise stays cached; reassignment of the user callback
+ * clears it.
+ *
+ * The helpers are pure functions of `(rawFn) -> wrappedFn`. They are
+ * intended to be called from a `$derived` so that reassigning the user
+ * callback automatically invalidates the cache.
+ */
+/**
+ * Wrap a row-keyed accessor `(row, index) => V | Promise<V>` with a
+ * WeakMap cache keyed by row identity. Returns `undefined` when the
+ * input is `undefined` (passes through the optional contract).
+ *
+ * The `index` argument is intentionally NOT part of the cache key. Rows
+ * keep their identity across sort / filter passes; only their visible
+ * index changes. Caching by row identity gives the desired re-use.
+ */
+export function memoiseRowAccessor(rawFn) {
+    if (rawFn === undefined) {
+        return undefined;
+    }
+    const cache = new WeakMap();
+    return (row, index) => {
+        const hit = cache.get(row);
+        if (hit !== undefined || cache.has(row)) {
+            return hit;
+        }
+        const value = rawFn(row, index);
+        cache.set(row, value);
+        return value;
+    };
+}
+/**
+ * Wrap a per-cell value-keyed accessor `(row, index, value) => V` with
+ * a WeakMap<row, Map<value, V>> cache. Used by BubbleDef where the
+ * colour depends on both the row and a per-bubble string value.
+ *
+ * The inner Map is created lazily per row. Bubble counts per row are
+ * small (typically < 10) so the inner Map cost is dominated by the
+ * outer WeakMap.
+ */
+export function memoiseRowValueAccessor(rawFn) {
+    if (rawFn === undefined) {
+        return undefined;
+    }
+    const cache = new WeakMap();
+    return (row, index, value) => {
+        let inner = cache.get(row);
+        if (inner === undefined) {
+            inner = new Map();
+            cache.set(row, inner);
+        }
+        const hit = inner.get(value);
+        if (hit !== undefined || inner.has(value)) {
+            return hit;
+        }
+        const result = rawFn(row, index, value);
+        inner.set(value, result);
+        return result;
+    };
+}

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

@@ -0,0 +1,27 @@
+/**
+ * Reactive accessor for the `prefers-reduced-motion: reduce` user preference.
+ *
+ * Components that drive motion from JS (the `svelte/transition` family, custom
+ * `requestAnimationFrame` loops, etc.) cannot opt out via a CSS media query
+ * alone: the offending styles are inlined onto the element by the transition
+ * tween, which beats any external rule. This helper exposes the current value
+ * of `matchMedia('(prefers-reduced-motion: reduce)')` as a runed reactive flag
+ * that survives re-renders and removes its listener on teardown.
+ *
+ * Usage:
+ *
+ *   <script>
+ *     const reducedMotion = usePrefersReducedMotion();
+ *     const slideDuration = $derived(reducedMotion.matches ? 0 : 200);
+ *   </script>
+ *   <div transition:slide={{ duration: slideDuration }}>...</div>
+ *
+ * In environments without a `matchMedia` implementation (server-side render,
+ * legacy embedded browser) the helper returns `matches: false` and never
+ * registers a listener, so callers can use the same code path on both client
+ * and server.
+ */
+export interface PrefersReducedMotionResult {
+    readonly matches: boolean;
+}
+export declare function usePrefersReducedMotion(): PrefersReducedMotionResult;

package/dist/Helpers/prefersReducedMotion.svelte.js

@@ -0,0 +1,18 @@
+export function usePrefersReducedMotion() {
+    const state = $state({ matches: false });
+    if (typeof globalThis === 'undefined' || typeof globalThis.matchMedia !== 'function') {
+        return state;
+    }
+    const mql = globalThis.matchMedia('(prefers-reduced-motion: reduce)');
+    state.matches = mql.matches;
+    const listener = (event) => {
+        state.matches = event.matches;
+    };
+    $effect(() => {
+        mql.addEventListener('change', listener);
+        return () => {
+            mql.removeEventListener('change', listener);
+        };
+    });
+    return state;
+}

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

@@ -0,0 +1,53 @@
+import { Side } from '../Types/Internal/Side.js';
+/**
+ * Options for {@link useTooltip}. All inputs are thunks so the helper can
+ * establish its own `$effect` / lazy-read dependency on whatever reactive
+ * state the caller wraps inside.
+ */
+export interface UseTooltipOptions {
+    /**
+     * The text to show in the tooltip. Return `null` or `undefined` to
+     * suppress the tooltip entirely (e.g. for label-less icon buttons).
+     * Empty strings are also treated as "no tooltip". The non-empty text
+     * value is also used as the cleanup key passed to
+     * {@link TooltipContext.hideTooltip}.
+     */
+    text: () => string | null | undefined;
+    /**
+     * Optional thunk returning the side of the anchor the tooltip arrow
+     * should point to. Defaults to {@link Side.Top}.
+     */
+    arrow?: () => Side;
+    /**
+     * Optional thunk returning the show-delay in milliseconds. Defaults
+     * to {@link Delay.Default}.
+     */
+    delay?: () => number;
+}
+/**
+ * Event-handler bundle returned by {@link useTooltip}. Spread these onto
+ * the anchor element or compose them with the consumer's existing
+ * handlers using the `(e) => { tt.onmouseenter(e); custom(e); }` pattern.
+ */
+export interface UseTooltipHandlers {
+    onmouseenter: (e: MouseEvent) => void;
+    onmouseleave: () => void;
+    onclick: () => void;
+}
+/**
+ * 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 declare function useTooltip(options: UseTooltipOptions): UseTooltipHandlers;