@rowsncolumns/spreadsheet-state 29.0.0 → 29.1.1

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

@@ -1,10 +1,24 @@
-import type { ColorFilterCriteria, ConditionType, ConditionValue, FilterSpec, IconFilterCriteria } from "@rowsncolumns/spreadsheet";
+import type { BooleanCondition, ColorFilterCriteria, ConditionType, ConditionValue, FilterConditionJoin, FilterCriteria, FilterSpec, IconFilterCriteria } from "@rowsncolumns/spreadsheet";
 export type CreateFilterSpecsExtras = {
     /** Pass `null` to clear an existing color filter on this column. */
     colorFilter?: ColorFilterCriteria | null;
     /** Pass `null` to clear an existing icon filter on this column. */
     iconFilter?: IconFilterCriteria | null;
+    /**
+     * Custom AutoFilter second clause + join (Excel's And / Or). Pass `null`
+     * to drop an existing second clause; omit to preserve it.
+     */
+    condition2?: BooleanCondition | null;
+    conditionJoin?: FilterConditionJoin | null;
 };
+/**
+ * Whether a column's criteria still filter anything. An entry with no
+ * condition, no value whitelist and no color / icon criterion is inert, so
+ * `createFilterSpecs` drops it — Excel's "Clear Filter From <column>" —
+ * instead of leaving a stale spec behind (the rnc engine's
+ * `upsert_filter_spec` removes such entries the same way).
+ */
+export declare const isFilterCriteriaActive: (criteria: FilterCriteria) => boolean;
 /**
  * Create a new filterspec
  * @param filterSpecs

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

@@ -1 +1 @@
-{"version":3,"file":"filter.d.ts","sourceRoot":"","sources":["../../../api/filter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,mBAAmB,EACnB,aAAa,EACb,cAAc,EACd,UAAU,EACV,kBAAkB,EACnB,MAAM,2BAA2B,CAAC;AAEnC,MAAM,MAAM,uBAAuB,GAAG;IACpC,oEAAoE;IACpE,WAAW,CAAC,EAAE,mBAAmB,GAAG,IAAI,CAAC;IACzC,mEAAmE;IACnE,UAAU,CAAC,EAAE,kBAAkB,GAAG,IAAI,CAAC;CACxC,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,iBAAiB,GAC5B,aAAa,UAAU,EAAE,GAAG,SAAS,EACrC,aAAa,MAAM,EACnB,eAAe,aAAa,GAAG,SAAS,EACxC,iBAAiB,cAAc,EAAE,GAAG,SAAS,EAC7C,eAAe,MAAM,EAAE,GAAG,SAAS,GAAG,IAAI,EAC1C,SAAQ,uBAA4B,KACnC,UAAU,EAuCZ,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,8BAA8B,GACzC,cAAa,UAAU,EAAO,+BAO/B,CAAC"}
+{"version":3,"file":"filter.d.ts","sourceRoot":"","sources":["../../../api/filter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,gBAAgB,EAChB,mBAAmB,EACnB,aAAa,EACb,cAAc,EACd,mBAAmB,EACnB,cAAc,EACd,UAAU,EACV,kBAAkB,EACnB,MAAM,2BAA2B,CAAC;AAEnC,MAAM,MAAM,uBAAuB,GAAG;IACpC,oEAAoE;IACpE,WAAW,CAAC,EAAE,mBAAmB,GAAG,IAAI,CAAC;IACzC,mEAAmE;IACnE,UAAU,CAAC,EAAE,kBAAkB,GAAG,IAAI,CAAC;IACvC;;;OAGG;IACH,UAAU,CAAC,EAAE,gBAAgB,GAAG,IAAI,CAAC;IACrC,aAAa,CAAC,EAAE,mBAAmB,GAAG,IAAI,CAAC;CAC5C,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB,GAAI,UAAU,cAAc,KAAG,OAO/D,CAAC;AAEJ;;;;;;;;GAQG;AACH,eAAO,MAAM,iBAAiB,GAC5B,aAAa,UAAU,EAAE,GAAG,SAAS,EACrC,aAAa,MAAM,EACnB,eAAe,aAAa,GAAG,SAAS,EACxC,iBAAiB,cAAc,EAAE,GAAG,SAAS,EAC7C,eAAe,MAAM,EAAE,GAAG,SAAS,GAAG,IAAI,EAC1C,SAAQ,uBAA4B,KACnC,UAAU,EAuDZ,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,8BAA8B,GACzC,cAAa,UAAU,EAAO,+BAO/B,CAAC"}

package/dist/cjs/api/filter.js

@@ -1,4 +1,19 @@
 import { __assign, __read, __spreadArray, __values } from "tslib";
+/**
+ * Whether a column's criteria still filter anything. An entry with no
+ * condition, no value whitelist and no color / icon criterion is inert, so
+ * `createFilterSpecs` drops it — Excel's "Clear Filter From <column>" —
+ * instead of leaving a stale spec behind (the rnc engine's
+ * `upsert_filter_spec` removes such entries the same way).
+ */
+export var isFilterCriteriaActive = function (criteria) {
+    var _a, _b, _c;
+    return Boolean(((_a = criteria.condition) === null || _a === void 0 ? void 0 : _a.type) ||
+        ((_b = criteria.condition2) === null || _b === void 0 ? void 0 : _b.type) ||
+        ((_c = criteria.visibleValues) === null || _c === void 0 ? void 0 : _c.length) ||
+        criteria.colorFilter ||
+        criteria.iconFilter);
+};
 /**
  * Create a new filterspec
  * @param filterSpecs
@@ -9,13 +24,13 @@ import { __assign, __read, __spreadArray, __values } from "tslib";
  * @param extras Optional colorFilter / iconFilter criteria.
  */
 export var createFilterSpecs = function (filterSpecs, columnIndex, conditionType, conditionValues, visibleValues, extras) {
-    var _a, _b;
+    var _a, _b, _c, _d;
     if (extras === void 0) { extras = {}; }
     var exists = filterSpecs === null || filterSpecs === void 0 ? void 0 : filterSpecs.find(function (spec) { return spec.columnIndex === columnIndex; });
     // Spec
     var filterSpec = {
         columnIndex: columnIndex,
-        filterCriteria: __assign(__assign({ condition: {
+        filterCriteria: __assign(__assign(__assign({ condition: {
                 type: conditionType,
                 values: conditionValues,
             }, visibleValues: visibleValues }, (extras.colorFilter !== undefined
@@ -26,8 +41,23 @@ export var createFilterSpecs = function (filterSpecs, columnIndex, conditionType
             ? { iconFilter: (_b = extras.iconFilter) !== null && _b !== void 0 ? _b : undefined }
             : (exists === null || exists === void 0 ? void 0 : exists.filterCriteria.iconFilter)
                 ? { iconFilter: exists.filterCriteria.iconFilter }
+                : {})), (extras.condition2 !== undefined
+            ? extras.condition2
+                ? {
+                    condition2: extras.condition2,
+                    conditionJoin: (_c = extras.conditionJoin) !== null && _c !== void 0 ? _c : "AND",
+                }
+                : {}
+            : (exists === null || exists === void 0 ? void 0 : exists.filterCriteria.condition2)
+                ? {
+                    condition2: exists.filterCriteria.condition2,
+                    conditionJoin: (_d = exists.filterCriteria.conditionJoin) !== null && _d !== void 0 ? _d : "AND",
+                }
                 : {})),
     };
+    if (!isFilterCriteriaActive(filterSpec.filterCriteria)) {
+        return (filterSpecs !== null && filterSpecs !== void 0 ? filterSpecs : []).filter(function (spec) { return spec.columnIndex !== columnIndex; });
+    }
     if (exists && filterSpecs) {
         return filterSpecs.map(function (spec) {
             if (spec.columnIndex === columnIndex) {

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

@@ -1,3 +1,4 @@
+import type { GridRange } from "@rowsncolumns/common-types";
 import type { ParsedToken } from "@rowsncolumns/spreadsheet";
 export { ERROR_CIRCULAR_DEPENDENCY, ERROR_REFERENCE, formulaToRelativeReference, } from "@rowsncolumns/calculator";
 export type { FormulaToRelativeReferenceOptions } from "@rowsncolumns/calculator";
@@ -39,6 +40,68 @@ export declare const breakTableReferencesInFormula: (formulaValue: string, table
  * `=Table1[@#REF!]*2`). Keeps every other character of the reference as typed.
  */
 export declare const breakTableColumnsInFormula: (formulaValue: string, tableName: string | undefined, columnNames: string[]) => string;
+/**
+ * Rename the column `oldName` → `newName` inside the 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): `Table1[Qty]`,
+ * `[@Qty]`, `Table1[[#Headers],[Qty]]` and `Table1[[Qty]:[Price]]` all follow
+ * a header-cell edit in Excel. Column names compare case-insensitively; every
+ * other character of the reference is kept as typed.
+ */
+export declare const renameTableColumnInFormula: (formulaValue: string, tableName: string | undefined, oldName: string, newName: string) => string;
+/**
+ * Rename several columns of `tableName` at once — `renames` maps each
+ * LOWER-CASED old name to its new name. One pass over the formula, so
+ * `Name` → `Qty` and `Qty` → `Name` swap instead of chaining into the same
+ * column (a header row re-derived after a row delete, or several header cells
+ * written by one paste / change-batch).
+ */
+export declare const renameTableColumnsInFormula: (formulaValue: string, tableName: string | undefined, renames: ReadonlyMap<string, string>) => string;
+/**
+ * Rename the table `oldName` → `newName` in every structured reference
+ * (`Old[Col]`, `Old[@Col]`, `Old[[#Headers],[Col]]`, `Old[#All]`) — Excel
+ * rewrites them all when a table is renamed. Table names compare
+ * case-insensitively; the bare `[@Col]` form names no table and is left alone.
+ */
+export declare const renameTableInFormula: (formulaValue: string, oldName: string, newName: string) => string;
+/**
+ * Rename several tables at once — `renames` maps each LOWER-CASED old name to
+ * its new name. One pass, so `Sales` → `Sales2` and `Sales2` → `Sales3` never
+ * chain (a sheet duplicated with both tables re-points each reference exactly
+ * once).
+ */
+export declare const renameTablesInFormula: (formulaValue: string, renames: ReadonlyMap<string, string>) => string;
+/** The table geometry a structured reference resolves against — the `TableView` fields that matter. */
+export type StructuredRefTable = {
+    title: string;
+    range: GridRange;
+    headerRow?: boolean | null;
+    totalRow?: boolean | null;
+    /** Column names in header order. */
+    columnNames: string[];
+};
+export type ConvertStructuredRefsOptions = {
+    /** Name of the sheet the table lives on. */
+    tableSheetName: string;
+    /** Name of the sheet the formula cell lives on — the reference is sheet-qualified when it differs. */
+    formulaSheetName: string;
+    /** Row of the formula cell: what a this-row item (`[@Col]`) resolves to. */
+    formulaRowIndex: number;
+    /** Whether the formula cell sits inside the table, which the bare `[@Col]` / `[Col]` forms name. */
+    inTable: boolean;
+};
+/**
+ * Rewrite every structured reference into `table` — `T[Col]`, `T[[#Headers],[Col]]`, `T[#All]`,
+ * `T[[A]:[B]]`, `T[@Col]`, `T[[#This Row],[Col]]` and, inside the table, the bare `[@Col]` /
+ * `[Col]` forms — to the plain A1 reference it resolves to, the way Excel's Convert to Range
+ * rewrites formulas so their values keep working once the table is gone. Column, header, totals
+ * and whole-table items become absolute (`$B$2:$B$9`, `$B$1`), this-row items the relative
+ * same-row reference (`B3`), and the reference is qualified with the table's sheet when the
+ * formula lives on another one. A reference that cannot resolve (an unknown column, `#Headers`
+ * on a headerless table, `@` outside the table's data rows) becomes the `#REF!` it would have
+ * evaluated to. Returns the input unchanged when the formula never references the table.
+ */
+export declare const convertStructuredRefsToA1InFormula: (formulaValue: string, table: StructuredRefTable, options: ConvertStructuredRefsOptions) => string;
 /**
  * Converts tokens to string
  * @param tokens

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

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

package/dist/cjs/api/formula.js

@@ -1,5 +1,5 @@
-import { __assign, __read, __values } from "tslib";
-import { cleanupColumnName, cleanupTableName, isRangeToken, lexify, stripPropertyFromCellRef, tokenVocabulary, } from "@rowsncolumns/calculator";
+import { __assign, __read, __spreadArray, __values } from "tslib";
+import { cleanupColumnName, cleanupSpecialItem, cleanupTableName, detectCurrentRow, 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";
 /**
@@ -193,10 +193,99 @@ export var breakTableReferencesInFormula = function (formulaValue, tableName) {
  * `=Table1[@#REF!]*2`). Keeps every other character of the reference as typed.
  */
 export var breakTableColumnsInFormula = function (formulaValue, tableName, columnNames) {
-    if (!formulaValue.includes("[") || columnNames.length === 0) {
+    return replaceTableColumnsInFormula(formulaValue, tableName, columnNames, REF_ERROR_COLUMN);
+};
+/**
+ * Rename the column `oldName` → `newName` inside the 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): `Table1[Qty]`,
+ * `[@Qty]`, `Table1[[#Headers],[Qty]]` and `Table1[[Qty]:[Price]]` all follow
+ * a header-cell edit in Excel. Column names compare case-insensitively; every
+ * other character of the reference is kept as typed.
+ */
+export var renameTableColumnInFormula = function (formulaValue, tableName, oldName, newName) {
+    return oldName && newName && oldName !== newName
+        ? renameTableColumnsInFormula(formulaValue, tableName, new Map([[oldName.toLowerCase(), newName]]))
+        : formulaValue;
+};
+/**
+ * Rename several columns of `tableName` at once — `renames` maps each
+ * LOWER-CASED old name to its new name. One pass over the formula, so
+ * `Name` → `Qty` and `Qty` → `Name` swap instead of chaining into the same
+ * column (a header row re-derived after a row delete, or several header cells
+ * written by one paste / change-batch).
+ */
+export var renameTableColumnsInFormula = function (formulaValue, tableName, renames) {
+    return rewriteTableColumnsInFormula(formulaValue, tableName, function (name) {
+        return renames.get(name);
+    });
+};
+/**
+ * Rename the table `oldName` → `newName` in every structured reference
+ * (`Old[Col]`, `Old[@Col]`, `Old[[#Headers],[Col]]`, `Old[#All]`) — Excel
+ * rewrites them all when a table is renamed. Table names compare
+ * case-insensitively; the bare `[@Col]` form names no table and is left alone.
+ */
+export var renameTableInFormula = function (formulaValue, oldName, newName) {
+    if (!oldName || !newName || oldName === newName) {
+        return formulaValue;
+    }
+    return renameTablesInFormula(formulaValue, new Map([[oldName.toLowerCase(), newName]]));
+};
+/**
+ * Rename several tables at once — `renames` maps each LOWER-CASED old name to
+ * its new name. One pass, so `Sales` → `Sales2` and `Sales2` → `Sales3` never
+ * chain (a sheet duplicated with both tables re-points each reference exactly
+ * once).
+ */
+export var renameTablesInFormula = function (formulaValue, renames) {
+    var e_5, _a;
+    if (!formulaValue.includes("[") || renames.size === 0) {
+        return formulaValue;
+    }
+    var tokens = cloneTokens(lexify(formulaValue).tokens);
+    var hasChanges = false;
+    try {
+        for (var tokens_4 = __values(tokens), tokens_4_1 = tokens_4.next(); !tokens_4_1.done; tokens_4_1 = tokens_4.next()) {
+            var token = tokens_4_1.value;
+            if (!isTableNameToken(token))
+                continue;
+            var newName = renames.get(cleanupTableName(token.image).trim().toLowerCase());
+            if (newName === undefined)
+                continue;
+            // The image is the name as typed plus its opening bracket.
+            token.image = newName + token.image.slice(token.image.indexOf("["));
+            hasChanges = true;
+        }
+    }
+    catch (e_5_1) { e_5 = { error: e_5_1 }; }
+    finally {
+        try {
+            if (tokens_4_1 && !tokens_4_1.done && (_a = tokens_4.return)) _a.call(tokens_4);
+        }
+        finally { if (e_5) throw e_5.error; }
+    }
+    return hasChanges ? detokenize(tokens) : formulaValue;
+};
+var replaceTableColumnsInFormula = function (formulaValue, tableName, columnNames, replacement) {
+    if (columnNames.length === 0) {
         return formulaValue;
     }
     var targets = new Set(columnNames.map(function (name) { return name.toLowerCase(); }));
+    return rewriteTableColumnsInFormula(formulaValue, tableName, function (name) {
+        return targets.has(name) ? replacement : undefined;
+    });
+};
+/**
+ * Rewrite the column items of every structured reference into `tableName`
+ * (or, when undefined, the bare `[@Col]` forms) through `resolve`, which maps
+ * a LOWER-CASED column name to its replacement or `undefined` to leave it.
+ * Each item is resolved once, so a set of renames applies in a single pass.
+ */
+var rewriteTableColumnsInFormula = function (formulaValue, tableName, resolve) {
+    if (!formulaValue.includes("[")) {
+        return formulaValue;
+    }
     var target = tableName === null || tableName === void 0 ? void 0 : tableName.toLowerCase();
     var tokens = cloneTokens(lexify(formulaValue).tokens);
     var hasChanges = false;
@@ -209,8 +298,9 @@ export var breakTableColumnsInFormula = function (formulaValue, tableName, colum
                 cleanupTableName(token.image).trim().toLowerCase() === target;
             if (matches) {
                 for (var j = i + 1; j < end; j++) {
-                    if (breakColumnToken(tokens[j], targets))
+                    if (replaceColumnToken(tokens[j], resolve)) {
                         hasChanges = true;
+                    }
                 }
             }
             i = end;
@@ -218,26 +308,206 @@ export var breakTableColumnsInFormula = function (formulaValue, tableName, colum
         }
         // A bare `[@Col]` / `[Col]` names the table the formula cell sits in.
         if (target === undefined && isTableColumnToken(token)) {
-            if (breakColumnToken(token, targets))
+            if (replaceColumnToken(token, resolve))
                 hasChanges = true;
         }
         i++;
     }
     return hasChanges ? detokenize(tokens) : formulaValue;
 };
-var breakColumnToken = function (token, targets) {
+var replaceColumnToken = function (token, resolve) {
     if (!token || !isTableColumnToken(token))
         return false;
     var name = cleanupColumnName(token.image);
-    if (!name || !targets.has(name.toLowerCase()))
+    if (!name)
+        return false;
+    var replacement = resolve(name.toLowerCase());
+    if (replacement === undefined)
         return false;
     var 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);
+        token.image.slice(0, at) + replacement + token.image.slice(at + name.length);
     return true;
 };
+/**
+ * Rewrite every structured reference into `table` — `T[Col]`, `T[[#Headers],[Col]]`, `T[#All]`,
+ * `T[[A]:[B]]`, `T[@Col]`, `T[[#This Row],[Col]]` and, inside the table, the bare `[@Col]` /
+ * `[Col]` forms — to the plain A1 reference it resolves to, the way Excel's Convert to Range
+ * rewrites formulas so their values keep working once the table is gone. Column, header, totals
+ * and whole-table items become absolute (`$B$2:$B$9`, `$B$1`), this-row items the relative
+ * same-row reference (`B3`), and the reference is qualified with the table's sheet when the
+ * formula lives on another one. A reference that cannot resolve (an unknown column, `#Headers`
+ * on a headerless table, `@` outside the table's data rows) becomes the `#REF!` it would have
+ * evaluated to. Returns the input unchanged when the formula never references the table.
+ */
+export var convertStructuredRefsToA1InFormula = function (formulaValue, table, options) {
+    if (!formulaValue.includes("["))
+        return formulaValue;
+    var target = table.title.toLowerCase();
+    var tokens = cloneTokens(lexify(formulaValue).tokens);
+    var newTokens = [];
+    var hasChanges = false;
+    var i = 0;
+    while (i < tokens.length) {
+        var token = tokens[i];
+        if (isTableNameToken(token)) {
+            var end = structuredReferenceEnd(tokens, i);
+            if (cleanupTableName(token.image).trim().toLowerCase() !== target) {
+                // Another table's reference: keep it whole (its `@Col` items are not bare forms).
+                newTokens.push.apply(newTokens, __spreadArray([], __read(tokens.slice(i, end)), false));
+                i = end;
+                continue;
+            }
+            newTokens.push(collapseToReference(token, tokens[end - 1], resolveStructuredReference(table, tokens.slice(i + 1, end), options)));
+            hasChanges = true;
+            i = end;
+            continue;
+        }
+        // A bare `[@Col]` / `[Col]` names the table the formula cell sits in.
+        if (options.inTable &&
+            isTableColumnToken(token) &&
+            token.image.startsWith("[")) {
+            var end = structuredReferenceEnd(tokens, i);
+            newTokens.push(collapseToReference(token, tokens[end - 1], resolveStructuredReference(table, tokens.slice(i, end), options)));
+            hasChanges = true;
+            i = end;
+            continue;
+        }
+        newTokens.push(token);
+        i++;
+    }
+    return hasChanges ? detokenize(newTokens) : formulaValue;
+};
+/** One reference token (or `#REF!`) standing in for the run `start … end` (see `collapseToRefError`). */
+var collapseToReference = function (start, end, image) {
+    var _a, _b;
+    return (__assign(__assign({}, start), { image: image, tokenType: image === REF_ERROR_TOKEN
+            ? tokenVocabulary.RefError
+            : tokenVocabulary.Cell, endOffset: (_a = end === null || end === void 0 ? void 0 : end.endOffset) !== null && _a !== void 0 ? _a : start.endOffset, endColumn: (_b = end === null || end === void 0 ? void 0 : end.endColumn) !== null && _b !== void 0 ? _b : start.endColumn }));
+};
+/**
+ * The A1 text the structured-reference `specifier` tokens (everything after the table name up to
+ * the closing bracket, or the bare column form) resolve to against `table`, or `#REF!`.
+ */
+var resolveStructuredReference = function (table, specifier, _a) {
+    var e_6, _b, _c, e_7, _d;
+    var _e, _f;
+    var tableSheetName = _a.tableSheetName, formulaSheetName = _a.formulaSheetName, formulaRowIndex = _a.formulaRowIndex;
+    var thisRow = false;
+    var items = new Set();
+    var columns = [];
+    try {
+        for (var specifier_1 = __values(specifier), specifier_1_1 = specifier_1.next(); !specifier_1_1.done; specifier_1_1 = specifier_1.next()) {
+            var token = specifier_1_1.value;
+            var name_1 = token.tokenType.name;
+            if (name_1 === tokenVocabulary.SpecialItem.name) {
+                var item = cleanupSpecialItem(token.image).trim().toLowerCase();
+                if (item === "#this row")
+                    thisRow = true;
+                else
+                    items.add(item);
+            }
+            else if (name_1 === tokenVocabulary.TableColumnName.name) {
+                if (detectCurrentRow(token.image))
+                    thisRow = true;
+                var column = cleanupColumnName(token.image).trim();
+                if (column)
+                    columns.push(column);
+            }
+            else if (name_1 === tokenVocabulary.At.name) {
+                thisRow = true;
+            }
+        }
+    }
+    catch (e_6_1) { e_6 = { error: e_6_1 }; }
+    finally {
+        try {
+            if (specifier_1_1 && !specifier_1_1.done && (_b = specifier_1.return)) _b.call(specifier_1);
+        }
+        finally { if (e_6) throw e_6.error; }
+    }
+    var range = table.range;
+    var headerRow = (_e = table.headerRow) !== null && _e !== void 0 ? _e : true;
+    var totalRow = (_f = table.totalRow) !== null && _f !== void 0 ? _f : false;
+    var dataStartRowIndex = range.startRowIndex + (headerRow ? 1 : 0);
+    var dataEndRowIndex = range.endRowIndex - (totalRow ? 1 : 0);
+    // Column span: the named column, or the `[A]:[B]` pair (either order); none → every column.
+    var startColumnIndex = range.startColumnIndex;
+    var endColumnIndex = range.endColumnIndex;
+    if (columns.length) {
+        if (columns.length > 2)
+            return REF_ERROR_TOKEN;
+        var offsets = columns.map(function (column) {
+            return table.columnNames.findIndex(function (candidate) { return candidate.toLowerCase() === column.toLowerCase(); });
+        });
+        if (offsets.some(function (offset) { return offset === -1; }))
+            return REF_ERROR_TOKEN;
+        startColumnIndex = range.startColumnIndex + Math.min.apply(Math, __spreadArray([], __read(offsets), false));
+        endColumnIndex = range.startColumnIndex + Math.max.apply(Math, __spreadArray([], __read(offsets), false));
+    }
+    // Row band.
+    var startRowIndex;
+    var endRowIndex;
+    if (thisRow) {
+        if (items.size ||
+            formulaRowIndex < dataStartRowIndex ||
+            formulaRowIndex > range.endRowIndex) {
+            return REF_ERROR_TOKEN;
+        }
+        startRowIndex = endRowIndex = formulaRowIndex;
+    }
+    else if (items.has("#all")) {
+        startRowIndex = range.startRowIndex;
+        endRowIndex = range.endRowIndex;
+    }
+    else {
+        var bands = [];
+        if (items.has("#headers")) {
+            if (!headerRow)
+                return REF_ERROR_TOKEN;
+            bands.push([range.startRowIndex, range.startRowIndex]);
+        }
+        if (items.has("#data") || (!items.has("#headers") && !items.has("#totals"))) {
+            if (dataStartRowIndex > dataEndRowIndex)
+                return REF_ERROR_TOKEN;
+            bands.push([dataStartRowIndex, dataEndRowIndex]);
+        }
+        if (items.has("#totals")) {
+            if (!totalRow)
+                return REF_ERROR_TOKEN;
+            bands.push([range.endRowIndex, range.endRowIndex]);
+        }
+        bands.sort(function (a, b) { return a[0] - b[0]; });
+        _c = __read(bands[0], 2), startRowIndex = _c[0], endRowIndex = _c[1];
+        try {
+            for (var _g = __values(bands.slice(1)), _h = _g.next(); !_h.done; _h = _g.next()) {
+                var _j = __read(_h.value, 2), bandStart = _j[0], bandEnd = _j[1];
+                // `[#Headers],[#Totals]` skips the data rows: not one rectangle.
+                if (bandStart > endRowIndex + 1)
+                    return REF_ERROR_TOKEN;
+                endRowIndex = Math.max(endRowIndex, bandEnd);
+            }
+        }
+        catch (e_7_1) { e_7 = { error: e_7_1 }; }
+        finally {
+            try {
+                if (_h && !_h.done && (_d = _g.return)) _d.call(_g);
+            }
+            finally { if (e_7) throw e_7.error; }
+        }
+    }
+    var absolute = !thisRow;
+    var start = cellToAddress({ rowIndex: startRowIndex, columnIndex: startColumnIndex }, absolute, absolute);
+    var end = cellToAddress({ rowIndex: endRowIndex, columnIndex: endColumnIndex }, absolute, absolute);
+    if (!start || !end)
+        return REF_ERROR_TOKEN;
+    var prefix = tableSheetName.toLowerCase() !== formulaSheetName.toLowerCase()
+        ? "".concat(sanitizeSheetName(tableSheetName), "!")
+        : "";
+    return start === end ? "".concat(prefix).concat(start) : "".concat(prefix).concat(start, ":").concat(end);
+};
 /**
  * Converts tokens to string
  * @param tokens

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

@@ -1,4 +1,9 @@
 import type { CellFormat, CellInterface, GridRange } from "@rowsncolumns/common-types";
+import type { CellData } from "@rowsncolumns/spreadsheet";
+import type { Draft } from "immer";
+import type { CellXfsRegistry } from "../hooks/use-cellxfs-registry";
+import type { SheetData } from "../hooks/use-spreadsheet-state";
+import type { SharedStringRegistry } from "../hooks/use-ss-registry";
 /**
  * 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
@@ -49,7 +54,23 @@ export declare const getBandedCellFormat: (bandedCells: Map<string, CellFormat>
  * 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.
+ * `undefined` never clobbers a banded value. `textFormat` merges key-wise: an explicitly bold
+ * header keeps the contrast text colour the band paints it with.
  */
 export declare const layerBandedFormat: (explicit: CellFormat | null | undefined, banded: CellFormat | undefined) => CellFormat | null | undefined;
+/**
+ * Write the banded (table stripe) formats the grid paints under `range` into the cells as
+ * static formats — Excel's Convert to Range bakes the table style into the cell formats — each
+ * cell's explicit format layered on top exactly as the format painter captures it. Runs inside
+ * the caller's sheet-data draft; cells without a band are untouched.
+ */
+export declare const bakeBandedFormats: <T extends CellData>({ draft, sheetId, range, bandedCells, locale, cellXfsRegistry, sharedStringRegistry, }: {
+    draft: Draft<SheetData<T>>;
+    sheetId: number;
+    range: GridRange;
+    bandedCells: Map<string, CellFormat> | undefined | null;
+    locale?: string;
+    cellXfsRegistry?: CellXfsRegistry;
+    sharedStringRegistry?: SharedStringRegistry;
+}) => void;
 //# sourceMappingURL=paint-format.d.ts.map

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

@@ -1 +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"}
+{"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;AAEpC,OAAO,KAAK,EAAE,QAAQ,EAAkB,MAAM,2BAA2B,CAAC;AAC1E,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,OAAO,CAAC;AAEnC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AACrE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gCAAgC,CAAC;AAChE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAIrE;;;;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;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,GAC5B,UAAU,UAAU,GAAG,IAAI,GAAG,SAAS,EACvC,QAAQ,UAAU,GAAG,SAAS,KAC7B,UAAU,GAAG,IAAI,GAAG,SActB,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,GAAI,CAAC,SAAS,QAAQ,EAAE,wFAQnD;IACD,KAAK,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,SAAS,CAAC;IACjB,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,GAAG,SAAS,GAAG,IAAI,CAAC;IACxD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC,oBAAoB,CAAC,EAAE,oBAAoB,CAAC;CAC7C,SA6CA,CAAC"}

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

@@ -1,5 +1,7 @@
 import { __assign, __read, __values } from "tslib";
 import { cellIdentifier, isCellWithinBounds } from "@rowsncolumns/grid";
+import { SheetCell } from "../sheet-cell";
+import { createSheetDraft } from "./immer-utils";
 var rangeContains = function (outer, inner) {
     return inner.startRowIndex >= outer.startRowIndex &&
         inner.endRowIndex <= outer.endRowIndex &&
@@ -146,7 +148,8 @@ export var getBandedCellFormat = function (bandedCells, 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.
+ * `undefined` never clobbers a banded value. `textFormat` merges key-wise: an explicitly bold
+ * header keeps the contrast text colour the band paints it with.
  */
 export var layerBandedFormat = function (explicit, banded) {
     var e_4, _a;
@@ -169,6 +172,59 @@ export var layerBandedFormat = function (explicit, banded) {
             }
             finally { if (e_4) throw e_4.error; }
         }
+        if (explicit.textFormat && banded.textFormat) {
+            merged.textFormat = __assign(__assign({}, banded.textFormat), explicit.textFormat);
+        }
     }
     return merged;
 };
+/**
+ * Write the banded (table stripe) formats the grid paints under `range` into the cells as
+ * static formats — Excel's Convert to Range bakes the table style into the cell formats — each
+ * cell's explicit format layered on top exactly as the format painter captures it. Runs inside
+ * the caller's sheet-data draft; cells without a band are untouched.
+ */
+export var bakeBandedFormats = function (_a) {
+    var e_5, _b;
+    var _c, _d;
+    var draft = _a.draft, sheetId = _a.sheetId, range = _a.range, bandedCells = _a.bandedCells, locale = _a.locale, cellXfsRegistry = _a.cellXfsRegistry, sharedStringRegistry = _a.sharedStringRegistry;
+    if (!(bandedCells === null || bandedCells === void 0 ? void 0 : bandedCells.size))
+        return;
+    var sheetCell = new SheetCell();
+    for (var rowIndex = range.startRowIndex; rowIndex <= range.endRowIndex; rowIndex++) {
+        for (var columnIndex = range.startColumnIndex; columnIndex <= range.endColumnIndex; columnIndex++) {
+            var banded = getBandedCellFormat(bandedCells, rowIndex, columnIndex);
+            if (!banded)
+                continue;
+            var currentSheet = createSheetDraft(draft, sheetId, rowIndex);
+            sheetCell.assign(sheetId, { rowIndex: rowIndex, columnIndex: columnIndex }, (_d = (_c = currentSheet[rowIndex]) === null || _c === void 0 ? void 0 : _c.values) === null || _d === void 0 ? void 0 : _d[columnIndex], { locale: locale, cellXfsRegistry: cellXfsRegistry, sharedStringRegistry: sharedStringRegistry });
+            var baked = layerBandedFormat(sheetCell.userEnteredFormat, banded);
+            sheetCell.clearUserEnteredFormat();
+            try {
+                for (var _e = (e_5 = void 0, __values(Object.entries(baked !== null && baked !== void 0 ? baked : {}))), _f = _e.next(); !_f.done; _f = _e.next()) {
+                    var _g = __read(_f.value, 2), key = _g[0], value = _g[1];
+                    // A band carries `undefined` for the parts it does not paint (no border, no text
+                    // colour) — those must not land as empty `{}` formats on the cell.
+                    if (value === undefined)
+                        continue;
+                    if (typeof value === "object" &&
+                        value !== null &&
+                        Object.values(value).every(function (part) { return part === undefined; })) {
+                        continue;
+                    }
+                    sheetCell.setUserEnteredFormat(key, value);
+                }
+            }
+            catch (e_5_1) { e_5 = { error: e_5_1 }; }
+            finally {
+                try {
+                    if (_f && !_f.done && (_b = _e.return)) _b.call(_e);
+                }
+                finally { if (e_5) throw e_5.error; }
+            }
+            currentSheet[rowIndex].values[columnIndex] =
+                sheetCell.getCellData();
+            cellXfsRegistry === null || cellXfsRegistry === void 0 ? void 0 : cellXfsRegistry.registerCellXfs(sheetCell);
+        }
+    }
+};

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

@@ -1,3 +1,25 @@
 import type { SortOrder } from "@rowsncolumns/spreadsheet";
-export declare const cellValueSorter: (left: string | number | boolean | undefined | null, right: string | number | boolean | undefined | null, sortOrder: SortOrder) => number;
+/**
+ * A cell whose effective value is an error (`#DIV/0!`, `#N/A`, …). Errors
+ * form the last value tier and keep their relative order, as in Excel.
+ */
+export type SortErrorValue = {
+    readonly sortError: string;
+};
+export type SortCellValue = string | number | boolean | SortErrorValue | undefined | null;
+export declare const isSortErrorValue: (value: unknown) => value is SortErrorValue;
+/**
+ * The value a sort compares for a cell: its error when it has one, else the
+ * effective value, else the display text.
+ */
+export declare const getCellSortValue: (cell: {
+    readonly error: unknown;
+    getEffectiveValue(): string | number | boolean | undefined;
+    readonly formattedValue: string | undefined | null;
+}) => SortCellValue;
+/**
+ * Excel's sort order: numbers < text < logicals < errors, blanks last in
+ * BOTH directions, text compared case-insensitively through the collator.
+ */
+export declare const cellValueSorter: (left: SortCellValue, right: SortCellValue, sortOrder: SortOrder) => number;
 //# sourceMappingURL=sort.d.ts.map