@svgrid/grid 1.2.34 → 2.0.1

package/dist/SvTreeSelect.svelte.d.ts

@@ -0,0 +1,24 @@
+export type { TreeSelectNode } from './ui-app.types';
+/**
+   * SvTreeSelect - a single-select dropdown that shows an indented, collapsible
+   * tree in its panel (pick a node from a hierarchy). The open / position /
+   * dismiss / roving / keyboard / ARIA mechanics come from the shared
+   * `createPopoverSelect` core (with ArrowLeft/Right handled via onExtraKey for
+   * expand/collapse); this component adds the tree flattening + rendering. Covers
+   * the "cascader / tree select" pattern without depending on SvTree.
+   */
+import type { TreeSelectNode } from './ui-app.types';
+import { type SvEditorProps } from './editor-contract';
+type Props = Pick<SvEditorProps, 'disabled' | 'label' | 'hint' | 'error' | 'required' | 'invalid' | 'size' | 'id' | 'name' | 'dir' | 'ariaLabel'> & {
+    nodes: ReadonlyArray<TreeSelectNode>;
+    value?: string | number | null;
+    onChange?: (value: string | number) => void;
+    onCommit?: (value: string | number) => void;
+    onCancel?: () => void;
+    placeholder?: string;
+    showPath?: boolean;
+    expandedIds?: ReadonlyArray<string | number>;
+};
+declare const SvTreeSelect: import("svelte").Component<Props, {}, "value">;
+type SvTreeSelect = ReturnType<typeof SvTreeSelect>;
+export default SvTreeSelect;

package/dist/a11y/dismissable.d.ts

@@ -0,0 +1,32 @@
+/**
+ * dismissable-layer - a global stack of dismissable overlays (dropdowns,
+ * popovers, dialogs). Escape and outside-pointer dismiss only the TOP layer, so
+ * a menu opened inside a dialog closes the menu first and the dialog second -
+ * the ordering users expect from nested overlays. One set of document listeners
+ * is shared by every layer instead of each component wiring its own.
+ */
+type Reason = 'escape' | 'outside';
+/** One element, several elements, or a getter of either. A pointerdown counts
+ *  as "inside" when it lands in ANY of them (e.g. a popover's panel AND its
+ *  trigger, so clicking the trigger doesn't immediately re-dismiss). */
+export type DismissTarget = HTMLElement | null | ReadonlyArray<HTMLElement | null>;
+export type DismissableOptions = {
+    /** The panel element(s); a pointerdown outside ALL of them dismisses the layer.
+     *  Pass multiple (e.g. panel + trigger) so clicking the trigger doesn't
+     *  immediately re-dismiss what it just opened. */
+    element: () => DismissTarget;
+    onDismiss: (reason: Reason) => void;
+    /** Dismiss on Escape when topmost. Default true. */
+    closeOnEscape?: boolean;
+    /** Dismiss on outside pointerdown when topmost. Default true. */
+    closeOnOutside?: boolean;
+};
+export type DismissableLayer = {
+    activate: () => void;
+    release: () => void;
+};
+/** Register a dismissable layer. Inert until `activate()`. */
+export declare function createDismissableLayer(options: DismissableOptions): DismissableLayer;
+/** Test/introspection helper: current number of active layers. */
+export declare function dismissableDepth(): number;
+export {};

package/dist/a11y/dismissable.js

@@ -0,0 +1,54 @@
+function containsTarget(target, node) {
+    if (!node)
+        return false;
+    const els = Array.isArray(target) ? target : [target];
+    return els.some((el) => el != null && el.contains(node));
+}
+const stack = [];
+let wired = false;
+function ensureWired() {
+    if (wired || typeof document === 'undefined')
+        return;
+    wired = true;
+    document.addEventListener('keydown', (e) => {
+        if (e.key !== 'Escape')
+            return;
+        const top = stack[stack.length - 1];
+        if (top?.closeOnEscape) {
+            e.stopPropagation();
+            top.onDismiss('escape');
+        }
+    }, true);
+    document.addEventListener('pointerdown', (e) => {
+        const top = stack[stack.length - 1];
+        if (!top?.closeOnOutside)
+            return;
+        if (!containsTarget(top.element(), e.target))
+            top.onDismiss('outside');
+    }, true);
+}
+/** Register a dismissable layer. Inert until `activate()`. */
+export function createDismissableLayer(options) {
+    const layer = {
+        element: options.element,
+        onDismiss: options.onDismiss,
+        closeOnEscape: options.closeOnEscape ?? true,
+        closeOnOutside: options.closeOnOutside ?? true,
+    };
+    return {
+        activate() {
+            ensureWired();
+            if (!stack.includes(layer))
+                stack.push(layer);
+        },
+        release() {
+            const i = stack.indexOf(layer);
+            if (i >= 0)
+                stack.splice(i, 1);
+        },
+    };
+}
+/** Test/introspection helper: current number of active layers. */
+export function dismissableDepth() {
+    return stack.length;
+}

