@office-kit/xlsx 0.11.1 → 0.12.0

package/dist/worksheet/cell-range.d.ts

@@ -1,11 +1,18 @@
 import type { Cell } from '../cell/cell.js';
-import { type CellRangeBoundaries } from '../utils/coordinate.js';
+import { type CellRangeBoundaries, type RangeRef } from '../utils/coordinate.js';
 /** Re-export under the plan's canonical name. */
 export type CellRange = CellRangeBoundaries;
 /** Build a CellRange from explicit 1-based bounds. */
 export declare function makeCellRange(minRow: number, minCol: number, maxRow: number, maxCol: number): CellRange;
-/** Parse a range expression — wraps {@link rangeBoundaries}. */
-export declare function parseRange(input: string): CellRange;
+/**
+ * Resolve a {@link RangeRef} to numeric bounds: A1 expressions go through
+ * {@link rangeBoundaries}, pre-computed bounds through {@link makeCellRange}.
+ * Both paths validate against the grid and normalise inverted bounds, so
+ * `{ minRow: 5, maxRow: 1 }` behaves like `"A5:A1"` rather than iterating zero
+ * rows, and a fractional or off-grid bound throws here instead of half-way
+ * through the caller's loop.
+ */
+export declare function parseRange(input: RangeRef): CellRange;
 /** Format a CellRange back into the canonical OOXML string. */
 export declare function rangeToString(r: CellRange): string;
 /**

package/dist/worksheet/data-validations.d.ts

@@ -45,7 +45,7 @@ export interface ValidationCommon {
 /**
  * Add a list-type dropdown validation to a range. `values` may be an inline
  * list (`['Red', 'Green', 'Blue']`) or a sheet reference
- * (`'=Sheet1!$A$1:$A$10'`).
+ * (`'Sheet1!$A$1:$A$10'`, with or without a leading `=`).
  */
 export declare const addListValidation: (ws: Worksheet, sqref: MultiCellRange | string, values: ReadonlyArray<string> | string, opts?: ValidationCommon) => DataValidation;
 /**

package/dist/worksheet/index.d.ts

@@ -1,10 +1,10 @@
-export type { CellsByKindCounts, IterRowsOptions, Worksheet, } from './worksheet.js';
-export { addCellWatch, addConditionalFormatting, addDataValidation, addIgnoredError, addTable, appendRow, appendRows, applyToRange, autofitColumns, clearAllCells, clearRange, collapseColumnGroup, collapseRowGroup, copyRange, countCells, countCellsByKind, deleteCell, expandColumnGroup, expandRowGroup, findCells, freezePanes, getAutoFilter, getCell, getCellByCoord, getCellsInColumn, getCellsInRange, getCellsInRow, getColumnDimension, getDataExtent, getFreezePanes, getMaxCol, getMaxRow, getMergedCells, getMergedRangeAt, getNonEmptyCellCount, getPopulatedColumnIndices, getPopulatedRowIndices, getRangeValues, getRowDimension, getTable, groupColumns, groupRows, hideColumn, hideColumns, hideRow, hideRows, isMergedCell, isWorksheetEmpty, iterCells, iterRows, iterValues, listComments, listDataValidations, listHyperlinks, listTables, makeWorksheet, mergeCells, moveRange, removeAllComments, removeAllConditionalFormatting, removeAllDataValidations, removeAllHyperlinks, removeAllMergedRanges, removeAllTables, removeCellWatches, removeDataValidations, removeHyperlink, removeIgnoredErrors, removeTable, setAutoFilter, setCell, setCellByCoord, setColumnDimension, setColumnWidth, setColumnWidths, setComment, setDefaultColumnWidth, setDefaultRowHeight, setFreezePanes, setHyperlink, setRangeValues, setRowDimension, setRowHeight, setRowHeights, setSheetTabColor, setSheetViewMode, setSheetZoom, ungroupColumns, ungroupRows, unhideColumn, unhideColumns, unhideRow, unhideRows, unmergeCells, unmergeCellsAt, writeRange, } from './worksheet.js';
+export type { AppendRowOptions, CellsByKindCounts, IterRowsOptions, Worksheet, } from './worksheet.js';
+export { addCellWatch, addConditionalFormatting, addDataValidation, addIgnoredError, addTable, appendRow, appendRows, applyToRange, autofitColumns, clearAllCells, clearRange, collapseColumnGroup, collapseRowGroup, copyRange, countCells, countCellsByKind, deleteCell, ensureCell, ensureCellByCoord, expandColumnGroup, expandRowGroup, findCells, getAutoFilter, getCell, getCellByCoord, getCellsInColumn, getCellsInRange, getCellsInRow, getColumnDimension, getDataExtent, getFreezePanes, getMaxCol, getMaxRow, getMergedCells, getMergedRangeAt, getNonEmptyCellCount, getPopulatedColumnIndices, getPopulatedRowIndices, getRangeValues, getRowDimension, getTable, groupColumns, groupRows, hideColumn, hideColumns, hideRow, hideRows, isMergedCell, isWorksheetEmpty, iterCells, iterRows, iterValues, listComments, listDataValidations, listHyperlinks, listTables, makeWorksheet, mergeCells, moveRange, removeAllComments, removeAllConditionalFormatting, removeAllDataValidations, removeAllHyperlinks, removeAllMergedRanges, removeAllTables, removeCellWatches, removeDataValidations, removeHyperlink, removeIgnoredErrors, removeTable, setAutoFilter, setCell, setCellByCoord, setColumnDimension, setColumnWidth, setColumnWidths, setComment, setDefaultColumnWidth, setDefaultRowHeight, setFreezePanes, setHyperlink, setRangeValues, setRowDimension, setRowHeight, setRowHeights, setSheetTabColor, setSheetViewMode, setSheetZoom, ungroupColumns, ungroupRows, unhideColumn, unhideColumns, unhideRow, unhideRows, unmergeCells, unmergeCellsAt, writeRange, } from './worksheet.js';
 export type { MultiCellRange } from './cell-range.js';
 export { expandRangeStr, intersectionRange, isCellInRange, isRangeInRange, rangeArea, rangeContainsCell, rangeContainsRange, rangesOverlap, shiftRange, unionRange, } from './cell-range.js';
 export type { ColumnDimension, RowDimension } from './dimensions.js';
 export { makeColumnDimension, makeRowDimension } from './dimensions.js';
-export type { Pane, PaneState, PaneType, Selection, SheetView, SheetViewMode, } from './views.js';
+export type { FreezeCounts, Pane, PaneState, PaneType, Selection, SheetView, SheetViewMode, } from './views.js';
 export { freezePaneRef, makeFreezePane, makeSheetView } from './views.js';
 export type { LegacyComment } from './comments.js';
 export { makeLegacyComment } from './comments.js';

package/dist/worksheet/table-validate.d.ts

@@ -0,0 +1,7 @@
+import type { TableDefinition } from './table.js';
+import type { Worksheet } from './worksheet.js';
+/**
+ * Reject a table whose declared geometry or column names disagree with the
+ * sheet underneath it.
+ */
+export declare const validateTableAgainstSheet: (ws: Worksheet, table: TableDefinition) => void;

