@shbernal/ts-xlsx 2.1.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
@@ -43,7 +44,7 @@ export interface CustomFilterPredicate {
 }
 export type CustomFilterOperator = 'equal' | 'notEqual' | 'lessThan' | 'lessThanOrEqual' | 'greaterThan' | 'greaterThanOrEqual';
 /** Narrow a raw `operator` attribute to a known {@link CustomFilterOperator}. */
-export declare function isCustomFilterOperator(value: string): value is CustomFilterOperator;
+export declare const isCustomFilterOperator: (value: string) => value is CustomFilterOperator;
 /**
  * Validate and normalise a settable autofilter into its canonical stored form. A bare range string
  * is the common case (dropdowns, no criteria); an {@link AutoFilter} object carries per-column
@@ -54,8 +55,8 @@ export declare function isCustomFilterOperator(value: string): value is CustomFi
  */
 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,28 +1,27 @@
-import { AuthoringError } from '../errors.js';
-import { decodeRange, encodeAddress } from './address.js';
-import { isDeletedSpan, shiftIndex } from './grid-shift.js';
-const CUSTOM_FILTER_OPERATORS = {
+import { AuthoringError, quoted } from '../errors.js';
+import { tokenSet } from '../token-set.js';
+import { boundedRect, decodeRange, encodeRect } from './address.js';
+import { isDeletedSpan, shiftIndex, shiftRect } from './grid-shift.js';
+export const isCustomFilterOperator = tokenSet({
     equal: true,
     notEqual: true,
     lessThan: true,
     lessThanOrEqual: true,
     greaterThan: true,
     greaterThanOrEqual: true,
-};
-export function isCustomFilterOperator(value) {
-    return Object.hasOwn(CUSTOM_FILTER_OPERATORS, value);
-}
+});
 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)),
     };
 }
@@ -30,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] } };
+    }
+    const count = criteria.predicates.length;
+    if (count < 1 || count > 2) {
+        throw new AuthoringError(`a custom filter needs one or two predicates, got ${count}`);
     }
-    return column;
+    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

@@ -0,0 +1,10 @@
+export declare abstract class AxisHandle<P extends object> {
+    /** This position's format record, or `undefined` when it has none. Never fabricates one. */
+    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

@@ -0,0 +1,17 @@
+export class AxisHandle {
+    read(key) {
+        return this.propertiesOf()?.[key];
+    }
+    write(key, value) {
+        if (value === undefined) {
+            const properties = this.propertiesOf();
+            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

@@ -138,6 +138,31 @@ export declare class Cell {
     get note(): string | undefined;
     set note(note: string | undefined);
 }
+/**
+ * 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
+ * empty cell needs serialising asks exactly this. A caller asking whether the cell is *used* wants
+ * {@link cellCarriesContent}, which is this plus the value and the note.
+ */
+export declare function cellHasOwnStyle(cell: Cell): boolean;
+/**
+ * Whether a cell carries anything at all: a value, formatting of its own, or a note. This is the
+ * used-range test, the "carrying anything (data or its own formatting)" that `rowCount` and
+ * `columnCount` promise, and it is deliberately wider than "holds a value": someone who pre-formats
+ * an empty band has
+ * laid claim to those cells, and an append that treats them as free ground writes over the layout
+ * they just built; someone who notes an empty cell has put content in it by the note's own
+ * definition.
+ *
+ * A cell merely materialised by `getCell` and then left alone carries nothing, which is what keeps
+ * reading a far address from growing the sheet.
+ */
+export declare function cellCarriesContent(cell: Cell): boolean;
 export declare function applyCellStyle(cell: Cell, style: Readonly<CellStyle>): void;
 export declare function copyCellContent(source: CellModel, target: Cell): void;
 export declare function cellToModel(cell: Cell): CellModel;

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, } from './style.js';
+import { assignContentFacets, assignStyleFacets, CELL_CONTENT_FACETS, } from './style.js';
 import { cellValueToText, coerceCellValue, detectValueType, } from './value.js';
 export class Cell {
     row;
@@ -106,12 +106,18 @@ export class Cell {
         this.#note = note;
     }
 }
+export function cellHasOwnStyle(cell) {
+    return CELL_CONTENT_FACETS.some((facet) => cell[facet] !== undefined);
+}
+export function cellCarriesContent(cell) {
+    return cell.value !== null || cell.note !== undefined || cellHasOwnStyle(cell);
+}
 export function applyCellStyle(cell, style) {
     assignStyleFacets(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) {
@@ -121,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

@@ -1,9 +1,10 @@
+import { AxisHandle } from './axis-handle.ts';
 import type { Cell } from './cell.ts';
 import { type AssertNever } from './internal.ts';
 import type { Alignment, Border, Fill, Font, Protection } from './style.ts';
 import type { CellValue } from './value.ts';
 import type { ColumnProperties, Worksheet } from './worksheet.ts';
-export declare class Column {
+export declare class Column extends AxisHandle<ColumnProperties> {
     #private;
     /** 1-based column index. Fixed for this handle's lifetime. */
     readonly index: number;
@@ -18,6 +19,9 @@ export declare class Column {
      * is formatted, and they create the record on first write.
      */
     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.