@svgrid/grid 1.2.33 → 2.0.0

package/dist/otp.js

@@ -0,0 +1,26 @@
+/**
+ * otp - pure helpers behind <SvOtpInput>: sanitize/spread a raw string across N
+ * segments (used on paste and per-cell input) and detect completion.
+ * Framework-free + pure so they are unit-tested directly.
+ */
+/**
+ * Keep only the characters allowed for `numeric` mode (digits) or any
+ * non-whitespace otherwise, then clamp to `length`. Returns the cleaned string
+ * (<= length chars).
+ */
+export function sanitizeOtp(raw, length, numeric) {
+    const kept = numeric ? raw.replace(/\D/g, '') : raw.replace(/\s/g, '');
+    return kept.slice(0, Math.max(0, length));
+}
+/** Split a value into exactly `length` single-char cells (padding with ''). */
+export function otpCells(value, length) {
+    const cells = [];
+    for (let i = 0; i < length; i++)
+        cells[i] = value[i] ?? '';
+    return cells;
+}
+/** Whether `value` fills every cell (a joined OTP has no internal gaps, so an
+ *  exact-length string is complete). */
+export function isOtpComplete(value, length) {
+    return value.length === length;
+}

package/dist/paginate.d.ts

@@ -0,0 +1,20 @@
+/**
+ * paginate - the pure page-range algorithm behind <SvPagination>. Given the
+ * current page and total page count, returns the sequence of page numbers and
+ * ellipsis markers to render (boundary pages + a window of siblings around the
+ * current page, with gaps collapsed to an ellipsis). Framework-free + pure so
+ * it is unit-tested on its own.
+ */
+export type PaginationItem = number | 'ellipsis-left' | 'ellipsis-right';
+export type PaginationRangeOptions = {
+    /** 1-based current page. */
+    page: number;
+    /** Total number of pages. */
+    pageCount: number;
+    /** Pages shown on each side of the current page. Default 1. */
+    siblingCount?: number;
+    /** Pages pinned at each end. Default 1. */
+    boundaryCount?: number;
+};
+/** Build the page/ellipsis sequence (e.g. `[1, 'ellipsis-left', 4, 5, 6, 'ellipsis-right', 20]`). */
+export declare function paginationRange(options: PaginationRangeOptions): PaginationItem[];

package/dist/paginate.js

@@ -0,0 +1,40 @@
+const clamp = (n, lo, hi) => Math.min(Math.max(n, lo), hi);
+/** Build the page/ellipsis sequence (e.g. `[1, 'ellipsis-left', 4, 5, 6, 'ellipsis-right', 20]`). */
+export function paginationRange(options) {
+    const { pageCount } = options;
+    if (pageCount <= 0)
+        return [];
+    const siblingCount = Math.max(0, options.siblingCount ?? 1);
+    const boundaryCount = Math.max(1, options.boundaryCount ?? 1);
+    const page = clamp(options.page, 1, pageCount);
+    // If ellipsis could hide at most one page, just show every page.
+    if (pageCount <= boundaryCount * 2 + siblingCount * 2 + 3) {
+        return Array.from({ length: pageCount }, (_, i) => i + 1);
+    }
+    const pages = new Set();
+    // End boundaries (both ends).
+    for (let i = 1; i <= boundaryCount && i <= pageCount; i++) {
+        pages.add(i);
+        pages.add(pageCount - i + 1);
+    }
+    // Siblings around the current page.
+    for (let i = page - siblingCount; i <= page + siblingCount; i++) {
+        if (i >= 1 && i <= pageCount)
+            pages.add(i);
+    }
+    const sorted = [...pages].sort((a, b) => a - b);
+    const result = [];
+    let prev = 0;
+    for (const p of sorted) {
+        if (p - prev === 2) {
+            // Exactly one page in the gap: show it instead of an ellipsis.
+            result.push(prev + 1);
+        }
+        else if (p - prev > 2) {
+            result.push(p <= page ? 'ellipsis-left' : 'ellipsis-right');
+        }
+        result.push(p);
+        prev = p;
+    }
+    return result;
+}

package/dist/popover.d.ts

@@ -14,7 +14,7 @@
  * resolved values and pin them inline. Keep this list in sync with the tokens
  * any popover panel actually consumes.
  */
