@svgrid/grid 1.2.22 → 1.2.24

package/dist/createToggle.svelte.d.ts

@@ -0,0 +1,43 @@
+/**
+ * createToggle - the HEADLESS core behind <SvToggleButton>, in the same spirit
+ * as `createSvGrid`: a tiny controlled state machine (a single pressed on/off
+ * bit + ARIA) exposed as **prop-getters** you spread onto YOUR OWN markup. No
+ * styles, no DOM assumptions.
+ *
+ * ```svelte
+ * <script lang="ts">
+ *   import { createToggle } from '@svgrid/grid'
+ *   let pressed = $state(false)
+ *   const t = createToggle({ pressed: () => pressed, onChange: (v) => (pressed = v) })
+ * </script>
+ * <button {...t.buttonProps()}>Bold</button>
+ * ```
+ *
+ * The styled <SvToggleButton> is just one renderer over this core.
+ */
+/** Reactive inputs are passed as getters so the core tracks live prop changes
+ *  (the same controlled pattern used across the SvGrid UI kit). */
+export type ToggleConfig = {
+    pressed: () => boolean;
+    onChange?: (pressed: boolean) => void;
+    disabled?: () => boolean;
+    ariaLabel?: () => string | undefined;
+};
+export type ToggleButtonProps = {
+    type: 'button';
+    'aria-pressed': boolean;
+    'aria-label': string | undefined;
+    disabled: boolean;
+    'data-pressed': '' | undefined;
+    onclick: () => void;
+};
+export type Toggle = {
+    /** Current pressed state. */
+    readonly pressed: boolean;
+    readonly disabled: boolean;
+    /** Flip pressed (no-op when disabled). */
+    toggle: () => void;
+    /** Spread onto the button element. */
+    buttonProps: () => ToggleButtonProps;
+};
+export declare function createToggle(config: ToggleConfig): Toggle;

package/dist/createToggle.svelte.js

@@ -0,0 +1,39 @@
+/**
+ * createToggle - the HEADLESS core behind <SvToggleButton>, in the same spirit
+ * as `createSvGrid`: a tiny controlled state machine (a single pressed on/off
+ * bit + ARIA) exposed as **prop-getters** you spread onto YOUR OWN markup. No
+ * styles, no DOM assumptions.
+ *
+ * ```svelte
+ * <script lang="ts">
+ *   import { createToggle } from '@svgrid/grid'
+ *   let pressed = $state(false)
+ *   const t = createToggle({ pressed: () => pressed, onChange: (v) => (pressed = v) })
+ * </script>
+ * <button {...t.buttonProps()}>Bold</button>
+ * ```
+ *
+ * The styled <SvToggleButton> is just one renderer over this core.
+ */
+export function createToggle(config) {
+    const pressed = () => config.pressed();
+    const disabled = () => config.disabled?.() ?? false;
+    function toggle() {
+        if (disabled())
+            return;
+        config.onChange?.(!pressed());
+    }
+    return {
+        get pressed() { return pressed(); },
+        get disabled() { return disabled(); },
+        toggle,
+        buttonProps: () => ({
+            type: 'button',
+            'aria-pressed': pressed(),
+            'aria-label': config.ariaLabel?.(),
+            disabled: disabled(),
+            'data-pressed': pressed() ? '' : undefined,
+            onclick: toggle,
+        }),
+    };
+}

package/dist/createTree.svelte.d.ts

