odf-kit 0.9.9 → 0.10.0

package/CHANGELOG.md

@@ -5,6 +5,22 @@ All notable changes to odf-kit will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.9.9] - 2026-04-11
+
+### Added
+
+- **`xlsxToOds()`** — Convert an `.xlsx` file to an `.ods` file. Available via `odf-kit/xlsx`. Zero new dependencies — parses XLSX XML directly using fflate (already present) and odf-kit's existing XML parser.
+- **XLSX parser** — Reads `xl/workbook.xml`, `xl/_rels/workbook.xml.rels`, `xl/sharedStrings.xml`, `xl/styles.xml`, and `xl/worksheets/sheet*.xml`. No dependency on SheetJS or any external library.
+- **Cell types supported:** string, number, boolean, date (with Excel serial → `Date` conversion including Lotus 1900 leap year bug correction), formula (cached result + formula string), error (as string).
+- **Date detection** — Built-in XLSX date format IDs (14–17, 22, 27–36, 45–47, 50–58) plus custom format code analysis.
+- **Merged cells** — `colSpan`/`rowSpan` preserved via `<mergeCells>` parsing.
+- **Freeze rows/columns** — Detected from `<pane state="frozen">` in sheet XML.
+- **Multi-sheet workbooks** — All sheets converted in tab order.
+- **`readXlsx()`** — Lower-level function returning an `XlsxWorkbook` intermediate model. Exported from `odf-kit/xlsx` for callers who need the parsed model directly.
+- **`odf-kit/xlsx`** sub-export added.
+- Supports `.xlsx` and `.xlsm` (macro-enabled, same XML structure). Does not support legacy `.xls` (binary) or `.xlsb` (binary XML).
+- 47 new tests (936 total).
+
 ## [0.9.8] - 2026-04-10
 
 ### Added
@@ -186,6 +202,7 @@ Initial release. Complete ODT generation support.
 - Tables, page layout, headers/footers, page breaks, lists, tab stops.
 - Method chaining. Full TypeScript types. ESM-only, Node.js 22+. 102 tests.
 
+[0.9.9]: https://github.com/GitHubNewbie0/odf-kit/releases/tag/v0.9.9
 [0.9.8]: https://github.com/GitHubNewbie0/odf-kit/releases/tag/v0.9.8
 [0.9.7]: https://github.com/GitHubNewbie0/odf-kit/releases/tag/v0.9.7
 [0.9.6]: https://github.com/GitHubNewbie0/odf-kit/releases/tag/v0.9.6

package/README.md

@@ -8,7 +8,7 @@ Generate, fill, read, and convert OpenDocument Format files (.odt, .ods) in Type
 npm install odf-kit
 ```
 
-## Nine ways to work with ODF files
+## Ten ways to work with ODF files
 
 ```typescript
 // 1. Build an ODT document from scratch
@@ -128,7 +128,15 @@ const html  = odsToHtml(bytes);            // HTML table string
 ```
 
 ```typescript
-// 9. Convert .odt to Typst for PDF generation
+// 9. Convert .xlsx to .ods — no external dependencies
+import { xlsxToOds } from "odf-kit/xlsx"
+
+const bytes = await xlsxToOds(readFileSync("report.xlsx"))
+writeFileSync("report.ods", bytes)
+```
+
+```typescript
+// 10. Convert .odt to Typst for PDF generation
 import { odtToTypst } from "odf-kit/typst";
 import { execSync } from "child_process";
 
@@ -680,6 +688,43 @@ Primary cells have `colSpan` and/or `rowSpan`. Covered cells have `type: "covere
 
 ---
 
+## Convert: XLSX → ODS
+
+`odf-kit/xlsx` converts `.xlsx` spreadsheets to `.ods` with no external dependencies — parses XLSX XML directly using fflate (already in odf-kit) and our own XML parser. Supports `.xlsx` and `.xlsm`. Does not support legacy `.xls` (binary format).
+
+```typescript
+import { xlsxToOds } from "odf-kit/xlsx"
+import { readFileSync, writeFileSync } from "fs"
+
+// Simple conversion
+const bytes = await xlsxToOds(readFileSync("report.xlsx"))
+writeFileSync("report.ods", bytes)
+
+// With options
+const bytes2 = await xlsxToOds(readFileSync("report.xlsx"), {
+  dateFormat: "DD/MM/YYYY",
+  metadata: { title: "Q4 Report", creator: "Alice" },
+})
+
+// Works with ArrayBuffer too (browser-friendly)
+const bytes3 = await xlsxToOds(arrayBuffer)
+```
+
+**What is preserved:**
+- All sheets in tab order, with their names
+- Cell values: strings, numbers, booleans, dates, formula cached results
+- Formula strings
+- Merged cells (colSpan/rowSpan)
+- Freeze rows/columns
+- Multiple sheets
+
+**What is not preserved** (out of scope for v0.9.9):
+- Cell formatting (colors, fonts, borders)
+- Column widths and row heights
+- Charts, images, pivot tables
+
+---
+
 ## Typst: ODT to PDF
 
 ```typescript
