@rowsncolumns/spreadsheet-state 29.0.0 → 29.1.0

package/dist/esm/interface/spreadsheet-interface.js

@@ -1,7 +1,7 @@
 import { tokenize as defaultTokenizer } from "@rowsncolumns/calculator";
 import { isCellCoordinate, isCellNode, isCellRangeNode, isStaticNode, } from "@rowsncolumns/dag";
 import { FormulaError } from "@rowsncolumns/fast-formula-parser";
-import { defaultSpreadsheetTheme, } from "@rowsncolumns/spreadsheet";
+import { defaultSpreadsheetTheme, getBandedCells, } from "@rowsncolumns/spreadsheet";
 import { addressToCell, canUseDOM, cellToAddress, DEFAULT_ACTIVE_CELL, DEFAULT_COLUMN_COUNT, DEFAULT_COLUMN_WIDTH, DEFAULT_ROW_COUNT, DEFAULT_ROW_HEIGHT, generateSelectionsFromFormula, getCellEffectiveFormat, getCellEffectiveValue, getCellFormattedValue, getCellUserEnteredFormat, cellFormatWrapsText, getCellUserEnteredValue, getColumnIndexFromColumnName, getExtendedValueBool, getExtendedValueError, getExtendedValueFormula, getExtendedValueNumber, getExtendedValueString, isAreasEqual, isCellWithinBounds, isNil, iterateCellsInRange, pointToPixel, } from "@rowsncolumns/utils";
 import { enableMapSet, enablePatches, produceWithPatches } from "immer";
 import { buildConditionalFormatExpression } from "../api/conditional-format";
@@ -12,6 +12,7 @@ import { getAutoFillValues } from "../api/fill";
 import { formulaToRelativeReference } from "../api/formula";
 import { createSheetDraft, deriveCellFromPrecedents } from "../api/immer-utils";
 import { arrayResultToA1Ref } from "../hooks/use-on-calculation-success";
+import { deriveBuiltInTableBanding, } from "../hooks/use-spreadsheet-state";
 import { defaultCellCoords, isStyleReference, SheetCell } from "../sheet-cell";
 import { CellXfsRegistry } from "../cellxfs-registry";
 import { SharedStringRegistry } from "../shared-string-registry";
@@ -1221,6 +1222,22 @@ export class Spreadsheet {
                     sheetName,
                 };
             }