-export declare const PANEL_THEME_VARS: readonly ["--sg-accent", "--sg-bg", "--sg-fg", "--sg-border", "--sg-muted", "--sg-header-bg", "--sg-row-hover-bg", "--sg-selection-bg", "--sg-input-bg", "--sg-input-border", "--sg-selection-fg"];
+export declare const PANEL_THEME_VARS: readonly ["--sg-accent", "--sg-on-accent", "--sg-bg", "--sg-fg", "--sg-muted", "--sg-border", "--sg-header-bg", "--sg-header-fg", "--sg-row-hover-bg", "--sg-row-alt-bg", "--sg-selection-bg", "--sg-selection-fg", "--sg-input-bg", "--sg-input-border", "--sg-danger", "--sg-focus-ring", "--sg-radius", "--sg-font", "--sg-invalid-bg", "--sg-invalid-border", "--sg-invalid-fg", "--sg-rating-on", "--sg-rating-empty", "--sg-rating-hover"];
 /**
  * Svelte action: snapshot the resolved theme tokens from the node's current
  * (in-scope) position, then detach it and append to <body> so it can never be
@@ -23,6 +23,20 @@ export declare const PANEL_THEME_VARS: readonly ["--sg-accent", "--sg-bg", "--sg
 export declare function portalToBody(node: HTMLElement, vars?: ReadonlyArray<string>): {
     destroy(): void;
 };
+/**
+ * Svelte action: play a short enter animation when a portalled panel mounts
+ * (dropdowns, popovers, dialogs). Slides from the trigger side + fades/scales in.
+ * A no-op under `prefers-reduced-motion` and in environments without the Web
+ * Animations API (jsdom), so tests and reduced-motion users are unaffected.
+ *
+ * `use:popIn={{ up: rect.openUpward }}` - pass `up` for panels that flipped above
+ * their trigger so the slide direction matches.
+ */
+export declare function popIn(node: HTMLElement, param?: {
+    up?: boolean;
+    duration?: number;
+    scale?: number;
+}): {} | undefined;
 export type AnchoredRect = {
     top: number;
     left: number;

package/dist/popover.js

@@ -15,9 +15,12 @@
  * any popover panel actually consumes.
  */
 export const PANEL_THEME_VARS = [
-    '--sg-accent', '--sg-bg', '--sg-fg', '--sg-border', '--sg-muted',
-    '--sg-header-bg', '--sg-row-hover-bg', '--sg-selection-bg',
-    '--sg-input-bg', '--sg-input-border', '--sg-selection-fg',
+    '--sg-accent', '--sg-on-accent', '--sg-bg', '--sg-fg', '--sg-muted', '--sg-border',
+    '--sg-header-bg', '--sg-header-fg', '--sg-row-hover-bg', '--sg-row-alt-bg',
+    '--sg-selection-bg', '--sg-selection-fg', '--sg-input-bg', '--sg-input-border',
+    '--sg-danger', '--sg-focus-ring', '--sg-radius', '--sg-font',
+    '--sg-invalid-bg', '--sg-invalid-border', '--sg-invalid-fg',
+    '--sg-rating-on', '--sg-rating-empty', '--sg-rating-hover',
 ];
 /**
  * Svelte action: snapshot the resolved theme tokens from the node's current
@@ -39,6 +42,29 @@ export function portalToBody(node, vars = PANEL_THEME_VARS) {
         },
     };
 }
+/**
+ * Svelte action: play a short enter animation when a portalled panel mounts
+ * (dropdowns, popovers, dialogs). Slides from the trigger side + fades/scales in.
+ * A no-op under `prefers-reduced-motion` and in environments without the Web
+ * Animations API (jsdom), so tests and reduced-motion users are unaffected.
+ *
+ * `use:popIn={{ up: rect.openUpward }}` - pass `up` for panels that flipped above
+ * their trigger so the slide direction matches.
+ */
+export function popIn(node, param = {}) {
+    if (typeof node.animate !== 'function')
+        return;
+    const reduce = typeof matchMedia === 'function' && matchMedia('(prefers-reduced-motion: reduce)').matches;
+    if (reduce)
+        return;
+    const dy = param.up ? 6 : -6;
+    const s = param.scale ?? 0.97;
+    node.animate([
+        { opacity: 0, transform: `translateY(${dy}px) scale(${s})` },
+        { opacity: 1, transform: 'translateY(0) scale(1)' },
+    ], { duration: param.duration ?? 140, easing: 'cubic-bezier(0.16, 1, 0.3, 1)' });
+    return {};
+}
 /**
  * Compute a `position: fixed` rect anchored to `triggerRect`, flipping above the
  * trigger when there isn't room below and there's more room above. Mirrors the

package/dist/recurrence.d.ts

@@ -0,0 +1,36 @@
+/**
+ * recurrence - a small, pure repeat-pattern engine for SvCalendar (and anywhere
+ * you need "does this date match a recurring rule"). Supports daily / weekly /
+ * monthly / yearly frequencies with an interval, weekday lists, a day-of-month,
+ * an anchor (`from`) and an inclusive `until`. Framework-free + pure so it is
+ * unit-tested directly - no RRULE dependency.
+ *
+ * ```ts
+ * const standup = { freq: 'weekly', weekdays: [1, 2, 3, 4, 5] } // every weekday
+ * const payday  = { freq: 'monthly', day: 1 }                   // the 1st
+ * const sprint  = { freq: 'weekly', weekdays: [1], interval: 2, from: '2026-01-05' } // every other Monday
+ * matchesRecurrence(someDate, [standup, payday, sprint])
+ * ```
+ */
+import { type DateLike } from './datetime/date-core';
+export type RecurrenceFreq = 'daily' | 'weekly' | 'monthly' | 'yearly';
+export type RecurrenceRule = {
+    freq: RecurrenceFreq;
+    /** Repeat every N units of `freq`. Default 1. Uses `from` as the phase anchor. */
+    interval?: number;
+    /** weekly: the weekdays it lands on (0 = Sunday .. 6 = Saturday). */
+    weekdays?: ReadonlyArray<number>;
+    /** monthly / yearly: day of the month (1..31). */
+    day?: number;
+    /** yearly: the month (0 = January .. 11 = December). */
+    month?: number;
+    /** First occurrence + the phase for `interval`. */
+    from?: DateLike;
+    /** Last day the pattern applies (inclusive). */
+    until?: DateLike | null;
+};
+/** Whether `date` matches any of the given recurrence rule(s). */
+export declare function matchesRecurrence(date: Date, rules: RecurrenceRule | ReadonlyArray<RecurrenceRule> | null | undefined): boolean;
+/** Every matching date within [start, end] (inclusive), in order - for building
+ *  event lists / agendas. Bounded to avoid runaway loops. */
+export declare function expandRecurrence(rules: RecurrenceRule | ReadonlyArray<RecurrenceRule> | null | undefined, start: Date, end: Date): Date[];

package/dist/recurrence.js

@@ -0,0 +1,90 @@
+/**
+ * recurrence - a small, pure repeat-pattern engine for SvCalendar (and anywhere
+ * you need "does this date match a recurring rule"). Supports daily / weekly /
+ * monthly / yearly frequencies with an interval, weekday lists, a day-of-month,
+ * an anchor (`from`) and an inclusive `until`. Framework-free + pure so it is
+ * unit-tested directly - no RRULE dependency.
+ *
+ * ```ts
+ * const standup = { freq: 'weekly', weekdays: [1, 2, 3, 4, 5] } // every weekday
+ * const payday  = { freq: 'monthly', day: 1 }                   // the 1st
+ * const sprint  = { freq: 'weekly', weekdays: [1], interval: 2, from: '2026-01-05' } // every other Monday
+ * matchesRecurrence(someDate, [standup, payday, sprint])
+ * ```
+ */
+import { startOfDay, startOfWeek, toDate } from './datetime/date-core';
+const MS_DAY = 86400000;
+/** Whole-day index, rounded so DST transitions don't shift it. */
+const dayIndex = (d) => Math.round(startOfDay(d).getTime() / MS_DAY);
+function matchesRule(date, r) {
+    const d = startOfDay(date);
+    const fromD = r.from != null ? startOfDay(toDate(r.from) ?? d) : null;
+    const untilD = r.until != null ? startOfDay(toDate(r.until) ?? d) : null;
+    if (fromD && d < fromD)
+        return false;
+    if (untilD && d > untilD)
+        return false;
+    const interval = Math.max(1, Math.floor(r.interval ?? 1));
+    switch (r.freq) {
+        case 'daily':
+            if (!fromD)
+                return true;
+            return (dayIndex(d) - dayIndex(fromD)) % interval === 0;
+        case 'weekly': {
+            // The weekdays it repeats on: an explicit list, else the anchor's weekday.
+            const weekdays = r.weekdays && r.weekdays.length ? r.weekdays : fromD ? [fromD.getDay()] : null;
+            if (!weekdays)
+                return false;
+            if (!weekdays.includes(d.getDay()))
+                return false;
+            if (interval > 1 && fromD) {
+                const weeks = Math.round((startOfWeek(d, 0).getTime() - startOfWeek(fromD, 0).getTime()) / (MS_DAY * 7));
+                if (weeks % interval !== 0)
+                    return false;
+            }
+            return true;
+        }
+        case 'monthly': {
+            const dom = r.day ?? fromD?.getDate();
+            if (dom != null && d.getDate() !== dom)
+                return false;
+            if (!fromD)
+                return dom != null;
+            const months = (d.getFullYear() - fromD.getFullYear()) * 12 + (d.getMonth() - fromD.getMonth());
+            return months % interval === 0;
+        }
+        case 'yearly': {
+            if (r.month != null && d.getMonth() !== r.month)
+                return false;
+            const dom = r.day ?? fromD?.getDate();
+            if (dom != null && d.getDate() !== dom)
+                return false;
+            if (!fromD)
+                return r.month != null || dom != null;
+            return (d.getFullYear() - fromD.getFullYear()) % interval === 0;
+        }
+    }
+}
+/** Whether `date` matches any of the given recurrence rule(s). */
+export function matchesRecurrence(date, rules) {
+    if (!rules)
+        return false;
+    const list = Array.isArray(rules) ? rules : [rules];
+    return list.some((r) => matchesRule(date, r));
+}
+/** Every matching date within [start, end] (inclusive), in order - for building
+ *  event lists / agendas. Bounded to avoid runaway loops. */
+export function expandRecurrence(rules, start, end) {
+    if (!rules)
+        return [];
+    const out = [];
+    const last = startOfDay(end);
+    let cur = startOfDay(start);
+    let guard = 0;
+    while (cur <= last && guard++ < 4000) {
+        if (matchesRecurrence(cur, rules))
+            out.push(cur);
+        cur = new Date(cur.getFullYear(), cur.getMonth(), cur.getDate() + 1);
+    }
+    return out;
+}

package/dist/server-data-source.d.ts

@@ -34,6 +34,11 @@ export type ServerFilterModel = {
         selectedValues?: string[];
     }>;
 };
