@shbernal/ts-xlsx 1.0.0

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

@@ -0,0 +1,94 @@
+/**
+ * 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
+ * scaling, while the rest are `<pageSetup>` attributes. Excel honours `scale` only when `fitToPage`
+ * is off and the `fitToWidth`/`fitToHeight` page counts only when it is on, but the model carries
+ * whatever the author set — an unset field is omitted so a round-trip never fabricates one. An
+ * empty object emits neither element.
+ */
+export interface PageSetup {
+    /** Switch to fit-to-page scaling. Emitted as `<pageSetUpPr fitToPage="1">`. */
+    fitToPage?: boolean;
+    /** Pages wide to fit onto; `0` means "unbounded" (fit only by height). */
+    fitToWidth?: number;
+    /** Pages tall to fit onto; `0` means "unbounded" (fit only by width). */
+    fitToHeight?: number;
+    /** Fixed print zoom as a percentage; Excel honours it only when `fitToPage` is off. */
+    scale?: number;
+    /** Paper orientation. */
+    orientation?: 'portrait' | 'landscape';
+    /** Order pages are numbered/printed in across a multi-page sheet. */
+    pageOrder?: 'downThenOver' | 'overThenDown';
+    /**
+     * 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
+     * author or source file set.
+     */
+    paperSize?: number;
+    /**
+     * The printer-settings blob a source file bound to this sheet's `<pageSetup>` via an `r:id`
+     * relationship, held verbatim. Excel stores the platform-specific `DEVMODE` (paper tray, duplex,
+     * DPI, …) in this opaque binary part; the model does not interpret it, only round-trips the exact
+     * bytes so re-writing a file that carried one does not silently drop the user's print configuration.
+     */
+    printerSettings?: Uint8Array;
+}
+/**
+ * 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
+ * honoured. The model stores only what the source or caller set, so an unset flag is omitted and a
+ * round-trip never fabricates one; an empty object emits no element at all.
+ */
+export interface PrintOptions {
+    /** Centre the printed content horizontally on the page. */
+    horizontalCentered?: boolean;
+    /** Centre the printed content vertically on the page. */
+    verticalCentered?: boolean;
+    /** Print the row and column headings (the `1,2,3…` / `A,B,C…` gutters). */
+    headings?: boolean;
+    /** Print the cell gridlines. */
+    gridLines?: boolean;
+    /** Whether the `gridLines` flag is authoritative; when `false`, Excel ignores `gridLines`. */
+    gridLinesSet?: boolean;
+}
+/**
+ * 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
+ * the last row/column index) and `man` marks it author-set rather than automatic — the model preserves
+ * whatever the source carried so a round-trip reproduces the break's span exactly.
+ */
+export interface PageBreak {
+    /** The row (or column) the break precedes. */
+    readonly id: number;
+    /** The break's far extent across the other axis, if the source declared one. */
+    readonly max?: number;
+    /** `true` when the break is manual (author-set); Excel-authored breaks always are. */
+    readonly man?: boolean;
+}
+/**
+ * Print margins, in inches. OOXML's `<pageMargins>` requires all six to be present, but
+ * the model stores only what the caller set; the writer fills the untouched ones with
+ * valid defaults. An empty object means the element is omitted entirely.
+ */
+export interface PageMargins {
+    left?: number;
+    right?: number;
+    top?: number;
+    bottom?: number;
+    header?: number;
+    footer?: 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`,
+ * `differentFirst`); the writer derives those from which variants are present. An empty
+ * object means the element is omitted entirely.
+ */
+export interface HeaderFooter {
+    oddHeader?: string;
+    oddFooter?: string;
+    evenHeader?: string;
+    evenFooter?: string;
+    firstHeader?: string;
+    firstFooter?: string;
+}

package/dist/core/page-setup.js

@@ -0,0 +1,6 @@
+// The print/page-layout data shapes a worksheet carries: how it scales and orients on paper, which
+// print toggles are set, where manual page breaks fall, the margins, and the header/footer text. Each
+// is a pure data shape mapping onto an OOXML print element (`<pageSetup>`, `<printOptions>`, `<brk>`,
+// `<pageMargins>`, `<headerFooter>`); the model stores only what an author or source file set, so an
+// unset field is omitted and a round-trip never fabricates one.
+export {};

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

@@ -0,0 +1,113 @@
+import type { Worksheet } from './worksheet.ts';
+/** The aggregation a pivot's value field applies. These are OOXML's `ST_DataConsolidateFunction`
+ * names verbatim, so a metric doubles as its `<dataField subtotal="…">` value. Excel performs the
+ * aggregation itself on refresh; the writer only records which function to apply. */
+export type PivotMetric = 'sum' | 'count' | 'countNums' | 'average' | 'max' | 'min' | 'product' | 'stdDev' | 'stdDevp' | 'var' | 'varp';
+/** Narrow a raw `subtotal` attribute (or any string) to a known {@link PivotMetric}. */
+export declare function isPivotMetric(value: string): value is PivotMetric;
+/** Map an OOXML `<dataField subtotal="…">` value back to its metric. The attribute is absent for
+ * `sum` (Excel's implicit default), so `undefined` reads as `sum`; an unrecognised value also reads
+ * as `sum` rather than throwing, because reconstructing an existing file is a lenient operation —
+ * the strict rejection of unknown metrics belongs on the authoring path, not the read path. */
+export declare function pivotMetricFromSubtotal(subtotal: string | undefined): PivotMetric;
+/** One field in a loaded pivot's cache catalogue, in declared order; the pivot refers to it by index. */
+export interface ParsedPivotField {
+    readonly name: string;
+}
+/** The kind of data a pivot cache draws from, mirroring OOXML's `ST_SourceType`. Only `worksheet`
+ * carries a {@link ParsedPivotSource.sheet}/{@link ParsedPivotSource.ref}; every other kind draws from
+ * 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';
+/** 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
+ * parse (the former reports its {@link kind}, the latter stays `worksheet` with empty coordinates). */
+export interface ParsedPivotSource {
+    readonly kind: PivotSourceKind;
+    readonly sheet: string;
+    readonly ref: string;
+}
+/** The semantic model reconstructed from a loaded pivot's `pivotTableDefinition` and its
+ * `pivotCacheDefinition` (see `io/xlsx/pivot-read.ts`). Field roles are indices into {@link fields};
+ * {@link metric} is the aggregation the value field applies. This mirrors the authoring model's shape
+ * without requiring the source sheet it was built from, so a pivot loaded from a package is
+ * inspectable data rather than an opaque preserved blob. It is a read-only view: the writer emits a
+ * loaded pivot from its preserved parts, not from this model, so exposing it never double-emits. */
+export interface ParsedPivotTable {
+    readonly name: string;
+    readonly cacheId: string;
+    readonly source: ParsedPivotSource;
+    readonly fields: readonly ParsedPivotField[];
+    readonly rowFields: readonly number[];
+    readonly columnFields: readonly number[];
+    /** Index into {@link fields} of the aggregated field, or -1 when no `<dataField>` was declared. */
+    readonly valueField: number;
+    readonly valueFieldName: string;
+    /** The `<dataField>`'s own caption ("Average of Amount"), which Excel shows on the data column. */
+    readonly valueCaption: string;
+    readonly metric: PivotMetric;
+}
+/** How a pivot table is authored: a source sheet and the header names that drive each axis.
+ * `rows`/`columns`/`values` name columns by their header text in the source's first row. */
+export interface PivotTableOptions {
+    readonly source: Worksheet;
+    readonly rows: readonly string[];
+    readonly columns: readonly string[];
+    readonly values: readonly string[];
+    readonly metric?: PivotMetric;
+}
+/** One distinct value in a cache field's shared-items catalogue, or an inline record cell. A
+ * `blank` is a missing source value, serialised as `<m/>` rather than an empty string. */
+export type PivotItem = {
+    readonly kind: 'string';
+    readonly value: string;
+} | {
+    readonly kind: 'number';
+    readonly value: number;
+} | {
+    readonly kind: 'blank';
+};
+/** The numeric summary Excel expects on a non-shared field whose every present value is a number. */
+export interface PivotNumericSummary {
+    readonly allInteger: boolean;
+    readonly min: number;
+    readonly max: number;
+}
+/** One field of the pivot cache. An axis field (row or column) carries a `sharedItems` catalogue its
+ * records reference by index; any other field stores its values inline in the records and, when they
+ * are all numeric, describes them with a `numeric` summary. */
+export interface PivotCacheField {
+    readonly name: string;
+    readonly sharedItems: readonly PivotItem[] | null;
+    readonly numeric: PivotNumericSummary | null;
+    readonly containsBlank: boolean;
+}
+/** One cell of a cache record: an index into a shared-items catalogue, or an inline value. */
+export type PivotRecordCell = {
+    readonly kind: 'index';
+    readonly index: number;
+} | PivotItem;
+/**
+ * A pivot table built over a source sheet's data. Construction reads the source once and computes
+ * the full cache (fields + records) and the axis-field wiring the renderer needs; nothing here
+ * touches XML.
+ *
+ * Supported shape: exactly one value field aggregated by `sum`, at least one row field and one
+ * column field. An unsupported request throws at authoring time rather than emitting a corrupt file.
+ */
+export declare class PivotTable {
+    readonly metric: PivotMetric;
+    readonly sourceSheetName: string;
+    /** The `A1:C4` source range: the header row through the last data row, across the field columns. */
+    readonly sourceRef: string;
+    readonly cacheFields: readonly PivotCacheField[];
+    readonly records: readonly (readonly PivotRecordCell[])[];
+    /** Indices into {@link cacheFields} of the row-axis, column-axis, and value fields. */
+    readonly rowFields: readonly number[];
+    readonly columnFields: readonly number[];
+    readonly valueField: number;
+    constructor(options: PivotTableOptions);
+    /** The value field's header name, used to label the aggregated data column ("Sum of Amount"). */
+    get valueFieldName(): string;
+}

package/dist/core/pivot-table.js

@@ -0,0 +1,249 @@
+// A pivot table authored from a model.
+//
+// A pivot summarises a source range: its distinct field values become row/column axes and a value
+// field is aggregated across them. OOXML splits that into three parts — a `pivotCacheDefinition`
+// (the field catalogue), a `pivotCacheRecords` (a copy of the source rows, with axis-field cells
+// swapped for indices into the catalogue), and a `pivotTableDefinition` (the layout on the
+// destination sheet). This module owns the *semantic* computation of all three; the OOXML rendering
+// lives in `io/xlsx/pivot.ts`.
+//
+// The source data is captured when the pivot is added — the model reads the source sheet's cells
+// once, here, so the pivot is a stable snapshot independent of later edits to the source.
+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',
+]);
+/** Narrow a raw `subtotal` attribute (or any string) to a known {@link PivotMetric}. */
+export function isPivotMetric(value) {
+    return PIVOT_METRICS.has(value);
+}
+/** Map an OOXML `<dataField subtotal="…">` value back to its metric. The attribute is absent for
+ * `sum` (Excel's implicit default), so `undefined` reads as `sum`; an unrecognised value also reads
+ * as `sum` rather than throwing, because reconstructing an existing file is a lenient operation —
+ * the strict rejection of unknown metrics belongs on the authoring path, not the read path. */
+export function pivotMetricFromSubtotal(subtotal) {
+    if (subtotal === undefined)
+        return 'sum';
+    return isPivotMetric(subtotal) ? subtotal : 'sum';
+}
+const BLANK = { kind: 'blank' };
+/**
+ * A pivot table built over a source sheet's data. Construction reads the source once and computes
+ * the full cache (fields + records) and the axis-field wiring the renderer needs; nothing here
+ * touches XML.
+ *
+ * Supported shape: exactly one value field aggregated by `sum`, at least one row field and one
+ * column field. An unsupported request throws at authoring time rather than emitting a corrupt file.
+ */
+export class PivotTable {
+    metric;
+    sourceSheetName;
+    /** The `A1:C4` source range: the header row through the last data row, across the field columns. */
+    sourceRef;
+    cacheFields;
+    records;
+    /** Indices into {@link cacheFields} of the row-axis, column-axis, and value fields. */
+    rowFields;
+    columnFields;
+    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(', ')}`);
+        }
+        this.metric = metric;
+        const source = options.source;
+        const columnCount = source.columnCount;
+        const lastRow = source.rowCount;
+        if (columnCount < 1 || lastRow < 2) {
+            throw new AuthoringError('a pivot source needs a header row and at least one data row');
+        }
+        // Every non-blank header cell in row 1 defines a field, in ascending column order.
+        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]);
+        // fields is non-empty (guarded above); the source span runs from its first to its last column.
+        const firstField = fields[0];
+        const lastField = fields[fields.length - 1];
+        if (firstField === undefined || lastField === undefined) {
+            throw new AuthoringError('the pivot source header row is empty');
+        }
+        this.sourceSheetName = source.name;
+        this.sourceRef = `${encodeAddress(firstField.col, 1)}:${encodeAddress(lastField.col, lastRow)}`;
+        // Read the source body once, field by field, so the same scan feeds both the shared-items
+        // catalogues and the records that reference them.
+        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));
+            }
+            return scalars;
+        });
+        const catalogues = fields.map(() => null);
+        this.cacheFields = fields.map((field, fieldIndex) => {
+            const scalars = scalarsForField(columnScalars, fieldIndex);
+            const containsBlank = scalars.some((scalar) => scalar.kind === 'blank');
+            if (axisFields.has(fieldIndex)) {
+                const items = [];
+                const catalogue = new Map();
+                for (const scalar of scalars) {
+                    const key = itemKey(scalar);
+                    if (!catalogue.has(key)) {
+                        catalogue.set(key, items.length);
+                        items.push(scalar);
+                    }
+                }
+                catalogues[fieldIndex] = catalogue;
+                return { name: field.name, sharedItems: items, numeric: null, containsBlank };
+            }
+            return { name: field.name, sharedItems: null, numeric: numericSummary(scalars), containsBlank };
+        });
+        const records = [];
+        for (let row = 0; row < dataRowCount; row++) {
+            records.push(fields.map((_field, fieldIndex) => {
+                const scalar = scalarsForField(columnScalars, fieldIndex)[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;
+                // Every scalar was catalogued in the shared-items pass above, so this always hits.
+                const index = catalogue.get(itemKey(scalar));
+                if (index === undefined)
+                    throw new InternalError('pivot record references an uncatalogued item');
+                return { kind: 'index', index };
+            }));
+        }
+        this.records = records;
+    }
+    /** The value field's header name, used to label the aggregated data column ("Sum of Amount"). */
+    get valueFieldName() {
+        const field = this.cacheFields[this.valueField];
+        if (field === undefined) {
+            throw new InternalError(`pivot valueField index ${this.valueField} is out of range — resolve() validated it against ` +
+                'the same fields array cacheFields was built from');
+        }
+        return field.name;
+    }
+}
+// columnScalars[fieldIndex] is always present: it was built by mapping the same `fields` array this
+// index is drawn from. Centralised here so the invariant is asserted once rather than cast away at
+// each of its two call sites.
+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`);
+    }
+    return scalars;
+}
+/** A stable dedup key for a shared item: kind-tagged so the number `1` and the string `"1"` differ. */
+function itemKey(item) {
+    switch (item.kind) {
+        case 'string':
+            return `s:${item.value}`;
+        case 'number':
+            return `n:${item.value}`;
+        case 'blank':
+            return 'b';
+    }
+}
+/** The numeric summary for an inline field, or null when any present value is non-numeric (a string
+ * present means the field is not a pure numeric column; blanks alone do not disqualify it). */
+function numericSummary(scalars) {
+    let min = Infinity;
+    let max = -Infinity;
+    let allInteger = true;
+    let sawNumber = false;
+    for (const scalar of scalars) {
+        if (scalar.kind === 'blank')
+            continue;
+        if (scalar.kind !== 'number')
+            return null;
+        sawNumber = true;
+        if (scalar.value < min)
+            min = scalar.value;
+        if (scalar.value > max)
+            max = scalar.value;
+        if (!Number.isInteger(scalar.value))
+            allInteger = false;
+    }
+    return sawNumber ? { allInteger, min, max } : null;
+}
+/** The string form of a shared item, used for header names (a blank header contributes no field). */
+function textOf(item) {
+    return item.kind === 'blank' ? '' : String(item.value);
+}
+/**
+ * Reduce any cell value to the scalar a pivot cache can hold: a number, a string, or a blank. Only
+ * finite numbers stay numeric (a NaN would corrupt the cache); every other kind is flattened to its
+ * displayed text so hostile or exotic source content can never throw or leak an object into the XML.
+ */
+function scalarOf(value) {
+    if (value === null)
+        return BLANK;
+    switch (typeof value) {
+        case 'number':
+            return Number.isFinite(value) ? { kind: 'number', value } : BLANK;
+        case 'string':
+            return { kind: 'string', value };
+        case 'boolean':
+            return { kind: 'string', value: value ? 'TRUE' : 'FALSE' };
+        default:
+            break;
+    }
+    if (value instanceof Date)
+        return { kind: 'string', value: value.toISOString() };
+    if (isRichTextValue(value))
+        return { kind: 'string', value: richTextToPlain(value) };
+    if (isHyperlinkValue(value)) {
+        return {
+            kind: 'string',
+            value: typeof value.text === 'string' ? value.text : richTextToPlain(value.text),
+        };
+    }
+    if (isErrorValue(value))
+        return { kind: 'string', value: value.error };
+    if (isFormulaValue(value) || isSharedFormulaValue(value)) {
+        return value.result === undefined ? BLANK : scalarOf(value.result);
+    }
+    return BLANK;
+}

package/dist/core/preserved.d.ts

@@ -0,0 +1,58 @@
+/**
+ * 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
+ * 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.
+ */
+export interface PreservedRelationship {
+    readonly id: string;
+    readonly type: string;
+    readonly targetPath: string;
+    readonly external?: boolean;
+}
+/**
+ * A package part the model does not interpret, captured verbatim so a round-trip re-emits it intact.
+ * `bytes` are the raw part contents, `contentType` how the source package declared it, and `rels` its
+ * outbound relationships (empty when the part references nothing). The writer re-numbers the part to a
+ * fresh, collision-proof path and rewires `rels` accordingly, but never touches `bytes`.
+ */
+export interface PreservedPart {
+    readonly path: string;
+    readonly contentType: string;
+    readonly bytes: Uint8Array;
+    readonly rels: readonly PreservedRelationship[];
+}
+/**
+ * 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
+ * discovers by scanning the sheet's rels, with no worksheet child pointing at it). `relType` is the
+ * relationship Type URI to re-emit; `entryPath` is the part it points at; `parts` is the transitive
+ * closure of parts that reference reaches (the entry included), each re-emitted with its relationships
+ * rewired.
+ */
+export interface PreservedWorksheetReference {
+    readonly element: 'drawing' | 'legacyDrawingHF' | undefined;
+    readonly relType: string;
+    readonly entryPath: string;
+    readonly parts: readonly PreservedPart[];
+}
+/**
+ * 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
+ * (`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.
+ * `relType` is the relationship Type URI to re-emit, `entryPath` the part it targets (kept at its
+ * original path, since the writer generates nothing of these kinds to collide with), and `parts` the
+ * transitive closure the reference reaches.
+ */
+export interface PreservedRootReference {
+    readonly relType: string;
+    readonly entryPath: string;
+    readonly parts: readonly PreservedPart[];
+}

