@shbernal/ts-xlsx 1.3.1 → 2.1.0

package/dist/core/preserved.d.ts

@@ -2,7 +2,7 @@
  * One outbound relationship of a {@link PreservedPart}: the id it carries inside its own rels part,
  * the relationship Type URI, and its target. An internal relationship's `targetPath` is the resolved
  * package path of the part it points at (the writer re-numbers and rewires it); an `external`
- * relationship's `targetPath` is the raw `Target` verbatim (a linked workbook's path or URL) — it is
+ * relationship's `targetPath` is the raw `Target` verbatim (a linked workbook's path or URL). It is
  * outside the package, so it is emitted unchanged with `TargetMode="External"` and never remapped.
  * Preserving external relationships is what keeps an `externalLink` part's pointer to its source
  * workbook alive, so a round-trip does not orphan the `[n]` external references formulas resolve through.
@@ -26,7 +26,7 @@ export interface PreservedPart {
     readonly rels: readonly PreservedRelationship[];
 }
 /**
- * A worksheet-level reference to package content the model does not model — preserved verbatim across
+ * A worksheet-level reference to package content the model does not model, preserved verbatim across
  * a round-trip instead of being silently dropped. `element` is the worksheet child that wires the
  * reference (`<drawing>` for a vector-shape drawing, `<legacyDrawingHF>` for a header/footer image),
  * or `undefined` when the sheet wires it by relationship alone (a pivot table or slicer Excel
@@ -43,7 +43,7 @@ export interface PreservedWorksheetReference {
 }
 /**
  * A package-root reference to content the model does not model, wired from the package's own
- * `_rels/.rels` rather than the workbook part's rels — the ribbon-customisation parts
+ * `_rels/.rels` rather than the workbook part's rels: the ribbon-customisation parts
  * (`customUI/customUI14.xml`), custom document properties (`docProps/custom.xml`), a thumbnail, and
  * anything else hung off the root. The writer regenerates the root rels for the parts it models
  * (workbook, core/app properties), so these would be dropped unless captured here and re-declared.

package/dist/core/protection.d.ts

@@ -33,7 +33,7 @@ export interface SheetProtectionOptions extends SheetProtectionFlags {
 }
 /**
  * A password-derived credential, in OOXML's agile form: the hash algorithm, the salted
- * iterated hash of the password, the salt, and the iteration count — everything a consumer
+ * iterated hash of the password, the salt, and the iteration count: everything a consumer
  * needs to verify a supplied password without the password ever being stored.
  */
 export interface SheetProtectionCredential {
@@ -50,8 +50,8 @@ export interface SheetProtection {
 /**
  * The OOXML encoding table for the protection flags: each `<sheetProtection>` attribute paired
  * with whether that operation is *forbidden by default* once a sheet is protected. Both directions
- * key off this one list — the writer turns an author allow-flag into an attribute (omitting values
- * equal to the default), the reader turns an attribute back into an allow-flag — so serialization
+ * key off this one list. The writer turns an author allow-flag into an attribute (omitting values
+ * equal to the default) and the reader turns an attribute back into an allow-flag, so serialization
  * and deserialization can never fall out of step. Most editing operations default to forbidden
  * under protection; selecting cells and the object/scenario operations default to permitted.
  */
@@ -61,7 +61,10 @@ export declare const SHEET_PROTECTION_FLAGS: readonly {
 }[];
 /**
  * Derive a fresh {@link SheetProtectionCredential} for a password. Each call generates a new
- * random salt, so protecting two sheets with the same password yields different credentials —
+ * random salt, so protecting two sheets with the same password yields different credentials:
  * the salt is real randomness, not a stub.
+ *
+ * The spin loop is the cost of the scheme rather than of this implementation: Excel's default
+ * 100000 iterations is 100000 chained SHA-512 digests, and no shortcut through them exists.
  */
 export declare function deriveCredential(password: string, spinCount?: number): SheetProtectionCredential;

package/dist/core/protection.js

@@ -1,4 +1,5 @@
-import { createHash, randomBytes } from 'node:crypto';
+import { concat, toBase64 } from '../bytes.js';
+import { sha512 } from '../sha512.js';
 export const SHEET_PROTECTION_FLAGS = [
     { key: 'formatCells', defaultForbidden: true },
     { key: 'formatColumns', defaultForbidden: true },
@@ -17,26 +18,31 @@ export const SHEET_PROTECTION_FLAGS = [
     { key: 'selectUnlockedCells', defaultForbidden: false },
 ];
 const ALGORITHM_NAME = 'SHA-512';
-const HASH = 'sha512';
 const DEFAULT_SPIN_COUNT = 100000;
 const SALT_BYTES = 16;
 export function deriveCredential(password, spinCount = DEFAULT_SPIN_COUNT) {
-    const salt = randomBytes(SALT_BYTES);
-    const secret = Buffer.from(password, 'utf16le');
-    let hash = createHash(HASH)
-        .update(Buffer.concat([salt, secret]))
-        .digest();
-    const iteration = Buffer.alloc(4);
+    const salt = crypto.getRandomValues(new Uint8Array(SALT_BYTES));
+    let hash = sha512(concat([salt, utf16le(password)]));
+    const spun = new Uint8Array(hash.length + 4);
+    const counter = new DataView(spun.buffer, hash.length, 4);
     for (let i = 0; i < spinCount; i++) {
-        iteration.writeUInt32LE(i, 0);
-        hash = createHash(HASH)
-            .update(Buffer.concat([hash, iteration]))
-            .digest();
+        spun.set(hash, 0);
+        counter.setUint32(0, i, true);
+        hash = sha512(spun);
     }
     return {
         algorithmName: ALGORITHM_NAME,
-        hashValue: hash.toString('base64'),
-        saltValue: salt.toString('base64'),
+        hashValue: toBase64(hash),
+        saltValue: toBase64(salt),
         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.d.ts

@@ -1,18 +1,20 @@
+import { type GridRect } from './address.ts';
 import { type Cell } from './cell.ts';
 import { type Alignment, type Border, type CellStyle, type Fill, type Font, type Protection } from './style.ts';
 import type { Worksheet } from './worksheet.ts';
 /**
  * A rectangular block of a worksheet's cells: `sheet.getRange('B2:D5')`.
  *
- * Cheap and stateless — constructing one creates no cells and does not extend the used range.
+ * Cheap and stateless: constructing one creates no cells and does not extend the used range.
  * {@link addresses} walks the block without materialising anything; {@link cells} reports only what
  * already exists.
  *
  * Bounds are **inclusive first/last**, never start-and-count. That is the convention every
  * range-shaped accessor in this library follows, so the three axes cannot disagree about what a
- * pair of numbers means.
+ * pair of numbers means; the handle is declared to satisfy {@link GridRect}, which is that
+ * convention written down once.
  */
-export declare class Range {
+export declare class Range implements GridRect {
     #private;
     /** 1-based row of the block's top edge. Fixed for this handle's lifetime. */
     readonly top: number;
@@ -23,7 +25,7 @@ export declare class Range {
     /** 1-based column of the block's right edge, inclusive. */
     readonly right: number;
     /**
-     * Build a handle from inclusive corners, in any order — `(5, 4, 2, 2)` and `(2, 2, 5, 4)` name the
+     * Build a handle from inclusive corners, in any order: `(5, 4, 2, 2)` and `(2, 2, 5, 4)` name the
      * same block, exactly as `D5:B2` and `B2:D5` do. Prefer {@link Worksheet.getRange}.
      *
      * @throws {RangeError} if a corner is not a positive integer or falls outside the sheet's bounds.
@@ -31,30 +33,30 @@ export declare class Range {
     constructor(sheet: Worksheet, top: number, left: number, bottom: number, right: number);
     /** The worksheet this block belongs to. */
     get sheet(): Worksheet;
-    /** Canonical `tl:br` A1 form — `"B2:D5"`. A one-cell block still reads as `"B2:B2"`. */
+    /** Canonical `tl:br` A1 form, `"B2:D5"`. A one-cell block still reads as `"B2:B2"`. */
     get address(): string;
     /** Rows spanned, inclusive of both edges. */
     get rowCount(): number;
     /** Columns spanned, inclusive of both edges. */
     get columnCount(): number;
-    /** Cells the block covers — `rowCount * columnCount`, whether or not they exist yet. */
+    /** Cells the block covers: `rowCount * columnCount`, whether or not they exist yet. */
     get cellCount(): number;
     /** Whether a 1-based position falls inside the block. */
     contains(row: number, col: number): boolean;
     /**
      * Every address the block covers, row-major (`B2`, `C2`, `D2`, `B3`, …). Materialises nothing, so
-     * this is the cheap way to walk a large block — and, being a generator, it can be abandoned
+     * this is the cheap way to walk a large block, and, being a generator, it can be abandoned
      * part-way without having built the whole list.
      */
     addresses(): IterableIterator<string>;
     /**
      * The block's **materialised** cells, row-major. Sparse: a position nothing has ever written to is
      * simply absent, which is what distinguishes "never written" from a cell holding `null`. Reading
-     * this creates nothing — mirroring {@link Column.cells}.
+     * this creates nothing, mirroring {@link Column.cells}.
      */
     get cells(): readonly Cell[];
     /**
-     * The block's style, facet by facet — the counterpart of {@link Cell.style} over a rectangle, with
+     * The block's style, facet by facet: the counterpart of {@link Cell.style} over a rectangle, with
      * the same semantics in both directions.
      *
      * **Reading** reports a facet only when *every* position in the block carries a structurally
@@ -62,13 +64,13 @@ export declare class Range {
      * through this handle therefore reads back what was written; a block whose cells disagree says so
      * rather than picking a corner's answer and passing it off as the whole.
      *
-     * **Writing** lays each facet the payload names onto every cell, leaving facets it omits untouched
-     * — exactly what `cell.style = {...}` does, so this composes with prior styling instead of clearing
-     * it. Use {@link clearStyle} first for a wholesale replace.
+     * **Writing** lays each facet the payload names onto every cell, leaving facets it omits
+     * untouched, exactly what `cell.style = {...}` does, so this composes with prior styling instead
+     * of clearing it. Use {@link clearStyle} first for a wholesale replace.
      *
      * Writing **materialises** every position in the block, because a styled-but-valueless cell is the
      * only way an empty cell renders with a fill: skipping the holes would leave gaps in a header band.
-     * The cost is bounded by construction — a range is always a bounded rectangle, and whole-axis
+     * The cost is bounded by construction: a range is always a bounded rectangle, and whole-axis
      * styling belongs to {@link Worksheet.getColumn}/{@link Worksheet.getRow} instead. {@link cellCount}
      * is the exact number of cells a write will create.
      */
@@ -77,7 +79,7 @@ export declare class Range {
     /**
      * Strip every style facet from every cell in the block, leaving values untouched. Assigning
      * {@link style} composes, so this is how a wholesale replace is said: `clearStyle()` then assign.
-     * Materialises nothing — a cell that does not exist carries no style to clear.
+     * Materialises nothing: a cell that does not exist carries no style to clear.
      */
     clearStyle(): void;
     /** Fill applied to every cell in the block; `undefined` when they do not all agree. */

package/dist/core/range.js

@@ -154,22 +154,22 @@ function facetKey(value) {
 }
 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`);
+        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}`);
+        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(`"${reference}" names worksheet "${sheetName}", not "${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(`"${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(`"${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.d.ts

@@ -1,14 +1,21 @@
 import { Cell } from './cell.ts';
 import type { CellValue } from './value.ts';
 import type { ColumnProperties, RowInput } from './worksheet.ts';
+/**
+ * Resolve a positional array of values to the (1-based index, value) placements it names: the first
+ * value lands at 1, and a hole or an explicit `undefined` places nothing, leaving that line
+ * untouched. The index is a column on the row axis and a row on the column axis; the reading is the
+ * same either way.
+ */
+export declare function positionalPlacements(values: readonly (CellValue | undefined)[]): Array<[number, CellValue]>;
 /**
  * Resolve a `RowInput` to the (1-based column, value) placements it names. A positional array maps
  * each value to its column from A, skipping a hole or an explicit `undefined` so that column is left
  * untouched; a keyed object maps each value under the column carrying the matching key.
  *
  * `Array.isArray`, not `instanceof Array`: a row built in another realm (a vm context, a browser
- * iframe) is still an array but fails the identity check, and would then be walked as a keyed object —
- * placing nothing.
+ * iframe) is still an array but fails the identity check, and would then be walked as a keyed
+ * object, placing nothing.
  */
 export declare function rowPlacements(values: RowInput, columns: ReadonlyMap<number, ColumnProperties>): Array<[number, CellValue]>;
 /**
@@ -16,9 +23,3 @@ export declare function rowPlacements(values: RowInput, columns: ReadonlyMap<num
  * keyed by column. The grid-edit machinery then splices this map into place.
  */
 export declare function buildRowCells(number: number, values: RowInput, columns: ReadonlyMap<number, ColumnProperties>): Map<number, Cell>;
-/**
- * The 1-based index of the column carrying `key` (see {@link ColumnProperties.key}).
- *
- * @throws {AuthoringError} if no column declares that key.
- */
-export declare function columnIndexByKey(columns: ReadonlyMap<number, ColumnProperties>, key: string): number;

package/dist/core/row-input.js

@@ -1,14 +1,16 @@
 import { AuthoringError } from '../errors.js';
 import { Cell } from './cell.js';
+export function positionalPlacements(values) {
+    const placements = [];
+    values.forEach((value, index) => {
+        if (value !== undefined)
+            placements.push([index + 1, value]);
+    });
+    return placements;
+}
 export function rowPlacements(values, columns) {
-    if (Array.isArray(values)) {
-        const placements = [];
-        values.forEach((value, index) => {
-            if (value !== undefined)
-                placements.push([index + 1, value]);
-        });
-        return placements;
-    }
+    if (Array.isArray(values))
+        return positionalPlacements(values);
     return Object.entries(values).map(([key, value]) => [columnIndexByKey(columns, key), value]);
 }
 export function buildRowCells(number, values, columns) {
@@ -20,10 +22,10 @@ export function buildRowCells(number, values, columns) {
     }
     return row;
 }
-export function columnIndexByKey(columns, key) {
+function columnIndexByKey(columns, key) {
     for (const [index, properties] of columns) {
         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 ${JSON.stringify(key)}: set getColumn(n).key first`);
 }

package/dist/core/row.d.ts

@@ -1,4 +1,5 @@
 import type { Cell } from './cell.ts';
+import { type AssertNever } from './internal.ts';
 import type { Fill } from './style.ts';
 import type { CellValue } from './value.ts';
 import type { RowProperties, Worksheet } from './worksheet.ts';
@@ -6,10 +7,10 @@ export declare class Row {
     #private;
     /** 1-based row number. Fixed for this handle's lifetime. */
     readonly number: number;
-    /** @throws {RangeError} if the number is not a positive integer. */
+    /** @throws {RangeError} unless the number is an integer within Excel's row grid (1..1048576). */
     constructor(sheet: Worksheet, number: number);
     /**
-     * The row's format record if it has one, else `undefined` — a read that never fabricates, so a
+     * The row's format record if it has one, else `undefined`: a read that never fabricates, so a
      * serializer can ask every row it visits whether there are attributes to emit without giving each
      * one an empty record. Read-only on purpose: {@link height} and its siblings are how a row is
      * formatted, and they create the record on first write.
@@ -21,7 +22,7 @@ export declare class Row {
      * Not bounded here, deliberately: {@link MAX_ROW_HEIGHT} is what Excel accepts *being set*, but
      * the schema puts no ceiling on `ht` and this setter is also how the reader loads a foreign
      * file, so refusing a taller row would mean refusing a file Excel opens clean. Check against the
-     * constant when authoring — Excel silently clamps a taller row on read, so a height above it is
+     * constant when authoring: Excel silently clamps a taller row on read, so a height above it is
      * one you state and do not get.
      */
     get height(): number | undefined;
@@ -51,7 +52,7 @@ export declare class Row {
     getCell(column: number | string): Cell;
     /**
      * The row's materialised cells in ascending column order. Sparse: a column never written to has
-     * no cell here, and the array is a fresh snapshot of *which* cells exist — the cells themselves
+     * no cell here, and the array is a fresh snapshot of *which* cells exist; the cells themselves
      * are the live ones.
      */
     get cells(): readonly Cell[];
@@ -60,16 +61,15 @@ export declare class Row {
      * a column with no cell is a hole, which is what distinguishes "never written" from a cell
      * holding `null`.
      *
-     * Assigning places each value it names and leaves every other column untouched — a hole or an
+     * Assigning places each value it names and leaves every other column untouched: a hole or an
      * explicit `undefined` skips that column, and a shorter array does not clear the tail. These are
      * {@link Worksheet.addRow}'s rules, deliberately: `values` is that same row shape addressed by
-     * number rather than appended. To *replace* a row, including clearing what it held, splice it —
+     * number rather than appended. To *replace* a row, including clearing what it held, splice it:
      * `sheet.spliceRows(n, 1, values)`.
      */
     get values(): (CellValue | undefined)[];
     set values(values: (CellValue | undefined)[]);
 }
-type AssertNever<T extends never> = T;
 /**
  * Compile-time proof that {@link Row} mirrors every {@link RowProperties} field. A field added to
  * the record without an accessor here resolves this to that field's name, which does not satisfy
@@ -78,4 +78,3 @@ type AssertNever<T extends never> = T;
  * would simply never mention it.
  */
 export type EveryRowPropertyIsMirrored = AssertNever<Exclude<keyof RowProperties, keyof Row & keyof RowProperties>>;
-export {};

package/dist/core/row.js

@@ -1,12 +1,10 @@
-import { columnToNumber, encodeAddress } from './address.js';
+import { assertRowInBounds, columnToNumber, encodeAddress } from './address.js';
 import { INTERNAL } from './internal.js';
 export class Row {
     #sheet;
     number;
     constructor(sheet, number) {
-        if (!Number.isInteger(number) || number < 1) {
-            throw new RangeError(`row ${number} is out of bounds — rows start at 1`);
-        }
+        assertRowInBounds(number);
         this.#sheet = sheet;
         this.number = number;
     }

package/dist/core/style.d.ts

@@ -14,6 +14,26 @@ export interface Color {
      *  automatic placeholder `indexed="64"`; the visible colour lives on `fgColor`. */
     readonly indexed?: number;
 }
+/**
+ * Parse a colour written in any of the shapes the API accepts into the bare 8-hex ARGB OOXML wants,
+ * or `undefined` if it is not one of them.
+ *
+ * Two conveniences are accepted, and nothing else: a leading `#` is a CSS habit and is stripped
+ * (`'#FFBFBFBF'` → `'FFBFBFBF'`), and a 6-hex RGB is promoted with a fully-opaque alpha (`'00FF00'` →
+ * `'FF00FF00'`), the common case of a colour written without its alpha channel. Casing is preserved,
+ * so a foreign file's lowercase value round-trips as it arrived.
+ *
+ * This states the grammar once for both directions. What a malformed value *means* differs by
+ * direction and is decided by the caller: on read it is foreign data and resolves to nothing, on
+ * write it is a caller's bug and throws (see `normalizeArgb` in `io/xlsx/color-xml.ts`). Neither can
+ * be a silently half-parsed value, because Excel does not report a malformed `rgb` at all; it
+ * renders flat black.
+ *
+ * `normalizeThemeColor` in `core/theme.ts` asks a similar question and stays separate: a theme
+ * slot is `<a:srgbClr val>`, which DrawingML gives no alpha channel, so the two differ in exactly the
+ * thing this one exists to add.
+ */
+export declare function parseArgb(value: string): string | undefined;
 /**
  * Fill pattern kinds, as OOXML's `ST_PatternType` enumerates them. `none` is the
  * absence of a fill; `solid` paints the whole cell with the foreground colour (the
@@ -24,7 +44,7 @@ export type FillPatternType = 'none' | 'solid' | 'gray125' | 'darkGray' | 'mediu
 export declare function isFillPatternType(value: string): value is FillPatternType;
 /**
  * A pattern fill. For a `solid` fill the visible colour is the pattern *foreground*
- * (`fgColor`) — OOXML's counter-intuitive rule — while `bgColor` is the automatic
+ * (`fgColor`), OOXML's counter-intuitive rule, while `bgColor` is the automatic
  * indexed placeholder.
  */
 export interface PatternFill {
@@ -89,13 +109,13 @@ export interface Border {
 export type FontVerticalAlignment = 'superscript' | 'subscript';
 /** Narrow a raw `<vertAlign val>` token to a known {@link FontVerticalAlignment}. */
 export declare function isFontVerticalAlignment(value: string): value is FontVerticalAlignment;
-/** The theme-font role a `<scheme val>` names — `"minor"`/`"major"` bind the font to whichever
+/** The theme-font role a `<scheme val>` names: `"minor"`/`"major"` bind the font to whichever
  * face the workbook theme assigns that role, `"none"` leaves it a literal, unbound face. */
 export type FontScheme = 'minor' | 'major' | 'none';
 /** Narrow a raw `<scheme val>` token to a known {@link FontScheme}. */
 export declare function isFontScheme(value: string): value is FontScheme;
 /** A font, as it applies to a cell or a single rich-text run. Every facet is optional and
- * independent, like {@link Border}/{@link Alignment}/{@link Protection} — a font sets only the
+ * independent, like {@link Border}/{@link Alignment}/{@link Protection}: a font sets only the
  * facets it overrides (Excel's own default font backs the rest), so no consumer ever holds every
  * field populated at once. */
 export interface Font {
@@ -125,7 +145,7 @@ export type VerticalAlignment = 'top' | 'center' | 'bottom' | 'justify' | 'distr
 export declare function isVerticalAlignment(value: string): value is VerticalAlignment;
 /**
  * A cell's alignment. Every facet is optional and independent; an absent facet means the cell
- * takes Excel's default for it. The boolean flags default to off — a cell that never enabled
+ * takes Excel's default for it. The boolean flags default to off, so a cell that never enabled
  * `wrapText`/`shrinkToFit` must never read back with them on. `textRotation` is in degrees
  * (0–180, where 91–180 encodes -1° to -90°); `indent` is a non-negative indent level.
  */
@@ -139,7 +159,7 @@ export interface Alignment {
     readonly readingOrder?: number;
 }
 /**
- * A cell's protection state, enforced only when the worksheet itself is protected — the flags
+ * A cell's protection state, enforced only when the worksheet itself is protected. The flags
  * do nothing on an unprotected sheet. `locked` defaults to TRUE in OOXML (every cell is locked
  * unless told otherwise), so the meaningful, information-carrying state is an explicitly
  * *unlocked* cell (`locked: false`); marking a cell locked merely restates the default and
@@ -151,14 +171,14 @@ export interface Protection {
     readonly hidden?: boolean;
 }
 /**
- * The six direct-format facets a cell can carry — its fill, number format, font, border, alignment,
+ * The six direct-format facets a cell can carry: its fill, number format, font, border, alignment,
  * and protection. Every facet is optional and independent: a cell sets only the facets it overrides
  * and inherits the rest. This one tuple is the unit of style throughout the library, so the
- * interfaces that carry a cell's formatting compose it rather than re-listing the fields — a column,
+ * interfaces that carry a cell's formatting compose it rather than re-listing the fields: a column,
  * table column, or named style whose facets *default* the cells that leave them unset (see
  * {@link ColumnProperties}, {@link NamedCellStyle}), and a cell's own resolved format. Because they
  * share this type, "add a facet" is a single edit here and the compiler enforces that no read/write
- * path silently drops one — the round-trip symmetry the merge-loss contract depends on.
+ * path silently drops one, the round-trip symmetry the merge-loss contract depends on.
  */
 export interface CellStyle {
     fill?: Fill | undefined;
@@ -171,15 +191,22 @@ 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)[];
 /**
- * Copy each present facet of `source` onto `target`, leaving facets `source` omits untouched — the
+ * 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
  * `Cell`'s setters don't reach (a column's cell-defaults, a named style being assembled on read).
  * Driven by {@link CELL_STYLE_FACETS}, so a facet added to the tuple reaches these paths the moment
- * it joins — the same single-point-of-change the cell path gets.
+ * it joins, the same single-point-of-change the cell path gets.
  */
 export declare function assignStyleFacets(target: CellStyle, source: Readonly<CellStyle>): void;
 /**
- * A named cell style — the OOXML `cellStyleXfs`/`cellStyles` layer. A spreadsheet applies a built-in
+ * The {@link CellStyle} facets of `source` as a plain tuple of their own, for a source that carries
+ * more than the facets (a column's properties also hold width, hidden and outline state). The
+ * projection counterpart to {@link assignStyleFacets}, driven by the same list, so a facet added to
+ * 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
@@ -192,7 +219,7 @@ export type NamedCellStyle = Readonly<CellStyle> & {
 /**
  * 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,
+ * 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:
@@ -214,7 +241,7 @@ export type DifferentialStyle = Pick<CellStyle, 'font' | 'numFmt' | 'fill' | 'bo
  * 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
+ * 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
@@ -230,7 +257,7 @@ export interface TableStyleTable {
      *
      * 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 — no
+     * `<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.