@@ -0,0 +1,96 @@
+/**
+ * createTree - the HEADLESS core behind <SvTree>, in the same spirit as
+ * `createSvGrid` for the grid: a runes-based state machine (expand/collapse,
+ * single-select highlight, cascading tri-state checkboxes, full keyboard) with
+ * **prop-getters** you spread onto YOUR OWN markup. The visible tree is
+ * flattened into `rows` so roving-focus keyboard nav stays a flat index walk.
+ *
+ * ```svelte
+ * <script lang="ts">
+ *   import { createTree } from '@svgrid/grid'
+ *   let selected = $state<string | null>(null)
+ *   const tree = createTree({ nodes: () => nodes, selected: () => selected, onSelect: (id) => (selected = id) })
+ * </script>
+ * <div {...tree.treeProps()}>
+ *   {#each tree.rows as row (row.node.id)}
+ *     <div {...tree.itemProps(row)}>{row.node.label}</div>
+ *   {/each}
+ * </div>
+ * ```
+ *
+ * The styled <SvTree> is just one renderer over this core. The cascade math
+ * (`treeDescendantIds`, `treeCheckState`) is exported as pure functions.
+ */
+export type TreeNode = {
+    id: string;
+    label: string;
+    children?: TreeNode[];
+    disabled?: boolean;
+};
+export type CheckState = 'checked' | 'indeterminate' | 'unchecked';
+/** A single visible (flattened) tree row. */
+export type TreeRow = {
+    node: TreeNode;
+    depth: number;
+    hasChildren: boolean;
+    open: boolean;
+    parentId: string | null;
+    index: number;
+};
+/** All descendant ids of `node` (pure, depth-first). */
+export declare function treeDescendantIds(node: TreeNode): string[];
+/** Tri-state check status of `node` given the set of checked ids (pure). */
+export declare function treeCheckState(node: TreeNode, checked: ReadonlySet<string>): CheckState;
+/** Reactive inputs are passed as getters so the core tracks live prop changes. */
+export type TreeConfig = {
+    nodes: () => ReadonlyArray<TreeNode>;
+    selected?: () => string | null;
+    onSelect?: (id: string) => void;
+    /** Seed the internally-managed expanded set (read once). */
+    expandedIds?: () => string[] | undefined;
+    onToggle?: (id: string, expanded: boolean) => void;
+    checkable?: () => boolean;
+    checked?: () => string[];
+    onCheck?: (ids: string[]) => void;
+    ariaLabel?: () => string | undefined;
+};
+export declare function createTree(config: TreeConfig): {
+    /** Internally-managed set of expanded node ids. */
+    readonly expanded: Set<string>;
+    /** Selected node id (single-select highlight). */
+    readonly selected: string | null;
+    /** Flattened list of visible rows. */
+    readonly rows: TreeRow[];
+    /** Roving-focus row index. */
+    readonly activeIndex: number;
+    /** Monotonic counter; changes only on keyboard navigation. */
+    readonly focusTick: number;
+    isExpanded: (id: string) => boolean;
+    isSelected: (id: string) => boolean;
+    checkStateOf: (node: TreeNode) => CheckState;
+    toggle: (id: string) => void;
+    toggleExpand: (node: TreeNode) => void;
+    select: (id: string) => void;
+    toggleCheck: (node: TreeNode) => void;
+    setActive: (i: number, focus?: boolean) => void;
+    onKeydown: (e: KeyboardEvent) => void;
+    /** Spread onto the tree container element. */
+    treeProps: () => {
+        role: "tree";
+        'aria-label': string | undefined;
+        'aria-multiselectable': boolean;
+    };
+    /** Spread onto the treeitem element for a flattened `row`. */
+    itemProps: (row: TreeRow) => {
+        role: "treeitem";
+        'aria-level': number;
+        'aria-selected': boolean;
+        'aria-expanded': boolean | undefined;
+        'aria-checked': "true" | "mixed" | "false" | undefined;
+        'data-row': number;
+        tabindex: number;
+        onclick: () => void;
+        onkeydown: (e: KeyboardEvent) => void;
+    };
+};
+export type Tree = ReturnType<typeof createTree>;

package/dist/createTree.svelte.js

