@shbernal/ts-xlsx 1.3.1 → 2.1.0

package/dist/core/style.js

@@ -1,83 +1,93 @@
-const NAMED_UNDERLINE_STYLES = new Set([
-    'none',
-    'single',
-    'double',
-    'singleAccounting',
-    'doubleAccounting',
-]);
+const NAMED_UNDERLINE_STYLES = {
+    none: true,
+    single: true,
+    double: true,
+    singleAccounting: true,
+    doubleAccounting: true,
+};
 export function isNamedUnderlineStyle(value) {
-    return NAMED_UNDERLINE_STYLES.has(value);
+    return Object.hasOwn(NAMED_UNDERLINE_STYLES, value);
+}
+export function parseArgb(value) {
+    const hex = value.startsWith('#') ? value.slice(1) : value;
+    const argb = hex.length === 6 ? `FF${hex}` : hex;
+    return /^[0-9a-fA-F]{8}$/.test(argb) ? argb : undefined;
 }
-const FILL_PATTERN_TYPES = new Set([
-    'none',
-    'solid',
-    'gray125',
-    'darkGray',
-    'mediumGray',
-    'lightGray',
-    'gray0625',
-    'darkHorizontal',
-    'darkVertical',
-    'darkDown',
-    'darkUp',
-    'darkGrid',
-    'darkTrellis',
-    'lightHorizontal',
-    'lightVertical',
-    'lightDown',
-    'lightUp',
-    'lightGrid',
-    'lightTrellis',
-]);
+const FILL_PATTERN_TYPES = {
+    none: true,
+    solid: true,
+    gray125: true,
+    darkGray: true,
+    mediumGray: true,
+    lightGray: true,
+    gray0625: true,
+    darkHorizontal: true,
+    darkVertical: true,
+    darkDown: true,
+    darkUp: true,
+    darkGrid: true,
+    darkTrellis: true,
+    lightHorizontal: true,
+    lightVertical: true,
+    lightDown: true,
+    lightUp: true,
+    lightGrid: true,
+    lightTrellis: true,
+};
 export function isFillPatternType(value) {
-    return FILL_PATTERN_TYPES.has(value);
+    return Object.hasOwn(FILL_PATTERN_TYPES, value);
 }
-const BORDER_STYLES = new Set([
-    'thin',
-    'medium',
-    'thick',
-    'dashed',
-    'dotted',
-    'double',
-    'hair',
-    'mediumDashed',
-    'dashDot',
-    'mediumDashDot',
-    'dashDotDot',
-    'mediumDashDotDot',
-    'slantDashDot',
-]);
+const BORDER_STYLES = {
+    thin: true,
+    medium: true,
+    thick: true,
+    dashed: true,
+    dotted: true,
+    double: true,
+    hair: true,
+    mediumDashed: true,
+    dashDot: true,
+    mediumDashDot: true,
+    dashDotDot: true,
+    mediumDashDotDot: true,
+    slantDashDot: true,
+};
 export function isBorderStyle(value) {
-    return BORDER_STYLES.has(value);
+    return Object.hasOwn(BORDER_STYLES, value);
 }
+const FONT_VERTICAL_ALIGNMENTS = {
+    superscript: true,
+    subscript: true,
+};
 export function isFontVerticalAlignment(value) {
-    return value === 'superscript' || value === 'subscript';
+    return Object.hasOwn(FONT_VERTICAL_ALIGNMENTS, value);
 }
+const FONT_SCHEMES = { minor: true, major: true, none: true };
 export function isFontScheme(value) {
-    return value === 'minor' || value === 'major' || value === 'none';
+    return Object.hasOwn(FONT_SCHEMES, value);
 }
