@bilig/headless 0.1.28 → 0.1.30

package/README.md

@@ -1,6 +1,6 @@
 # @bilig/headless
 
-Headless workbook facade for `bilig`.
+WorkPaper workbook facade for `bilig`.
 
 `@bilig/headless` exposes `WorkPaper`, a HyperFormula-style workbook API on top of
 `@bilig/core`'s `SpreadsheetEngine` for server-side and headless workflows.
@@ -44,7 +44,6 @@ const value = workbook.getCellValue({ sheet: sheetId, row: 0, col: 1 });
 ## Compatibility Notes
 
 - `WorkPaper` is the canonical top-level interface.
-- `HeadlessWorkbook` remains exported as a compatibility alias for existing callers.
 - The facade follows HyperFormula's public workbook workflow closely, but it is not a
   byte-for-byte drop-in replacement.
 - Public lookup helpers such as `getSheetId()`, `getSheetName()`,

package/dist/change-order.d.ts

@@ -0,0 +1,7 @@
+import type { WorkPaperChange } from "./work-paper-types.js";
+type SheetOrder = readonly {
+    id: number;
+    order: number;
+}[];
+export declare function orderWorkPaperCellChanges(changes: WorkPaperChange[], sheets: SheetOrder, explicitChangedCount?: number): WorkPaperChange[];
+export {};

package/dist/change-order.js

@@ -0,0 +1,64 @@
+export function orderWorkPaperCellChanges(changes, sheets, explicitChangedCount) {
+    if (changes.length < 2) {
+        return changes;
+    }
+    const compare = compareWorkPaperCellChanges(sheets);
+    const split = explicitChangedCount === undefined ? undefined : Math.min(explicitChangedCount, changes.length);
+    if (split !== undefined &&
+        split > 0 &&
+        split < changes.length &&
+        isSortedCellChangeSlice(changes, compare, 0, split) &&
+        isSortedCellChangeSlice(changes, compare, split, changes.length)) {
+        return mergeSortedCellChangeSlices(changes, compare, split);
+    }
+    if (isSortedCellChangeSlice(changes, compare, 0, changes.length)) {
+        return changes;
+    }
+    return changes.toSorted(compare);
+}
+function compareWorkPaperCellChanges(sheets) {
+    const orderBySheet = new Map(sheets.map((sheet) => [sheet.id, sheet.order]));
+    return (left, right) => {
+        if (left.kind !== "cell" || right.kind !== "cell") {
+            return 0;
+        }
+        return ((orderBySheet.get(left.address.sheet) ?? 0) - (orderBySheet.get(right.address.sheet) ?? 0) ||
+            left.address.row - right.address.row ||
+            left.address.col - right.address.col);
+    };
+}
+function isSortedCellChangeSlice(changes, compare, start, end) {
+    for (let index = start + 1; index < end; index += 1) {
+        if (compare(changes[index - 1], changes[index]) > 0) {
+            return false;
+        }
+    }
+    return true;
+}
+function mergeSortedCellChangeSlices(changes, compare, split) {
+    const merged = [];
+    let leftIndex = 0;
+    let rightIndex = split;
+    while (leftIndex < split && rightIndex < changes.length) {
+        const left = changes[leftIndex];
+        const right = changes[rightIndex];
+        if (compare(left, right) <= 0) {
+            merged.push(left);
+            leftIndex += 1;
+        }
+        else {
+            merged.push(right);
+            rightIndex += 1;
+        }
+    }
+    while (leftIndex < split) {
+        merged.push(changes[leftIndex]);
+        leftIndex += 1;
+    }
+    while (rightIndex < changes.length) {
+        merged.push(changes[rightIndex]);
+        rightIndex += 1;
+    }
+    return merged;
+}
+//# sourceMappingURL=change-order.js.map

