@office-kit/xlsx 0.8.0

package/dist/utils/datetime.d.ts

@@ -0,0 +1,38 @@
+/** Excel epoch identifier. */
+export type ExcelEpoch = 'windows' | 'mac';
+/** 1899-12-30 (UTC) — the Windows / 1900-system epoch in ms. */
+export declare const WINDOWS_EPOCH_MS: number;
+/** 1904-01-01 (UTC) — the Mac / 1904-system epoch in ms. */
+export declare const MAC_EPOCH_MS: number;
+/**
+ * Convert an Excel serial date into a JS `Date` (UTC). The fractional part is
+ * treated as a fraction of a day. For Windows 1900 the leap-bug compensation
+ * kicks in for serials in [0, 60).
+ */
+export declare function excelToDate(serial: number, opts?: {
+    epoch?: ExcelEpoch;
+}): Date;
+/**
+ * Convert a JS `Date` into an Excel serial. The Date is read in UTC. On Windows
+ * 1900, dates ≤ 1900-02-28 get a -1 day correction to account for Excel's
+ * phantom leap day.
+ */
+export declare function dateToExcel(date: Date, opts?: {
+    epoch?: ExcelEpoch;
+}): number;
+/** Excel duration serial (fraction of a day) → milliseconds. */
+export declare function excelToDuration(serial: number): number;
+/** Milliseconds → Excel duration serial (fraction of a day). */
+export declare function durationToExcel(ms: number): number;
+/**
+ * Parse an ISO-8601 / W3CDTF datetime string into a `Date`. Same grammar as
+ * `new Date(string)`; the wrapper just adds typed error reporting and a
+ * stricter "must be a recognised ISO" guard.
+ */
+export declare function fromIso8601(s: string): Date;
+/**
+ * Format a `Date` as ISO-8601 with second precision in UTC. Trims the
+ * millisecond fragment that `Date.toISOString()` always produces, so the output
+ * matches Excel / openpyxl's W3CDTF style.
+ */
+export declare function toIso8601(d: Date): string;

package/dist/utils/escape.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Escape a string for safe storage in an OOXML cell. Already-escaped
+ * sequences (`_xHHHH_`) are protected by escaping their leading
+ * underscore; illegal codepoints are replaced with their `_xHHHH_`
+ * representation.
+ */
+export declare function escapeCellString(s: string): string;
+/**
+ * Inverse of {@link escapeCellString}. Looking from left to right
+ * we replace any `_xHHHH_` sequence with the corresponding code unit;
+ * the protected `_x005F_` becomes a literal underscore which the
+ * subsequent replacements skip safely (replace's regex is non-overlapping).
+ */
+export declare function unescapeCellString(s: string): string;
+/**
+ * Escape a string for safe placement in an XML text node. Replaces the three
+ * codepoints that would otherwise terminate the text region or open a markup
+ * sequence (`&`, `<`, `>`); `"` and `'` are not legal markup terminators
+ * inside text and stay verbatim.
+ */
+export declare function escapeXmlText(s: string): string;
+/**
+ * Escape a string for safe placement inside a `"`-quoted XML attribute.
+ * Handles `&`, `<`, `>` and the `"` that would otherwise close the value.
+ *
+ * Note: this deliberately does NOT escape `\r` / `\n` / `\t` to numeric
+ * character references. XML 1.0 attribute-value normalisation would
+ * collapse them to spaces in theory, but the parser used on the read side
+ * (fast-xml-parser) does not decode numeric character references, so a
+ * write-then-read round-trip would surface the literal `&#9;` instead of
+ * recovering the original tab. Leaving the whitespace bytes literal keeps
+ * the round-trip stable and matches what Excel itself emits.
+ */
+export declare function escapeXmlAttr(s: string): string;

package/dist/utils/exceptions.d.ts

