@shbernal/ts-xlsx 2.0.0 → 2.1.0

package/README.md

@@ -9,6 +9,8 @@
 A TypeScript-first library for reading and writing spreadsheet documents
 (`.xlsx` / OOXML, and CSV) — synchronous, `Uint8Array`-native, and dependency-lean.
 
+**[Documentation, guide and a browser playground](https://shbernal.github.io/ts-xlsx/)**
+
 > **Status — 1.0.0, the first release.**
 > `ts-xlsx` began as a hard fork of [ExcelJS](https://github.com/exceljs/exceljs)
 > and has been rebuilt from the ground up into a modern, strict-TypeScript library.
@@ -130,10 +132,12 @@ import {
   readXlsx, writeXlsx,        // buffered .xlsx  (Uint8Array ⇄ Workbook)
   readSheetRows,              // stream one sheet's rows, bounded memory
   readWorkbookStream,         // stream every sheet, rows one at a time
-  WorkbookStreamWriter,       // write a workbook incrementally, bounded memory
   readCsv, writeCsv,          // CSV as Uint8Array
   writeCsvText,               // CSV as a string
 } from '@shbernal/ts-xlsx';
+// The streaming writer opens files and pipes Node streams, so it is the one Node-only face
+// and lives behind its own subpath — which is what keeps everything above browser-safe:
+import {WorkbookStreamWriter} from '@shbernal/ts-xlsx/node';
 
 // Bounded-memory extraction — the whole workbook is never materialized:
 for (const row of readSheetRows(bytes, {sheet: 'People'})) {
@@ -189,18 +193,24 @@ on — a Lambda with no bundler, a service that only classifies failures:
 
 | Import from | You get | It loads |
 | --- | --- | --- |
-| `@shbernal/ts-xlsx` | everything | 902 KB |
-| `@shbernal/ts-xlsx/core` | `Workbook`, `Worksheet`, `Cell`, styles, values, addresses | 332 KB |
-| `@shbernal/ts-xlsx/xlsx` | `readXlsx`, `writeXlsx`/`writeXlsxAsync`, the streaming pair, VBA part edits | 887 KB |
-| `@shbernal/ts-xlsx/xlsb` | `readXlsb` | 469 KB |
-| `@shbernal/ts-xlsx/csv` | `readCsv`, `writeCsv`, `writeCsvText` | 341 KB |
-| `@shbernal/ts-xlsx/vba` | `parseVbaProject`, `addVbaReference`, `removeVbaModule` | 73 KB |
-| `@shbernal/ts-xlsx/customui` | `parseCustomUi` and the ribbon types | 26 KB |
-| `@shbernal/ts-xlsx/errors` | every error class the library throws | 12 KB |
+| `@shbernal/ts-xlsx` | everything except the streaming writer | 501 KB |
+| `@shbernal/ts-xlsx/core` | `Workbook`, `Worksheet`, `Cell`, styles, values, addresses | 185 KB |
+| `@shbernal/ts-xlsx/xlsx` | `readXlsx`, `writeXlsx`/`writeXlsxAsync`, the streaming reader, VBA part edits | 490 KB |
+| `@shbernal/ts-xlsx/xlsb` | `readXlsb` | 256 KB |
+| `@shbernal/ts-xlsx/csv` | `readCsv`, `writeCsv`, `writeCsvText` | 191 KB |
+| `@shbernal/ts-xlsx/node` | `WorkbookStreamWriter` and the rest of the streaming writer | 358 KB |
+| `@shbernal/ts-xlsx/vba` | `parseVbaProject`, `addVbaReference`, `removeVbaModule` | 46 KB |
+| `@shbernal/ts-xlsx/customui` | `parseCustomUi` and the ribbon types | 15 KB |
+| `@shbernal/ts-xlsx/errors` | every error class the library throws | 3 KB |
+
+`/node` is the only one the root specifier does not carry, and the reason is its imports
+rather than its size: it reaches `node:fs` and `node:stream`, and every other entry reaches
+no Node built-in at all, which is what makes them bundle for a browser with nothing to
+configure ([ADR-0040](docs/decisions/0040-the-browser-boundary-is-an-entry-point.md)).
 
 Every error class lives in `/errors` and nowhere else, because a container-level failure
 belongs to no single codec — `readXlsx` and `readXlsb` both raise `UnsupportedFormatError`.
-Catching and classifying therefore costs 12 KB, not a parser.
+Catching and classifying therefore costs 3 KB, not a parser.
 
 `/xlsx` is barely cheaper than the whole package, and that is honest rather than a defect:
 `readXlsx` sniffs the bytes and hands a binary package to the BIFF12 reader, so the `.xlsb`

package/dist/bytes.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Join byte chunks into one buffer.
+ *
+ * Both parameters exist to avoid work the caller has already done. `size` is the total length when
+ * the caller knows it, as a reader draining a length-prefixed stream does, which skips a pass over
+ * the chunks. A lone chunk is handed straight back rather than copied, which is the common case on
+ * the inflate path, where a part that fits in one chunk would otherwise be duplicated in memory the
+ * moment it is read.
+ *
+ * The returned buffer therefore aliases the caller's chunk when there is exactly one. Every caller
+ * here is a reader assembling bytes it then only reads, so this is sound; a caller that means to
+ * mutate the result must copy it.
+ */
+export declare function concat(chunks: readonly Uint8Array[], size?: number): Uint8Array;
+/**
+ * Standard base64 of `bytes`, padded with `=`.
+ *
+ * Spelled out rather than delegated because both platform routes are unavailable here: `Buffer` is
+ * a Node global, which is exactly what a browser-safe module may not reach for, and `btoa` is
+ * declared deprecated in Node's types (so the `no-deprecated` lint rule rejects it) and takes a
+ * binary string rather than bytes anyway. The one caller encodes a 16-byte salt and a 64-byte
+ * hash, so the loop below is not on any path where its cost is measurable.
+ */
+export declare function toBase64(bytes: Uint8Array): string;

package/dist/bytes.js

@@ -0,0 +1,34 @@
+export function concat(chunks, size) {
+    const first = chunks[0];
+    if (chunks.length === 1 && first !== undefined)
+        return first;
+    let total = size;
+    if (total === undefined) {
+        total = 0;
+        for (const chunk of chunks)
+            total += chunk.length;
+    }
+    const out = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        out.set(chunk, offset);
+        offset += chunk.length;
+    }
+    return out;
+}
+const BASE64_ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+export function toBase64(bytes) {
+    let out = '';
+    for (let i = 0; i < bytes.length; i += 3) {
+        const a = bytes[i] ?? 0;
+        const b = bytes[i + 1] ?? 0;
+        const c = bytes[i + 2] ?? 0;
+        const triple = (a << 16) | (b << 8) | c;
+        const remaining = bytes.length - i;
+        out += BASE64_ALPHABET.charAt((triple >>> 18) & 63);
+        out += BASE64_ALPHABET.charAt((triple >>> 12) & 63);
+        out += remaining > 1 ? BASE64_ALPHABET.charAt((triple >>> 6) & 63) : '=';
+        out += remaining > 2 ? BASE64_ALPHABET.charAt(triple & 63) : '=';
+    }
+    return out;
+}

package/dist/core/address.d.ts

@@ -52,10 +52,21 @@ export interface RangeAddress {
     /** Canonical `tl:br` form: `"A1:B2"`, `"1:1"` (rows), `"A:A"` (columns). */
     readonly dimensions: string;
 }
-/** Convert a 1-based column number to its letters (`1 → "A"`, `27 → "AA"`). */
+/** Convert a 1-based column number to its letters (`1 → "A"`, `27 → "AA"`).
+ *
+ * @throws {RangeError} unless `n` is an integer in `1..MAX_COLUMN`. */
 export declare function numberToColumn(n: number): string;
 /** Convert column letters to a 1-based number (`"A" → 1`, `"AA" → 27`). */
 export declare function columnToNumber(letters: string): number;
+/**
+ * One corner of a range, as its reference text. An axis the corner omits contributes nothing, so a
+ * whole-row corner spells `6` and a whole-column one spells `B`, rather than acquiring the other
+ * axis from a sentinel. That is the honesty rule this module's header states, and letting an absent
+ * axis decay into text is exactly how `"$undefined$1"` and `"NaN:NaN"` used to reach a file.
+ *
+ * The unbounded counterpart to {@link encodeAddress}, which names one cell and so requires both.
+ */
+export declare function encodeCornerRef(col: number | undefined, row: number | undefined): string;
 /**
  * Decode a single cell/row/column reference into `{address, col, row}`. Anchoring
  * `$` signs are accepted and dropped; an absent axis is `undefined`.
@@ -81,11 +92,22 @@ export interface CellPosition {
 export declare function decodeCellRef(reference: string): CellPosition;
 /**
  * {@link decodeCellRef} for a reference that came out of a file rather than out of a caller:
- * `undefined` for anything that does not name one cell, whether it is a range, a bare row or
- * column, or outright garbage. A foreign producer writes all four, and none of them is worth
- * throwing over when the reading code's answer is simply "then there is nothing here".
+ * `undefined` for anything that does not name one cell that can exist: a range, a bare row or
+ * column, a position off the grid (`A0`, `XFE1`), or outright garbage. A foreign producer writes
+ * all of them, and none is worth throwing over when the reading code's answer is simply "then
+ * there is nothing here".
  */
 export declare function tryDecodeCellRef(reference: string): CellPosition | undefined;
+/**
+ * {@link decodeRange} for a reference that came out of a file: `undefined` for anything that does
+ * not name a region that can exist. The sibling of {@link tryDecodeCellRef} on the other arity: a
+ * `ref` or one area of a `sqref` is as likely to be malformed as a cell's `r`, and the reader's
+ * answer to both is the same one.
+ *
+ * An axis neither endpoint mentions stays `undefined`, exactly as in `decodeRange`: a whole-column
+ * range is unbounded, not unreadable, and a caller that needs a bounded rectangle says so itself.
+ */
+export declare function tryDecodeRange(reference: string): RangeAddress | undefined;
 /**
  * Decode a range reference (`A1:B2`, `$1:$1`, `Sheet1!$A:$A`) into its corners and
  * canonical dimensions. A single reference collapses to a degenerate range whose

package/dist/core/address.js

@@ -16,9 +16,7 @@ export function rectsOverlap(a, b) {
 const SINGLE_REF = /^\$?([A-Z]*)\$?(\d*)$/;
 const SHEET_PREFIX = /^(?:(?:'((?:[^']|'')*)')|([^'!]+))!(.*)$/;
 export function numberToColumn(n) {
-    if (!Number.isInteger(n) || n < 1 || n > MAX_COLUMN) {
-        throw new RangeError(`column ${n} is out of bounds: Excel supports 1..${MAX_COLUMN}`);
-    }
+    assertColumnInBounds(n);
     let letters = '';
     let remaining = n;
     while (remaining > 0) {
@@ -45,12 +43,11 @@ export function columnToNumber(letters) {
     }
     return n;
 }
+export function encodeCornerRef(col, row) {
+    return `${col !== undefined ? numberToColumn(col) : ''}${row !== undefined ? row : ''}`;
+}
 function makeCellAddress(col, row) {
-    return {
-        address: `${col !== undefined ? numberToColumn(col) : ''}${row !== undefined ? row : ''}`,
-        col,
-        row,
-    };
+    return { address: encodeCornerRef(col, row), col, row };
 }
 export function decodeAddress(reference) {
     const match = SINGLE_REF.exec(reference);
@@ -73,13 +70,28 @@ export function decodeCellRef(reference) {
     }
     return { col, row };
 }
+function rowCanExist(row) {
+    return row === undefined || (Number.isInteger(row) && row >= 1 && row <= MAX_ROW);
+}
 export function tryDecodeCellRef(reference) {
+    let position;
+    try {
+        position = decodeCellRef(reference);
+    }
+    catch {
+        return undefined;
+    }
+    return rowCanExist(position.row) ? position : undefined;
+}
+export function tryDecodeRange(reference) {
+    let range;
     try {
-        return decodeCellRef(reference);
+        range = decodeRange(reference);
     }
     catch {
         return undefined;
     }
+    return rowCanExist(range.top) && rowCanExist(range.bottom) ? range : undefined;
 }
 export function decodeRange(reference) {
     const prefix = SHEET_PREFIX.exec(reference);

package/dist/core/autofilter.d.ts

@@ -53,3 +53,14 @@ export declare function isCustomFilterOperator(value: string): value is CustomFi
  * here, so load never trips these guards.)
  */
 export declare function canonicalizeAutoFilter(input: string | AutoFilter): AutoFilter;
+/**
+ * Re-anchor a filter through a splice of `count` lines at `start` on `axis`, or drop it (`undefined`)
+ * when the splice deleted every line it covered.
+ *
+ * A row splice only moves the range. A column splice moves its left edge too, and a criterion is
+ * addressed by its offset from that edge rather than by an absolute column, so every offset is
+ * re-measured against the new edge and a criterion whose column was deleted goes with the column.
+ * Left alone, those offsets would keep their old numbers and silently re-point each filter at a
+ * neighbouring column.
+ */
+export declare function shiftAutoFilter(filter: AutoFilter, axis: 'row' | 'col', start: number, count: number, delta: number): AutoFilter | undefined;

package/dist/core/autofilter.js

@@ -1,15 +1,16 @@
 import { AuthoringError } from '../errors.js';
-import { decodeRange } from './address.js';
-const CUSTOM_FILTER_OPERATORS = new Set([
-    'equal',
-    'notEqual',
-    'lessThan',
-    'lessThanOrEqual',
-    'greaterThan',
-    'greaterThanOrEqual',
-]);
+import { decodeRange, encodeAddress } from './address.js';
+import { isDeletedSpan, shiftIndex } from './grid-shift.js';
+const CUSTOM_FILTER_OPERATORS = {
+    equal: true,
+    notEqual: true,
+    lessThan: true,
+    lessThanOrEqual: true,
+    greaterThan: true,
+    greaterThanOrEqual: true,
+};
 export function isCustomFilterOperator(value) {
-    return CUSTOM_FILTER_OPERATORS.has(value);
+    return Object.hasOwn(CUSTOM_FILTER_OPERATORS, value);
 }
 export function canonicalizeAutoFilter(input) {
     const ref = typeof input === 'string' ? input : input.ref;
@@ -37,3 +38,27 @@ function canonicalizeColumn(column, width) {
     }
     return column;
 }
+export function shiftAutoFilter(filter, axis, start, count, delta) {
+    const { top, left, bottom, right } = decodeRange(filter.ref);
+    if (top === undefined || left === undefined || bottom === undefined || right === undefined) {
+        return filter;
+    }
+    const [lo, hi] = axis === 'row' ? [top, bottom] : [left, right];
+    if (isDeletedSpan(lo, hi, start, count))
+        return undefined;
+    const movedLo = shiftIndex(lo, start, count, delta, axis);
+    const movedHi = shiftIndex(hi, start, count, delta, axis);
+    if (axis === 'row') {
+        const ref = `${encodeAddress(left, movedLo)}:${encodeAddress(right, movedHi)}`;
+        return { ref, columns: filter.columns };
+    }
+    const ref = `${encodeAddress(movedLo, top)}:${encodeAddress(movedHi, bottom)}`;
+    const columns = [];
+    for (const column of filter.columns) {
+        const absolute = left + column.colId;
+        if (isDeletedSpan(absolute, absolute, start, count))
+            continue;
+        columns.push({ ...column, colId: shiftIndex(absolute, start, count, delta, axis) - movedLo });
+    }
+    return { ref, columns };
+}

package/dist/core/color-resolution.d.ts

@@ -1,4 +1,4 @@
-import type { Color } from './style.ts';
+import { type Color } from './style.ts';
 import { type ThemeColorScheme } from './theme.ts';
 /**
  * The built-in indexed colour palette (ECMA-376 §18.8.27), by index. Entries 0–7 duplicate 8–15, a

package/dist/core/color-resolution.js

@@ -1,3 +1,4 @@
+import { parseArgb } from './style.js';
 import { DEFAULT_THEME_COLOR_SCHEME, THEME_COLOR_SLOTS } from './theme.js';
 export const DEFAULT_INDEXED_COLORS = [
     '00000000', '00FFFFFF', '00FF0000', '0000FF00', '000000FF', '00FFFF00', '00FF00FF', '0000FFFF',
@@ -19,9 +20,12 @@ export function resolveColor(color, context = {}) {
         return base;
     return applyTint(base, tint);
 }
+function resolveArgb(value) {
+    return parseArgb(value)?.toUpperCase();
+}
 function resolveBase(color, context) {
     if (color.argb !== undefined)
-        return normalizeArgb(color.argb);
+        return resolveArgb(color.argb);
     if (color.theme !== undefined) {
         const slot = THEME_COLOR_SLOTS[color.theme];
         if (slot === undefined)
@@ -38,16 +42,11 @@ function resolveBase(color, context) {
             : DEFAULT_INDEXED_COLORS[color.indexed];
         if (entry === undefined)
             return undefined;
-        const normalized = normalizeArgb(entry);
-        return normalized === undefined ? undefined : `FF${normalized.slice(2)}`;
+        const parsed = resolveArgb(entry);
+        return parsed === undefined ? undefined : `FF${parsed.slice(2)}`;
     }
     return undefined;
 }
-function normalizeArgb(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.toUpperCase() : undefined;
-}
 export function applyTint(argb, tint) {
     const alpha = argb.slice(0, 2);
     const r = Number.parseInt(argb.slice(2, 4), 16) / 255;

package/dist/core/conditional-formatting-overlay.d.ts

@@ -10,6 +10,11 @@ export declare class ConditionalFormattingOverlay {
     add(formatting: ConditionalFormatting): void;
     /** The conditional formattings on this sheet, each bound to its target range, in insertion order. */
     get entries(): readonly ConditionalFormatting[];
+    /**
+     * Re-anchor every rule set through a row or column splice, so a highlight keeps covering the cells
+     * it was written for. A rule set whose every target area fell inside a deleted span goes with them.
+     */
+    shift(axis: 'row' | 'col', start: number, count: number, delta: number): void;
     /** Drop every conditional formatting, leaving the overlay empty. */
     clear(): void;
 }

package/dist/core/conditional-formatting-overlay.js

@@ -1,4 +1,6 @@
 import { cloneConditionalFormatting } from './conditional-formatting.js';
+import { replaceContents } from './containers.js';
+import { shiftSqref } from './merge.js';
 export class ConditionalFormattingOverlay {
     #entries = [];
     add(formatting) {
@@ -7,6 +9,15 @@ export class ConditionalFormattingOverlay {
     get entries() {
         return this.#entries;
     }
+    shift(axis, start, count, delta) {
+        const entries = [];
+        for (const entry of this.#entries) {
+            const ref = shiftSqref(entry.ref, axis, start, count, delta);
+            if (ref !== undefined)
+                entries.push({ ...entry, ref });
+        }
+        replaceContents(this.#entries, entries);
+    }
     clear() {
         this.#entries.length = 0;
     }

package/dist/core/conditional-formatting.d.ts

@@ -1,26 +1,66 @@
 import type { Color, DifferentialStyle } from './style.ts';
+/** How a {@link CfValueObject} reads its `value`: `ST_CfvoType` verbatim. */
+export type CfValueObjectType = 'num' | 'percent' | 'max' | 'min' | 'percentile' | 'formula';
+/** Narrow a raw `<cfvo type>` token to a known {@link CfValueObjectType}. */
+export declare function isCfValueObjectType(value: string): value is CfValueObjectType;
 /**
  * One anchor of a colour-scale, data-bar, or icon-set scale: a "conditional format value object".
  * `type` names how `value` is read: a literal `num`, a `percent`/`percentile` of the range, a
  * `formula`, or the range's own `min`/`max` (which carry no value).
  */
 export interface CfValueObject {
-    type: 'num' | 'percent' | 'max' | 'min' | 'percentile' | 'formula';
+    type: CfValueObjectType;
     value?: number | string;
 }
+/**
+ * What a rule tests, as `<cfRule type>` carries it: `ST_CfType` verbatim.
+ *
+ * Closed, and stated in full rather than left as `string`, even though the library models only some
+ * of these in depth. Depth of modelling and legality are different questions: a `timePeriod` rule
+ * whose operands the library never inspects still round-trips, while a token outside this list is one
+ * Excel refuses to open, so it is refused on the way in and on the way out alike.
+ */
+export type ConditionalFormattingType = 'expression' | 'cellIs' | 'colorScale' | 'dataBar' | 'iconSet' | 'top10' | 'uniqueValues' | 'duplicateValues' | 'containsText' | 'notContainsText' | 'beginsWith' | 'endsWith' | 'containsBlanks' | 'notContainsBlanks' | 'containsErrors' | 'notContainsErrors' | 'timePeriod' | 'aboveAverage';
+/** Narrow a raw `<cfRule type>` token to a known {@link ConditionalFormattingType}. */
+export declare function isConditionalFormattingType(value: string): value is ConditionalFormattingType;
+/**
+ * How a `cellIs` or text rule compares, as `ST_ConditionalFormattingOperator` enumerates it.
+ *
+ * Overlaps {@link import('./data-validation.ts').DataValidationOperator} in four members and diverges
+ * in the rest: this one has the text comparisons a validation has no use for, and spells "does not
+ * contain" as `notContains` where nothing else in the format does.
+ */
+export type ConditionalFormattingOperator = 'lessThan' | 'lessThanOrEqual' | 'equal' | 'notEqual' | 'greaterThanOrEqual' | 'greaterThan' | 'between' | 'notBetween' | 'containsText' | 'notContains' | 'beginsWith' | 'endsWith';
+/** Narrow a raw `<cfRule operator>` token to a known {@link ConditionalFormattingOperator}. */
+export declare function isConditionalFormattingOperator(value: string): value is ConditionalFormattingOperator;
+/** The window a `timePeriod` rule matches against, relative to the day the sheet is recalculated. */
+export type CfTimePeriod = 'today' | 'yesterday' | 'tomorrow' | 'last7Days' | 'thisMonth' | 'lastMonth' | 'nextMonth' | 'thisWeek' | 'lastWeek' | 'nextWeek';
+/** Narrow a raw `<cfRule timePeriod>` token to a known {@link CfTimePeriod}. */
+export declare function isCfTimePeriod(value: string): value is CfTimePeriod;
+/**
+ * The named icon family an `iconSet` rule draws from, as `ST_IconSetType` enumerates it. The leading
+ * digit is the number of icons, which is also how many {@link CfValueObject} anchors the rule needs.
+ *
+ * The 2009 extension adds three more families (`3Stars`, `3Triangles`, `5Boxes`) under its own
+ * namespace. They are absent here because the classic `<iconSet>` element this list types cannot
+ * carry them; a file using one states it in the extension, which the library round-trips verbatim.
+ */
+export type IconSetType = '3Arrows' | '3ArrowsGray' | '3Flags' | '3TrafficLights1' | '3TrafficLights2' | '3Signs' | '3Symbols' | '3Symbols2' | '4Arrows' | '4ArrowsGray' | '4RedToBlack' | '4Rating' | '4TrafficLights' | '5Arrows' | '5ArrowsGray' | '5Rating' | '5Quarters';
+/** Narrow a raw `<iconSet iconSet>` token to a known {@link IconSetType}. */
+export declare function isIconSetType(value: string): value is IconSetType;
 /**
  * A single conditional-formatting rule. `type` is the OOXML cfRule type; the remaining fields carry
  * the operands that type needs and are absent otherwise. A rule the library does not model in depth
  * still preserves `type`, `priority`, `operator`, `formulae`, and `dxfId` across a round-trip.
  */
 export interface ConditionalFormattingRule {
-    type: string;
+    type: ConditionalFormattingType;
     /** Evaluation precedence; lower wins. Excel requires one, so the writer supplies it when absent. */
     priority?: number;
     /** Halt evaluation of lower-priority rules on any cell this rule matches. */
     stopIfTrue?: boolean;
     /** cellIs / text comparison operator (`greaterThan`, `between`, `beginsWith`, …). */
-    operator?: string;
+    operator?: ConditionalFormattingOperator;
     /** Formula operands: cellIs bounds, an expression predicate, a containsText target formula, … */
     formulae?: (string | number)[];
     /** The literal a containsText / beginsWith / endsWith rule searches for. */
@@ -42,7 +82,7 @@ export interface ConditionalFormattingRule {
     /** A dataBar's axis colour (the zero line between positive and negative bars). An x14 property. */
     axisColor?: Color;
     /** An iconSet's named icon family (e.g. `3TrafficLights1`). */
-    iconSet?: string;
+    iconSet?: IconSetType;
     /** top10 rank cutoff. */
     rank?: number;
     /** top10: the rank is a percentage rather than a count. */
@@ -56,7 +96,7 @@ export interface ConditionalFormattingRule {
     /** aboveAverage: match beyond this many standard deviations. */
     stdDev?: number;
     /** timePeriod window (`today`, `lastWeek`, …). */
-    timePeriod?: string;
+    timePeriod?: CfTimePeriod;
 }
 /** A set of rules bound to the range(s) they cover. `ref` is an OOXML `sqref`: one or more
  * space-separated areas (`"A1:C1 A3:C3 A5:C5"`), the shape Excel writes when one rule is applied to

package/dist/core/conditional-formatting.js

@@ -1,3 +1,91 @@
+const CF_VALUE_OBJECT_TYPES = {
+    num: true,
+    percent: true,
+    max: true,
+    min: true,
+    percentile: true,
+    formula: true,
+};
+export function isCfValueObjectType(value) {
+    return Object.hasOwn(CF_VALUE_OBJECT_TYPES, value);
+}
+const CONDITIONAL_FORMATTING_TYPES = {
+    expression: true,
+    cellIs: true,
+    colorScale: true,
+    dataBar: true,
+    iconSet: true,
+    top10: true,
+    uniqueValues: true,
+    duplicateValues: true,
+    containsText: true,
+    notContainsText: true,
+    beginsWith: true,
+    endsWith: true,
+    containsBlanks: true,
+    notContainsBlanks: true,
+    containsErrors: true,
+    notContainsErrors: true,
+    timePeriod: true,
+    aboveAverage: true,
+};
+export function isConditionalFormattingType(value) {
+    return Object.hasOwn(CONDITIONAL_FORMATTING_TYPES, value);
+}
+const CONDITIONAL_FORMATTING_OPERATORS = {
+    lessThan: true,
+    lessThanOrEqual: true,
+    equal: true,
+    notEqual: true,
+    greaterThanOrEqual: true,
+    greaterThan: true,
+    between: true,
+    notBetween: true,
+    containsText: true,
+    notContains: true,
+    beginsWith: true,
+    endsWith: true,
+};
+export function isConditionalFormattingOperator(value) {
+    return Object.hasOwn(CONDITIONAL_FORMATTING_OPERATORS, value);
+}
+const CF_TIME_PERIODS = {
+    today: true,
+    yesterday: true,
+    tomorrow: true,
+    last7Days: true,
+    thisMonth: true,
+    lastMonth: true,
+    nextMonth: true,
+    thisWeek: true,
+    lastWeek: true,
+    nextWeek: true,
+};
+export function isCfTimePeriod(value) {
+    return Object.hasOwn(CF_TIME_PERIODS, value);
+}
+const ICON_SET_TYPES = {
+    '3Arrows': true,
+    '3ArrowsGray': true,
+    '3Flags': true,
+    '3TrafficLights1': true,
+    '3TrafficLights2': true,
+    '3Signs': true,
+    '3Symbols': true,
+    '3Symbols2': true,
+    '4Arrows': true,
+    '4ArrowsGray': true,
+    '4RedToBlack': true,
+    '4Rating': true,
+    '4TrafficLights': true,
+    '5Arrows': true,
+    '5ArrowsGray': true,
+    '5Rating': true,
+    '5Quarters': true,
+};
+export function isIconSetType(value) {
+    return Object.hasOwn(ICON_SET_TYPES, value);
+}
 export function cloneConditionalFormatting(cf) {
     return { ref: cf.ref, rules: cf.rules.map(cloneRule) };
 }

package/dist/core/data-validation-overlay.d.ts

@@ -11,6 +11,11 @@ export declare class DataValidationOverlay {
      * (`<x14:dataValidation>`), the carrier Excel uses for a list source on another sheet and other
      * shapes the standard element cannot express. The reader sets it for a rule found in that form so a
      * round-trip writes it back there instead of silently corrupting the cross-sheet reference.
+     *
+     * @throws {AuthoringError} when `sqref` names no area at all. A rule attached to nothing covers no
+     * cell and is written back as the same unreadable text, so it is a mistake worth surfacing at the
+     * call. The reader does not reach this: it drops such an entry at its own boundary, where a foreign
+     * file's malformed attribute is supposed to be dropped.
      */
     add(sqref: string, rule: DataValidation, options?: {
         extended?: boolean;
@@ -23,6 +28,12 @@ export declare class DataValidationOverlay {
      * validations.
      */
     at(col: number, row: number): DataValidation | undefined;
+    /**
+     * Re-anchor every rule through a row or column splice, so a dropdown stays on the cells it was
+     * attached to rather than on whatever moved into their place. A rule whose every target area fell
+     * inside a deleted span is dropped with them.
+     */
+    shift(axis: 'row' | 'col', start: number, count: number, delta: number): void;
     /** Drop every validation, leaving the overlay empty. */
     clear(): void;
 }

package/dist/core/data-validation-overlay.js

@@ -1,15 +1,21 @@
+import { AuthoringError } from '../errors.js';
+import { replaceContents } from './containers.js';
 import { cloneDataValidation, } from './data-validation.js';
-import { decodeSqrefRects } from './merge.js';
+import { decodeSqrefRects, shiftSqref } from './merge.js';
 export class DataValidationOverlay {
     #entries = [];
     #rects = [];
     add(sqref, rule, options = {}) {
+        const rects = decodeSqrefRects(sqref);
+        if (rects.length === 0) {
+            throw new AuthoringError(`data validation range "${sqref}" names no cells`);
+        }
         const stored = cloneDataValidation(rule);
         const entry = { sqref, rule: stored };
         if (options.extended)
             entry.extended = true;
         this.#entries.push(entry);
-        this.#rects.push({ rects: decodeSqrefRects(sqref), rule: stored });
+        this.#rects.push({ rects, rule: stored });
     }
     get entries() {
         return this.#entries;
@@ -24,6 +30,19 @@ export class DataValidationOverlay {
         }
         return undefined;
     }
+    shift(axis, start, count, delta) {
+        const entries = [];
+        const rects = [];
+        for (const entry of this.#entries) {
+            const sqref = shiftSqref(entry.sqref, axis, start, count, delta);
+            if (sqref === undefined)
+                continue;
+            entries.push({ ...entry, sqref });
+            rects.push({ rects: decodeSqrefRects(sqref), rule: entry.rule });
+        }
+        replaceContents(this.#entries, entries);
+        replaceContents(this.#rects, rects);
+    }
     clear() {
         this.#entries.length = 0;
         this.#rects.length = 0;

package/dist/core/data-validation.d.ts

@@ -1,11 +1,18 @@
 /** The kind of constraint a validation enforces. `list` is a dropdown; `custom` is an arbitrary
- * boolean formula; the rest bound a typed value (`whole`/`decimal`/`date`/`time`/`textLength`). */
-export type DataValidationType = 'list' | 'whole' | 'decimal' | 'date' | 'time' | 'textLength' | 'custom';
+ * boolean formula; `none` constrains nothing and exists only to carry the rule's messages; the rest
+ * bound a typed value (`whole`/`decimal`/`date`/`time`/`textLength`). */
+export type DataValidationType = 'none' | 'list' | 'whole' | 'decimal' | 'date' | 'time' | 'textLength' | 'custom';
+/** Narrow a raw `<dataValidation type>` token to a known {@link DataValidationType}. */
+export declare function isDataValidationType(value: string): value is DataValidationType;
 /** How a typed validation compares its operand(s). Absent on a `list`/`custom` rule; defaults to
  * `between` on a typed rule (the value Excel omits from the XML). */
 export type DataValidationOperator = 'between' | 'notBetween' | 'equal' | 'notEqual' | 'greaterThan' | 'lessThan' | 'greaterThanOrEqual' | 'lessThanOrEqual';
+/** Narrow a raw `<dataValidation operator>` token to a known {@link DataValidationOperator}. */
+export declare function isDataValidationOperator(value: string): value is DataValidationOperator;
 /** How Excel reacts to input that fails the rule. */
 export type DataValidationErrorStyle = 'stop' | 'warning' | 'information';
+/** Narrow a raw `<dataValidation errorStyle>` token to a known {@link DataValidationErrorStyle}. */
+export declare function isDataValidationErrorStyle(value: string): value is DataValidationErrorStyle;
 /** One validation rule. `formulae` holds the operand(s), `formula1` then optional `formula2`: a
  * numeric literal is stored as a number, while a cell reference, defined name, or list source keeps
  * its verbatim string. */