@shbernal/ts-xlsx 2.0.0 → 2.1.0

package/dist/core/data-validation.js

@@ -1,3 +1,37 @@
+const DATA_VALIDATION_TYPES = {
+    none: true,
+    list: true,
+    whole: true,
+    decimal: true,
+    date: true,
+    time: true,
+    textLength: true,
+    custom: true,
+};
+export function isDataValidationType(value) {
+    return Object.hasOwn(DATA_VALIDATION_TYPES, value);
+}
+const DATA_VALIDATION_OPERATORS = {
+    between: true,
+    notBetween: true,
+    equal: true,
+    notEqual: true,
+    greaterThan: true,
+    lessThan: true,
+    greaterThanOrEqual: true,
+    lessThanOrEqual: true,
+};
+export function isDataValidationOperator(value) {
+    return Object.hasOwn(DATA_VALIDATION_OPERATORS, value);
+}
+const DATA_VALIDATION_ERROR_STYLES = {
+    stop: true,
+    warning: true,
+    information: true,
+};
+export function isDataValidationErrorStyle(value) {
+    return Object.hasOwn(DATA_VALIDATION_ERROR_STYLES, value);
+}
 export function cloneDataValidation(rule) {
     return {
         ...rule,

package/dist/core/grid-edits.d.ts

@@ -1,9 +1,21 @@
+import { type AutoFilter } from './autofilter.ts';
 import { Cell } from './cell.ts';
+import type { ConditionalFormattingOverlay } from './conditional-formatting-overlay.ts';
+import type { DataValidationOverlay } from './data-validation-overlay.ts';
 import { type AnchoredImage } from './image.ts';
 import type { MergeRect } from './merge.ts';
 import type { Table } from './table.ts';
 import { type CellValue } from './value.ts';
+import type { WorksheetComments } from './worksheet-comments.ts';
 import type { ColumnProperties, RowProperties } from './worksheet.ts';
+/**
+ * The sheet's autofilter, reached as a slot rather than held by reference like the containers beside
+ * it: it is a single replaceable value, and a splice that deletes every filtered line clears it.
+ */
+export interface AutoFilterSlot {
+    get(): AutoFilter | undefined;
+    set(next: AutoFilter | undefined): void;
+}
 interface GridStorage {
     readonly rows: Map<number, Map<number, Cell>>;
     readonly rowProperties: Map<number, RowProperties>;
@@ -12,6 +24,10 @@ interface GridStorage {
     readonly mergeRects: MergeRect[];
     readonly tables: Table[];
     readonly images: AnchoredImage[];
+    readonly dataValidations: DataValidationOverlay;
+    readonly conditionalFormattings: ConditionalFormattingOverlay;
+    readonly comments: WorksheetComments;
+    readonly autoFilter: AutoFilterSlot;
 }
 export declare class GridEdits {
     #private;

package/dist/core/grid-edits.js

@@ -1,11 +1,10 @@
 import { decodeRange, encodeAddress, tryDecodeCellRef } from './address.js';
+import { shiftAutoFilter } from './autofilter.js';
 import { Cell, copyCellContent } from './cell.js';
 import { replaceContents } from './containers.js';
+import { isDeletedSpan, shiftIndex } from './grid-shift.js';
 import { isOneCellAnchor } from './image.js';
 import { isSharedFormulaValue } from './value.js';
-function shiftIndex(v, start, count, delta) {
-    return v < start ? v : v >= start + count ? v + delta : start;
-}
 export class GridEdits {
     #rows;
     #rowProperties;
@@ -14,6 +13,10 @@ export class GridEdits {
     #mergeRects;
     #tables;
     #images;
+    #dataValidations;
+    #conditionalFormattings;
+    #comments;
+    #autoFilter;
     constructor(storage) {
         this.#rows = storage.rows;
         this.#rowProperties = storage.rowProperties;
@@ -22,6 +25,10 @@ export class GridEdits {
         this.#mergeRects = storage.mergeRects;
         this.#tables = storage.tables;
         this.#images = storage.images;
+        this.#dataValidations = storage.dataValidations;
+        this.#conditionalFormattings = storage.conditionalFormattings;
+        this.#comments = storage.comments;
+        this.#autoFilter = storage.autoFilter;
     }
     spliceRows(start, count, inserted) {
         const delta = inserted.length - count;
@@ -43,6 +50,7 @@ export class GridEdits {
         this.#shiftTables('row', start, count, delta);
         this.#shiftImages('row', start, count, delta);
         this.#reanchorSharedFormulas('row', start, count, delta);
+        this.#shiftRangeBoundOverlays('row', start, count, delta);
     }
     spliceColumns(start, count, inserts) {
         const delta = inserts.length - count;
@@ -74,6 +82,16 @@ export class GridEdits {
         this.#shiftTables('col', start, count, delta);
         this.#shiftImages('col', start, count, delta);
         this.#reanchorSharedFormulas('col', start, count, delta);
+        this.#shiftRangeBoundOverlays('col', start, count, delta);
+    }
+    #shiftRangeBoundOverlays(axis, start, count, delta) {
+        this.#dataValidations.shift(axis, start, count, delta);
+        this.#conditionalFormattings.shift(axis, start, count, delta);
+        this.#comments.shift(axis, start, count, delta);
+        const filter = this.#autoFilter.get();
+        if (filter !== undefined) {
+            this.#autoFilter.set(shiftAutoFilter(filter, axis, start, count, delta));
+        }
     }
     #relocateRow(cols, destRow) {
         const moved = new Map();
@@ -99,8 +117,8 @@ export class GridEdits {
                 if (master === undefined)
                     continue;
                 const anchored = axis === 'row'
-                    ? encodeAddress(master.col, shiftIndex(master.row, start, count, delta))
-                    : encodeAddress(shiftIndex(master.col, start, count, delta), master.row);
+                    ? encodeAddress(master.col, shiftIndex(master.row, start, count, delta, 'row'))
+                    : encodeAddress(shiftIndex(master.col, start, count, delta, 'col'), master.row);
                 if (anchored === value.sharedFormula)
                     continue;
                 const reanchored = { ...value, sharedFormula: anchored };
@@ -121,7 +139,7 @@ export class GridEdits {
             map.set(index, value);
     }
     #shiftMerges(axis, start, count, delta) {
-        const shift = (v) => shiftIndex(v, start, count, delta);
+        const shift = (v) => shiftIndex(v, start, count, delta, axis);
         const merges = [];
         const rects = [];
         for (const range of this.#merges) {
@@ -131,7 +149,7 @@ export class GridEdits {
                 continue;
             }
             const [lo, hi] = axis === 'row' ? [top, bottom] : [left, right];
-            if (lo >= start && hi < start + count)
+            if (isDeletedSpan(lo, hi, start, count))
                 continue;
             const rect = axis === 'row'
                 ? { top: shift(top), left, bottom: shift(bottom), right }
@@ -151,7 +169,7 @@ export class GridEdits {
     #shiftImages(axis, start, count, delta) {
         const shiftPoint = (point) => {
             const zeroBased = axis === 'row' ? point.row : point.col;
-            const shifted = shiftIndex(zeroBased + 1, start, count, delta) - 1;
+            const shifted = shiftIndex(zeroBased + 1, start, count, delta, axis) - 1;
             if (shifted === zeroBased)
                 return point;
             return axis === 'row' ? { ...point, row: shifted } : { ...point, col: shifted };

package/dist/core/grid-shift.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Where a 1-based coordinate on `axis` lands after `count` lines are deleted at `start` and the
+ * replacement lines shift what follows by `delta`: before the edit it stays put, at or after the
+ * edited span it shifts, and inside a deleted span it clamps to the cut line. The clamp is the best
+ * effort for a geometry straddling the cut; a caller that must instead *drop* what a delete swallowed
+ * whole tests {@link isDeletedSpan} first.
+ *
+ * A shift never leaves the grid: the result is clamped to the axis's last line, so a region already
+ * touching the bottom (or the right edge) keeps its edge there instead of naming a line the format
+ * has no room for. That shrinks such a region by what it could not move, which is the lesser of the
+ * two evils and is what Excel does to the same region on the same edit.
+ */
+export declare function shiftIndex(v: number, start: number, count: number, delta: number, axis: 'row' | 'col'): number;
+/**
+ * Whether the inclusive span `lo..hi` lies entirely within the `count` lines deleted at `start`: the
+ * test that separates "this moved" from "this is gone". A single coordinate is the degenerate span
+ * `lo === hi`.
+ */
+export declare function isDeletedSpan(lo: number, hi: number, start: number, count: number): boolean;

package/dist/core/grid-shift.js

@@ -0,0 +1,8 @@
+import { MAX_COLUMN, MAX_ROW } from './address.js';
+export function shiftIndex(v, start, count, delta, axis) {
+    const moved = v < start ? v : v >= start + count ? v + delta : start;
+    return Math.min(moved, axis === 'row' ? MAX_ROW : MAX_COLUMN);
+}
+export function isDeletedSpan(lo, hi, start, count) {
+    return lo >= start && hi < start + count;
+}

package/dist/core/image.d.ts

@@ -17,6 +17,8 @@ export declare const PX_TO_EMU = 9525;
  * them; `oneCell` moves but keeps its size; `absolute` is pinned to the page and does neither. Excel
  * defaults to `oneCell` when the attribute is omitted. */
 export type ImageEditAs = 'oneCell' | 'twoCell' | 'absolute';
+/** Narrow a raw `<xdr:twoCellAnchor editAs>` token to a known {@link ImageEditAs}. */
+export declare function isImageEditAs(value: string): value is ImageEditAs;
 /** A fixed image size in EMUs: the extent of a one-cell anchor, which pixel dimensions convert into
  * via {@link PX_TO_EMU}. */
 export interface Extent {

package/dist/core/image.js

@@ -1,4 +1,8 @@
 export const PX_TO_EMU = 9525;
+const IMAGE_EDIT_AS = { oneCell: true, twoCell: true, absolute: true };
+export function isImageEditAs(value) {
+    return Object.hasOwn(IMAGE_EDIT_AS, value);
+}
 export function isOneCellAnchor(anchor) {
     return 'ext' in anchor;
 }

package/dist/core/merge.d.ts

@@ -21,5 +21,16 @@ export declare function masterOf(rects: readonly MergeRect[], row: number, col:
 export declare function clearCoveredValues(rows: Map<number, Map<number, Cell>>, rect: MergeRect): void;
 /** Decode an OOXML `sqref` (one or more space-separated ranges) into containment rectangles. A whole
  * column or row leaves one axis unbounded, so its missing edges open to `Infinity` rather than
- * clamping: a cell anywhere down the column still resolves inside it. */
+ * clamping: a cell anywhere down the column still resolves inside it. An area that names no region
+ * that can exist contributes no rectangle, the reader's rule for every other foreign attribute. */
 export declare function decodeSqrefRects(sqref: string): MergeRect[];
+/**
+ * Re-anchor an OOXML `sqref` through a splice of `count` lines at `start` on `axis`, the inverse of
+ * {@link decodeSqrefRects}. Returns `undefined` when the splice deleted every area the `sqref` named:
+ * an empty `sqref` is not writable, so the entry holding it goes too.
+ *
+ * Each space-separated area shifts on its own, and one the splice does not move is returned as the
+ * *original text*. That matters for a file the library did not author: `B:B` and `B1:B1048576` decode
+ * identically, so a re-encode would rewrite a foreign spelling and cost the byte-clean round trip.
+ */
+export declare function shiftSqref(sqref: string, axis: 'row' | 'col', start: number, count: number, delta: number): string | undefined;

package/dist/core/merge.js

@@ -1,4 +1,5 @@
-import { decodeRange } from './address.js';
+import { encodeCornerRef, tryDecodeRange } from './address.js';
+import { isDeletedSpan, shiftIndex } from './grid-shift.js';
 export function masterOf(rects, row, col) {
     for (const rect of rects) {
         if (row >= rect.top && row <= rect.bottom && col >= rect.left && col <= rect.right) {
@@ -26,7 +27,10 @@ export function decodeSqrefRects(sqref) {
     for (const part of sqref.split(/\s+/)) {
         if (part === '')
             continue;
-        const { top, left, bottom, right } = decodeRange(part);
+        const decoded = tryDecodeRange(part);
+        if (decoded === undefined)
+            continue;
+        const { top, left, bottom, right } = decoded;
         rects.push({
             top: top ?? 1,
             left: left ?? 1,
@@ -36,3 +40,33 @@ export function decodeSqrefRects(sqref) {
     }
     return rects;
 }
+export function shiftSqref(sqref, axis, start, count, delta) {
+    const areas = [];
+    for (const area of sqref.split(/\s+/)) {
+        if (area === '')
+            continue;
+        const shifted = shiftSqrefArea(area, axis, start, count, delta);
+        if (shifted !== undefined)
+            areas.push(shifted);
+    }
+    return areas.length > 0 ? areas.join(' ') : undefined;
+}
+function shiftSqrefArea(area, axis, start, count, delta) {
+    const decoded = tryDecodeRange(area);
+    if (decoded === undefined)
+        return area;
+    const { top, left, bottom, right } = decoded;
+    const [lo, hi] = axis === 'row' ? [top, bottom] : [left, right];
+    if (lo === undefined || hi === undefined)
+        return area;
+    if (isDeletedSpan(lo, hi, start, count))
+        return undefined;
+    const movedLo = shiftIndex(lo, start, count, delta, axis);
+    const movedHi = shiftIndex(hi, start, count, delta, axis);
+    if (movedLo === lo && movedHi === hi)
+        return area;
+    const [tl, br] = axis === 'row'
+        ? [encodeCornerRef(left, movedLo), encodeCornerRef(right, movedHi)]
+        : [encodeCornerRef(movedLo, top), encodeCornerRef(movedHi, bottom)];
+    return area.includes(':') ? `${tl}:${br}` : tl;
+}

package/dist/core/page-setup.d.ts

@@ -1,3 +1,17 @@
+/**
+ * Paper orientation, as `<pageSetup orientation>` carries it.
+ *
+ * `ST_Orientation` has a third member, `default`, which means "whatever the printer decides" and is
+ * indistinguishable from the attribute being absent. The model spells that absence as an unset field,
+ * so a file carrying `default` reads back with no orientation and writes back without the attribute.
+ */
+export type PageOrientation = 'portrait' | 'landscape';
+/** Narrow a raw `<pageSetup orientation>` token to a known {@link PageOrientation}. */
+export declare function isPageOrientation(value: string): value is PageOrientation;
+/** The order pages are numbered and printed in across a sheet wider and taller than one page. */
+export type PageOrder = 'downThenOver' | 'overThenDown';
+/** Narrow a raw `<pageSetup pageOrder>` token to a known {@link PageOrder}. */
+export declare function isPageOrder(value: string): value is PageOrder;
 /**
  * Print-scaling and orientation settings. These map onto two OOXML elements: `fitToPage` is the
  * `<pageSetUpPr>` flag (a `<sheetPr>` child) that switches Excel from fixed-zoom to fit-to-page
@@ -16,9 +30,9 @@ export interface PageSetup {
     /** Fixed print zoom as a percentage; Excel honours it only when `fitToPage` is off. */
     scale?: number;
     /** Paper orientation. */
-    orientation?: 'portrait' | 'landscape';
+    orientation?: PageOrientation;
     /** Order pages are numbered/printed in across a multi-page sheet. */
-    pageOrder?: 'downThenOver' | 'overThenDown';
+    pageOrder?: PageOrder;
     /**
      * Paper size as Excel's 1-based enumeration index (e.g. `9` = A4, `1` = US Letter). Carried as an
      * opaque integer: the model does not map it to physical dimensions, only preserves whatever the

package/dist/core/page-setup.js

@@ -1 +1,8 @@
-export {};
+const PAGE_ORIENTATIONS = { portrait: true, landscape: true };
+export function isPageOrientation(value) {
+    return Object.hasOwn(PAGE_ORIENTATIONS, value);
+}
+const PAGE_ORDERS = { downThenOver: true, overThenDown: true };
+export function isPageOrder(value) {
+    return Object.hasOwn(PAGE_ORDERS, value);
+}

package/dist/core/pivot-table.d.ts

@@ -17,6 +17,8 @@ export interface ParsedPivotField {
  * data the reader does not model (an external connection, a range consolidation, or a scenario), and
  * `unknown` covers a `type` the file declares that is none of these. */
 export type PivotSourceKind = 'worksheet' | 'external' | 'consolidation' | 'scenario' | 'unknown';
+/** Narrow a raw `<cacheSource type>` token to a {@link PivotSourceKind} a file may declare. */
+export declare function isDeclarablePivotSourceKind(value: string): value is Exclude<PivotSourceKind, 'unknown'>;
 /** Where a pivot cache draws its rows from. {@link kind} names the source type; {@link sheet} and
  * {@link ref} locate the range only when it is `worksheet` and are empty strings otherwise, so a
  * consumer can tell a genuinely non-worksheet source apart from a worksheet source that failed to

package/dist/core/pivot-table.js

@@ -1,27 +1,36 @@
 import { AuthoringError, InternalError } from '../errors.js';
 import { encodeAddress } from './address.js';
 import { isErrorValue, isFormulaValue, isHyperlinkValue, isRichTextValue, isSharedFormulaValue, richTextToPlain, } from './value.js';
-const PIVOT_METRICS = new Set([
-    'sum',
-    'count',
-    'countNums',
-    'average',
-    'max',
-    'min',
-    'product',
-    'stdDev',
-    'stdDevp',
-    'var',
-    'varp',
-]);
+const PIVOT_METRICS = {
+    sum: true,
+    count: true,
+    countNums: true,
+    average: true,
+    max: true,
+    min: true,
+    product: true,
+    stdDev: true,
+    stdDevp: true,
+    var: true,
+    varp: true,
+};
 function isPivotMetric(value) {
-    return PIVOT_METRICS.has(value);
+    return Object.hasOwn(PIVOT_METRICS, value);
 }
 export function pivotMetricFromSubtotal(subtotal) {
     if (subtotal === undefined)
         return 'sum';
     return isPivotMetric(subtotal) ? subtotal : 'sum';
 }
+const DECLARABLE_PIVOT_SOURCE_KINDS = {
+    worksheet: true,
+    external: true,
+    consolidation: true,
+    scenario: true,
+};
+export function isDeclarablePivotSourceKind(value) {
+    return Object.hasOwn(DECLARABLE_PIVOT_SOURCE_KINDS, value);
+}
 const BLANK = { kind: 'blank' };
 export class PivotTable {
     metric;
@@ -34,8 +43,8 @@ export class PivotTable {
     valueField;
     constructor(options) {
         const metric = options.metric ?? 'sum';
-        if (!PIVOT_METRICS.has(metric)) {
-            throw new AuthoringError(`unsupported pivot metric "${metric}": expected one of ${[...PIVOT_METRICS].join(', ')}`);
+        if (!Object.hasOwn(PIVOT_METRICS, metric)) {
+            throw new AuthoringError(`unsupported pivot metric "${metric}": expected one of ${Object.keys(PIVOT_METRICS).join(', ')}`);
         }
         this.metric = metric;
         const source = options.source;

package/dist/core/protection.d.ts

@@ -63,5 +63,8 @@ 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:
  * 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/row-input.d.ts

@@ -1,6 +1,13 @@
 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

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) {

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
@@ -178,6 +198,13 @@ export declare const CELL_STYLE_FACETS: (keyof CellStyle)[];
  * it joins, the same single-point-of-change the cell path gets.
  */
 export declare function assignStyleFacets(target: CellStyle, source: Readonly<CellStyle>): void;
+/**
+ * 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