@shbernal/ts-xlsx 2.0.0 → 3.0.0

package/dist/core/conditional-formatting.d.ts

@@ -1,26 +1,66 @@
 import type { Color, DifferentialStyle } from './style.ts';
+/** How a {@link CfValueObject} reads its `value`: `ST_CfvoType` verbatim. */
+export type CfValueObjectType = 'num' | 'percent' | 'max' | 'min' | 'percentile' | 'formula';
+/** Narrow a raw `<cfvo type>` token to a known {@link CfValueObjectType}. */
+export declare const isCfValueObjectType: (value: string) => value is CfValueObjectType;
 /**
  * One anchor of a colour-scale, data-bar, or icon-set scale: a "conditional format value object".
  * `type` names how `value` is read: a literal `num`, a `percent`/`percentile` of the range, a
  * `formula`, or the range's own `min`/`max` (which carry no value).
  */
 export interface CfValueObject {
-    type: 'num' | 'percent' | 'max' | 'min' | 'percentile' | 'formula';
+    type: CfValueObjectType;
     value?: number | string;
 }
+/**
+ * What a rule tests, as `<cfRule type>` carries it: `ST_CfType` verbatim.
+ *
+ * Closed, and stated in full rather than left as `string`, even though the library models only some
+ * of these in depth. Depth of modelling and legality are different questions: a `timePeriod` rule
+ * whose operands the library never inspects still round-trips, while a token outside this list is one
+ * Excel refuses to open, so it is refused on the way in and on the way out alike.
+ */
+export type ConditionalFormattingType = 'expression' | 'cellIs' | 'colorScale' | 'dataBar' | 'iconSet' | 'top10' | 'uniqueValues' | 'duplicateValues' | 'containsText' | 'notContainsText' | 'beginsWith' | 'endsWith' | 'containsBlanks' | 'notContainsBlanks' | 'containsErrors' | 'notContainsErrors' | 'timePeriod' | 'aboveAverage';
+/** Narrow a raw `<cfRule type>` token to a known {@link ConditionalFormattingType}. */
+export declare const isConditionalFormattingType: (value: string) => value is ConditionalFormattingType;
+/**
+ * How a `cellIs` or text rule compares, as `ST_ConditionalFormattingOperator` enumerates it.
+ *
+ * Overlaps {@link import('./data-validation.ts').DataValidationOperator} in four members and diverges
+ * in the rest: this one has the text comparisons a validation has no use for, and spells "does not
+ * contain" as `notContains` where nothing else in the format does.
+ */
+export type ConditionalFormattingOperator = 'lessThan' | 'lessThanOrEqual' | 'equal' | 'notEqual' | 'greaterThanOrEqual' | 'greaterThan' | 'between' | 'notBetween' | 'containsText' | 'notContains' | 'beginsWith' | 'endsWith';
+/** Narrow a raw `<cfRule operator>` token to a known {@link ConditionalFormattingOperator}. */
+export declare const isConditionalFormattingOperator: (value: string) => value is ConditionalFormattingOperator;
+/** The window a `timePeriod` rule matches against, relative to the day the sheet is recalculated. */
+export type CfTimePeriod = 'today' | 'yesterday' | 'tomorrow' | 'last7Days' | 'thisMonth' | 'lastMonth' | 'nextMonth' | 'thisWeek' | 'lastWeek' | 'nextWeek';
+/** Narrow a raw `<cfRule timePeriod>` token to a known {@link CfTimePeriod}. */
+export declare const isCfTimePeriod: (value: string) => value is CfTimePeriod;
+/**
+ * The named icon family an `iconSet` rule draws from, as `ST_IconSetType` enumerates it. The leading
+ * digit is the number of icons, which is also how many {@link CfValueObject} anchors the rule needs.
+ *
+ * The 2009 extension adds three more families (`3Stars`, `3Triangles`, `5Boxes`) under its own
+ * namespace. They are absent here because the classic `<iconSet>` element this list types cannot
+ * carry them; a file using one states it in the extension, which the library round-trips verbatim.
+ */
+export type IconSetType = '3Arrows' | '3ArrowsGray' | '3Flags' | '3TrafficLights1' | '3TrafficLights2' | '3Signs' | '3Symbols' | '3Symbols2' | '4Arrows' | '4ArrowsGray' | '4RedToBlack' | '4Rating' | '4TrafficLights' | '5Arrows' | '5ArrowsGray' | '5Rating' | '5Quarters';
+/** Narrow a raw `<iconSet iconSet>` token to a known {@link IconSetType}. */
+export declare const isIconSetType: (value: string) => value is IconSetType;
 /**
  * A single conditional-formatting rule. `type` is the OOXML cfRule type; the remaining fields carry
  * the operands that type needs and are absent otherwise. A rule the library does not model in depth
  * still preserves `type`, `priority`, `operator`, `formulae`, and `dxfId` across a round-trip.
  */
 export interface ConditionalFormattingRule {
-    type: string;
+    type: ConditionalFormattingType;
     /** Evaluation precedence; lower wins. Excel requires one, so the writer supplies it when absent. */
     priority?: number;
     /** Halt evaluation of lower-priority rules on any cell this rule matches. */
     stopIfTrue?: boolean;
     /** cellIs / text comparison operator (`greaterThan`, `between`, `beginsWith`, …). */
-    operator?: string;
+    operator?: ConditionalFormattingOperator;
     /** Formula operands: cellIs bounds, an expression predicate, a containsText target formula, … */
     formulae?: (string | number)[];
     /** The literal a containsText / beginsWith / endsWith rule searches for. */
@@ -42,7 +82,7 @@ export interface ConditionalFormattingRule {
     /** A dataBar's axis colour (the zero line between positive and negative bars). An x14 property. */
     axisColor?: Color;
     /** An iconSet's named icon family (e.g. `3TrafficLights1`). */
-    iconSet?: string;
+    iconSet?: IconSetType;
     /** top10 rank cutoff. */
     rank?: number;
     /** top10: the rank is a percentage rather than a count. */
@@ -56,7 +96,7 @@ export interface ConditionalFormattingRule {
     /** aboveAverage: match beyond this many standard deviations. */
     stdDev?: number;
     /** timePeriod window (`today`, `lastWeek`, …). */
-    timePeriod?: string;
+    timePeriod?: CfTimePeriod;
 }
 /** A set of rules bound to the range(s) they cover. `ref` is an OOXML `sqref`: one or more
  * space-separated areas (`"A1:C1 A3:C3 A5:C5"`), the shape Excel writes when one rule is applied to

package/dist/core/conditional-formatting.js

@@ -1,3 +1,77 @@
+import { tokenSet } from '../token-set.js';
+export const isCfValueObjectType = tokenSet({
+    num: true,
+    percent: true,
+    max: true,
+    min: true,
+    percentile: true,
+    formula: true,
+});
+export const isConditionalFormattingType = tokenSet({
+    expression: true,
+    cellIs: true,
+    colorScale: true,
+    dataBar: true,
+    iconSet: true,
+    top10: true,
+    uniqueValues: true,
+    duplicateValues: true,
+    containsText: true,
+    notContainsText: true,
+    beginsWith: true,
+    endsWith: true,
+    containsBlanks: true,
+    notContainsBlanks: true,
+    containsErrors: true,
+    notContainsErrors: true,
+    timePeriod: true,
+    aboveAverage: true,
+});
+export const isConditionalFormattingOperator = tokenSet({
+    lessThan: true,
+    lessThanOrEqual: true,
+    equal: true,
+    notEqual: true,
+    greaterThanOrEqual: true,
+    greaterThan: true,
+    between: true,
+    notBetween: true,
+    containsText: true,
+    notContains: true,
+    beginsWith: true,
+    endsWith: true,
+});
+export const isCfTimePeriod = tokenSet({
+    today: true,
+    yesterday: true,
+    tomorrow: true,
+    last7Days: true,
+    thisMonth: true,
+    lastMonth: true,
+    nextMonth: true,
+    thisWeek: true,
+    lastWeek: true,
+    nextWeek: true,
+});
+export const isIconSetType = tokenSet({
+    '3Arrows': true,
+    '3ArrowsGray': true,
+    '3Flags': true,
+    '3TrafficLights1': true,
+    '3TrafficLights2': true,
+    '3Signs': true,
+    '3Symbols': true,
+    '3Symbols2': true,
+    '4Arrows': true,
+    '4ArrowsGray': true,
+    '4RedToBlack': true,
+    '4Rating': true,
+    '4TrafficLights': true,
+    '5Arrows': true,
+    '5ArrowsGray': true,
+    '5Rating': true,
+    '5Quarters': true,
+});
 export function cloneConditionalFormatting(cf) {
     return { ref: cf.ref, rules: cf.rules.map(cloneRule) };
 }

package/dist/core/data-validation-overlay.d.ts

@@ -11,6 +11,11 @@ export declare class DataValidationOverlay {
      * (`<x14:dataValidation>`), the carrier Excel uses for a list source on another sheet and other
      * shapes the standard element cannot express. The reader sets it for a rule found in that form so a
      * round-trip writes it back there instead of silently corrupting the cross-sheet reference.
+     *
+     * @throws {AuthoringError} when `sqref` names no area at all. A rule attached to nothing covers no
+     * cell and is written back as the same unreadable text, so it is a mistake worth surfacing at the
+     * call. The reader does not reach this: it drops such an entry at its own boundary, where a foreign
+     * file's malformed attribute is supposed to be dropped.
      */
     add(sqref: string, rule: DataValidation, options?: {
         extended?: boolean;
@@ -23,6 +28,12 @@ export declare class DataValidationOverlay {
      * validations.
      */
     at(col: number, row: number): DataValidation | undefined;
+    /**
+     * Re-anchor every rule through a row or column splice, so a dropdown stays on the cells it was
+     * attached to rather than on whatever moved into their place. A rule whose every target area fell
+     * inside a deleted span is dropped with them.
+     */
+    shift(axis: 'row' | 'col', start: number, count: number, delta: number): void;
     /** Drop every validation, leaving the overlay empty. */
     clear(): void;
 }

package/dist/core/data-validation-overlay.js

@@ -1,15 +1,21 @@
+import { AuthoringError } from '../errors.js';
+import { replaceContents } from './containers.js';
 import { cloneDataValidation, } from './data-validation.js';
-import { decodeSqrefRects } from './merge.js';
+import { decodeSqrefRects, shiftSqref } from './merge.js';
 export class DataValidationOverlay {
     #entries = [];
     #rects = [];
     add(sqref, rule, options = {}) {
+        const rects = decodeSqrefRects(sqref);
+        if (rects.length === 0) {
+            throw new AuthoringError(`data validation range "${sqref}" names no cells`);
+        }
         const stored = cloneDataValidation(rule);
         const entry = { sqref, rule: stored };
         if (options.extended)
             entry.extended = true;
         this.#entries.push(entry);
-        this.#rects.push({ rects: decodeSqrefRects(sqref), rule: stored });
+        this.#rects.push({ rects, rule: stored });
     }
     get entries() {
         return this.#entries;
@@ -24,6 +30,19 @@ export class DataValidationOverlay {
         }
         return undefined;
     }
+    shift(axis, start, count, delta) {
+        const entries = [];
+        const rects = [];
+        for (const entry of this.#entries) {
+            const sqref = shiftSqref(entry.sqref, axis, start, count, delta);
+            if (sqref === undefined)
+                continue;
+            entries.push({ ...entry, sqref });
+            rects.push({ rects: decodeSqrefRects(sqref), rule: entry.rule });
+        }
+        replaceContents(this.#entries, entries);
+        replaceContents(this.#rects, rects);
+    }
     clear() {
         this.#entries.length = 0;
         this.#rects.length = 0;

package/dist/core/data-validation.d.ts

@@ -1,11 +1,18 @@
 /** The kind of constraint a validation enforces. `list` is a dropdown; `custom` is an arbitrary
- * boolean formula; the rest bound a typed value (`whole`/`decimal`/`date`/`time`/`textLength`). */
-export type DataValidationType = 'list' | 'whole' | 'decimal' | 'date' | 'time' | 'textLength' | 'custom';
+ * boolean formula; `none` constrains nothing and exists only to carry the rule's messages; the rest
+ * bound a typed value (`whole`/`decimal`/`date`/`time`/`textLength`). */
+export type DataValidationType = 'none' | 'list' | 'whole' | 'decimal' | 'date' | 'time' | 'textLength' | 'custom';
+/** Narrow a raw `<dataValidation type>` token to a known {@link DataValidationType}. */
+export declare const isDataValidationType: (value: string) => value is DataValidationType;
 /** How a typed validation compares its operand(s). Absent on a `list`/`custom` rule; defaults to
  * `between` on a typed rule (the value Excel omits from the XML). */
 export type DataValidationOperator = 'between' | 'notBetween' | 'equal' | 'notEqual' | 'greaterThan' | 'lessThan' | 'greaterThanOrEqual' | 'lessThanOrEqual';
+/** Narrow a raw `<dataValidation operator>` token to a known {@link DataValidationOperator}. */
+export declare const isDataValidationOperator: (value: string) => value is DataValidationOperator;
 /** How Excel reacts to input that fails the rule. */
 export type DataValidationErrorStyle = 'stop' | 'warning' | 'information';
+/** Narrow a raw `<dataValidation errorStyle>` token to a known {@link DataValidationErrorStyle}. */
+export declare const isDataValidationErrorStyle: (value: string) => value is DataValidationErrorStyle;
 /** One validation rule. `formulae` holds the operand(s), `formula1` then optional `formula2`: a
  * numeric literal is stored as a number, while a cell reference, defined name, or list source keeps
  * its verbatim string. */

package/dist/core/data-validation.js

@@ -1,3 +1,29 @@
+import { tokenSet } from '../token-set.js';
+export const isDataValidationType = tokenSet({
+    none: true,
+    list: true,
+    whole: true,
+    decimal: true,
+    date: true,
+    time: true,
+    textLength: true,
+    custom: true,
+});
+export const isDataValidationOperator = tokenSet({
+    between: true,
+    notBetween: true,
+    equal: true,
+    notEqual: true,
+    greaterThan: true,
+    lessThan: true,
+    greaterThanOrEqual: true,
+    lessThanOrEqual: true,
+});
+export const isDataValidationErrorStyle = tokenSet({
+    stop: true,
+    warning: true,
+    information: true,
+});
 export function cloneDataValidation(rule) {
     return {
         ...rule,

package/dist/core/grid-edits.d.ts

@@ -1,9 +1,21 @@
+import { type AutoFilter } from './autofilter.ts';
 import { Cell } from './cell.ts';
+import type { ConditionalFormattingOverlay } from './conditional-formatting-overlay.ts';
+import type { DataValidationOverlay } from './data-validation-overlay.ts';
 import { type AnchoredImage } from './image.ts';
 import type { MergeRect } from './merge.ts';
 import type { Table } from './table.ts';
 import { type CellValue } from './value.ts';
+import type { WorksheetComments } from './worksheet-comments.ts';
 import type { ColumnProperties, RowProperties } from './worksheet.ts';
+/**
+ * The sheet's autofilter, reached as a slot rather than held by reference like the containers beside
+ * it: it is a single replaceable value, and a splice that deletes every filtered line clears it.
+ */
+export interface AutoFilterSlot {
+    get(): AutoFilter | undefined;
+    set(next: AutoFilter | undefined): void;
+}
 interface GridStorage {
     readonly rows: Map<number, Map<number, Cell>>;
     readonly rowProperties: Map<number, RowProperties>;
@@ -12,6 +24,10 @@ interface GridStorage {
     readonly mergeRects: MergeRect[];
     readonly tables: Table[];
     readonly images: AnchoredImage[];
+    readonly dataValidations: DataValidationOverlay;
+    readonly conditionalFormattings: ConditionalFormattingOverlay;
+    readonly comments: WorksheetComments;
+    readonly autoFilter: AutoFilterSlot;
 }
 export declare class GridEdits {
     #private;

package/dist/core/grid-edits.js

@@ -1,11 +1,10 @@
 import { decodeRange, encodeAddress, tryDecodeCellRef } from './address.js';
+import { shiftAutoFilter } from './autofilter.js';
 import { Cell, copyCellContent } from './cell.js';
 import { replaceContents } from './containers.js';
+import { isDeletedSpan, shiftIndex } from './grid-shift.js';
 import { isOneCellAnchor } from './image.js';
 import { isSharedFormulaValue } from './value.js';
-function shiftIndex(v, start, count, delta) {
-    return v < start ? v : v >= start + count ? v + delta : start;
-}
 export class GridEdits {
     #rows;
     #rowProperties;
@@ -14,6 +13,10 @@ export class GridEdits {
     #mergeRects;
     #tables;
     #images;
+    #dataValidations;
+    #conditionalFormattings;
+    #comments;
+    #autoFilter;
     constructor(storage) {
         this.#rows = storage.rows;
         this.#rowProperties = storage.rowProperties;
@@ -22,6 +25,10 @@ export class GridEdits {
         this.#mergeRects = storage.mergeRects;
         this.#tables = storage.tables;
         this.#images = storage.images;
+        this.#dataValidations = storage.dataValidations;
+        this.#conditionalFormattings = storage.conditionalFormattings;
+        this.#comments = storage.comments;
+        this.#autoFilter = storage.autoFilter;
     }
     spliceRows(start, count, inserted) {
         const delta = inserted.length - count;
@@ -43,6 +50,7 @@ export class GridEdits {
         this.#shiftTables('row', start, count, delta);
         this.#shiftImages('row', start, count, delta);
         this.#reanchorSharedFormulas('row', start, count, delta);
+        this.#shiftRangeBoundOverlays('row', start, count, delta);
     }
     spliceColumns(start, count, inserts) {
         const delta = inserts.length - count;
@@ -74,6 +82,16 @@ export class GridEdits {
         this.#shiftTables('col', start, count, delta);
         this.#shiftImages('col', start, count, delta);
         this.#reanchorSharedFormulas('col', start, count, delta);
+        this.#shiftRangeBoundOverlays('col', start, count, delta);
+    }
+    #shiftRangeBoundOverlays(axis, start, count, delta) {
+        this.#dataValidations.shift(axis, start, count, delta);
+        this.#conditionalFormattings.shift(axis, start, count, delta);
+        this.#comments.shift(axis, start, count, delta);
+        const filter = this.#autoFilter.get();
+        if (filter !== undefined) {
+            this.#autoFilter.set(shiftAutoFilter(filter, axis, start, count, delta));
+        }
     }
     #relocateRow(cols, destRow) {
         const moved = new Map();
@@ -99,8 +117,8 @@ export class GridEdits {
                 if (master === undefined)
                     continue;
                 const anchored = axis === 'row'
-                    ? encodeAddress(master.col, shiftIndex(master.row, start, count, delta))
-                    : encodeAddress(shiftIndex(master.col, start, count, delta), master.row);
+                    ? encodeAddress(master.col, shiftIndex(master.row, start, count, delta, 'row'))
+                    : encodeAddress(shiftIndex(master.col, start, count, delta, 'col'), master.row);
                 if (anchored === value.sharedFormula)
                     continue;
                 const reanchored = { ...value, sharedFormula: anchored };
@@ -121,7 +139,7 @@ export class GridEdits {
             map.set(index, value);
     }
     #shiftMerges(axis, start, count, delta) {
-        const shift = (v) => shiftIndex(v, start, count, delta);
+        const shift = (v) => shiftIndex(v, start, count, delta, axis);
         const merges = [];
         const rects = [];
         for (const range of this.#merges) {
@@ -131,7 +149,7 @@ export class GridEdits {
                 continue;
             }
             const [lo, hi] = axis === 'row' ? [top, bottom] : [left, right];
-            if (lo >= start && hi < start + count)
+            if (isDeletedSpan(lo, hi, start, count))
                 continue;
             const rect = axis === 'row'
                 ? { top: shift(top), left, bottom: shift(bottom), right }
@@ -151,7 +169,7 @@ export class GridEdits {
     #shiftImages(axis, start, count, delta) {
         const shiftPoint = (point) => {
             const zeroBased = axis === 'row' ? point.row : point.col;
-            const shifted = shiftIndex(zeroBased + 1, start, count, delta) - 1;
+            const shifted = shiftIndex(zeroBased + 1, start, count, delta, axis) - 1;
             if (shifted === zeroBased)
                 return point;
             return axis === 'row' ? { ...point, row: shifted } : { ...point, col: shifted };

package/dist/core/grid-shift.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Where a 1-based coordinate on `axis` lands after `count` lines are deleted at `start` and the
+ * replacement lines shift what follows by `delta`: before the edit it stays put, at or after the
+ * edited span it shifts, and inside a deleted span it clamps to the cut line. The clamp is the best
+ * effort for a geometry straddling the cut; a caller that must instead *drop* what a delete swallowed
+ * whole tests {@link isDeletedSpan} first.
+ *
+ * A shift never leaves the grid: the result is clamped to the axis's last line, so a region already
+ * touching the bottom (or the right edge) keeps its edge there instead of naming a line the format
+ * has no room for. That shrinks such a region by what it could not move, which is the lesser of the
+ * two evils and is what Excel does to the same region on the same edit.
+ */
+export declare function shiftIndex(v: number, start: number, count: number, delta: number, axis: 'row' | 'col'): number;
+/**
+ * Whether the inclusive span `lo..hi` lies entirely within the `count` lines deleted at `start`: the
+ * test that separates "this moved" from "this is gone". A single coordinate is the degenerate span
+ * `lo === hi`.
+ */
+export declare function isDeletedSpan(lo: number, hi: number, start: number, count: number): boolean;

package/dist/core/grid-shift.js

@@ -0,0 +1,8 @@
+import { MAX_COLUMN, MAX_ROW } from './address.js';
+export function shiftIndex(v, start, count, delta, axis) {
+    const moved = v < start ? v : v >= start + count ? v + delta : start;
+    return Math.min(moved, axis === 'row' ? MAX_ROW : MAX_COLUMN);
+}
+export function isDeletedSpan(lo, hi, start, count) {
+    return lo >= start && hi < start + count;
+}

package/dist/core/image.d.ts

@@ -17,6 +17,8 @@ export declare const PX_TO_EMU = 9525;
  * them; `oneCell` moves but keeps its size; `absolute` is pinned to the page and does neither. Excel
  * defaults to `oneCell` when the attribute is omitted. */
 export type ImageEditAs = 'oneCell' | 'twoCell' | 'absolute';
+/** Narrow a raw `<xdr:twoCellAnchor editAs>` token to a known {@link ImageEditAs}. */
+export declare const isImageEditAs: (value: string) => value is ImageEditAs;
 /** A fixed image size in EMUs: the extent of a one-cell anchor, which pixel dimensions convert into
  * via {@link PX_TO_EMU}. */
 export interface Extent {

package/dist/core/image.js

@@ -1,4 +1,6 @@
+import { tokenSet } from '../token-set.js';
 export const PX_TO_EMU = 9525;
+export const isImageEditAs = tokenSet({ oneCell: true, twoCell: true, absolute: true });
 export function isOneCellAnchor(anchor) {
     return 'ext' in anchor;
 }

package/dist/core/merge-index.d.ts

@@ -0,0 +1,31 @@
+import { type GridRect } from './address.ts';
+import type { MergeRect } from './merge.ts';
+/**
+ * A row-banded index over a sheet's merged regions. Holds the region list by reference and never
+ * mutates it: the sheet stays the owner, reports what it adds, and says when it has rewritten the
+ * list wholesale (a splice, an unmerge, a model assignment), which the index answers by rebuilding
+ * on the next query rather than by tracking the edit.
+ */
+export declare class MergeIndex {
+    #private;
+    constructor(rects: readonly MergeRect[]);
+    /** Note a region added to the list. Ignored while stale: the rebuild reads the list itself. */
+    note(rect: MergeRect): void;
+    /** Report that the region list has been rewritten from outside this index. */
+    invalidate(): void;
+    /**
+     * The region overlapping `rect`, or `undefined` when the rectangle is free. Which of several
+     * overlapping regions is returned is unspecified beyond being one of them; a sheet admits no
+     * overlap, so at most one ever applies.
+     */
+    overlapping(rect: GridRect): MergeRect | undefined;
+    /**
+     * Resolve a position to the top-left of the merged region covering it, or to itself when no region
+     * does. Only fully-bounded regions participate: an unbounded whole-row/column merge carries no
+     * rectangle and so resolves nothing.
+     */
+    masterOf(row: number, col: number): {
+        row: number;
+        col: number;
+    };
+}

package/dist/core/merge-index.js

@@ -0,0 +1,60 @@
+import { rectsOverlap } from './address.js';
+const BAND_ROWS = 64;
+function bandOf(row) {
+    return Math.floor(row / BAND_ROWS);
+}
+export class MergeIndex {
+    #rects;
+    #bands = new Map();
+    #tallest = 0;
+    #stale = true;
+    constructor(rects) {
+        this.#rects = rects;
+    }
+    note(rect) {
+        if (!this.#stale)
+            this.#place(rect);
+    }
+    invalidate() {
+        this.#stale = true;
+    }
+    overlapping(rect) {
+        this.#refresh();
+        const first = bandOf(Math.max(1, rect.top - this.#tallest + 1));
+        const last = bandOf(rect.bottom);
+        for (let band = first; band <= last; band++) {
+            const bucket = this.#bands.get(band);
+            if (bucket === undefined)
+                continue;
+            for (const candidate of bucket) {
+                if (rectsOverlap(candidate, rect))
+                    return candidate;
+            }
+        }
+        return undefined;
+    }
+    masterOf(row, col) {
+        const covering = this.overlapping({ top: row, left: col, bottom: row, right: col });
+        return covering === undefined ? { row, col } : { row: covering.top, col: covering.left };
+    }
+    #place(rect) {
+        const height = rect.bottom - rect.top + 1;
+        if (height > this.#tallest)
+            this.#tallest = height;
+        const band = bandOf(rect.top);
+        const bucket = this.#bands.get(band);
+        if (bucket === undefined)
+            this.#bands.set(band, [rect]);
+        else
+            bucket.push(rect);
+    }
+    #refresh() {
+        if (!this.#stale)
+            return;
+        this.#stale = false;
+        this.#bands = new Map();
+        this.#tallest = 0;
+        for (const rect of this.#rects)
+            this.#place(rect);
+    }
+}

package/dist/core/merge.d.ts

@@ -2,16 +2,6 @@ import { type GridRect } from './address.ts';
 import type { Cell } from './cell.ts';
 /** A merged region, as the {@link GridRect} every range-shaped thing in the library is. */
 export type MergeRect = GridRect;
-/**
- * Resolve a position to the master (top-left) of the merged region covering it, or to itself when no
- * region does. First covering region wins; `Worksheet.mergeCells` rejects overlaps, so at most one
- * region ever applies. Only fully-bounded rects participate: an unbounded whole-row/column merge
- * carries no rect and so resolves nothing.
- */
-export declare function masterOf(rects: readonly MergeRect[], row: number, col: number): {
-    row: number;
-    col: number;
-};
 /**
  * Drop any value already sitting in a merge's covered non-anchor cells, keeping only the top-left
  * anchor, the collapse Excel performs on merge. A leftover covered value would serialise as a
@@ -21,5 +11,16 @@ export declare function masterOf(rects: readonly MergeRect[], row: number, col:
 export declare function clearCoveredValues(rows: Map<number, Map<number, Cell>>, rect: MergeRect): void;
 /** Decode an OOXML `sqref` (one or more space-separated ranges) into containment rectangles. A whole
  * column or row leaves one axis unbounded, so its missing edges open to `Infinity` rather than
- * clamping: a cell anywhere down the column still resolves inside it. */
+ * clamping: a cell anywhere down the column still resolves inside it. An area that names no region
+ * that can exist contributes no rectangle, the reader's rule for every other foreign attribute. */
 export declare function decodeSqrefRects(sqref: string): MergeRect[];
+/**
+ * Re-anchor an OOXML `sqref` through a splice of `count` lines at `start` on `axis`, the inverse of
+ * {@link decodeSqrefRects}. Returns `undefined` when the splice deleted every area the `sqref` named:
+ * an empty `sqref` is not writable, so the entry holding it goes too.
+ *
+ * Each space-separated area shifts on its own, and one the splice does not move is returned as the
+ * *original text*. That matters for a file the library did not author: `B:B` and `B1:B1048576` decode
+ * identically, so a re-encode would rewrite a foreign spelling and cost the byte-clean round trip.
+ */
+export declare function shiftSqref(sqref: string, axis: 'row' | 'col', start: number, count: number, delta: number): string | undefined;

package/dist/core/merge.js

@@ -1,12 +1,5 @@
-import { decodeRange } from './address.js';
-export function masterOf(rects, row, col) {
-    for (const rect of rects) {
-        if (row >= rect.top && row <= rect.bottom && col >= rect.left && col <= rect.right) {
-            return { row: rect.top, col: rect.left };
-        }
-    }
-    return { row, col };
-}
+import { encodeCornerRef, tryDecodeRange } from './address.js';
+import { isDeletedSpan, shiftIndex } from './grid-shift.js';
 export function clearCoveredValues(rows, rect) {
     for (let row = rect.top; row <= rect.bottom; row++) {
         const cols = rows.get(row);
@@ -26,7 +19,10 @@ export function decodeSqrefRects(sqref) {
     for (const part of sqref.split(/\s+/)) {
         if (part === '')
             continue;
-        const { top, left, bottom, right } = decodeRange(part);
+        const decoded = tryDecodeRange(part);
+        if (decoded === undefined)
+            continue;
+        const { top, left, bottom, right } = decoded;
         rects.push({
             top: top ?? 1,
             left: left ?? 1,
@@ -36,3 +32,33 @@ export function decodeSqrefRects(sqref) {
     }
     return rects;
 }
+export function shiftSqref(sqref, axis, start, count, delta) {
+    const areas = [];
+    for (const area of sqref.split(/\s+/)) {
+        if (area === '')
+            continue;
+        const shifted = shiftSqrefArea(area, axis, start, count, delta);
+        if (shifted !== undefined)
+            areas.push(shifted);
+    }
+    return areas.length > 0 ? areas.join(' ') : undefined;
+}
+function shiftSqrefArea(area, axis, start, count, delta) {
+    const decoded = tryDecodeRange(area);
+    if (decoded === undefined)
+        return area;
+    const { top, left, bottom, right } = decoded;
+    const [lo, hi] = axis === 'row' ? [top, bottom] : [left, right];
+    if (lo === undefined || hi === undefined)
+        return area;
+    if (isDeletedSpan(lo, hi, start, count))
+        return undefined;
+    const movedLo = shiftIndex(lo, start, count, delta, axis);
+    const movedHi = shiftIndex(hi, start, count, delta, axis);
+    if (movedLo === lo && movedHi === hi)
+        return area;
+    const [tl, br] = axis === 'row'
+        ? [encodeCornerRef(left, movedLo), encodeCornerRef(right, movedHi)]
+        : [encodeCornerRef(movedLo, top), encodeCornerRef(movedHi, bottom)];
+    return area.includes(':') ? `${tl}:${br}` : tl;
+}