@svgrid/enterprise 3.0.2 → 3.0.3

package/dist/sheet/culture.js

@@ -0,0 +1,247 @@
+/**
+ * How a locale spells a number, a date and a formula.
+ *
+ * The rule this module exists to enforce: **the workbook stores the
+ * invariant spelling, always.** A formula in the document is
+ * `=SUM(1.5, A1)` whatever the user's locale, and a number is `1234.5`.
+ * The culture is a layer over the top, applied when a formula is shown for
+ * editing and un-applied when one is typed.
+ *
+ * That is what Excel does, and it is the only arrangement where a file
+ * written in Berlin opens in Boston. Storing `=SUMME(1,5;A1)` would make
+ * the document's meaning depend on who saved it, and every reader, writer
+ * and test would have to carry the locale to make sense of a cell.
+ *
+ * What a culture changes:
+ *   - the decimal mark and the group mark, `1.234,5` against `1,234.5`
+ *   - the argument separator, which Excel makes `;` wherever the decimal
+ *     mark is `,`, since `,` is then busy
+ *   - the order of a slash date, `31/12` against `12/31`
+ *
+ * What it does NOT change: function names, which stay English here, and
+ * the spelling in the file, which stays invariant.
+ */
+/**
+ * The space-like group marks, written by code point rather than as
+ * literals so they are visible in the source.
+ *
+ * `fr-FR` formats with a narrow no-break space and `nb-NO` with a plain
+ * no-break one; neither is on anybody's keyboard, so a typed plain space
+ * has to mean the same thing.
+ */
+const NO_BREAK_SPACE = String.fromCharCode(0x00a0);
+const NARROW_NO_BREAK_SPACE = String.fromCharCode(0x202f);
+export const SPACE_GROUP_MARKS = [' ', NO_BREAK_SPACE, NARROW_NO_BREAK_SPACE];
+/** The spelling the document itself uses, and the default. */
+export const INVARIANT_CULTURE = {
+    locale: 'en-US',
+    decimal: '.',
+    group: ',',
+    argSeparator: ',',
+    dateOrder: 'mdy',
+};
+/**
+ * The culture a locale implies, read off `Intl` rather than a table, so a
+ * locale nobody thought of still comes out right.
+ *
+ * Falls back to the invariant culture where `Intl` is missing or the
+ * locale is not one it knows, since a sheet that renders in the wrong
+ * separators is better than one that does not render.
+ */
+export function cultureFromLocale(locale) {
+    try {
+        const parts = new Intl.NumberFormat(locale).formatToParts(12345.6);
+        const decimal = parts.find((p) => p.type === 'decimal')?.value ?? '.';
+        const group = parts.find((p) => p.type === 'group')?.value ?? ',';
+        const order = dateOrderOf(locale);
+        return {
+            locale,
+            decimal,
+            group,
+            // Excel's rule, not a preference: where the decimal mark is a comma
+            // the comma cannot also separate arguments.
+            argSeparator: decimal === ',' ? ';' : ',',
+            dateOrder: order,
+        };
+    }
+    catch {
+        return INVARIANT_CULTURE;
+    }
+}
+/** Which of day, month and year a locale writes first. */
+function dateOrderOf(locale) {
+    try {
+        const parts = new Intl.DateTimeFormat(locale).formatToParts(new Date(Date.UTC(2026, 11, 31)));
+        const order = parts.filter((p) => p.type === 'day' || p.type === 'month' || p.type === 'year')
+            .map((p) => p.type[0]).join('');
+        if (order.startsWith('y'))
+            return 'ymd';
+        if (order.startsWith('d'))
+            return 'dmy';
+        return 'mdy';
+    }
+    catch {
+        return 'mdy';
+    }
+}
+/** True where the culture spells everything the way the document does. */
+export const isInvariant = (c) => c.decimal === '.' && c.argSeparator === ',';
+/**
+ * Walk a formula, handing each piece to `onNumber` and `onSeparator`.
+ *
+ * Shared by both directions so they cannot disagree about what counts as a
+ * number. The three things that must survive untouched are a string
+ * literal (`"a,b"`), a quoted sheet name (`'Q1,Q2'!A1`) and a function
+ * name with a dot in it (`NORM.DIST`), which is why a word is consumed
+ * whole before any punctuation is looked at.
+ */
+function scanFormula(text, decimal, separator, onNumber, onSeparator) {
+    let out = '';
+    let i = 0;
+    while (i < text.length) {
+        const ch = text[i];
+        // A string literal, with Excel's doubled quote for an embedded one.
+        if (ch === '"') {
+            let j = i + 1;
+            while (j < text.length) {
+                if (text[j] === '"') {
+                    if (text[j + 1] === '"') {
+                        j += 2;
+                        continue;
+                    }
+                    j += 1;
+                    break;
+                }
+                j += 1;
+            }
+            out += text.slice(i, j);
+            i = j;
+            continue;
+        }
+        // A quoted sheet name.
+        if (ch === "'") {
+            const end = text.indexOf("'", i + 1);
+            const close = end < 0 ? text.length : end + 1;
+            out += text.slice(i, close);
+            i = close;
+            continue;
+        }
+        // A word: a function name, a defined name or a cell reference. Taken
+        // whole so the dot in NORM.DIST is never read as a decimal mark.
+        if (/[A-Za-z_$]/.test(ch)) {
+            let j = i;
+            while (j < text.length && /[A-Za-z0-9_.$]/.test(text[j]))
+                j += 1;
+            out += text.slice(i, j);
+            i = j;
+            continue;
+        }
+        // A number, which is where the decimal mark lives.
+        if (/[0-9]/.test(ch)) {
+            let j = i;
+            while (j < text.length && /[0-9]/.test(text[j]))
+                j += 1;
+            let digits = text.slice(i, j);
+            // A decimal mark only counts with a digit after it, so `1,` in
+            // `SUM(1,2)` stays a separator where the mark is a comma.
+            if (text.startsWith(decimal, j) && /[0-9]/.test(text[j + decimal.length] ?? '')) {
+                let k = j + decimal.length;
+                while (k < text.length && /[0-9]/.test(text[k]))
+                    k += 1;
+                digits = text.slice(i, k);
+                j = k;
+            }
+            // An exponent rides along so `1.5E-3` is one number.
+            if (/[eE]/.test(text[j] ?? '') && /[0-9+-]/.test(text[j + 1] ?? '')) {
+                let k = j + 1;
+                if (/[+-]/.test(text[k]))
+                    k += 1;
+                while (k < text.length && /[0-9]/.test(text[k]))
+                    k += 1;
+                digits = text.slice(i, k);
+                j = k;
+            }
+            out += onNumber(digits);
+            i = j;
+            continue;
+        }
+        if (separator !== '' && text.startsWith(separator, i)) {
+            out += onSeparator();
+            i += separator.length;
+            continue;
+        }
+        out += ch;
+        i += 1;
+    }
+    return out;
+}
+/**
+ * A stored formula as the user's locale spells it, for the formula bar.
+ *
+ * `=SUM(1.5, A1)` becomes `=SUM(1,5; A1)` in a German sheet.
+ */
+export function formulaToCulture(formula, culture) {
+    if (isInvariant(culture))
+        return formula;
+    return scanFormula(formula, '.', ',', (digits) => digits.replace('.', culture.decimal), () => culture.argSeparator);
+}
+/**
+ * A typed formula back to the spelling the document stores.
+ *
+ * The inverse of `formulaToCulture`, with one deliberate kindness: where
+ * the culture's separator is `;`, a `,` between arguments is taken as a
+ * separator too, so a user with an English keyboard habit is not stopped.
+ * A `,` that sits between digits is still the decimal mark, so nothing
+ * ambiguous is guessed at.
+ */
+export function formulaFromCulture(formula, culture) {
+    if (isInvariant(culture))
+        return formula;
+    return scanFormula(formula, culture.decimal, culture.argSeparator, (digits) => digits.replace(culture.decimal, '.'), () => ',');
+}
+/**
+ * A number as the culture writes it, back to a plain number.
+ *
+ * Returns null when the text is not a number in this culture, so the
+ * caller can fall through to treating it as text. The group mark is
+ * dropped wherever it appears rather than checked for position, as Excel
+ * does: `1.2.3,4` is not worth refusing on a technicality.
+ */
+export function parseNumberInCulture(text, culture) {
+    const trimmed = text.trim();
+    if (trimmed === '')
+        return null;
+    const groups = culture.group === '' ? [] : [culture.group];
+    // A non-breaking or thin space as a group mark also arrives as a plain
+    // space when it is typed rather than pasted.
+    if (/\s/.test(culture.group))
+        groups.push(...SPACE_GROUP_MARKS);
+    let plain = trimmed;
+    for (const g of groups)
+        plain = plain.split(g).join('');
+    if (culture.decimal !== '.')
+        plain = plain.split(culture.decimal).join('.');
+    if (!/^[+-]?(\d+(\.\d*)?|\.\d+)([eE][+-]?\d+)?$/.test(plain))
+        return null;
+    const n = Number(plain);
+    return Number.isFinite(n) ? n : null;
+}
+/** A number as the culture writes it, for display. */
+export function formatNumberInCulture(value, culture) {
+    const plain = String(value);
+    if (culture.decimal === '.')
+        return plain;
+    return plain.replace('.', culture.decimal);
+}
+/**
+ * The day, month and year a slash date names, in this culture's order.
+ *
+ * Returns null when the pieces cannot be a date, which is what tells a
+ * slash date apart from a fraction typed without a whole part.
+ */
+export function slashDateParts(a, b, culture) {
+    const [month, day] = culture.dateOrder === 'dmy' ? [b, a] : [a, b];
+    if (month < 1 || month > 12 || day < 1 || day > 31)
+        return null;
+    return { month, day };
+}