+/** A value column to roll up per group. */
+export type ServerAggregation = {
+    col: string;
+    fn: 'sum' | 'avg' | 'min' | 'max' | 'count';
+};
 export type ServerRequest = {
     /** Zero-based index of the first row wanted (inclusive). */
     startRow: number;
@@ -43,7 +48,91 @@ export type ServerRequest = {
     pageSize: number;
     sortModel: ServerSortModel;
     filterModel: ServerFilterModel;
+    /**
+     * Server-side grouping / tree: the columns being grouped on, outer to inner.
+     * Omitted / empty for a flat request.
+     */
+    groupBy?: string[];
+    /**
+     * The path of group keys the grid is expanding, e.g. `['Germany', 'Berlin']`.
+     * Empty (`[]`) asks for the top level. When `groupKeys.length < groupBy.length`
+     * the server returns **group rows** (one per distinct key at this level,
+     * carrying the group key + aggregates); when they are equal it returns the
+     * **leaf rows** under that path.
+     */
+    groupKeys?: string[];
+    /** Value columns to aggregate per group. */
+    aggregations?: ServerAggregation[];
+};
+/**
+ * A group row in the server-side group/tree model - one distinct key at a
+ * level, with its rolled-up aggregates. The grid renders it with an expander;
+ * expanding it fetches its children through the same `getRows`.
+ */
+export type ServerGroupRow<TData> = {
+    kind: 'group';
+    /** Stable id (the group path). */
+    id: string;
+    /** Group keys from the root to this node, e.g. `['Germany', 'Berlin']`. */
+    path: string[];
+    /** The column this group is on (the `groupBy` entry for this level). */
+    field: string;
+    /** This group's key value. */
+    key: string;
+    /** Zero-based depth (0 = top level). */
+    level: number;
+    expanded: boolean;
+    loading: boolean;
+    /** Aggregate values keyed by column id, read from the group's response row. */
+    aggregates: Record<string, unknown>;
+    /** The raw response row for this group (key + aggregates), for cell rendering. */
+    data: TData;
+};
+export type ServerLeafRow<TData> = {
+    kind: 'leaf';
+    id: string;
+    level: number;
+    data: TData;
+};
+/**
+ * A "load more" affordance emitted at the end of a group whose children are
+ * only partially loaded (intra-group paging). Trigger `loadMoreChildren(path)`
+ * to fetch the next block.
+ */
+export type ServerMoreRow = {
+    kind: 'more';
+    id: string;
+    level: number;
+    /** Path of the parent group whose children to load more of. */
+    path: string[];
+    /** How many children remain unloaded. */
+    remaining: number;
+    loading: boolean;
+};
+/**
+ * A subtotal / footer row emitted after an expanded group's children when
+ * `groupFooters` is on. Carries the group's aggregates a second time so a
+ * "Total" line sits under the detail.
+ */
+export type ServerFooterRow<TData> = {
+    kind: 'footer';
+    id: string;
+    level: number;
+    path: string[];
+    /** The group this footer totals (its key). */
+    key: string;
+    aggregates: Record<string, unknown>;
+    /** The group's response row (key + aggregates), so value columns show totals. */
+    data: TData;
+};
+/** A placeholder row shown while a block of children is being fetched. */
+export type ServerSkeletonRow = {
+    kind: 'skeleton';
+    id: string;
+    level: number;
 };
+/** A row in the flattened server-side group/tree display list. */
+export type ServerDisplayRow<TData> = ServerGroupRow<TData> | ServerLeafRow<TData> | ServerMoreRow | ServerFooterRow<TData> | ServerSkeletonRow;
 export type ServerResult<TData> = {
     rows: ReadonlyArray<TData>;
     /** Total row count after filtering (for the pager). */

package/dist/server-data-source.js

@@ -35,6 +35,10 @@ export function createServerDataSource(source, options) {
                 pageSize: state.pageSize,
                 sortModel: state.sortModel,
                 filterModel: state.filterModel,
+                // Flat mode: no grouping. Group mode lives in createServerGroupModel.
+                groupBy: [],
+                groupKeys: [],
+                aggregations: [],
             });
             if (disposed || id !== requestSeq)
                 return; // stale

package/dist/server-group-model.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Server-side GROUP row model (SSRM grouping) - the first-class
+ * companion to `createServerDataSource`. Grouping, aggregation, and lazy
+ * expansion all flow through the SAME `ServerDataSource.getRows` contract:
+ *
+ *   - The request carries `groupBy` (the columns grouped on) and `groupKeys`
+ *     (the path of the group being expanded). While `groupKeys.length <
+ *     groupBy.length` the server returns GROUP rows (one per distinct key at
+ *     that level, carrying the key + aggregate values); at the bottom level it
+ *     returns the leaf rows under that path.
+ *   - Expanding a group is just another `getRows` with `groupKeys` set to that
+ *     group's path. This controller owns the group tree: expand / collapse,
+ *     per-node lazy fetch + cache, race-safety, and flattening to a display
+ *     list the grid renders (group rows with an expander, leaves underneath).
+ *
+ * Headless and framework-agnostic on purpose: render from `state.displayRows`
+ * and call `toggleGroup` from the group cell's expander.
+ */
+import type { ServerAggregation, ServerDataSource, ServerDisplayRow, ServerFilterModel, ServerGroupRow, ServerSortModel } from './server-data-source';
+export type ServerGroupState<TData> = {
+    /** The flattened tree: top-level groups, with expanded groups' children spliced in. */
+    displayRows: ServerDisplayRow<TData>[];
+    groupBy: string[];
+    /** True during the initial top-level fetch (before the root has ever loaded). */
+    loading: boolean;
+    /** The rejection from the last failed top-level fetch, else null. */
+    error: unknown;
+    sortModel: ServerSortModel;
+    filterModel: ServerFilterModel;
+    /** Ids (JSON of the path) of the currently expanded groups. */
+    expandedGroups: string[];
+};
+export type ServerGroupControllerOptions<TData> = {
+    /** Columns to group on, outer to inner. Empty in `treeData` mode. */
+    groupBy?: string[];
+    /** Value columns to roll up per group. */
+    aggregations?: ServerAggregation[];
+    /** Max children fetched per group in one request. Default 200. */
+    pageSize?: number;
+    /**
+     * Self-referential tree mode: instead of grouping flat rows by columns, each
+     * row is a node whose children are fetched on expand. Requires `getRowId`
+     * (the node id, which builds the `groupKeys` path) and `hasChildren` (whether
+     * a node is expandable). `getRows` receives `groupKeys` = the path to the
+     * node being expanded, and returns that node's direct children.
+     */
+    treeData?: boolean;
+    /** Node id, used to build the `groupKeys` path. Required in `treeData` mode. */
+    getRowId?: (row: TData) => string;
+    /** Whether a node can be expanded. Required in `treeData` mode. */
+    hasChildren?: (row: TData) => boolean;
+    /** Emit a subtotal "footer" row after each expanded group's children. */
+    groupFooters?: boolean;
+    /** Placeholder rows shown while a group's first block is loading. Default 3. */
+    skeletonRows?: number;
+    onChange: (state: ServerGroupState<TData>) => void;
+};
+export type ServerGroupController<TData> = {
+    /** (Re-)fetch the tree from the top. Call once to load the first level. */
+    refresh(): void;
+    setSort(sortModel: ServerSortModel): void;
+    setFilter(filterModel: ServerFilterModel): void;
+    /** Change the grouping columns. Collapses everything and reloads the top level. */
+    setGroupBy(groupBy: string[]): void;
+    /** Expand or collapse a group row (from its expander). */
+    toggleGroup(row: ServerGroupRow<TData>): void;
+    expandGroup(path: string[]): void;
+    collapseGroup(path: string[]): void;
+    /** Fetch the next block of a group's children (intra-group paging). */
+    loadMoreChildren(path: string[]): void;
+    isExpanded(path: string[]): boolean;
+    getState(): ServerGroupState<TData>;
+    /** Stop accepting in-flight responses. Call on unmount. */
+    dispose(): void;
+};
+/**
+ * Map a `ServerGroupState.displayRows` to grid rows: each row's data spread at
+ * the top level (so normal `field` columns show group subtotals on group rows
+ * and cell values on leaves) plus a `__group` marker the built-in `SvGroupCell`
+ * reads to draw the expander + indentation. Feed the result to `<SvGrid data>`.
+ */
+export type ServerGroupGridRow<TData> = TData & {
+    __group: ServerDisplayRow<TData>;
+};
+export declare function serverGroupRows<TData>(state: ServerGroupState<TData> | undefined | null): ServerGroupGridRow<TData>[];
+/**
+ * Build the `serverGroup` prop for `<SvGrid>` from a controller, so the grid's
+ * built-in tree keyboard (ArrowRight / ArrowLeft expand / collapse) and treegrid
+ * a11y work with no app-level key handling. Reads the `__group` marker that
+ * `serverGroupRows` attaches. Usage: `<SvGrid ... serverGroup={serverGroupNav(ctl)} />`.
+ */
+export declare function serverGroupNav<TData>(ctl: ServerGroupController<TData>): {
+    isGroup: (row: ServerGroupGridRow<TData>) => boolean;
+    level: (row: ServerGroupGridRow<TData>) => number;
+    expanded: (row: ServerGroupGridRow<TData>) => boolean;
+    onToggle: (row: ServerGroupGridRow<TData>) => void;
+};
+export declare function createServerGroupModel<TData>(source: ServerDataSource<TData>, options: ServerGroupControllerOptions<TData>): ServerGroupController<TData>;