@rowsncolumns/spreadsheet-state 28.0.75 → 28.0.76

package/dist/esm/api/formula.d.ts

@@ -22,6 +22,23 @@ export declare const updateNamedRangeName: (formulaValue: string, newName: strin
  * @param newName
  */
 export declare const updateColumnName: (formulaValue: string, newName: string, oldName: string) => string;
+/** The column specifier Excel writes for a deleted table column (`Table1[@#REF!]`). */
+export declare const REF_ERROR_COLUMN = "#REF!";
+/**
+ * Rewrite every structured reference into `tableName` to the `#REF!` token —
+ * Excel's text for a formula whose table was deleted (`=SUM(Table1[Price])`
+ * → `=SUM(#REF!)`), so the cell evaluates to `#REF!` rather than `#NAME?`.
+ * Returns the input unchanged when the formula never names the table.
+ */
+export declare const breakTableReferencesInFormula: (formulaValue: string, tableName: string) => string;
+/**
+ * Rewrite the column specifiers of `columnNames` inside structured references
+ * to `tableName` (or, when `tableName` is undefined, the bare this-row form
+ * `[@Col]` whose table is implied by the formula's own cell) to `#REF!` —
+ * Excel's text for a deleted table column (`=Table1[@Qty]*2` →
+ * `=Table1[@#REF!]*2`). Keeps every other character of the reference as typed.
+ */
+export declare const breakTableColumnsInFormula: (formulaValue: string, tableName: string | undefined, columnNames: string[]) => string;
 /**
  * Converts tokens to string
  * @param tokens
@@ -46,24 +63,64 @@ export declare const isAbsoluteColumnReference: (formula: string | undefined) =>
  * @param formula
  */
 export declare const isAbsoluteRowReference: (formula: string | undefined) => boolean;
+export type StructuralRangeRewriteOptions = {
+    /**
+     * Whether references WITHOUT a sheet qualifier resolve to the edited sheet.
+     * True for a formula that lives on the edited sheet; false for a formula on
+     * another sheet, whose bare `A1:A3` is its own sheet's range and must not
+     * move when the edited sheet changes shape.
+     */
+    includeUnqualifiedReferences?: boolean;
+    /**
+     * Restrict the rewrite to ranges whose PERPENDICULAR span lies inside this
+     * band — an insert/delete-cells shift of columns `B:C` only touches ranges
+     * that live entirely inside columns B..C (SHF-08); a wider range keeps its
+     * address (SHF-07). Whole-column and whole-row references span the entire
+     * sheet, so they never fall inside a band.
+     */
+    bandSpan?: RangeBandSpan;
+};
+/** Alias kept for callers that import the scope options under this name. */
+export type StructuralFormulaScopeOptions = StructuralRangeRewriteOptions;
+/**
+ * Restricts `expandRangesInFormula` / `contractRangesInFormula` to ranges whose PERPENDICULAR span
+ * lies within a band — an insert/delete-cells shift of columns `B:C` only expands ranges that live
+ * entirely inside columns B..C (SHF-08); a wider range keeps its address (SHF-07). Whole-column and
+ * whole-row references span the entire sheet, so they never fall inside a band.
+ */
+export type RangeBandSpan = {
+    startIndex: number;
+    endIndex: number;
+};
 /**
  * Expands ranges in a formula when rows or columns are inserted within the range
  * @param formula The formula to process
  * @param insertionIndex The row or column index where insertion happens
  * @param count Number of rows or columns being inserted
  * @param dimension Whether inserting 'row' or 'column'
- * @param activeSheetName Active sheet name to scope range updates
+ * @param activeSheetName Name of the EDITED sheet: only references that resolve
+ *   to it are touched
+ * @param options `includeUnqualifiedReferences` — whether references without a
+ *   sheet qualifier resolve to the edited sheet (true when the formula lives on
+ *   it; false for a formula on another sheet, whose bare `A1:A3` is its own)
  * @returns The formula with expanded ranges, or undefined if no changes
  */
-export declare const expandRangesInFormula: (formula: string | undefined, insertionIndex: number, count: number, dimension: "row" | "column", activeSheetName: string) => string | undefined;
+export declare const expandRangesInFormula: (formula: string | undefined, insertionIndex: number, count: number, dimension: "row" | "column", activeSheetName: string, options?: StructuralRangeRewriteOptions) => string | undefined;
 /**
  * Contracts ranges in a formula when rows or columns are deleted within the range
  * @param formula The formula to process
  * @param deletionIndex The row or column index where deletion starts
  * @param count Number of rows or columns being deleted
  * @param dimension Whether deleting 'row' or 'column'
- * @param activeSheetName Active sheet name to scope range updates
+ * @param activeSheetName Name of the EDITED sheet: only references that resolve
+ *   to it are touched
+ * @param options `includeUnqualifiedReferences` — see `expandRangesInFormula`
  * @returns The formula with contracted ranges, or undefined if no changes
+ *
+ * Excel semantics for the deleted band: a range whose rows/columns are ALL
+ * deleted becomes the `#REF!` token (`=SUM(A2:A3)` → `=SUM(#REF!)`); a single
+ * cell reference into the band becomes `#REF!` (`=A3+1` → `=#REF!+1`, a spill
+ * reference `=C1#` → `=#REF!#`); a partially covered range shrinks.
  */
-export declare const contractRangesInFormula: (formula: string | undefined, deletionIndex: number, count: number, dimension: "row" | "column", activeSheetName: string) => string | undefined;
+export declare const contractRangesInFormula: (formula: string | undefined, deletionIndex: number, count: number, dimension: "row" | "column", activeSheetName: string, options?: StructuralRangeRewriteOptions) => string | undefined;
 //# sourceMappingURL=formula.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"formula.d.ts","sourceRoot":"","sources":["../../../api/formula.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,WAAW,EAAS,MAAM,2BAA2B,CAAC;AAUpE,OAAO,EACL,yBAAyB,EACzB,eAAe,EACf,0BAA0B,GAC3B,MAAM,0BAA0B,CAAC;AAClC,YAAY,EAAE,iCAAiC,EAAE,MAAM,0BAA0B,CAAC;AAElF;;;;;GAKG;AACH,eAAO,MAAM,eAAe,GAC1B,cAAc,MAAM,EACpB,SAAS,MAAM,EACf,SAAS,MAAM,WA4BhB,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,GAC/B,cAAc,MAAM,EACpB,SAAS,MAAM,EACf,SAAS,MAAM,WAehB,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,GAC3B,cAAc,MAAM,EACpB,SAAS,MAAM,EACf,SAAS,MAAM,WAYhB,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,UAAU,GAAI,QAAQ,WAAW,EAAE,WAU/C,CAAC;AAiBF;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,GACpC,SAAS,MAAM,EACf,UAAU,MAAM,EAChB,aAAa,MAAM,WAGpB,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,GAAI,SAAS,MAAM,GAAG,SAAS,YAGpE,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,GAAI,SAAS,MAAM,GAAG,SAAS,YAGjE,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,qBAAqB,GAChC,SAAS,MAAM,GAAG,SAAS,EAC3B,gBAAgB,MAAM,EACtB,OAAO,MAAM,EACb,WAAW,KAAK,GAAG,QAAQ,EAC3B,iBAAiB,MAAM,KACtB,MAAM,GAAG,SAmKX,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,uBAAuB,GAClC,SAAS,MAAM,GAAG,SAAS,EAC3B,eAAe,MAAM,EACrB,OAAO,MAAM,EACb,WAAW,KAAK,GAAG,QAAQ,EAC3B,iBAAiB,MAAM,KACtB,MAAM,GAAG,SA6NX,CAAC"}
+{"version":3,"file":"formula.d.ts","sourceRoot":"","sources":["../../../api/formula.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,WAAW,EAAS,MAAM,2BAA2B,CAAC;AAUpE,OAAO,EACL,yBAAyB,EACzB,eAAe,EACf,0BAA0B,GAC3B,MAAM,0BAA0B,CAAC;AAClC,YAAY,EAAE,iCAAiC,EAAE,MAAM,0BAA0B,CAAC;AAElF;;;;;GAKG;AACH,eAAO,MAAM,eAAe,GAC1B,cAAc,MAAM,EACpB,SAAS,MAAM,EACf,SAAS,MAAM,WA4BhB,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,GAC/B,cAAc,MAAM,EACpB,SAAS,MAAM,EACf,SAAS,MAAM,WAehB,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,GAC3B,cAAc,MAAM,EACpB,SAAS,MAAM,EACf,SAAS,MAAM,WAYhB,CAAC;AAEF,uFAAuF;AACvF,eAAO,MAAM,gBAAgB,UAAU,CAAC;AAgDxC;;;;;GAKG;AACH,eAAO,MAAM,6BAA6B,GACxC,cAAc,MAAM,EACpB,WAAW,MAAM,KAChB,MA4BF,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,0BAA0B,GACrC,cAAc,MAAM,EACpB,WAAW,MAAM,GAAG,SAAS,EAC7B,aAAa,MAAM,EAAE,KACpB,MA+BF,CAAC;AAaF;;;GAGG;AACH,eAAO,MAAM,UAAU,GAAI,QAAQ,WAAW,EAAE,WAU/C,CAAC;AAiBF;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,GACpC,SAAS,MAAM,EACf,UAAU,MAAM,EAChB,aAAa,MAAM,WAGpB,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,GAAI,SAAS,MAAM,GAAG,SAAS,YAGpE,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,GAAI,SAAS,MAAM,GAAG,SAAS,YAGjE,CAAC;AAEF,MAAM,MAAM,6BAA6B,GAAG;IAC1C;;;;;OAKG;IACH,4BAA4B,CAAC,EAAE,OAAO,CAAC;IACvC;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,aAAa,CAAC;CAC1B,CAAC;AAEF,4EAA4E;AAC5E,MAAM,MAAM,6BAA6B,GAAG,6BAA6B,CAAC;AAE1E;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GAAG;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC;AAmBrE;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,qBAAqB,GAChC,SAAS,MAAM,GAAG,SAAS,EAC3B,gBAAgB,MAAM,EACtB,OAAO,MAAM,EACb,WAAW,KAAK,GAAG,QAAQ,EAC3B,iBAAiB,MAAM,EACvB,UAAS,6BAAkC,KAC1C,MAAM,GAAG,SAyKX,CAAC;AAEF;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,uBAAuB,GAClC,SAAS,MAAM,GAAG,SAAS,EAC3B,eAAe,MAAM,EACrB,OAAO,MAAM,EACb,WAAW,KAAK,GAAG,QAAQ,EAC3B,iBAAiB,MAAM,EACvB,UAAS,6BAAkC,KAC1C,MAAM,GAAG,SAkPX,CAAC"}

package/dist/esm/api/formula.js

@@ -1,4 +1,4 @@
-import { isRangeToken, lexify, stripPropertyFromCellRef, tokenVocabulary, } from "@rowsncolumns/calculator";
+import { cleanupColumnName, cleanupTableName, isRangeToken, lexify, stripPropertyFromCellRef, tokenVocabulary, } from "@rowsncolumns/calculator";
 import { addressToCell, alpha2number, cellToAddress, desanitizeSheetName, number2Alpha, sanitizeSheetName, } from "@rowsncolumns/utils";
 export { ERROR_CIRCULAR_DEPENDENCY, ERROR_REFERENCE, formulaToRelativeReference, } from "@rowsncolumns/calculator";
 /**
@@ -65,6 +65,138 @@ export const updateColumnName = (formulaValue, newName, oldName) => {
     }
     return detokenize(newTokens);
 };
+/** The column specifier Excel writes for a deleted table column (`Table1[@#REF!]`). */
+export const REF_ERROR_COLUMN = "#REF!";
+const REF_ERROR_TOKEN = "#REF!";
+/**
+ * One `#REF!` token standing in for the run `start … end` (a range's start,
+ * colon and end): it keeps `start`'s position and stretches to `end` so
+ * `detokenize` (which re-inserts a space wherever adjacent tokens' offsets
+ * disagree) prints `SUM(#REF!)`, not `SUM(#REF! )`.
+ */
+const collapseToRefError = (start, end) => ({
+    ...start,
+    image: REF_ERROR_TOKEN,
+    tokenType: tokenVocabulary.RefError,
+    endOffset: end?.endOffset ?? start.endOffset,
+    endColumn: end?.endColumn ?? start.endColumn,
+});
+const isTableNameToken = (token) => token?.tokenType.name === tokenVocabulary.TableName.name;
+const isTableColumnToken = (token) => token?.tokenType.name === tokenVocabulary.TableColumnName.name;
+/** Bracket depth change contributed by one token's image (`Table1[` opens, `Qty]` closes). */
+const bracketDelta = (image) => {
+    let depth = 0;
+    for (const ch of image) {
+        if (ch === "[")
+            depth++;
+        else if (ch === "]")
+            depth--;
+    }
+    return depth;
+};
+/**
+ * Index just past the last token of the structured reference that starts at
+ * `start` (a TableName token): consume tokens until the bracket the table name
+ * opened is closed again.
+ */
+const structuredReferenceEnd = (tokens, start) => {
+    let depth = 0;
+    let i = start;
+    while (i < tokens.length) {
+        depth += bracketDelta(tokens[i].image);
+        i++;
+        if (depth <= 0)
+            break;
+    }
+    return i;
+};
+/**
+ * Rewrite every structured reference into `tableName` to the `#REF!` token —
+ * Excel's text for a formula whose table was deleted (`=SUM(Table1[Price])`
+ * → `=SUM(#REF!)`), so the cell evaluates to `#REF!` rather than `#NAME?`.
+ * Returns the input unchanged when the formula never names the table.
+ */
+export const breakTableReferencesInFormula = (formulaValue, tableName) => {
+    if (!formulaValue.includes("["))
+        return formulaValue;
+    const tokens = cloneTokens(lexify(formulaValue).tokens);
+    const newTokens = [];
+    const target = tableName.toLowerCase();
+    let hasChanges = false;
+    for (let i = 0; i < tokens.length; i++) {
+        const token = tokens[i];
+        if (isTableNameToken(token) &&
+            cleanupTableName(token.image).trim().toLowerCase() === target) {
+            const end = structuredReferenceEnd(tokens, i);
+            const last = tokens[end - 1] ?? token;
+            newTokens.push({
+                ...token,
+                image: REF_ERROR_TOKEN,
+                endOffset: last.endOffset,
+                endColumn: last.endColumn,
+                tokenType: tokenVocabulary.RefError,
+            });
+            i = end - 1;
+            hasChanges = true;
+            continue;
+        }
+        newTokens.push(token);
+    }
+    return hasChanges ? detokenize(newTokens) : formulaValue;
+};
+/**
+ * Rewrite the column specifiers of `columnNames` inside structured references
+ * to `tableName` (or, when `tableName` is undefined, the bare this-row form
+ * `[@Col]` whose table is implied by the formula's own cell) to `#REF!` —
+ * Excel's text for a deleted table column (`=Table1[@Qty]*2` →
+ * `=Table1[@#REF!]*2`). Keeps every other character of the reference as typed.
+ */
+export const breakTableColumnsInFormula = (formulaValue, tableName, columnNames) => {
+    if (!formulaValue.includes("[") || columnNames.length === 0) {
+        return formulaValue;
+    }
+    const targets = new Set(columnNames.map((name) => name.toLowerCase()));
+    const target = tableName?.toLowerCase();
+    const tokens = cloneTokens(lexify(formulaValue).tokens);
+    let hasChanges = false;
+    let i = 0;
+    while (i < tokens.length) {
+        const token = tokens[i];
+        if (isTableNameToken(token)) {
+            const end = structuredReferenceEnd(tokens, i);
+            const matches = target !== undefined &&
+                cleanupTableName(token.image).trim().toLowerCase() === target;
+            if (matches) {
+                for (let j = i + 1; j < end; j++) {
+                    if (breakColumnToken(tokens[j], targets))
+                        hasChanges = true;
+                }
+            }
+            i = end;
+            continue;
+        }
+        // A bare `[@Col]` / `[Col]` names the table the formula cell sits in.
+        if (target === undefined && isTableColumnToken(token)) {
+            if (breakColumnToken(token, targets))
+                hasChanges = true;
+        }
+        i++;
+    }
+    return hasChanges ? detokenize(tokens) : formulaValue;
+};
+const breakColumnToken = (token, targets) => {
+    if (!token || !isTableColumnToken(token))
+        return false;
+    const name = cleanupColumnName(token.image);
+    if (!name || !targets.has(name.toLowerCase()))
+        return false;
+    const at = token.image.indexOf(name);
+    if (at === -1)
+        return false;
+    token.image =
+        token.image.slice(0, at) + REF_ERROR_COLUMN + token.image.slice(at + name.length);
+    return true;
+};
 /**
  * Converts tokens to string
  * @param tokens
@@ -122,19 +254,33 @@ export const isAbsoluteRowReference = (formula) => {
         return false;
     return /\$\d+/gi.test(formula);
 };
+const isRangeWithinBandSpan = (startCell, endCell, dimension, bandSpan) => {
+    if (!bandSpan)
+        return true;
+    const [start, end] = dimension === "row"
+        ? [startCell.columnIndex, endCell.columnIndex]
+        : [startCell.rowIndex, endCell.rowIndex];
+    return (Math.min(start, end) >= bandSpan.startIndex &&
+        Math.max(start, end) <= bandSpan.endIndex);
+};
 /**
  * Expands ranges in a formula when rows or columns are inserted within the range
  * @param formula The formula to process
  * @param insertionIndex The row or column index where insertion happens
  * @param count Number of rows or columns being inserted
  * @param dimension Whether inserting 'row' or 'column'
- * @param activeSheetName Active sheet name to scope range updates
+ * @param activeSheetName Name of the EDITED sheet: only references that resolve
+ *   to it are touched
+ * @param options `includeUnqualifiedReferences` — whether references without a
+ *   sheet qualifier resolve to the edited sheet (true when the formula lives on
+ *   it; false for a formula on another sheet, whose bare `A1:A3` is its own)
  * @returns The formula with expanded ranges, or undefined if no changes
  */
-export const expandRangesInFormula = (formula, insertionIndex, count, dimension, activeSheetName) => {
+export const expandRangesInFormula = (formula, insertionIndex, count, dimension, activeSheetName, options = {}) => {
     if (!formula || count <= 0) {
         return formula;
     }
+    const { includeUnqualifiedReferences = true, bandSpan } = options;
     const normalizedActiveSheetName = activeSheetName.toLowerCase();
     const tokens = cloneTokens(lexify(formula).tokens);
     const newTokens = [];
@@ -142,7 +288,9 @@ export const expandRangesInFormula = (formula, insertionIndex, count, dimension,
     for (let i = 0; i < tokens.length; i++) {
         const token = tokens[i];
         const sheetName = getSheetNameFromToken(tokens[i - 1]);
-        const skipSheet = sheetName && sheetName.toLowerCase() !== normalizedActiveSheetName;
+        const skipSheet = sheetName
+            ? sheetName.toLowerCase() !== normalizedActiveSheetName
+            : !includeUnqualifiedReferences;
         // Handle cell ranges (e.g., A1:A10)
         if (token.tokenType.name === tokenVocabulary.Cell.name) {
             const isRange = isRangeToken(tokens[i + 1]);
@@ -157,7 +305,9 @@ export const expandRangesInFormula = (formula, insertionIndex, count, dimension,
             if (isRange && tokens[i + 2]) {
                 const startCell = addressToCell(stripPropertyFromCellRef(token.image));
                 const endCell = addressToCell(stripPropertyFromCellRef(tokens[i + 2].image));
-                if (startCell && endCell) {
+                if (startCell &&
+                    endCell &&
+                    isRangeWithinBandSpan(startCell, endCell, dimension, bandSpan)) {
                     const isAbsoluteEndRow = isAbsoluteRowReference(tokens[i + 2].image);
                     const isAbsoluteEndCol = isAbsoluteColumnReference(tokens[i + 2].image);
                     if (dimension === "row") {
@@ -197,7 +347,7 @@ export const expandRangesInFormula = (formula, insertionIndex, count, dimension,
         if (dimension === "column" &&
             token.tokenType.name === tokenVocabulary.Column.name) {
             const isRange = isRangeToken(tokens[i + 1]);
-            if (skipSheet) {
+            if (skipSheet || bandSpan) {
                 if (isRange) {
                     newTokens.push(token, tokens[i + 1], tokens[i + 2]);
                     i += 2;
@@ -224,7 +374,7 @@ export const expandRangesInFormula = (formula, insertionIndex, count, dimension,
         if (dimension === "row" &&
             token.tokenType.name === tokenVocabulary.Number.name) {
             const isRange = isRangeToken(tokens[i + 1]);
-            if (skipSheet) {
+            if (skipSheet || bandSpan) {
                 if (isRange) {
                     newTokens.push(token, tokens[i + 1], tokens[i + 2]);
                     i += 2;
@@ -257,22 +407,45 @@ export const expandRangesInFormula = (formula, insertionIndex, count, dimension,
  * @param deletionIndex The row or column index where deletion starts
  * @param count Number of rows or columns being deleted
  * @param dimension Whether deleting 'row' or 'column'
- * @param activeSheetName Active sheet name to scope range updates
+ * @param activeSheetName Name of the EDITED sheet: only references that resolve
+ *   to it are touched
+ * @param options `includeUnqualifiedReferences` — see `expandRangesInFormula`
  * @returns The formula with contracted ranges, or undefined if no changes
+ *
+ * Excel semantics for the deleted band: a range whose rows/columns are ALL
+ * deleted becomes the `#REF!` token (`=SUM(A2:A3)` → `=SUM(#REF!)`); a single
+ * cell reference into the band becomes `#REF!` (`=A3+1` → `=#REF!+1`, a spill
+ * reference `=C1#` → `=#REF!#`); a partially covered range shrinks.
  */
-export const contractRangesInFormula = (formula, deletionIndex, count, dimension, activeSheetName) => {
+export const contractRangesInFormula = (formula, deletionIndex, count, dimension, activeSheetName, options = {}) => {
     if (!formula || count <= 0) {
         return formula;
     }
+    const { includeUnqualifiedReferences = true, bandSpan } = options;
     const normalizedActiveSheetName = activeSheetName.toLowerCase();
     const tokens = cloneTokens(lexify(formula).tokens);
     const newTokens = [];
     let hasChanges = false;
     const deletionEnd = deletionIndex + count - 1;
+    const inDeletedBand = (cell) => {
+        const index = dimension === "row" ? cell.rowIndex : cell.columnIndex;
+        return index >= deletionIndex && index <= deletionEnd;
+    };
+    const overlapsBand = (start, end) => deletionIndex <= end && deletionEnd >= start;
+    // The survivors of a span that overlaps (but is not swallowed by) the band:
+    // whatever lay before the band keeps its start, whatever lay inside starts at
+    // the deletion point; an end past the band moves up by the full count, an
+    // end inside the band stops just before it.
+    const contractSpan = (start, end) => ({
+        start: Math.min(start, deletionIndex),
+        end: end > deletionEnd ? end - count : deletionIndex - 1,
+    });
     for (let i = 0; i < tokens.length; i++) {
         const token = tokens[i];
         const sheetName = getSheetNameFromToken(tokens[i - 1]);
-        const skipSheet = sheetName && sheetName.toLowerCase() !== normalizedActiveSheetName;
+        const skipSheet = sheetName
+            ? sheetName.toLowerCase() !== normalizedActiveSheetName
+            : !includeUnqualifiedReferences;
         // Handle cell ranges (e.g., A1:A10)
         if (token.tokenType.name === tokenVocabulary.Cell.name) {
             const isRange = isRangeToken(tokens[i + 1]);
@@ -284,10 +457,33 @@ export const contractRangesInFormula = (formula, deletionIndex, count, dimension
                 }
                 continue;
             }
+            if (!isRange) {
+                // Single cell: broken when it sits in the deleted band. The trailing
+                // spilled-range operator (`C1#`) stays on the token (`#REF!#`).
+                const spill = token.image.endsWith("#") ? "#" : "";
+                const cell = addressToCell(stripPropertyFromCellRef(spill ? token.image.slice(0, -1) : token.image));
+                if (cell &&
+                    inDeletedBand(cell) &&
+                    isRangeWithinBandSpan(cell, cell, dimension, bandSpan)) {
+                    token.image = `${REF_ERROR_TOKEN}${spill}`;
+                    hasChanges = true;
+                }
+                newTokens.push(token);
+                continue;
+            }
             if (isRange && tokens[i + 2]) {
                 const startCell = addressToCell(stripPropertyFromCellRef(token.image));
                 const endCell = addressToCell(stripPropertyFromCellRef(tokens[i + 2].image));
-                if (startCell && endCell) {
+                if (startCell &&
+                    endCell &&
+                    isRangeWithinBandSpan(startCell, endCell, dimension, bandSpan)) {
+                    // Every row/column of the range deleted → the whole range is #REF!.
+                    if (inDeletedBand(startCell) && inDeletedBand(endCell)) {
+                        newTokens.push(collapseToRefError(token, tokens[i + 2]));
+                        i += 2;
+                        hasChanges = true;
+                        continue;
+                    }
                     const isAbsoluteStartRow = isAbsoluteRowReference(token.image);
                     const isAbsoluteEndRow = isAbsoluteRowReference(tokens[i + 2].image);
                     const isAbsoluteStartCol = isAbsoluteColumnReference(token.image);
@@ -295,18 +491,10 @@ export const contractRangesInFormula = (formula, deletionIndex, count, dimension
                     if (dimension === "row") {
                         const rangeStart = startCell.rowIndex;
                         const rangeEnd = endCell.rowIndex;
-                        // Check if deletion overlaps with range
-                        if (deletionIndex <= rangeEnd && deletionEnd >= rangeStart) {
-                            // Calculate how many deleted rows are within the range
-                            const overlapStart = Math.max(deletionIndex, rangeStart);
-                            const overlapEnd = Math.min(deletionEnd, rangeEnd);
-                            const rowsDeletedInRange = overlapEnd - overlapStart + 1;
-                            // Contract the end of the range
-                            endCell.rowIndex -= rowsDeletedInRange;
-                            // If entire range is deleted, result in #REF! (but we'll just contract to minimum)
-                            if (endCell.rowIndex < startCell.rowIndex) {
-                                endCell.rowIndex = startCell.rowIndex;
-                            }
+                        if (overlapsBand(rangeStart, rangeEnd)) {
+                            const survivors = contractSpan(rangeStart, rangeEnd);
+                            startCell.rowIndex = survivors.start;
+                            endCell.rowIndex = survivors.end;
                             const newStartAddress = cellToAddress(startCell, isAbsoluteStartCol, isAbsoluteStartRow);
                             const newEndAddress = cellToAddress(endCell, isAbsoluteEndCol, isAbsoluteEndRow);
                             if (newStartAddress && newEndAddress) {
@@ -320,18 +508,10 @@ export const contractRangesInFormula = (formula, deletionIndex, count, dimension
                         // dimension === 'column'
                         const rangeStart = startCell.columnIndex;
                         const rangeEnd = endCell.columnIndex;
-                        // Check if deletion overlaps with range
-                        if (deletionIndex <= rangeEnd && deletionEnd >= rangeStart) {
-                            // Calculate how many deleted columns are within the range
-                            const overlapStart = Math.max(deletionIndex, rangeStart);
-                            const overlapEnd = Math.min(deletionEnd, rangeEnd);
-                            const colsDeletedInRange = overlapEnd - overlapStart + 1;
-                            // Contract the end of the range
-                            endCell.columnIndex -= colsDeletedInRange;
-                            // If entire range is deleted, result in #REF! (but we'll just contract to minimum)
-                            if (endCell.columnIndex < startCell.columnIndex) {
-                                endCell.columnIndex = startCell.columnIndex;
-                            }
+                        if (overlapsBand(rangeStart, rangeEnd)) {
+                            const survivors = contractSpan(rangeStart, rangeEnd);
+                            startCell.columnIndex = survivors.start;
+                            endCell.columnIndex = survivors.end;
                             const newStartAddress = cellToAddress(startCell, isAbsoluteStartCol, isAbsoluteStartRow);
                             const newEndAddress = cellToAddress(endCell, isAbsoluteEndCol, isAbsoluteEndRow);
                             if (newStartAddress && newEndAddress) {
@@ -351,7 +531,7 @@ export const contractRangesInFormula = (formula, deletionIndex, count, dimension
         if (dimension === "column" &&
             token.tokenType.name === tokenVocabulary.Column.name) {
             const isRange = isRangeToken(tokens[i + 1]);
-            if (skipSheet) {
+            if (skipSheet || bandSpan) {
                 if (isRange) {
                     newTokens.push(token, tokens[i + 1], tokens[i + 2]);
                     i += 2;
@@ -361,20 +541,19 @@ export const contractRangesInFormula = (formula, deletionIndex, count, dimension
             if (isRange && tokens[i + 2]) {
                 const startColumnIndex = alpha2number(token.image);
                 const endColumnIndex = alpha2number(tokens[i + 2].image);
-                // Check if deletion overlaps with range
-                if (deletionIndex <= endColumnIndex &&
-                    deletionEnd >= startColumnIndex) {
-                    // Calculate how many deleted columns are within the range
-                    const overlapStart = Math.max(deletionIndex, startColumnIndex);
-                    const overlapEnd = Math.min(deletionEnd, endColumnIndex);
-                    const colsDeletedInRange = overlapEnd - overlapStart + 1;
-                    // Contract the end column
-                    const newEndColumnIndex = endColumnIndex - colsDeletedInRange;
-                    // If entire range is deleted, keep at minimum
-                    if (newEndColumnIndex >= startColumnIndex) {
-                        tokens[i + 2].image = number2Alpha(newEndColumnIndex - 1);
+                if (overlapsBand(startColumnIndex, endColumnIndex)) {
+                    // Every column deleted → #REF!; otherwise the survivors close up.
+                    if (startColumnIndex >= deletionIndex &&
+                        endColumnIndex <= deletionEnd) {
+                        newTokens.push(collapseToRefError(token, tokens[i + 2]));
+                        i += 2;
                         hasChanges = true;
+                        continue;
                     }
+                    const survivors = contractSpan(startColumnIndex, endColumnIndex);
+                    token.image = number2Alpha(survivors.start - 1);
+                    tokens[i + 2].image = number2Alpha(survivors.end - 1);
+                    hasChanges = true;
                 }
                 newTokens.push(token, tokens[i + 1], tokens[i + 2]);
                 i += 2;
@@ -385,7 +564,7 @@ export const contractRangesInFormula = (formula, deletionIndex, count, dimension
         if (dimension === "row" &&
             token.tokenType.name === tokenVocabulary.Number.name) {
             const isRange = isRangeToken(tokens[i + 1]);
-            if (skipSheet) {
+            if (skipSheet || bandSpan) {
                 if (isRange) {
                     newTokens.push(token, tokens[i + 1], tokens[i + 2]);
                     i += 2;
@@ -397,19 +576,18 @@ export const contractRangesInFormula = (formula, deletionIndex, count, dimension
                 tokens[i + 2].tokenType.name === tokenVocabulary.Number.name) {
                 const startRowIndex = Number(token.image);
                 const endRowIndex = Number(tokens[i + 2].image);
-                // Check if deletion overlaps with range
-                if (deletionIndex <= endRowIndex && deletionEnd >= startRowIndex) {
-                    // Calculate how many deleted rows are within the range
-                    const overlapStart = Math.max(deletionIndex, startRowIndex);
-                    const overlapEnd = Math.min(deletionEnd, endRowIndex);
-                    const rowsDeletedInRange = overlapEnd - overlapStart + 1;
-                    // Contract the end row
-                    const newEndRowIndex = endRowIndex - rowsDeletedInRange;
-                    // If entire range is deleted, keep at minimum
-                    if (newEndRowIndex >= startRowIndex) {
-                        tokens[i + 2].image = String(newEndRowIndex);
+                if (overlapsBand(startRowIndex, endRowIndex)) {
+                    // Every row deleted → #REF!; otherwise the survivors close up.
+                    if (startRowIndex >= deletionIndex && endRowIndex <= deletionEnd) {
+                        newTokens.push(collapseToRefError(token, tokens[i + 2]));
+                        i += 2;
                         hasChanges = true;
+                        continue;
                     }
+                    const survivors = contractSpan(startRowIndex, endRowIndex);
+                    token.image = String(survivors.start);
+                    tokens[i + 2].image = String(survivors.end);
+                    hasChanges = true;
                 }
                 newTokens.push(token, tokens[i + 1], tokens[i + 2]);
                 i += 2;

package/dist/esm/api/merges.d.ts

@@ -4,4 +4,12 @@ export declare const shrinkMergesOnRowDelete: (merges: GridRange[], deleteStart:
 export declare const shrinkMergesOnColumnDelete: (merges: GridRange[], deleteStart: number, deleteCount: number) => GridRange[];
 export declare const expandMergesOnRowInsert: (merges: GridRange[], insertIndex: number, count: number) => GridRange[];
 export declare const expandMergesOnColumnInsert: (merges: GridRange[], insertIndex: number, count: number) => GridRange[];
+/**
+ * Merges that travel with an insert/delete-cells shift: a merge wholly inside the shifted band
+ * (rows `>= start` in the band's columns for a vertical shift; columns `>= start` in its rows for a
+ * horizontal one) moves by `count`; on a delete, a merge wholly inside the deleted block is dropped
+ * with it. Merges the band only partially covers are refused upstream (`findTornMerge`) — this
+ * helper never tears one, it leaves anything outside the band untouched.
+ */
+export declare const shiftMergesInBand: (merges: GridRange[] | undefined | null, axis: "row" | "column", start: number, count: number, insert: boolean, spanStart: number, spanEnd: number) => GridRange[] | null | undefined;
 //# sourceMappingURL=merges.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"merges.d.ts","sourceRoot":"","sources":["../../../api/merges.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAC;AAY5D,eAAO,MAAM,eAAe,GAC1B,aAAa,SAAS,EAAE,GAAG,SAAS,GAAG,IAAI,EAC3C,IAAI,eAAe,GAAG,YAAY,GAAG,eAAe,GAAG,YAAY,EACnE,gBAAgB,MAAM,EACtB,cAAS,EACT,YAAY,CAAC,IAAI,EAAE,SAAS,KAAK,OAAO,mCA2DzC,CAAC;AAEF,eAAO,MAAM,uBAAuB,GAClC,QAAQ,SAAS,EAAE,EACnB,aAAa,MAAM,EACnB,aAAa,MAAM,gBA8CpB,CAAC;AAEF,eAAO,MAAM,0BAA0B,GACrC,QAAQ,SAAS,EAAE,EACnB,aAAa,MAAM,EACnB,aAAa,MAAM,gBA8CpB,CAAC;AAEF,eAAO,MAAM,uBAAuB,GAClC,QAAQ,SAAS,EAAE,EACnB,aAAa,MAAM,EACnB,OAAO,MAAM,gBAyBd,CAAC;AAEF,eAAO,MAAM,0BAA0B,GACrC,QAAQ,SAAS,EAAE,EACnB,aAAa,MAAM,EACnB,OAAO,MAAM,gBAyBd,CAAC"}
+{"version":3,"file":"merges.d.ts","sourceRoot":"","sources":["../../../api/merges.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAC;AAY5D,eAAO,MAAM,eAAe,GAC1B,aAAa,SAAS,EAAE,GAAG,SAAS,GAAG,IAAI,EAC3C,IAAI,eAAe,GAAG,YAAY,GAAG,eAAe,GAAG,YAAY,EACnE,gBAAgB,MAAM,EACtB,cAAS,EACT,YAAY,CAAC,IAAI,EAAE,SAAS,KAAK,OAAO,mCA2DzC,CAAC;AAEF,eAAO,MAAM,uBAAuB,GAClC,QAAQ,SAAS,EAAE,EACnB,aAAa,MAAM,EACnB,aAAa,MAAM,gBA8CpB,CAAC;AAEF,eAAO,MAAM,0BAA0B,GACrC,QAAQ,SAAS,EAAE,EACnB,aAAa,MAAM,EACnB,aAAa,MAAM,gBA8CpB,CAAC;AAEF,eAAO,MAAM,uBAAuB,GAClC,QAAQ,SAAS,EAAE,EACnB,aAAa,MAAM,EACnB,OAAO,MAAM,gBAyBd,CAAC;AAEF,eAAO,MAAM,0BAA0B,GACrC,QAAQ,SAAS,EAAE,EACnB,aAAa,MAAM,EACnB,OAAO,MAAM,gBAyBd,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,GAC5B,QAAQ,SAAS,EAAE,GAAG,SAAS,GAAG,IAAI,EACtC,MAAM,KAAK,GAAG,QAAQ,EACtB,OAAO,MAAM,EACb,OAAO,MAAM,EACb,QAAQ,OAAO,EACf,WAAW,MAAM,EACjB,SAAS,MAAM,mCAkDhB,CAAC"}

package/dist/esm/api/merges.js

@@ -172,3 +172,54 @@ export const expandMergesOnColumnInsert = (merges, insertIndex, count) => {
     })
         .filter((merge) => !isSingleCellMerge(merge));
 };
+/**
+ * Merges that travel with an insert/delete-cells shift: a merge wholly inside the shifted band
+ * (rows `>= start` in the band's columns for a vertical shift; columns `>= start` in its rows for a
+ * horizontal one) moves by `count`; on a delete, a merge wholly inside the deleted block is dropped
+ * with it. Merges the band only partially covers are refused upstream (`findTornMerge`) — this
+ * helper never tears one, it leaves anything outside the band untouched.
+ */
+export const shiftMergesInBand = (merges, axis, start, count, insert, spanStart, spanEnd) => {
+    if (!merges || count <= 0) {
+        return merges;
+    }
+    const deletedEnd = start + count - 1;
+    const inSpan = axis === "row"
+        ? (merge) => merge.startColumnIndex >= spanStart && merge.endColumnIndex <= spanEnd
+        : (merge) => merge.startRowIndex >= spanStart && merge.endRowIndex <= spanEnd;
+    const lineStart = (merge) => axis === "row" ? merge.startRowIndex : merge.startColumnIndex;
+    const lineEnd = (merge) => axis === "row" ? merge.endRowIndex : merge.endColumnIndex;
+    const moved = (merge, delta) => axis === "row"
+        ? {
+            ...merge,
+            startRowIndex: merge.startRowIndex + delta,
+            endRowIndex: merge.endRowIndex + delta,
+        }
+        : {
+            ...merge,
+            startColumnIndex: merge.startColumnIndex + delta,
+            endColumnIndex: merge.endColumnIndex + delta,
+        };
+    const next = [];
+    for (const merge of merges) {
+        if (!inSpan(merge) || lineStart(merge) < start) {
+            next.push(merge);
+            continue;
+        }
+        if (insert) {
+            next.push(moved(merge, count));
+            continue;
+        }
+        if (lineEnd(merge) <= deletedEnd) {
+            // Wholly inside the deleted block — removed with it.
+            continue;
+        }
+        if (lineStart(merge) > deletedEnd) {
+            next.push(moved(merge, -count));
+            continue;
+        }
+        // Straddles the deleted block's edge: refused upstream; never tear it here.
+        next.push(merge);
+    }
+    return next;
+};