@shbernal/ts-xlsx 2.0.0 → 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.d.ts

@@ -5,16 +5,30 @@ import type { CellValue } from './value.ts';
  * 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
@@ -127,7 +141,7 @@ 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
      * from a file derives it from the stored range, so reading the height never throws. */

package/dist/core/table.js

@@ -1,5 +1,6 @@
 import { AuthoringError } from '../errors.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,20 +25,20 @@ 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;
 function disambiguateColumnNames(columns) {
@@ -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`);
@@ -102,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`);
         }
+        if (grid !== undefined)
+            this.#materializeFrame(grid);
     }
     get columnCount() {
         return this.columns.length;
@@ -119,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) {
+            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) {
+            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;

package/dist/core/theme.d.ts

@@ -15,6 +15,8 @@
 export declare const THEME_COLOR_SLOTS: readonly ['lt1', 'dk1', 'lt2', 'dk2', 'accent1', 'accent2', 'accent3', 'accent4', 'accent5', 'accent6', 'hlink', 'folHlink'];
 /** One slot of a theme's colour scheme. */
 export type ThemeColorSlot = (typeof THEME_COLOR_SLOTS)[number];
+/** Narrow a raw `<a:clrScheme>` child name to a known {@link ThemeColorSlot}. */
+export declare function isThemeColorSlot(value: string): value is ThemeColorSlot;
 /**
  * A theme's colour scheme: each slot's colour as a 6-hex `RRGGBB` string. Partial because a foreign
  * theme is free to omit a slot (or express one in a colour model this reader does not decode), and an
@@ -22,7 +24,7 @@ export type ThemeColorSlot = (typeof THEME_COLOR_SLOTS)[number];
  */
 export type ThemeColorScheme = Readonly<Partial<Record<ThemeColorSlot, string>>>;
 /** The Office default colour scheme, matching the theme part the writer emits for a workbook with none. */
-export declare const DEFAULT_THEME_COLOR_SCHEME: ThemeColorScheme;
+export declare const DEFAULT_THEME_COLOR_SCHEME: Readonly<Record<ThemeColorSlot, string>>;
 /**
  * The two typefaces a theme nominates: the `major` face headings use and the `minor` face body text
  * uses. A cell's font reaches them by `scheme="major"`/`scheme="minor"` instead of naming a typeface,

package/dist/core/theme.js

@@ -12,6 +12,10 @@ export const THEME_COLOR_SLOTS = [
     'hlink',
     'folHlink',
 ];
+const THEME_COLOR_SLOT_NAMES = new Set(THEME_COLOR_SLOTS);
+export function isThemeColorSlot(value) {
+    return THEME_COLOR_SLOT_NAMES.has(value);
+}
 export const DEFAULT_THEME_COLOR_SCHEME = {
     lt1: 'FFFFFF',
     dk1: '000000',

package/dist/core/workbook.d.ts

@@ -9,7 +9,7 @@ import { type TableStyle } from './table-style.ts';
 import { type ThemeColorScheme, type ThemeFontScheme, type ThemeOverrides } from './theme.ts';
 import type { WorkbookProtection } from './workbook-protection.ts';
 import { type DeclaredThemeSchemes } from './workbook-theme.ts';
-import { Worksheet, type WorksheetState } from './worksheet.ts';
+import { type Visibility, Worksheet, type WorksheetState } from './worksheet.ts';
 /**
  * A workbook-level reference to package content the model does not model: a pivot cache
  * (`pivotCacheDefinition`) or a slicer cache (`slicerCache`), preserved verbatim across a round-trip
@@ -70,7 +70,7 @@ export interface WorkbookView {
     /** 0-based index into {@link Workbook.worksheets} of the sheet selected on open. */
     activeTab: number;
     /** Window visibility; omit for a normally visible window. */
-    visibility?: 'visible' | 'hidden' | 'veryHidden';
+    visibility?: Visibility;
     /** Whether the document window opens minimised; omit for a restored window. */
     minimized?: boolean;
 }

package/dist/core/worksheet-comments.d.ts

