@shbernal/ts-xlsx 3.0.0 → 3.1.0

package/README.md

@@ -149,12 +149,15 @@ const writer = new WorkbookStreamWriter();
 const out = writer.addWorksheet('Big');
 for (let i = 1; i <= 1_000_000; i++) out.addRow([i, i * i]).commit();
 out.commit();
-const packaged: Uint8Array = await writer.commit(); // also delivered via writer.stream
+const packaged = await writer.commit(); // Uint8Array here; also delivered via writer.stream
 ```
 
 The streaming writer is asynchronous where the buffered path is synchronous: `commit()`
 resolves to the package bytes and simultaneously pipes them through `writer.stream` (a Node
 `Readable`), so `writer.stream.pipe(res)` streams a workbook straight to an HTTP response.
+Hand the writer its own sink instead (`{stream}` or `{filename}`) and never touch
+`writer.stream`, and `commit()` resolves with `undefined`: the archive goes to the sink and is
+never assembled as one object, which is what passing a sink was for.
 
 ## Writing without blocking the event loop
 

package/dist/bytes.d.ts

@@ -22,3 +22,10 @@ export declare function concat(chunks: readonly Uint8Array[], size?: number): Ui
  * hash, so the loop below is not on any path where its cost is measurable.
  */
 export declare function toBase64(bytes: Uint8Array): string;
+/** A string's UTF-16LE bytes, code unit by code unit, with lone surrogates carried through. */
+export declare function utf16leBytes(text: string): Uint8Array;
+/**
+ * Decode UTF-16LE code units. A trailing odd byte is dropped: these fields are length-prefixed by
+ * their producer, and half a code unit carries nothing to decode.
+ */
+export declare function decodeUtf16le(bytes: Uint8Array): string;

package/dist/bytes.js

@@ -32,3 +32,25 @@ export function toBase64(bytes) {
     }
     return out;
 }
+export function utf16leBytes(text) {
+    const bytes = new Uint8Array(text.length * 2);
+    for (let i = 0; i < text.length; i++) {
+        const unit = text.charCodeAt(i);
+        bytes[i * 2] = unit & 0xff;
+        bytes[i * 2 + 1] = unit >>> 8;
+    }
+    return bytes;
+}
+const CHARS_PER_BATCH = 4096;
+export function decodeUtf16le(bytes) {
+    let text = '';
+    let batch = [];
+    for (let i = 0; i + 1 < bytes.length; i += 2) {
+        batch.push(bytes[i] | (bytes[i + 1] << 8));
+        if (batch.length === CHARS_PER_BATCH) {
+            text += String.fromCharCode(...batch);
+            batch = [];
+        }
+    }
+    return batch.length > 0 ? text + String.fromCharCode(...batch) : text;
+}

package/dist/core/address.d.ts

@@ -2,6 +2,22 @@
 export declare const MAX_COLUMN = 16384;
 /** Excel's row bound: 1 through 1048576. The other axis of {@link MAX_COLUMN}. */
 export declare const MAX_ROW = 1048576;
+/**
+ * The same two bounds, zero-based: the last valid *index* on each axis.
+ *
+ * BIFF12 counts from zero throughout, so its reader and its formula decoder both need these, and both
+ * were deriving them privately. Two derivations of one fact is one fewer than three, but it is still
+ * the shape where a change to a limit reaches some of its consequences. The subtraction belongs beside
+ * the number it subtracts from.
+ */
+export declare const MAX_COLUMN_INDEX: number;
+export declare const MAX_ROW_INDEX: number;
+/**
+ * Refuse a coordinate that names no position on the grid.
+ *
+ * @throws {RangeError} unless `value` is an integer within the axis's bounds.
+ */
+export declare function assertAxisInBounds(axis: 'row' | 'column', value: number): void;
 /** @throws {RangeError} unless `n` is an integer in `1..MAX_COLUMN`. */
 export declare function assertColumnInBounds(n: number): void;
 /** @throws {RangeError} unless `n` is an integer in `1..MAX_ROW`. */
@@ -56,7 +72,19 @@ export interface RangeAddress {
  *
  * @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`). */