package/dist/a11y/focus-trap.d.ts

@@ -0,0 +1,39 @@
+/**
+ * focus-trap - keep Tab / Shift+Tab focus inside a container while it is active,
+ * move focus in on activate, and restore it on release. Shared by SvModal,
+ * SvDrawer, SvMenu and any dialog-like overlay so the WAI-ARIA dialog focus
+ * behaviour lives in ONE place instead of being re-hand-rolled per component.
+ *
+ * Framework-free (DOM only): call `createFocusTrap(el).activate()` from a
+ * component `$effect` and `release()` from its cleanup.
+ *
+ * ```ts
+ * $effect(() => {
+ *   if (!open || !panel) return
+ *   const trap = createFocusTrap(panel)
+ *   trap.activate()
+ *   return () => trap.release()
+ * })
+ * ```
+ */
+/** Selector for elements that can, in principle, hold keyboard focus. */
+export declare const FOCUSABLE_SELECTOR: string;
+/** Visible, Tab-focusable descendants of `container`, in DOM order. Elements
+ *  with `tabindex="-1"` are excluded (script-focusable, not Tab-reachable). */
+export declare function getFocusable(container: HTMLElement): HTMLElement[];
+export type FocusTrapOptions = {
+    /** Where focus goes on activate: the first focusable (default), the container
+     *  itself, a specific element, or a getter resolved at activate time. */
+    initialFocus?: 'first' | 'container' | HTMLElement | (() => HTMLElement | null);
+    /** Restore focus to the previously-focused element on release. Default true. */
+    returnFocus?: boolean;
+    /** Called on Escape while active. Dismissal is usually owned by the layer
+     *  manager, so most consumers leave this unset. */
+    onEscape?: (e: KeyboardEvent) => void;
+};
+export type FocusTrap = {
+    activate: () => void;
+    release: () => void;
+};
+/** Create a focus trap for `container`. Inert until `activate()`. */
+export declare function createFocusTrap(container: HTMLElement, options?: FocusTrapOptions): FocusTrap;

package/dist/a11y/focus-trap.js