package/dist/sheet/delta.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Collaboration: the document's changes as a stream of deltas, and the other
+ * half, applying one that arrived from somewhere else.
+ *
+ * `onChange` already says WHAT changed; a collaborator needs to know WHAT IT
+ * BECAME, and small enough to send on every keystroke. So each reason is
+ * turned into a delta carrying just that:
+ *
+ *   cells      the raw text of the cells that were written, not their values:
+ *              a collaborator has to receive `=SUM(A1:A9)` and work out 42 in
+ *              their own workbook, or a formula would arrive as a number;
+ *   structure  the insert or delete itself, which both sides apply the same
+ *              way, so every formula is rewritten identically on each;
+ *   state      the one part of one sheet that changed, serialized the way
+ *              `getState` serializes it (the formats, the merges, the rules,
+ *              the objects, ...);
+ *   document   the whole state, for the changes that are not worth
+ *              describing piecemeal or cannot be: adding, removing or
+ *              reordering sheets, a restore, and the parts the WORKBOOK
+ *              keeps rather than a sheet - its tables, its defined names and
+ *              its calculation settings.
+ *
+ * **Conflicts are last-writer-wins, per cell.** A delta carries no version
+ * and no transform: two people typing in the same cell end on whichever
+ * message arrived last, and everyone converges on that. Two people typing in
+ * DIFFERENT cells never conflict, which is the case that actually happens.
+ * Anything stronger (operational transform, CRDTs) is a different piece of
+ * work and does not belong behind an API this small.
+ */
+import type { SheetChangeReason, SheetDocument, SheetState, SheetStateEntry } from './document.js';
+import type { SheetPresence } from './presence.js';
+import type { StructuralEdit } from './refs.js';
+/** One cell's raw text, as typed. */
+export type SheetCellWrite = {
+    row: number;
+    col: number;
+    text: string;
+};
+export type SheetDelta = {
+    kind: 'cells';
+    sheet: string;
+    cells: SheetCellWrite[];
+} | {
+    kind: 'structure';
+    sheet: string;
+    edit: StructuralEdit;
+} | {
+    kind: 'state';
+    sheet: string;
+    entry: Partial<SheetStateEntry>;
+} | {
+    kind: 'document';
+    state: SheetState;
+}
+/**
+ * Where someone is, which is not part of the document and is never
+ * applied to one: it rides the same wire because there is no reason to
+ * make an application run two, and the stream hands it to `onPresence`.
+ */
+ | {
+    kind: 'presence';
+    who: SheetPresence;
+};
+/** The entry parts a batch of reasons could have changed, deduplicated. */
+export declare function partsOfReasons(reasons: ReadonlyArray<SheetChangeReason>): Array<keyof SheetStateEntry>;
+/**
+ * Apply a delta to a document. The change is reported, so a shell over it
+ * repaints; wrap the call in `doc.mute` where it should not be.
+ *
+ * Applying is idempotent for `cells` and `state`, and NOT for `structure`:
+ * an insert applied twice inserts twice. A transport that can deliver twice
+ * has to deduplicate, which is its job rather than this function's.
+ */
+export declare function applySheetDelta(doc: SheetDocument, delta: SheetDelta): void;
+export type SheetDeltaStream = {
+    /** Apply a delta from elsewhere without sending it straight back out.
+     *  A `presence` delta changes no document; it goes to `onPresence`. */
+    apply(delta: SheetDelta): void;
+    /** Say where this user is. Sent as it stands, since a cursor has no
+     *  history worth batching. */
+    sendPresence(who: SheetPresence): void;
+    /** Send everything as one `document` delta: a new participant's first read. */
+    resync(): void;
+    /** Stop listening. */
+    stop(): void;
+};
+export type SheetDeltaOptions = {
+    /** Called with each delta, in the order they happened. */
+    onDelta(delta: SheetDelta): void;
+    /** Called when a `presence` delta arrives through `apply`: someone else
+     *  moved. Pass what it carries to the shell's `presence` prop. */
+    onPresence?(who: SheetPresence): void;
+};
+/**
+ * Watch a document and report its changes as deltas.
+ *
+ * Cells come from the workbook's raw writes, so what goes out is the text a
+ * user typed rather than the value it computed. Everything else is worked
+ * out by comparing the sheet's serialized parts against the last ones sent,
+ * which is why a change that touches nothing sends nothing.
+ */
+export declare function createDeltaStream(doc: SheetDocument, options: SheetDeltaOptions): SheetDeltaStream;