@@ -852,6 +897,8 @@ odf-kit targets ODF 1.2 (ISO/IEC 26300). Generated files include proper ZIP pack
 
 ## Version history
 
+**v0.9.9** — `xlsxToOds()` via `odf-kit/xlsx`. XLSX→ODS conversion with zero new dependencies. 936 tests passing.
+
 **v0.9.8** — ODS reader: `readOds()` and `odsToHtml()` via `odf-kit/ods-reader`. Typed values, formula strings, merged cell handling, formatting, metadata. `odf-kit/odt-reader` alias added. 889 tests passing.
 
 **v0.9.7** — ODS enhancements: number formats (integer, decimal:N, percentage, currency), merged cells (colSpan/rowSpan), freeze rows/columns, hyperlinks in cells, sheet tab color. 849 tests passing.

package/dist/docx/body-reader.d.ts

@@ -0,0 +1,54 @@
+/**
+ * odf-kit — DOCX body reader
+ *
+ * Walks the w:body element from word/document.xml and converts it into the
+ * DocxBodyElement[] model. Also used to parse footnote/endnote/header/footer
+ * XML bodies, which share the same paragraph/table structure.
+ *
+ * Design decisions:
+ *  - Only explicitly present XML properties are stored — no style inheritance
+ *    resolution. The converter walks the basedOn chain at conversion time.
+ *  - Mid-paragraph page breaks split the paragraph:
+ *    [DocxParagraph (before), DocxPageBreak, DocxParagraph (after)]
+ *  - Field state machine runs on every paragraph — handles both w:hyperlink
+ *    elements and complex HYPERLINK fields (w:fldChar / w:instrText).
+ *  - w:pict (legacy VML) images are fully handled via v:imagedata + v:shape.
+ *  - w:sdt content is always processed; checkboxes get special rendering.
+ *  - Tracked changes: w:ins / w:moveTo children are processed;
+ *    w:del / w:moveFrom children are skipped.
+ *  - Two-pass bookmark resolution: pass 1 collects all bookmark id→name
+ *    mappings across the entire body; pass 2 emits bookmark elements using
+ *    the pre-built map. This correctly handles cross-paragraph bookmarks.
+ *  - Spec reference: ECMA-376 5th edition Part 1, §17 (WordprocessingML).
+ *    CT_Body child elements validated against §17.2.2.
+ */
+import type { DocxBodyElement, DocxNote, RelationshipMap, StyleMap, NumberingMap } from "./types.js";
+export interface BodyReaderContext {
+    styles: StyleMap;
+    numbering: NumberingMap;
+    relationships: RelationshipMap;
+    /** id → name map built by collectBookmarkNames() before the main walk. */
+    bookmarkNames: Map<string, string>;
+    warnings: string[];
+}
+/**
+ * Parse a body XML string into a DocxBodyElement array.
+ *
+ * Used for: word/document.xml (rootTag="body"), word/header*.xml (rootTag="hdr"),
+ * word/footer*.xml (rootTag="ftr"). Footnote/endnote XML uses readNotes().
+ *
+ * @param xml     - Raw XML string.
+ * @param rootTag - Local name of the container element, e.g. "body", "hdr", "ftr".
+ * @param ctx     - Shared reader context.
+ */
+export declare function readBody(xml: string, rootTag: string, ctx: BodyReaderContext): DocxBodyElement[];
+/**
+ * Parse footnote/endnote XML into a Map<id, DocxNote>.
+ * Handles both word/footnotes.xml and word/endnotes.xml.
+ *
+ * @param xml     - Raw XML string.
+ * @param noteTag - "footnote" | "endnote".
+ * @param ctx     - Shared reader context.
+ */
+export declare function readNotes(xml: string, noteTag: "footnote" | "endnote", ctx: BodyReaderContext): Map<string, DocxNote>;
+//# sourceMappingURL=body-reader.d.ts.map

package/dist/docx/body-reader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"body-reader.d.ts","sourceRoot":"","sources":["../../src/docx/body-reader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAMH,OAAO,KAAK,EACV,eAAe,EAcf,QAAQ,EAGR,eAAe,EACf,QAAQ,EACR,YAAY,EACb,MAAM,YAAY,CAAC;AAOpB,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,QAAQ,CAAC;IACjB,SAAS,EAAE,YAAY,CAAC;IACxB,aAAa,EAAE,eAAe,CAAC;IAC/B,0EAA0E;IAC1E,aAAa,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAMD;;;;;;;;;GASG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,iBAAiB,GAAG,eAAe,EAAE,CAShG;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CACvB,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,UAAU,GAAG,SAAS,EAC/B,GAAG,EAAE,iBAAiB,GACrB,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAC,CA0BvB"}