package/dist/change-order.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"change-order.js","sourceRoot":"","sources":["../src/change-order.ts"],"names":[],"mappings":"AAIA,MAAM,UAAU,yBAAyB,CACvC,OAA0B,EAC1B,MAAkB,EAClB,oBAA6B;IAE7B,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACvB,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,MAAM,OAAO,GAAG,2BAA2B,CAAC,MAAM,CAAC,CAAC;IACpD,MAAM,KAAK,GACT,oBAAoB,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,oBAAoB,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;IAElG,IACE,KAAK,KAAK,SAAS;QACnB,KAAK,GAAG,CAAC;QACT,KAAK,GAAG,OAAO,CAAC,MAAM;QACtB,uBAAuB,CAAC,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,KAAK,CAAC;QACnD,uBAAuB,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,CAAC,MAAM,CAAC,EAChE,CAAC;QACD,OAAO,2BAA2B,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,CAAC,CAAC;IAC9D,CAAC;IAED,IAAI,uBAAuB,CAAC,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QACjE,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,OAAO,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;AACnC,CAAC;AAED,SAAS,2BAA2B,CAClC,MAAkB;IAElB,MAAM,YAAY,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,EAAE,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAC7E,OAAO,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE;QACrB,IAAI,IAAI,CAAC,IAAI,KAAK,MAAM,IAAI,KAAK,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;YAClD,OAAO,CAAC,CAAC;QACX,CAAC;QACD,OAAO,CACL,CAAC,YAAY,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YAC1F,IAAI,CAAC,OAAO,CAAC,GAAG,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG;YACpC,IAAI,CAAC,OAAO,CAAC,GAAG,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CACrC,CAAC;IACJ,CAAC,CAAC;AACJ,CAAC;AAED,SAAS,uBAAuB,CAC9B,OAAmC,EACnC,OAAkE,EAClE,KAAa,EACb,GAAW;IAEX,KAAK,IAAI,KAAK,GAAG,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,GAAG,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC;QACpD,IAAI,OAAO,CAAC,OAAO,CAAC,KAAK,GAAG,CAAC,CAAE,EAAE,OAAO,CAAC,KAAK,CAAE,CAAC,GAAG,CAAC,EAAE,CAAC;YACtD,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAS,2BAA2B,CAClC,OAAmC,EACnC,OAAkE,EAClE,KAAa;IAEb,MAAM,MAAM,GAAsB,EAAE,CAAC;IACrC,IAAI,SAAS,GAAG,CAAC,CAAC;IAClB,IAAI,UAAU,GAAG,KAAK,CAAC;IACvB,OAAO,SAAS,GAAG,KAAK,IAAI,UAAU,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;QACxD,MAAM,IAAI,GAAG,OAAO,CAAC,SAAS,CAAE,CAAC;QACjC,MAAM,KAAK,GAAG,OAAO,CAAC,UAAU,CAAE,CAAC;QACnC,IAAI,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;YAC9B,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAClB,SAAS,IAAI,CAAC,CAAC;QACjB,CAAC;aAAM,CAAC;YACN,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACnB,UAAU,IAAI,CAAC,CAAC;QAClB,CAAC;IACH,CAAC;IACD,OAAO,SAAS,GAAG,KAAK,EAAE,CAAC;QACzB,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,SAAS,CAAE,CAAC,CAAC;QACjC,SAAS,IAAI,CAAC,CAAC;IACjB,CAAC;IACD,OAAO,UAAU,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;QACnC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,UAAU,CAAE,CAAC,CAAC;QAClC,UAAU,IAAI,CAAC,CAAC;IAClB,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/deferred-literal-history.d.ts

@@ -0,0 +1,13 @@
+import { SpreadsheetEngine } from "@bilig/core";
+import type { EngineOp } from "@bilig/workbook-domain";
+export interface DeferredLiteralHistoryRecord {
+    forward: {
+        ops: unknown[];
+        potentialNewCells?: number;
+    };
+    inverse: {
+        ops: unknown[];
+        potentialNewCells?: number;
+    };
+}
+export declare function buildDeferredLiteralHistoryRecord(engine: SpreadsheetEngine, ops: readonly EngineOp[], potentialNewCells?: number): DeferredLiteralHistoryRecord | null;

package/dist/deferred-literal-history.js