+            // Totals row only (the table's last row); nothing to highlight while it is off.
+            if (specialItem === "#Totals") {
+                if (!totalRow) {
+                    return undefined;
+                }
+                return {
+                    range: {
+                        ...range,
+                        startColumnIndex,
+                        endColumnIndex,
+                        startRowIndex: range.endRowIndex,
+                        endRowIndex: range.endRowIndex,
+                    },
+                    sheetName,
+                };
+            }
             // All
             if (specialItem === "#All") {
                 return {
@@ -1358,6 +1375,7 @@ export class Spreadsheet {
             onChangeSheets: this.onChangeSheets,
             onChangeSheetData: this.onChangeSheetData,
             onChangeTables: this.onChangeTables,
+            onChangeCharts: this.onChangeCharts,
             onChangeDataValidations: this.onChangeDataValidations,
             onChangeConditionalFormats: this.onChangeConditionalFormats,
             createHistory: this.createHistory,
@@ -1510,6 +1528,8 @@ export class Spreadsheet {
                 getDependents: this.getDependents,
                 onChangeSheetData: this.onChangeSheetData,
                 onChangeTables: this.onChangeTables,
+                onChangeCharts: this.onChangeCharts,
+                tables: this.tables,
             })(...args),
             onChangeCalculatedColumn: (...args) => changeCalculatedColumn({
                 locale: this.locale,
@@ -1613,15 +1633,27 @@ export class Spreadsheet {
      * @param previousTable
      */
     updateTable(sheetId, tableId, updatedTable) {
+        const sheet = this.getSheet(sheetId);
         return updateTable({
             locale: this.locale,
             tables: this.tables,
             createHistory: this.createHistory,
             enqueueCalculation: this.enqueueCalculation,
+            enqueueGraphOperation: this.enqueueGraphOperation,
+            getGraphNodes: () => this._calculationInterface.getNodes(),
             getDependents: this.getDependents,
             onChangeSheetData: this.onChangeSheetData,
             onChangeTables: this.onChangeTables,
             getFormattedValue: this.getFormattedValue,
+            sheetData: this.sheetData,
+            rowCount: sheet.rowCount,
+            columnCount: sheet.columnCount,
+            getSheetName: this.getSheetName,
+            getActiveCell: this.getActiveCell,
+            enqueueStructureChange: this.enqueueStructureChange,
+            onChangeSheets: this.onChangeSheets,
+            onChangeDataValidations: this.onChangeDataValidations,
+            onChangeConditionalFormats: this.onChangeConditionalFormats,
         })(sheetId, tableId, updatedTable);
     }
     /**
@@ -1630,10 +1662,39 @@ export class Spreadsheet {
      */
     removeTable(tableView) {
         removeTable({
+            locale: this.locale,
+            cellXfsRegistry: this.cellXfsRegistry,
+            sharedStringRegistry: this.sharedStringRegistry,
+            getSheetName: this.getSheetName,
             createHistory: this.createHistory,
             enqueueCalculation: this.enqueueCalculation,
+            enqueueGraphOperation: this.enqueueGraphOperation,
             getDependents: this.getDependents,
+            getGraphNodes: () => this._calculationInterface.getNodes(),
+            getBandedCells: (sheetId) => {
+                const bands = (this.tables ?? []).flatMap((table) => {
+                    const banded = table.sheetId === sheetId
+                        ? (table.bandedRange ?? deriveBuiltInTableBanding(table))
+                        : undefined;
+                    return banded
+                        ? [
+                            {
+                                bandedRangeId: `${table.id}-${table.theme}`,
+                                showFirstColumn: table.showFirstColumn,
+                                showLastColumn: table.showLastColumn,
+                                totalRow: table.totalRow ?? false,
+                                range: { ...table.range, sheetId },
+                                ...banded,
+                            },
+                        ]
+                        : [];
+                });
+                return bands.length
+                    ? getBandedCells(bands, defaultSpreadsheetTheme, sheetId, (rowIndex) => this.isHiddenRow(sheetId, rowIndex), () => false)
+                    : undefined;
+            },
             onChangeSheets: this.onChangeSheets,
+            onChangeSheetData: this.onChangeSheetData,
             onChangeTables: this.onChangeTables,
         })(tableView);
     }
@@ -1736,6 +1797,7 @@ export class Spreadsheet {
             enqueueStructureChange: this.enqueueStructureChange,
             onChangeSheetData: this.onChangeSheetData,
             onChangeSheets: this.onChangeSheets,
+            onChangeCharts: this.onChangeCharts,
         })(sheetId, activeCell, selections);
     }
     /**
@@ -1756,6 +1818,7 @@ export class Spreadsheet {
             enqueueStructureChange: this.enqueueStructureChange,
             onChangeSheetData: this.onChangeSheetData,
             onChangeSheets: this.onChangeSheets,
+            onChangeCharts: this.onChangeCharts,
         })(sheetId, activeCell, selections);
     }
     /** Freeze a row index */
@@ -1858,6 +1921,12 @@ export class Spreadsheet {
             onChangeSheetData: this.onChangeSheetData,
             onChangeActiveSheet: () => { },
             onChangeSheets: this.onChangeSheets,
+            onChangeCharts: this.onChangeCharts,
+            onChangeEmbeds: this.onChangeEmbeds,
+            onChangeTables: this.onChangeTables,
+            onChangeConditionalFormats: this.onChangeConditionalFormats,
+            onChangeDataValidations: this.onChangeDataValidations,
+            onChangeNamedRanges: this.onChangeNamedRanges,
             createHistory: this.createHistory,
             enqueueGraphOperation: this.enqueueGraphOperation,
         })(sheetId);
@@ -2137,6 +2206,7 @@ export class Spreadsheet {
             onChangeSheetData: this.onChangeSheetData,
             onChangeSheets: this.onChangeSheets,
             onChangeTables: this.onChangeTables,
+            onChangeCharts: this.onChangeCharts,
             onChangeDataValidations: this.onChangeDataValidations,
             onChangeConditionalFormats: this.onChangeConditionalFormats,
         })(tableView, rowIndexes);
@@ -2337,6 +2407,7 @@ export class Spreadsheet {
             database,
             locale: this.locale,
             onChangeSheetData: this.onChangeSheetData,
+            onChangeCharts: this.onChangeCharts,
             onChangeSheets: this.onChangeSheets,
             // onCreateNewSheet:,
             createHistory: this.createHistory,
@@ -2355,6 +2426,7 @@ export class Spreadsheet {
             database,
             locale: this.locale,
             onChangeSheetData: this.onChangeSheetData,
+            onChangeCharts: this.onChangeCharts,
             onChangeSheets: this.onChangeSheets,
             // onCreateNewSheet:,
             createHistory: this.createHistory,

package/dist/esm/interface/table-totalrow.d.ts

@@ -3,12 +3,24 @@ import type { UseOnTableProps } from "../hooks/use-on-table";
 import type { SpreadsheetPatch } from "../hooks/use-undo-redo";
 type TableTotalRowProps<T extends CellData, S extends Sheet> = Pick<UseOnTableProps<T, S>, "locale" | "onChangeSheetData" | "enqueueCalculation">;
 /**
- * Add a total row to a table.
+ * Add a total row to a table the way Excel does when Total Row is switched on:
+ * "Total" in the first column and ONE structured-reference `SUBTOTAL` in the
+ * last column — Sum (`109`) when that column's body is all numbers, Count
+ * (`103`) otherwise; every other totals cell stays blank. A single-column
+ * table gets the formula.
  *
  * Expects `updatedTable.range` to already include the total row, i.e.
  * `range.endRowIndex` is the row the totals are written to.
  */
 export declare const addTotalRow: <T extends CellData, S extends Sheet>({ locale, onChangeSheetData, enqueueCalculation, }: TableTotalRowProps<T, S>) => (sheetId: number, updatedTable: TableView, saveHistory: (patches: SpreadsheetPatch) => void) => void;
+/**
+ * Rewrite the totals-row cells of `columnIndexes` from their column's recorded
+ * `totalsRowFunction` (the totals dropdown's choice): a function writes its
+ * structured `SUBTOTAL`, `none` (or no name to reference) clears the cell.
+ *
+ * Expects `table.range` to include the total row (`range.endRowIndex`).
+ */
+export declare const setTotalRowFunctions: <T extends CellData, S extends Sheet>({ locale, onChangeSheetData, enqueueCalculation, }: TableTotalRowProps<T, S>) => (sheetId: number, table: TableView, columnIndexes: number[], saveHistory: (patches: SpreadsheetPatch) => void) => void;
 /**
  * Remove the total row from a table.
  *

package/dist/esm/interface/table-totalrow.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"table-totalrow.d.ts","sourceRoot":"","sources":["../../../interface/table-totalrow.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAM5E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAI/D,KAAK,kBAAkB,CAAC,CAAC,SAAS,QAAQ,EAAE,CAAC,SAAS,KAAK,IAAI,IAAI,CACjE,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,EACrB,QAAQ,GAAG,mBAAmB,GAAG,oBAAoB,CACtD,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,WAAW,GAAI,CAAC,SAAS,QAAQ,EAAE,CAAC,SAAS,KAAK,EAAE,oDAI9D,kBAAkB,CAAC,CAAC,EAAE,CAAC,CAAC,MAEvB,SAAS,MAAM,EACf,cAAc,SAAS,EACvB,aAAa,CAAC,OAAO,EAAE,gBAAgB,KAAK,IAAI,SAuJnD,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,cAAc,GAAI,CAAC,SAAS,QAAQ,EAAE,CAAC,SAAS,KAAK,EAAE,oDAIjE,kBAAkB,CAAC,CAAC,EAAE,CAAC,CAAC,MAEvB,SAAS,MAAM,EACf,cAAc,SAAS,EACvB,aAAa,CAAC,OAAO,EAAE,gBAAgB,KAAK,IAAI,SA4DnD,CAAC"}
+{"version":3,"file":"table-totalrow.d.ts","sourceRoot":"","sources":["../../../interface/table-totalrow.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAM5E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAI/D,KAAK,kBAAkB,CAAC,CAAC,SAAS,QAAQ,EAAE,CAAC,SAAS,KAAK,IAAI,IAAI,CACjE,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,EACrB,QAAQ,GAAG,mBAAmB,GAAG,oBAAoB,CACtD,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,WAAW,GAAI,CAAC,SAAS,QAAQ,EAAE,CAAC,SAAS,KAAK,EAAE,oDAI9D,kBAAkB,CAAC,CAAC,EAAE,CAAC,CAAC,MAEvB,SAAS,MAAM,EACf,cAAc,SAAS,EACvB,aAAa,CAAC,OAAO,EAAE,gBAAgB,KAAK,IAAI,SA8HnD,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,GAAI,CAAC,SAAS,QAAQ,EAAE,CAAC,SAAS,KAAK,EAAE,oDAIvE,kBAAkB,CAAC,CAAC,EAAE,CAAC,CAAC,MAEvB,SAAS,MAAM,EACf,OAAO,SAAS,EAChB,eAAe,MAAM,EAAE,EACvB,aAAa,CAAC,OAAO,EAAE,gBAAgB,KAAK,IAAI,SAqDnD,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,cAAc,GAAI,CAAC,SAAS,QAAQ,EAAE,CAAC,SAAS,KAAK,EAAE,oDAIjE,kBAAkB,CAAC,CAAC,EAAE,CAAC,CAAC,MAEvB,SAAS,MAAM,EACf,cAAc,SAAS,EACvB,aAAa,CAAC,OAAO,EAAE,gBAAgB,KAAK,IAAI,SA4DnD,CAAC"}

package/dist/esm/interface/table-totalrow.js

@@ -1,10 +1,14 @@
-import { isNil, isNumber } from "@rowsncolumns/utils";
+import { getTotalsRowFormula, isNil, isNumber } from "@rowsncolumns/utils";
 import { produceWithPatches } from "immer";
 import { createSheetCellIdentifier } from "../api/formula";
 import { createSheetDraft } from "../api/immer-utils";
 import { SheetCell } from "../sheet-cell";
 /**
- * Add a total row to a table.
+ * Add a total row to a table the way Excel does when Total Row is switched on:
+ * "Total" in the first column and ONE structured-reference `SUBTOTAL` in the
+ * last column — Sum (`109`) when that column's body is all numbers, Count
+ * (`103`) otherwise; every other totals cell stays blank. A single-column
+ * table gets the formula.
  *
  * Expects `updatedTable.range` to already include the total row, i.e.
  * `range.endRowIndex` is the row the totals are written to.
@@ -13,94 +17,120 @@ export const addTotalRow = ({ locale, onChangeSheetData, enqueueCalculation, })
     return (sheetId, updatedTable, saveHistory) => {
         // We need to track this for history. Precedent cells
         const recalcCells = new Map();
-        /**
-         * 1. Validate number columns
-         * 2. Add Subtotal function
-         */
-        const numberColumnIndexes = [];
         const sheetCell = new SheetCell();
         const { range: { startRowIndex, startColumnIndex, endRowIndex, endColumnIndex }, } = updatedTable;
-        // Add total text
         const totalRowIndex = endRowIndex;
+        const bodyStartRowIndex = startRowIndex + (updatedTable.headerRow !== false ? 1 : 0);
         /**
          * Update sheet
          */
         onChangeSheetData?.((prevSheetData) => {
             const [nextState, patches, inversePatches] = produceWithPatches(prevSheetData, (draft) => {
-                // User is adding a total row
-                for (let columnIndex = startColumnIndex; columnIndex <= endColumnIndex; columnIndex++) {
+                // Is every non-blank body cell of the column a number? Dates are
+                // stored as numbers, but summing them is meaningless.
+                const isNumericColumn = (columnIndex) => {
                     const values = [];
-                    let isDateColumn = false;
-                    for (let rowIndex = startRowIndex + (updatedTable.headerRow ? 1 : 0); rowIndex < totalRowIndex; rowIndex++) {
+                    for (let rowIndex = bodyStartRowIndex; rowIndex < totalRowIndex; rowIndex++) {
                         const cellData = draft[sheetId]?.[rowIndex]?.values?.[columnIndex];
-                        sheetCell.assign(sheetId, {
-                            rowIndex,
-                            columnIndex,
-                        }, cellData, { locale });
-                        const effectiveValue = sheetCell.getEffectiveValue();
+                        sheetCell.assign(sheetId, { rowIndex, columnIndex }, cellData, {
+                            locale,
+                        });
                         const numberFormat = sheetCell.getNumberFormat();
-                        // Dates are stored as numbers, but summing them is meaningless
                         if (numberFormat?.type === "DATE" ||
                             numberFormat?.type === "DATE_TIME") {
-                            isDateColumn = true;
-                            break;
+                            return false;
                         }
+                        const effectiveValue = sheetCell.getEffectiveValue();
                         if (!isNil(effectiveValue)) {
                             values.push(effectiveValue);
                         }
                     }
-                    if (!isDateColumn && values.length && values.every(isNumber)) {
-                        numberColumnIndexes.push(columnIndex);
-                    }
-                }
+                    return values.length > 0 && values.every(isNumber);
+                };
                 const currentSheet = createSheetDraft(draft, sheetId, totalRowIndex);
-                sheetCell.assign(sheetId, {
-                    rowIndex: totalRowIndex,
-                    columnIndex: startColumnIndex,
-                }, currentSheet[totalRowIndex]?.values?.[startColumnIndex], { locale });
-                // Add total text
-                sheetCell.setUserEnteredValue("Total");
-                // Bold, can be overridden by user
-                sheetCell.setUserEnteredFormat("textFormat", {
-                    bold: true,
-                });
-                // Set cell data
-                currentSheet[totalRowIndex].values[startColumnIndex] =
-                    sheetCell.getCellData();
-                // Add subtotal
-                for (const columnIndex of numberColumnIndexes) {
-                    // The total label owns the first column
-                    if (columnIndex === startColumnIndex) {
+                const writeTotalCell = (columnIndex, value) => {
+                    sheetCell.assign(sheetId, { rowIndex: totalRowIndex, columnIndex }, currentSheet[totalRowIndex]?.values?.[columnIndex], { locale });
+                    sheetCell.setUserEnteredValue(value);
+                    // The totals row's bold and top rule come from the table style's
+                    // `totalRow` band, not from an explicit cell format.
+                    currentSheet[totalRowIndex].values[columnIndex] =
+                        sheetCell.getCellData();
+                };
+                const writeTotalFormula = (columnIndex, formula) => {
+                    writeTotalCell(columnIndex, formula);
+                    const position = { rowIndex: totalRowIndex, columnIndex, sheetId };
+                    enqueueCalculation({ type: "add", position });
+                    recalcCells.set(createSheetCellIdentifier(sheetId, totalRowIndex, columnIndex), position);
+                };
+                // A column with a recorded `totalsRowFunction` (the totals dropdown's
+                // choice, kept across toggles) regenerates that; the others take
+                // Excel's defaults below.
+                const recorded = new Set();
+                for (let columnIndex = startColumnIndex; columnIndex <= endColumnIndex; columnIndex++) {
+                    const column = updatedTable.columns?.[columnIndex - startColumnIndex];
+                    const fn = column?.totalsRowFunction;
+                    if (!fn)
                         continue;
-                    }
-                    const rowIndex = totalRowIndex;
-                    const cellData = draft[sheetId]?.[rowIndex]?.values?.[columnIndex];
-                    sheetCell.assign(sheetId, {
-                        columnIndex,
-                        rowIndex,
-                    }, cellData, { locale });
-                    const columnName = updatedTable.columns?.[columnIndex - startColumnIndex]?.name;
-                    if (columnName) {
-                        sheetCell.setUserEnteredValue(`=SUBTOTAL(109, [${columnName}])`);
+                    recorded.add(columnIndex);
+                    const formula = column?.name
+                        ? getTotalsRowFormula(fn, updatedTable.title, column.name)
+                        : undefined;
+                    if (formula)
+                        writeTotalFormula(columnIndex, formula);
+                }
+                const lastColumnName = updatedTable.columns?.[endColumnIndex - startColumnIndex]?.name;
+                const lastColumnFormula = lastColumnName && !recorded.has(endColumnIndex)
+                    ? getTotalsRowFormula(isNumericColumn(endColumnIndex) ? "sum" : "count", updatedTable.title, lastColumnName)
+                    : undefined;
+                // The total label owns the first column unless the formula needs it
+                // (single-column table).
+                if (!recorded.has(startColumnIndex) &&
+                    (endColumnIndex > startColumnIndex || !lastColumnFormula)) {
+                    writeTotalCell(startColumnIndex, "Total");
+                }
+                if (lastColumnFormula) {
+                    writeTotalFormula(endColumnIndex, lastColumnFormula);
+                }
+            });
+            saveHistory({
+                sheetData: { patches, inversePatches },
+                recalcCells: { undo: recalcCells, redo: recalcCells },
+            });
+            return nextState;
+        });
+    };
+};
+/**
+ * Rewrite the totals-row cells of `columnIndexes` from their column's recorded
+ * `totalsRowFunction` (the totals dropdown's choice): a function writes its
+ * structured `SUBTOTAL`, `none` (or no name to reference) clears the cell.
+ *
+ * Expects `table.range` to include the total row (`range.endRowIndex`).
+ */
+export const setTotalRowFunctions = ({ locale, onChangeSheetData, enqueueCalculation, }) => {
+    return (sheetId, table, columnIndexes, saveHistory) => {
+        const recalcCells = new Map();
+        const sheetCell = new SheetCell();
+        const totalRowIndex = table.range.endRowIndex;
+        onChangeSheetData?.((prevSheetData) => {
+            const [nextState, patches, inversePatches] = produceWithPatches(prevSheetData, (draft) => {
+                const currentSheet = createSheetDraft(draft, sheetId, totalRowIndex);
+                for (const columnIndex of columnIndexes) {
+                    const column = table.columns?.[columnIndex - table.range.startColumnIndex];
+                    const formula = column?.totalsRowFunction && column.name
+                        ? getTotalsRowFormula(column.totalsRowFunction, table.title, column.name)
+                        : undefined;
+                    sheetCell.assign(sheetId, { rowIndex: totalRowIndex, columnIndex }, formula ? currentSheet[totalRowIndex]?.values?.[columnIndex] : undefined, { locale });
+                    if (formula) {
+                        sheetCell.setUserEnteredValue(formula);
                         // Bold, can be overridden by user
-                        sheetCell.setUserEnteredFormat("textFormat", {
-                            bold: true,
-                        });
-                        // Set cell data
-                        currentSheet[totalRowIndex].values[columnIndex] =
-                            sheetCell.getCellData();
-                        const position = {
-                            rowIndex,
-                            columnIndex,
-                            sheetId,
-                        };
-                        enqueueCalculation({
-                            type: "add",
-                            position,
-                        });
-                        // Add sheet id
-                        recalcCells.set(createSheetCellIdentifier(sheetId, rowIndex, columnIndex), position);
+                        sheetCell.setUserEnteredFormat("textFormat", { bold: true });
                     }
+                    currentSheet[totalRowIndex].values[columnIndex] =
+                        sheetCell.getCellData();
+                    const position = { rowIndex: totalRowIndex, columnIndex, sheetId };
+                    enqueueCalculation({ type: "add", position });
+                    recalcCells.set(createSheetCellIdentifier(sheetId, totalRowIndex, columnIndex), position);
                 }
             });
             saveHistory({

package/dist/esm/interface/table-utils.d.ts

@@ -1,21 +1,74 @@
-import type { GridRange } from "@rowsncolumns/common-types";
-import type { CellData, TableView } from "@rowsncolumns/spreadsheet";
+import type { GridRange, SelectionArea } from "@rowsncolumns/common-types";
+import type { CellData, Column, TableView } from "@rowsncolumns/spreadsheet";
 import type { Draft } from "immer";
 import type { GeneratedNames } from "../generated-names";
+import type { SheetData } from "../hooks/use-spreadsheet-state";
+/**
+ * Does any cell of `rowIndex` within a table's columns hold a value or formula?
+ * Decides whether switching Total Row on must first shift the row below the
+ * table down (Excel inserts a row rather than overwrite data).
+ */
+export declare const tableRowHasContent: <T extends CellData>(rows: SheetData<T>[number] | undefined, rowIndex: number, startColumnIndex: number, endColumnIndex: number) => boolean;
+/**
+ * Excel's Header Row → ON re-adds the header ABOVE the data when the row above the table is free:
+ * it exists, holds no value or formula in the table's columns, and belongs to no other table.
+ * Otherwise the first data row becomes the header row in place.
+ */
+export declare const tableHeaderRowAboveIsFree: <T extends CellData>({ sheetId, table, sheetData, tables, }: {
+    sheetId: number;
+    table: TableView;
+    sheetData: SheetData<T> | undefined;
+    tables: TableView[] | undefined;
+}) => boolean;
 export declare const rangesOverlap: (a: GridRange, b: GridRange) => boolean;
 export declare const tableWouldOverlap: (candidate: {
     sheetId: number;
     range: GridRange;
     id?: TableView["id"];
 }, existing: TableView[] | undefined) => boolean;
-type AddTableColumnOptions<T extends CellData> = {
+/**
+ * Excel: a table's header names are unique, compared case-insensitively — a duplicate takes the
+ * next free numeric suffix (`Name`, `Name2`, `Name3`).
+ */
+export declare const getUniqueTableColumnName: (name: string, taken: Iterable<string>) => string;
+type TableHeaderNamesOptions = {
     sheetId: number;
-    draft: Draft<any>;
     range: GridRange;
     getFormattedValue: (sheetId: number, rowIndex: number, columnIndex: number) => string | null | undefined;
-    locale?: string;
     generatedNames?: GeneratedNames;
+    /** Columns the table already names, by position — kept as they are; only the rest are derived. */
+    columns?: (Column | undefined)[] | null;
 };
-export declare const addTableColumn: <T extends CellData>({ draft, sheetId, range, getFormattedValue, locale, generatedNames, }: AddTableColumnOptions<T>) => void;
+/**
+ * The header names a table takes over `range` (Excel): a column the table already names keeps
+ * that name; every other column takes its header cell's display text, de-duplicated against the
+ * names before it (`Name`, `Name2`, …), and a blank header cell takes the first free `ColumnN`.
+ */
+export declare const getTableHeaderNames: ({ sheetId, range, getFormattedValue, generatedNames, columns, }: TableHeaderNamesOptions) => string[];
+type AddTableColumnOptions<T extends CellData> = TableHeaderNamesOptions & {
+    draft: Draft<any>;
+    locale?: string;
+};
+/**
+ * Write a table's header row: every header cell holds its column's name as TEXT (Excel stores
+ * headers as text — a `2024` header becomes the string "2024"), so a blank, numeric, formula or
+ * de-duplicated header cell is (re)written; a text cell already reading its name is left alone.
+ * The names come from {@link getTableHeaderNames}, so the table's `columns` and its cells agree.
+ */
+export declare const addTableColumn: <T extends CellData>({ draft, sheetId, range, getFormattedValue, locale, generatedNames, columns, }: AddTableColumnOptions<T>) => string[];
+export type TableHeaderRefill = {
+    tableId: TableView["id"];
+    rowIndex: number;
+    columnIndex: number;
+    /** Position of the header within `table.columns`. */
+    dimensionIndex: number;
+    name: string;
+};
+export declare const getTableHeaderRefills: ({ sheetId, tables, selections, generatedNames, }: {
+    sheetId: number;
+    tables: TableView[] | undefined;
+    selections: Pick<SelectionArea, "range">[];
+    generatedNames?: GeneratedNames;
+}) => TableHeaderRefill[];
 export {};
 //# sourceMappingURL=table-utils.d.ts.map

package/dist/esm/interface/table-utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"table-utils.d.ts","sourceRoot":"","sources":["../../../interface/table-utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAC;AAC5D,OAAO,KAAK,EAAE,QAAQ,EAAU,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAC7E,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,OAAO,CAAC;AAGnC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAOzD,eAAO,MAAM,aAAa,GAAI,GAAG,SAAS,EAAE,GAAG,SAAS,KAAG,OAMxD,CAAC;AAEJ,eAAO,MAAM,iBAAiB,GAC5B,WAAW;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,SAAS,CAAC;IAAC,EAAE,CAAC,EAAE,SAAS,CAAC,IAAI,CAAC,CAAA;CAAE,EACtE,UAAU,SAAS,EAAE,GAAG,SAAS,KAChC,OAQF,CAAC;AAEF,KAAK,qBAAqB,CAAC,CAAC,SAAS,QAAQ,IAAI;IAC/C,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC;IAClB,KAAK,EAAE,SAAS,CAAC;IACjB,iBAAiB,EAAE,CACjB,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,KAChB,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IAC/B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,cAAc,CAAC,EAAE,cAAc,CAAC;CACjC,CAAC;AAEF,eAAO,MAAM,cAAc,GAAI,CAAC,SAAS,QAAQ,EAAE,uEAOhD,qBAAqB,CAAC,CAAC,CAAC,SAoC1B,CAAC"}
+{"version":3,"file":"table-utils.d.ts","sourceRoot":"","sources":["../../../interface/table-utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAC3E,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAE7E,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,OAAO,CAAC;AAGnC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAEzD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gCAAgC,CAAC;AAGhE;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,GAAI,CAAC,SAAS,QAAQ,EACnD,MAAM,SAAS,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,SAAS,EACtC,UAAU,MAAM,EAChB,kBAAkB,MAAM,EACxB,gBAAgB,MAAM,KACrB,OAUF,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,GAAI,CAAC,SAAS,QAAQ,EAAE,wCAK3D;IACD,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,SAAS,CAAC;IACjB,SAAS,EAAE,SAAS,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC;IACpC,MAAM,EAAE,SAAS,EAAE,GAAG,SAAS,CAAC;CACjC,KAAG,OAqBH,CAAC;AAKF,eAAO,MAAM,aAAa,GAAI,GAAG,SAAS,EAAE,GAAG,SAAS,KAAG,OAMxD,CAAC;AAEJ,eAAO,MAAM,iBAAiB,GAC5B,WAAW;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,SAAS,CAAC;IAAC,EAAE,CAAC,EAAE,SAAS,CAAC,IAAI,CAAC,CAAA;CAAE,EACtE,UAAU,SAAS,EAAE,GAAG,SAAS,KAChC,OAQF,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,wBAAwB,GACnC,MAAM,MAAM,EACZ,OAAO,QAAQ,CAAC,MAAM,CAAC,KACtB,MAaF,CAAC;AAEF,KAAK,uBAAuB,GAAG;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,SAAS,CAAC;IACjB,iBAAiB,EAAE,CACjB,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,KAChB,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IAC/B,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,kGAAkG;IAClG,OAAO,CAAC,EAAE,CAAC,MAAM,GAAG,SAAS,CAAC,EAAE,GAAG,IAAI,CAAC;CACzC,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,GAAI,iEAMjC,uBAAuB,KAAG,MAAM,EA2BlC,CAAC;AAEF,KAAK,qBAAqB,CAAC,CAAC,SAAS,QAAQ,IAAI,uBAAuB,GAAG;IACzE,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AA6BF;;;;;GAKG;AACH,eAAO,MAAM,cAAc,GAAI,CAAC,SAAS,QAAQ,EAAE,gFAQhD,qBAAqB,CAAC,CAAC,CAAC,aAyC1B,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,OAAO,EAAE,SAAS,CAAC,IAAI,CAAC,CAAC;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,qDAAqD;IACrD,cAAc,EAAE,MAAM,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAMF,eAAO,MAAM,qBAAqB,GAAI,kDAKnC;IACD,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,SAAS,EAAE,GAAG,SAAS,CAAC;IAChC,UAAU,EAAE,IAAI,CAAC,aAAa,EAAE,OAAO,CAAC,EAAE,CAAC;IAC3C,cAAc,CAAC,EAAE,cAAc,CAAC;CACjC,KAAG,iBAAiB,EAuCpB,CAAC"}