+/**
+ * Convert column letters to a 1-based number (`"A" → 1`, `"AA" → 27`), or `undefined` when they name
+ * no column that can exist: not letters at all, or past `XFD` (`"ZZZ"` is well-formed and is column
+ * 18278, which the grid does not have). The tolerant half of the pair the module header describes,
+ * for a caller reading a file rather than a caller's own argument.
+ */
+export declare function tryColumnToNumber(letters: string): number | undefined;
+/**
+ * Convert column letters to a 1-based number (`"A" → 1`, `"AA" → 27`).
+ *
+ * @throws {RangeError} if the letters are malformed or name a column past `XFD`. The two are
+ *   separate messages because a caller fixes them differently.
+ */
 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
@@ -67,6 +95,17 @@ export declare function columnToNumber(letters: string): number;
  * 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;
+/**
+ * A bounded rectangle as its canonical `tl:br` A1 range, `"B2:D5"`. A one-cell rectangle still reads
+ * as `"B2:B2"`, which is the form Excel writes and the form every consumer of these refs parses.
+ *
+ * The rendering half of {@link boundedRect}, and it belongs beside it for the same reason: ten sites
+ * spelled `` `${encodeAddress(left, top)}:${encodeAddress(right, bottom)}` `` by hand, and the risk in
+ * that expression is not its length but its argument order. `encodeAddress` takes column first and a
+ * rectangle names its rows first, so the two orders are transposed with respect to each other at every
+ * one of those sites.
+ */
+export declare function encodeRect(rect: GridRect): string;
 /**
  * Decode a single cell/row/column reference into `{address, col, row}`. Anchoring
  * `$` signs are accepted and dropped; an absent axis is `undefined`.
@@ -98,6 +137,19 @@ export declare function decodeCellRef(reference: string): CellPosition;
  * there is nothing here".
  */
 export declare function tryDecodeCellRef(reference: string): CellPosition | undefined;
+/**
+ * Narrow a decoded range to a {@link GridRect}, or `undefined` when either axis is unbounded.
+ *
+ * A whole-column reference (`A:A`) and a whole-row one (`1:1`) are legal range references whose
+ * corners are partly absent, so every caller that needs a real rectangle has to test all four. Doing
+ * that in seven places is the other half of the convention `GridRect` already exists to state once:
+ * the shape is declared here, and so is the one narrowing that produces it.
+ *
+ * A caller wanting to say something *different* about each axis (a `Range` refuses `A:A` and `1:1`
+ * with two distinct messages) still tests them separately, and one that only cares about the axis it
+ * is splicing still tests only that one. Neither is this question.
+ */
+export declare function boundedRect(range: RangeAddress): GridRect | 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
@@ -114,5 +166,11 @@ export declare function tryDecodeRange(reference: string): RangeAddress | undefi
  * corners coincide.
  */
 export declare function decodeRange(reference: string): RangeAddress;
-/** Encode a 1-based `col`/`row` pair into its canonical A1 address (`"B2"`). */
+/**
+ * Encode a 1-based `col`/`row` pair into its canonical A1 address (`"B2"`).
+ *
+ * Both axes go through the shared guard. The column already did, through `numberToColumn`; the row
+ * checked only its lower bound in a message of its own, so `encodeAddress(1, 1048577)` produced an
+ * address naming a row Excel has no reference for while `encodeAddress(16385, 1)` refused.
+ */
 export declare function encodeAddress(col: number, row: number): string;

package/dist/core/address.js

@@ -1,14 +1,20 @@
+import { quoted } from '../errors.js';
 export const MAX_COLUMN = 16384;
 export const MAX_ROW = 1048576;