package/dist/core/preserved.js

@@ -0,0 +1,5 @@
+// Package content the model does not interpret, captured verbatim so a round-trip re-emits it intact.
+// A preserved reference names a worksheet- or workbook-level relationship (a chart, vector drawing,
+// slicer, pivot table) the model does not model; its transitive closure of parts is held as raw bytes
+// with their content types and rewired relationships, and re-emitted unchanged on write.
+export {};

package/dist/core/protection.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Whether each protected-sheet operation stays available to a user. Every flag is an
+ * *allow* flag: `true` keeps the operation permitted, `false` forbids it, and an absent
+ * flag falls to Excel's default for that operation (most editing operations default to
+ * forbidden once a sheet is protected; selecting cells defaults to permitted).
+ */
+export interface SheetProtectionFlags {
+    /** Select locked cells (Excel permits this by default). */
+    readonly selectLockedCells?: boolean;
+    /** Select unlocked cells (permitted by default). */
+    readonly selectUnlockedCells?: boolean;
+    readonly formatCells?: boolean;
+    readonly formatColumns?: boolean;
+    readonly formatRows?: boolean;
+    readonly insertColumns?: boolean;
+    readonly insertRows?: boolean;
+    readonly insertHyperlinks?: boolean;
+    readonly deleteColumns?: boolean;
+    readonly deleteRows?: boolean;
+    readonly sort?: boolean;
+    readonly autoFilter?: boolean;
+    readonly pivotTables?: boolean;
+    readonly objects?: boolean;
+    readonly scenarios?: boolean;
+}
+/** {@link SheetProtectionFlags} plus the password-hardening knob accepted by `protect`. */
+export interface SheetProtectionOptions extends SheetProtectionFlags {
+    /**
+     * Iteration count for the password hash. Higher is slower to brute-force; Excel writes
+     * 100000 by default. Ignored when no password is given.
+     */
+    readonly spinCount?: number;
+}
+/**
+ * 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
+ * needs to verify a supplied password without the password ever being stored.
+ */
+export interface SheetProtectionCredential {
+    readonly algorithmName: string;
+    readonly hashValue: string;
+    readonly saltValue: string;
+    readonly spinCount: number;
+}
+/** A sheet's protection: which operations stay allowed, and the optional password guard. */
+export interface SheetProtection {
+    readonly flags: SheetProtectionFlags;
+    readonly credential?: SheetProtectionCredential;
+}
+/**
+ * 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
+ * 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.
+ */
+export declare const SHEET_PROTECTION_FLAGS: readonly {
+    readonly key: keyof SheetProtectionFlags;
+    readonly defaultForbidden: boolean;
+}[];
+/**
+ * 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.
+ */
+export declare function deriveCredential(password: string, spinCount?: number): SheetProtectionCredential;