@@ -0,0 +1,34 @@
+export interface OpenXmlErrorOptions {
+    /** Underlying cause; preserved on the standard `cause` property. */
+    cause?: unknown;
+}
+export declare class OpenXmlError extends Error {
+    readonly name: string;
+    constructor(message: string, options?: OpenXmlErrorOptions);
+}
+/** Thrown for ZIP, file system, network or stream-level failures. */
+export declare class OpenXmlIoError extends OpenXmlError {
+    readonly name: string;
+}
+/** Thrown when an OOXML payload violates structural / schema invariants. */
+export declare class OpenXmlSchemaError extends OpenXmlError {
+    readonly name = "OpenXmlSchemaError";
+}
+/** Thrown when a workbook is structurally valid OOXML but semantically broken. */
+export declare class OpenXmlInvalidWorkbookError extends OpenXmlError {
+    readonly name = "OpenXmlInvalidWorkbookError";
+}
+/** Thrown for features the port has chosen not to implement (yet). */
+export declare class OpenXmlNotImplementedError extends OpenXmlError {
+    readonly name = "OpenXmlNotImplementedError";
+}
+/**
+ * Thrown when an archive trips the decompression-bomb safeguards configured on
+ * {@link openZip} / {@link loadWorkbook} / {@link loadWorkbookStream}. Subclass
+ * of {@link OpenXmlIoError} so existing `catch (OpenXmlIoError)` paths still
+ * see it, while letting callers branch on bomb-specific recovery (reject the
+ * upload, log a security event, etc.).
+ */
+export declare class OpenXmlDecompressionBombError extends OpenXmlIoError {
+    readonly name = "OpenXmlDecompressionBombError";
+}

package/dist/utils/index.d.ts

@@ -0,0 +1,11 @@
+export type { CellCoordinate, CellCoordinateNumeric, CellRangeBoundaries } from './coordinate';
+export { boundariesToRangeString, columnIndexFromLetter, columnLetterFromIndex, coordinateFromString, coordinateToTuple, formatSheetQualifiedRef, isValidCellRef, isValidColumnLetter, isValidColumnNumber, isValidRangeRef, isValidRowNumber, MAX_COL, MAX_ROW, parseSheetRange, rangeBoundaries, tupleToCoordinate, } from './coordinate';
+export type { ExcelEpoch } from './datetime';
+export { dateToExcel, durationToExcel, excelToDate, excelToDuration, fromIso8601, MAC_EPOCH_MS, toIso8601, WINDOWS_EPOCH_MS, } from './datetime';
+export { cssRecordToInlineStyle } from './css';
+export { escapeCellString, unescapeCellString } from './escape';
+export type { OpenXmlErrorOptions } from './exceptions';
+export { OpenXmlDecompressionBombError, OpenXmlError, OpenXmlInvalidWorkbookError, OpenXmlIoError, OpenXmlNotImplementedError, OpenXmlSchemaError, } from './exceptions';
+export type { CellDataType } from './inference';
+export { ERROR_CODES, inferCellType } from './inference';
+export { cmFromEmu, EMU_PER_CM, EMU_PER_INCH, EMU_PER_PIXEL, EMU_PER_POINT, emuFromCm, emuFromInch, emuFromPoint, emuFromPx, inchFromEmu, pixelToPoint, pointFromEmu, pointToPixel, pxFromEmu, } from './units';

package/dist/utils/inference.d.ts

@@ -0,0 +1,24 @@
+/**
+ * OOXML `t` attribute values. Note that 'inlineStr' is treated
+ * separately — the writer chooses between 's' (shared string) and
+ * 'inlineStr' based on workbook settings, not the value itself.
+ */
+export type CellDataType = 'n' | 's' | 'b' | 'd' | 'f' | 'e';
+/** Excel error tokens. Anything outside this set is treated as a string. */
+export declare const ERROR_CODES: ReadonlySet<string>;
+/**
+ * Infer the cell `t` attribute for a runtime value.
+ *
+ * - `boolean` → 'b'
+ * - `number` → 'n' (incl. integer numerics; date inference is left to
+ *   the caller because Excel decides on type via the cell's number
+ *   format, not the raw value)
+ * - `Date` → 'd'
+ * - string starting with `=` → 'f' (formula)
+ * - string in {@link ERROR_CODES} → 'e'
+ * - any other string → 's'
+ * - `null` / `undefined` → 'n' (empty)
+ *
+ * Throws nothing — returns 'n' as the no-information fallback.
+ */
+export declare function inferCellType(value: unknown): CellDataType;

