@shbernal/ts-xlsx 2.0.0 → 3.0.0

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

@@ -1,3 +1,18 @@
+import type { AssertNever } from './internal.ts';
+/**
+ * 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 const 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 const 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 +31,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
@@ -33,6 +48,61 @@ export interface PageSetup {
      */
     printerSettings?: Uint8Array;
 }
+/**
+ * How one `<pageSetup>` attribute encodes: which model key it is and what kind of value it carries.
+ *
+ * Format-blind on purpose, the same way {@link AlignmentFacet} is: `PageSetup` is a core type and
+ * the layering gate forbids core importing a serialisation, so the table states what an attribute
+ * *is* and each codec supplies the reading and the writing off the `kind`. The OOXML attribute name
+ * is the model key throughout, so it is not restated.
+ */
+export type PageSetupFacet = {
+    readonly key: 'paperSize' | 'scale' | 'fitToWidth' | 'fitToHeight';
+    /** A non-negative integer: a page count, a percentage, or a paper-size id. */
+    readonly kind: 'count';
+} | {
+    readonly key: 'pageOrder' | 'orientation';
+    readonly kind: 'token';
+    /** The enumeration guard, and what to call it in the error when a value fails it. */
+    readonly isValid: (value: string) => boolean;
+    readonly label: string;
+};
+/**
+ * The six `<pageSetup>` attributes, declared once, in CT_PageSetup order. Both directions key off
+ * this list, so an attribute written but not read (it survives a re-write and vanishes on load) or
+ * read but not written is a compile error rather than something a reviewer has to notice.
+ */
+export declare const PAGE_SETUP_FACETS: readonly [{
+    readonly key: 'paperSize';
+    readonly kind: 'count';
+}, {
+    readonly key: 'scale';
+    readonly kind: 'count';
+}, {
+    readonly key: 'fitToWidth';
+    readonly kind: 'count';
+}, {
+    readonly key: 'fitToHeight';
+    readonly kind: 'count';
+}, {
+    readonly key: 'pageOrder';
+    readonly kind: 'token';
+    readonly isValid: (value: string) => value is PageOrder;
+    readonly label: 'page order';
+}, {
+    readonly key: 'orientation';
+    readonly kind: 'token';
+    readonly isValid: (value: string) => value is PageOrientation;
+    readonly label: 'page orientation';
+}];
+/**
+ * Compile-time proof that {@link PAGE_SETUP_FACETS} covers every `<pageSetup>` attribute.
+ *
+ * `fitToPage` and `printerSettings` are excluded because neither is one: `fitToPage` is a
+ * `<sheetPr>` child's flag and `printerSettings` is the blob behind an `r:id`, so both are written
+ * and read somewhere else entirely and a table entry for them would describe nothing.
+ */
+export type EveryPageSetupFacetIsDeclared = AssertNever<Exclude<keyof PageSetup, 'fitToPage' | 'printerSettings' | (typeof PAGE_SETUP_FACETS)[number]['key']>>;
 /**
  * Print-toggle flags from the `<printOptions>` element. Each maps to a boolean OOXML attribute that
  * defaults false, except `gridLinesSet`, which defaults true and gates whether `gridLines` is
@@ -51,6 +121,11 @@ export interface PrintOptions {
     /** Whether the `gridLines` flag is authoritative; when `false`, Excel ignores `gridLines`. */
     gridLinesSet?: boolean;
 }