package/dist/core/protection.js

@@ -0,0 +1,68 @@
+// Worksheet-level protection: the `<sheetProtection>` state that makes the per-cell
+// `locked`/`hidden` flags enforceable. A cell's protection does nothing until the sheet
+// itself is protected; this module models that sheet-level switch and the optional
+// password credential that guards lifting it.
+//
+// The option surface is stated in the AUTHOR's terms — each flag answers "may a user do
+// this while the sheet is protected?" (`sort: true` = sorting stays available). OOXML
+// encodes the inverse ("1" LOCKS an operation, "0"/omission PERMITS it) and its per-
+// attribute defaults differ; that encoding table is {@link SHEET_PROTECTION_FLAGS} below,
+// shared by the writer and reader, while the translation that consumes it lives in the io layer.
+import { createHash, randomBytes } from 'node:crypto';
+/**
+ * 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
+ * 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.
+ */
+export const SHEET_PROTECTION_FLAGS = [
+    { key: 'formatCells', defaultForbidden: true },
+    { key: 'formatColumns', defaultForbidden: true },
+    { key: 'formatRows', defaultForbidden: true },
+    { key: 'insertColumns', defaultForbidden: true },
+    { key: 'insertRows', defaultForbidden: true },
+    { key: 'insertHyperlinks', defaultForbidden: true },
+    { key: 'deleteColumns', defaultForbidden: true },
+    { key: 'deleteRows', defaultForbidden: true },
+    { key: 'sort', defaultForbidden: true },
+    { key: 'autoFilter', defaultForbidden: true },
+    { key: 'pivotTables', defaultForbidden: true },
+    { key: 'objects', defaultForbidden: false },
+    { key: 'scenarios', defaultForbidden: false },
+    { key: 'selectLockedCells', defaultForbidden: false },
+    { key: 'selectUnlockedCells', defaultForbidden: false },
+];
+// OOXML's agile hashing (ECMA-376 / MS-OFFCRYPTO): the password is UTF-16LE, prefixed with
+// the salt for the first hash, then re-hashed `spinCount` times with a little-endian uint32
+// iteration counter mixed in. SHA-512 is the modern choice Excel writes.
+const ALGORITHM_NAME = 'SHA-512';
+const HASH = 'sha512';
+const DEFAULT_SPIN_COUNT = 100000;
+const SALT_BYTES = 16;
+/**
+ * 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.
+ */
+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);
+    for (let i = 0; i < spinCount; i++) {
+        iteration.writeUInt32LE(i, 0);
+        hash = createHash(HASH)
+            .update(Buffer.concat([hash, iteration]))
+            .digest();
+    }
+    return {
+        algorithmName: ALGORITHM_NAME,
+        hashValue: hash.toString('base64'),
+        saltValue: salt.toString('base64'),
+        spinCount,
+    };
+}