@@ -0,0 +1,67 @@
+import { ValueTag } from "@bilig/protocol";
+function cloneDeferredLiteralOp(op) {
+    switch (op.kind) {
+        case "setCellValue":
+            return {
+                kind: "setCellValue",
+                sheetName: op.sheetName,
+                address: op.address,
+                value: op.value,
+            };
+        case "clearCell":
+            return {
+                kind: "clearCell",
+                sheetName: op.sheetName,
+                address: op.address,
+            };
+    }
+}
+function restoreCellOp(engine, sheetName, address) {
+    const cellIndex = engine.workbook.getCellIndex(sheetName, address);
+    if (cellIndex === undefined) {
+        return { kind: "clearCell", sheetName, address };
+    }
+    const cell = engine.getCellByIndex(cellIndex);
+    if (cell.formula !== undefined) {
+        return {
+            kind: "setCellFormula",
+            sheetName,
+            address,
+            formula: cell.formula,
+        };
+    }
+    switch (cell.value.tag) {
+        case ValueTag.Empty:
+        case ValueTag.Error:
+            return { kind: "clearCell", sheetName, address };
+        case ValueTag.Number:
+        case ValueTag.Boolean:
+        case ValueTag.String:
+            return {
+                kind: "setCellValue",
+                sheetName,
+                address,
+                value: cell.value.value,
+            };
+    }
+}
+export function buildDeferredLiteralHistoryRecord(engine, ops, potentialNewCells) {
+    const literalOps = [];
+    for (let index = 0; index < ops.length; index += 1) {
+        const op = ops[index];
+        if (!op || (op.kind !== "setCellValue" && op.kind !== "clearCell")) {
+            return null;
+        }
+        literalOps.push(op);
+    }
+    return {
+        forward: potentialNewCells === undefined
+            ? { ops: literalOps.map((op) => cloneDeferredLiteralOp(op)) }
+            : { ops: literalOps.map((op) => cloneDeferredLiteralOp(op)), potentialNewCells },
+        inverse: {
+            ops: literalOps.toReversed().map((op) => restoreCellOp(engine, op.sheetName, op.address)),
+            potentialNewCells: literalOps.length,
+        },
+    };
+}
+//# sourceMappingURL=deferred-literal-history.js.map

package/dist/deferred-literal-history.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deferred-literal-history.js","sourceRoot":"","sources":["../src/deferred-literal-history.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -1,4 +1 @@
-export * from "./errors.js";
-export * from "./headless-workbook.js";
-export * from "./types.js";
 export * from "./work-paper.js";

package/dist/index.js

@@ -1,5 +1,2 @@
-export * from "./errors.js";
-export * from "./headless-workbook.js";
-export * from "./types.js";
 export * from "./work-paper.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,wBAAwB,CAAC;AACvC,cAAc,YAAY,CAAC;AAC3B,cAAc,iBAAiB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAC"}

package/dist/initial-sheet-load.d.ts

@@ -0,0 +1,3 @@
+import { type SpreadsheetEngine } from "@bilig/core";
+import type { WorkPaperSheet } from "./work-paper-types.js";
+export declare function tryLoadInitialLiteralSheet(engine: SpreadsheetEngine, sheetId: number, content: WorkPaperSheet): boolean;

package/dist/initial-sheet-load.js

@@ -0,0 +1,12 @@
+import { loadLiteralSheetIntoEmptySheet } from "@bilig/core";
+export function tryLoadInitialLiteralSheet(engine, sheetId, content) {
+    if (sheetContainsFormulaContent(content)) {
+        return false;
+    }
+    loadLiteralSheetIntoEmptySheet(engine.workbook, engine.strings, sheetId, content);
+    return true;
+}
+function sheetContainsFormulaContent(content) {
+    return content.some((row) => row.some((value) => typeof value === "string" && value.trim().startsWith("=")));
+}
+//# sourceMappingURL=initial-sheet-load.js.map

package/dist/initial-sheet-load.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"initial-sheet-load.js","sourceRoot":"","sources":["../src/initial-sheet-load.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,8BAA8B,EAA0B,MAAM,aAAa,CAAC;AAGrF,MAAM,UAAU,0BAA0B,CACxC,MAAyB,EACzB,OAAe,EACf,OAAuB;IAEvB,IAAI,2BAA2B,CAAC,OAAO,CAAC,EAAE,CAAC;QACzC,OAAO,KAAK,CAAC;IACf,CAAC;IACD,8BAA8B,CAAC,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;IAClF,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAS,2BAA2B,CAAC,OAAuB;IAC1D,OAAO,OAAO,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAC1B,GAAG,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAC/E,CAAC;AACJ,CAAC"}

