@rowsncolumns/spreadsheet-state 28.0.73 → 28.0.75

package/dist/esm/api/goal-seek.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Excel's Data → What-If Analysis → Goal Seek solver.
+ *
+ * Excel's defaults are 100 iterations and a change-tolerance of 0.001 (its
+ * Calculation options → "Maximum Iterations" / "Maximum Change"). The
+ * search is a secant method — Excel's own is a secant/Newton hybrid — with
+ * bisection whenever a sign change has been bracketed and the secant step
+ * would leave the bracket, so a monotone target converges in a handful of
+ * evaluations while a badly scaled one still narrows a bracket.
+ *
+ * `evaluate(trial)` returns the set cell's value with the changing cell at
+ * `trial`; `undefined` means the trial produced an error (`#DIV/0!`, text…),
+ * which the solver treats as "step somewhere else".
+ */
+import type { GoalSeekResult, GoalSeekStatus } from "@rowsncolumns/spreadsheet";
+export declare const GOAL_SEEK_MAX_ITERATIONS = 100;
+export declare const GOAL_SEEK_TOLERANCE = 0.001;
+export type GoalSeekEvaluate = (trial: number) => Promise<number | undefined>;
+export type { GoalSeekResult, GoalSeekStatus };
+export type GoalSeekOptions = {
+    evaluate: GoalSeekEvaluate;
+    targetValue: number;
+    /** Starting trial — the changing cell's current value (0 when blank). */
+    initialValue?: number;
+    maxIterations?: number;
+    tolerance?: number;
+};
+export declare const goalSeek: ({ evaluate, targetValue, initialValue, maxIterations, tolerance, }: GoalSeekOptions) => Promise<GoalSeekResult>;
+//# sourceMappingURL=goal-seek.d.ts.map

package/dist/esm/api/goal-seek.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"goal-seek.d.ts","sourceRoot":"","sources":["../../../api/goal-seek.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAEhF,eAAO,MAAM,wBAAwB,MAAM,CAAC;AAC5C,eAAO,MAAM,mBAAmB,QAAQ,CAAC;AAEzC,MAAM,MAAM,gBAAgB,GAAG,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;AAE9E,YAAY,EAAE,cAAc,EAAE,cAAc,EAAE,CAAC;AAE/C,MAAM,MAAM,eAAe,GAAG;IAC5B,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,WAAW,EAAE,MAAM,CAAC;IACpB,yEAAyE;IACzE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAKF,eAAO,MAAM,QAAQ,GAAU,oEAM5B,eAAe,KAAG,OAAO,CAAC,cAAc,CAqG1C,CAAC"}

package/dist/esm/api/goal-seek.js