@@ -0,0 +1,142 @@
+/**
+ * focus-trap - keep Tab / Shift+Tab focus inside a container while it is active,
+ * move focus in on activate, and restore it on release. Shared by SvModal,
+ * SvDrawer, SvMenu and any dialog-like overlay so the WAI-ARIA dialog focus
+ * behaviour lives in ONE place instead of being re-hand-rolled per component.
+ *
+ * Framework-free (DOM only): call `createFocusTrap(el).activate()` from a
+ * component `$effect` and `release()` from its cleanup.
+ *
+ * ```ts
+ * $effect(() => {
+ *   if (!open || !panel) return
+ *   const trap = createFocusTrap(panel)
+ *   trap.activate()
+ *   return () => trap.release()
+ * })
+ * ```
+ */
+/** Selector for elements that can, in principle, hold keyboard focus. */
+export const FOCUSABLE_SELECTOR = [
+    'a[href]',
+    'area[href]',
+    'button:not([disabled])',
+    'input:not([disabled])',
+    'select:not([disabled])',
+    'textarea:not([disabled])',
+    'iframe',
+    'audio[controls]',
+    'video[controls]',
+    '[contenteditable]:not([contenteditable="false"])',
+    '[tabindex]',
+].join(',');
+/**
+ * Whether `el` is visible enough to be Tab-focusable. Detects the common,
+ * layout-independent ways of hiding (disabled / hidden attr / aria-hidden /
+ * inline display:none|visibility:hidden) so the check is deterministic in both
+ * real browsers and jsdom. Class-based `display:none` in a real browser is
+ * additionally caught via client rects when layout is available.
+ */
+function isVisible(el) {
+    if (el.hasAttribute('disabled'))
+        return false;
+    if (el.getAttribute('aria-hidden') === 'true')
+        return false;
+    if (el.hidden || el.closest('[hidden]'))
+        return false;
+    const style = el.style;
+    if (style.display === 'none' || style.visibility === 'hidden')
+        return false;
+    // Only trust layout when the environment actually lays out (real browsers).
+    if (typeof el.getClientRects === 'function') {
+        const rects = el.getClientRects();
+        // jsdom reports 0 rects for everything, so 0 alone is not "hidden" there;
+        // treat 0 rects as hidden only when SOME element in the doc has layout.
+        if (rects.length === 0 && document.body.getClientRects().length > 0)
+            return false;
+    }
+    return true;
+}
+/** Visible, Tab-focusable descendants of `container`, in DOM order. Elements
+ *  with `tabindex="-1"` are excluded (script-focusable, not Tab-reachable). */
+export function getFocusable(container) {
+    const nodes = Array.from(container.querySelectorAll(FOCUSABLE_SELECTOR));
+    return nodes.filter((el) => {
+        const ti = el.getAttribute('tabindex');
+        if (ti !== null && Number(ti) < 0)
+            return false;
+        return isVisible(el);
+    });
+}
+/** Create a focus trap for `container`. Inert until `activate()`. */
+export function createFocusTrap(container, options = {}) {
+    const { initialFocus = 'first', returnFocus = true } = options;
+    let previouslyFocused = null;
+    let active = false;
+    function resolveInitial() {
+        const f = initialFocus;
+        if (f === 'container')
+            return container;
+        if (f === 'first')
+            return getFocusable(container)[0] ?? container;
+        if (typeof f === 'function')
+            return f();
+        return f;
+    }
+    function onKeydown(e) {
+        if (!active)
+            return;
+        if (e.key === 'Escape' && options.onEscape) {
+            options.onEscape(e);
+            return;
+        }
+        if (e.key !== 'Tab')
+            return;
+        const f = getFocusable(container);
+        if (!f.length) {
+            e.preventDefault();
+            container.focus();
+            return;
+        }
+        const first = f[0];
+        const last = f[f.length - 1];
+        const activeEl = document.activeElement;
+        // Focus escaped the container entirely (programmatic blur, etc.): pull back.
+        if (!container.contains(activeEl)) {
+            e.preventDefault();
+            first.focus();
+            return;
+        }
+        if (e.shiftKey && activeEl === first) {
+            e.preventDefault();
+            last.focus();
+        }
+        else if (!e.shiftKey && activeEl === last) {
+            e.preventDefault();
+            first.focus();
+        }
+    }
+    function activate() {
+        if (active)
+            return;
+        active = true;
+        previouslyFocused = document.activeElement;
+        // Guarantee the container is a focus fallback even without focusable children.
+        if (!container.hasAttribute('tabindex'))
+            container.setAttribute('tabindex', '-1');
+        document.addEventListener('keydown', onKeydown, true);
+        // Focus on the next microtask so a just-opened panel is in the DOM first.
+        queueMicrotask(() => { if (active)
+            resolveInitial()?.focus(); });
+    }
+    function release() {
+        if (!active)
+            return;
+        active = false;
+        document.removeEventListener('keydown', onKeydown, true);
+        if (returnFocus)
+            previouslyFocused?.focus?.();
+        previouslyFocused = null;
+    }
+    return { activate, release };
+}

package/dist/a11y/live-region.d.ts

@@ -0,0 +1,8 @@
+export type AnnounceOptions = {
+    /** Interrupt the user immediately (role="alert"). Default polite. */
+    assertive?: boolean;
+};
+/** Announce `message` to screen readers. Empty messages are ignored. */
+export declare function announce(message: string, options?: AnnounceOptions): void;
+/** Test helper: tear the shared live regions down. */
+export declare function _resetLiveRegions(): void;

package/dist/a11y/live-region.js