package/dist/matrix-mutation-plan.d.ts

@@ -1,29 +1,18 @@
-import type { LiteralInput } from "@bilig/protocol";
-import type { HeadlessCellAddress, HeadlessSheet } from "./types.js";
-export type MatrixMutationOp = {
-    kind: "clearCell";
-    sheetName: string;
-    address: string;
-} | {
-    kind: "setCellValue";
-    sheetName: string;
-    address: string;
-    value: LiteralInput;
-} | {
-    kind: "setCellFormula";
-    sheetName: string;
-    address: string;
-    formula: string;
-};
+import type { EngineCellMutationRef } from "@bilig/core";
+import type { WorkPaperCellAddress, WorkPaperSheet } from "./work-paper-types.js";
+export type MatrixMutationRef = EngineCellMutationRef;
 export interface MatrixMutationPlan {
-    ops: MatrixMutationOp[];
+    leadingRefs: MatrixMutationRef[];
+    formulaRefs: MatrixMutationRef[];
+    refs: MatrixMutationRef[];
     potentialNewCells: number;
+    trailingLiteralRefs: MatrixMutationRef[];
 }
 interface BuildMatrixMutationPlanArgs {
-    target: HeadlessCellAddress;
-    targetSheetName: string;
-    content: HeadlessSheet;
-    rewriteFormula: (formula: string, destination: HeadlessCellAddress, rowOffset: number, columnOffset: number) => string;
+    target: WorkPaperCellAddress;
+    content: WorkPaperSheet;
+    rewriteFormula: (formula: string, destination: WorkPaperCellAddress, rowOffset: number, columnOffset: number) => string;
+    deferLiteralAddresses?: ReadonlySet<string>;
     skipNulls?: boolean;
 }
 export declare function buildMatrixMutationPlan(args: BuildMatrixMutationPlanArgs): MatrixMutationPlan;

package/dist/matrix-mutation-plan.js