package/dist/worksheet/table.d.ts

@@ -1,6 +1,6 @@
 import type { Workbook } from '../workbook/workbook.js';
 import type { AutoFilter } from './auto-filter.js';
-import type { Worksheet } from './worksheet.js';
+import { type Worksheet } from './worksheet.js';
 export interface TableColumn {
     /** 1-based column id (per-table). */
     id: number;
@@ -65,6 +65,9 @@ export declare function makeTableDefinition(opts: {
  * in one call. Auto-assigns the workbook-unique `id`, derives `displayName`
  * from the supplied `name`, and constructs `TableColumn` records (1-based ids)
  * from a string-array shorthand.
+ *
+ * Goes through {@link addTable}, so the definition is checked against the sheet
+ * before it lands. Pass `headerRowCount: 0` for a genuinely header-less table.
  */
 export declare const addExcelTable: (wb: Workbook, ws: Worksheet, opts: {
     name: string;

package/dist/worksheet/views.d.ts

@@ -35,6 +35,11 @@ export interface SheetView {
 }
 /** Build a SheetView with sensible defaults. */
 export declare function makeSheetView(opts?: Partial<SheetView>): SheetView;
+/** How many rows / columns a freeze holds in place, counted from the top-left. */
+export interface FreezeCounts {
+    rows: number;
+    cols: number;
+}
 /**
  * Build a frozen Pane from a top-left coordinate. Per Excel semantics:
  * - "B2" → freeze 1 row + 1 col → xSplit=1, ySplit=1, activePane='bottomRight'

package/dist/worksheet/worksheet.d.ts

@@ -1,8 +1,8 @@
 import type { CellValue } from '../cell/cell.js';
 import { type Cell } from '../cell/cell.js';
-import { type InlineFont, type TextRun } from '../cell/rich-text.js';
 import type { Drawing } from '../drawing/drawing.js';
 import { type Color } from '../styles/colors.js';
+import { type CellCoordinateNumeric, type RangeRef } from '../utils/coordinate.js';
 import type { AutoFilter } from './auto-filter.js';
 import { type CellRange } from './cell-range.js';
 import type { LegacyComment } from './comments.js';
@@ -21,7 +21,7 @@ import type { SortState } from './sort-state.js';
 import type { WebPublishItem, WorksheetCustomProperty } from './web-publish.js';
 import { type Hyperlink } from './hyperlinks.js';
 import type { TableDefinition } from './table.js';
-import { type SheetView } from './views.js';
+import { type FreezeCounts, type SheetView } from './views.js';
 export interface Worksheet {
     title: string;
     /** Sparse store: row index → (col index → Cell). */
@@ -232,10 +232,29 @@ export declare function makeWorksheet(title: string): Worksheet;
 /** Resolve a 1-based or "A1" coordinate; returns the populated Cell or undefined. */
 export declare function getCell(ws: Worksheet, row: number, col: number): Cell | undefined;
 /**
- * Create or update a Cell at (row, col). Existing cells keep their styleId /
- * hyperlinkId / commentId unless explicitly overridden.
+ * Write a Cell at (row, col), creating it when the coordinate is empty.
+ * `value` always lands on the cell, so an existing value is replaced. Use
+ * {@link ensureCell} to reach a cell without writing to it. An existing cell
+ * keeps its styleId / hyperlinkId / commentId unless `styleId` is passed.
+ *
+ * `null` is the explicit empty value: it clears the value and leaves the cell
+ * in the sheet with its fill, border and number format, the way Excel's
+ * Delete key does. {@link deleteCell} drops the cell entirely, formatting
+ * included, and {@link clearRange} does the same across a rectangle.
+ */
+export declare function setCell(ws: Worksheet, row: number, col: number, value: CellValue, styleId?: number): Cell;
+/**
+ * Get the Cell at (row, col), allocating an empty one when the coordinate is
+ * not populated yet. An existing cell is returned untouched, value and all,
+ * which makes this the way to reach a cell you are about to style or attach a
+ * formula to.
+ *
+ * {@link mergeCells} drops the cells underneath a merge; reaching one of those
+ * coordinates allocates it again, and the written `<sheetData>` then carries a
+ * blank `<c>` under the merge. A merged block's value lives on its top-left
+ * cell, so address that coordinate when the block is what you mean.
  */
-export declare function setCell(ws: Worksheet, row: number, col: number, value?: CellValue, styleId?: number): Cell;
+export declare function ensureCell(ws: Worksheet, row: number, col: number): Cell;
 /** Delete a single cell from the sheet. Empty rows are pruned. */
 export declare function deleteCell(ws: Worksheet, row: number, col: number): void;
 /**
@@ -243,28 +262,51 @@ export declare function deleteCell(ws: Worksheet, row: number, col: number): voi
  * removed. Row maps that go empty are pruned. Column / row dimensions, merges,
  * comments etc. are left untouched.
  */
-export declare function clearRange(ws: Worksheet, range: string): number;
+export declare function clearRange(ws: Worksheet, range: RangeRef): number;
 /**
  * Wipe every populated cell on the worksheet, leaving styles, dimensions,
  * merges, comments, hyperlinks etc. intact. Returns the count of cells removed.
  * Useful when a sheet should be re-filled from scratch but its formatting kept.
  */
 export declare function clearAllCells(ws: Worksheet): number;
+export interface AppendRowOptions {
+    /**
+     * Style ids to apply per column, positionally aligned with `values`. Build
+     * the ids once with `registerCellStyle` from `@office-kit/xlsx/styles` and
+     * reuse them for every row.
+     *
+     * A column carrying a style id is written even when its value is empty, so a
+     * bordered-but-blank input column survives the append. Ids past the end of
+     * `values` therefore materialise styled blank cells, widening the sheet: a
+     * 4-value row with 5 ids occupies 5 columns, and `getMaxCol`, the
+     * `<dimension>` ref and `iterRows` all see the fifth. For ragged rows that
+     * should stop at their own last value, trim the array per row:
+     * `{ styleIds: columnStyles.slice(0, values.length) }`.
+     */
+    styleIds?: ReadonlyArray<number | undefined>;
+}
 /**
  * Append a row of values starting at the next empty row. Returns the row index
  * (1-based). Mirrors openpyxl's `Worksheet.append`. `null` / `undefined`
- * entries leave the cell empty.
+ * entries leave the cell empty unless `opts.styleIds` names a style for that
+ * column.
  */
-export declare function appendRow(ws: Worksheet, values: ReadonlyArray<CellValue | undefined>): number;
+export declare function appendRow(ws: Worksheet, values: ReadonlyArray<CellValue | undefined>, opts?: AppendRowOptions): number;
 /**
  * Bulk version of {@link appendRow}: append a 2D array of values one row at a
- * time. Returns `{firstRow, lastRow}` — both 1-based, inclusive. An empty input
- * returns `{firstRow, lastRow: firstRow - 1}` so callers can detect the no-op
- * without throwing.
+ * time. Returns `{firstRow, lastRow}`, both 1-based and inclusive. An empty
+ * input returns `{firstRow, lastRow: firstRow - 1}` so callers can detect the
+ * no-op without throwing.
  *
  * Common usage: `appendRows(ws, csvParsedRows)` for fast import.
+ *
+ * `opts` is column-indexed, not row-indexed: the same
+ * {@link AppendRowOptions.styleIds} apply to every row, which is the point when
+ * a column has one format down the whole table. Rows shorter than `styleIds`
+ * still get the trailing styled blanks described there, so trim per row when
+ * the input is ragged.
  */
-export declare function appendRows(ws: Worksheet, rows: ReadonlyArray<ReadonlyArray<CellValue | undefined>>): {
+export declare function appendRows(ws: Worksheet, rows: ReadonlyArray<ReadonlyArray<CellValue | undefined>>, opts?: AppendRowOptions): {
     firstRow: number;
     lastRow: number;
 };
@@ -282,7 +324,7 @@ export declare function appendRows(ws: Worksheet, rows: ReadonlyArray<ReadonlyAr
  * coordinates. An empty rows array returns `undefined` rather than an invalid
  * zero-area range.
  */
-export declare function writeRange(ws: Worksheet, startRef: string, values: ReadonlyArray<ReadonlyArray<CellValue | undefined>>): {
+export declare function writeRange(ws: Worksheet, startRef: string | CellCoordinateNumeric, values: ReadonlyArray<ReadonlyArray<CellValue | undefined>>): {
     minRow: number;
     maxRow: number;
     minCol: number;
@@ -386,10 +428,11 @@ export declare function getCellAddress(ws: Worksheet, c: Cell): string;
  * Sheet-qualified A1 range address — `'Sheet1!A1:B5'` for plain titles,
  * `'\'Quarter 1\'!A1:B5'` for titles needing quoting. Pass any A1-style range
  * string (single cell `'A1'`, rectangle `'A1:B5'`, row span `'1:5'`, column
- * span `'A:E'`); the helper does no validation on `range` itself — that's the
- * caller's responsibility.
+ * span `'A:E'`), which is forwarded verbatim without validation, or numeric
+ * bounds, which are validated and normalised into a rectangle so the address
+ * names the region the other range helpers would operate on.
  */
-export declare function getRangeAddress(ws: Worksheet, range: string): string;
+export declare function getRangeAddress(ws: Worksheet, range: RangeRef): string;
 /**
  * True iff the worksheet has zero non-empty cells. Equivalent to
  * `getNonEmptyCellCount(ws) === 0` but short-circuits on the first non-null
@@ -450,57 +493,41 @@ export declare function replaceCellValues(ws: Worksheet, search: string | ((valu
  * predicate over every populated cell), but only cells inside the rectangular
  * `range` are visited. Returns the count changed.
  */
-export declare function replaceInRange(ws: Worksheet, range: string, search: string | ((value: CellValue, cell: Cell) => boolean), replacement: CellValue): number;
+export declare function replaceInRange(ws: Worksheet, range: RangeRef, search: string | ((value: CellValue, cell: Cell) => boolean), replacement: CellValue): number;
 /**
  * Iterate the populated cells inside a rectangular range. Cells that don't
  * exist in the sparse store are skipped (no auto-allocate). Use {@link
  * applyToRange} when you need every coordinate visited regardless of
  * population.
  */
-export declare function getCellsInRange(ws: Worksheet, range: string): IterableIterator<Cell>;
+export declare function getCellsInRange(ws: Worksheet, range: RangeRef): IterableIterator<Cell>;
 /**
- * Set a cell's value to a rich-text run array. Accepts either a pre-built
- * `RichText` (frozen array of TextRun) or a fresh `Array<{ text, font? }>`
- * shape — `makeRichText` normalises and freezes the runs in either case.
- * Returns the cell.
+ * A1-addressed {@link setCell}: resolves `coord` to a numeric (row, col) and
+ * writes `value` there. Throws `OpenXmlSchemaError` when `coord` is not a
+ * plain A1 reference.
  */
-export declare function setCellRichText(ws: Worksheet, row: number, col: number, runs: ReadonlyArray<TextRun | {
-    text: string;
-    font?: InlineFont;
-}>, styleId?: number): Cell;
-/**
- * Set a cell's value to a normal Excel formula. Combines `setCell` with
- * `setFormula`. The leading `=` is stripped if present so callers can pass
- * `'=A1+1'` or `'A1+1'` interchangeably.
- */
-export declare function setCellFormula(ws: Worksheet, row: number, col: number, formula: string, opts?: {
-    cachedValue?: number | string | boolean;
-    styleId?: number;
-}): Cell;
-/**
- * Set a cell's value to an array (CSE) formula spanning `ref`. Lands the
- * formula on the top-left cell of the range — Excel reads the `ref` attribute
- * to know how far the result spreads. Equivalent to `setCell` +
- * `setArrayFormula`. Leading `=` is stripped.
- */
-export declare function setCellArrayFormula(ws: Worksheet, row: number, col: number, ref: string, formula: string, opts?: {
-    cachedValue?: number | string | boolean;
-    styleId?: number;
-}): Cell;
-/** Resolve an "A1" coordinate to a numeric (col, row) pair on the sheet. */
-export declare function setCellByCoord(ws: Worksheet, coord: string, value?: CellValue, styleId?: number): Cell;
+export declare function setCellByCoord(ws: Worksheet, coord: string, value: CellValue, styleId?: number): Cell;
 /** Convenience getter accepting an "A1" coordinate. */
 export declare function getCellByCoord(ws: Worksheet, coord: string): Cell | undefined;
+/**
+ * A1-addressed {@link ensureCell}. Throws `OpenXmlSchemaError` when `coord` is
+ * not a plain A1 reference.
+ */
+export declare function ensureCellByCoord(ws: Worksheet, coord: string): Cell;
 /**
  * Merge a range. The top-left cell keeps its value; every other cell in the
  * range is dropped from `ws.rows` so the on-wire `<sheetData>` won't carry
  * phantom cells underneath the merge. Mirrors openpyxl's
  * `MergedCellRange.format()`. Idempotent for an identical range, throws when
  * the range overlaps an existing merge.
+ *
+ * The registered range is a validated, normalised copy of `refOrRange`, so
+ * mutating a bounds object afterwards can't rewrite a merge that is already on
+ * the sheet.
  */
-export declare function mergeCells(ws: Worksheet, refOrRange: string | CellRange): CellRange;
+export declare function mergeCells(ws: Worksheet, refOrRange: RangeRef): CellRange;
 /** Drop a previously-merged range. No-op if the range isn't registered. */
-export declare function unmergeCells(ws: Worksheet, refOrRange: string | CellRange): boolean;
+export declare function unmergeCells(ws: Worksheet, refOrRange: RangeRef): boolean;
 /** Read-only iterator over the worksheet's merged ranges. */
 export declare function getMergedCells(ws: Worksheet): ReadonlyArray<CellRange>;
 /** True iff (row, col) sits inside any merged range — top-left included. */
@@ -524,26 +551,28 @@ export declare function unmergeCellsAt(ws: Worksheet, row: number, col: number):
  */
 export declare function removeAllMergedRanges(ws: Worksheet): number;
 /**
- * Freeze rows / columns above + left of `topLeftRef` ("B2" → 1 row + 1 col).
+ * Freeze rows / columns above + left of the given top-left cell. Takes either
+ * the A1 ref of the first unfrozen cell (`"B2"` freezes 1 row + 1 column) or
+ * the counts directly (`{ rows: 1, cols: 0 }` freezes the header row alone).
  * Pass `undefined` to clear any existing freeze. Targets the workbook's primary
  * SheetView (`ws.views[0]`); creates one if absent.
  */
-export declare function setFreezePanes(ws: Worksheet, topLeftRef: string | undefined): void;
+export declare function setFreezePanes(ws: Worksheet, topLeft: string | FreezeCounts | undefined): void;
 /** Inverse of {@link setFreezePanes}; returns the top-left ref or undefined when no freeze is active. */
 export declare function getFreezePanes(ws: Worksheet): string | undefined;
 /**
- * Freeze the top `count` rows. Equivalent to `setFreezePanes(ws, "A${count +
- * 1}")` — Excel's "Freeze Top Row" is `freezeRows(ws, 1)`.
+ * Freeze the top `count` rows. Equivalent to `setFreezePanes(ws, { rows: count,
+ * cols: 0 })`, and Excel's "Freeze Top Row" is `freezeRows(ws, 1)`. Rejects 0,
+ * which the counts form accepts: {@link unfreezePanes} is how a freeze is
+ * cleared.
  */
 export declare function freezeRows(ws: Worksheet, count: number): void;
 /**
- * Freeze the leftmost `count` columns. Equivalent to `setFreezePanes(ws,
- * "${columnLetter(count + 1)}1")` — Excel's "Freeze First Column" is
- * `freezeColumns(ws, 1)`.
+ * Freeze the leftmost `count` columns. Equivalent to `setFreezePanes(ws, {
+ * rows: 0, cols: count })`, and Excel's "Freeze First Column" is
+ * `freezeColumns(ws, 1)`. Rejects 0 for the same reason as {@link freezeRows}.
  */
 export declare function freezeColumns(ws: Worksheet, count: number): void;
-/** Freeze both top `rows` rows AND left `cols` columns. */
-export declare function freezePanes(ws: Worksheet, rows: number, cols: number): void;
 /** Drop the freeze pane on the primary view. */
 export declare const unfreezePanes: (ws: Worksheet) => void;
 /**
@@ -560,7 +589,7 @@ export declare const freezeFirstColumn: (ws: Worksheet) => void;
 /**
  * Freeze both row 1 and column A so the header row + label column stay visible.
  * Equivalent to selecting B2 and "View → Freeze Panes". Shortcut for
- * `freezePanes(ws, 1, 1)`.
+ * `setFreezePanes(ws, { rows: 1, cols: 1 })`.
  */
 export declare const freezeFirstRowAndColumn: (ws: Worksheet) => void;
 /**
@@ -605,19 +634,24 @@ export declare function setSelectedRange(ws: Worksheet, sqref: string): void;
  * down starting at the top-left of `range`; subsequent rows follow. `null` /
  * `undefined` entries skip the cell. Useful for dropping a header + data block
  * in one call.
+ *
+ * Values past the range's bottom or right edge are dropped rather than written
+ * outside it, the way {@link copyRange} clips to its target extent. Use
+ * {@link writeRange} for the unbounded form, which takes an anchor and grows to
+ * fit the array.
  */
-export declare function setRangeValues(ws: Worksheet, range: string, rows: ReadonlyArray<ReadonlyArray<CellValue | null | undefined>>): void;
+export declare function setRangeValues(ws: Worksheet, range: RangeRef, rows: ReadonlyArray<ReadonlyArray<CellValue | null | undefined>>): void;
 /**
  * Iterate over every cell coordinate in a range, calling `visit` once per (row,
  * col). Allocates the cell on first touch so callers can mutate it freely.
  */
-export declare function applyToRange(ws: Worksheet, range: string, visit: (cell: Cell, row: number, col: number) => void): void;
+export declare function applyToRange(ws: Worksheet, range: RangeRef, visit: (cell: Cell, row: number, col: number) => void): void;
 /**
  * Read a rectangular range as a dense 2-D array of values. Empty cells yield
  * `null`. The shape is `[maxRow - minRow + 1] × [maxCol - minCol + 1]`. Inverse
  * of {@link setRangeValues}.
  */
-export declare function getRangeValues(ws: Worksheet, range: string): (CellValue | null)[][];
+export declare function getRangeValues(ws: Worksheet, range: RangeRef): (CellValue | null)[][];
 /**
  * Copy every populated cell from `source` to `target` (within the same
  * worksheet, or across worksheets via `targetWs`). Cells are shallow-cloned:
@@ -632,7 +666,7 @@ export declare function getRangeValues(ws: Worksheet, range: string): (CellValue
  *
  * Returns the number of cells copied.
  */
-export declare function copyRange(ws: Worksheet, source: string, target: string, opts?: {
+export declare function copyRange(ws: Worksheet, source: RangeRef, target: RangeRef, opts?: {
     targetWs?: Worksheet;
 }): number;
 /**
@@ -643,7 +677,7 @@ export declare function copyRange(ws: Worksheet, source: string, target: string,
  * cells aren't overwritten before they've been read. Returns the number of
  * cells moved.
  */
-export declare function moveRange(ws: Worksheet, source: string, target: string, opts?: {
+export declare function moveRange(ws: Worksheet, source: RangeRef, target: RangeRef, opts?: {
     targetWs?: Worksheet;
 }): number;
 /**
@@ -890,7 +924,14 @@ export declare function removeAllDataValidations(ws: Worksheet): number;
 export declare function setAutoFilter(ws: Worksheet, filter: AutoFilter | undefined): void;
 /** Read the current AutoFilter, if any. */
 export declare function getAutoFilter(ws: Worksheet): AutoFilter | undefined;
-/** Append a table. The id and displayName must be workbook-unique — the caller is responsible. */
+/**
+ * Append a table, rejecting one whose geometry or column names disagree with
+ * the cells under it: the column count has to match the width of `ref`, `ref`
+ * has to contain the header and totals rows, column names have
+ * to be unique and non-empty, and every header cell has to hold its column's
+ * name as text. The id and displayName must be workbook-unique, and stay the
+ * caller's responsibility: neither is visible from a single sheet.
+ */
 export declare function addTable(ws: Worksheet, table: TableDefinition): TableDefinition;
 /** Look up a table by displayName. */
 export declare function getTable(ws: Worksheet, displayName: string): TableDefinition | undefined;

package/dist/worksheet/writer.d.ts

@@ -1,5 +1,6 @@
 import { type Cell } from '../cell/cell.js';
 import type { Relationships } from '../packaging/relationships.js';
+import type { Stylesheet } from '../styles/stylesheet.js';
 import type { SharedStringsTable } from '../workbook/shared-strings.js';
 import type { HeaderFooter, PageMargins, PageSetup } from './page-setup.js';
 import type { WebPublishItem } from './web-publish.js';
@@ -7,6 +8,12 @@ import type { Worksheet } from './worksheet.js';
 export interface WorksheetWriteContext {
     /** Accumulator the writer mutates as it emits string cells. */
     sharedStrings: SharedStringsTable;
+    /**
+     * Stylesheet the sheet's cells resolve their `styleId` against. Held live
+     * rather than as a count, because the write-only path grows the pool while
+     * rows stream out.
+     */
+    styles: Stylesheet;
     /**
      * Workbook epoch for `Date` / `{kind:'duration'}` cell serialisation. `true`
      * = Mac 1904 epoch; `false` (default) = Windows 1900 epoch. Modern Excel