@@ -0,0 +1,108 @@
+export const GOAL_SEEK_MAX_ITERATIONS = 100;
+export const GOAL_SEEK_TOLERANCE = 0.001;
+const isUsable = (value) => typeof value === "number" && Number.isFinite(value);
+export const goalSeek = async ({ evaluate, targetValue, initialValue = 0, maxIterations = GOAL_SEEK_MAX_ITERATIONS, tolerance = GOAL_SEEK_TOLERANCE, }) => {
+    let iterations = 0;
+    let best = {
+        value: initialValue,
+        currentValue: undefined,
+        residual: Number.POSITIVE_INFINITY,
+    };
+    // Residual f(x) = set(x) − target; records the best trial as a side effect.
+    const residualAt = async (trial) => {
+        iterations++;
+        const current = await evaluate(trial);
+        if (!isUsable(current))
+            return undefined;
+        const residual = current - targetValue;
+        if (Math.abs(residual) < best.residual) {
+            best = { value: trial, currentValue: current, residual: Math.abs(residual) };
+        }
+        return residual;
+    };
+    const finish = (status) => ({
+        status,
+        value: best.value,
+        currentValue: best.currentValue,
+        targetValue,
+        iterations,
+    });
+    // Bracket of a sign change, once seen: bisection fallback + secant clamp.
+    let negative;
+    let positive;
+    const bracket = (x, f) => {
+        if (f < 0)
+            negative = x;
+        else
+            positive = x;
+    };
+    let x0 = initialValue;
+    let f0 = await residualAt(x0);
+    // The current value may itself be an error (=1/A1 with A1 blank): nudge off it.
+    let nudges = 0;
+    while (f0 === undefined && iterations < maxIterations && nudges < 8) {
+        x0 = x0 === 0 ? 1 : x0 * 2;
+        f0 = await residualAt(x0);
+        nudges++;
+    }
+    if (f0 === undefined)
+        return finish("not-found");
+    if (Math.abs(f0) <= tolerance)
+        return finish("found");
+    bracket(x0, f0);
+    // Excel perturbs the starting value by ~1% to get a first slope.
+    let x1 = x0 === 0 ? 0.01 : x0 * 1.01;
+    let shrinks = 0;
+    let backoffs = 0;
+    while (iterations < maxIterations) {
+        const f1 = await residualAt(x1);
+        if (f1 === undefined) {
+            // Errored trial: pull it halfway back toward the last good point.
+            if (++shrinks > 16)
+                return finish("not-found");
+            x1 = x0 + (x1 - x0) / 2;
+            continue;
+        }
+        shrinks = 0;
+        if (Math.abs(f1) <= tolerance)
+            return finish("found");
+        bracket(x1, f1);
+        // A secant step that made things worse with no sign change in sight is
+        // heading away from the root (a flat or curving function such as =1/A1):
+        // back off — half the step, in the opposite direction — instead of
+        // following it to infinity. The bracketed case below never needs this.
+        if ((negative === undefined || positive === undefined) &&
+            Math.abs(f1) > Math.abs(f0)) {
+            if (++backoffs > 24)
+                return finish("not-found");
+            x1 = x0 - (x1 - x0) / 2;
+            continue;
+        }
+        backoffs = 0;
+        let x2;
+        const slope = f1 - f0;
+        if (slope === 0 || !Number.isFinite(slope)) {
+            // Flat: widen the step in the same direction to find any change.
+            x2 = x1 + (x1 - x0 || 0.01) * 2;
+        }
+        else {
+            x2 = x1 - (f1 * (x1 - x0)) / slope;
+        }
+        if (negative !== undefined && positive !== undefined) {
+            const lo = Math.min(negative, positive);
+            const hi = Math.max(negative, positive);
+            if (!Number.isFinite(x2) || x2 <= lo || x2 >= hi) {
+                x2 = (lo + hi) / 2;
+            }
+        }
+        else if (!Number.isFinite(x2)) {
+            return finish("not-found");
+        }
+        if (x2 === x1)
+            return finish(Math.abs(f1) <= tolerance ? "found" : "not-found");
+        x0 = x1;
+        f0 = f1;
+        x1 = x2;
+    }
+    return finish("not-found");
+};

