@shbernal/ts-xlsx 3.0.0 → 3.1.0

package/dist/core/pivot-table.js

@@ -1,6 +1,7 @@
-import { AuthoringError, InternalError } from '../errors.js';
+import { AuthoringError, InternalError, quoted } from '../errors.js';
 import { tokenSet } from '../token-set.js';
-import { encodeAddress } from './address.js';
+import { encodeRect } from './address.js';
+import { INTERNAL } from './internal.js';
 import { isErrorValue, isFormulaValue, isHyperlinkValue, isRichTextValue, isSharedFormulaValue, richTextToPlain, } from './value.js';
 const PIVOT_METRICS = {
     sum: true,
@@ -40,7 +41,7 @@ export class PivotTable {
     constructor(options) {
         const metric = options.metric ?? 'sum';
         if (!Object.hasOwn(PIVOT_METRICS, metric)) {
-            throw new AuthoringError(`unsupported pivot metric "${metric}": expected one of ${Object.keys(PIVOT_METRICS).join(', ')}`);
+            throw new AuthoringError(`unsupported pivot metric ${quoted(metric)}: expected one of ${Object.keys(PIVOT_METRICS).join(', ')}`);
         }
         this.metric = metric;
         const source = options.source;
@@ -49,51 +50,36 @@ export class PivotTable {
         if (columnCount < 1 || lastRow < 2) {
             throw new AuthoringError('a pivot source needs a header row and at least one data row');
         }
-        const fields = [];
-        for (let col = 1; col <= columnCount; col++) {
-            const name = textOf(scalarOf(source.getCell(encodeAddress(col, 1)).value));
-            if (name !== '')
-                fields.push({ name, col });
-        }
-        if (fields.length === 0)
-            throw new AuthoringError('the pivot source header row is empty');
-        const resolve = (role, name) => {
-            const index = fields.findIndex((field) => field.name === name);
-            if (index < 0) {
-                throw new AuthoringError(`pivot ${role} field "${name}" is not a column header in the source sheet`);
-            }
-            return index;
-        };
-        if (options.rows.length === 0)
-            throw new AuthoringError('a pivot table needs at least one row field');
-        if (options.columns.length === 0)
-            throw new AuthoringError('a pivot table needs at least one column field');
-        const [valueName, ...extraValues] = options.values;
-        if (valueName === undefined || extraValues.length > 0) {
-            throw new AuthoringError('a pivot table needs exactly one value field');
-        }
-        this.rowFields = options.rows.map((name) => resolve('row', name));
-        this.columnFields = options.columns.map((name) => resolve('column', name));
-        this.valueField = resolve('value', valueName);
-        const axisFields = new Set([...this.rowFields, ...this.columnFields]);
+        const internals = source[INTERNAL];
+        const valueAt = (row, col) => internals.peekCell(row, col)?.value ?? null;
+        const fields = discoverFields(valueAt, columnCount);
+        const roles = resolveRoles(options, fields);
+        this.rowFields = roles.rowFields;
+        this.columnFields = roles.columnFields;
+        this.valueField = roles.valueField;
+        const axisFields = new Set([...roles.rowFields, ...roles.columnFields]);
         const firstField = fields[0];
-        const lastField = fields[fields.length - 1];
+        const lastField = fields.at(-1);
         if (firstField === undefined || lastField === undefined) {
-            throw new AuthoringError('the pivot source header row is empty');
+            throw new InternalError('pivot field list is empty after discoverFields guaranteed it is not');
         }
         this.sourceSheetName = source.name;
-        this.sourceRef = `${encodeAddress(firstField.col, 1)}:${encodeAddress(lastField.col, lastRow)}`;
+        this.sourceRef = encodeRect({
+            top: 1,
+            left: firstField.col,
+            bottom: lastRow,
+            right: lastField.col,
+        });
         const dataRowCount = lastRow - 1;
         const columnScalars = fields.map((field) => {
             const scalars = [];
-            for (let row = 2; row <= lastRow; row++) {
-                scalars.push(scalarOf(source.getCell(encodeAddress(field.col, row)).value));
-            }
+            for (let row = 2; row <= lastRow; row++)
+                scalars.push(scalarOf(valueAt(row, field.col)));
             return scalars;
         });
         const catalogues = fields.map(() => null);
         this.cacheFields = fields.map((field, fieldIndex) => {
-            const scalars = scalarsForField(columnScalars, fieldIndex);
+            const scalars = columnScalars[fieldIndex] ?? missingColumn(fieldIndex);
             const containsBlank = scalars.some((scalar) => scalar.kind === 'blank');
             if (axisFields.has(fieldIndex)) {
                 const items = [];
@@ -110,15 +96,18 @@ export class PivotTable {
             }
             return { name: field.name, sharedItems: null, numeric: numericSummary(scalars), containsBlank };
         });
+        const byField = fields.map((_field, fieldIndex) => ({
+            scalars: columnScalars[fieldIndex] ?? missingColumn(fieldIndex),
+            catalogue: catalogues[fieldIndex],
+        }));
         const records = [];
         for (let row = 0; row < dataRowCount; row++) {
-            records.push(fields.map((_field, fieldIndex) => {
-                const scalar = scalarsForField(columnScalars, fieldIndex)[row];
+            records.push(byField.map(({ scalars, catalogue }, fieldIndex) => {
+                const scalar = scalars[row];
                 if (scalar === undefined) {
                     throw new InternalError(`pivot record row ${row} is out of range for field ${fieldIndex}: every column was ` +
                         'scanned for the same dataRowCount above, so this index is always in range');
                 }
-                const catalogue = catalogues[fieldIndex];
                 if (!catalogue)
                     return scalar;
                 const index = catalogue.get(itemKey(scalar));
@@ -138,12 +127,41 @@ export class PivotTable {
         return field.name;
     }
 }
-function scalarsForField(columnScalars, fieldIndex) {
-    const scalars = columnScalars[fieldIndex];
-    if (scalars === undefined) {
-        throw new InternalError(`pivot field index ${fieldIndex} is out of range for columnScalars: it was built from the same fields array`);
+function discoverFields(valueAt, columnCount) {
+    const fields = [];
+    for (let col = 1; col <= columnCount; col++) {
+        const name = textOf(scalarOf(valueAt(1, col)));
+        if (name !== '')
+            fields.push({ name, col });
     }
-    return scalars;
+    if (fields.length === 0)
+        throw new AuthoringError('the pivot source header row is empty');
+    return fields;
+}
+function resolveRoles(options, fields) {
+    const resolve = (role, name) => {
+        const index = fields.findIndex((field) => field.name === name);
+        if (index < 0) {
+            throw new AuthoringError(`pivot ${role} field ${quoted(name)} is not a column header in the source sheet`);
+        }
+        return index;
+    };
+    if (options.rows.length === 0)
+        throw new AuthoringError('a pivot table needs at least one row field');
+    if (options.columns.length === 0)
+        throw new AuthoringError('a pivot table needs at least one column field');
+    const [valueName, ...extraValues] = options.values;
+    if (valueName === undefined || extraValues.length > 0) {
+        throw new AuthoringError('a pivot table needs exactly one value field');
+    }
+    return {
+        rowFields: options.rows.map((name) => resolve('row', name)),
+        columnFields: options.columns.map((name) => resolve('column', name)),
+        valueField: resolve('value', valueName),
+    };
+}
+function missingColumn(fieldIndex) {
+    throw new InternalError(`pivot field index ${fieldIndex} is out of range for columnScalars: it was built from the same fields array`);
 }
 function itemKey(item) {
     switch (item.kind) {

package/dist/core/protection.js

@@ -1,4 +1,4 @@
-import { concat, toBase64 } from '../bytes.js';
+import { concat, toBase64, utf16leBytes } from '../bytes.js';
 import { sha512 } from '../sha512.js';
 export const SHEET_PROTECTION_FLAGS = [
     { key: 'formatCells', defaultForbidden: true },
@@ -22,7 +22,7 @@ const DEFAULT_SPIN_COUNT = 100000;
 const SALT_BYTES = 16;
 export function deriveCredential(password, spinCount = DEFAULT_SPIN_COUNT) {
     const salt = crypto.getRandomValues(new Uint8Array(SALT_BYTES));
-    let hash = sha512(concat([salt, utf16le(password)]));
+    let hash = sha512(concat([salt, utf16leBytes(password)]));
     const spun = new Uint8Array(hash.length + 4);
     const counter = new DataView(spun.buffer, hash.length, 4);
     for (let i = 0; i < spinCount; i++) {
@@ -37,12 +37,3 @@ export function deriveCredential(password, spinCount = DEFAULT_SPIN_COUNT) {
         spinCount,
     };
 }
-function utf16le(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;
-}

package/dist/core/range.js

@@ -1,5 +1,7 @@
-import { decodeRange, encodeAddress, MAX_COLUMN, MAX_ROW } from './address.js';
+import { quoted } from '../errors.js';
+import { assertAxisInBounds, decodeRange, encodeAddress, encodeRect, MAX_COLUMN, MAX_ROW, } from './address.js';
 import { applyCellStyle } from './cell.js';
+import { INTERNAL } from './internal.js';
 import { CELL_STYLE_FACETS, } from './style.js';
 export class Range {
     #sheet;
@@ -8,10 +10,10 @@ export class Range {
     bottom;
     right;
     constructor(sheet, top, left, bottom, right) {
-        checkBound('row', top, MAX_ROW);
-        checkBound('row', bottom, MAX_ROW);
-        checkBound('column', left, MAX_COLUMN);
-        checkBound('column', right, MAX_COLUMN);
+        assertAxisInBounds('row', top);
+        assertAxisInBounds('row', bottom);
+        assertAxisInBounds('column', left);
+        assertAxisInBounds('column', right);
         this.#sheet = sheet;
         this.top = Math.min(top, bottom);
         this.bottom = Math.max(top, bottom);
@@ -22,7 +24,7 @@ export class Range {
         return this.#sheet;
     }
     get address() {
-        return `${encodeAddress(this.left, this.top)}:${encodeAddress(this.right, this.bottom)}`;
+        return encodeRect(this);
     }
     get rowCount() {
         return this.bottom - this.top + 1;
@@ -45,12 +47,8 @@ export class Range {
     }
     get cells() {
         const cells = [];
-        for (let row = this.top; row <= this.bottom; row++) {
-            for (let col = this.left; col <= this.right; col++) {
-                if (this.#sheet.hasCell(row, col))
-                    cells.push(this.#sheet.getCell(encodeAddress(col, row)));
-            }
-        }
+        for (const cell of this.#storedCells())
+            cells.push(cell);
         return cells;
     }
     get style() {
@@ -64,7 +62,7 @@ export class Range {
             applyCellStyle(cell, style);
     }
     clearStyle() {
-        for (const cell of this.cells) {
+        for (const cell of this.#storedCells()) {
             for (const facet of CELL_STYLE_FACETS)
                 setFacet(cell, facet, undefined);
         }
@@ -105,28 +103,42 @@ export class Range {
     set protection(protection) {
         this.#writeFacet('protection', protection);
     }
-    #materialise() {
-        return [...this.addresses()].map((address) => this.#sheet.getCell(address));
+    *#materialise() {
+        const internals = this.#sheet[INTERNAL];
+        for (let row = this.top; row <= this.bottom; row++) {
+            for (let col = this.left; col <= this.right; col++) {
+                yield internals.masterAt(row, col);
+            }
+        }
     }
     #writeFacet(facet, value) {
-        const cells = value === undefined ? this.cells : this.#materialise();
+        const cells = value === undefined ? this.#storedCells() : this.#materialise();
         for (const cell of cells)
             setFacet(cell, facet, value);
     }
+    *#storedCells() {
+        const internals = this.#sheet[INTERNAL];
+        for (let row = this.top; row <= this.bottom; row++) {
+            for (let col = this.left; col <= this.right; col++) {
+                const cell = internals.peekCell(row, col);
+                if (cell !== undefined)
+                    yield cell;
+            }
+        }
+    }
     #collectShared(target, facet) {
         const shared = this.#sharedFacet(facet);
         if (shared !== undefined)
             target[facet] = shared;
     }
     #sharedFacet(facet) {
+        const internals = this.#sheet[INTERNAL];
         let first;
         let firstKey;
         let seen = 0;
         for (let row = this.top; row <= this.bottom; row++) {
             for (let col = this.left; col <= this.right; col++) {
-                const value = this.#sheet.hasCell(row, col)
-                    ? this.#sheet.getCell(encodeAddress(col, row))[facet]
-                    : undefined;
+                const value = internals.peekCell(row, col)?.[facet];
                 const key = facetKey(value);
                 if (seen === 0) {
                     first = value;
@@ -152,24 +164,16 @@ function facetKey(value) {
         ? Object.fromEntries(Object.entries(inner).sort(([a], [b]) => (a < b ? -1 : 1)))
         : inner);
 }
-function checkBound(axis, value, max) {
-    if (!Number.isInteger(value) || value < 1) {
-        throw new RangeError(`${axis} ${value} is out of bounds: ${axis}s start at 1`);
-    }
-    if (value > max) {
-        throw new RangeError(`${axis} ${value} is out of bounds: the sheet ends at ${max}`);
-    }
-}
 export function rangeFrom(sheet, reference) {
     const { top, left, bottom, right, sheetName, dimensions } = decodeRange(reference);
     if (sheetName !== undefined && sheetName.toLowerCase() !== sheet.name.toLowerCase()) {
-        throw new SyntaxError(`"${reference}" names worksheet "${sheetName}", not "${sheet.name}": a range belongs to the sheet it came from`);
+        throw new SyntaxError(`${quoted(reference)} names worksheet ${quoted(sheetName)}, not ${quoted(sheet.name)}: a range belongs to the sheet it came from`);
     }
     if (top === undefined || bottom === undefined) {
-        throw new SyntaxError(`"${reference}" spans whole columns (${dimensions}): style them through getColumn(n), which says the same thing in one attribute instead of ${MAX_ROW} cells`);
+        throw new SyntaxError(`${quoted(reference)} spans whole columns (${dimensions}): style them through getColumn(n), which says the same thing in one attribute instead of ${MAX_ROW} cells`);
     }
     if (left === undefined || right === undefined) {
-        throw new SyntaxError(`"${reference}" spans whole rows (${dimensions}): style them through getRow(n), which says the same thing in one attribute instead of ${MAX_COLUMN} cells`);
+        throw new SyntaxError(`${quoted(reference)} spans whole rows (${dimensions}): style them through getRow(n), which says the same thing in one attribute instead of ${MAX_COLUMN} cells`);
     }
     return new Range(sheet, top, left, bottom, right);
 }

package/dist/core/row-input.js

@@ -1,4 +1,4 @@
-import { AuthoringError } from '../errors.js';
+import { AuthoringError, quoted } from '../errors.js';
 import { Cell } from './cell.js';
 export function positionalPlacements(values) {
     const placements = [];
@@ -27,5 +27,5 @@ function columnIndexByKey(columns, key) {
         if (properties.key === key)
             return index;
     }
-    throw new AuthoringError(`no column is keyed ${JSON.stringify(key)}: set getColumn(n).key first`);
+    throw new AuthoringError(`no column is keyed ${quoted(key)}: set getColumn(n).key first`);
 }

package/dist/core/row.d.ts

@@ -19,6 +19,7 @@ export declare class Row extends AxisHandle<RowProperties> {
     get properties(): Readonly<RowProperties> | undefined;
     protected propertiesOf(): RowProperties | undefined;
     protected ensureProperties(): RowProperties;
+    protected dropProperties(): void;
     /**
      * Row height in points; `undefined` leaves the sheet default in force.
      *

package/dist/core/row.js

@@ -19,6 +19,9 @@ export class Row extends AxisHandle {
     ensureProperties() {
         return this.#sheet[INTERNAL].ensureRowProperties(this.number);
     }
+    dropProperties() {
+        this.#sheet[INTERNAL].dropRowProperties(this.number);
+    }
     get height() {
         return this.read('height');
     }

package/dist/core/style.d.ts

@@ -1,4 +1,5 @@
-import type { AssertNever } from './internal.ts';
+import { type ClonePlan } from './clone.ts';
+import { type AssertNever, NAMED_STYLE_ID } from './internal.ts';
 /** Underline can be a plain flag or one of Excel's named underline styles. */
 export type UnderlineStyle = boolean | 'none' | 'single' | 'double' | 'singleAccounting' | 'doubleAccounting';
 /** Narrow a raw `<u val>` token to a named {@link UnderlineStyle} (the non-boolean members). */
@@ -36,11 +37,35 @@ export interface Color {
  */
 export declare function parseArgb(value: string): string | undefined;
 /**
- * Fill pattern kinds, as OOXML's `ST_PatternType` enumerates them. `none` is the
+ * Fill pattern kinds, in the order OOXML's `ST_PatternType` enumerates them. `none` is the
  * absence of a fill; `solid` paints the whole cell with the foreground colour (the
  * common case). The remaining hatch patterns are carried for fidelity on read.
+ *
+ * The order is load-bearing rather than cosmetic, which is why it is stated twice over -- here, and
+ * in {@link FILL_PATTERNS_IN_SCHEMA_ORDER}, tied together by a proof. BIFF12 stores a pattern as its
+ * *index* into this enumeration, so the binary codec needs the sequence as a value; the doc above
+ * this type used to claim schema order while the union put `gray125` and `gray0625` at positions 2
+ * and 6, where the schema puts them last, and the binary codec carried a third copy that was right.
+ */
+export type FillPatternType = 'none' | 'solid' | 'mediumGray' | 'darkGray' | 'lightGray' | 'darkHorizontal' | 'darkVertical' | 'darkDown' | 'darkUp' | 'darkGrid' | 'darkTrellis' | 'lightHorizontal' | 'lightVertical' | 'lightDown' | 'lightUp' | 'lightGrid' | 'lightTrellis' | 'gray125' | 'gray0625';
+/**
+ * Every {@link FillPatternType}, in `ST_PatternType` order, which is also the order BIFF12's `fls`
+ * field indexes: `fls` 1 is `solid`, 2 is `mediumGray`, and so on. Index 0 is `none`, which the
+ * model spells as no fill at all rather than as a pattern.
+ *
+ * One list, consulted by the guard below and by `io/xlsb/read-styles.ts`. It replaced three
+ * hand-maintained copies of one enumeration -- the union, the guard's own table, and the binary
+ * codec's index array -- of which only the first two were checked against each other, so adding a
+ * pattern forced the guard to be updated and let the binary codec silently drop it.
  */
-export type FillPatternType = 'none' | 'solid' | 'gray125' | 'darkGray' | 'mediumGray' | 'lightGray' | 'gray0625' | 'darkHorizontal' | 'darkVertical' | 'darkDown' | 'darkUp' | 'darkGrid' | 'darkTrellis' | 'lightHorizontal' | 'lightVertical' | 'lightDown' | 'lightUp' | 'lightGrid' | 'lightTrellis';
+export declare const FILL_PATTERNS_IN_SCHEMA_ORDER: readonly ["none", "solid", "mediumGray", "darkGray", "lightGray", "darkHorizontal", "darkVertical", "darkDown", "darkUp", "darkGrid", "darkTrellis", "lightHorizontal", "lightVertical", "lightDown", "lightUp", "lightGrid", "lightTrellis", "gray125", "gray0625"];
+/**
+ * The two halves of the proof {@link FILL_PATTERNS_IN_SCHEMA_ORDER} owes, since a list -- unlike the
+ * `Record` shape every other token guard here is built from -- can name fewer members than its union
+ * without the compiler minding. `satisfies` above covers "no invented name"; this covers "no
+ * omission".
+ */
+export type EveryFillPatternIsOrdered = AssertNever<Exclude<FillPatternType, (typeof FILL_PATTERNS_IN_SCHEMA_ORDER)[number]>>;
 /** Narrow a raw `<patternFill patternType>` token to a known {@link FillPatternType}. */
 export declare const isFillPatternType: (value: string) => value is FillPatternType;
 /**
@@ -79,6 +104,18 @@ export interface GradientFill {
 }
 /** A cell/row background fill: a flat pattern or a colour gradient. */
 export type Fill = PatternFill | GradientFill;
+declare const GRADIENT_STOP_CLONE: ClonePlan<GradientStop>;
+/** The proof that {@link GRADIENT_STOP_CLONE} names every field of a gradient stop. */
+export type EveryGradientStopFieldIsCloned = AssertNever<Exclude<keyof Required<GradientStop>, keyof typeof GRADIENT_STOP_CLONE>>;
+declare const PATTERN_FILL_CLONE: ClonePlan<PatternFill>;
+/** The proof that {@link PATTERN_FILL_CLONE} names every field of a pattern fill. */
+export type EveryPatternFillFieldIsCloned = AssertNever<Exclude<keyof Required<PatternFill>, keyof typeof PATTERN_FILL_CLONE>>;
+declare const GRADIENT_FILL_CLONE: ClonePlan<GradientFill>;
+/** The proof that {@link GRADIENT_FILL_CLONE} names every field of a gradient fill. */
+export type EveryGradientFillFieldIsCloned = AssertNever<Exclude<keyof Required<GradientFill>, keyof typeof GRADIENT_FILL_CLONE>>;
+/** A defensive deep copy of a fill, whichever of the two shapes it is. The union is dispatched on
+ * `type` because the two halves share no field beyond it, so one plan could not describe both. */
+export declare function cloneFill(fill: Fill): Fill;
 /**
  * Line styles a cell border edge can take, as OOXML's `ST_BorderStyle` enumerates them.
  * `none` is the absence of an edge and is expressed by omitting the edge, not by this value.
@@ -106,6 +143,14 @@ export interface Border {
     readonly diagonalUp?: boolean;
     readonly diagonalDown?: boolean;
 }
+declare const BORDER_EDGE_CLONE: ClonePlan<BorderEdge>;
+/** The proof that {@link BORDER_EDGE_CLONE} names every field of a border edge. */
+export type EveryBorderEdgeFieldIsCloned = AssertNever<Exclude<keyof Required<BorderEdge>, keyof typeof BORDER_EDGE_CLONE>>;
+declare const BORDER_CLONE: ClonePlan<Border>;
+/** The proof that {@link BORDER_CLONE} names every side of a border. */
+export type EveryBorderFieldIsCloned = AssertNever<Exclude<keyof Required<Border>, keyof typeof BORDER_CLONE>>;
+/** A defensive deep copy of a border, each present edge and its colour included. */
+export declare function cloneBorder(border: Border): Border;
 /** Vertical alignment of a font relative to the baseline (super/subscript). */
 export type FontVerticalAlignment = 'superscript' | 'subscript';
 /** Narrow a raw `<vertAlign val>` token to a known {@link FontVerticalAlignment}. */
@@ -133,6 +178,11 @@ export interface Font {
     readonly outline?: boolean;
     readonly vertAlign?: FontVerticalAlignment;
 }
+declare const FONT_CLONE: ClonePlan<Font>;
+/** The proof that {@link FONT_CLONE} names every facet of a font. */
+export type EveryFontFieldIsCloned = AssertNever<Exclude<keyof Required<Font>, keyof typeof FONT_CLONE>>;
+/** A defensive deep copy of a font, its nested colour included. */
+export declare function cloneFont(font: Font): Font;
 /** How a cell's content sits horizontally within its bounds, as OOXML's `ST_HorizontalAlignment`
  *  enumerates it. `general` is the type-dependent default (text left, numbers right) and reads
  *  back as no explicit horizontal alignment. */
@@ -166,7 +216,11 @@ export interface Alignment {
  * Format-blind on purpose. `Alignment` is a core type and the layering gate forbids core importing a
  * serialisation, so the table states what a facet *is* and each codec supplies the reading and the
  * writing off the `kind`. That is where {@link SHEET_PROTECTION_FLAGS} sits and how it is consumed,
- * and it is the shape the BIFF12 codec would want if alignment ever reaches it.
+ * and it is the shape the BIFF12 codec drives off too: `io/xlsb/read-styles.ts` walks this list and
+ * looks each facet up in a `Record` keyed by {@link Alignment}, so the bit layout stays a BIFF12 fact
+ * in the BIFF12 codec while the *set* of facets is decided here, once, for both. (That sentence used
+ * to read "if alignment ever reaches it". Alignment had reached it; the comment had not noticed, and
+ * the binary reader was restating all seven facets and their default-omission rules by hand.)
  *
  * The OOXML attribute name is the model key for all seven facets, so it is not restated here: a
  * second list that is always identical is a second list to keep in step. A future facet whose
@@ -234,6 +288,32 @@ export interface CellStyle {
 }
 /** The names of the {@link CellStyle} facets, for helpers that copy the tuple facet-by-facet. */
 export declare const CELL_STYLE_FACETS: (keyof CellStyle)[];
+/**
+ * Everything a cell's *formatting* is, which is the six {@link CellStyle} facets plus two that only a
+ * cell can carry: the quote-prefix flag and the link to a named cell style.
+ *
+ * The two extras are on the cell's `xf` record exactly as the six are, and are written and read back
+ * exactly as the six are, but they sat outside the tuple, so every copy path driven by the tuple
+ * dropped them: a splice, a `duplicateRow`, or a `dst.model = src.model` turned a leading-apostrophe
+ * text cell back into an unprefixed one. That is the merge-loss the tuple exists to make impossible,
+ * so they join it. Callers that mean "the six shared facets" (a column default, a named style, a
+ * `<dxf>`) still say {@link CellStyle}; callers copying a *cell* say this.
+ */
+export type CellContent = CellStyle & {
+    quotePrefix?: boolean | undefined;
+    [NAMED_STYLE_ID]?: number | undefined;
+};
+/**
+ * The names of every {@link CellContent} facet, the six shared ones first. Helpers that copy a cell's
+ * whole formatting drive off this, so a facet added to either half reaches all of them at once.
+ */
+export declare const CELL_CONTENT_FACETS: (keyof CellContent)[];
+/**
+ * Copy every present facet of a cell's formatting from `source` onto `target`, leaving facets
+ * `source` omits untouched: {@link assignStyleFacets} widened to the two cell-only facets. This is
+ * what a copy of a *cell* uses, so no structural edit can drop one.
+ */
+export declare function assignContentFacets(target: CellContent, source: Readonly<CellContent>): void;
 /**
  * Copy each present facet of `source` onto `target`, leaving facets `source` omits untouched: the
  * plain-record counterpart to a cell's `applyCellStyle`, for the {@link CellStyle}-shaped targets a
@@ -249,69 +329,4 @@ export declare function assignStyleFacets(target: CellStyle, source: Readonly<Ce
  * the tuple reaches a `<col>` style without anyone remembering to widen a literal.
  */
 export declare function pickStyleFacets(source: Readonly<CellStyle>): CellStyle;
-/**
- * A named cell style: the OOXML `cellStyleXfs`/`cellStyles` layer. A spreadsheet applies a built-in
- * or custom style (e.g. "Normal", "Accent1") whose visual facets live in this shared, named layer
- * rather than on each cell's direct format; a cell links to it and inherits any facet the direct
- * format leaves unset. The facets are a cell's own (see {@link CellStyle}); `name` is the style's
- * display name and `builtinId` its Excel gallery index when it is a built-in style.
- */
-export type NamedCellStyle = Readonly<CellStyle> & {
-    readonly name?: string;
-    readonly builtinId?: number;
-};
-/**
- * A differential style (OOXML CT_Dxf): formatting laid *over* whatever a cell already carries. Only
- * the facets present override; the rest of the cell's own style shows through. It carries the subset
- * of the cell-style facets (see {@link CellStyle}) a `<dxf>` can express: font, number format, fill,
- * and border.
- *
- * Differential styles live in one workbook-level table (`<dxfs>`) that several features index into:
- * a conditional-formatting rule's highlight format, and a table style's per-element formatting
- * (`<tableStyleElement dxfId="…">`). They are interned and shared, so two features asking for the
- * same formatting land on one entry.
- *
- * Not every facet reaches every consumer. As a **table style element**, Excel applies only the font,
- * fill, and border: its own object model exposes `Font`, `Interior`, and `Borders` on a table style
- * element and nothing for a number format, so a `numFmt` set here is carried faithfully through a
- * round-trip but has no visible effect. The type is left whole rather than split, because the same
- * value is legitimately reused across both consumers and narrowing it would only move the surprise.
- */
-export type DifferentialStyle = Pick<CellStyle, 'font' | 'numFmt' | 'fill' | 'border'>;
-/**
- * The `<tableStyles>` block of a styles part: the custom table/pivot style definitions a file
- * declares, and the two gallery names it nominates as the default for a new table and a new pivot.
- *
- * Each entry of {@link styles} is one `<tableStyle>…</tableStyle>` fragment kept verbatim, for the
- * same reason a `<dxf>` is: a `tableStyleElement`'s `dxfId` indexes the differential-style table,
- * which the writer re-emits **at its original indices**, so the references stay valid without
- * reparsing anything. That index-stability is load-bearing: renumbering the dxf table would
- * silently re-point every preserved table style at a different format.
- *
- * The two default names are ordinary strings, not fragments: they are re-escaped on write, so they
- * are held decoded.
- */
-export interface TableStyleTable {
-    readonly styles: readonly string[];
-    readonly defaultTableStyle?: string | undefined;
-    readonly defaultPivotStyle?: string | undefined;
-    /**
-     * The namespace prefixes the verbatim {@link styles} fragments use, mapped to their URI and to
-     * whether the source marked the prefix ignorable (`mc:Ignorable`).
-     *
-     * Carrying a fragment verbatim carries its *prefixes* too. Excel stamps a revision id
-     * (`xr9:uid="{…}"`) on every `<tableStyle>` it writes, so a fragment re-emitted under a
-     * `<styleSheet>` that declares only the default namespace is not namespace-well-formed, and no
-     * consumer can parse the part at all, which is a far louder failure than the dropped table style
-     * this preservation exists to prevent. The writer re-declares each prefix on `<styleSheet>` and
-     * re-states the ignorable ones, exactly as the source did.
-     */
-    readonly namespaces?: readonly TableStyleNamespace[];
-}
-/** One namespace declaration a preserved `<tableStyle>` fragment depends on. */
-export interface TableStyleNamespace {
-    readonly prefix: string;
-    readonly uri: string;
-    /** Whether the source listed this prefix in the stylesheet's `mc:Ignorable`. */
-    readonly ignorable: boolean;
-}
+export {};