@svgrid/grid 1.2.22 → 1.2.24

package/dist/createDateTimePicker.svelte.js

@@ -0,0 +1,202 @@
+/**
+ * createDateTimePicker - the HEADLESS core behind <SvDateTimePicker>: a
+ * runes-based state machine for a masked date-time field (format/parse via the
+ * ./datetime token engine, min/max clamping, nullable clear, spin-button
+ * stepping) plus the dropdown's open/tab state and the calendar/time-picker
+ * wiring. The render-only concerns - the portalled popover positioning, DOM
+ * refs, outside-click + reposition listeners - stay in the styled component.
+ *
+ * ```svelte
+ * <script lang="ts">
+ *   import { createDateTimePicker } from '@svgrid/grid'
+ *   let value = $state<Date | null>(new Date())
+ *   const dtp = createDateTimePicker({ value: () => value, onChange: (d) => (value = d) })
+ * </script>
+ * <input bind:value={dtp.text} {...dtp.inputProps()} />
+ * ```
+ */
+import { formatDate, parseDate } from './datetime/date-format';
+import { toDate, clampDate, withTime, startOfDay } from './datetime/date-core';
+const defaultLocale = () => (typeof navigator !== 'undefined' ? navigator.language : 'en-US');
+export function createDateTimePicker(config) {
+    const formatString = () => config.formatString?.() ?? 'yyyy-MM-dd HH:mm';
+    const nullable = () => config.nullable?.() ?? true;
+    const locale = () => config.locale?.() ?? defaultLocale();
+    const dropDownDisplayMode = () => config.dropDownDisplayMode?.() ?? 'both';
+    const spinButtons = () => config.spinButtons?.() ?? false;
+    const stepMinutes = () => config.stepMinutes?.() ?? 1;
+    const isDisabled = () => config.disabled?.() ?? false;
+    const isReadonly = () => config.readonly?.() ?? false;
+    const isInteractive = $derived(!isDisabled() && !isReadonly());
+    const minD = $derived(toDate(config.min?.() ?? null));
+    const maxD = $derived(toDate(config.max?.() ?? null));
+    let current = $state(null);
+    let text = $state('');
+    let lastKey = '￿';
+    $effect(() => {
+        const d = toDate(config.value());
+        const key = d ? String(d.getTime()) : 'null';
+        if (key !== lastKey) {
+            lastKey = key;
+            current = d;
+            text = d ? formatDate(d, formatString(), locale()) : '';
+        }
+    });
+    // --- Dropdown (open/tab) state; positioning stays in the component ----------
+    let open = $state(false);
+    let tab = $state('date');
+    const showDateTab = $derived(dropDownDisplayMode() !== 'time');
+    const showTimeTab = $derived(dropDownDisplayMode() !== 'calendar');
+    // --- Commit helpers --------------------------------------------------------
+    function commit(next) {
+        const clamped = next ? clampDate(next, minD, maxD) : null;
+        current = clamped;
+        lastKey = clamped ? String(clamped.getTime()) : 'null';
+        text = clamped ? formatDate(clamped, formatString(), locale()) : '';
+        config.onChange?.(clamped);
+    }
+    function commitFromText() {
+        const raw = text.trim();
+        if (!raw) {
+            if (nullable())
+                commit(null);
+            else
+                text = current ? formatDate(current, formatString(), locale()) : '';
+            return;
+        }
+        const parsed = parseDate(raw, formatString(), locale(), 2029, current ?? new Date());
+        if (parsed)
+            commit(parsed);
+        else
+            text = current ? formatDate(current, formatString(), locale()) : ''; // revert on bad input
+    }
+    function bump(deltaMin) {
+        const base = current ?? new Date();
+        commit(new Date(base.getTime() + deltaMin * 60000));
+    }
+    // --- Sub-picker wiring -----------------------------------------------------
+    function onCalendarChange(dates) {
+        const day = dates[0];
+        if (!day)
+            return;
+        commit(withTime(day, current ?? startOfDay(day)));
+        // Date-only picker: a single pick finalizes the value.
+        if (dropDownDisplayMode() === 'calendar') {
+            open = false;
+            config.onCommit?.(current);
+        }
+        else if (dropDownDisplayMode() === 'both')
+            tab = 'time';
+    }
+    function onTimeChange(t) {
+        const base = current ?? new Date();
+        commit(withTime(base, t));
+    }
+    // --- Dropdown control ------------------------------------------------------
+    function openPanel() {
+        if (!isInteractive || open)
+            return;
+        tab = dropDownDisplayMode() === 'time' ? 'time' : 'date';
+        open = true;
+    }
+    function closePanel() { open = false; }
+    function toggle() { (open ? closePanel : openPanel)(); }
+    function setTab(t) { tab = t; }
+    function onInputKeydown(e) {
+        if (e.key === 'Enter') {
+            e.preventDefault();
+            commitFromText();
+            closePanel();
+            config.onCommit?.(current);
+        }
+        else if (e.key === 'Escape') {
+            closePanel();
+            config.onCancel?.();
+        }
+        else if (e.key === 'ArrowDown' && (e.altKey || !text)) {
+            e.preventDefault();
+            openPanel();
+        }
+        else if (spinButtons() && e.key === 'ArrowUp') {
+            e.preventDefault();
+            bump(stepMinutes());
+        }
+        else if (spinButtons() && e.key === 'ArrowDown') {
+            e.preventDefault();
+            bump(-stepMinutes());
+        }
+    }
+    return {
+        // --- Reactive state -------------------------------------------------------
+        get current() { return current; },
+        get text() { return text; },
+        set text(v) { text = v; },
+        get open() { return open; },
+        get tab() { return tab; },
+        get isInteractive() { return isInteractive; },
+        get showDateTab() { return showDateTab; },
+        get showTimeTab() { return showTimeTab; },
+        // --- Actions --------------------------------------------------------------
+        commit,
+        commitFromText,
+        bump,
+        onCalendarChange,
+        onTimeChange,
+        openPanel,
+        closePanel,
+        toggle,
+        setTab,
+        onInputKeydown,
+        // --- Prop-getters ---------------------------------------------------------
+        /** The text field: masked value round-trips through the token engine. Spread
+         *  alongside `bind:value={dtp.text}`. */
+        inputProps() {
+            return {
+                type: 'text',
+                disabled: isDisabled(),
+                readonly: isReadonly(),
+                onblur: commitFromText,
+                onkeydown: onInputKeydown,
+            };
+        },
+        /** The calendar-toggle button. */
+        toggleProps() {
+            return {
+                type: 'button',
+                'aria-label': 'Open picker',
+                'aria-haspopup': 'dialog',
+                'aria-expanded': open,
+                disabled: !isInteractive,
+                tabindex: -1,
+                onclick: toggle,
+            };
+        },
+        /** The inline clear (x) button (nullable values). */
+        clearProps() {
+            return {
+                type: 'button',
+                'aria-label': 'Clear',
+                onclick: () => commit(null),
+            };
+        },
+        /** A spin (increment/decrement) button that steps by `stepMinutes`. */
+        spinProps(dir) {
+            return {
+                type: 'button',
+                tabindex: -1,
+                'aria-label': dir === 1 ? 'Increment' : 'Decrement',
+                disabled: !isInteractive,
+                onclick: () => bump(dir * stepMinutes()),
+            };
+        },
+        /** A DATE / TIME tab button. */
+        tabProps(which) {
+            return {
+                type: 'button',
+                role: 'tab',
+                'aria-selected': tab === which,
+                onclick: () => setTab(which),
+            };
+        },
+    };
+}