package/dist/esm/api/immer-utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"immer-utils.d.ts","sourceRoot":"","sources":["../../../api/immer-utils.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"immer-utils.d.ts","sourceRoot":"","sources":["../../../api/immer-utils.ts"],"names":[],"mappings":"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"}

package/dist/esm/api/immer-utils.js

@@ -47,8 +47,7 @@ const isGenericNumberFormatType = (type) => !type || type === "NUMBER" || type =
  * Date-family types — when the derived (resolved) type is one of these
  * and the precedent's type is also in this set, we preserve the
  * precedent's exact custom pattern instead of synthesizing a locale
- * default. Mirrors Excel's behaviour for date-arithmetic functions
- * (EDATE, EOMONTH, …) where `=EDATE(A1, 1)` keeps A1's custom pattern.
+ * default (`=DATE(YEAR(A1), MONTH(A1), 1)` keeps A1's custom pattern).
  */
 const isDateFamilyType = (type) => type === "DATE" || type === "TIME" || type === "DATE_TIME";
 const customNumberFormatMap = {
@@ -67,6 +66,7 @@ const formatDerivationRules = {
     UNIQUE: { type: "fixed_index", index: 0 },
     TAKE: { type: "fixed_index", index: 0 },
     DROP: { type: "fixed_index", index: 0 },
+    TRIMRANGE: { type: "fixed_index", index: 0 },
     EXPAND: { type: "fixed_index", index: 0 },
     TOCOL: { type: "fixed_index", index: 0 },
     TOROW: { type: "fixed_index", index: 0 },
@@ -160,18 +160,21 @@ const functionReturnTypes = {
     NETWORKDAYS: "NUMBER",
     "NETWORKDAYS.INTL": "NUMBER",
     DAYS360: "NUMBER",
+    // The date-arithmetic functions return date serials, but Excel does
+    // NOT auto-format them: `=EDATE(DATE(2026,1,31),1)` shows 46081 in a
+    // General cell until the user formats it (rowsncolumns/spreadsheet#642
+    // B-09). NUMBER — like DATEVALUE — rather than absent, so a nested
+    // DATE()/TODAY() argument cannot promote the result to a date (the
+    // outermost function decides, as in `=YEAR(TODAY())`).
+    EDATE: "NUMBER",
+    EOMONTH: "NUMBER",
+    WORKDAY: "NUMBER",
+    "WORKDAY.INTL": "NUMBER",
     // ─── Date/time — date producers (must render as DATE/TIME/DATE_TIME) ─
     NOW: "DATE_TIME",
     TODAY: "DATE",
     DATE: "DATE",
     TIME: "TIME",
-    EDATE: "DATE",
-    EOMONTH: "DATE",
-    // WORKDAY returns a date serial number — must render as DATE, not
-    // raw NUMBER (was a bug: cells showed e.g. "45292" instead of the
-    // calendar date).
-    WORKDAY: "DATE",
-    "WORKDAY.INTL": "DATE",
     // ─── Aggregation / rounding (return NUMBER; CURRENCY precedent
     //     preserved via the "expectedOutputType === NUMBER + numFormat
     //     CURRENCY → keep numFormat" branch) ──────────────────────────
@@ -318,7 +321,10 @@ const currencyDecimalAdjustmentFunctions = new Set([
     "QUOTIENT",
 ]);
 // Get all function names from formula
-const functionRegex = /([A-Za-z0-9_]+)\s*\(/g;
+// Function names may be dotted (`WORKDAY.INTL`, `PERCENTILE.INC`, `FORECAST.ETS`); without the
+// `.` the match stopped at the suffix (`INTL(`) and the dotted keys of `functionReturnTypes` /
+// `formatDerivationRules` never applied.
+const functionRegex = /([A-Za-z0-9_.]+)\s*\(/g;
 export const getFunctionNamesFromFormula = (formula) => {
     let match;
     const matches = [];
@@ -499,7 +505,7 @@ resolvePrecedentNumberFormat) => {
     effectivePrecedents = filterPrecedentsByBounds(effectivePrecedents, directBounds);
     const upperFormula = formula?.trim().toUpperCase();
     if (upperFormula) {
-        const functionNameMatch = upperFormula.match(/^=([A-Z0-9_]+)\(/);
+        const functionNameMatch = upperFormula.match(/^=([A-Z0-9_.]+)\(/);
         topLevelFunctionName = functionNameMatch ? functionNameMatch[1] : undefined;
         const rule = topLevelFunctionName
             ? formatDerivationRules[topLevelFunctionName]
@@ -672,10 +678,10 @@ resolvePrecedentNumberFormat) => {
         // Date/time types need a concrete pattern — without one the renderer
         // falls back to "General" and shows the serial number (the
         // =TODAY() bug). When the precedent itself is a date-family format
-        // with a pattern, inherit that pattern (e.g. `=EDATE(A1, 1)` keeps
-        // A1's custom `yyyy-mm-dd` instead of falling back to the locale
-        // default). Otherwise mirror the format toolbar's default for the
-        // type.
+        // with a pattern, inherit that pattern (e.g. `=DATE(YEAR(A1),
+        // MONTH(A1), 1)` keeps A1's custom `yyyy-mm-dd` instead of falling
+        // back to the locale default). Otherwise mirror the format toolbar's
+        // default for the type.
         if (isDateFamilyType(resolvedNumberFormat.type) &&
             isDateFamilyType(numFormat?.type) &&
             numFormat?.pattern) {

package/dist/esm/api/intl.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"intl.d.ts","sourceRoot":"","sources":["../../../api/intl.ts"],"names":[],"mappings":"AA0BA;;GAEG;AACH,eAAO,MAAM,eAAe,GAAI,OAAO,MAAM,EAAE,gBAAc,WAK5D,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,mBAAmB,GAAI,SAAS,MAAM;;;;;CA2ClD,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,WAAW,GAAI,SAAS,MAAM;eA1E5B,MAAM;YAAU,OAAO;YAAU,OAAO;iBAAe,OAAO;CAqH5E,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,kBAAkB,GAAI,SAAS,MAAM;UAtHxC,MAAM;YAAU,OAAO;YAAU,OAAO;CAkJjD,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,eAAe,GAAI,SAAS,MAAM;aA/JlC,MAAM;eAAa,MAAM;WAAS,MAAM;aAgMpD,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,iBAAiB,GAAI,SAAS,MAAM,wBAkBhD,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,uBAAuB,GAAI,MAAM,MAAM,YAuBnD,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,mBAAmB,GAAI,aAAa,MAAM,gBA0BtD,CAAC"}
+{"version":3,"file":"intl.d.ts","sourceRoot":"","sources":["../../../api/intl.ts"],"names":[],"mappings":"AA0BA;;GAEG;AACH,eAAO,MAAM,eAAe,GAAI,OAAO,MAAM,EAAE,gBAAc,WAK5D,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,mBAAmB,GAAI,SAAS,MAAM;WAlCxC,MAAM;aAAW,MAAM;eAAa,MAAM;iBAAe,MAAM;CA6EzE,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,WAAW,GAAI,SAAS,MAAM;eA1E5B,MAAM;YAAU,OAAO;YAAU,OAAO;iBAAe,OAAO;CAqH5E,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,kBAAkB,GAAI,SAAS,MAAM;UAtHxC,MAAM;YAAU,OAAO;YAAU,OAAO;CAkJjD,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,eAAe,GAAI,SAAS,MAAM;aA/JlC,MAAM;eAAa,MAAM;WAAS,MAAM;aAgMpD,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,iBAAiB,GAAI,SAAS,MAAM,wBAkBhD,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,uBAAuB,GAAI,MAAM,MAAM,YAuBnD,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,mBAAmB,GAAI,aAAa,MAAM,gBA0BtD,CAAC"}

package/dist/esm/api/paint-format.d.ts

@@ -0,0 +1,55 @@
+import type { CellFormat, CellInterface, GridRange } from "@rowsncolumns/common-types";
+/**
+ * Format-painter pattern shared by both engines: the captured 2-D format grid plus the
+ * source block's merge configuration, re-based to the block's top-left so it can be tiled
+ * onto any target (Google Sheets copies merges with the format; Excel's painter does too).
+ */
+export type PaintPattern = {
+    formats: (CellFormat | null | undefined)[][];
+    /** Merges fully inside the source block, as 0-based offsets from its top-left. */
+    merges: GridRange[];
+    /** Source block size — the tiling period. */
+    rows: number;
+    cols: number;
+};
+/**
+ * The merges the painter carries from a source block: every merge that lies FULLY inside
+ * `source`, re-based to 0-based offsets from the block's top-left. A merge reaching outside the
+ * block is not part of its pattern (Sheets/Excel behave the same — the painter copies the look of
+ * the selected cells, not of the cells around them).
+ */
+export declare const collectPaintMerges: (merges: GridRange[] | null | undefined, source: GridRange) => GridRange[];
+/**
+ * The block the painter captures when it is armed WITHOUT a drag selection. A plain click on a
+ * merged cell selects the whole merged area in Excel and Sheets, but the grid reports it as the
+ * anchor active cell plus an empty selection list — so the source is the merge containing the
+ * active cell when there is one, otherwise the single cell.
+ */
+export declare const paintSourceForActiveCell: (merges: GridRange[] | null | undefined, activeCell: CellInterface) => GridRange;
+/**
+ * Excel stores a merged area's style on every constituent cell, and the grid paints a merge with
+ * its anchor's format. Copy the anchor's captured format over the covered cells of every merge in
+ * the pattern (in place) so the painted target carries the fill on all of them — an unmerge at the
+ * target, or a partial tile that drops the merge, still leaves every cell looking as it did.
+ */
+export declare const spreadMergeAnchorFormats: (formats: (CellFormat | null | undefined)[][], relativeMerges: GridRange[]) => void;
+/**
+ * Tile a pattern's relative merges across `target` with the pattern's period (`rows` × `cols`),
+ * the same way the format grid itself is tiled by the formatting applier. A merge that a partial
+ * trailing tile would push past the target's edge is dropped — the painter never creates a merge
+ * that the user did not drag over.
+ */
+export declare const tilePaintMerges: (relativeMerges: GridRange[], rows: number, cols: number, target: GridRange) => GridRange[];
+/**
+ * The banded (table stripe / alternating-colour) format the grid paints under a cell, looked up
+ * in the map `getBandedCells` builds for a sheet.
+ */
+export declare const getBandedCellFormat: (bandedCells: Map<string, CellFormat> | undefined | null, rowIndex: number, columnIndex: number) => CellFormat | undefined;
+/**
+ * Layer a cell's explicit format over the banded format the grid would paint beneath it, so the
+ * captured pattern carries the VISIBLE look (Sheets copies the alternating colours as static cell
+ * fills — it does not create a table or banding at the target). Explicit keys win; an explicit
+ * `undefined` never clobbers a banded value.
+ */
+export declare const layerBandedFormat: (explicit: CellFormat | null | undefined, banded: CellFormat | undefined) => CellFormat | null | undefined;
+//# sourceMappingURL=paint-format.d.ts.map

package/dist/esm/api/paint-format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paint-format.d.ts","sourceRoot":"","sources":["../../../api/paint-format.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,UAAU,EACV,aAAa,EACb,SAAS,EACV,MAAM,4BAA4B,CAAC;AAGpC;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,OAAO,EAAE,CAAC,UAAU,GAAG,IAAI,GAAG,SAAS,CAAC,EAAE,EAAE,CAAC;IAC7C,kFAAkF;IAClF,MAAM,EAAE,SAAS,EAAE,CAAC;IACpB,6CAA6C;IAC7C,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAQF;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,GAC7B,QAAQ,SAAS,EAAE,GAAG,IAAI,GAAG,SAAS,EACtC,QAAQ,SAAS,KAChB,SAAS,EAaX,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,GACnC,QAAQ,SAAS,EAAE,GAAG,IAAI,GAAG,SAAS,EACtC,YAAY,aAAa,KACxB,SAkBF,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,GACnC,SAAS,CAAC,UAAU,GAAG,IAAI,GAAG,SAAS,CAAC,EAAE,EAAE,EAC5C,gBAAgB,SAAS,EAAE,KAC1B,IAYF,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,eAAe,GAC1B,gBAAgB,SAAS,EAAE,EAC3B,MAAM,MAAM,EACZ,MAAM,MAAM,EACZ,QAAQ,SAAS,KAChB,SAAS,EAqBX,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,mBAAmB,GAC9B,aAAa,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,GAAG,SAAS,GAAG,IAAI,EACvD,UAAU,MAAM,EAChB,aAAa,MAAM,KAClB,UAAU,GAAG,SACyC,CAAC;AAE1D;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,GAC5B,UAAU,UAAU,GAAG,IAAI,GAAG,SAAS,EACvC,QAAQ,UAAU,GAAG,SAAS,KAC7B,UAAU,GAAG,IAAI,GAAG,SAWtB,CAAC"}

package/dist/esm/api/paint-format.js

@@ -0,0 +1,122 @@
+import { cellIdentifier, isCellWithinBounds } from "@rowsncolumns/grid";
+const rangeContains = (outer, inner) => inner.startRowIndex >= outer.startRowIndex &&
+    inner.endRowIndex <= outer.endRowIndex &&
+    inner.startColumnIndex >= outer.startColumnIndex &&
+    inner.endColumnIndex <= outer.endColumnIndex;
+/**
+ * The merges the painter carries from a source block: every merge that lies FULLY inside
+ * `source`, re-based to 0-based offsets from the block's top-left. A merge reaching outside the
+ * block is not part of its pattern (Sheets/Excel behave the same — the painter copies the look of
+ * the selected cells, not of the cells around them).
+ */
+export const collectPaintMerges = (merges, source) => {
+    if (!merges?.length)
+        return [];
+    const out = [];
+    for (const merge of merges) {
+        if (!rangeContains(source, merge))
+            continue;
+        out.push({
+            startRowIndex: merge.startRowIndex - source.startRowIndex,
+            endRowIndex: merge.endRowIndex - source.startRowIndex,
+            startColumnIndex: merge.startColumnIndex - source.startColumnIndex,
+            endColumnIndex: merge.endColumnIndex - source.startColumnIndex,
+        });
+    }
+    return out;
+};
+/**
+ * The block the painter captures when it is armed WITHOUT a drag selection. A plain click on a
+ * merged cell selects the whole merged area in Excel and Sheets, but the grid reports it as the
+ * anchor active cell plus an empty selection list — so the source is the merge containing the
+ * active cell when there is one, otherwise the single cell.
+ */
+export const paintSourceForActiveCell = (merges, activeCell) => {
+    const merge = merges?.find((candidate) => isCellWithinBounds(activeCell, candidate));
+    if (merge) {
+        return {
+            startRowIndex: merge.startRowIndex,
+            endRowIndex: merge.endRowIndex,
+            startColumnIndex: merge.startColumnIndex,
+            endColumnIndex: merge.endColumnIndex,
+        };
+    }
+    return {
+        startRowIndex: activeCell.rowIndex,
+        endRowIndex: activeCell.rowIndex,
+        startColumnIndex: activeCell.columnIndex,
+        endColumnIndex: activeCell.columnIndex,
+    };
+};
+/**
+ * Excel stores a merged area's style on every constituent cell, and the grid paints a merge with
+ * its anchor's format. Copy the anchor's captured format over the covered cells of every merge in
+ * the pattern (in place) so the painted target carries the fill on all of them — an unmerge at the
+ * target, or a partial tile that drops the merge, still leaves every cell looking as it did.
+ */
+export const spreadMergeAnchorFormats = (formats, relativeMerges) => {
+    for (const merge of relativeMerges) {
+        const anchor = formats[merge.startRowIndex]?.[merge.startColumnIndex];
+        for (let r = merge.startRowIndex; r <= merge.endRowIndex; r++) {
+            const row = formats[r];
+            if (!row)
+                continue;
+            for (let c = merge.startColumnIndex; c <= merge.endColumnIndex; c++) {
+                if (r === merge.startRowIndex && c === merge.startColumnIndex)
+                    continue;
+                if (c < row.length)
+                    row[c] = anchor;
+            }
+        }
+    }
+};
+/**
+ * Tile a pattern's relative merges across `target` with the pattern's period (`rows` × `cols`),
+ * the same way the format grid itself is tiled by the formatting applier. A merge that a partial
+ * trailing tile would push past the target's edge is dropped — the painter never creates a merge
+ * that the user did not drag over.
+ */
+export const tilePaintMerges = (relativeMerges, rows, cols, target) => {
+    if (!relativeMerges.length || rows <= 0 || cols <= 0)
+        return [];
+    const out = [];
+    for (let top = target.startRowIndex; top <= target.endRowIndex; top += rows) {
+        for (let left = target.startColumnIndex; left <= target.endColumnIndex; left += cols) {
+            for (const merge of relativeMerges) {
+                const placed = {
+                    startRowIndex: top + merge.startRowIndex,
+                    endRowIndex: top + merge.endRowIndex,
+                    startColumnIndex: left + merge.startColumnIndex,
+                    endColumnIndex: left + merge.endColumnIndex,
+                };
+                if (rangeContains(target, placed))
+                    out.push(placed);
+            }
+        }
+    }
+    return out;
+};
+/**
+ * The banded (table stripe / alternating-colour) format the grid paints under a cell, looked up
+ * in the map `getBandedCells` builds for a sheet.
+ */
+export const getBandedCellFormat = (bandedCells, rowIndex, columnIndex) => bandedCells?.get(cellIdentifier(rowIndex, columnIndex));
+/**
+ * Layer a cell's explicit format over the banded format the grid would paint beneath it, so the
+ * captured pattern carries the VISIBLE look (Sheets copies the alternating colours as static cell
+ * fills — it does not create a table or banding at the target). Explicit keys win; an explicit
+ * `undefined` never clobbers a banded value.
+ */
+export const layerBandedFormat = (explicit, banded) => {
+    if (!banded)
+        return explicit;
+    const merged = { ...banded };
+    if (explicit) {
+        for (const [key, value] of Object.entries(explicit)) {
+            if (value !== undefined) {
+                merged[key] = value;
+            }
+        }
+    }
+    return merged;
+};

package/dist/esm/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/esm/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/esm/api/split-text.js

@@ -22,3 +22,31 @@ export const splitTextToColumns = (values, delimiter = ",") => {
         return trimmedParts;
     });
 };
+/** Normalized, ascending, de-duplicated positive break positions. */
+export const normalizeColumnBreaks = (columnBreaks) => [...new Set(columnBreaks)]
+    .filter((position) => Number.isInteger(position) && position > 0)
+    .sort((a, b) => 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 const splitTextFixedWidth = (values, columnBreaks) => {
+    const breaks = normalizeColumnBreaks(columnBreaks);
+    return values.map((cell) => {
+        if (isNil(cell)) {
+            return [""];
+        }
+        const text = String(cell);
+        const parts = [];
+        let start = 0;
+        for (const position of breaks) {
+            parts.push(text.slice(start, position).trim());
+            start = position;
+        }
+        parts.push(text.slice(start).trim());
+        return parts;
+    });
+};

package/dist/esm/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/esm/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"}