@@ -0,0 +1,194 @@
+/** All descendant ids of `node` (pure, depth-first). */
+export function treeDescendantIds(node) {
+    const ids = [];
+    const walk = (n) => { for (const c of n.children ?? []) {
+        ids.push(c.id);
+        walk(c);
+    } };
+    walk(node);
+    return ids;
+}
+/** Tri-state check status of `node` given the set of checked ids (pure). */
+export function treeCheckState(node, checked) {
+    if (!node.children?.length)
+        return checked.has(node.id) ? 'checked' : 'unchecked';
+    const desc = treeDescendantIds(node);
+    const on = desc.filter((id) => checked.has(id)).length;
+    if (on === 0 && !checked.has(node.id))
+        return 'unchecked';
+    if (on === desc.length)
+        return 'checked';
+    return 'indeterminate';
+}
+function findNode(list, id) {
+    for (const n of list) {
+        if (n.id === id)
+            return n;
+        if (n.children) {
+            const f = findNode(n.children, id);
+            if (f)
+                return f;
+        }
+    }
+    return null;
+}
+export function createTree(config) {
+    const nodes = () => config.nodes();
+    const checkable = () => config.checkable?.() ?? false;
+    const selected = () => config.selected?.() ?? null;
+    // Internal expanded set, seeded from the prop once (then self-managed).
+    let expanded = $state(new Set());
+    let seeded = false;
+    $effect(() => {
+        if (!seeded) {
+            seeded = true;
+            const ids = config.expandedIds?.();
+            if (ids)
+                expanded = new Set(ids);
+        }
+    });
+    const rows = $derived.by(() => {
+        const out = [];
+        const walk = (list, depth, parentId) => {
+            for (const node of list) {
+                const hasChildren = !!node.children?.length;
+                const open = expanded.has(node.id);
+                out.push({ node, depth, hasChildren, open, parentId, index: out.length });
+                if (hasChildren && open)
+                    walk(node.children, depth + 1, node.id);
+            }
+        };
+        walk(nodes(), 0, null);
+        return out;
+    });
+    let active = $state(0);
+    $effect(() => { if (active >= rows.length)
+        active = Math.max(0, rows.length - 1); });
+    const checkedSet = $derived(new Set(config.checked?.() ?? []));
+    // Roving focus target; `focusTick` bumps only on keyboard moves.
+    let focusTick = $state(0);
+    function setActive(i, focus = false) { active = i; if (focus)
+        focusTick++; }
+    const checkStateOf = (node) => treeCheckState(node, checkedSet);
+    const isExpanded = (id) => expanded.has(id);
+    const isSelected = (id) => id === selected();
+    function toggleExpand(node) {
+        if (!node.children?.length)
+            return;
+        const next = new Set(expanded);
+        const willOpen = !next.has(node.id);
+        willOpen ? next.add(node.id) : next.delete(node.id);
+        expanded = next;
+        config.onToggle?.(node.id, willOpen);
+    }
+    const toggle = (id) => { const n = findNode(nodes(), id); if (n)
+        toggleExpand(n); };
+    function select(node) {
+        if (node.disabled)
+            return;
+        config.onSelect?.(node.id);
+    }
+    const selectId = (id) => { const n = findNode(nodes(), id); if (n)
+        select(n); };
+    function toggleCheck(node) {
+        if (node.disabled)
+            return;
+        const next = new Set(checkedSet);
+        const ids = [node.id, ...treeDescendantIds(node)];
+        const currentlyOn = checkStateOf(node) === 'checked';
+        for (const id of ids)
+            currentlyOn ? next.delete(id) : next.add(id);
+        config.onCheck?.([...next]);
+    }
+    function onKeydown(e) {
+        const item = rows[active];
+        if (!item)
+            return;
+        switch (e.key) {
+            case 'ArrowDown':
+                e.preventDefault();
+                setActive(Math.min(active + 1, rows.length - 1), true);
+                break;
+            case 'ArrowUp':
+                e.preventDefault();
+                setActive(Math.max(active - 1, 0), true);
+                break;
+            case 'ArrowRight':
+                e.preventDefault();
+                if (item.hasChildren && !item.open)
+                    toggleExpand(item.node);
+                else if (item.hasChildren && item.open)
+                    setActive(Math.min(active + 1, rows.length - 1), true);
+                break;
+            case 'ArrowLeft':
+                e.preventDefault();
+                if (item.hasChildren && item.open)
+                    toggleExpand(item.node);
+                else if (item.parentId) {
+                    const pi = rows.findIndex((r) => r.node.id === item.parentId);
+                    if (pi >= 0)
+                        setActive(pi, true);
+                }
+                break;
+            case 'Enter':
+                e.preventDefault();
+                select(item.node);
+                break;
+            case ' ':
+                e.preventDefault();
+                checkable() ? toggleCheck(item.node) : select(item.node);
+                break;
+            case 'Home':
+                e.preventDefault();
+                setActive(0, true);
+                break;
+            case 'End':
+                e.preventDefault();
+                setActive(rows.length - 1, true);
+                break;
+        }
+    }
+    return {
+        /** Internally-managed set of expanded node ids. */
+        get expanded() { return expanded; },
+        /** Selected node id (single-select highlight). */
+        get selected() { return selected(); },
+        /** Flattened list of visible rows. */
+        get rows() { return rows; },
+        /** Roving-focus row index. */
+        get activeIndex() { return active; },
+        /** Monotonic counter; changes only on keyboard navigation. */
+        get focusTick() { return focusTick; },
+        isExpanded,
+        isSelected,
+        checkStateOf,
+        toggle,
+        toggleExpand,
+        select: selectId,
+        toggleCheck,
+        setActive,
+        onKeydown,
+        /** Spread onto the tree container element. */
+        treeProps: () => ({
+            role: 'tree',
+            'aria-label': config.ariaLabel?.(),
+            'aria-multiselectable': checkable(),
+        }),
+        /** Spread onto the treeitem element for a flattened `row`. */
+        itemProps: (row) => {
+            const cs = checkable() ? checkStateOf(row.node) : 'unchecked';
+            const ariaChecked = checkable() ? (cs === 'checked' ? 'true' : cs === 'indeterminate' ? 'mixed' : 'false') : undefined;
+            return {
+                role: 'treeitem',
+                'aria-level': row.depth + 1,
+                'aria-selected': row.node.id === selected(),
+                'aria-expanded': row.hasChildren ? row.open : undefined,
+                'aria-checked': ariaChecked,
+                'data-row': row.index,
+                tabindex: row.index === active ? 0 : -1,
+                onclick: () => { setActive(row.index); select(row.node); },
+                onkeydown: onKeydown,
+            };
+        },
+    };
+}