package/dist/sheet/delta.js

@@ -0,0 +1,203 @@
+/** Which parts of a sheet's saved entry a change reason can have touched. */
+const PARTS = {
+    formats: ['formats'],
+    sizes: ['columnWidths', 'rowHeights'],
+    hidden: ['hidden', 'sheetHidden'],
+    freeze: ['freeze'],
+    comments: ['comments'],
+    validation: ['validation'],
+    'conditional-formats': ['conditionalFormats'],
+    protection: ['protected', 'protection'],
+    'page-setup': ['pageSetup'],
+    objects: ['objects'],
+    sparklines: ['sparklines'],
+    pivots: ['pivots'],
+    links: ['links'],
+    merges: ['merges'],
+    filter: ['autoFilter'],
+};
+/** The entry parts a batch of reasons could have changed, deduplicated. */
+export function partsOfReasons(reasons) {
+    const out = new Set();
+    for (const reason of reasons)
+        for (const part of PARTS[reason.kind] ?? [])
+            out.add(part);
+    return [...out];
+}
+const same = (a, b) => JSON.stringify(a ?? null) === JSON.stringify(b ?? null);
+/**
+ * Apply a delta to a document. The change is reported, so a shell over it
+ * repaints; wrap the call in `doc.mute` where it should not be.
+ *
+ * Applying is idempotent for `cells` and `state`, and NOT for `structure`:
+ * an insert applied twice inserts twice. A transport that can deliver twice
+ * has to deduplicate, which is its job rather than this function's.
+ */
+export function applySheetDelta(doc, delta) {
+    // Presence is a cursor, not a document change: there is nothing to apply,
+    // and applying it would put someone else's selection in the file.
+    if (delta.kind === 'presence')
+        return;
+    if (delta.kind === 'cells') {
+        for (const cell of delta.cells)
+            doc.workbook.setRaw(delta.sheet, cell.row, cell.col, cell.text);
+        doc.changed({ kind: 'cells' });
+        return;
+    }
+    if (delta.kind === 'structure') {
+        doc.workbook.applyStructuralEdit(delta.sheet, delta.edit);
+        doc.shift(delta.sheet, delta.edit);
+        doc.changed({ kind: 'structure', sheet: delta.sheet, edit: delta.edit });
+        return;
+    }
+    if (delta.kind === 'state') {
+        doc.patch(delta.sheet, delta.entry);
+        return;
+    }
+    doc.setState(delta.state);
+}
+/**
+ * Watch a document and report its changes as deltas.
+ *
+ * Cells come from the workbook's raw writes, so what goes out is the text a
+ * user typed rather than the value it computed. Everything else is worked
+ * out by comparing the sheet's serialized parts against the last ones sent,
+ * which is why a change that touches nothing sends nothing.
+ */
+export function createDeltaStream(doc, options) {
+    /** The last entry we know the other side has, per sheet. */
+    let sent = new Map();
+    /** Raw writes waiting to go out, per sheet, keyed by cell so a cell typed
+     *  twice in one tick is sent once. */
+    const pending = new Map();
+    /**
+     * What arrived from elsewhere and must not go straight back out.
+     *
+     * A time-based "we are applying right now" flag cannot do this: the
+     * document reports its changes on a LATER microtask, by which time the
+     * flag is down, and two streams wired to each other would echo forever.
+     * So each applied change is marked instead, and the mark is what the
+     * listener drops - which also means a local change made in the same tick
+     * is still sent rather than being swallowed by the window.
+     */
+    const appliedStructures = [];
+    let appliedDocument = false;
+    let stopped = false;
+    const snapshot = () => {
+        const state = doc.getState();
+        sent = new Map(Object.entries(state.sheets));
+        return state;
+    };
+    snapshot();
+    function flushCells() {
+        if (pending.size === 0)
+            return;
+        for (const [sheet, cells] of pending) {
+            if (cells.size)
+                options.onDelta({ kind: 'cells', sheet, cells: [...cells.values()] });
+        }
+        pending.clear();
+    }
+    const offWrites = doc.workbook.subscribeWrites((change) => {
+        if (stopped)
+            return;
+        const key = `${change.row},${change.col}`;
+        const cells = pending.get(change.sheet) ?? new Map();
+        cells.set(key, { row: change.row, col: change.col, text: change.text });
+        pending.set(change.sheet, cells);
+    });
+    const offChanges = doc.subscribe((reasons) => {
+        if (stopped)
+            return;
+        // The cells first: a structural edit or a rule that arrived in the same
+        // tick reads them, and the other side has to see them in that order too.
+        flushCells();
+        for (const reason of reasons) {
+            if (reason.kind !== 'structure')
+                continue;
+            const mark = JSON.stringify({ sheet: reason.sheet, edit: reason.edit });
+            const at = appliedStructures.indexOf(mark);
+            // One that came from elsewhere: the other side already has it.
+            if (at >= 0) {
+                appliedStructures.splice(at, 1);
+                continue;
+            }
+            options.onDelta({ kind: 'structure', sheet: reason.sheet, edit: reason.edit });
+        }
+        // Sheets added, removed or reordered, a restore, and the parts that
+        // belong to the WORKBOOK rather than to a sheet - its tables, its names,
+        // its calculation settings - are the changes a part-by-part delta cannot
+        // describe: a `state` delta is keyed by sheet and carries a sheet's own
+        // entry, and none of these live there. Send the document.
+        if (reasons.some((r) => r.kind === 'sheets' || r.kind === 'restore' || r.kind === 'tables' || r.kind === 'workbook')) {
+            if (appliedDocument) {
+                appliedDocument = false;
+                snapshot();
+                return;
+            }
+            options.onDelta({ kind: 'document', state: snapshot() });
+            return;
+        }
+        const parts = partsOfReasons(reasons);
+        if (parts.length === 0) {
+            snapshot();
+            return;
+        }
+        const state = doc.getState();
+        for (const [sheet, entry] of Object.entries(state.sheets)) {
+            const before = sent.get(sheet);
+            const patch = {};
+            let any = false;
+            for (const part of parts) {
+                if (same(entry[part], before?.[part]))
+                    continue;
+                patch[part] = entry[part];
+                any = true;
+            }
+            if (any)
+                options.onDelta({ kind: 'state', sheet, entry: patch });
+        }
+        sent = new Map(Object.entries(state.sheets));
+    });
+    return {
+        apply(delta) {
+            if (stopped)
+                return;
+            if (delta.kind === 'presence') {
+                options.onPresence?.(delta.who);
+                return;
+            }
+            if (delta.kind === 'structure')
+                appliedStructures.push(JSON.stringify({ sheet: delta.sheet, edit: delta.edit }));
+            if (delta.kind === 'document')
+                appliedDocument = true;
+            applySheetDelta(doc, delta);
+            if (delta.kind === 'cells') {
+                // Written here, so there is nothing to write back.
+                const cells = pending.get(delta.sheet);
+                if (cells) {
+                    for (const cell of delta.cells)
+                        cells.delete(`${cell.row},${cell.col}`);
+                    if (cells.size === 0)
+                        pending.delete(delta.sheet);
+                }
+            }
+            // What arrived is what the other side already has: fold it into the
+            // baseline so the next comparison does not report it as ours.
+            snapshot();
+        },
+        sendPresence(who) {
+            if (stopped)
+                return;
+            options.onDelta({ kind: 'presence', who });
+        },
+        resync() {
+            options.onDelta({ kind: 'document', state: snapshot() });
+        },
+        stop() {
+            stopped = true;
+            offWrites();
+            offChanges();
+        },
+    };
+}