@@ -3,8 +3,26 @@ function isFormulaContent(content) {
     return typeof content === "string" && content.trim().startsWith("=");
 }
 export function buildMatrixMutationPlan(args) {
-    const ops = [];
+    const leadingRefs = [];
+    const formulaRefs = [];
+    const trailingLiteralRefs = [];
     let potentialNewCells = 0;
+    const earliestFormulaRowByColumn = new Map();
+    args.content.forEach((row, rowOffset) => {
+        row.forEach((raw, columnOffset) => {
+            if (!isFormulaContent(raw)) {
+                return;
+            }
+            const destinationRow = args.target.row + rowOffset;
+            const destinationCol = args.target.col + columnOffset;
+            const earliestFormulaRow = earliestFormulaRowByColumn.get(destinationCol);
+            if (earliestFormulaRow === undefined || destinationRow < earliestFormulaRow) {
+                earliestFormulaRowByColumn.set(destinationCol, destinationRow);
+            }
+        });
+    });
+    const shouldDeferLiteral = (address, row, col) => args.deferLiteralAddresses?.has(address) === true ||
+        row > (earliestFormulaRowByColumn.get(col) ?? Number.POSITIVE_INFINITY);
     args.content.forEach((row, rowOffset) => {
         row.forEach((raw, columnOffset) => {
             const destination = {
@@ -15,28 +33,55 @@ export function buildMatrixMutationPlan(args) {
             const address = formatAddress(destination.row, destination.col);
             if (raw === null) {
                 if (!args.skipNulls) {
-                    ops.push({ kind: "clearCell", sheetName: args.targetSheetName, address });
+                    const ref = {
+                        sheetId: args.target.sheet,
+                        mutation: { kind: "clearCell", row: destination.row, col: destination.col },
+                    };
+                    if (shouldDeferLiteral(address, destination.row, destination.col)) {
+                        trailingLiteralRefs.push(ref);
+                    }
+                    else {
+                        leadingRefs.push(ref);
+                    }
                 }
                 return;
             }
             potentialNewCells += 1;
             if (isFormulaContent(raw)) {
-                ops.push({
-                    kind: "setCellFormula",
-                    sheetName: args.targetSheetName,
-                    address,
-                    formula: args.rewriteFormula(raw, destination, rowOffset, columnOffset),
+                formulaRefs.push({
+                    sheetId: args.target.sheet,
+                    mutation: {
+                        kind: "setCellFormula",
+                        row: destination.row,
+                        col: destination.col,
+                        formula: args.rewriteFormula(raw, destination, rowOffset, columnOffset),
+                    },
                 });
                 return;
             }
-            ops.push({
-                kind: "setCellValue",
-                sheetName: args.targetSheetName,
-                address,
-                value: raw,
-            });
+            const ref = {
+                sheetId: args.target.sheet,
+                mutation: {
+                    kind: "setCellValue",
+                    row: destination.row,
+                    col: destination.col,
+                    value: raw,
+                },
+            };
+            if (shouldDeferLiteral(address, destination.row, destination.col)) {
+                trailingLiteralRefs.push(ref);
+            }
+            else {
+                leadingRefs.push(ref);
+            }
         });
     });
-    return { ops, potentialNewCells };
+    return {
+        leadingRefs,
+        formulaRefs,
+        refs: [...leadingRefs, ...formulaRefs, ...trailingLiteralRefs],
+        potentialNewCells,
+        trailingLiteralRefs,
+    };
 }
 //# sourceMappingURL=matrix-mutation-plan.js.map

package/dist/matrix-mutation-plan.js.map

@@ -1 +1 @@
-{"version":3,"file":"matrix-mutation-plan.js","sourceRoot":"","sources":["../src/matrix-mutation-plan.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AA2B/C,SAAS,gBAAgB,CAAC,OAAuB;IAC/C,OAAO,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;AACvE,CAAC;AAED,MAAM,UAAU,uBAAuB,CAAC,IAAiC;IACvE,MAAM,GAAG,GAAuB,EAAE,CAAC;IACnC,IAAI,iBAAiB,GAAG,CAAC,CAAC;IAE1B,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,GAAG,EAAE,SAAS,EAAE,EAAE;QACtC,GAAG,CAAC,OAAO,CAAC,CAAC,GAAG,EAAE,YAAY,EAAE,EAAE;YAChC,MAAM,WAAW,GAAwB;gBACvC,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC,KAAK;gBACxB,GAAG,EAAE,IAAI,CAAC,MAAM,CAAC,GAAG,GAAG,SAAS;gBAChC,GAAG,EAAE,IAAI,CAAC,MAAM,CAAC,GAAG,GAAG,YAAY;aACpC,CAAC;YACF,MAAM,OAAO,GAAG,aAAa,CAAC,WAAW,CAAC,GAAG,EAAE,WAAW,CAAC,GAAG,CAAC,CAAC;YAEhE,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;gBACjB,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC;oBACpB,GAAG,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,SAAS,EAAE,IAAI,CAAC,eAAe,EAAE,OAAO,EAAE,CAAC,CAAC;gBAC5E,CAAC;gBACD,OAAO;YACT,CAAC;YAED,iBAAiB,IAAI,CAAC,CAAC;YAEvB,IAAI,gBAAgB,CAAC,GAAG,CAAC,EAAE,CAAC;gBAC1B,GAAG,CAAC,IAAI,CAAC;oBACP,IAAI,EAAE,gBAAgB;oBACtB,SAAS,EAAE,IAAI,CAAC,eAAe;oBAC/B,OAAO;oBACP,OAAO,EAAE,IAAI,CAAC,cAAc,CAAC,GAAG,EAAE,WAAW,EAAE,SAAS,EAAE,YAAY,CAAC;iBACxE,CAAC,CAAC;gBACH,OAAO;YACT,CAAC;YAED,GAAG,CAAC,IAAI,CAAC;gBACP,IAAI,EAAE,cAAc;gBACpB,SAAS,EAAE,IAAI,CAAC,eAAe;gBAC/B,OAAO;gBACP,KAAK,EAAE,GAAG;aACX,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,OAAO,EAAE,GAAG,EAAE,iBAAiB,EAAE,CAAC;AACpC,CAAC"}
+{"version":3,"file":"matrix-mutation-plan.js","sourceRoot":"","sources":["../src/matrix-mutation-plan.ts"],"names":[],"mappings":"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"}

package/dist/tracked-engine-event-refs.d.ts

@@ -0,0 +1,11 @@
+import type { EngineEvent } from "@bilig/protocol";
+export interface TrackedEngineEvent {
+    invalidation: EngineEvent["invalidation"];
+    changedCellIndices: Uint32Array;
+    changedInputCount: number;
+    explicitChangedCount?: number;
+    hasInvalidatedRanges: boolean;
+    hasInvalidatedRows: boolean;
+    hasInvalidatedColumns: boolean;
+}
+export declare function captureTrackedEngineEvent(event: EngineEvent): TrackedEngineEvent;

package/dist/tracked-engine-event-refs.js

@@ -0,0 +1,18 @@
+function readExplicitChangedCount(event) {
+    const explicitChangedCount = Reflect.get(event, "explicitChangedCount");
+    return typeof explicitChangedCount === "number" && explicitChangedCount >= 0
+        ? explicitChangedCount
+        : undefined;
+}
+export function captureTrackedEngineEvent(event) {
+    return {
+        invalidation: event.invalidation,
+        changedCellIndices: Uint32Array.from(event.changedCellIndices),
+        changedInputCount: event.metrics.changedInputCount,
+        explicitChangedCount: readExplicitChangedCount(event),
+        hasInvalidatedRanges: event.invalidatedRanges.length > 0,
+        hasInvalidatedRows: event.invalidatedRows.length > 0,
+        hasInvalidatedColumns: event.invalidatedColumns.length > 0,
+    };
+}
+//# sourceMappingURL=tracked-engine-event-refs.js.map

package/dist/tracked-engine-event-refs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracked-engine-event-refs.js","sourceRoot":"","sources":["../src/tracked-engine-event-refs.ts"],"names":[],"mappings":"AAYA,SAAS,wBAAwB,CAAC,KAAkB;IAClD,MAAM,oBAAoB,GAAG,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,sBAAsB,CAAC,CAAC;IACxE,OAAO,OAAO,oBAAoB,KAAK,QAAQ,IAAI,oBAAoB,IAAI,CAAC;QAC1E,CAAC,CAAC,oBAAoB;QACtB,CAAC,CAAC,SAAS,CAAC;AAChB,CAAC;AAED,MAAM,UAAU,yBAAyB,CAAC,KAAkB;IAC1D,OAAO;QACL,YAAY,EAAE,KAAK,CAAC,YAAY;QAChC,kBAAkB,EAAE,WAAW,CAAC,IAAI,CAAC,KAAK,CAAC,kBAAkB,CAAC;QAC9D,iBAAiB,EAAE,KAAK,CAAC,OAAO,CAAC,iBAAiB;QAClD,oBAAoB,EAAE,wBAAwB,CAAC,KAAK,CAAC;QACrD,oBAAoB,EAAE,KAAK,CAAC,iBAAiB,CAAC,MAAM,GAAG,CAAC;QACxD,kBAAkB,EAAE,KAAK,CAAC,eAAe,CAAC,MAAM,GAAG,CAAC;QACpD,qBAAqB,EAAE,KAAK,CAAC,kBAAkB,CAAC,MAAM,GAAG,CAAC;KAC3D,CAAC;AACJ,CAAC"}

package/dist/work-paper-errors.d.ts

@@ -0,0 +1,106 @@
+import type { WorkPaperCellAddress } from "./work-paper-types.js";
+declare class BaseWorkPaperError extends Error {
+    constructor(name: string, message: string);
+}
+export declare class WorkPaperConfigValueTooBigError extends BaseWorkPaperError {
+    constructor(paramName: string, maximum: number);
+}
+export declare class WorkPaperConfigValueTooSmallError extends BaseWorkPaperError {
+    constructor(paramName: string, minimum: number);
+}
+export declare class WorkPaperEvaluationSuspendedError extends BaseWorkPaperError {
+    constructor(message?: string);
+}
+export declare class WorkPaperExpectedOneOfValuesError extends BaseWorkPaperError {
+    constructor(values: string, paramName: string);
+}
+export declare class WorkPaperExpectedValueOfTypeError extends BaseWorkPaperError {
+    constructor(expectedType: string, paramName: string);
+}
+export declare class WorkPaperFunctionPluginValidationError extends BaseWorkPaperError {
+    constructor(message: string);
+    static functionNotDeclaredInPlugin(functionId: string, pluginName: string): WorkPaperFunctionPluginValidationError;
+    static functionMethodNotFound(functionName: string, pluginName: string): WorkPaperFunctionPluginValidationError;
+}
+export declare class WorkPaperInvalidAddressError extends BaseWorkPaperError {
+    constructor(address: WorkPaperCellAddress);
+}
+export declare class WorkPaperInvalidArgumentsError extends BaseWorkPaperError {
+    constructor(expectedArguments: string);
+}
+export declare class WorkPaperLanguageAlreadyRegisteredError extends BaseWorkPaperError {
+    constructor(languageCode?: string);
+}
+export declare class WorkPaperLanguageNotRegisteredError extends BaseWorkPaperError {
+    constructor(languageCode?: string);
+}
+export declare class WorkPaperMissingTranslationError extends BaseWorkPaperError {
+    constructor(key: string);
+}
+export declare class WorkPaperNamedExpressionDoesNotExistError extends BaseWorkPaperError {
+    constructor(expressionName: string);
+}
+export declare class WorkPaperNamedExpressionNameIsAlreadyTakenError extends BaseWorkPaperError {
+    constructor(expressionName: string);
+}
+export declare class WorkPaperNamedExpressionNameIsInvalidError extends BaseWorkPaperError {
+    constructor(expressionName: string);
+}
+export declare class WorkPaperNoOperationToRedoError extends BaseWorkPaperError {
+    constructor();
+}
+export declare class WorkPaperNoOperationToUndoError extends BaseWorkPaperError {
+    constructor();
+}
+export declare class WorkPaperNoRelativeAddressesAllowedError extends BaseWorkPaperError {
+    constructor();
+}
+export declare class WorkPaperNoSheetWithIdError extends BaseWorkPaperError {
+    constructor(sheetId: number);
+}
+export declare class WorkPaperNoSheetWithNameError extends BaseWorkPaperError {
+    constructor(sheetName: string);
+}
+export declare class WorkPaperNotAFormulaError extends BaseWorkPaperError {
+    constructor();
+}
+export declare class WorkPaperNothingToPasteError extends BaseWorkPaperError {
+    constructor();
+}
+export declare class WorkPaperProtectedFunctionTranslationError extends BaseWorkPaperError {
+    constructor(functionId: string);
+}
+export declare class WorkPaperSheetNameAlreadyTakenError extends BaseWorkPaperError {
+    constructor(sheetName: string);
+}
+export declare class WorkPaperSheetSizeLimitExceededError extends BaseWorkPaperError {
+    constructor();
+}
+export declare class WorkPaperSourceLocationHasArrayError extends BaseWorkPaperError {
+    constructor();
+}
+export declare class WorkPaperTargetLocationHasArrayError extends BaseWorkPaperError {
+    constructor();
+}
+export declare class WorkPaperUnableToParseError extends BaseWorkPaperError {
+    constructor(value: unknown);
+}
+export declare class WorkPaperConfigError extends BaseWorkPaperError {
+    constructor(message: string);
+}
+export declare class WorkPaperSheetError extends BaseWorkPaperError {
+    constructor(message: string);
+}
+export declare class WorkPaperNamedExpressionError extends BaseWorkPaperError {
+    constructor(message: string);
+}
+export declare class WorkPaperClipboardError extends BaseWorkPaperError {
+    constructor(message: string);
+}
+export declare class WorkPaperParseError extends BaseWorkPaperError {
+    constructor(message: string);
+}
+export declare class WorkPaperOperationError extends BaseWorkPaperError {
+    constructor(message: string);
+}
+export {};