@svgrid/enterprise 3.0.0 → 3.0.2

package/dist/sheet/find-replace.js

@@ -0,0 +1,152 @@
+let target = null;
+export function setFindTarget(next) {
+    target = next;
+}
+export function getFindTarget() {
+    return target;
+}
+function textOf(t, r, c, lookIn) {
+    if (lookIn === 'formulas')
+        return t.getRaw(r, c);
+    return t.getDisplay ? t.getDisplay(r, c) : t.getRaw(r, c);
+}
+/** Does `haystack` match `needle` under these options? */
+export function cellMatches(haystack, needle, opts = {}) {
+    if (needle === '')
+        return false;
+    const a = opts.matchCase ? haystack : haystack.toLowerCase();
+    const b = opts.matchCase ? needle : needle.toLowerCase();
+    return opts.matchEntireCell ? a === b : a.includes(b);
+}
+/** Every cell matching, in reading order. */
+export function findAll(cmd, needle, opts = {}) {
+    const t = target;
+    if (!t || needle === '')
+        return [];
+    const lookIn = opts.lookIn ?? 'values';
+    const bounds = opts.scope === 'selection' ? cmd.ranges : null;
+    const hits = [];
+    const inScope = (r, c) => {
+        if (!bounds)
+            return true;
+        return bounds.some(([minRow, minCol, maxRow, maxCol]) => r >= minRow && r <= maxRow && c >= minCol && c <= maxCol);
+    };
+    for (let r = 0; r < cmd.rowCount; r += 1) {
+        for (let c = 0; c < cmd.colCount; c += 1) {
+            if (!inScope(r, c))
+                continue;
+            if (cellMatches(textOf(t, r, c, lookIn), needle, opts))
+                hits.push({ rowIndex: r, colIndex: c });
+        }
+    }
+    return hits;
+}
+/** The next hit after the active cell, wrapping. Null when there are none. */
+export function findNext(cmd, needle, opts = {}, direction = 1) {
+    const hits = findAll(cmd, needle, opts);
+    if (hits.length === 0)
+        return null;
+    const active = cmd.activeCell;
+    if (!active)
+        return hits[0];
+    const key = (h) => h.rowIndex * cmd.colCount + h.colIndex;
+    const here = active.rowIndex * cmd.colCount + active.colIndex;
+    if (direction === 1) {
+        return hits.find((h) => key(h) > here) ?? hits[0];
+    }
+    // Reverse: the last hit strictly before the active cell, else wrap to the end.
+    for (let i = hits.length - 1; i >= 0; i -= 1) {
+        if (key(hits[i]) < here)
+            return hits[i];
+    }
+    return hits[hits.length - 1];
+}
+/** Replace inside one string, honouring case sensitivity and whole-cell. */
+export function replaceInText(haystack, needle, replacement, opts = {}) {
+    if (needle === '')
+        return haystack;
+    if (opts.matchEntireCell) {
+        return cellMatches(haystack, needle, opts) ? replacement : haystack;
+    }
+    if (opts.matchCase)
+        return haystack.split(needle).join(replacement);
+    // Case-insensitive substring replace, without a regex: the needle is user
+    // input and escaping it correctly is more code than scanning for it.
+    const lowerHay = haystack.toLowerCase();
+    const lowerNeedle = needle.toLowerCase();
+    let out = '';
+    let i = 0;
+    for (;;) {
+        const at = lowerHay.indexOf(lowerNeedle, i);
+        if (at < 0) {
+            out += haystack.slice(i);
+            break;
+        }
+        out += haystack.slice(i, at) + replacement;
+        i = at + needle.length;
+    }
+    return out;
+}
+/**
+ * Replace the active cell if it matches, then move to the next hit. Returns
+ * whether anything was written.
+ */
+export function replaceOne(cmd, needle, replacement, opts = {}) {
+    const t = target;
+    const active = cmd.activeCell;
+    if (!t || !active || needle === '')
+        return false;
+    const { rowIndex: r, colIndex: c } = active;
+    const lookIn = opts.lookIn ?? 'values';
+    const editable = t.isEditable?.(r, c) ?? true;
+    let wrote = false;
+    if (editable && cellMatches(textOf(t, r, c, lookIn), needle, opts)) {
+        // Always write through the RAW text: replacing inside a displayed value
+        // would overwrite a formula with its own result.
+        const raw = t.getRaw(r, c);
+        const next = replaceInText(raw, needle, replacement, opts);
+        if (next !== raw) {
+            t.setRaw(r, c, next);
+            t.onChange?.();
+            wrote = true;
+        }
+    }
+    const following = findNext(cmd, needle, opts);
+    if (following) {
+        cmd.setActiveCell(following.rowIndex, following.colIndex);
+        cmd.setSelection(following.rowIndex, following.colIndex);
+        cmd.scrollIntoView(following.rowIndex, following.colIndex);
+    }
+    return wrote;
+}
+/**
+ * Replace every match. Returns how many cells changed.
+ *
+ * Runs inside `cmd.batch`, so a hundred replacements are ONE Ctrl+Z. Without
+ * that this would be the single worst thing in the feature set for undo: it is
+ * the one command that routinely writes more cells than the history can hold.
+ */
+export function replaceAll(cmd, needle, replacement, opts = {}) {
+    const t = target;
+    if (!t || needle === '')
+        return 0;
+    const hits = findAll(cmd, needle, opts);
+    if (hits.length === 0)
+        return 0;
+    return cmd.batch(() => {
+        let changed = 0;
+        for (const { rowIndex: r, colIndex: c } of hits) {
+            if (!(t.isEditable?.(r, c) ?? true))
+                continue;
+            const raw = t.getRaw(r, c);
+            const next = replaceInText(raw, needle, replacement, opts);
+            if (next === raw)
+                continue;
+            t.setRaw(r, c, next);
+            changed += 1;
+        }
+        if (changed > 0)
+            t.onChange?.();
+        return changed;
+    });
+}