package/dist/sheet/deps.d.ts

@@ -44,7 +44,49 @@ export declare function precedentsOf(ast: Node, self: {
  * `Tax` leaves the formula showing its old value until something else
  * forces a recalculation.
  */
-resolveName?: (name: string) => Node | null, depth?: number): CellKey[];
+resolveName?: (name: string) => Node | null, 
+/**
+ * The rectangle behind a structured reference (`Orders[Amount]`,
+ * `[@Qty]`). Without it a formula over a table records no precedents, so
+ * editing a cell in the table leaves every total reading it stale until
+ * something forces a full recalculation.
+ */
+resolveTable?: (node: Extract<Node, {
+    k: 'table';
+}>) => {
+    sheet: string;
+    firstRow: number;
+    lastRow: number;
+    firstCol: number;
+    lastCol: number;
+} | null, 
+/**
+ * The rectangle a spilled-range operator (`A1#`) currently covers. The
+ * anchor cell is always recorded regardless, so a formula reading `A1#`
+ * recalculates whenever the array is re-typed and picks up the new extent;
+ * the covered cells are added on top so a change anywhere in the spill
+ * reaches it too.
+ */
+resolveSpill?: (node: Extract<Node, {
+    k: 'spill';
+}>) => {
+    sheet: string | null;
+    r1: number;
+    c1: number;
+    r2: number;
+    c2: number;
+} | null, 
+/** The sheets a 3D reference spans, so it recalculates when the cell on any
+ *  of them changes. */
+resolveSheets?: (from: string, to: string) => string[] | null, depth?: number): CellKey[];
+/**
+ * Functions whose result can change without any precedent changing: a
+ * reference built from text, a range built from arithmetic, the clock, a
+ * random number. A cell holding one is recomputed on every edit, as Excel
+ * recomputes its volatile cells, rather than trusting the graph.
+ */
+export declare const VOLATILE_FUNCTIONS: ReadonlySet<string>;
+export declare function isVolatile(ast: Node): boolean;
 export type DependencyGraph = {
     /** Record (or clear, with null) what one cell reads. */
     setPrecedents(cell: CellKey, precedents: ReadonlyArray<CellKey> | null): void;
@@ -55,6 +97,8 @@ export type DependencyGraph = {
     cycles(): CellKey[];
     /** Direct readers of a cell. */
     dependentsOf(cell: CellKey): CellKey[];
+    /** What a cell reads directly, as last recorded. */
+    precedentsOf(cell: CellKey): CellKey[];
     clear(): void;
 };
 export declare function createDependencyGraph(): DependencyGraph;