-const HORIZONTAL_ALIGNMENTS = new Set([
-    'general',
-    'left',
-    'center',
-    'right',
-    'fill',
-    'justify',
-    'centerContinuous',
-    'distributed',
-]);
+const HORIZONTAL_ALIGNMENTS = {
+    general: true,
+    left: true,
+    center: true,
+    right: true,
+    fill: true,
+    justify: true,
+    centerContinuous: true,
+    distributed: true,
+};
 export function isHorizontalAlignment(value) {
-    return HORIZONTAL_ALIGNMENTS.has(value);
+    return Object.hasOwn(HORIZONTAL_ALIGNMENTS, value);
 }
-const VERTICAL_ALIGNMENTS = new Set([
-    'top',
-    'center',
-    'bottom',
-    'justify',
-    'distributed',
-]);
+const VERTICAL_ALIGNMENTS = {
+    top: true,
+    center: true,
+    bottom: true,
+    justify: true,
+    distributed: true,
+};
 export function isVerticalAlignment(value) {
-    return VERTICAL_ALIGNMENTS.has(value);
+    return Object.hasOwn(VERTICAL_ALIGNMENTS, value);
 }
 const CELL_STYLE_FACET_KEYS = {
     fill: true,
@@ -92,6 +102,11 @@ export function assignStyleFacets(target, source) {
     for (const facet of CELL_STYLE_FACETS)
         copyFacet(target, source, facet);
 }
+export function pickStyleFacets(source) {
+    const facets = {};
+    assignStyleFacets(facets, source);
+    return facets;
+}
 function copyFacet(target, source, key) {
     const value = source[key];
     if (value !== undefined)

package/dist/core/table-style.d.ts

@@ -4,19 +4,19 @@ import type { DifferentialStyle } from './style.ts';
  *
  * The first thirteen apply to a **table**; the rest style a **pivot table**, which has regions a
  * table does not have (subtotal rows, page-field labels, subheadings). Both live in the same
- * enumeration and the same `<tableStyle>` element — what decides which regions a consumer honours is
- * the style's own `table`/`pivot` flags, not the element names — so the type carries all of them
+ * enumeration and the same `<tableStyle>` element. What decides which regions a consumer honours is
+ * the style's own `table`/`pivot` flags, not the element names, so the type carries all of them
  * rather than splitting into two enumerations that a caller would have to choose between up front.
  */
 export declare const TABLE_STYLE_ELEMENT_TYPES: readonly ['wholeTable', 'headerRow', 'totalRow', 'firstColumn', 'lastColumn', 'firstRowStripe', 'secondRowStripe', 'firstColumnStripe', 'secondColumnStripe', 'firstHeaderCell', 'lastHeaderCell', 'firstTotalCell', 'lastTotalCell', 'firstSubtotalColumn', 'secondSubtotalColumn', 'thirdSubtotalColumn', 'firstSubtotalRow', 'secondSubtotalRow', 'thirdSubtotalRow', 'blankRow', 'firstColumnSubheading', 'secondColumnSubheading', 'thirdColumnSubheading', 'firstRowSubheading', 'secondRowSubheading', 'thirdRowSubheading', 'pageFieldLabels', 'pageFieldValues'];
 /** One region of a table or pivot that a table style can format. */
 export type TableStyleElementType = (typeof TABLE_STYLE_ELEMENT_TYPES)[number];
-/** The four element types banded across several rows or columns — the only ones {@link TableStyleElement.size} means anything on. */
+/** The four element types banded across several rows or columns: the only ones {@link TableStyleElement.size} means anything on. */
 export declare const STRIPE_ELEMENT_TYPES: ReadonlySet<TableStyleElementType>;
 export declare function isTableStyleElementType(value: string): value is TableStyleElementType;
 /**
  * How one region of a table is formatted: a {@link DifferentialStyle} laid over whatever the cells
- * already carry, plus — for a stripe — how many rows or columns wide one band is.
+ * already carry, plus, for a stripe, how many rows or columns wide one band is.
  *
  * A `numFmt` here is carried faithfully but has no visible effect: Excel's own table-style element
  * exposes a font, an interior and borders, and nothing for a number format. See
@@ -24,7 +24,7 @@ export declare function isTableStyleElementType(value: string): value is TableSt
  */
 export interface TableStyleElement extends DifferentialStyle {
     /**
-     * The band width, in rows or columns, for a striped element — `2` makes each band two rows deep.
+     * The band width, in rows or columns, for a striped element: `2` makes each band two rows deep.
      * Defaults to 1.
      *
      * Meaningful **only** on the four stripe types ({@link STRIPE_ELEMENT_TYPES}); ECMA-376 says so and
@@ -41,7 +41,7 @@ export interface TableStyleElement extends DifferentialStyle {
  * Elements are applied in the order ECMA-376 fixes, not the order they are written here: whole table,
  * then the column stripes, then the row stripes, then last/first column, header row, total row, and
  * the four corner cells. So a row stripe wins over a column stripe, and both win over the whole-table
- * formatting — worth knowing when a stripe colour appears not to take.
+ * formatting, which is worth knowing when a stripe colour appears not to take.
  */
 export interface TableStyle {
     /** The name a table references, and the name Excel shows in its style gallery. */
@@ -58,10 +58,10 @@ export interface TableStyle {
  *
  * Both failures here are of the same kind: Excel accepts the file and quietly does nothing with the
  * part the caller cared about. An empty name means no table can ever reference the style, and a
- * `size` outside a stripe is ignored — neither shows up as a repair prompt or a schema error, so the
+ * `size` outside a stripe is ignored. Neither shows up as a repair prompt or a schema error, so the
  * only place to catch them is the call that made them.
  *
- * @throws {AuthoringError} if the name is empty, or a non-stripe element carries a `size`, or a `size` is not
- *   a positive integer.
+ * @throws {AuthoringError} if the name is empty, or a non-stripe element carries a `size`.
+ * @throws {RangeError} if a `size` is not a positive integer.
  */
 export declare function checkTableStyle(style: TableStyle): void;

package/dist/core/table-style.js

@@ -56,7 +56,7 @@ export function checkTableStyle(style) {
                 `${[...STRIPE_ELEMENT_TYPES].join(', ')}`);
         }
         if (!Number.isInteger(size) || size < 1) {
-            throw new AuthoringError(`Invalid table style band size ${size}: expected a positive integer`);
+            throw new RangeError(`Invalid table style band size ${size}: expected a positive integer`);
         }
     }
 }

package/dist/core/table.d.ts

@@ -1,36 +1,51 @@
+import { type GridRect } from './address.ts';
 import type { CellStyle } from './style.ts';
 import type { CellValue } from './value.ts';
-/** A per-column cell format applied to a table's body cells — the facets Excel's table-column style
+/** A per-column cell format applied to a table's body cells: the facets Excel's table-column style
  * bakes into the cells rather than storing as table metadata. Every facet ({@link CellStyle}) is
  * optional; only the ones set are applied, leaving the rest of each cell's style untouched. */
 export type TableColumnStyle = Readonly<CellStyle>;
-/** Writes a value into the owning worksheet's grid at a 1-based row/column, applying the column's
- * style (if any) to the cell — the hook a {@link Table} uses to materialise the cells of a row
- * appended through {@link Table.addRow}. A worksheet supplies it when it registers the table; a table
- * built standalone has none and cannot write cell values. */
-export type TableCellWriter = (row: number, col: number, value: CellValue, style?: TableColumnStyle) => void;
-/** Inserts one empty row into the owning worksheet's grid at a 1-based `row`, shifting that row and
- * everything below it down by one — the hook a {@link Table} with a totals row uses to open a slot
- * for an appended data row above the totals. Relocating the totals row lives in the grid, so a
- * standalone table has no inserter and cannot append past a totals row. */
-export type TableRowInserter = (row: number) => void;
+/**
+ * The channel a registered table holds into its owning worksheet's grid. A worksheet supplies it
+ * when it registers the table; a table built standalone (a unit test, a bare model) has none, so it
+ * can be inspected but cannot materialise or append cells, and appending throws rather than
+ * silently dropping the values.
+ *
+ * All three coordinates are 1-based.
+ */
+export interface TableGrid {
+    /**
+     * Whether the cell at this position already holds a value. The materialiser's round-trip guard
+     * asks this and nothing else: it must not create the cell, because asking whether a table's frame
+     * is already filled would otherwise fill the grid with the empty cells it was asking about.
+     */
+    holdsValue(row: number, col: number): boolean;
+    /** Write a value, applying the column's style (if any) to the cell. */
+    writeCell(row: number, col: number, value: CellValue, style?: TableColumnStyle): void;
+    /**
+     * Insert one empty row at `row`, shifting that row and everything below it down by one: how a
+     * table with a totals row opens a slot for an appended data row above the totals. Relocating the
+     * totals row lives in the grid, which is why this is the grid's job and not the table's.
+     */
+    insertRow(row: number): void;
+}
 /**
  * A table's visual style (`<tableStyleInfo>`): the named style to apply plus the banding/highlight
- * toggles. Every field is a tri-state so a round-trip stays faithful — a value present in the source
+ * toggles. Every field is a tri-state so a round-trip stays faithful: a value present in the source
  * re-emits, one the source omitted stays omitted rather than being defaulted to `"0"`. A workbook
  * whose part carries no `<tableStyleInfo>` at all leaves {@link TableOptions.style} undefined.
  */
 export interface TableStyleInfo {
     /**
-     * Named table style to apply — one of the built-in gallery (`"TableStyleMedium2"`, …) or a custom
+     * Named table style to apply: one of the built-in gallery (`"TableStyleMedium2"`, …) or a custom
      * one the workbook defines with {@link Workbook.addTableStyle}.
      *
-     * **Not validated.** A name that matches nothing renders the table unstyled, silently — but this
-     * library must not be the thing that rejects it. A reader has to accept a name from a newer Excel
-     * than the gallery list it was built with, and a writer that threw would make round-tripping such a
-     * file impossible; there is also no diagnostics channel to warn through, so the only options were
-     * "throw" and "accept". Accepting is the one that never makes a readable file unreadable. If a
-     * warning channel is ever added, this is the first thing that should use it.
+     * **Not validated.** A name that matches nothing renders the table unstyled, silently. Even so,
+     * this library must not be the thing that rejects it. A reader has to accept a name from a newer
+     * Excel than the gallery list it was built with, and a writer that threw would make round-tripping
+     * such a file impossible; there is also no diagnostics channel to warn through, so the only
+     * options were "throw" and "accept". Accepting is the one that never makes a readable file
+     * unreadable. If a warning channel is ever added, this is the first thing that should use it.
      */
     readonly name?: string;
     /** Emphasise the first column. */
@@ -44,17 +59,17 @@ export interface TableStyleInfo {
 }
 /**
  * OOXML's totals-row function names (`ST_TotalsRowFunction`) to the `SUBTOTAL` first-argument code
- * Excel writes into a materialised totals cell. The `10x` band ignores manually hidden rows — the
+ * Excel writes into a materialised totals cell. The `10x` band ignores manually hidden rows, the
  * behaviour Excel's totals row uses. The one inversion trap: `count` is COUNTA (103, non-empty) while
  * `countNums` is COUNT (102, numbers only). `none` (no aggregate) has no built-in code, so a column
- * carrying it is absent here and its totals cell is left unmaterialised — Excel accepts the blank
+ * carrying it is absent here and its totals cell is left unmaterialised: Excel accepts the blank
  * cell. `custom` is likewise absent: its aggregate is not a `SUBTOTAL` but the arbitrary formula
  * stored in {@link TableColumn.totalsRowFormula}, which the reader/writer round-trip and the
  * materialiser writes into the cell verbatim.
  */
 export declare const TOTALS_ROW_SUBTOTAL_CODE: Readonly<Partial<Record<TotalsRowFunction, number>>>;
 /**
- * The values `ST_TotalsRowFunction` (ECMA-376 §18.18.86) can take — a closed OOXML enumeration Excel
+ * The values `ST_TotalsRowFunction` (ECMA-376 §18.18.86) can take: a closed OOXML enumeration Excel
  * does not extend over time (unlike, say, a conditional-formatting rule type), so an author-side typo
  * such as `"avg"` is a compile error here rather than a silently no-op attribute at write time.
  */
@@ -63,7 +78,7 @@ export type TotalsRowFunction = 'average' | 'countNums' | 'count' | 'max' | 'min
 export declare function isTotalsRowFunction(value: string): value is TotalsRowFunction;
 /** One column of a table: a header name and its optional totals-row behaviour. */
 export interface TableColumn {
-    /** The column's header/display name. Must be unique within the table (case-insensitively) —
+    /** The column's header/display name. Must be unique within the table (case-insensitively):
      * Excel writes a table with colliding column names as corrupt. A collision supplied at construction
      * is disambiguated deterministically (the first keeps its name, later clashes gain a numeric
      * suffix), the same repair the reader applies to a loaded file, rather than being rejected. */
@@ -73,7 +88,7 @@ export interface TableColumn {
     /** Built-in totals-row aggregate (`"sum"`, `"average"`, `"count"`, …), or `"custom"` when the
      * column's total is the arbitrary formula in {@link totalsRowFormula} rather than a `SUBTOTAL`. */
     readonly totalsRowFunction?: TotalsRowFunction;
-    /** The formula (no leading `=`) backing a `totalsRowFunction: "custom"` column — OOXML's
+    /** The formula (no leading `=`) backing a `totalsRowFunction: "custom"` column. This is OOXML's
      * `<totalsRowFormula>` child. Round-tripped verbatim and written into the totals cell as the
      * cell's formula. Meaningful only alongside `totalsRowFunction: "custom"`; ignored otherwise. */
     readonly totalsRowFormula?: string;
@@ -83,13 +98,13 @@ export interface TableColumn {
     readonly style?: TableColumnStyle;
 }
 export interface TableOptions {
-    /** Table name — a valid Excel identifier, unique across the workbook. This is the name used in
+    /** Table name: a valid Excel identifier, unique across the workbook. This is the name used in
      * structured formula references (`Table1[Column]`). */
     name: string;
     /** Human-facing display name shown in the UI. A free-form label (spaces allowed) that need not
      * be a valid identifier. Defaults to {@link name} when omitted. */
     displayName?: string;
-    /** A1 reference of the table's top-left cell (an anchor, e.g. `"A1"` — not the full range). */
+    /** A1 reference of the table's top-left cell (an anchor, e.g. `"A1"`, not the full range). */
     ref: string;
     /** The table's columns, left to right. At least one is required. */
     columns: readonly TableColumn[];
@@ -99,36 +114,23 @@ export interface TableOptions {
     headerRow?: boolean;
     /** Whether the table has a totals row. Defaults to `false`. */
     totalsRow?: boolean;
-    /** The `totalsRowShown` flag on a table *without* a totals row — Excel's record of whether a
+    /** The `totalsRowShown` flag on a table *without* a totals row: Excel's record of whether a
      * totals row has ever been toggled on. Tri-state so a round-trip is faithful: `false` re-emits
      * `totalsRowShown="0"`, `true` re-emits `totalsRowShown="1"`, and `undefined` (the authoring
-     * default) emits nothing — a file read without the attribute must not have one injected. Ignored
+     * default) emits nothing: a file read without the attribute must not have one injected. Ignored
      * when {@link totalsRow} is set, since a present totals row already implies it is shown. */
     totalsRowShown?: boolean;
     /** Whether the header row carries an autoFilter. Defaults to {@link headerRow}: a header table
      * gains an autoFilter, a headerless one never can. Set `false` to keep a header table's rows
-     * unfiltered — a file read without an autoFilter must round-trip without one being injected. */
+     * unfiltered: a file read without an autoFilter must round-trip without one being injected. */
     autoFilter?: boolean;
     /** The table's visual style. Preserved verbatim across a round-trip; when omitted, a freshly
      * authored table is written with Excel's default (`TableStyleMedium2`, banded rows). A part read
      * with no `<tableStyleInfo>` sets this to `undefined`. See {@link TableStyleInfo}. */
     style?: TableStyleInfo;
 }
-/**
- * Return copies of `columns` with every name made unique (case-insensitively): the first occurrence
- * keeps its name; a later clash gains the smallest numeric suffix that resolves it (`foo`, `foo2`,
- * `foo3`, …). OOXML requires unique column names within a table — Excel treats a collision as
- * corruption — so this is applied both when a table is authored and when one is read from a file,
- * keeping the two paths identical rather than rejecting a name list the reader would accept.
- */
-export declare function disambiguateColumnNames(columns: readonly TableColumn[]): TableColumn[];
-/** The rectangle a table occupies, in 1-based coordinates. */
-export interface TableRegion {
-    readonly top: number;
-    readonly left: number;
-    readonly bottom: number;
-    readonly right: number;
-}
+/** The rectangle a table occupies, as the {@link GridRect} every range-shaped thing in the library is. */
+export type TableRegion = GridRect;
 export declare class Table {
     #private;
     readonly name: string;
@@ -139,9 +141,9 @@ export declare class Table {
     readonly totalsRowShown: boolean | undefined;
     readonly autoFilter: boolean;
     readonly style: TableStyleInfo | undefined;
-    constructor(options: TableOptions, writeCell?: TableCellWriter, insertRow?: TableRowInserter);
+    constructor(options: TableOptions, grid?: TableGrid);
     get columnCount(): number;
-    /** The number of data rows (excludes the header and totals rows). Always defined — a table loaded
+    /** The number of data rows (excludes the header and totals rows). Always defined: a table loaded
      * from a file derives it from the stored range, so reading the height never throws. */
     get rowCount(): number;
     /**
@@ -150,9 +152,9 @@ export declare class Table {
      * one, so this works identically whether the table was built in memory or read from a file.
      *
      * A table carrying a totals row appends above it: the new data row lands where the totals row sat,
-     * and the totals row (with any sheet content below) shifts down by one — exactly what inserting a
+     * and the totals row (with any sheet content below) shifts down by one, exactly what inserting a
      * worksheet row does. That relocation lives in the grid, so a totals-row table not attached to a
-     * worksheet throws, as does passing `values` on any detached table — there is nowhere to put them.
+     * worksheet throws, as does passing `values` on any detached table: there is nowhere to put them.
      */
     addRow(values?: readonly CellValue[]): void;
     /**
@@ -171,7 +173,7 @@ export declare class Table {
      */
     shiftColumns(start: number, count: number, delta: number): boolean;
     /**
-     * The options that reconstruct this table — the anchor as a single-cell ref (not the derived
+     * The options that reconstruct this table: the anchor as a single-cell ref (not the derived
      * full range), the columns, and the data-row count with the header/totals flags. Feeding this
      * back to the constructor yields an equivalent table, so a worksheet model can carry a table
      * losslessly across an export/import round-trip.
@@ -179,11 +181,11 @@ export declare class Table {
     get options(): TableOptions;
     /** The full A1 range the table occupies: header (if any) + data rows + totals (if any). Distinct
      * from {@link TableOptions.ref} (and {@link options}'s own `ref`), which is only the single-cell
-     * anchor a table is constructed from — this is the anchor plus the columns/rows it has grown to
+     * anchor a table is constructed from; this is the anchor plus the columns/rows it has grown to
      * cover. */
     get range(): string;
     /**
-     * The autoFilter range — the header row plus the data rows, never the totals row — or
+     * The autoFilter range (the header row plus the data rows, never the totals row), or
      * `undefined` when the table has no autoFilter: either it is headerless (an autoFilter has
      * nothing to anchor to and Excel treats its presence as corruption) or its {@link autoFilter}
      * flag is off (a table read without one must not gain one on round-trip).

package/dist/core/table.js

@@ -1,5 +1,6 @@
 import { AuthoringError } from '../errors.js';
-import { decodeAddress, encodeAddress } from './address.js';
+import { decodeCellRef, encodeAddress } from './address.js';
+import { isDeletedSpan, shiftIndex } from './grid-shift.js';
 function cloneStyleInfo(style) {
     const clone = {};
     if (style.name !== undefined && style.name !== 'None')
@@ -24,23 +25,23 @@ export const TOTALS_ROW_SUBTOTAL_CODE = {
     sum: 109,
     var: 110,
 };
-const TOTALS_ROW_FUNCTIONS = new Set([
-    'average',
-    'countNums',
-    'count',
-    'max',
-    'min',
-    'stdDev',
-    'sum',
-    'var',
-    'custom',
-    'none',
-]);
+const TOTALS_ROW_FUNCTIONS = {
+    average: true,
+    countNums: true,
+    count: true,
+    max: true,
+    min: true,
+    stdDev: true,
+    sum: true,
+    var: true,
+    custom: true,
+    none: true,
+};
 export function isTotalsRowFunction(value) {
-    return TOTALS_ROW_FUNCTIONS.has(value);
+    return Object.hasOwn(TOTALS_ROW_FUNCTIONS, value);
 }
 const IDENTIFIER = /^[\p{L}\\_][\p{L}\p{N}._]*$/u;
-export function disambiguateColumnNames(columns) {
+function disambiguateColumnNames(columns) {
     const seen = new Set();
     return columns.map((column) => {
         let candidate = column.name;
@@ -52,10 +53,10 @@ export function disambiguateColumnNames(columns) {
 }
 function validateTableName(name) {
     if (name.length === 0 || name.length > 255) {
-        throw new AuthoringError(`table name ${JSON.stringify(name)} must be between 1 and 255 characters`);
+        throw new RangeError(`table name ${JSON.stringify(name)} must be between 1 and 255 characters`);
     }
     if (!IDENTIFIER.test(name)) {
-        throw new AuthoringError(`table name ${JSON.stringify(name)} is not a valid Excel identifier — it must start with a letter, ` +
+        throw new SyntaxError(`table name ${JSON.stringify(name)} is not a valid Excel identifier: it must start with a letter, ` +
             'underscore, or backslash and contain only letters, digits, periods, and underscores');
     }
 }
@@ -71,9 +72,8 @@ export class Table {
     #anchorCol;
     #anchorRow;
     #dataRowCount;
-    #writeCell;
-    #insertRow;
-    constructor(options, writeCell, insertRow) {
+    #grid;
+    constructor(options, grid) {
         validateTableName(options.name);
         if (options.columns.length === 0) {
             throw new AuthoringError(`table "${options.name}" must declare at least one column`);
@@ -81,10 +81,16 @@ export class Table {
         if (!Number.isInteger(options.rowCount) || options.rowCount < 0) {
             throw new RangeError(`table "${options.name}" has an invalid data-row count (${options.rowCount})`);
         }
-        const { col, row } = decodeAddress(options.ref);
-        if (col === undefined || row === undefined) {
-            throw new SyntaxError(`table ref "${options.ref}" must anchor at a single cell (e.g. "A1")`);
+        let anchor;
+        try {
+            anchor = decodeCellRef(options.ref);
+        }
+        catch (cause) {
+            throw new SyntaxError(`table ref "${options.ref}" must anchor at a single cell (e.g. "A1")`, {
+                cause,
+            });
         }
+        const { col, row } = anchor;
         this.name = options.name;
         this.displayName = options.displayName ?? options.name;
         this.columns = disambiguateColumnNames(options.columns);
@@ -96,11 +102,12 @@ export class Table {
         this.#anchorCol = col;
         this.#anchorRow = row;
         this.#dataRowCount = options.rowCount;
-        this.#writeCell = writeCell;
-        this.#insertRow = insertRow;
+        this.#grid = grid;
         if (this.#rowSpan < 1) {
-            throw new AuthoringError(`table "${this.name}" has no rows — it needs a header row or at least one data row`);
+            throw new AuthoringError(`table "${this.name}" has no rows: it needs a header row or at least one data row`);
         }
+        if (grid !== undefined)
+            this.#materializeFrame(grid);
     }
     get columnCount() {
         return this.columns.length;
@@ -113,32 +120,67 @@ export class Table {
             throw new RangeError(`row has ${values.length} values but table "${this.name}" has ${this.columnCount} columns`);
         }
         const target = this.#anchorRow + (this.headerRow ? 1 : 0) + this.#dataRowCount;
+        const grid = this.#grid;
         if (this.totalsRow) {
-            if (this.#insertRow === undefined) {
-                throw new AuthoringError(`table "${this.name}" is not attached to a worksheet — cannot relocate its totals row to append a data row`);
+            if (grid === undefined) {
+                throw new AuthoringError(`table "${this.name}" is not attached to a worksheet: cannot relocate its totals row to append a data row`);
             }
-            this.#insertRow(target);
-            values.forEach((value, index) => {
-                this.#writeCell?.(target, this.#anchorCol + index, value, this.columns[index]?.style);
-            });
+            grid.insertRow(target);
+            this.#writeRow(grid, target, values);
             return;
         }
         if (values.length > 0) {
-            if (this.#writeCell === undefined) {
-                throw new AuthoringError(`table "${this.name}" is not attached to a worksheet — cannot write appended row values`);
+            if (grid === undefined) {
+                throw new AuthoringError(`table "${this.name}" is not attached to a worksheet: cannot write appended row values`);
             }
-            values.forEach((value, index) => {
-                this.#writeCell?.(target, this.#anchorCol + index, value, this.columns[index]?.style);
-            });
+            this.#writeRow(grid, target, values);
         }
         this.#dataRowCount += 1;
     }
+    #writeRow(grid, row, values) {
+        values.forEach((value, index) => {
+            grid.writeCell(row, this.#anchorCol + index, value, this.columns[index]?.style);
+        });
+    }
+    #materializeFrame(grid) {
+        if (this.headerRow) {
+            const { top, left } = this.region;
+            this.columns.forEach((column, index) => {
+                const col = left + index;
+                if (grid.holdsValue(top, col))
+                    return;
+                grid.writeCell(top, col, column.name);
+            });
+        }
+        if (this.totalsRow) {
+            const { left, bottom } = this.region;
+            this.columns.forEach((column, index) => {
+                const col = left + index;
+                if (grid.holdsValue(bottom, col))
+                    return;
+                if (column.totalsRowLabel !== undefined) {
+                    grid.writeCell(bottom, col, column.totalsRowLabel);
+                    return;
+                }
+                if (column.totalsRowFunction === undefined)
+                    return;
+                const code = TOTALS_ROW_SUBTOTAL_CODE[column.totalsRowFunction];
+                if (code !== undefined) {
+                    grid.writeCell(bottom, col, {
+                        formula: `SUBTOTAL(${code},${this.name}[${column.name}])`,
+                    });
+                }
+                else if (column.totalsRowFunction === 'custom' && column.totalsRowFormula !== undefined) {
+                    grid.writeCell(bottom, col, { formula: column.totalsRowFormula });
+                }
+            });
+        }
+    }
     shiftRows(start, count, delta) {
-        if (this.#anchorRow >= start && this.#bottom < start + count)
+        if (isDeletedSpan(this.#anchorRow, this.#bottom, start, count))
             return false;
-        const shift = (v) => (v < start ? v : v >= start + count ? v + delta : start);
-        const top = shift(this.#anchorRow);
-        const bottom = shift(this.#bottom);
+        const top = shiftIndex(this.#anchorRow, start, count, delta, 'row');
+        const bottom = shiftIndex(this.#bottom, start, count, delta, 'row');
         const span = bottom - top + 1;
         const fixedRows = (this.headerRow ? 1 : 0) + (this.totalsRow ? 1 : 0);
         const dataRows = span - fixedRows;