package/dist/datetime/date-core.d.ts

@@ -0,0 +1,88 @@
+/**
+ * date-core - framework-free date math shared by SvCalendar, SvTimePicker and
+ * SvDateTimePicker. No Svelte, no DOM: pure functions over the native `Date`
+ * so it is trivially unit- and mutation-testable and reusable standalone.
+ *
+ * Conventions:
+ * - A "day" is compared by local calendar date (year/month/date), ignoring the
+ *   time-of-day, unless a helper says otherwise.
+ * - `firstDayOfWeek` is 0-6 (0 = Sunday), matching `Date.getDay()` and Smart's
+ *   `firstDayOfWeek`.
+ */
+export type DateLike = Date | number | string;
+/** Coerce a Date | epoch-ms | parseable string to a Date, or null if invalid. */
+export declare function toDate(value: DateLike | null | undefined): Date | null;
+/** A new Date at local midnight of the same calendar day (time stripped). */
+export declare function startOfDay(d: Date): Date;
+/** First day (midnight) of the month `d` falls in. */
+export declare function startOfMonth(d: Date): Date;
+/** Last day (midnight) of the month `d` falls in. */
+export declare function endOfMonth(d: Date): Date;
+/** Number of days in the month `d` falls in. */
+export declare function daysInMonth(d: Date): number;
+/**
+ * Start of the week containing `d`, honoring `firstDayOfWeek` (0-6). Returns a
+ * local-midnight Date on or before `d`.
+ */
+export declare function startOfWeek(d: Date, firstDayOfWeek?: number): Date;
+/** True when both dates are the same local calendar day. */
+export declare function isSameDay(a: Date | null, b: Date | null): boolean;
+/** True when both dates are in the same year+month. */
+export declare function isSameMonth(a: Date | null, b: Date | null): boolean;
+/** -1 / 0 / 1 comparison by calendar day (time-of-day ignored). */
+export declare function compareDay(a: Date, b: Date): number;
+/** Add `n` days (can be negative), returning a new Date. */
+export declare function addDays(d: Date, n: number): Date;
+/**
+ * Add `n` calendar months, clamping the day-of-month so 31 Jan + 1 month = 28/29
+ * Feb rather than spilling into March (matches how calendars paginate).
+ */
+export declare function addMonths(d: Date, n: number): Date;
+/** Add `n` years, clamping Feb-29 to Feb-28 on non-leap targets. */
+export declare function addYears(d: Date, n: number): Date;
+/** Clamp `d` to the inclusive [min, max] range (either bound may be null). */
+export declare function clampDate(d: Date, min: Date | null, max: Date | null): Date;
+/**
+ * ISO 8601 week number (1-53) for `d`. Week 1 is the week containing the first
+ * Thursday of the year; weeks start Monday. Independent of `firstDayOfWeek`,
+ * matching Smart's `weekNumbers` column which is always ISO.
+ */
+export declare function isoWeek(d: Date): number;
+/**
+ * The [start, end] years of the decade block that `year` belongs to, as Smart
+ * renders it: a 12-cell page running from the decade start minus 1 to plus 10
+ * (one leading + one trailing year for context). We expose the canonical
+ * decade [Y0, Y0+9] and let the view pad.
+ */
+export declare function decadeRange(year: number): {
+    start: number;
+    end: number;
+};
+/** The [start, end] years of the century block (100-year) `year` belongs to. */
+export declare function centuryRange(year: number): {
+    start: number;
+    end: number;
+};
+export type MonthMatrixCell = {
+    date: Date;
+    /** In the displayed month (vs. leading/trailing days of adjacent months). */
+    inMonth: boolean;
+    /** ISO week number of the row this cell sits in. */
+    week: number;
+};
+/**
+ * Build a month grid of `weeks` rows x 7 columns starting at `firstDayOfWeek`,
+ * padded with the trailing days of the previous month and leading days of the
+ * next so every row is full. `weeks` defaults to 6 (the max any month needs),
+ * matching Smart's fixed-height calendar.
+ */
+export declare function monthMatrix(monthDate: Date, firstDayOfWeek?: number, weeks?: number): MonthMatrixCell[][];
+/**
+ * Ordered weekday indexes (0-6) for a header row starting at `firstDayOfWeek`.
+ * e.g. firstDayOfWeek=1 -> [1,2,3,4,5,6,0].
+ */
+export declare function weekdayOrder(firstDayOfWeek?: number): number[];
+/** Merge a calendar day with a time-of-day taken from `time`, returning a new Date. */
+export declare function withTime(day: Date, time: Date): Date;
+/** Snap a minute value to the nearest lower multiple of `interval` (>=1). */
+export declare function snapMinute(minute: number, interval: number): number;

