@office-kit/xlsx 0.8.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yuichiro Yamashita
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,319 @@
+<p align="center">
+  <img src="./assets/logo.png" alt="@office-kit/xlsx" width="180" height="180" />
+</p>
+
+# @office-kit/xlsx
+
+A TypeScript library for reading and writing Excel `.xlsx` workbooks
+from Node 22+ and modern browsers, with no runtime dependencies on
+Python or Excel. Inspired by [openpyxl](https://openpyxl.readthedocs.io/).
+
+> **Status: pre-1.0 alpha.** The core read / write / streaming pipeline is
+> in place and round-trips real-world fixtures (including pivot tables and
+> macro-enabled `.xlsm`), but APIs may shift before `1.0`.
+
+## Why @office-kit/xlsx?
+
+The JavaScript xlsx ecosystem in 2026 is split between **commercial upsell
+tiers** and **stalled open-source projects**. SheetJS Community Edition
+deliberately omits styling, charts, images, pivots, conditional formatting,
+and data validation on write — those live in [SheetJS Pro][sjs-pro], a paid
+tier. ExcelJS is MIT but
+[has not had a meaningful release since October 2023][exceljs-discussion]
+and its maintainers explicitly call it inactive; the dependency footprint
+unpacks to 21.8 MB. excel4node was [archived in 2022][e4n-archive].
+xlsx-js-style is frozen at a 2022 SheetJS fork.
+
+@office-kit/xlsx is the third option: an actively-developed, pure-MIT,
+TypeScript-first library with no Pro tier and no missing features behind a
+paywall.
+
+[sjs-pro]: https://sheetjs.com/pro/
+[exceljs-discussion]: https://github.com/exceljs/exceljs/discussions/2987
+[e4n-archive]: https://github.com/natergj/excel4node
+
+| Concern                | Other libraries                                                                  | @office-kit/xlsx                                                              |
+|------------------------|----------------------------------------------------------------------------------|-----------------------------------------------------------------------|
+| TypeScript types       | hand-written `.d.ts` retrofitted (SheetJS) or community typings (xlsx-populate, excel4node) | first-party, written in TS under `exactOptionalPropertyTypes` + `noUncheckedIndexedAccess` |
+| Bundle size            | ExcelJS unpacks to 21.8 MB; xlsx ~7.5 MB                                         | full lib ≤120 KB min+brotli (currently ~85 KB); streaming entry ~49 KB |
+| Streaming              | SheetJS docs explicitly note the zip central-directory layout prevents true streaming; ExcelJS supports both directions but the lib is heavy | both read iter and write append, with fixed-memory budget for tens of millions of rows |
+| Charts (write)         | none in ExcelJS, xlsx-js-style, SheetJS CE; gated behind SheetJS Pro             | 16 legacy `c:` + 8 modern `cx:` chart kinds (Sunburst, Treemap, Waterfall, Histogram, Pareto, Funnel, BoxWhisker, RegionMap) |
+| Pivots / VBA / OLE     | ExcelJS drops pivot tables on read ([#261][exceljs-pivot]); others vary           | byte-identical passthrough so Excel 365 still renders parts we don't model |
+| Maintenance            | ExcelJS stalled since 2023; excel4node archived 2022; xlsx-js-style frozen 2022; SheetJS npm artifact frozen 2022 (still distributed via private CDN) | active                                                                |
+| License                | SheetJS CE strips features for Pro upsell; SheetJS Pro pricing not published      | MIT, single tier, no upsell                                            |
+| Conformance            | none of the major libraries validate against ECMA-376 in CI                       | 3-tier validator (OPC structure + ECMA-376 XSD + semantic invariants) gates every CI build, including a fast-check property-based oracle |
+| Modules                | monolithic root barrel                                                           | subpath imports — `@office-kit/xlsx/io`, `/streaming`, `/cell`, `/styles`, etc., each independently tree-shakable |
+
+[exceljs-pivot]: https://github.com/exceljs/exceljs/issues/261
+
+### Where each existing library still wins
+
+- **Read simple xlsx in the browser** → [`read-excel-file`][rexf] is excellent.
+- **Write simple xlsx with images** → [`write-excel-file`][wexf] is excellent.
+- **Template-based fidelity preservation with password protection** → `xlsx-populate`.
+- **Non-xlsx formats** (XLS / XLSB / ODS / CSV / HTML) → SheetJS Community.
+- **Commercial budget + long shopping list** → SheetJS Pro.
+
+[rexf]: https://www.npmjs.com/package/read-excel-file
+[wexf]: https://www.npmjs.com/package/write-excel-file
+
+### @office-kit/xlsx's home turf
+
+- You write modern TypeScript and want types that actually behave under
+  strict mode (cell values are a discriminated union, not `any`).
+- You produce **large** xlsx files (tens of millions of cells) and care
+  about heap budget.
+- You need **charts**, conditional formatting, data validation, defined
+  names, tables, ZIP64 (entry-count overflow; see "What's supported" for the
+  4 GiB-per-entry caveat) — and want them in MIT.
+- You round-trip xlsx files that contain pivot tables, VBA macros,
+  threaded comments, Power Query metadata, or customXml — and need them
+  preserved byte-for-byte.
+- You want **proof** that the bytes you emit are valid OOXML, not "Excel
+  happens to open them today."
+
+### When NOT to use @office-kit/xlsx
+
+Honest list:
+
+- **Pre-1.0**: API may shift before 1.0. Pin the version for long-running
+  projects.
+- **`.xlsx` only**: no `.xls` (BIFF), `.xlsb`, `.ods`, or `.csv`. Use
+  SheetJS for those.
+- **Node 22+ required**: relies on built-in `Web Streams`, `Blob`, and
+  `fetch`. Node 18 / 20 (EOL) are not supported.
+- **Browser stress-test history is shorter** than ExcelJS's. If you ship
+  to millions of browser users today, run your own benchmark first.
+- **Visual QA in Excel 365** is on the human-verification list; the schema
+  gate proves spec compliance, not that every chart renders pixel-perfect.
+
+### Motivation
+
+The reasons @office-kit/xlsx exists, written down so future contributors don't
+relitigate them:
+
+1. **The reference implementation is in Python.** [openpyxl][openpyxl] has
+   spent 15 years collecting Excel / LibreOffice corner cases. @office-kit/xlsx
+   consumes its fixture corpus directly (`reference/openpyxl/` is a git
+   submodule), so edge cases the Python world solved years ago don't get
+   re-discovered painfully in JS.
+2. **The 2010-era JS stack is heavy.** Most existing libraries pull in
+   `jszip`, `lodash`, `archiver`, `xmlbuilder`, `sax`. In 2026 we have
+   `fflate`, `fast-xml-parser`, and `saxes` — the toolchain is an order
+   of magnitude lighter. @office-kit/xlsx ships with three runtime dependencies.
+3. **TypeScript-first changes the API surface.** A library authored in TS
+   under strict-mode flags from day one exposes different ergonomics than
+   `.d.ts` typings retrofitted onto an old JS codebase.
+4. **"Schema-valid" should be a CI gate, not a vibe.** ECMA-376 is
+   downloadable; xmllint is free; vendoring the schemas costs <1 MB. There
+   is no good reason a 2026 library shouldn't validate every byte it
+   emits against the spec.
+5. **No Pro tier.** Charts, pivots passthrough, conditional formatting,
+   ZIP64 write — all MIT. Nothing held back.
+
+[openpyxl]: https://openpyxl.readthedocs.io/
+
+## Install
+
+```sh
+pnpm add @office-kit/xlsx   # or npm / yarn / bun
+```
+
+Requires Node `>=22` for the built-in `Web Streams`, `Blob`, and `fetch`
+globals.
+
+## Subpath entries
+
+The package has no root barrel — every export lives behind a section
+subpath, so your editor's autocomplete only surfaces what's relevant to
+the area you're working in. Each export has exactly one home (no
+convenience re-exports).
+
+| Import                 | Use case                                          |
+|------------------------|---------------------------------------------------|
+| `@office-kit/xlsx/io`           | `loadWorkbook` / `saveWorkbook` / `workbookToBytes` plus byte-level Source/Sink + browser helpers (Blob/Response/Stream) |
+| `@office-kit/xlsx/node`         | Node fs glue (`fromFile` / `toFile` / `fromBuffer` / `toBuffer` / `fromReadable` / `toWritable`) |
+| `@office-kit/xlsx/streaming`    | Read-only iter (`loadWorkbookStream`) + write-only append (`createWriteOnlyWorkbook`) |
+| `@office-kit/xlsx/workbook`     | `createWorkbook`, `addWorksheet`, defined names   |
+| `@office-kit/xlsx/worksheet`    | `setCell`, `getCell`, `mergeCells`, tables, …     |
+| `@office-kit/xlsx/cell`         | Cell value-model + inline rich text               |
+| `@office-kit/xlsx/styles`       | Fonts, fills, borders, alignment, number formats  |
+| `@office-kit/xlsx/chart`        | `c:` and `cx:` chart kinds                        |
+| `@office-kit/xlsx/chartsheet`   | Standalone chartsheets                            |
+| `@office-kit/xlsx/drawing`      | Anchors, images, chart placement                  |
+
+Other subpaths: `@office-kit/xlsx/packaging`, `@office-kit/xlsx/utils`, `@office-kit/xlsx/xml`,
+`@office-kit/xlsx/zip`, `@office-kit/xlsx/schema`. All exports are tree-shakable
+(`"sideEffects": false`).
+
+Bundle budgets (min + brotli):
+
+- `@office-kit/xlsx/streaming` ≤ 80 KB    (currently ~49 KB)
+- `@office-kit/xlsx/io` ≤ 120 KB           (currently ~85 KB)
+
+## Quick examples
+
+For a one-page lookup of task → exact functions to import and call, see
+the [Cheatsheet](https://baseballyama.github.io/@office-kit/xlsx/docs/cheatsheet).
+For prose-style worked examples (styling, charts, validation, streaming),
+see the [Recipes](https://baseballyama.github.io/@office-kit/xlsx/docs/recipes).
+
+### Read + edit + write
+
+```ts
+import { loadWorkbook, workbookToBytes } from '@office-kit/xlsx/io';
+import { setCell } from '@office-kit/xlsx/worksheet';
+import { fromBuffer } from '@office-kit/xlsx/node';
+import { readFile, writeFile } from 'node:fs/promises';
+
+const wb = await loadWorkbook(fromBuffer(await readFile('input.xlsx')));
+const sheet = wb.sheets[0];
+if (sheet?.kind === 'worksheet') {
+  setCell(sheet.sheet, /* row */ 1, /* col */ 1, 'Hello from @office-kit/xlsx');
+}
+await writeFile('output.xlsx', await workbookToBytes(wb));
+```
+
+### Read directly from disk (Node)
+
+```ts
+import { loadWorkbook, saveWorkbook } from '@office-kit/xlsx/io';
+import { fromFile, toFile } from '@office-kit/xlsx/node';
+
+const wb = await loadWorkbook(fromFile('input.xlsx'));
+// …mutate wb…
+await saveWorkbook(wb, toFile('output.xlsx'));
+```
+
+### Read directly from a `fetch` response (browser)
+
+```ts
+import { fromResponse, loadWorkbook } from '@office-kit/xlsx/io';
+
+const response = await fetch('/sheet.xlsx');
+const wb = await loadWorkbook(fromResponse(response));
+```
+
+### Streaming write — millions of rows in a fixed memory budget
+
+```ts
+import { createWriteOnlyWorkbook } from '@office-kit/xlsx/streaming';
+import { toFile } from '@office-kit/xlsx/node';
+
+const sink = toFile('big.xlsx');
+const wb = await createWriteOnlyWorkbook(sink);
+const ws = await wb.addWorksheet('Data');
+ws.setColumnWidth(1, 24); // must precede the first appendRow
+for (let r = 0; r < 10_000_000; r++) {
+  await ws.appendRow([r, `row-${r}`, r * Math.PI]);
+}
+await ws.close();
+await wb.finalize();
+```
+
+The streaming writer pushes each row through deflate as it arrives, and
+`toFile` forwards each deflated chunk to disk (honouring write-stream
+backpressure) — peak memory stays at one pending-row buffer plus deflate
+scratch, regardless of total archive size. The same is true of `toWritable`;
+buffered sinks (`toBuffer` / `toBlob` / `toArrayBuffer`) instead keep the
+full archive resident so `result()` can hand it back in one piece.
+
+### Streaming read — iterate row-by-row without materialising the sheet
+
+```ts
+import { loadWorkbookStream } from '@office-kit/xlsx/streaming';
+import { fromFile } from '@office-kit/xlsx/node';
+
+const wb = await loadWorkbookStream(fromFile('big.xlsx'));
+const sheet = wb.openWorksheet(wb.sheetNames[0] ?? '');
+for await (const row of sheet.iterRows({ minRow: 1, maxRow: 100 })) {
+  console.log(row.map((c) => c.value));
+}
+await wb.close();
+```
+
+The whole-sheet iteration path (default / `minRow <= 1`) inflates the
+worksheet entry chunk-by-chunk straight into the SAX parser, so the inflated
+worksheet body is never fully resident. Note: ZIP requires random access to
+its central directory, so the **compressed archive bytes are loaded up
+front**. A 200 MB compressed xlsx therefore needs ~200 MB resident, plus the
+inflate window + SAX state per active iterator — not the multi-GB inflated
+worksheet payload. Band queries (`minRow > 1`) build a row-offset index once
+per sheet, which does materialise that sheet's inflated bytes; subsequent
+band queries reuse the cached index.
+
+### Migrating from openpyxl
+
+@office-kit/xlsx is shaped after openpyxl, but a few defaults differ. The most
+common surprise for direct ports:
+
+- **`createWorkbook()` returns an empty workbook with no sheets.**
+  `openpyxl.Workbook()` creates a default sheet named `Sheet` that
+  callers usually remove with `wb.remove(wb.active)`. @office-kit/xlsx skips
+  that step — call `addWorksheet(wb, 'Data')` directly. Translating a
+  `remove(active)` call literally produces a no-op (or, worse, a guard
+  that hides a real bug elsewhere).
+- **`setCell(ws, row, col, value)`** is the @office-kit/xlsx equivalent of
+  openpyxl's `ws.cell(row=r, column=c, value=v)`. Coordinates are
+  1-based on both sides.
+- **`makeBorder({ left: makeSide({ style: 'thin' }) })`** is the
+  @office-kit/xlsx equivalent of openpyxl's
+  `Border(left=Side(style='thin'))`. Same with `makeFill`, `makeFont`,
+  etc. — every style primitive has a `make*` constructor under
+  `@office-kit/xlsx/styles`.
+
+## What's supported
+
+- ✅ Cell values: number, string (sharedStrings), boolean, error, formulas
+  (normal / array / shared / dataTable), inline rich text
+- ✅ Styles: Font, Fill, Border, Alignment, Protection, NumberFormat, full
+  Stylesheet pool with dedup, named styles + DXF
+- ✅ Worksheet rich features: mergedCells, sheetView/freezePanes, columnDims,
+  rowDims, hyperlinks, defined names, data validations, autoFilter, Tables,
+  legacy comments, conditional formatting
+- ✅ Drawings: anchors, images (PNG/JPEG/GIF/BMP/WebP/TIFF/SVG/EMF/WMF) with
+  format + dimension auto-detection, picture frames in worksheets and charts
+- ✅ Charts: 16 legacy `c:` chart kinds + 8 `cx:` chartex kinds (Sunburst,
+  Treemap, Waterfall, Histogram, Pareto, Funnel, BoxWhisker, RegionMap),
+  spPr / txPr / dLbls / trendline / errBars wiring, chartsheets, UserShapes
+- ✅ Pivot tables / VBA / OLE / threaded comments / external links / Power
+  Query metadata / customXml / customUI: byte-identical passthrough so
+  Excel 365 still renders parts we don't model. The `<workbook>` body
+  extras and per-sheet rels chain are preserved end-to-end.
+- ✅ Encrypted xlsx detection (CFB Compound Document magic): clear error
+  pointing at `msoffcrypto-tool` for decryption.
+- ✅ ZIP64 write — partial: workbooks with > 65 535 entries get a ZIP64 EOCD
+  record + locator spliced into the final chunk. Read works too. **Limit:**
+  individual entry sizes and the central-directory offset must still fit in
+  32 bits (≤ 4 GiB each); xlsx archives never approach that in practice, but
+  if you genuinely need a single >4 GiB entry the writer will throw. Tracked
+  in [`src/zip/zip64-patch.ts`][zip64-patch].
+
+[zip64-patch]: ./src/zip/zip64-patch.ts
+
+## Development
+
+The test suite reads fixtures from the `reference/openpyxl` git submodule, so
+clone with submodules (or run `pnpm install`, which auto-inits via the
+`prepare` script):
+
+```sh
+git clone --recursive https://github.com/office-kit/xlsx.git
+# or, if you already cloned without --recursive:
+git submodule update --init --recursive
+
+pnpm install
+pnpm typecheck
+pnpm lint
+pnpm test          # vitest, ~2100 tests
+pnpm test:perf     # write-only throughput + heap-budget bench
+pnpm build         # tsdown + tsc → dist/
+pnpm size          # size-limit guards on each bundle
+```
+
+[Nix flake](flake.nix) included — `nix develop` (or [direnv](https://direnv.net/)
+with `use flake`) gives a pinned Node 22 + pnpm 10 + Python 3 environment.
+
+## License
+
+MIT — see [LICENSE](LICENSE) and [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,56 @@
+# Third Party Notices
+
+`@office-kit/xlsx` is a TypeScript port of, and incorporates work derived from, the
+following projects.
+
+## openpyxl (MIT)
+
+Source: <https://foss.heptapod.net/openpyxl/openpyxl> (canonical, Mercurial),
+mirrored at <https://github.com/quintagroup/openpyxl> (Git, used as this
+repository's `reference/openpyxl` submodule for porting reference only).
+
+```
+Copyright (c) 2010 openpyxl
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+```
+
+## Runtime dependencies
+
+The following npm packages ship as part of `@office-kit/xlsx` at runtime. Each is
+licensed under its own terms — links go to the upstream repository where the
+license text lives.
+
+- **fflate** (MIT) — <https://github.com/101arrowz/fflate>
+  ZIP / DEFLATE I/O. Used by `src/zip/reader.ts` (`unzipSync` fallback +
+  `inflateSync`) and `src/zip/writer.ts` (`Zip` + `ZipDeflate` /
+  `ZipPassThrough` streaming-deflate writer).
+- **saxes** (ISC) — <https://github.com/lddubeau/saxes>
+  Streaming XML parser. Drives the SAX iter API in `src/xml/iterparse.ts`
+  which the streaming read-only path in `src/streaming/read-only.ts` uses.
+- **fast-xml-parser** (MIT) —
+  <https://github.com/NaturalIntelligence/fast-xml-parser>
+  DOM-style XML parser used by `src/xml/parser.ts` for the eager
+  load path; the streaming read-only path uses saxes instead.
+
+## Dev dependencies
+
+Dev-only dependencies declared in `package.json` (vitest, oxlint, tsdown,
+typescript, fast-check, size-limit, …) are subject to their upstream
+licenses; consult `pnpm-lock.yaml` for resolved versions.

package/dist/cell/cell.d.ts

@@ -0,0 +1,234 @@
+import { type RichText } from './rich-text';
+/** Excel error tokens. */
+export type ExcelErrorCode = '#NULL!' | '#DIV/0!' | '#VALUE!' | '#REF!' | '#NAME?' | '#NUM!' | '#N/A' | '#GETTING_DATA';
+/** Formula sub-kind — drives the OOXML `<f t="…">` attribute. */
+export type FormulaKind = 'normal' | 'array' | 'shared' | 'dataTable';
+export interface FormulaValue {
+    readonly kind: 'formula';
+    readonly formula: string;
+    readonly t: FormulaKind;
+    /** Cached value Excel last computed for the cell, used when `data_only` reads it back. */
+    readonly cachedValue?: number | string | boolean;
+    /** Range string (`"A1:A10"`) for array / shared / dataTable formulas. */
+    readonly ref?: string;
+    /** Shared-formula index. */
+    readonly si?: number;
+    /** Data-table specific fields (mirrors openpyxl DataTableFormula). */
+    readonly r1?: string;
+    readonly r2?: string;
+    readonly dt2D?: boolean;
+    readonly dtr?: boolean;
+    readonly del1?: boolean;
+    readonly del2?: boolean;
+    readonly aca?: boolean;
+    readonly ca?: boolean;
+}
+export type CellValue = number | string | boolean | Date | {
+    kind: 'duration';
+    ms: number;
+} | {
+    kind: 'error';
+    code: ExcelErrorCode;
+} | {
+    kind: 'rich-text';
+    runs: RichText;
+} | FormulaValue | null;
+export interface Cell {
+    /** 1-based row index. */
+    row: number;
+    /** 1-based column index. */
+    col: number;
+    /** Effective cell value. `null` represents an empty cell. */
+    value: CellValue;
+    /** Index into Workbook.styles.cellXfs. 0 = default. */
+    styleId: number;
+    /** Optional reference to a Hyperlink registered on the worksheet. */
+    hyperlinkId?: number;
+    /** Optional reference to a Comment registered on the worksheet. */
+    commentId?: number;
+}
+/** Marker subtype for the placeholder cells inside a merged range (top-left holds the value). */
+export interface MergedCell extends Cell {
+    merged: true;
+}
+/** Build a fresh Cell. Validates coordinates against the OOXML grid bounds. */
+export declare function makeCell(row: number, col: number, value?: CellValue, styleId?: number): Cell;
+/** Format a Cell's coordinate as the canonical "A1" string. */
+export declare function getCoordinate(c: Cell): string;
+/**
+ * Direct value setter. No type inference, no validation beyond the union — the
+ * caller is in charge. Use {@link bindValue} for the "do what I mean" path.
+ */
+export declare function setCellValue(c: Cell, value: CellValue): void;
+/**
+ * "Smart" setter: infers the cell value from a JS runtime value.
+ * - `string` starting with `=` → formula
+ * - `string` matching an Excel error token → error variant
+ * - other primitives / Date / null pass through verbatim
+ *
+ * Intentionally not the default — explicit is clearer for typed code, and
+ * inferring on every write costs measurable time on the worksheet write hot
+ * path.
+ */
+export declare function bindValue(c: Cell, value: number | string | boolean | Date | null): void;
+/** Plain `=A1+B1` style formula. Cached value is optional but recommended for round-trip. */
+export declare function setFormula(c: Cell, formula: string, opts?: {
+    cachedValue?: FormulaValue['cachedValue'];
+}): void;
+/** Array (CSE) formula spanning a `ref` range. */
+export declare function setArrayFormula(c: Cell, ref: string, formula: string, opts?: {
+    cachedValue?: FormulaValue['cachedValue'];
+}): void;
+/**
+ * Shared formula. The first cell in the group carries the formula text + ref;
+ * subsequent cells with the same `si` carry only the index and Excel
+ * reconstructs the formula via reference shifting.
+ */
+export declare function setSharedFormula(c: Cell, si: number, formula?: string, ref?: string, opts?: {
+    cachedValue?: FormulaValue['cachedValue'];
+}): void;
+/**
+ * Excel data-table formula (`<f t="dataTable">`). These appear as the "What-if
+ * Analysis → Data Table" feature output: a 1- or 2-variable sensitivity grid
+ * where the formula references one or two input cells. The wire format mirrors
+ * openpyxl's `DataTableFormula`:
+ *
+ * - `ref`     — inclusive cell range the formula spans.
+ * - `r1`, `r2`— input cell coordinates ("$A$1" etc.).
+ * - `dt2D`    — true for two-variable tables (uses both r1 and r2).
+ * - `dtr`     — row-direction flag (true) vs column-direction (false).
+ * - `del1`/`del2` — Excel marks one of these true when the
+ * corresponding input cell has been deleted; the formula keeps round-tripping
+ * so Excel can show the warning state.
+ * - `aca`/`ca` — alwaysCalculate / calculate flags.
+ */
+export interface DataTableFormulaOpts {
+    ref: string;
+    r1?: string;
+    r2?: string;
+    dt2D?: boolean;
+    dtr?: boolean;
+    del1?: boolean;
+    del2?: boolean;
+    aca?: boolean;
+    ca?: boolean;
+    cachedValue?: FormulaValue['cachedValue'];
+}
+/**
+ * Set a data-table formula on a cell. Preserves all the dt-specific attributes
+ * so the writer can re-emit `<f t="dataTable" r1="..." />` verbatim and Excel
+ * keeps treating the cell as a Data Table cell.
+ */
+export declare function setDataTableFormula(c: Cell, formula: string, opts: DataTableFormulaOpts): void;
+/** Build a `{ kind: 'error', code }` cell value. */
+export declare function makeErrorValue(code: ExcelErrorCode): {
+    kind: 'error';
+    code: ExcelErrorCode;
+};
+/** Build a `{ kind: 'duration', ms }` cell value. */
+export declare function makeDurationValue(ms: number): {
+    kind: 'duration';
+    ms: number;
+};
+/** True iff `c.value` is the formula variant. */
+export declare function isFormulaCell(c: Cell): boolean;
+/** True iff `c.value` is the rich-text variant. */
+export declare function isRichTextCell(c: Cell): boolean;
+/** Returns true iff the cell has no content. */
+export declare function isEmptyCell(c: Cell): boolean;
+/**
+ * Type guard for `MergedCell` — true iff the cell is a placeholder for a
+ * merged-range covered cell (the top-left of a merged range holds the value;
+ * the rest are `MergedCell`). Use this to filter merge-placeholders out of
+ * value-walking loops.
+ */
+export declare function isMergedCell(c: Cell): c is MergedCell;
+/** Returns true iff the cell holds an Excel error value (`#REF!`, `#NAME?`, …). */
+export declare function isErrorCell(c: Cell): boolean;
+/**
+ * Get the formula text from a formula-bearing cell, or `undefined` for
+ * non-formula cells. Equivalent to: isFormulaValue(c.value) ? c.value.formula :
+ * undefined but spares callers the type-narrow + member access.
+ */
+export declare function getFormulaText(c: Cell): string | undefined;
+/**
+ * Get the cached value Excel last computed for a formula cell, or `undefined`
+ * for non-formula / uncached cells. Useful for `data_only` read paths that want
+ * the displayed result without re-evaluating.
+ */
+export declare function getCachedFormulaValue(c: Cell): number | string | boolean | undefined;
+/** True iff `v` is the formula variant. */
+export declare function isFormulaValue(v: CellValue): v is FormulaValue;
+/** True iff `v` is the rich-text variant. */
+export declare function isRichTextValue(v: CellValue): v is {
+    kind: 'rich-text';
+    runs: RichText;
+};
+/** True iff `v` is the error variant. */
+export declare function isErrorValue(v: CellValue): v is {
+    kind: 'error';
+    code: ExcelErrorCode;
+};
+/** True iff `v` is the duration variant. */
+export declare function isDurationValue(v: CellValue): v is {
+    kind: 'duration';
+    ms: number;
+};
+export interface CellValueAsStringOptions {
+    /** Renderer for `Date` cells. Defaults to `d => d.toISOString()`. */
+    dateFormat?: (value: Date) => string;
+    /** Replacement for the `null` cell value. Defaults to `''`. */
+    emptyText?: string;
+}
+/**
+ * Coerce a CellValue to its plain-string display form. Numbers / booleans
+ * convert via `String`; rich text concatenates run text; formulas yield the
+ * cached value (or empty string when uncached); errors yield their Excel token;
+ * durations yield `"<ms> ms"` with no formatting; Dates yield
+ * `Date.toISOString()`; `null` yields `""`.
+ *
+ * Pass `opts.dateFormat` to override the Date renderer (e.g. a locale-specific
+ * format) and `opts.emptyText` to substitute a different placeholder for
+ * `null` cells.
+ */
+export declare function cellValueAsString(v: CellValue, opts?: CellValueAsStringOptions): string;
+/**
+ * Coerce a CellValue to `boolean | undefined`. Booleans pass through; `'TRUE'`
+ * / `'true'` and `'FALSE'` / `'false'` (case-insensitive) parse to true /
+ * false; numbers yield `false` for 0 and `true` for any other finite value
+ * (matching Excel's truthy-number coercion); formula cells return their cached
+ * boolean if any. Everything else (null, Date, error, duration, rich-text,
+ * non-bool strings) yields `undefined`.
+ */
+export declare function cellValueAsBoolean(v: CellValue): boolean | undefined;
+/**
+ * Coerce a CellValue to a `Date` when one is meaningful. Pass-through for
+ * `Date`-typed values; ISO-8601 strings (anything `new Date(s)` parses to a
+ * finite time) round-trip; durations are interpreted as `new Date(ms)`.
+ * Numbers, booleans, formulas, errors, rich text, and null all return
+ * `undefined` — this helper does **not** apply the Excel-serial-to-Date
+ * conversion (use `excelToDate` for that).
+ */
+export declare function cellValueAsDate(v: CellValue): Date | undefined;
+/**
+ * Coerce a CellValue to a number when one is meaningful. Booleans yield 0/1;
+ * numeric strings parse via `Number(s)`; rich-text concats then parses;
+ * formulas with a numeric cached value pass through. Returns `undefined` when
+ * there's no sensible numeric reading (text strings, errors, dates, durations,
+ * null, empty).
+ */
+export declare function cellValueAsNumber(v: CellValue): number | undefined;
+/**
+ * Map a CellValue to the most natural JS primitive for display / export.
+ * Unlike `cellValueAsString`/`cellValueAsNumber`/etc., which each force a
+ * single target type and return `undefined` when the value can't be coerced,
+ * this returns whatever primitive best represents the union variant:
+ *
+ * - `null` → `null`
+ * - `string` / `number` / `boolean` / `Date` → passthrough
+ * - rich text → joined run text (`string`)
+ * - formula → recursive on `cachedValue` (`null` when uncached)
+ * - error → error code (`string`)
+ * - duration → `ms` (`number`)
+ */
+export declare function cellValueAsPrimitive(v: CellValue): string | number | boolean | Date | null;

package/dist/cell/index.d.ts

@@ -0,0 +1,4 @@
+export type { Cell, CellValue, CellValueAsStringOptions, DataTableFormulaOpts, ExcelErrorCode, FormulaKind, FormulaValue, MergedCell, } from './cell';
+export { bindValue, cellValueAsBoolean, cellValueAsDate, cellValueAsNumber, cellValueAsPrimitive, cellValueAsString, getCachedFormulaValue, getCoordinate, getFormulaText, isDurationValue, isEmptyCell, isErrorCell, isErrorValue, isFormulaCell, isFormulaValue, isMergedCell, isRichTextCell, isRichTextValue, makeCell, makeDurationValue, makeErrorValue, setArrayFormula, setCellValue, setDataTableFormula, setFormula, setSharedFormula, } from './cell';
+export type { InlineFont, InlineUnderline, InlineVertAlign, RichText, TextRun, } from './rich-text';
+export { makeRichText, makeTextRun, richTextToString } from './rich-text';

package/dist/cell/rich-text.d.ts

@@ -0,0 +1,37 @@
+import type { Color } from '../styles/colors';
+/** Underline styles per openpyxl's cell-level NestedNoneSet. */
+export type InlineUnderline = 'single' | 'double' | 'singleAccounting' | 'doubleAccounting';
+export type InlineVertAlign = 'baseline' | 'superscript' | 'subscript';
+export interface InlineFont {
+    readonly name?: string;
+    readonly sz?: number;
+    readonly b?: boolean;
+    readonly i?: boolean;
+    readonly u?: InlineUnderline;
+    readonly strike?: boolean;
+    readonly outline?: boolean;
+    readonly shadow?: boolean;
+    readonly condense?: boolean;
+    readonly extend?: boolean;
+    readonly vertAlign?: InlineVertAlign;
+    readonly color?: Color;
+    readonly family?: number;
+    readonly charset?: number;
+    readonly scheme?: 'major' | 'minor';
+}
+export interface TextRun {
+    readonly text: string;
+    readonly font?: InlineFont;
+}
+/** A frozen array of TextRuns. The shared cell value shape under `kind: 'rich-text'`. */
+export type RichText = ReadonlyArray<TextRun>;
+export declare function makeTextRun(text: string, font?: InlineFont): TextRun;
+export declare function makeRichText(runs: ReadonlyArray<TextRun | {
+    text: string;
+    font?: InlineFont;
+}>): RichText;
+/**
+ * Concatenate the plain-text content of a rich-text value (rich-text
+ * read paths often want the raw text without formatting).
+ */
+export declare function richTextToString(rt: RichText): string;