-export function assertColumnInBounds(n) {
-    if (!Number.isInteger(n) || n < 1 || n > MAX_COLUMN) {
-        throw new RangeError(`column ${n} is out of bounds: Excel supports 1..${MAX_COLUMN}`);
+export const MAX_COLUMN_INDEX = MAX_COLUMN - 1;
+export const MAX_ROW_INDEX = MAX_ROW - 1;
+const AXIS_BOUND = { row: MAX_ROW, column: MAX_COLUMN };
+export function assertAxisInBounds(axis, value) {
+    const bound = AXIS_BOUND[axis];
+    if (!Number.isInteger(value) || value < 1 || value > bound) {
+        throw new RangeError(`${axis} ${value} is out of bounds: Excel supports 1..${bound}`);
     }
 }
+export function assertColumnInBounds(n) {
+    assertAxisInBounds('column', n);
+}
 export function assertRowInBounds(n) {
-    if (!Number.isInteger(n) || n < 1 || n > MAX_ROW) {
-        throw new RangeError(`row ${n} is out of bounds: Excel supports 1..${MAX_ROW}`);
-    }
+    assertAxisInBounds('row', n);
 }
 export function rectsOverlap(a, b) {
     return a.left <= b.right && b.left <= a.right && a.top <= b.bottom && b.top <= a.bottom;
@@ -26,38 +32,43 @@ export function numberToColumn(n) {
     }
     return letters;
 }
-export function columnToNumber(letters) {
-    if (letters.length === 0 || letters.length > 3) {
-        throw new RangeError(`invalid column letters: "${letters}"`);
-    }
+const COLUMN_LETTERS = /^[A-Z]{1,3}$/;
+export function tryColumnToNumber(letters) {
+    if (!COLUMN_LETTERS.test(letters))
+        return undefined;
     let n = 0;
     for (let i = 0; i < letters.length; i++) {
-        const code = letters.charCodeAt(i);
-        if (code < 65 || code > 90) {
-            throw new RangeError(`invalid column letters: "${letters}"`);
-        }
-        n = n * 26 + (code - 64);
+        n = n * 26 + (letters.charCodeAt(i) - 64);
     }
-    if (n > MAX_COLUMN) {
-        throw new RangeError(`column "${letters}" is out of bounds: Excel supports up to ${MAX_COLUMN} (XFD)`);
+    return n > MAX_COLUMN ? undefined : n;
+}
+export function columnToNumber(letters) {
+    const n = tryColumnToNumber(letters);
+    if (n !== undefined)
+        return n;
+    if (!COLUMN_LETTERS.test(letters)) {
+        throw new RangeError(`invalid column letters: ${quoted(letters)}`);
     }
-    return n;
+    throw new RangeError(`column ${quoted(letters)} is out of bounds: Excel supports up to ${MAX_COLUMN} (XFD)`);
 }
 export function encodeCornerRef(col, row) {
     return `${col !== undefined ? numberToColumn(col) : ''}${row !== undefined ? row : ''}`;
 }
+export function encodeRect(rect) {
+    return `${encodeAddress(rect.left, rect.top)}:${encodeAddress(rect.right, rect.bottom)}`;
+}
 function makeCellAddress(col, row) {
     return { address: encodeCornerRef(col, row), col, row };
 }
 export function decodeAddress(reference) {
     const match = SINGLE_REF.exec(reference);
     if (!match) {
-        throw new SyntaxError(`invalid cell reference: "${reference}"`);
+        throw new SyntaxError(`invalid cell reference: ${quoted(reference)}`);
     }
     const letters = match[1] ?? '';
     const digits = match[2] ?? '';
     if (letters.length === 0 && digits.length === 0) {
-        throw new SyntaxError(`invalid cell reference: "${reference}"`);
+        throw new SyntaxError(`invalid cell reference: ${quoted(reference)}`);
     }
     const col = letters.length > 0 ? columnToNumber(letters) : undefined;
     const row = digits.length > 0 ? Number.parseInt(digits, 10) : undefined;
@@ -66,7 +77,7 @@ export function decodeAddress(reference) {
 export function decodeCellRef(reference) {
     const { col, row } = decodeAddress(reference);
     if (col === undefined || row === undefined) {
-        throw new SyntaxError(`"${reference}" is not a single-cell reference: it omits a column or row`);
+        throw new SyntaxError(`${quoted(reference)} is not a single-cell reference: it omits a column or row`);
     }
     return { col, row };
 }
@@ -83,6 +94,13 @@ export function tryDecodeCellRef(reference) {
     }
     return rowCanExist(position.row) ? position : undefined;
 }
+export function boundedRect(range) {
+    const { top, left, bottom, right } = range;
+    if (top === undefined || left === undefined || bottom === undefined || right === undefined) {
+        return undefined;
+    }
+    return { top, left, bottom, right };
+}
 export function tryDecodeRange(reference) {
     let range;
     try {
@@ -125,8 +143,6 @@ export function decodeRange(reference) {
     };
 }
 export function encodeAddress(col, row) {
-    if (!Number.isInteger(row) || row < 1) {
-        throw new RangeError(`row ${row} is out of bounds: rows start at 1`);
-    }
+    assertRowInBounds(row);
     return `${numberToColumn(col)}${row}`;
 }

package/dist/core/autofilter.d.ts

@@ -1,3 +1,4 @@
+import { type AxisSplice } from './grid-shift.ts';
 /**
  * A worksheet's autofilter: the filtered region plus any per-column criteria narrowing it. A bare
  * range (no columns) is just the header-row dropdowns Excel draws; adding {@link FilterColumn}s
@@ -54,8 +55,8 @@ export declare const isCustomFilterOperator: (value: string) => value is CustomF
  */
 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.
+ * Re-anchor a filter through a splice, 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
@@ -63,4 +64,4 @@ export declare function canonicalizeAutoFilter(input: string | AutoFilter): Auto
  * 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;
+export declare function shiftAutoFilter(filter: AutoFilter, splice: AxisSplice): AutoFilter | undefined;

package/dist/core/autofilter.js

@@ -1,7 +1,7 @@
-import { AuthoringError } from '../errors.js';
+import { AuthoringError, quoted } from '../errors.js';
 import { tokenSet } from '../token-set.js';
-import { decodeRange, encodeAddress } from './address.js';
-import { isDeletedSpan, shiftIndex } from './grid-shift.js';
+import { boundedRect, decodeRange, encodeRect } from './address.js';
+import { isDeletedSpan, shiftIndex, shiftRect } from './grid-shift.js';
 export const isCustomFilterOperator = tokenSet({
     equal: true,
     notEqual: true,
@@ -12,15 +12,16 @@ export const isCustomFilterOperator = tokenSet({
 });
 export function canonicalizeAutoFilter(input) {
     const ref = typeof input === 'string' ? input : input.ref;
-    const { top, left, bottom, right, dimensions } = decodeRange(ref);
-    if (top === undefined || left === undefined || bottom === undefined || right === undefined) {
-        throw new AuthoringError(`autofilter range "${ref}" must be a bounded rectangle`);
+    const decoded = decodeRange(ref);
+    const rect = boundedRect(decoded);
+    if (rect === undefined) {
+        throw new AuthoringError(`autofilter range ${quoted(ref)} must be a bounded rectangle`);
     }
     if (typeof input === 'string')
-        return { ref: dimensions, columns: [] };
-    const width = right - left + 1;
+        return { ref: decoded.dimensions, columns: [] };
+    const width = rect.right - rect.left + 1;
     return {
-        ref: dimensions,
+        ref: decoded.dimensions,
         columns: input.columns.map((column) => canonicalizeColumn(column, width)),
     };
 }
@@ -28,35 +29,35 @@ function canonicalizeColumn(column, width) {
     if (!Number.isInteger(column.colId) || column.colId < 0 || column.colId >= width) {
         throw new AuthoringError(`autofilter colId ${column.colId} is outside the filter range`);
     }
-    if (column.criteria.kind === 'custom') {
-        const count = column.criteria.predicates.length;
-        if (count < 1 || count > 2) {
-            throw new AuthoringError(`a custom filter needs one or two predicates, got ${count}`);
-        }
+    const criteria = column.criteria;
+    if (criteria.kind === 'values') {
+        return { colId: column.colId, criteria: { ...criteria, values: [...criteria.values] } };
     }
-    return column;
+    const count = criteria.predicates.length;
+    if (count < 1 || count > 2) {
+        throw new AuthoringError(`a custom filter needs one or two predicates, got ${count}`);
+    }
+    return {
+        colId: column.colId,
+        criteria: { ...criteria, predicates: criteria.predicates.map((predicate) => ({ ...predicate })) },
+    };
 }
-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) {
+export function shiftAutoFilter(filter, splice) {
+    const rect = boundedRect(decodeRange(filter.ref));
+    if (rect === undefined)
         return filter;
-    }
-    const [lo, hi] = axis === 'row' ? [top, bottom] : [left, right];
-    if (isDeletedSpan(lo, hi, start, count))
+    const moved = shiftRect(rect, splice);
+    if (moved === undefined)
         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)}`;
+    const ref = encodeRect(moved);
+    if (splice.axis === 'row')
         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))
+        const absolute = rect.left + column.colId;
+        if (isDeletedSpan(absolute, absolute, splice))
             continue;
-        columns.push({ ...column, colId: shiftIndex(absolute, start, count, delta, axis) - movedLo });
+        columns.push({ ...column, colId: shiftIndex(absolute, splice) - moved.left });
     }
     return { ref, columns };
 }

package/dist/core/axis-handle.d.ts

@@ -3,6 +3,8 @@ export declare abstract class AxisHandle<P extends object> {
     protected abstract propertiesOf(): P | undefined;
     /** This position's format record, created if it does not exist yet. */
     protected abstract ensureProperties(): P;
+    /** Remove this position's format record entirely, so nothing is left declaring the line. */
+    protected abstract dropProperties(): void;
     protected read<K extends keyof P>(key: K): P[K] | undefined;
     protected write<K extends keyof P>(key: K, value: P[K]): void;
 }

package/dist/core/axis-handle.js

@@ -5,8 +5,11 @@ export class AxisHandle {
     write(key, value) {
         if (value === undefined) {
             const properties = this.propertiesOf();
-            if (properties !== undefined)
-                delete properties[key];
+            if (properties === undefined)
+                return;
+            delete properties[key];
+            if (Object.keys(properties).length === 0)
+                this.dropProperties();
             return;
         }
         this.ensureProperties()[key] = value;

package/dist/core/cell.d.ts

@@ -139,9 +139,10 @@ export declare class Cell {
     set note(note: string | undefined);
 }
 /**
- * Whether a cell carries formatting of its own: one of the {@link CellStyle} facets, the quote-prefix
- * flag, or a link to a named style. Driven by {@link CELL_STYLE_FACETS}, so a facet added to the
- * tuple reaches every "is this cell blank" decision without anyone remembering to widen a literal.
+ * Whether a cell carries formatting of its own: any {@link CellContent} facet, which is the six shared
+ * style facets plus the quote-prefix flag and the link to a named style. Driven by
+ * {@link CELL_CONTENT_FACETS}, so a facet added to the tuple reaches every "is this cell blank"
+ * decision without anyone remembering to widen a literal.
  *
  * Row- and column-inherited formatting is not the cell's own and does not count. Neither does a
  * note: it lives in the comments part, not the cell's `<c>` element, so a writer deciding whether an

package/dist/core/cell.js

@@ -1,6 +1,6 @@
 import { assertColumnInBounds, assertRowInBounds, encodeAddress } from './address.js';
 import { NAMED_STYLE_ID } from './internal.js';
-import { assignStyleFacets, CELL_STYLE_FACETS, } from './style.js';
+import { assignContentFacets, assignStyleFacets, CELL_CONTENT_FACETS, } from './style.js';
 import { cellValueToText, coerceCellValue, detectValueType, } from './value.js';
 export class Cell {
     row;
@@ -107,9 +107,7 @@ export class Cell {
     }
 }
 export function cellHasOwnStyle(cell) {
-    return (CELL_STYLE_FACETS.some((facet) => cell[facet] !== undefined) ||
-        cell.quotePrefix === true ||
-        cell[NAMED_STYLE_ID] !== undefined);
+    return CELL_CONTENT_FACETS.some((facet) => cell[facet] !== undefined);
 }
 export function cellCarriesContent(cell) {
     return cell.value !== null || cell.note !== undefined || cellHasOwnStyle(cell);
@@ -119,7 +117,7 @@ export function applyCellStyle(cell, style) {
 }
 export function copyCellContent(source, target) {
     target.value = source.value;
-    applyCellStyle(target, source);
+    assignContentFacets(target, source);
     target.note = source.note;
 }
 export function cellToModel(cell) {
@@ -129,6 +127,6 @@ export function cellToModel(cell) {
         value: cell.value,
         note: cell.note,
     };
-    assignStyleFacets(model, cell);
+    assignContentFacets(model, cell);
     return model;
 }

package/dist/core/clone.d.ts

@@ -0,0 +1,29 @@
+/**
+ * How far a copy of one field goes.
+ *
+ * - `'value'`: assign it. Correct for a scalar, and for anything genuinely immutable.
+ * - `'record'`: `{...v}`. A flat object whose own fields are scalars.
+ * - `'values'`: `[...v]`. An array of scalars.
+ * - `'records'`: `v.map(x => ({...x}))`. An array of flat objects.
+ * - a function: the field's own clone, for a nested type that has a plan of its own.
+ */
+export type CloneStrategy<V> = 'value' | 'record' | 'values' | 'records' | ((value: V) => V);
+/**
+ * One strategy per field of `T`. The `Record` is what makes a missing field a compile error.
+ *
+ * A field's strategy sees the field's type without `undefined`, because {@link cloneWith} skips an
+ * absent field rather than handing it over. Under `exactOptionalPropertyTypes` a facet declared
+ * `font?: Font | undefined` keeps that `undefined` through `Required`, so without the exclusion a
+ * nested type's own clone function would not satisfy its own field's strategy.
+ */
+export type ClonePlan<T> = {
+    readonly [K in keyof Required<T>]-?: CloneStrategy<Exclude<Required<T>[K], undefined>>;
+};
+/**
+ * Copy `source` according to `plan`, leaving a field absent when the source leaves it absent.
+ *
+ * Absent rather than `undefined`: every one of these types declares its optional fields under
+ * `exactOptionalPropertyTypes`, where a present-but-undefined key is a different shape from a missing
+ * one, and a round-trip that fabricated the first would report formatting a cell does not have.
+ */
+export declare function cloneWith<T extends object>(source: T, plan: ClonePlan<T>): T;

package/dist/core/clone.js

@@ -0,0 +1,24 @@
+export function cloneWith(source, plan) {
+    const out = {};
+    for (const key of Object.keys(plan)) {
+        const value = source[key];
+        if (value === undefined)
+            continue;
+        out[key] = applyStrategy(value, plan[key]);
+    }
+    return out;
+}
+function applyStrategy(value, strategy) {
+    if (typeof strategy === 'function')
+        return strategy(value);
+    switch (strategy) {
+        case 'value':
+            return value;
+        case 'record':
+            return { ...value };
+        case 'values':
+            return [...value];
+        case 'records':
+            return value.map((entry) => ({ ...entry }));
+    }
+}

package/dist/core/color-resolution.js

@@ -1,3 +1,4 @@
+import { hex } from '../hex.js';
 import { parseArgb } from './style.js';
 import { DEFAULT_THEME_COLOR_SCHEME, THEME_COLOR_SLOTS } from './theme.js';
 export const DEFAULT_INDEXED_COLORS = [
@@ -102,8 +103,5 @@ function hueToChannel(p, q, offset) {
     return p;
 }
 function channelHex(value) {
-    return Math.round(clamp01(value) * 255)
-        .toString(16)
-        .toUpperCase()
-        .padStart(2, '0');
+    return hex(Math.round(clamp01(value) * 255), 2);
 }

package/dist/core/column.d.ts

@@ -21,6 +21,7 @@ export declare class Column extends AxisHandle<ColumnProperties> {
     get properties(): Readonly<ColumnProperties> | undefined;
     protected propertiesOf(): ColumnProperties | undefined;
     protected ensureProperties(): ColumnProperties;
+    protected dropProperties(): void;
     /**
      * Stable key naming this column so a keyed-object row (see {@link Worksheet.addRow}) can place a
      * value under it by name rather than position. In-memory only: never serialized to OOXML.

package/dist/core/column.js

@@ -22,6 +22,9 @@ export class Column extends AxisHandle {
     ensureProperties() {
         return this.#sheet[INTERNAL].ensureColumnProperties(this.index);
     }
+    dropProperties() {
+        this.#sheet[INTERNAL].dropColumnProperties(this.index);
+    }
     get key() {
         return this.read('key');
     }

package/dist/core/comment-thread.js

@@ -1,9 +1,10 @@
+import { quoted } from '../errors.js';
 const GUID = /^\{?([0-9a-f]{8})-([0-9a-f]{4})-([0-9a-f]{4})-([0-9a-f]{4})-([0-9a-f]{12})\}?$/i;
 export function commentThreadGuid(value, what) {
     const match = GUID.exec(value.trim());
     if (match === null) {
         throw new SyntaxError(`${what} must be a GUID: Excel writes threaded-comment ids as ` +
-            `"{XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}", but got "${value}"`);
+            `"{XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}", but got ${quoted(value)}`);
     }
     return `{${match.slice(1).join('-').toUpperCase()}}`;
 }

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

@@ -1,4 +1,5 @@
 import { type ConditionalFormatting } from './conditional-formatting.ts';
+import type { AxisSplice } from './grid-shift.ts';
 export declare class ConditionalFormattingOverlay {
     #private;
     /**
@@ -14,7 +15,7 @@ export declare class ConditionalFormattingOverlay {
      * 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;
+    shift(splice: AxisSplice): void;
     /** Drop every conditional formatting, leaving the overlay empty. */
     clear(): void;
 }

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

@@ -9,10 +9,10 @@ export class ConditionalFormattingOverlay {
     get entries() {
         return this.#entries;
     }
-    shift(axis, start, count, delta) {
+    shift(splice) {
         const entries = [];
         for (const entry of this.#entries) {
-            const ref = shiftSqref(entry.ref, axis, start, count, delta);
+            const ref = shiftSqref(entry.ref, splice);
             if (ref !== undefined)
                 entries.push({ ...entry, ref });
         }

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

@@ -1,4 +1,7 @@
-import type { Color, DifferentialStyle } from './style.ts';
+import { type ClonePlan } from './clone.ts';
+import type { AssertNever } from './internal.ts';
+import { type Color } from './style.ts';
+import type { DifferentialStyle } from './workbook-styles.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}. */
@@ -108,3 +111,8 @@ export interface ConditionalFormatting {
 /** A defensive deep copy, so a stored conditional formatting never aliases the caller's object nor
  * any of its nested arrays (rules, formulae, cfvo, colours) or the differential style. */
 export declare function cloneConditionalFormatting(cf: ConditionalFormatting): ConditionalFormatting;
+declare const RULE_CLONE: ClonePlan<ConditionalFormattingRule>;
+export type EveryRuleFieldIsCloned = AssertNever<Exclude<keyof Required<ConditionalFormattingRule>, keyof typeof RULE_CLONE>>;
+declare const STYLE_CLONE: ClonePlan<DifferentialStyle>;
+export type EveryDifferentialStyleFieldIsCloned = AssertNever<Exclude<keyof Required<DifferentialStyle>, keyof typeof STYLE_CLONE>>;
+export {};