package/dist/sheet/format-store.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Per-cell formats and styles, keyed so they survive the grid moving rows
+ * around.
+ *
+ * Demo 27 keys its format map by DISPLAY row index. Sort the grid and every
+ * bold cell moves to whatever row now sits at that index, which is the kind of
+ * bug that looks like a rendering glitch and is actually lost data. This keys
+ * by `rowId:columnId`, the same shape the grid already uses for `notes`, so
+ * sorting, filtering, column reordering and pagination all leave it alone.
+ *
+ * Storage is sparse: a sheet of ten thousand cells with three bold ones holds
+ * three entries. Most cells have no entry at all and cost nothing.
+ */
+import type { BorderSpec } from '@svgrid/grid';
+/** One cell's formatting. Every field optional; absent means inherit. */
+/** The boolean fields `toggle` can flip. Every one of them is a plain
+ *  on/off attribute of a cell, which is what makes Excel's all-on-turns-off
+ *  rule the right one for all of them. */
+export type ToggleableField = 'bold' | 'italic' | 'underline' | 'strike' | 'wrap';
+export type CellFormatEntry = {
+    /** Excel number-format string, e.g. '#,##0.00'. */
+    numFmt?: string;
+    bold?: boolean;
+    italic?: boolean;
+    underline?: boolean;
+    strike?: boolean;
+    /** Text colour, any CSS colour. */
+    color?: string;
+    /** Background fill. */
+    fill?: string;
+    align?: 'left' | 'center' | 'right';
+    fontFamily?: string;
+    fontSize?: number;
+    wrap?: boolean;
+    indent?: number;
+    border?: {
+        top?: BorderSpec;
+        right?: BorderSpec;
+        bottom?: BorderSpec;
+        left?: BorderSpec;
+    };
+    /**
+     * Excel's Locked flag from Format Cells > Protection. Every cell is locked
+     * unless told otherwise, so only `false` is ever stored; the flag means
+     * nothing until the sheet is protected, when a locked cell refuses edits.
+     */
+    locked?: boolean;
+};
+export type Rect = readonly [minRow: number, minCol: number, maxRow: number, maxCol: number];
+/** Translates a display position to the stable ids the store keys on. */
+export type CellAddressLookup = {
+    rowIdAt(rowIndex: number): string | null;
+    columnIdAt(colIndex: number): string | null;
+};
+export type SheetFormatStore = {
+    get(rowId: string, columnId: string): CellFormatEntry | undefined;
+    /** Merge `patch` into every cell of every rect. A field set to `undefined`
+     *  is REMOVED, which is how you clear one attribute without clearing the
+     *  cell; `clear` removes the whole entry. An entry left with no fields is
+     *  dropped rather than kept as an empty object. */
+    set(rects: ReadonlyArray<Rect>, patch: CellFormatEntry, at: CellAddressLookup): void;
+    /** Remove all formatting from every cell of every rect. */
+    clear(rects: ReadonlyArray<Rect>, at: CellAddressLookup): void;
+    /** Toggle one boolean field across a range. Excel's rule: if EVERY cell in
+     *  the range already has it, turn it off; otherwise turn it on. */
+    toggle(rects: ReadonlyArray<Rect>, field: ToggleableField, at: CellAddressLookup): void;
+    /** Drop every entry for a row. Call when a row is deleted, or the store
+     *  leaks an entry per removed row for the life of the session. */
+    forgetRow(rowId: string): void;
+    forgetColumn(columnId: string): void;
+    /** How many cells carry formatting. For tests and diagnostics. */
+    readonly size: number;
+    serialize(): Record<string, CellFormatEntry>;
+    hydrate(entries: Record<string, CellFormatEntry>): void;
+    clearAll(): void;
+    /**
+     * Rename every row id at once; `fn` returns the new id, or null to drop
+     * the row's entries. For a store keyed on record ids this is never
+     * needed - an id travels with its record - but a SHEET keys rows by
+     * position (`r4` is the fifth row and nothing else), so inserting a row
+     * above the fifth has to move its formats to `r5`, or the band stays on
+     * row five while the cells it belonged to move down.
+     */
+    remapRows(fn: (rowId: string) => string | null): void;
+    /** The same for column ids. */
+    remapColumns(fn: (columnId: string) => string | null): void;
+};
+export declare function createFormatStore(initial?: Record<string, CellFormatEntry>): SheetFormatStore;
+/** Turn an entry into inline style text for a cell renderer. */
+export declare function entryToStyle(entry: CellFormatEntry | undefined): string;
+/**
+ * Cell borders as inset shadows, one per side.
+ *
+ * The cell span fills its td edge to edge, so an inset shadow along one
+ * edge is a border that costs no layout: a real border would push the text
+ * and change the cell's size, and a bordered cell next to a plain one would
+ * misalign. Shadows stack, so a cell can carry any combination of sides.
+ */
+export declare function borderShadows(border: CellFormatEntry['border']): string;