package/dist/createDropdownList.svelte.d.ts

@@ -0,0 +1,78 @@
+/**
+ * createDropdownList - the HEADLESS core behind <SvDropDownList>: a single-select
+ * dropdown state machine (trigger open/close, roving active index over enabled
+ * options, full keyboard) exposed as **prop-getters** you spread onto YOUR OWN
+ * markup. No styles, no DOM, no portal/measurement - those stay in the styled
+ * component.
+ *
+ * ```svelte
+ * <script lang="ts">
+ *   import { createDropdownList } from '@svgrid/grid'
+ *   let value = $state<string | null>(null)
+ *   const dd = createDropdownList({ options: () => options, value: () => value, onChange: (v) => (value = v) })
+ * </script>
+ * <button {...dd.triggerProps()}>{dd.selected?.label ?? 'Select'}</button>
+ * {#if dd.open}
+ *   <ul {...dd.listboxProps()}>
+ *     {#each options as opt, i (opt.value)}<li {...dd.optionProps(i)}>{opt.label}</li>{/each}
+ *   </ul>
+ * {/if}
+ * ```
+ */
+import type { ListOption } from './list-option';
+export type DropdownValue = string | number | null;
+/** Reactive inputs are passed as getters so the core tracks live prop changes. */
+export type DropdownListConfig = {
+    options: () => ReadonlyArray<ListOption>;
+    value: () => DropdownValue;
+    onChange?: (value: string | number) => void;
+    disabled?: () => boolean;
+    ariaLabel?: () => string | undefined;
+    /** DOM focus hook provided by the renderer; the core never touches the DOM. */
+    focusTrigger?: () => void;
+};
+export declare function createDropdownList(config: DropdownListConfig): {
+    /** Panel open state. */
+    readonly open: boolean;
+    /** Highlighted option index into `options`. */
+    readonly activeIndex: number;
+    /** The option matching the controlled value, if any. */
+    readonly selected: ListOption | null;
+    /** Controlled value. */
+    readonly value: DropdownValue;
+    isActive: (i: number) => boolean;
+    isSelected: (o: ListOption) => boolean;
+    setActive: (i: number) => void;
+    openPanel: () => void;
+    close: () => void;
+    toggle: () => void;
+    pick: (i: number) => void;
+    move: (d: number) => void;
+    onKeydown: (e: KeyboardEvent) => void;
+    /** Spread onto the trigger <button>. */
+    triggerProps: () => {
+        type: "button";
+        'aria-haspopup': "listbox";
+        'aria-expanded': boolean;
+        'aria-label': string | undefined;
+        disabled: boolean;
+        onclick: () => void;
+        onkeydown: (e: KeyboardEvent) => void;
+    };
+    /** Spread onto the listbox container. */
+    listboxProps: () => {
+        role: "listbox";
+        tabindex: number;
+    };
+    /** Spread onto the option at `index` (index into `options`). */
+    optionProps: (index: number) => {
+        role: "option";
+        tabindex: number;
+        'aria-selected': boolean;
+        'aria-disabled': boolean | undefined;
+        'data-idx': number;
+        onclick: () => void;
+        onpointermove: () => void;
+    };
+};
+export type DropdownList = ReturnType<typeof createDropdownList>;