@@ -5,5 +5,13 @@ export declare class WorksheetComments {
     get threads(): readonly CommentThread[];
     add(thread: CommentThread): void;
     at(reference: string): CommentThread | undefined;
+    /**
+     * Re-anchor every conversation through a row or column splice. A thread hangs off exactly one cell,
+     * so it moves as a point, not a rectangle, and a thread whose cell the splice deleted is dropped
+     * along with its messages. Both halves matter: a cell's legacy note is cell state and travels with
+     * the cell, so a thread left behind would put a note on one cell and its conversation on another,
+     * a pairing the writer emits and Excel refuses.
+     */
+    shift(axis: 'row' | 'col', start: number, count: number, delta: number): void;
     restore(threads: readonly CommentThread[]): void;
 }

package/dist/core/worksheet-comments.js

@@ -1,6 +1,7 @@
 import { decodeCellRef, encodeAddress } from './address.js';
 import { commentThreadGuid, commentThreadOffset } from './comment-thread.js';
 import { replaceContents } from './containers.js';
+import { isDeletedSpan, shiftIndex } from './grid-shift.js';
 export class WorksheetComments {
     #sheetName;
     #threads = [];
@@ -42,6 +43,23 @@ export class WorksheetComments {
         const anchor = anchorRef(reference);
         return this.#threads.find((thread) => thread.ref === anchor);
     }
+    shift(axis, start, count, delta) {
+        const survivors = [];
+        for (const thread of this.#threads) {
+            const { col, row } = decodeCellRef(thread.ref);
+            const line = axis === 'row' ? row : col;
+            if (isDeletedSpan(line, line, start, count))
+                continue;
+            const moved = shiftIndex(line, start, count, delta, axis);
+            if (moved === line) {
+                survivors.push(thread);
+                continue;
+            }
+            const ref = axis === 'row' ? encodeAddress(col, moved) : encodeAddress(moved, row);
+            survivors.push({ ...thread, ref });
+        }
+        replaceContents(this.#threads, survivors);
+    }
     restore(threads) {
         replaceContents(this.#threads, threads);
     }

package/dist/core/worksheet.d.ts

@@ -15,9 +15,19 @@ import { Row } from './row.ts';
 import type { CellStyle, Color, Fill } from './style.ts';
 import { Table, type TableOptions } from './table.ts';
 import type { CellValue } from './value.ts';
+/**
+ * Whether a thing Excel can hide is showing: a sheet's tab, or the document window itself.
+ *
+ * One type for two schema enumerations. `ST_SheetState` and `ST_Visibility` are declared separately
+ * in ECMA-376 and carry the same three tokens with the same meanings, and `veryHidden` means the same
+ * thing in both: hidden, and not offered in the unhide list.
+ */
+export type Visibility = 'visible' | 'hidden' | 'veryHidden';
+/** Narrow a raw `<sheet state>` or `<workbookView visibility>` token to a known {@link Visibility}. */
+export declare function isVisibility(value: string): value is Visibility;
 export interface WorksheetState {
     /** Sheet visibility, as Excel models it. Defaults to `visible`. */
-    readonly state: 'visible' | 'hidden' | 'veryHidden';
+    readonly state: Visibility;
 }
 /** Format defaults applied to every row/column that carries no explicit override. */
 export interface WorksheetProperties {
@@ -574,7 +584,10 @@ export declare class Worksheet {
      * never disturbs merges or the columns to its left.
      *
      * `values` is an array indexed by row (index 0 → row 1); a hole or an explicit `undefined` leaves
-     * that row untouched, mirroring {@link addRow}'s positional-array shape.
+     * that row untouched, mirroring {@link addRow}'s positional-array shape. That is the only shape a
+     * column takes: the other {@link RowInput} form addresses columns by their
+     * {@link ColumnProperties.key}, and a column's values are indexed by *row*, which carries no key,
+     * so there is nothing on this axis for a keyed object to name.
      */
     addColumn(values: CellValue[]): Cell[];
     /**

package/dist/core/worksheet.js

@@ -11,12 +11,16 @@ import { clearCoveredValues, masterOf } from './merge.js';
 import { PivotTable } from './pivot-table.js';
 import { deriveCredential, } from './protection.js';
 import { Range, rangeFrom } from './range.js';
-import { buildRowCells, rowPlacements } from './row-input.js';
+import { buildRowCells, positionalPlacements, rowPlacements } from './row-input.js';
 import { Row } from './row.js';
-import { Table, TOTALS_ROW_SUBTOTAL_CODE } from './table.js';
+import { Table } from './table.js';
 import { WorksheetComments } from './worksheet-comments.js';
 import { WORKSHEET_MODEL_FACETS } from './worksheet-model.js';
 import { WorksheetPictures } from './worksheet-pictures.js';
+const VISIBILITIES = { visible: true, hidden: true, veryHidden: true };
+export function isVisibility(value) {
+    return Object.hasOwn(VISIBILITIES, value);
+}
 export class Worksheet {
     name;
     id;
@@ -62,6 +66,15 @@ export class Worksheet {
             mergeRects: this.#mergeRects,
             tables: this.#tables,
             images: this.#images.anchors,
+            dataValidations: this.#dataValidations,
+            conditionalFormattings: this.#conditionalFormattings,
+            comments: this.#comments,
+            autoFilter: {
+                get: () => this.#autoFilter,
+                set: (next) => {
+                    this.#autoFilter = next;
+                },
+            },
         });
     }
     getCell(reference) {
@@ -151,46 +164,17 @@ export class Worksheet {
         }
     }
     addTable(options) {
-        const table = new Table(options, (row, col, value, style) => {
-            const cell = this.#cellAt(row, col);
-            cell.value = value;
-            if (style !== undefined)
-                applyCellStyle(cell, style);
-        }, (row) => this.spliceRows(row, 0, []));
+        const table = new Table(options, {
+            holdsValue: (row, col) => this.hasCell(row, col) && this.#cellAt(row, col).value != null,
+            writeCell: (row, col, value, style) => {
+                const cell = this.#cellAt(row, col);
+                cell.value = value;
+                if (style !== undefined)
+                    applyCellStyle(cell, style);
+            },
+            insertRow: (row) => this.spliceRows(row, 0, []),
+        });
         this.#tables.push(table);
-        if (table.headerRow) {
-            const { top, left } = table.region;
-            table.columns.forEach((column, index) => {
-                const col = left + index;
-                if (this.hasCell(top, col) && this.#cellAt(top, col).value != null)
-                    return;
-                this.#cellAt(top, col).value = column.name;
-            });
-        }
-        if (table.totalsRow) {
-            const { left, bottom } = table.region;
-            table.columns.forEach((column, index) => {
-                const col = left + index;
-                if (this.hasCell(bottom, col) && this.#cellAt(bottom, col).value != null)
-                    return;
-                if (column.totalsRowLabel !== undefined) {
-                    this.#cellAt(bottom, col).value = column.totalsRowLabel;
-                    return;
-                }
-                if (column.totalsRowFunction !== undefined) {
-                    const code = TOTALS_ROW_SUBTOTAL_CODE[column.totalsRowFunction];
-                    if (code !== undefined) {
-                        this.#cellAt(bottom, col).value = {
-                            formula: `SUBTOTAL(${code},${table.name}[${column.name}])`,
-                        };
-                    }
-                    else if (column.totalsRowFunction === 'custom' &&
-                        column.totalsRowFormula !== undefined) {
-                        this.#cellAt(bottom, col).value = { formula: column.totalsRowFormula };
-                    }
-                }
-            });
-        }
         return table;
     }
     get tables() {
@@ -373,15 +357,11 @@ export class Worksheet {
         let index = this.columnCount;
         return columns.map((values) => {
             index += 1;
-            const cells = [];
-            values.forEach((value, i) => {
-                if (value === undefined)
-                    return;
-                const cell = this.#cellAt(i + 1, index);
+            return positionalPlacements(values).map(([row, value]) => {
+                const cell = this.#cellAt(row, index);
                 cell.value = value;
-                cells.push(cell);
+                return cell;
             });
-            return cells;
         });
     }
     get model() {