+/** The `<printOptions>` flags, in CT_PrintOptions attribute order. Each is a plain OOXML boolean, so
+ * the list is the whole of what either direction needs to know. */
+export declare const PRINT_OPTION_FLAGS: readonly ["horizontalCentered", "verticalCentered", "headings", "gridLines", "gridLinesSet"];
+/** Compile-time proof that {@link PRINT_OPTION_FLAGS} covers every {@link PrintOptions} flag. */
+export type EveryPrintOptionFlagIsDeclared = AssertNever<Exclude<keyof PrintOptions, (typeof PRINT_OPTION_FLAGS)[number]>>;
 /**
  * A manual page break (`<brk>`). For a row break, `id` is the row the layout splits *before*; for a
  * column break it is the column. `max` bounds the break's extent across the other axis (Excel writes
@@ -78,6 +153,10 @@ export interface PageMargins {
     header?: number;
     footer?: number;
 }
+/** The `<pageMargins>` sides, in the order CT_PageMargins declares them. */
+export declare const MARGIN_SIDES: readonly ["left", "right", "top", "bottom", "header", "footer"];
+/** Compile-time proof that {@link MARGIN_SIDES} covers every {@link PageMargins} side. */
+export type EveryMarginSideIsDeclared = AssertNever<Exclude<keyof PageMargins, (typeof MARGIN_SIDES)[number]>>;
 /**
  * Page header/footer text, one string per page class. Excel only honours the even- and
  * first-page variants when the writer also sets the gating flags (`differentOddEven`,
@@ -92,3 +171,8 @@ export interface HeaderFooter {
     firstHeader?: string;
     firstFooter?: string;
 }
+/** The `<headerFooter>` children, in CT_HeaderFooter child order. The element name is the model key
+ * throughout, so one list serves the reader's capture, the reader's commit, and the writer. */
+export declare const HEADER_FOOTER_ELEMENTS: readonly ["oddHeader", "oddFooter", "evenHeader", "evenFooter", "firstHeader", "firstFooter"];
+/** Compile-time proof that {@link HEADER_FOOTER_ELEMENTS} covers every {@link HeaderFooter} slot. */
+export type EveryHeaderFooterElementIsDeclared = AssertNever<Exclude<keyof HeaderFooter, (typeof HEADER_FOOTER_ELEMENTS)[number]>>;

package/dist/core/page-setup.js

@@ -1 +1,34 @@
-export {};
+import { tokenSet } from '../token-set.js';
+export const isPageOrientation = tokenSet({ portrait: true, landscape: true });
+export const isPageOrder = tokenSet({ downThenOver: true, overThenDown: true });
+export const PAGE_SETUP_FACETS = [
+    { key: 'paperSize', kind: 'count' },
+    { key: 'scale', kind: 'count' },
+    { key: 'fitToWidth', kind: 'count' },
+    { key: 'fitToHeight', kind: 'count' },
+    { key: 'pageOrder', kind: 'token', isValid: isPageOrder, label: 'page order' },
+    { key: 'orientation', kind: 'token', isValid: isPageOrientation, label: 'page orientation' },
+];
+export const PRINT_OPTION_FLAGS = [
+    'horizontalCentered',
+    'verticalCentered',
+    'headings',
+    'gridLines',
+    'gridLinesSet',
+];
+export const MARGIN_SIDES = [
+    'left',
+    'right',
+    'top',
+    'bottom',
+    'header',
+    'footer',
+];
+export const HEADER_FOOTER_ELEMENTS = [
+    'oddHeader',
+    'oddFooter',
+    'evenHeader',
+    'evenFooter',
+    'firstHeader',
+    'firstFooter',
+];

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 const isDeclarablePivotSourceKind: (value: string) => value is "consolidation" | "external" | "scenario" | "worksheet";
 /** 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,32 @@
 import { AuthoringError, InternalError } from '../errors.js';
+import { tokenSet } from '../token-set.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',
-]);
-function isPivotMetric(value) {
-    return PIVOT_METRICS.has(value);
-}
+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,
+};
+const isPivotMetric = tokenSet(PIVOT_METRICS);
 export function pivotMetricFromSubtotal(subtotal) {
     if (subtotal === undefined)
         return 'sum';
     return isPivotMetric(subtotal) ? subtotal : 'sum';
 }
+export const isDeclarablePivotSourceKind = tokenSet({
+    worksheet: true,
+    external: true,
+    consolidation: true,
+    scenario: true,
+});
 const BLANK = { kind: 'blank' };
 export class PivotTable {
     metric;
@@ -34,8 +39,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/row.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 { Fill } from './style.ts';
 import type { CellValue } from './value.ts';
 import type { RowProperties, Worksheet } from './worksheet.ts';
-export declare class Row {
+export declare class Row extends AxisHandle<RowProperties> {
     #private;
     /** 1-based row number. Fixed for this handle's lifetime. */
     readonly number: number;