@@ -0,0 +1,60 @@
+/**
+ * live-region - a single shared pair of visually-hidden ARIA live regions
+ * (polite + assertive) appended to <body> on first use, so any component can
+ * push a transient message to screen readers via `announce()` without each one
+ * shipping its own live region. Used for things like "3 rows selected",
+ * "copied", "no results".
+ */
+let politeEl = null;
+let assertiveEl = null;
+function make(mode) {
+    const el = document.createElement('div');
+    el.setAttribute('aria-live', mode);
+    el.setAttribute('aria-atomic', 'true');
+    el.setAttribute('role', mode === 'assertive' ? 'alert' : 'status');
+    // Visually hidden, but still exposed to assistive technology.
+    Object.assign(el.style, {
+        position: 'absolute',
+        width: '1px',
+        height: '1px',
+        margin: '-1px',
+        border: '0',
+        padding: '0',
+        overflow: 'hidden',
+        clip: 'rect(0 0 0 0)',
+        clipPath: 'inset(50%)',
+        whiteSpace: 'nowrap',
+    });
+    document.body.appendChild(el);
+    return el;
+}
+/** Announce `message` to screen readers. Empty messages are ignored. */
+export function announce(message, options = {}) {
+    if (typeof document === 'undefined' || !message)
+        return;
+    const assertive = options.assertive ?? false;
+    let el = assertive ? assertiveEl : politeEl;
+    // Recreate when missing OR when a prior DOM reset detached the cached node,
+    // so a stale reference can never swallow an announcement silently.
+    if (!el || !el.isConnected) {
+        el = make(assertive ? 'assertive' : 'polite');
+        if (assertive)
+            assertiveEl = el;
+        else
+            politeEl = el;
+    }
+    // Clear, then set on the next microtask, so an identical consecutive message
+    // still triggers a fresh announcement.
+    el.textContent = '';
+    const target = el;
+    queueMicrotask(() => {
+        target.textContent = message;
+    });
+}
+/** Test helper: tear the shared live regions down. */
+export function _resetLiveRegions() {
+    politeEl?.remove();
+    assertiveEl?.remove();
+    politeEl = null;
+    assertiveEl = null;
+}

package/dist/a11y/scroll-lock.d.ts

@@ -0,0 +1,4 @@
+/** Lock document scroll. Returns an idempotent unlock function. */
+export declare function lockScroll(): () => void;
+/** Test helper: current lock depth. */
+export declare function scrollLockDepth(): number;

package/dist/a11y/scroll-lock.js

@@ -0,0 +1,41 @@
+/**
+ * scroll-lock - stop the document scrolling behind an overlay, with REF-COUNTING
+ * so nested overlays (a dialog that opens a menu) never fight over
+ * `body.style.overflow`. The first lock records the original values; the last
+ * unlock restores them. Also pads for the vanishing scrollbar so the page
+ * doesn't shift when the lock engages.
+ */
+let locks = 0;
+let previousOverflow = '';
+let previousPaddingRight = '';
+/** Lock document scroll. Returns an idempotent unlock function. */
+export function lockScroll() {
+    if (typeof document === 'undefined')
+        return () => { };
+    const body = document.body;
+    if (locks === 0) {
+        previousOverflow = body.style.overflow;
+        previousPaddingRight = body.style.paddingRight;
+        // Compensate for the scrollbar width so fixed/full-width layout stays put.
+        const sbw = window.innerWidth - document.documentElement.clientWidth;
+        if (sbw > 0) {
+            const current = parseFloat(getComputedStyle(body).paddingRight) || 0;
+            body.style.paddingRight = `${current + sbw}px`;
+        }
+        body.style.overflow = 'hidden';
+    }
+    locks++;
+    let released = false;
+    return () => {
+        if (released)
+            return;
+        released = true;
+        locks = Math.max(0, locks - 1);
+        if (locks === 0) {
+            body.style.overflow = previousOverflow;
+            body.style.paddingRight = previousPaddingRight;
+        }
+    };
+}
+/** Test helper: current lock depth. */
+export function scrollLockDepth() { return locks; }

package/dist/a11y.d.ts