package/dist/datetime/date-core.js

@@ -0,0 +1,165 @@
+/**
+ * date-core - framework-free date math shared by SvCalendar, SvTimePicker and
+ * SvDateTimePicker. No Svelte, no DOM: pure functions over the native `Date`
+ * so it is trivially unit- and mutation-testable and reusable standalone.
+ *
+ * Conventions:
+ * - A "day" is compared by local calendar date (year/month/date), ignoring the
+ *   time-of-day, unless a helper says otherwise.
+ * - `firstDayOfWeek` is 0-6 (0 = Sunday), matching `Date.getDay()` and Smart's
+ *   `firstDayOfWeek`.
+ */
+/** Coerce a Date | epoch-ms | parseable string to a Date, or null if invalid. */
+export function toDate(value) {
+    if (value == null)
+        return null;
+    const d = value instanceof Date ? new Date(value.getTime()) : new Date(value);
+    return isNaN(d.getTime()) ? null : d;
+}
+/** A new Date at local midnight of the same calendar day (time stripped). */
+export function startOfDay(d) {
+    return new Date(d.getFullYear(), d.getMonth(), d.getDate());
+}
+/** First day (midnight) of the month `d` falls in. */
+export function startOfMonth(d) {
+    return new Date(d.getFullYear(), d.getMonth(), 1);
+}
+/** Last day (midnight) of the month `d` falls in. */
+export function endOfMonth(d) {
+    return new Date(d.getFullYear(), d.getMonth() + 1, 0);
+}
+/** Number of days in the month `d` falls in. */
+export function daysInMonth(d) {
+    return endOfMonth(d).getDate();
+}
+/**
+ * Start of the week containing `d`, honoring `firstDayOfWeek` (0-6). Returns a
+ * local-midnight Date on or before `d`.
+ */
+export function startOfWeek(d, firstDayOfWeek = 0) {
+    const start = startOfDay(d);
+    const diff = (start.getDay() - firstDayOfWeek + 7) % 7;
+    start.setDate(start.getDate() - diff);
+    return start;
+}
+/** True when both dates are the same local calendar day. */
+export function isSameDay(a, b) {
+    if (!a || !b)
+        return false;
+    return (a.getFullYear() === b.getFullYear() &&
+        a.getMonth() === b.getMonth() &&
+        a.getDate() === b.getDate());
+}
+/** True when both dates are in the same year+month. */
+export function isSameMonth(a, b) {
+    if (!a || !b)
+        return false;
+    return a.getFullYear() === b.getFullYear() && a.getMonth() === b.getMonth();
+}
+/** -1 / 0 / 1 comparison by calendar day (time-of-day ignored). */
+export function compareDay(a, b) {
+    const av = startOfDay(a).getTime();
+    const bv = startOfDay(b).getTime();
+    return av < bv ? -1 : av > bv ? 1 : 0;
+}
+/** Add `n` days (can be negative), returning a new Date. */
+export function addDays(d, n) {
+    const r = new Date(d.getTime());
+    r.setDate(r.getDate() + n);
+    return r;
+}
+/**
+ * Add `n` calendar months, clamping the day-of-month so 31 Jan + 1 month = 28/29
+ * Feb rather than spilling into March (matches how calendars paginate).
+ */
+export function addMonths(d, n) {
+    const day = d.getDate();
+    const r = new Date(d.getFullYear(), d.getMonth() + n, 1, d.getHours(), d.getMinutes(), d.getSeconds(), d.getMilliseconds());
+    r.setDate(Math.min(day, daysInMonth(r)));
+    return r;
+}
+/** Add `n` years, clamping Feb-29 to Feb-28 on non-leap targets. */
+export function addYears(d, n) {
+    return addMonths(d, n * 12);
+}
+/** Clamp `d` to the inclusive [min, max] range (either bound may be null). */
+export function clampDate(d, min, max) {
+    if (min && d.getTime() < min.getTime())
+        return new Date(min.getTime());
+    if (max && d.getTime() > max.getTime())
+        return new Date(max.getTime());
+    return d;
+}
+/**
+ * ISO 8601 week number (1-53) for `d`. Week 1 is the week containing the first
+ * Thursday of the year; weeks start Monday. Independent of `firstDayOfWeek`,
+ * matching Smart's `weekNumbers` column which is always ISO.
+ */
+export function isoWeek(d) {
+    // Shift to the Thursday of this week, then count weeks from Jan 1.
+    const date = startOfDay(d);
+    const day = (date.getDay() + 6) % 7; // Mon=0..Sun=6
+    date.setDate(date.getDate() - day + 3); // Thursday of this week
+    const firstThursday = new Date(date.getFullYear(), 0, 4);
+    const firstDay = (firstThursday.getDay() + 6) % 7;
+    firstThursday.setDate(firstThursday.getDate() - firstDay + 3);
+    const diffMs = date.getTime() - firstThursday.getTime();
+    return 1 + Math.round(diffMs / (7 * 24 * 3600 * 1000));
+}
+/**
+ * The [start, end] years of the decade block that `year` belongs to, as Smart
+ * renders it: a 12-cell page running from the decade start minus 1 to plus 10
+ * (one leading + one trailing year for context). We expose the canonical
+ * decade [Y0, Y0+9] and let the view pad.
+ */
+export function decadeRange(year) {
+    const start = Math.floor(year / 10) * 10;
+    return { start, end: start + 9 };
+}
+/** The [start, end] years of the century block (100-year) `year` belongs to. */
+export function centuryRange(year) {
+    const start = Math.floor(year / 100) * 100;
+    return { start, end: start + 99 };
+}
+/**
+ * Build a month grid of `weeks` rows x 7 columns starting at `firstDayOfWeek`,
+ * padded with the trailing days of the previous month and leading days of the
+ * next so every row is full. `weeks` defaults to 6 (the max any month needs),
+ * matching Smart's fixed-height calendar.
+ */
+export function monthMatrix(monthDate, firstDayOfWeek = 0, weeks = 6) {
+    const first = startOfMonth(monthDate);
+    const gridStart = startOfWeek(first, firstDayOfWeek);
+    const rows = [];
+    let cursor = gridStart;
+    for (let r = 0; r < weeks; r++) {
+        const row = [];
+        const weekNo = isoWeek(cursor);
+        for (let c = 0; c < 7; c++) {
+            row.push({
+                date: cursor,
+                inMonth: cursor.getMonth() === first.getMonth() && cursor.getFullYear() === first.getFullYear(),
+                week: weekNo,
+            });
+            cursor = addDays(cursor, 1);
+        }
+        rows.push(row);
+    }
+    return rows;
+}
+/**
+ * Ordered weekday indexes (0-6) for a header row starting at `firstDayOfWeek`.
+ * e.g. firstDayOfWeek=1 -> [1,2,3,4,5,6,0].
+ */
+export function weekdayOrder(firstDayOfWeek = 0) {
+    return Array.from({ length: 7 }, (_, i) => (firstDayOfWeek + i) % 7);
+}
+/** Merge a calendar day with a time-of-day taken from `time`, returning a new Date. */
+export function withTime(day, time) {
+    return new Date(day.getFullYear(), day.getMonth(), day.getDate(), time.getHours(), time.getMinutes(), time.getSeconds(), time.getMilliseconds());
+}
+/** Snap a minute value to the nearest lower multiple of `interval` (>=1). */
+export function snapMinute(minute, interval) {
+    const step = Math.max(1, Math.floor(interval));
+    return Math.floor(minute / step) * step;
+}