@@ -16,6 +17,8 @@ export declare class Row {
      * formatted, and they create the record on first write.
      */
     get properties(): Readonly<RowProperties> | undefined;
+    protected propertiesOf(): RowProperties | undefined;
+    protected ensureProperties(): RowProperties;
     /**
      * Row height in points; `undefined` leaves the sheet default in force.
      *

package/dist/core/row.js

@@ -1,45 +1,53 @@
 import { assertRowInBounds, columnToNumber, encodeAddress } from './address.js';
+import { AxisHandle } from './axis-handle.js';
 import { INTERNAL } from './internal.js';
-export class Row {
+export class Row extends AxisHandle {
     #sheet;
     number;
     constructor(sheet, number) {
+        super();
         assertRowInBounds(number);
         this.#sheet = sheet;
         this.number = number;
     }
     get properties() {
+        return this.propertiesOf();
+    }
+    propertiesOf() {
         return this.#sheet[INTERNAL].rowPropertiesOf(this.number);
     }
+    ensureProperties() {
+        return this.#sheet[INTERNAL].ensureRowProperties(this.number);
+    }
     get height() {
-        return this.#read('height');
+        return this.read('height');
     }
     set height(height) {
-        this.#write('height', height);
+        this.write('height', height);
     }
     get hidden() {
-        return this.#read('hidden');
+        return this.read('hidden');
     }
     set hidden(hidden) {
-        this.#write('hidden', hidden);
+        this.write('hidden', hidden);
     }
     get outlineLevel() {
-        return this.#read('outlineLevel');
+        return this.read('outlineLevel');
     }
     set outlineLevel(outlineLevel) {
-        this.#write('outlineLevel', outlineLevel);
+        this.write('outlineLevel', outlineLevel);
     }
     get collapsed() {
-        return this.#read('collapsed');
+        return this.read('collapsed');
     }
     set collapsed(collapsed) {
-        this.#write('collapsed', collapsed);
+        this.write('collapsed', collapsed);
     }
     get fill() {
-        return this.#read('fill');
+        return this.read('fill');
     }
     set fill(fill) {
-        this.#write('fill', fill);
+        this.write('fill', fill);
     }
     getCell(column) {
         const index = typeof column === 'number' ? column : columnToNumber(column);
@@ -60,16 +68,4 @@ export class Row {
                 this.getCell(index + 1).value = value;
         });
     }
-    #read(key) {
-        return this.#sheet[INTERNAL].rowPropertiesOf(this.number)?.[key];
-    }
-    #write(key, value) {
-        if (value === undefined) {
-            const properties = this.#sheet[INTERNAL].rowPropertiesOf(this.number);
-            if (properties !== undefined)
-                delete properties[key];
-            return;
-        }
-        this.#sheet[INTERNAL].ensureRowProperties(this.number)[key] = value;
-    }
 }

package/dist/core/style.d.ts

@@ -1,7 +1,8 @@
+import type { AssertNever } 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). */
-export declare function isNamedUnderlineStyle(value: string): value is Exclude<UnderlineStyle, boolean>;
+export declare const isNamedUnderlineStyle: (value: string) => value is "double" | "doubleAccounting" | "none" | "single" | "singleAccounting";
 /** A colour, expressed as an ARGB hex string (`"FF0000FF"`) or an indexed theme colour. */
 export interface Color {
     /** 8-digit ARGB hex, uppercase, no leading `#`. */
@@ -14,6 +15,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
@@ -21,7 +42,7 @@ export interface Color {
  */
 export type FillPatternType = 'none' | 'solid' | 'gray125' | 'darkGray' | 'mediumGray' | 'lightGray' | 'gray0625' | 'darkHorizontal' | 'darkVertical' | 'darkDown' | 'darkUp' | 'darkGrid' | 'darkTrellis' | 'lightHorizontal' | 'lightVertical' | 'lightDown' | 'lightUp' | 'lightGrid' | 'lightTrellis';
 /** Narrow a raw `<patternFill patternType>` token to a known {@link FillPatternType}. */
-export declare function isFillPatternType(value: string): value is FillPatternType;
+export declare const 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
@@ -64,7 +85,7 @@ export type Fill = PatternFill | GradientFill;
  */
 export type BorderStyle = 'thin' | 'medium' | 'thick' | 'dashed' | 'dotted' | 'double' | 'hair' | 'mediumDashed' | 'dashDot' | 'mediumDashDot' | 'dashDotDot' | 'mediumDashDotDot' | 'slantDashDot';
 /** Narrow a raw border-edge `style` attribute to a known {@link BorderStyle}. */
-export declare function isBorderStyle(value: string): value is BorderStyle;
+export declare const isBorderStyle: (value: string) => value is BorderStyle;
 /** One edge of a cell border: its line style, and optionally the line colour. */
 export interface BorderEdge {
     readonly style: BorderStyle;
@@ -88,12 +109,12 @@ export interface 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}. */
-export declare function isFontVerticalAlignment(value: string): value is FontVerticalAlignment;
+export declare const isFontVerticalAlignment: (value: string) => value is FontVerticalAlignment;
 /** 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;
+export declare const 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
  * facets it overrides (Excel's own default font backs the rest), so no consumer ever holds every
@@ -117,12 +138,12 @@ export interface Font {
  *  back as no explicit horizontal alignment. */
 export type HorizontalAlignment = 'general' | 'left' | 'center' | 'right' | 'fill' | 'justify' | 'centerContinuous' | 'distributed';
 /** Narrow a raw `<alignment horizontal>` token to a known {@link HorizontalAlignment}. */
-export declare function isHorizontalAlignment(value: string): value is HorizontalAlignment;
+export declare const isHorizontalAlignment: (value: string) => value is HorizontalAlignment;
 /** How a cell's content sits vertically within its bounds, as OOXML's `ST_VerticalAlignment`
  *  enumerates it. */
 export type VerticalAlignment = 'top' | 'center' | 'bottom' | 'justify' | 'distributed';
 /** Narrow a raw `<alignment vertical>` token to a known {@link VerticalAlignment}. */
-export declare function isVerticalAlignment(value: string): value is VerticalAlignment;
+export declare const 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, so a cell that never enabled
@@ -138,6 +159,49 @@ export interface Alignment {
     readonly shrinkToFit?: boolean;
     readonly readingOrder?: number;
 }
+/**
+ * How one `<alignment>` facet encodes: which model key it is, what kind of value it carries, and the
+ * value that means "default", which the writer omits and the reader drops.
+ *
+ * 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.
+ *
+ * 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
+ * attribute differs from its key is the one that would have to add the field.
+ */
+export type AlignmentFacet = {
+    readonly key: 'horizontal' | 'vertical';
+    readonly kind: 'token';
+    /** The enumeration guard, and what to call it in the error when a value fails it. */
+    readonly isValid: (value: string) => boolean;
+    readonly label: string;
+    /** The token that means the OOXML default, expressed by omitting the attribute. */
+    readonly omit?: string;
+} | {
+    readonly key: 'textRotation' | 'indent' | 'readingOrder';
+    readonly kind: 'number';
+} | {
+    readonly key: 'wrapText' | 'shrinkToFit';
+    readonly kind: 'flag';
+};
+/**
+ * The seven `<alignment>` facets, declared once. Both directions key off this list, so a facet
+ * written but not read (it survives a re-write and vanishes on load) or read but not written (the
+ * reverse) is no longer something a reviewer has to notice: {@link EveryAlignmentFacetIsDeclared}
+ * makes a facet added to {@link Alignment} and forgotten here a compile error.
+ *
+ * In ECMA-376 CT_CellAlignment order, which is the order the writer emits.
+ */
+export declare const ALIGNMENT_FACETS: readonly AlignmentFacet[];
+/**
+ * Compile-time proof that {@link ALIGNMENT_FACETS} covers every {@link Alignment} facet. A facet
+ * added to the type without a table entry resolves this to that facet's name, which does not satisfy
+ * `never`, so the error names what is missing.
+ */
+export type EveryAlignmentFacetIsDeclared = AssertNever<Exclude<keyof Alignment, (typeof ALIGNMENT_FACETS)[number]['key']>>;
 /**
  * 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
@@ -178,6 +242,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