package/dist/createDropdownList.svelte.js

@@ -0,0 +1,117 @@
+export function createDropdownList(config) {
+    const opts = () => config.options();
+    const disabled = () => config.disabled?.() ?? false;
+    let open = $state(false);
+    let active = $state(-1);
+    const selected = $derived(opts().find((o) => o.value === config.value()) ?? null);
+    const enabledIdx = $derived(opts().map((o, i) => (o.disabled ? -1 : i)).filter((i) => i >= 0));
+    function openPanel() {
+        if (disabled() || open)
+            return;
+        open = true;
+        active = Math.max(0, opts().findIndex((o) => o.value === config.value()));
+    }
+    function close() { open = false; }
+    function toggle() { if (open) {
+        close();
+    }
+    else {
+        openPanel();
+    } }
+    function pick(i) {
+        const o = opts()[i];
+        if (!o || o.disabled)
+            return;
+        config.onChange?.(o.value);
+        close();
+        config.focusTrigger?.();
+    }
+    function setActive(i) { const o = opts()[i]; if (o && !o.disabled)
+        active = i; }
+    function move(d) {
+        const pos = enabledIdx.indexOf(active);
+        active = enabledIdx[(pos + d + enabledIdx.length) % enabledIdx.length] ?? active;
+    }
+    function onKeydown(e) {
+        if (disabled())
+            return;
+        if (!open && (e.key === 'ArrowDown' || e.key === 'Enter' || e.key === ' ')) {
+            e.preventDefault();
+            openPanel();
+            return;
+        }
+        if (!open)
+            return;
+        if (e.key === 'ArrowDown') {
+            e.preventDefault();
+            move(1);
+        }
+        else if (e.key === 'ArrowUp') {
+            e.preventDefault();
+            move(-1);
+        }
+        else if (e.key === 'Enter' || e.key === ' ') {
+            e.preventDefault();
+            pick(active);
+        }
+        else if (e.key === 'Escape') {
+            e.preventDefault();
+            close();
+            config.focusTrigger?.();
+        }
+        else if (e.key === 'Home') {
+            active = enabledIdx[0] ?? 0;
+        }
+        else if (e.key === 'End') {
+            active = enabledIdx.at(-1) ?? 0;
+        }
+    }
+    return {
+        /** Panel open state. */
+        get open() { return open; },
+        /** Highlighted option index into `options`. */
+        get activeIndex() { return active; },
+        /** The option matching the controlled value, if any. */
+        get selected() { return selected; },
+        /** Controlled value. */
+        get value() { return config.value(); },
+        isActive: (i) => i === active,
+        isSelected: (o) => o.value === config.value(),
+        setActive,
+        openPanel,
+        close,
+        toggle,
+        pick,
+        move,
+        onKeydown,
+        /** Spread onto the trigger <button>. */
+        triggerProps: () => ({
+            type: 'button',
+            'aria-haspopup': 'listbox',
+            'aria-expanded': open,
+            'aria-label': config.ariaLabel?.(),
+            disabled: disabled(),
+            onclick: toggle,
+            onkeydown: onKeydown,
+        }),
+        /** Spread onto the listbox container. */
+        listboxProps: () => ({
+            role: 'listbox',
+            tabindex: -1,
+        }),
+        /** Spread onto the option at `index` (index into `options`). */
+        optionProps: (index) => {
+            const o = opts()[index];
+            return {
+                role: 'option',
+                tabindex: -1,
+                'aria-selected': o ? o.value === config.value() : false,
+                'aria-disabled': o?.disabled,
+                'data-idx': index,
+                onclick: () => pick(index),
+                onpointermove: () => { if (o && !o.disabled)
+                    active = index; },
+            };
+        },
+    };
+}