package/dist/utils/stable-stringify.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Stringify `value` with object keys sorted recursively. Equal logical
+ * values produce the same string regardless of insertion order; arrays
+ * preserve their element order. Circular references throw (the error
+ * comes straight from JSON.stringify's stack-overflow check).
+ */
+export declare function stableStringify(value: unknown): string;

package/dist/utils/units.d.ts

@@ -0,0 +1,14 @@
+export declare const EMU_PER_INCH = 914400;
+export declare const EMU_PER_CM = 360000;
+export declare const EMU_PER_PIXEL = 9525;
+export declare const EMU_PER_POINT = 12700;
+export declare function emuFromPx(px: number): number;
+export declare function pxFromEmu(emu: number): number;
+export declare function emuFromCm(cm: number): number;
+export declare function cmFromEmu(emu: number): number;
+export declare function emuFromInch(inch: number): number;
+export declare function inchFromEmu(emu: number): number;
+export declare function emuFromPoint(pt: number): number;
+export declare function pointFromEmu(emu: number): number;
+export declare function pointToPixel(pt: number, dpi?: number): number;
+export declare function pixelToPoint(px: number, dpi?: number): number;

package/dist/utils/utf8.d.ts

@@ -0,0 +1 @@
+export declare function utf8ByteLength(s: string): number;

package/dist/utils.mjs

@@ -0,0 +1,39 @@
+import { a as OpenXmlNotImplementedError, i as OpenXmlIoError, n as OpenXmlError, o as OpenXmlSchemaError, r as OpenXmlInvalidWorkbookError, t as OpenXmlDecompressionBombError } from "./exceptions-D-CFwxgm.mjs";
+import { a as columnLetterFromIndex, c as formatSheetQualifiedRef, d as isValidColumnNumber, f as isValidRangeRef, g as tupleToCoordinate, h as rangeBoundaries, i as columnIndexFromLetter, l as isValidCellRef, m as parseSheetRange, n as MAX_ROW, o as coordinateFromString, p as isValidRowNumber, r as boundariesToRangeString, s as coordinateToTuple, t as MAX_COL, u as isValidColumnLetter } from "./coordinate-96Ecci4d.mjs";
+import { n as inferCellType, t as ERROR_CODES } from "./inference-B3ES3KEJ.mjs";
+import { a as cmFromEmu, c as emuFromPoint, d as pixelToPoint, f as pointFromEmu, i as EMU_PER_POINT, l as emuFromPx, m as pxFromEmu, n as EMU_PER_INCH, o as emuFromCm, p as pointToPixel, r as EMU_PER_PIXEL, s as emuFromInch, t as EMU_PER_CM, u as inchFromEmu } from "./units-rOMQqXh2.mjs";
+import { i as unescapeCellString, t as escapeCellString } from "./escape-DFTE7ZJc.mjs";
+import { a as excelToDate, c as toIso8601, i as durationToExcel, n as WINDOWS_EPOCH_MS, o as excelToDuration, r as dateToExcel, s as fromIso8601, t as MAC_EPOCH_MS } from "./datetime-B2ySVlXt.mjs";
+//#region src/utils/css.ts
+/**
+* Serialize a CSS-property record to an inline-style declaration string
+* (`prop1: val1; prop2: val2`). Properties are alphabetised so the
+* output is deterministic across runs.
+*
+* - Empty record returns `''`.
+* - Empty-string values are skipped (treat as "unset").
+* - Values containing `;` are dropped — they would terminate the
+*   declaration early and risk attribute-injection in `style="…"`
+*   contexts. Callers should pre-escape user data; this is a
+*   defensive last line.
+*
+* The returned string is suitable for direct interpolation into an
+* HTML `style="…"` attribute *after* the usual attribute-value HTML
+* escaping (no `&` / `"` injection here — this only guards against
+* stray semicolons).
+*/
+function cssRecordToInlineStyle(record) {
+	if (!record) return "";
+	const parts = [];
+	for (const key of Object.keys(record).sort()) {
+		const value = record[key];
+		if (value === void 0 || value === "") continue;
+		if (value.includes(";")) continue;
+		parts.push(`${key}: ${value}`);
+	}
+	return parts.join("; ");
+}
+//#endregion
+export { EMU_PER_CM, EMU_PER_INCH, EMU_PER_PIXEL, EMU_PER_POINT, ERROR_CODES, MAC_EPOCH_MS, MAX_COL, MAX_ROW, OpenXmlDecompressionBombError, OpenXmlError, OpenXmlInvalidWorkbookError, OpenXmlIoError, OpenXmlNotImplementedError, OpenXmlSchemaError, WINDOWS_EPOCH_MS, boundariesToRangeString, cmFromEmu, columnIndexFromLetter, columnLetterFromIndex, coordinateFromString, coordinateToTuple, cssRecordToInlineStyle, dateToExcel, durationToExcel, emuFromCm, emuFromInch, emuFromPoint, emuFromPx, escapeCellString, excelToDate, excelToDuration, formatSheetQualifiedRef, fromIso8601, inchFromEmu, inferCellType, isValidCellRef, isValidColumnLetter, isValidColumnNumber, isValidRangeRef, isValidRowNumber, parseSheetRange, pixelToPoint, pointFromEmu, pointToPixel, pxFromEmu, rangeBoundaries, toIso8601, tupleToCoordinate, unescapeCellString };
+
+//# sourceMappingURL=utils.mjs.map

package/dist/utils.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.mjs","names":[],"sources":["../src/utils/css.ts"],"sourcesContent":["// CSS-record → inline-style serializer.\n//\n// Companion to the `*ToCss` style helpers (fontToCss / fillToCss /\n// borderToCss / alignmentToCss / cellStyleToCss): once a caller has\n// merged the partials into a `Record<string, string>`, this turns it\n// into a stable `style=\"…\"` attribute value for HTML preview.\n\n/**\n * Serialize a CSS-property record to an inline-style declaration string\n * (`prop1: val1; prop2: val2`). Properties are alphabetised so the\n * output is deterministic across runs.\n *\n * - Empty record returns `''`.\n * - Empty-string values are skipped (treat as \"unset\").\n * - Values containing `;` are dropped — they would terminate the\n *   declaration early and risk attribute-injection in `style=\"…\"`\n *   contexts. Callers should pre-escape user data; this is a\n *   defensive last line.\n *\n * The returned string is suitable for direct interpolation into an\n * HTML `style=\"…\"` attribute *after* the usual attribute-value HTML\n * escaping (no `&` / `\"` injection here — this only guards against\n * stray semicolons).\n */\nexport function cssRecordToInlineStyle(record: Record<string, string> | undefined): string {\n  if (!record) return '';\n  const parts: string[] = [];\n  for (const key of Object.keys(record).sort()) {\n    const value = record[key];\n    if (value === undefined || value === '') continue;\n    if (value.includes(';')) continue;\n    parts.push(`${key}: ${value}`);\n  }\n  return parts.join('; ');\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;AAwBA,SAAgB,uBAAuB,QAAoD;CACzF,IAAI,CAAC,QAAQ,OAAO;CACpB,MAAM,QAAkB,CAAC;CACzB,KAAK,MAAM,OAAO,OAAO,KAAK,MAAM,EAAE,KAAK,GAAG;EAC5C,MAAM,QAAQ,OAAO;EACrB,IAAI,UAAU,KAAA,KAAa,UAAU,IAAI;EACzC,IAAI,MAAM,SAAS,GAAG,GAAG;EACzB,MAAM,KAAK,GAAG,IAAI,IAAI,OAAO;CAC/B;CACA,OAAO,MAAM,KAAK,IAAI;AACxB"}

package/dist/workbook/calc-properties.d.ts

@@ -0,0 +1,47 @@
+export type CalcMode = 'manual' | 'auto' | 'autoNoTable';
+export type RefMode = 'A1' | 'R1C1';
+export interface CalcProperties {
+    /** Excel build/calc-engine identifier; OpenOffice sets 191621, Excel 2016+ 162913 etc. */
+    calcId?: number;
+    calcMode?: CalcMode;
+    /** Force a full recalc when the workbook is loaded. Excel default `true` for safety. */
+    fullCalcOnLoad?: boolean;
+    refMode?: RefMode;
+    /** Allow circular references via iterative calculation. */
+    iterate?: boolean;
+    iterateCount?: number;
+    iterateDelta?: number;
+    /** Use full 15-digit precision (vs. displayed precision). */
+    fullPrecision?: boolean;
+    calcCompleted?: boolean;
+    /** Run a recalc on save. */
+    calcOnSave?: boolean;
+    /** Use multi-threaded calculation. */
+    concurrentCalc?: boolean;
+    concurrentManualCount?: number;
+    /** Force a full recalc on next interaction. */
+    forceFullCalc?: boolean;
+}
+export declare const makeCalcProperties: (opts?: CalcProperties) => CalcProperties;
+import type { Workbook } from './workbook';
+/**
+ * Set the recalculation mode. `'auto'` is Excel's default;
+ * `'manual'` requires F9 to recompute formulas; `'autoNoTable'`
+ * recomputes everything except data-table cells.
+ */
+export declare const setCalcMode: (wb: Workbook, mode: CalcMode) => void;
+/**
+ * Toggle iterative calculation (Excel's "Enable iterative calculation"
+ * option). When `enable` is true and `count` / `delta` are provided,
+ * they replace the default Excel limits (100 iterations, 0.001 delta).
+ */
+export declare const setIterativeCalc: (wb: Workbook, enable: boolean, opts?: {
+    count?: number;
+    delta?: number;
+}) => void;
+/** Toggle "Recalculate workbook before saving" (workbook-level). */
+export declare const setCalcOnSave: (wb: Workbook, on: boolean) => void;
+/** Toggle "Recalculate workbook on load" — forces a full recalc on open. */
+export declare const setFullCalcOnLoad: (wb: Workbook, on: boolean) => void;
+/** Toggle "Set precision as displayed" (false = full 15-digit precision). */
+export declare const setFullPrecision: (wb: Workbook, on: boolean) => void;

package/dist/workbook/defined-names.d.ts

@@ -0,0 +1,121 @@
+export interface DefinedName {
+    /** Identifier — `_xlnm.Print_Area` for built-ins, otherwise user-chosen. */
+    name: string;
+    /** The formula expression the name points at. */
+    value: string;
+    /** 0-based sheet index for sheet-scope names; undefined → workbook-scope. */
+    scope?: number;
+    /** Hidden from the Name Manager when true. */
+    hidden?: boolean;
+    /** Optional human-readable description. */
+    comment?: string;
+}
+export declare function makeDefinedName(opts: Partial<DefinedName> & {
+    name: string;
+    value: string;
+}): DefinedName;
+import { type CellRangeBoundaries } from '../utils/coordinate';
+import type { Worksheet } from '../worksheet/worksheet';
+import type { Workbook } from './workbook';
+/**
+ * One parsed leg of a defined name's value. Defined-name values can be
+ * comma-separated multi-range expressions (e.g. `_xlnm.Print_Titles` sets
+ * `Sheet!$1:$1,Sheet!$A:$A`); this represents one such leg.
+ */
+export interface DefinedNameTarget {
+    sheet: string;
+    range: string;
+    bounds: CellRangeBoundaries;
+}
+/**
+ * Add a workbook-scope or sheet-scope defined name. If a defined name with the
+ * same `name` (and `scope`) already exists, it's replaced — Excel allows one
+ * workbook-scope and one per-sheet-scope name, but not two with the same scope.
+ * Returns the resulting `DefinedName`.
+ */
+export declare const addDefinedName: (wb: Workbook, opts: Partial<DefinedName> & {
+    name: string;
+    value: string;
+}) => DefinedName;
+/**
+ * High-level: register a defined name pointing at a worksheet range. Combines
+ * {@link getRangeAddress} (sheet-qualified, properly quoted) with {@link
+ * addDefinedName}, so the caller doesn't have to assemble the formula string by
+ * hand.
+ *
+ * Pass `opts.localToSheet: true` to scope the name to the worksheet (instead of
+ * the workbook). Re-using the same `name` + scope replaces the previous entry
+ * (Excel's per-scope-uniqueness rule).
+ *
+ * Throws when `localToSheet: true` is set but the worksheet isn't on
+ * `wb.sheets` — that would be a stale Worksheet reference.
+ */
+export declare const addDefinedNameForRange: (wb: Workbook, name: string, ws: Worksheet, range: string, opts?: {
+    localToSheet?: boolean;
+    hidden?: boolean;
+    comment?: string;
+}) => DefinedName;
+/** Look up a defined name by identifier and (optional) sheet scope. */
+export declare const getDefinedName: (wb: Workbook, name: string, scope?: number) => DefinedName | undefined;
+/**
+ * Resolve a defined name's `value` into one or more {@link DefinedNameTarget}s.
+ * Comma-separated values (e.g. `_xlnm.Print_Titles` typically sets
+ * `Sheet!$1:$1,Sheet!$A:$A`) yield one entry per leg; a plain `Sheet!A1:B5`
+ * yields a single-element array.
+ *
+ * Returns `undefined` when the name doesn't exist; throws when the value can't
+ * be parsed (e.g. a constant or a non-range formula — defined names are
+ * sometimes used for things like `=42` or `=SUM(A:A)` which aren't ranges).
+ */
+export declare const getDefinedNameTarget: (wb: Workbook, name: string, scope?: number) => DefinedNameTarget[] | undefined;
+/**
+ * Remove a defined name by identifier + scope. Returns true if any entry was
+ * removed.
+ */
+export declare const removeDefinedName: (wb: Workbook, name: string, scope?: number) => boolean;
+/**
+ * Read-only snapshot of every defined name. Pass `{ scope }` to narrow to
+ * workbook-scope (`scope: undefined`) or one specific sheet (`scope: 0`) — omit
+ * the option entirely to list all.
+ */
+export declare const listDefinedNames: (wb: Workbook, opts?: {
+    scope?: number | "workbook" | "all";
+}) => ReadonlyArray<DefinedName>;
+/**
+ * Bulk-remove every defined name matching `predicate`. Returns the count
+ * removed. Mirrors {@link removeDataValidations} on worksheets.
+ */
+export declare const removeDefinedNames: (wb: Workbook, predicate: (d: DefinedName) => boolean) => number;
+/**
+ * Rename a defined name, scoped or workbook-scope. Returns `true` when an entry
+ * was renamed. Throws when `newName` is already taken with the same scope
+ * (Excel forbids duplicates within a scope).
+ */
+export declare const renameDefinedName: (wb: Workbook, oldName: string, newName: string, scope?: number) => boolean;
+/**
+ * Read-only snapshot of every `_xlnm.Print_Area` defined name. Each entry is
+ * the raw DefinedName carrying `scope` (sheet index) and `value` (the
+ * print-area expression like `'Sheet1'!$A$1:$D$10`).
+ */
+export declare const listPrintAreas: (wb: Workbook) => ReadonlyArray<DefinedName>;
+/**
+ * Read-only snapshot of every `_xlnm.Print_Titles` defined name. Each entry's
+ * `value` is the title-row / title-col expression Excel re-uses on every
+ * printed page.
+ */
+export declare const listPrintTitles: (wb: Workbook) => ReadonlyArray<DefinedName>;
+/**
+ * Define the print-area for a given sheet. Excel uses the built-in
+ * `_xlnm.Print_Area` defined name with sheet scope.
+ */
+export declare const setPrintArea: (wb: Workbook, sheetIndex: number, ref: string) => DefinedName;
+/**
+ * Define print-title rows / columns on a sheet. Excel uses the
+ * `_xlnm.Print_Titles` defined name. Pass `rows` ("$1:$1") to repeat row 1 on
+ * every printed page; `cols` ("$A:$A") to repeat column A.
+ */
+export declare const setPrintTitles: (wb: Workbook, sheetIndex: number, opts: {
+    rows?: string;
+    cols?: string;
+    sheetName: string;
+}) => DefinedName;

package/dist/workbook/file-recovery.d.ts

@@ -0,0 +1,11 @@
+export interface FileRecoveryProperties {
+    /** True after an autorecover save — Excel uses it to display the recovery banner. */
+    autoRecover?: boolean;
+    /** Persisted crash-recovery flag. */
+    crashSave?: boolean;
+    /** Mark the file as "data extracted from a damaged workbook". */
+    dataExtractLoad?: boolean;
+    /** Workbook was repaired during load. */
+    repairLoad?: boolean;
+}
+export declare const makeFileRecoveryProperties: (opts?: FileRecoveryProperties) => FileRecoveryProperties;

package/dist/workbook/file-sharing.d.ts

@@ -0,0 +1,14 @@
+export interface FileSharing {
+    /** Mark the workbook as "Read-only recommended" — Excel pops a dialog on open. */
+    readOnlyRecommended?: boolean;
+    /** Author name attached to the read/write password. */
+    userName?: string;
+    /** Legacy 16-bit hex hash of the reservation password. */
+    reservationPassword?: string;
+    /** Modern hash quad — algorithmName + hashValue + saltValue + spinCount. */
+    algorithmName?: string;
+    hashValue?: string;
+    saltValue?: string;
+    spinCount?: number;
+}
+export declare const makeFileSharing: (opts?: FileSharing) => FileSharing;

package/dist/workbook/file-version.d.ts

@@ -0,0 +1,13 @@
+export interface FileVersion {
+    /** Application that last saved the workbook ("xl" for Excel). */
+    appName?: string;
+    /** Build number of the last editor (e.g. "7.5210"). */
+    lastEdited?: string;
+    /** Build number of the lowest editor (oldest Excel that touched the file). */
+    lowestEdited?: string;
+    /** Internal "rolled-up build" number. */
+    rupBuild?: string;
+    /** GUID identifying the file content (Excel uses it to detect re-saves). */
+    codeName?: string;
+}
+export declare const makeFileVersion: (opts?: FileVersion) => FileVersion;

package/dist/workbook/function-groups.d.ts

@@ -0,0 +1,10 @@
+export interface FunctionGroup {
+    name: string;
+}
+export interface FunctionGroups {
+    /** Number of built-in groups Excel reserves before user entries (default 16). */
+    builtInGroupCount?: number;
+    groups: FunctionGroup[];
+}
+export declare const makeFunctionGroup: (name: string) => FunctionGroup;
+export declare const makeFunctionGroups: (opts?: Partial<FunctionGroups>) => FunctionGroups;

package/dist/workbook/index.d.ts

@@ -0,0 +1,24 @@
+export type { CellSummary, SheetRef, SheetState, Workbook, WorkbookOverview, WorkbookSheetOverview, WorkbookStats, } from './workbook';
+export { addChartsheet, addWorksheet, createWorkbook, describeWorkbook, getActiveSheet, getCellAtAddress, getCellSummary, getChartsheet, getSheet, getSheetState, getWorkbookCellsByKind, getWorkbookStats, iterWorksheets, listCustomXmlParts, moveSheet, removeSheet, renameSheet, setActiveSheet, setCellAtAddress, setSheetState, sheetNames, } from './workbook';
+export type { DefinedName, DefinedNameTarget } from './defined-names';
+export { addDefinedName, getDefinedName, getDefinedNameTarget, listDefinedNames, makeDefinedName, removeDefinedName, } from './defined-names';
+export type { WorkbookProtection } from './protection';
+export { makeWorkbookProtection } from './protection';
+export type { SharedStringEntry, SharedStringsTable } from './shared-strings';
+export { addSharedString, getSharedStringAt, getSharedStringIndex, makeSharedStrings, sharedStringCount, } from './shared-strings';
+export type { CustomViewShowComments, CustomViewShowObjects, CustomWorkbookView, WorkbookView, WorkbookViewVisibility, } from './views';
+export { makeCustomWorkbookView, makeWorkbookView } from './views';
+export type { CalcMode, CalcProperties, RefMode } from './calc-properties';
+export { makeCalcProperties } from './calc-properties';
+export type { ShowObjectsMode, UpdateLinksMode, WorkbookProperties, } from './workbook-properties';
+export { makeWorkbookProperties } from './workbook-properties';
+export type { FileVersion } from './file-version';
+export { makeFileVersion } from './file-version';
+export type { FileSharing } from './file-sharing';
+export { makeFileSharing } from './file-sharing';
+export type { FileRecoveryProperties } from './file-recovery';
+export { makeFileRecoveryProperties } from './file-recovery';
+export type { SmartTagProperties, SmartTagShowMode, SmartTagType } from './smart-tags';
+export { makeSmartTagProperties, makeSmartTagType } from './smart-tags';
+export type { FunctionGroup, FunctionGroups } from './function-groups';
+export { makeFunctionGroup, makeFunctionGroups } from './function-groups';

package/dist/workbook/protection.d.ts

@@ -0,0 +1,35 @@
+export interface WorkbookProtection {
+    /** Legacy 16-bit hex hash of the workbook password ("CC1A" etc.). */
+    workbookPassword?: string;
+    workbookPasswordCharacterSet?: string;
+    workbookAlgorithmName?: string;
+    workbookHashValue?: string;
+    workbookSaltValue?: string;
+    workbookSpinCount?: number;
+    /** Legacy 16-bit hex hash of the revisions-tracking password. */
+    revisionsPassword?: string;
+    revisionsPasswordCharacterSet?: string;
+    revisionsAlgorithmName?: string;
+    revisionsHashValue?: string;
+    revisionsSaltValue?: string;
+    revisionsSpinCount?: number;
+    /** Lock add/delete/move/rename/hide of sheets. */
+    lockStructure?: boolean;
+    /** Lock the workbook window size and position. */
+    lockWindows?: boolean;
+    /** Lock revision tracking — enabled with the "Track Changes" feature. */
+    lockRevision?: boolean;
+}
+export declare const makeWorkbookProtection: (opts?: WorkbookProtection) => WorkbookProtection;
+import type { Workbook } from './workbook';
+/**
+ * Lock the workbook with Excel's "Protect Workbook → Structure" default
+ * (lockStructure=true). Pass `overrides` to also lock windows /
+ * revision-tracking, or to attach a password-hash quad. Plaintext password
+ * support is deferred until the D-tier hashing helper lands.
+ */
+export declare const protectWorkbook: (wb: Workbook, overrides?: Partial<WorkbookProtection>) => WorkbookProtection;
+/** Drop the workbook-protection record entirely. */
+export declare const unprotectWorkbook: (wb: Workbook) => void;
+/** True iff `lockStructure === true`. */
+export declare const isWorkbookProtected: (wb: Workbook) => boolean;

package/dist/workbook/shared-strings.d.ts

@@ -0,0 +1,57 @@
+import type { RichText } from '../cell/rich-text';
+/** A single SST entry: either a plain string or a rich-text run array. */
+export type SharedStringEntry = string | {
+    kind: 'rich-text';
+    runs: RichText;
+};
+/**
+ * Mutable shared-strings accumulator + lookup table. The same shape is used
+ * during read (just populate `entries`) and write (call `addSharedString` from
+ * the worksheet writer; emit to bytes at the end).
+ */
+export interface SharedStringsTable {
+    /** Insertion-ordered list of unique entries. */
+    entries: SharedStringEntry[];
+    /** Reverse lookup keyed by literal text — rich-text entries skip this map. */
+    index: Map<string, number>;
+}
+export declare function makeSharedStrings(): SharedStringsTable;
+/**
+ * Insert a string and return its index. Idempotent: calling with the same value
+ * twice gives the same index. Empty strings are deduped just like everything
+ * else.
+ */
+export declare function addSharedString(table: SharedStringsTable, value: string): number;
+/** Look up a shared-string index by its literal text. Returns `undefined` for unknown values. */
+export declare function getSharedStringIndex(table: SharedStringsTable, value: string): number | undefined;
+/**
+ * Read a shared-string by its 0-based index. Returns `undefined` for
+ * out-of-range. Rich-text entries surface their concatenated plain text so
+ * callers that want only the textual body don't need to know about the
+ * discriminated union.
+ */
+export declare function getSharedStringAt(table: SharedStringsTable, index: number): string | undefined;
+/** Number of unique entries in the SST. */
+export declare function sharedStringCount(table: SharedStringsTable): number;
+/**
+ * Parse a `xl/sharedStrings.xml` payload. Returns the table directly (rather
+ * than just the array) so the worksheet writer can keep appending to it without
+ * rebuilding the index.
+ *
+ * Rich-text runs are preserved as their full per-run formatting so
+ * round-tripping a file with rich text doesn't drop the styling.
+ */
+export declare function parseSharedStringsXml(bytes: Uint8Array | string): SharedStringsTable;
+/**
+ * Serialise a SharedStringsTable to its OOXML bytes. The `count` attribute
+ * tracks total references (we don't know that here so we report the same as
+ * `uniqueCount` — readers tolerate the discrepancy and Excel ignores `count` in
+ * practice). `uniqueCount` always matches `entries.length`.
+ */
+export declare function sharedStringsToBytes(table: SharedStringsTable): Uint8Array;
+export declare function serializeSharedStrings(table: SharedStringsTable): string;
+/**
+ * Serialise a sequence of `<r>...<r>` runs — shared by the SST `<si>` writer
+ * and the worksheet's inline-string (`t="inlineStr"`) cell writer.
+ */
+export declare function serializeRichTextRuns(runs: import('../cell/rich-text').RichText): string;

package/dist/workbook/smart-tags.d.ts

@@ -0,0 +1,13 @@
+export type SmartTagShowMode = 'all' | 'noIndicator';
+export interface SmartTagProperties {
+    /** Embed smart tags into the workbook on save. */
+    embed?: boolean;
+    show?: SmartTagShowMode;
+}
+export interface SmartTagType {
+    namespaceUri?: string;
+    name?: string;
+    url?: string;
+}
+export declare const makeSmartTagProperties: (opts?: SmartTagProperties) => SmartTagProperties;
+export declare const makeSmartTagType: (opts?: SmartTagType) => SmartTagType;