@@ -13,11 +13,13 @@ export declare function getGridRootA11yProps(input?: {
     activeDescendantId?: string | null;
     rowCount?: number;
     colCount?: number;
+    /** Use the treegrid role (expandable server group / tree rows are present). */
+    treegrid?: boolean;
 }): {
     readonly 'aria-colcount'?: number | undefined;
     readonly 'aria-rowcount'?: number | undefined;
     readonly 'aria-activedescendant'?: string | undefined;
-    readonly role: "grid";
+    readonly role: "grid" | "treegrid";
     readonly tabindex: 0;
 };
 export declare function getGridHeaderA11yProps(input?: GridColumnA11yInput): {

package/dist/a11y.js

@@ -1,6 +1,6 @@
 export function getGridRootA11yProps(input = {}) {
     return {
-        role: 'grid',
+        role: input.treegrid ? 'treegrid' : 'grid',
         tabindex: 0,
         ...(input.activeDescendantId
             ? { 'aria-activedescendant': input.activeDescendantId }

package/dist/avatar.d.ts

@@ -0,0 +1,10 @@
+/**
+ * avatar - pure helpers behind <SvAvatar>: derive up-to-two-letter initials from
+ * a name, and a stable hue from a string so the same name always gets the same
+ * fallback colour. Framework-free + pure so they are unit-tested directly.
+ */
+/** Up to two uppercase initials for `name` (first + last word, or first two
+ *  letters of a single word). Empty string for blank input. */
+export declare function avatarInitials(name: string): string;
+/** Deterministic hue (0-359) derived from a string, for the fallback tint. */
+export declare function avatarColorHue(name: string): number;

package/dist/avatar.js

@@ -0,0 +1,22 @@
+/**
+ * avatar - pure helpers behind <SvAvatar>: derive up-to-two-letter initials from
+ * a name, and a stable hue from a string so the same name always gets the same
+ * fallback colour. Framework-free + pure so they are unit-tested directly.
+ */
+/** Up to two uppercase initials for `name` (first + last word, or first two
+ *  letters of a single word). Empty string for blank input. */
+export function avatarInitials(name) {
+    const parts = name.trim().split(/\s+/).filter(Boolean);
+    if (!parts.length)
+        return '';
+    if (parts.length === 1)
+        return parts[0].slice(0, 2).toUpperCase();
+    return (parts[0][0] + parts[parts.length - 1][0]).toUpperCase();
+}
+/** Deterministic hue (0-359) derived from a string, for the fallback tint. */
+export function avatarColorHue(name) {
+    let h = 0;
+    for (let i = 0; i < name.length; i++)
+        h = (h * 31 + name.charCodeAt(i)) % 360;
+    return h;
+}

package/dist/builtin-editors.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Register the config-free UI-kit editors (`otp`, `duration`) as grid cell
+ * editors. Idempotent. Returns the list of type names it registered.
+ */
+export declare function registerBuiltinEditors(): string[];

package/dist/builtin-editors.js

@@ -0,0 +1,55 @@
+/**
+ * builtin-editors - opt-in registration of the configuration-free UI-kit editors
+ * as grid cell editors, so a column can use `editorType: 'otp'` or
+ * `editorType: 'duration'` out of the box. Call `registerBuiltinEditors()` once
+ * near your app root.
+ *
+ * It is opt-in (rather than automatic) so the editor components tree-shake away
+ * when you don't use them. Option / structured editors (SvMultiSelect,
+ * SvTreeSelect, SvGridSelect) need their `options` / `nodes` / `columns`, so
+ * register those yourself with a props mapping:
+ *
+ * ```ts
+ * import { registerCellEditor, SvMultiSelect } from '@svgrid/grid'
+ * registerCellEditor('tags', {
+ *   component: SvMultiSelect,
+ *   props: (ctx) => ({
+ *     options: TAG_OPTIONS,
+ *     value: ctx.value,
+ *     onChange: ctx.onChange,        // update the in-progress value
+ *     onCommit: () => ctx.onCommit(),// e.g. the panel's Done button
+ *   }),
+ * })
+ * ```
+ */
+import { registerCellEditor } from './editor-registry';
+import SvOtpInput from './SvOtpInput.svelte';
+import SvDurationInput from './SvDurationInput.svelte';
+/**
+ * Register the config-free UI-kit editors (`otp`, `duration`) as grid cell
+ * editors. Idempotent. Returns the list of type names it registered.
+ */
+export function registerBuiltinEditors() {
+    registerCellEditor('otp', {
+        component: SvOtpInput,
+        autoOpen: false,
+        props: (ctx) => ({
+            value: (ctx.value ?? ''),
+            autofocus: true,
+            onChange: (v) => ctx.onChange(v),
+            // The code is complete -> commit + stop editing.
+            onComplete: (v) => ctx.onCommit(v),
+        }),
+    });
+    registerCellEditor('duration', {
+        component: SvDurationInput,
+        props: (ctx) => ({
+            value: (ctx.value ?? null),
+            autofocus: true,
+            onChange: (v) => ctx.onChange(v),
+            onCommit: (v) => ctx.onCommit(v),
+            onCancel: () => ctx.onCancel(),
+        }),
+    });
+    return ['otp', 'duration'];
+}