package/dist/datetime/date-format.d.ts

@@ -0,0 +1,39 @@
+/**
+ * date-format - a small .NET/Smart-style date format-token engine used for
+ * `formatString` display and for parsing the masked DateTimePicker input. It is
+ * locale-aware for names (month/weekday, AM/PM) via `Intl`, and framework-free.
+ *
+ * Supported tokens (case-sensitive, matching Smart's `formatString`):
+ *   d    dd            day of month           (5, 05)
+ *   ddd  dddd          weekday name           (Mon, Monday)  [locale]
+ *   M    MM            month number           (6, 06)
+ *   MMM  MMMM          month name             (Jun, June)    [locale]
+ *   yy   yyyy          year                   (26, 2026)
+ *   H    HH            hour 24                 (7, 07)
+ *   h    hh            hour 12                 (7, 07)
+ *   m    mm            minute
+ *   s    ss            second
+ *   f    ff   fff      fractional seconds      (tenths..millis)
+ *   t    tt            AM/PM designator        (A, AM)        [locale]
+ *
+ * Anything else is a literal. Wrap literal letters in single quotes ('T') or
+ * escape with a backslash (\T) to keep them out of token matching.
+ */
+type Part = {
+    token: string;
+} | {
+    literal: string;
+};
+/** Split a mask into an ordered list of token / literal parts. */
+export declare function tokenizeMask(mask: string): Part[];
+/** Render `date` per `mask` in `locale`. */
+export declare function formatDate(date: Date, mask: string, locale?: string): string;
+/**
+ * Parse `str` against `mask` in `locale`. Returns a Date or null if the string
+ * does not satisfy the mask. `yearCutoff` disambiguates 2-digit years: values
+ * <= (yearCutoff % 100) map to 2000s, above to 1900s (Smart's default 1926 ->
+ * a 26 pivot). `base` supplies fields the mask omits (defaults to epoch-zero
+ * local midnight so a time-only mask yields a today-agnostic time).
+ */
+export declare function parseDate(str: string, mask: string, locale?: string, yearCutoff?: number, base?: Date): Date | null;
+export {};