package/dist/sheet/format-store.js

@@ -0,0 +1,233 @@
+/**
+ * Keys are "rowId columnId" with each half percent-encoded.
+ *
+ * Encoding is what makes the key reversible. Ids come from the grid and may
+ * contain spaces, so a plain join cannot be split back apart - and `hydrate`
+ * has to split it, or the row and column indexes come back empty and
+ * `forgetRow` / `forgetColumn` become silent no-ops on a restored store.
+ */
+function keyOf(rowId, columnId) {
+    return `${encodeURIComponent(rowId)} ${encodeURIComponent(columnId)}`;
+}
+function splitKey(key) {
+    const gap = key.indexOf(' ');
+    if (gap < 0)
+        return null;
+    try {
+        return {
+            rowId: decodeURIComponent(key.slice(0, gap)),
+            columnId: decodeURIComponent(key.slice(gap + 1)),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+export function createFormatStore(initial) {
+    const cells = new Map();
+    const rowsIndex = new Map();
+    const colsIndex = new Map();
+    function remember(rowId, columnId, key) {
+        let byRow = rowsIndex.get(rowId);
+        if (!byRow) {
+            byRow = new Set();
+            rowsIndex.set(rowId, byRow);
+        }
+        byRow.add(key);
+        let byCol = colsIndex.get(columnId);
+        if (!byCol) {
+            byCol = new Set();
+            colsIndex.set(columnId, byCol);
+        }
+        byCol.add(key);
+    }
+    function eachCell(rects, at, fn) {
+        const seen = new Set();
+        for (const [minRow, minCol, maxRow, maxCol] of rects) {
+            for (let r = minRow; r <= maxRow; r += 1) {
+                const rowId = at.rowIdAt(r);
+                if (rowId === null)
+                    continue;
+                for (let c = minCol; c <= maxCol; c += 1) {
+                    const columnId = at.columnIdAt(c);
+                    if (columnId === null)
+                        continue;
+                    // Overlapping ranges must not apply a toggle twice.
+                    const key = keyOf(rowId, columnId);
+                    if (seen.has(key))
+                        continue;
+                    seen.add(key);
+                    fn(rowId, columnId);
+                }
+            }
+        }
+    }
+    const store = {
+        get(rowId, columnId) {
+            return cells.get(keyOf(rowId, columnId));
+        },
+        set(rects, patch, at) {
+            eachCell(rects, at, (rowId, columnId) => {
+                const key = keyOf(rowId, columnId);
+                const next = { ...(cells.get(key) ?? {}), ...patch };
+                // Strip keys explicitly set to undefined so an entry does not grow
+                // a field that means nothing.
+                for (const [k, v] of Object.entries(next)) {
+                    if (v === undefined)
+                        delete next[k];
+                }
+                if (Object.keys(next).length === 0) {
+                    cells.delete(key);
+                    return;
+                }
+                cells.set(key, next);
+                remember(rowId, columnId, key);
+            });
+        },
+        clear(rects, at) {
+            eachCell(rects, at, (rowId, columnId) => {
+                cells.delete(keyOf(rowId, columnId));
+            });
+        },
+        toggle(rects, field, at) {
+            // Excel's rule, and the one users expect: a mixed selection turns ON.
+            let all = true;
+            eachCell(rects, at, (rowId, columnId) => {
+                if (!cells.get(keyOf(rowId, columnId))?.[field])
+                    all = false;
+            });
+            // `set` treats undefined as "remove this field", so one pass does both
+            // directions.
+            store.set(rects, { [field]: all ? undefined : true }, at);
+        },
+        forgetRow(rowId) {
+            for (const key of rowsIndex.get(rowId) ?? [])
+                cells.delete(key);
+            rowsIndex.delete(rowId);
+        },
+        forgetColumn(columnId) {
+            for (const key of colsIndex.get(columnId) ?? [])
+                cells.delete(key);
+            colsIndex.delete(columnId);
+        },
+        get size() {
+            return cells.size;
+        },
+        serialize() {
+            return Object.fromEntries(cells);
+        },
+        hydrate(entries) {
+            cells.clear();
+            rowsIndex.clear();
+            colsIndex.clear();
+            for (const [key, entry] of Object.entries(entries)) {
+                cells.set(key, entry);
+                // Rebuild the indexes, or forgetRow / forgetColumn do nothing on a
+                // store that came back from storage.
+                const parts = splitKey(key);
+                if (parts)
+                    remember(parts.rowId, parts.columnId, key);
+            }
+        },
+        clearAll() {
+            cells.clear();
+            rowsIndex.clear();
+            colsIndex.clear();
+        },
+        remapRows(fn) {
+            const next = {};
+            for (const [key, entry] of cells) {
+                const parts = splitKey(key);
+                if (!parts)
+                    continue;
+                const rowId = fn(parts.rowId);
+                if (rowId !== null)
+                    next[keyOf(rowId, parts.columnId)] = entry;
+            }
+            store.hydrate(next);
+        },
+        remapColumns(fn) {
+            const next = {};
+            for (const [key, entry] of cells) {
+                const parts = splitKey(key);
+                if (!parts)
+                    continue;
+                const columnId = fn(parts.columnId);
+                if (columnId !== null)
+                    next[keyOf(parts.rowId, columnId)] = entry;
+            }
+            store.hydrate(next);
+        },
+    };
+    if (initial)
+        store.hydrate(initial);
+    return store;
+}
+/** Turn an entry into inline style text for a cell renderer. */
+export function entryToStyle(entry) {
+    if (!entry)
+        return '';
+    const parts = [];
+    if (entry.bold)
+        parts.push('font-weight:700');
+    if (entry.italic)
+        parts.push('font-style:italic');
+    if (entry.underline && entry.strike)
+        parts.push('text-decoration:underline line-through');
+    else if (entry.underline)
+        parts.push('text-decoration:underline');
+    else if (entry.strike)
+        parts.push('text-decoration:line-through');
+    if (entry.color)
+        parts.push(`color:${entry.color}`);
+    if (entry.fill)
+        parts.push(`background:${entry.fill}`);
+    if (entry.align)
+        parts.push(`text-align:${entry.align}`);
+    if (entry.fontFamily)
+        parts.push(`font-family:${entry.fontFamily}`);
+    if (entry.fontSize)
+        parts.push(`font-size:${entry.fontSize}px`);
+    if (entry.wrap)
+        parts.push('white-space:pre-wrap');
+    if (entry.indent)
+        parts.push(`padding-left:${entry.indent * 12}px`);
+    const borders = borderShadows(entry.border);
+    if (borders)
+        parts.push(`box-shadow:${borders}`);
+    return parts.join(';');
+}
+/**
+ * Cell borders as inset shadows, one per side.
+ *
+ * The cell span fills its td edge to edge, so an inset shadow along one
+ * edge is a border that costs no layout: a real border would push the text
+ * and change the cell's size, and a bordered cell next to a plain one would
+ * misalign. Shadows stack, so a cell can carry any combination of sides.
+ */
+export function borderShadows(border) {
+    if (!border)
+        return '';
+    const parts = [];
+    const line = (spec) => ({
+        w: spec?.width ?? 1,
+        c: spec?.color ?? 'currentColor',
+    });
+    if (border.top) {
+        const { w, c } = line(border.top);
+        parts.push(`inset 0 ${w}px 0 0 ${c}`);
+    }
+    if (border.bottom) {
+        const { w, c } = line(border.bottom);
+        parts.push(`inset 0 -${w}px 0 0 ${c}`);
+    }
+    if (border.left) {
+        const { w, c } = line(border.left);
+        parts.push(`inset ${w}px 0 0 0 ${c}`);
+    }
+    if (border.right) {
+        const { w, c } = line(border.right);
+        parts.push(`inset -${w}px 0 0 0 ${c}`);
+    }
+    return parts.join(',');
+}

package/dist/sheet/freeze.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Freeze panes, over what the grid already has.
+ *
+ * Columns freeze through `api.setColumnPinning({ left: [...] })`, which
+ * makes them sticky and excludes them from the horizontal scroll, and rows
+ * through the grid's `frozenRows` prop, set here with `api.setOption`: the
+ * first N rows stay under the header, still the grid's own rows, editable
+ * and numbered, while the virtualized body scrolls beneath them. Both halves
+ * go through the api, so Freeze Panes is one call for any consumer.
+ *
+ * `splitFrozenRows` stays for a grid that renders its own pinned band from
+ * `pinnedTopRows` instead.
+ */
+import type { GridCommandContext } from '@svgrid/grid/shortcuts';
+export type FreezeState = {
+    /** How many leading rows should be pinned. */
+    rows: number;
+    /** How many leading columns should be pinned. */
+    cols: number;
+};
+export type FreezeSplit<TData> = {
+    /** Pass as `pinnedTopRows`. */
+    pinnedTopRows: ReadonlyArray<TData>;
+    /** Pass as `data`. The pinned rows are REMOVED, so nothing renders twice. */
+    bodyRows: ReadonlyArray<TData>;
+};
+/**
+ * Split a row array for a frozen-row count.
+ *
+ * ```svelte
+ * {@const split = splitFrozenRows(rows, freeze.rows)}
+ * <SvGrid data={split.bodyRows} pinnedTopRows={split.pinnedTopRows} ... />
+ * ```
+ */
+export declare function splitFrozenRows<TData>(rows: ReadonlyArray<TData>, count: number): FreezeSplit<TData>;
+/** Column ids left of `cols`, which is what column pinning takes. */
+export declare function frozenColumnIds(cmd: GridCommandContext, cols: number): string[];
+/**
+ * Apply both halves through the api and report the state: the columns pin,
+ * the rows freeze. Zero rows clears the row half.
+ */
+export declare function applyFreeze(cmd: GridCommandContext, state: FreezeState): FreezeState;
+/**
+ * Excel's Freeze Panes: everything above and to the left of the active cell
+ * freezes. With the cursor on B3 you get two frozen rows and one frozen
+ * column.
+ */
+export declare function freezeAtActiveCell(cmd: GridCommandContext): FreezeState;
+/** Freeze Top Row. */
+export declare function freezeTopRow(cmd: GridCommandContext): FreezeState;
+/** Freeze First Column. */
+export declare function freezeFirstColumn(cmd: GridCommandContext): FreezeState;
+/** Unfreeze everything. */
+export declare function unfreeze(cmd: GridCommandContext): FreezeState;

package/dist/sheet/freeze.js

@@ -0,0 +1,58 @@
+/**
+ * Split a row array for a frozen-row count.
+ *
+ * ```svelte
+ * {@const split = splitFrozenRows(rows, freeze.rows)}
+ * <SvGrid data={split.bodyRows} pinnedTopRows={split.pinnedTopRows} ... />
+ * ```
+ */
+export function splitFrozenRows(rows, count) {
+    const n = Math.max(0, Math.min(Math.floor(count), rows.length));
+    if (n === 0)
+        return { pinnedTopRows: [], bodyRows: rows };
+    return { pinnedTopRows: rows.slice(0, n), bodyRows: rows.slice(n) };
+}
+/** Column ids left of `cols`, which is what column pinning takes. */
+export function frozenColumnIds(cmd, cols) {
+    const out = [];
+    for (let c = 0; c < Math.min(cols, cmd.colCount); c += 1) {
+        const id = cmd.columnIdAt(c);
+        if (id !== null)
+            out.push(id);
+    }
+    return out;
+}
+/**
+ * Apply both halves through the api and report the state: the columns pin,
+ * the rows freeze. Zero rows clears the row half.
+ */
+export function applyFreeze(cmd, state) {
+    const api = cmd.api;
+    api.setColumnPinning?.({ left: frozenColumnIds(cmd, state.cols) });
+    api.setOption?.('frozenRows', state.rows > 0 ? state.rows : undefined);
+    return state;
+}
+/**
+ * Excel's Freeze Panes: everything above and to the left of the active cell
+ * freezes. With the cursor on B3 you get two frozen rows and one frozen
+ * column.
+ */
+export function freezeAtActiveCell(cmd) {
+    const active = cmd.activeCell;
+    const state = active
+        ? { rows: active.rowIndex, cols: active.colIndex }
+        : { rows: 0, cols: 0 };
+    return applyFreeze(cmd, state);
+}
+/** Freeze Top Row. */
+export function freezeTopRow(cmd) {
+    return applyFreeze(cmd, { rows: 1, cols: 0 });
+}
+/** Freeze First Column. */
+export function freezeFirstColumn(cmd) {
+    return applyFreeze(cmd, { rows: 0, cols: 1 });
+}
+/** Unfreeze everything. */
+export function unfreeze(cmd) {
+    return applyFreeze(cmd, { rows: 0, cols: 0 });
+}

package/dist/sheet/function-catalog.d.ts

@@ -0,0 +1,10 @@
+export type FunctionGroup = 'Math' | 'Statistical' | 'Logical' | 'Information' | 'Text' | 'Date & Time' | 'Lookup & Reference' | 'Other';
+export type FunctionInfo = {
+    name: string;
+    group: FunctionGroup;
+    signature: string;
+    description: string;
+};
+export declare const FUNCTION_GROUPS: ReadonlyArray<FunctionGroup>;
+/** Every function the engine knows, described, alphabetical. */
+export declare function functionCatalog(): FunctionInfo[];