package/dist/createGauge.svelte.d.ts

@@ -0,0 +1,56 @@
+/**
+ * createGauge - the HEADLESS core behind <SvGauge>. A gauge is a display control,
+ * so this core is light: value in, computed arc/needle geometry out, plus a
+ * `rootProps()` with `role="meter"` + `aria-valuenow/min/max`. The styled
+ * <SvGauge> (or your own SVG) reads the geometry and draws it.
+ *
+ * ```svelte
+ * <script lang="ts">
+ *   import { createGauge } from '@svgrid/grid'
+ *   const g = createGauge({ value: () => value })
+ * </script>
+ * <div {...g.rootProps()}>
+ *   <svg viewBox={`0 0 ${g.cx * 2} ${g.cy * 2}`}>
+ *     <path d={g.arcPath(0, g.clamped, g.r)} />
+ *   </svg>
+ * </div>
+ * ```
+ */
+export type GaugePoint = {
+    x: number;
+    y: number;
+};
+/** Reactive inputs are passed as getters so the core tracks live prop changes. */
+export type GaugeConfig = {
+    value: () => number;
+    min?: () => number;
+    max?: () => number;
+    /** Sweep angle in degrees (default 270, a classic dashboard gauge). */
+    sweep?: () => number;
+    size?: () => number;
+    thickness?: () => number;
+    ariaLabel?: () => string | undefined;
+};
+export declare function createGauge(config: GaugeConfig): {
+    /** Value clamped into [min, max]. */
+    readonly clamped: number;
+    readonly startAngle: number;
+    readonly cx: number;
+    readonly cy: number;
+    readonly r: number;
+    /** Needle tip point (for `<line x2 y2>`). */
+    readonly needleEnd: GaugePoint;
+    frac: (v: number) => number;
+    angleOf: (v: number) => number;
+    polar: (angleDeg: number, radius: number) => GaugePoint;
+    arcPath: (v0: number, v1: number, radius: number) => string;
+    /** Spread onto the gauge root element. */
+    rootProps: () => {
+        role: "meter";
+        'aria-valuenow': number;
+        'aria-valuemin': number;
+        'aria-valuemax': number;
+        'aria-label': string;
+    };
+};
+export type Gauge = ReturnType<typeof createGauge>;

package/dist/createGauge.svelte.js

