@rowsncolumns/spreadsheet-state 28.0.72 → 28.0.74

package/dist/cjs/api/paste-special.js

@@ -0,0 +1,229 @@
+import { __assign, __rest } from "tslib";
+import { getCellUserEnteredValue, getExtendedValueBool, getExtendedValueFormula, getExtendedValueNumber, getExtendedValueString, isNil, } from "@rowsncolumns/utils";
+import { SheetCell } from "../sheet-cell";
+import { convertToNumber, isNumber } from "./datatype";
+/** Synthetic clipboard key carrying the legacy single-mode `PasteSpecialType`. */
+export var PASTE_SPECIAL_TYPE_KEY = "pasteSpecialType";
+/** Synthetic clipboard key carrying a JSON-encoded `PasteSpecialOptions`. */
+export var PASTE_SPECIAL_OPTIONS_KEY = "pasteSpecialOptions";
+var PLAIN_PASTE = {
+    paste: "all",
+    skipBlanks: false,
+    transpose: false,
+    isSpecial: false,
+};
+var LEGACY_TYPE_TO_OPTIONS = {
+    Transposed: { transpose: true },
+    Formatting: { paste: "formats" },
+    Formula: { paste: "formulas" },
+    Value: { paste: "values" },
+    Link: {},
+};
+var isOperation = function (value) {
+    return value === "add" ||
+        value === "subtract" ||
+        value === "multiply" ||
+        value === "divide";
+};
+var isPasteMode = function (value) {
+    return value === "all" ||
+        value === "values" ||
+        value === "formulas" ||
+        value === "formats";
+};
+/**
+ * Normalize a `PasteSpecialOptions` (or the legacy single-mode string) into
+ * the flags the paste pipelines branch on.
+ */
+export var normalizePasteSpecialOptions = function (input) {
+    var _a;
+    if (!input)
+        return PLAIN_PASTE;
+    var options = typeof input === "string" ? (_a = LEGACY_TYPE_TO_OPTIONS[input]) !== null && _a !== void 0 ? _a : {} : input;
+    var paste = isPasteMode(options.paste) ? options.paste : "all";
+    // Excel greys Operation out under Paste → Formats: a formats paste never
+    // touches destination values, so an operation is dropped here for both
+    // pipelines rather than each guarding separately.
+    var operation = paste !== "formats" && isOperation(options.operation)
+        ? options.operation
+        : undefined;
+    var skipBlanks = Boolean(options.skipBlanks);
+    var transpose = Boolean(options.transpose);
+    return {
+        paste: paste,
+        operation: operation,
+        skipBlanks: skipBlanks,
+        transpose: transpose,
+        isSpecial: paste !== "all" || operation !== undefined || skipBlanks || transpose,
+    };
+};
+/**
+ * Read the Paste Special request the grid stashed on the clipboard event
+ * (`pasteSpecialOptions` JSON wins over the legacy `pasteSpecialType`).
+ */
+export var resolvePasteSpecialOptions = function (clipboardData) {
+    if (!clipboardData)
+        return PLAIN_PASTE;
+    var encoded = clipboardData.getData(PASTE_SPECIAL_OPTIONS_KEY);
+    if (encoded) {
+        try {
+            var parsed = JSON.parse(encoded);
+            if (parsed && typeof parsed === "object") {
+                return normalizePasteSpecialOptions(parsed);
+            }
+        }
+        catch (_a) {
+            // Fall through to the legacy key
+        }
+    }
+    var legacy = clipboardData.getData(PASTE_SPECIAL_TYPE_KEY);
+    return normalizePasteSpecialOptions(legacy || undefined);
+};
+/**
+ * A clipboard cell that carries no value: Paste Special "Skip blanks" leaves
+ * the destination untouched for these. A shared-string reference counts as a
+ * value.
+ */
+export var isBlankClipboardCell = function (cell) {
+    if (isNil(cell))
+        return true;
+    if (!isNil(cell.ss))
+        return false;
+    var ue = getCellUserEnteredValue(cell);
+    if (isNil(ue))
+        return true;
+    return (isNil(getExtendedValueFormula(ue)) &&
+        isNil(getExtendedValueNumber(ue)) &&
+        isNil(getExtendedValueString(ue)) &&
+        isNil(getExtendedValueBool(ue)));
+};
+var classifyOperand = function (cell, locale) {
+    if (isNil(cell))
+        return { kind: "blank" };
+    var ue = getCellUserEnteredValue(cell);
+    var formula = getExtendedValueFormula(ue);
+    if (!isNil(formula)) {
+        var body = formula.trim().replace(/^=/, "");
+        return body ? { kind: "formula", body: body } : { kind: "blank" };
+    }
+    var nv = getExtendedValueNumber(ue);
+    if (!isNil(nv))
+        return { kind: "number", value: nv };
+    var bv = getExtendedValueBool(ue);
+    if (!isNil(bv))
+        return { kind: "number", value: bv ? 1 : 0 };
+    var sv = getExtendedValueString(ue);
+    if (isNil(sv) || sv === "")
+        return { kind: "blank" };
+    if (isNumber(sv, locale)) {
+        return { kind: "number", value: convertToNumber(sv, locale) };
+    }
+    return { kind: "text", value: sv };
+};
+var OPERATOR = {
+    add: "+",
+    subtract: "-",
+    multiply: "*",
+    divide: "/",
+};
+var compute = function (operation, left, right) {
+    switch (operation) {
+        case "add":
+            return left + right;
+        case "subtract":
+            return left - right;
+        case "multiply":
+            return left * right;
+        case "divide":
+            return left / right;
+    }
+};
+var numberLiteral = function (value) {
+    return value < 0 ? "(".concat(String(value), ")") : String(value);
+};
+/** Render an operand as a formula fragment (a formula body is parenthesized). */
+var toFormulaFragment = function (operand) {
+    switch (operand.kind) {
+        case "blank":
+            return "0";
+        case "number":
+            return numberLiteral(operand.value);
+        case "formula":
+            return "(".concat(operand.body, ")");
+        case "text":
+            return "\"".concat(operand.value.replace(/"/g, '""'), "\"");
+    }
+};
+/**
+ * Strip every value facet from a clipboard cell, keeping its formatting so a
+ * "Paste all + operation" still carries the source formats.
+ */
+var withoutValue = function (cell) {
+    if (isNil(cell))
+        return {};
+    var _a = cell, _ue = _a.ue, _ev = _a.ev, _fv = _a.fv, _ss = _a.ss, _userEnteredValue = _a.userEnteredValue, _effectiveValue = _a.effectiveValue, _formattedValue = _a.formattedValue, rest = __rest(_a, ["ue", "ev", "fv", "ss", "userEnteredValue", "effectiveValue", "formattedValue"]);
+    return rest;
+};
+/**
+ * Excel Paste Special → Operation. Combines one clipboard cell with the
+ * destination cell it lands on and returns the cell data to write there:
+ *
+ * - number ⊕ number → the arithmetic result (blank destination counts as 0,
+ *   numeric text is coerced; a non-finite result such as `x/0` is written as
+ *   the formula `=x/0` so the cell shows `#DIV/0!`).
+ * - a formula on either side → a combined formula (`=(dest)+(source)`), the
+ *   source formula already relocated to the destination by the paste.
+ * - blank source → the destination is left as it is (Excel: `d + 0`; the
+ *   classic "paste-add a blank cell" trick still coerces numeric text).
+ * - non-numeric text destination → left as it is.
+ * - non-numeric text source → `=dest+"text"` (Excel's `#VALUE!`).
+ *
+ * `paste: "values"` callers pre-resolve the source to values with
+ * `pickValue`, so the source side is never a formula there.
+ */
+export var applyPasteOperation = function (source, destination, operation, sheetId, locale) {
+    var src = classifyOperand(source, locale);
+    var dst = classifyOperand(destination, locale);
+    var base = withoutValue(source);
+    var keepDestination = function () {
+        var destinationValue = getCellUserEnteredValue(destination);
+        return isNil(destinationValue) ? base : __assign(__assign({}, base), { ue: destinationValue });
+    };
+    if (dst.kind === "text") {
+        return keepDestination();
+    }
+    if (src.kind === "blank") {
+        if (dst.kind === "number" &&
+            (operation === "add" || operation === "subtract")) {
+            // `d + 0` — the destination's numeric text becomes a number.
+            return writeValue(base, dst.value, sheetId, locale);
+        }
+        return keepDestination();
+    }
+    var leftIsNumeric = dst.kind === "blank" || dst.kind === "number";
+    if (leftIsNumeric && src.kind === "number") {
+        var left = dst.kind === "number" ? dst.value : 0;
+        var result = compute(operation, left, src.value);
+        if (Number.isFinite(result)) {
+            return writeValue(base, result, sheetId, locale);
+        }
+    }
+    var formula = "=".concat(toFormulaFragment(dst)).concat(OPERATOR[operation]).concat(toFormulaFragment(src));
+    return writeValue(base, formula, sheetId, locale);
+};
+var writeValue = function (base, value, sheetId, locale) {
+    var _a;
+    var sheetCell = new SheetCell();
+    sheetCell.setLocale(locale);
+    sheetCell.assign(sheetId, undefined, base);
+    sheetCell.setUserEnteredValue(value);
+    var result = (_a = sheetCell.getCellData()) !== null && _a !== void 0 ? _a : __assign({}, base);
+    // Typing a number stamps an inferred `uf.numberFormat`; an unformatted
+    // source (values-only paste) must stay unformatted so the destination's
+    // own format survives the merge.
+    if (!base.uf && result.uf) {
+        var _uf = result.uf, rest = __rest(result, ["uf"]);
+        return rest;
+    }
+    return result;
+};

package/dist/cjs/api/split-text.d.ts

@@ -1,2 +1,14 @@
+import type { SplitTextOptions } from "@rowsncolumns/spreadsheet";
 export declare const splitTextToColumns: (values: (string | null | undefined)[], delimiter?: string) => string[][];
+export type { SplitTextOptions };
+/** Normalized, ascending, de-duplicated positive break positions. */
+export declare const normalizeColumnBreaks: (columnBreaks: number[]) => number[];
+/**
+ * Excel's Text to Columns → Fixed width: cut each cell at the given
+ * character positions. Fields are trimmed like the delimited path (Excel's
+ * General column data format drops the padding spaces fixed-width data is
+ * aligned with). Cells without breaks inside their text still split — the
+ * trailing fields are empty — so the resulting block is rectangular.
+ */
+export declare const splitTextFixedWidth: (values: (string | null | undefined)[], columnBreaks: number[]) => string[][];
 //# sourceMappingURL=split-text.d.ts.map

package/dist/cjs/api/split-text.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"split-text.d.ts","sourceRoot":"","sources":["../../../api/split-text.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,kBAAkB,GAC7B,QAAQ,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,EAAE,EACrC,YAAW,MAAY,KACtB,MAAM,EAAE,EAwBV,CAAC"}
+{"version":3,"file":"split-text.d.ts","sourceRoot":"","sources":["../../../api/split-text.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAIlE,eAAO,MAAM,kBAAkB,GAC7B,QAAQ,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,EAAE,EACrC,YAAW,MAAY,KACtB,MAAM,EAAE,EAwBV,CAAC;AAEF,YAAY,EAAE,gBAAgB,EAAE,CAAC;AAEjC,qEAAqE;AACrE,eAAO,MAAM,qBAAqB,GAAI,cAAc,MAAM,EAAE,KAAG,MAAM,EAG3C,CAAC;AAE3B;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,GAC9B,QAAQ,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,EAAE,EACrC,cAAc,MAAM,EAAE,KACrB,MAAM,EAAE,EAgBV,CAAC"}

package/dist/cjs/api/split-text.js

@@ -1,3 +1,4 @@
+import { __read, __spreadArray, __values } from "tslib";
 import { isNil } from "@rowsncolumns/utils";
 // Split text to columns - takes a single column and returns 2D array
 export var splitTextToColumns = function (values, delimiter) {
@@ -23,3 +24,43 @@ export var splitTextToColumns = function (values, delimiter) {
         return trimmedParts;
     });
 };
+/** Normalized, ascending, de-duplicated positive break positions. */
+export var normalizeColumnBreaks = function (columnBreaks) {
+    return __spreadArray([], __read(new Set(columnBreaks)), false).filter(function (position) { return Number.isInteger(position) && position > 0; })
+        .sort(function (a, b) { return a - b; });
+};
+/**
+ * Excel's Text to Columns → Fixed width: cut each cell at the given
+ * character positions. Fields are trimmed like the delimited path (Excel's
+ * General column data format drops the padding spaces fixed-width data is
+ * aligned with). Cells without breaks inside their text still split — the
+ * trailing fields are empty — so the resulting block is rectangular.
+ */
+export var splitTextFixedWidth = function (values, columnBreaks) {
+    var breaks = normalizeColumnBreaks(columnBreaks);
+    return values.map(function (cell) {
+        var e_1, _a;
+        if (isNil(cell)) {
+            return [""];
+        }
+        var text = String(cell);
+        var parts = [];
+        var start = 0;
+        try {
+            for (var breaks_1 = __values(breaks), breaks_1_1 = breaks_1.next(); !breaks_1_1.done; breaks_1_1 = breaks_1.next()) {
+                var position = breaks_1_1.value;
+                parts.push(text.slice(start, position).trim());
+                start = position;
+            }
+        }
+        catch (e_1_1) { e_1 = { error: e_1_1 }; }
+        finally {
+            try {
+                if (breaks_1_1 && !breaks_1_1.done && (_a = breaks_1.return)) _a.call(breaks_1);
+            }
+            finally { if (e_1) throw e_1.error; }
+        }
+        parts.push(text.slice(start).trim());
+        return parts;
+    });
+};

package/dist/cjs/api/subtotal.d.ts

@@ -0,0 +1,85 @@
+import type { GridRange } from "@rowsncolumns/common-types";
+import { SUBTOTAL_FUNCTIONS, type SubtotalFunction, type SubtotalOptions } from "@rowsncolumns/spreadsheet";
+export { SUBTOTAL_FUNCTIONS };
+export type { SubtotalFunction, SubtotalOptions };
+/**
+ * The `SUBTOTAL(function_num, …)` code each "Use function" entry writes.
+ * Codes 1–11 (not 101–111): the subtotal rows Excel inserts count manually
+ * hidden rows.
+ */
+export declare const SUBTOTAL_FUNCTION_NUMBERS: Record<SubtotalFunction, number>;
+/** Excel's total-row labels: "<group> Total" per group, "Grand Total" at the bottom. */
+export declare const SUBTOTAL_GRAND_TOTAL_LABEL = "Grand Total";
+export declare const subtotalGroupLabel: (groupValue: string) => string;
+/**
+ * Reads a cell of the data range. `getValue` should return the DISPLAYED text
+ * when the host has one (Excel groups and labels on what the cells show —
+ * `1/1/2024 Total`, not `45292 Total`). `getFormula` returns the `=…` text for
+ * a formula cell. `getOutlineLevel` returns a row's current outline level so
+ * "Replace current subtotals" can rebuild the outline from level 0.
+ */
+export type SubtotalReader = {
+    getValue: (rowIndex: number, columnIndex: number) => string | number | boolean | null | undefined;
+    getFormula: (rowIndex: number, columnIndex: number) => string | undefined;
+    getOutlineLevel?: (rowIndex: number) => number | undefined;
+};
+/** One `change-batch` write: a single row segment at final coordinates. */
+export type SubtotalWrite = {
+    rowIndex: number;
+    startColumnIndex: number;
+    values: (string | null)[];
+};
+/**
+ * The plan applies in this order, every index already in FINAL coordinates
+ * (the sheet after all removals and insertions):
+ *   1. `deleteRows` (descending original indexes — existing subtotal rows),
+ *   2. `insertRows` ascending: inserting at final row `r` shifts the not-yet
+ *      final rows below it, so ascending order lands each new row exactly
+ *      where the plan expects it,
+ *   3. `writes` (labels + SUBTOTAL formulas),
+ *   4. `ungroupRows`: one `ungroup-rows` call per entry — the outline reset of
+ *      "Replace current subtotals". Group / ungroup are ±1 steps in both
+ *      engines, so pass `k` lists the surviving data rows that were deeper
+ *      than level `k`; after the passes every row of the range is back at
+ *      level 0 (empty when nothing was outlined or when not replacing), then
+ *   5. `outlineGroups`: one `group-rows` call per entry (Excel's levels — the
+ *      first spans every row above the grand total, the second the detail
+ *      rows of each group, so detail rows end at level 2 and subtotal rows
+ *      at level 1 — the same three-level outline on every re-apply).
+ */
+export type SubtotalPlan = {
+    deleteRows: number[];
+    insertRows: number[];
+    writes: SubtotalWrite[];
+    ungroupRows: number[][];
+    outlineGroups: number[][];
+    /** Number of groups found. */
+    groupCount: number;
+    /** The range after the plan is applied (header row included when present). */
+    resultRange: GridRange;
+};
+/**
+ * Plans Excel's Subtotal command over `options.range`. Consecutive rows with
+ * the same group-column value form a group (Excel does not sort — it expects
+ * the data sorted and totals each run of equal values). Each group gets a
+ * total row right below it holding "<value> Total" in the group column and
+ * `=SUBTOTAL(n, first:last)` over the group's data rows in every aggregate
+ * column; a grand-total row closes the range with `SUBTOTAL` over the whole
+ * data block (SUBTOTAL ignores the nested subtotal rows, like Excel). With
+ * `replaceCurrent` the range's existing outline is cleared too, so a re-apply
+ * yields Excel's fresh detail 2 / subtotal 1 / grand total 0 levels instead
+ * of nesting deeper; without it the new levels stack on the old ones (Excel's
+ * nested subtotals). Returns `undefined` when the range has no data rows.
+ */
+export declare const planSubtotals: (options: SubtotalOptions, reader: SubtotalReader) => SubtotalPlan | undefined;
+/** The state callbacks a plan is applied through — the same in both engines. */
+export type SubtotalPlanExecutor = {
+    onDeleteRow: (sheetId: number, rowIndexes: number[]) => void;
+    onInsertRow: (sheetId: number, referenceRowIndex: number, numRows?: number) => void;
+    onChangeBatch: (sheetId: number, range: GridRange, values: (string | null)[][]) => void;
+    onGroupRows: (sheetId: number, rowIndexes: number[]) => void;
+    onUngroupRows: (sheetId: number, rowIndexes: number[]) => void;
+};
+/** Applies a {@link SubtotalPlan} in its documented order. */
+export declare const applySubtotalPlan: (sheetId: number, plan: SubtotalPlan, executor: SubtotalPlanExecutor) => void;
+//# sourceMappingURL=subtotal.d.ts.map

package/dist/cjs/api/subtotal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subtotal.d.ts","sourceRoot":"","sources":["../../../api/subtotal.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAC;AAC5D,OAAO,EACL,kBAAkB,EAClB,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACrB,MAAM,2BAA2B,CAAC;AAGnC,OAAO,EAAE,kBAAkB,EAAE,CAAC;AAC9B,YAAY,EAAE,gBAAgB,EAAE,eAAe,EAAE,CAAC;AAElD;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,EAAE,MAAM,CAAC,gBAAgB,EAAE,MAAM,CAYtE,CAAC;AAEF,wFAAwF;AACxF,eAAO,MAAM,0BAA0B,gBAAgB,CAAC;AACxD,eAAO,MAAM,kBAAkB,GAAI,YAAY,MAAM,WACP,CAAC;AAE/C;;;;;;GAMG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,QAAQ,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,KAAK,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,SAAS,CAAC;IAClG,UAAU,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC;IAC1E,eAAe,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC;CAC5D,CAAC;AAEF,2EAA2E;AAC3E,MAAM,MAAM,aAAa,GAAG;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,gBAAgB,EAAE,MAAM,CAAC;IACzB,MAAM,EAAE,CAAC,MAAM,GAAG,IAAI,CAAC,EAAE,CAAC;CAC3B,CAAC;AAEF;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,MAAM,EAAE,aAAa,EAAE,CAAC;IACxB,WAAW,EAAE,MAAM,EAAE,EAAE,CAAC;IACxB,aAAa,EAAE,MAAM,EAAE,EAAE,CAAC;IAC1B,8BAA8B;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,8EAA8E;IAC9E,WAAW,EAAE,SAAS,CAAC;CACxB,CAAC;AAcF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,aAAa,GACxB,SAAS,eAAe,EACxB,QAAQ,cAAc,KACrB,YAAY,GAAG,SAyHjB,CAAC;AAEF,gFAAgF;AAChF,MAAM,MAAM,oBAAoB,GAAG;IACjC,WAAW,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,KAAK,IAAI,CAAC;IAC7D,WAAW,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,iBAAiB,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IACpF,aAAa,EAAE,CACb,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,SAAS,EAChB,MAAM,EAAE,CAAC,MAAM,GAAG,IAAI,CAAC,EAAE,EAAE,KACxB,IAAI,CAAC;IACV,WAAW,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,KAAK,IAAI,CAAC;IAC7D,aAAa,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,KAAK,IAAI,CAAC;CAChE,CAAC;AAEF,8DAA8D;AAC9D,eAAO,MAAM,iBAAiB,GAC5B,SAAS,MAAM,EACf,MAAM,YAAY,EAClB,UAAU,oBAAoB,SAwB/B,CAAC"}

package/dist/cjs/api/subtotal.js

@@ -0,0 +1,250 @@
+import { __assign, __read, __spreadArray, __values } from "tslib";
+import { SUBTOTAL_FUNCTIONS, } from "@rowsncolumns/spreadsheet";
+import { number2Alpha } from "@rowsncolumns/utils";
+export { SUBTOTAL_FUNCTIONS };
+/**
+ * The `SUBTOTAL(function_num, …)` code each "Use function" entry writes.
+ * Codes 1–11 (not 101–111): the subtotal rows Excel inserts count manually
+ * hidden rows.
+ */
+export var SUBTOTAL_FUNCTION_NUMBERS = {
+    AVERAGE: 1,
+    COUNT: 2,
+    COUNTA: 3,
+    MAX: 4,
+    MIN: 5,
+    PRODUCT: 6,
+    STDEV: 7,
+    STDEVP: 8,
+    SUM: 9,
+    VAR: 10,
+    VARP: 11,
+};
+/** Excel's total-row labels: "<group> Total" per group, "Grand Total" at the bottom. */
+export var SUBTOTAL_GRAND_TOTAL_LABEL = "Grand Total";
+export var subtotalGroupLabel = function (groupValue) {
+    return groupValue ? "".concat(groupValue, " Total") : "Total";
+};
+var isSubtotalFormula = function (formula) {
+    return !!formula && /^=\s*(_xlfn\.)?SUBTOTAL\s*\(/i.test(formula);
+};
+/** What a cell shows: booleans display as `TRUE`/`FALSE` (Excel's label is "TRUE Total"). */
+var displayValue = function (value) {
+    if (value === null || value === undefined)
+        return "";
+    if (typeof value === "boolean")
+        return value ? "TRUE" : "FALSE";
+    return String(value);
+};
+var columnLetters = function (columnIndex) { return number2Alpha(columnIndex - 1); };
+/**
+ * Plans Excel's Subtotal command over `options.range`. Consecutive rows with
+ * the same group-column value form a group (Excel does not sort — it expects
+ * the data sorted and totals each run of equal values). Each group gets a
+ * total row right below it holding "<value> Total" in the group column and
+ * `=SUBTOTAL(n, first:last)` over the group's data rows in every aggregate
+ * column; a grand-total row closes the range with `SUBTOTAL` over the whole
+ * data block (SUBTOTAL ignores the nested subtotal rows, like Excel). With
+ * `replaceCurrent` the range's existing outline is cleared too, so a re-apply
+ * yields Excel's fresh detail 2 / subtotal 1 / grand total 0 levels instead
+ * of nesting deeper; without it the new levels stack on the old ones (Excel's
+ * nested subtotals). Returns `undefined` when the range has no data rows.
+ */
+export var planSubtotals = function (options, reader) {
+    var e_1, _a, e_2, _b;
+    var _c, _d, _e;
+    var range = options.range, groupByColumnIndex = options.groupByColumnIndex, aggregateColumnIndices = options.aggregateColumnIndices, _f = options.fn, fn = _f === void 0 ? "SUM" : _f, _g = options.hasHeader, hasHeader = _g === void 0 ? true : _g, _h = options.replaceCurrent, replaceCurrent = _h === void 0 ? true : _h;
+    var functionNumber = SUBTOTAL_FUNCTION_NUMBERS[fn];
+    var aggregates = __spreadArray([], __read(new Set(aggregateColumnIndices)), false).filter(function (columnIndex) {
+        return columnIndex >= range.startColumnIndex &&
+            columnIndex <= range.endColumnIndex;
+    })
+        .sort(function (a, b) { return a - b; });
+    var firstDataRow = hasHeader ? range.startRowIndex + 1 : range.startRowIndex;
+    if (firstDataRow > range.endRowIndex)
+        return undefined;
+    // Existing subtotal rows (any aggregate column, or the group column's
+    // "… Total" label next to a SUBTOTAL anywhere in the range) are dropped
+    // first when replacing.
+    var deleteRows = [];
+    var dataRows = [];
+    for (var rowIndex = firstDataRow; rowIndex <= range.endRowIndex; rowIndex++) {
+        var isTotalRow = false;
+        if (replaceCurrent) {
+            for (var columnIndex = range.startColumnIndex; columnIndex <= range.endColumnIndex && !isTotalRow; columnIndex++) {
+                isTotalRow = isSubtotalFormula(reader.getFormula(rowIndex, columnIndex));
+            }
+        }
+        if (isTotalRow)
+            deleteRows.push(rowIndex);
+        else
+            dataRows.push(rowIndex);
+    }
+    if (dataRows.length === 0)
+        return undefined;
+    deleteRows.sort(function (a, b) { return b - a; });
+    // Runs of equal group values over the surviving data rows.
+    var groups = [];
+    try {
+        for (var dataRows_1 = __values(dataRows), dataRows_1_1 = dataRows_1.next(); !dataRows_1_1.done; dataRows_1_1 = dataRows_1.next()) {
+            var rowIndex = dataRows_1_1.value;
+            var label = displayValue(reader.getValue(rowIndex, groupByColumnIndex));
+            var last = groups[groups.length - 1];
+            if (last && last.label === label)
+                last.size++;
+            else
+                groups.push({ label: label, size: 1 });
+        }
+    }
+    catch (e_1_1) { e_1 = { error: e_1_1 }; }
+    finally {
+        try {
+            if (dataRows_1_1 && !dataRows_1_1.done && (_a = dataRows_1.return)) _a.call(dataRows_1);
+        }
+        finally { if (e_1) throw e_1.error; }
+    }
+    // Lay out the final rows: data rows are compacted (deleted rows gone),
+    // then each group is followed by its total row.
+    var insertRows = [];
+    var writes = [];
+    var detailRows = [];
+    var startColumn = Math.min.apply(Math, __spreadArray([groupByColumnIndex], __read(aggregates), false));
+    var endColumn = Math.max.apply(Math, __spreadArray([groupByColumnIndex], __read(aggregates), false));
+    var totalRowValues = function (label, firstRow, lastRow) {
+        var values = [];
+        for (var columnIndex = startColumn; columnIndex <= endColumn; columnIndex++) {
+            if (columnIndex === groupByColumnIndex) {
+                values.push(label);
+            }
+            else if (aggregates.includes(columnIndex)) {
+                var letters = columnLetters(columnIndex);
+                values.push("=SUBTOTAL(".concat(functionNumber, ",").concat(letters).concat(firstRow, ":").concat(letters).concat(lastRow, ")"));
+            }
+            else {
+                values.push(null);
+            }
+        }
+        return values;
+    };
+    // "Replace current subtotals": the surviving data rows carry the previous
+    // outline (detail rows at 2, or deeper after repeated applies) into their
+    // final positions — the inserted total rows arrive at level 0 — so record
+    // how many ungroup steps each needs before the fresh levels go on.
+    var ungroupRows = [];
+    var dataRowCursor = 0;
+    var cursor = firstDataRow;
+    try {
+        for (var groups_1 = __values(groups), groups_1_1 = groups_1.next(); !groups_1_1.done; groups_1_1 = groups_1.next()) {
+            var group = groups_1_1.value;
+            var groupStart = cursor;
+            for (var i = 0; i < group.size; i++) {
+                var originalRow = dataRows[dataRowCursor++];
+                var level = replaceCurrent ? ((_d = (_c = reader.getOutlineLevel) === null || _c === void 0 ? void 0 : _c.call(reader, originalRow)) !== null && _d !== void 0 ? _d : 0) : 0;
+                for (var pass = 0; pass < level; pass++) {
+                    ((_e = ungroupRows[pass]) !== null && _e !== void 0 ? _e : (ungroupRows[pass] = [])).push(cursor);
+                }
+                detailRows.push(cursor++);
+            }
+            var groupEnd = cursor - 1;
+            insertRows.push(cursor);
+            writes.push({
+                rowIndex: cursor,
+                startColumnIndex: startColumn,
+                values: totalRowValues(subtotalGroupLabel(group.label), groupStart, groupEnd),
+            });
+            cursor++;
+        }
+    }
+    catch (e_2_1) { e_2 = { error: e_2_1 }; }
+    finally {
+        try {
+            if (groups_1_1 && !groups_1_1.done && (_b = groups_1.return)) _b.call(groups_1);
+        }
+        finally { if (e_2) throw e_2.error; }
+    }
+    var lastRowBeforeGrand = cursor - 1;
+    insertRows.push(cursor);
+    writes.push({
+        rowIndex: cursor,
+        startColumnIndex: startColumn,
+        values: totalRowValues(SUBTOTAL_GRAND_TOTAL_LABEL, firstDataRow, lastRowBeforeGrand),
+    });
+    var level1 = [];
+    for (var rowIndex = firstDataRow; rowIndex <= lastRowBeforeGrand; rowIndex++) {
+        level1.push(rowIndex);
+    }
+    return {
+        deleteRows: deleteRows,
+        insertRows: insertRows,
+        writes: writes,
+        ungroupRows: ungroupRows,
+        outlineGroups: [level1, detailRows],
+        groupCount: groups.length,
+        resultRange: __assign(__assign({}, range), { endRowIndex: cursor }),
+    };
+};
+/** Applies a {@link SubtotalPlan} in its documented order. */
+export var applySubtotalPlan = function (sheetId, plan, executor) {
+    var e_3, _a, e_4, _b, e_5, _c, e_6, _d;
+    if (plan.deleteRows.length)
+        executor.onDeleteRow(sheetId, plan.deleteRows);
+    try {
+        for (var _e = __values(plan.insertRows), _f = _e.next(); !_f.done; _f = _e.next()) {
+            var rowIndex = _f.value;
+            executor.onInsertRow(sheetId, rowIndex, 1);
+        }
+    }
+    catch (e_3_1) { e_3 = { error: e_3_1 }; }
+    finally {
+        try {
+            if (_f && !_f.done && (_a = _e.return)) _a.call(_e);
+        }
+        finally { if (e_3) throw e_3.error; }
+    }
+    try {
+        for (var _g = __values(plan.writes), _h = _g.next(); !_h.done; _h = _g.next()) {
+            var write = _h.value;
+            executor.onChangeBatch(sheetId, {
+                startRowIndex: write.rowIndex,
+                endRowIndex: write.rowIndex,
+                startColumnIndex: write.startColumnIndex,
+                endColumnIndex: write.startColumnIndex + write.values.length - 1,
+            }, [write.values]);
+        }
+    }
+    catch (e_4_1) { e_4 = { error: e_4_1 }; }
+    finally {
+        try {
+            if (_h && !_h.done && (_b = _g.return)) _b.call(_g);
+        }
+        finally { if (e_4) throw e_4.error; }
+    }
+    try {
+        for (var _j = __values(plan.ungroupRows), _k = _j.next(); !_k.done; _k = _j.next()) {
+            var rows = _k.value;
+            if (rows.length)
+                executor.onUngroupRows(sheetId, rows);
+        }
+    }
+    catch (e_5_1) { e_5 = { error: e_5_1 }; }
+    finally {
+        try {
+            if (_k && !_k.done && (_c = _j.return)) _c.call(_j);
+        }
+        finally { if (e_5) throw e_5.error; }
+    }
+    try {
+        for (var _l = __values(plan.outlineGroups), _m = _l.next(); !_m.done; _m = _l.next()) {
+            var rows = _m.value;
+            if (rows.length)
+                executor.onGroupRows(sheetId, rows);
+        }
+    }
+    catch (e_6_1) { e_6 = { error: e_6_1 }; }
+    finally {
+        try {
+            if (_m && !_m.done && (_d = _l.return)) _d.call(_l);
+        }
+        finally { if (e_6) throw e_6.error; }
+    }
+};

package/dist/cjs/commands.d.ts

@@ -53,6 +53,10 @@ export type Command = {
         value: string | null;
         format?: CellFormat | null;
         hyperlink?: string | null;
+        /** Paste Special "Skip blanks": leave the destination untouched (value, format,
+         *  hyperlink) — unlike `null`, which clears it. The other fields are then only a
+         *  fallback for an engine build predating `skip`. */
+        skip?: boolean;
     } | null)[][];
     /** When the clipboard came from a CUT, the source range to clear after the paste lands. */
     cut?: {
@@ -75,12 +79,21 @@ export type Command = {
     activeCell: CellInterface;
     selections: SelectionArea<SelectionAttributes>[];
     columnIndices?: number[];
+    hasHeader?: boolean;
 } | {
     command: "split-text-to-columns";
     sheetId: number;
     activeCell: CellInterface;
     selections: SelectionArea<SelectionAttributes>[];
     delimiter: string;
+    /** Fixed-width mode: character positions of the column breaks (wins over `delimiter`). */
+    columnBreaks?: number[];
+} | {
+    command: "goal-seek";
+    sheetId: number;
+    setCell: CellInterface;
+    targetValue: number;
+    changingCell: CellInterface;
 } | {
     command: "find-replace";
     ranges: SheetRange[];