@@ -0,0 +1,49 @@
+export function createGauge(config) {
+    const min = () => config.min?.() ?? 0;
+    const max = () => config.max?.() ?? 100;
+    const sweep = () => config.sweep?.() ?? 270;
+    const size = () => config.size?.() ?? 180;
+    const thickness = () => config.thickness?.() ?? 14;
+    const clamped = $derived(Math.min(max(), Math.max(min(), config.value())));
+    const startAngle = $derived(90 + (360 - sweep()) / 2); // symmetric around the bottom
+    const cx = $derived(size() / 2);
+    const cy = $derived(size() / 2);
+    const r = $derived(size() / 2 - thickness() / 2 - 2);
+    const frac = (v) => (v - min()) / (max() - min());
+    const angleOf = (v) => startAngle + frac(v) * sweep();
+    function polar(angleDeg, radius) {
+        const a = (angleDeg * Math.PI) / 180;
+        return { x: cx + radius * Math.cos(a), y: cy + radius * Math.sin(a) };
+    }
+    function arcPath(v0, v1, radius) {
+        const a0 = angleOf(v0);
+        const a1 = angleOf(v1);
+        const p0 = polar(a0, radius);
+        const p1 = polar(a1, radius);
+        const large = a1 - a0 > 180 ? 1 : 0;
+        return `M ${p0.x} ${p0.y} A ${radius} ${radius} 0 ${large} 1 ${p1.x} ${p1.y}`;
+    }
+    const needleEnd = $derived(polar(angleOf(clamped), r - thickness() / 2));
+    return {
+        /** Value clamped into [min, max]. */
+        get clamped() { return clamped; },
+        get startAngle() { return startAngle; },
+        get cx() { return cx; },
+        get cy() { return cy; },
+        get r() { return r; },
+        /** Needle tip point (for `<line x2 y2>`). */
+        get needleEnd() { return needleEnd; },
+        frac,
+        angleOf,
+        polar,
+        arcPath,
+        /** Spread onto the gauge root element. */
+        rootProps: () => ({
+            role: 'meter',
+            'aria-valuenow': clamped,
+            'aria-valuemin': min(),
+            'aria-valuemax': max(),
+            'aria-label': config.ariaLabel?.() ?? 'Gauge',
+        }),
+    };
+}

package/dist/createListbox.svelte.d.ts

@@ -0,0 +1,79 @@
+/**
+ * createListbox - the HEADLESS core behind <SvListBox>, in the same spirit as
+ * `createSvGrid` for the grid: a runes-based state machine (roving active index,
+ * single/multi selection, full keyboard) with **prop-getters** you spread onto
+ * YOUR OWN markup. No styles, no DOM assumptions - render it however you like.
+ *
+ * ```svelte
+ * <script lang="ts">
+ *   import { createListbox } from '@svgrid/grid'
+ *   let value = $state<string | null>(null)
+ *   const lb = createListbox({
+ *     options: () => options, value: () => value,
+ *     onChange: (v) => (value = v),
+ *   })
+ * </script>
+ * <ul {...lb.rootProps()}>
+ *   {#each options as opt, i}
+ *     <li {...lb.optionProps(i)}>{opt.label}</li>
+ *   {/each}
+ * </ul>
+ * ```
+ *
+ * The styled <SvListBox> is just one renderer over this core.
+ */
+import type { ListOption } from './list-option';
+export type ListboxValue = string | number | Array<string | number> | null;
+/** Reactive inputs are passed as getters so the core tracks live prop changes
+ *  (the same controlled pattern Svelte headless libraries use). */
+export type ListboxConfig = {
+    options: () => ReadonlyArray<ListOption>;
+    value: () => ListboxValue;
+    onChange?: (value: string | number | Array<string | number>) => void;
+    multiple?: () => boolean;
+    disabled?: () => boolean;
+    ariaLabel?: () => string | undefined;
+};
+export type OptionProps = {
+    role: 'option';
+    id: string;
+    'aria-selected': boolean;
+    'aria-disabled': boolean | undefined;
+    'data-idx': number;
+    'data-active': '' | undefined;
+    'data-selected': '' | undefined;
+    onclick: () => void;
+    onpointermove: () => void;
+};
+export type ListboxRootProps = {
+    role: 'listbox';
+    'aria-multiselectable': boolean;
+    'aria-label': string | undefined;
+    'aria-disabled': boolean;
+    'aria-activedescendant': string | undefined;
+    tabindex: number;
+    onkeydown: (e: KeyboardEvent) => void;
+};
+export type Listbox = {
+    /** Currently highlighted option index (roving focus). */
+    readonly activeIndex: number;
+    /** Selected values as an array (single mode -> 0 or 1 entry). */
+    readonly selectedValues: Array<string | number>;
+    isSelected: (value: string | number) => boolean;
+    isActive: (index: number) => boolean;
+    setActive: (index: number) => void;
+    /** Toggle (multi) / set (single) the option at `index`. */
+    pick: (index: number) => void;
+    /** Move the active highlight by `delta`, wrapping over enabled options. */
+    move: (delta: number) => void;
+    first: () => void;
+    last: () => void;
+    onKeydown: (e: KeyboardEvent) => void;
+    /** Spread onto the list container element. */
+    rootProps: () => ListboxRootProps;
+    /** Spread onto the option element at `index`. */
+    optionProps: (index: number) => OptionProps;
+};
+/** Normalize a listbox value to an array (pure). */
+export declare function toSelectedArray(value: ListboxValue, multiple: boolean): Array<string | number>;
+export declare function createListbox(config: ListboxConfig): Listbox;