odf-kit 0.9.9 → 0.10.1

package/CHANGELOG.md

@@ -5,6 +5,45 @@ 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.10.0] - 2026-04-12
+
+### Added
+
+- **`docxToOdt()`** — Convert `.docx` files directly to `.odt`. Pure ESM, zero new dependencies, runs in Node.js 22+ and browsers. No CommonJS, no LibreOffice, no intermediate HTML step. Available via `odf-kit/docx`.
+- **Native DOCX parser** — Reads the full DOCX ZIP structure: `word/document.xml`, `word/styles.xml`, `word/numbering.xml`, `word/_rels/document.xml.rels`, `word/footnotes.xml`, `word/endnotes.xml`, `word/header*.xml`, `word/footer*.xml`, `word/settings.xml`, `word/media/*`, `docProps/core.xml`.
+- **Content preserved:** paragraphs, headings (style-name and outlineLvl detection), bold, italic, underline, strikethrough, superscript/subscript, small caps, all caps, font size, font family, text color, highlight color, text alignment, paragraph spacing (before/after), line height, indentation (left, right, first-line/hanging), bullet lists, numbered lists (decimal, roman, alpha), nested lists, tables (column widths, merged cells — colSpan and rowSpan, cell background color, vertical alignment), hyperlinks (external and internal anchor), bookmarks (two-pass cross-paragraph resolution), images (actual EMU dimensions, not defaulted to 10cm), page layout (size, margins, orientation from `w:sectPr`), headers and footers, footnotes and endnotes, page breaks, tabs, line breaks, tracked changes (final-text mode — insertions included, deletions skipped).
+- **Metadata** — title, creator, description read from `docProps/core.xml` (Dublin Core / OCP core properties).
+- **Style inheritance** — `w:basedOn` chain walked at conversion time; each style layer correctly overrides its parent.
+- **Complex fields** — `w:fldChar`/`w:instrText` HYPERLINK fields handled via state machine in addition to `w:hyperlink` elements. `w:fldSimple` fields (including in headers/footers) also handled.
+- **`w:pict` legacy VML images** — Dimensions parsed from `v:shape style` attribute; image bytes loaded via `v:imagedata r:id`.
+- **`w:sdt` structured document tags** — Always unwrapped and processed; checkboxes rendered as ☐/☑.
+- **`pageBreakBefore`** paragraph property respected — emits a page break before the affected paragraph.
+- **`DocxToOdtOptions`** — `pageFormat`, `orientation`, `preservePageLayout` (default: true), `styleMap` (custom style name → heading level), `metadata` override.
+- **`DocxToOdtResult`** — `{ bytes: Uint8Array, warnings: string[] }`. Warnings report content that could not be fully converted (unrecognised fields, missing images, mid-document section breaks, etc.).
+- **`odf-kit/docx`** sub-export added.
+- **Deprecates** `@odf-kit/docx-to-odt` (CommonJS, browser-incompatible) — use `odf-kit/docx` instead.
+- Spec-validated against ECMA-376 5th edition Part 1 (WordprocessingML). Every XSD schema element verified against the authoritative spec PDF.
+- 117 new tests (1053 total, 23 test suites).
+- Landing page updated: eleven modes, all 11 code examples, updated stats.
+- New guide: [Convert DOCX to ODT in JavaScript](https://githubnewbie0.github.io/odf-kit/guides/docx-to-odt.html).
+- All 7 tool pages now linked from README and landing page footer.
+
+## [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 +225,8 @@ 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.10.0]: https://github.com/GitHubNewbie0/odf-kit/releases/tag/v0.10.0
+[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
@@ -204,3 +245,4 @@ Initial release. Complete ODT generation support.
 [0.3.0]: https://github.com/GitHubNewbie0/odf-kit/releases/tag/v0.3.0
 [0.2.0]: https://github.com/GitHubNewbie0/odf-kit/releases/tag/v0.2.0
 [0.1.0]: https://github.com/GitHubNewbie0/odf-kit/releases/tag/v0.1.0
+

package/README.md

@@ -1,6 +1,6 @@
 # odf-kit
 
-Generate, fill, read, and convert OpenDocument Format files (.odt, .ods) in TypeScript and JavaScript. Convert HTML, Markdown, and TipTap JSON to ODT. Works in Node.js and browsers. No LibreOffice dependency — pure spec-compliant ODF.
+Generate, fill, read, and convert OpenDocument Format files (.odt, .ods) in TypeScript and JavaScript. Convert HTML, Markdown, TipTap JSON, and DOCX to ODT. Works in Node.js and browsers. No LibreOffice dependency — pure spec-compliant ODF.
 
 **[Documentation & examples →](https://githubnewbie0.github.io/odf-kit/)**
 
@@ -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
+## Eleven 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";
 
@@ -137,6 +145,21 @@ writeFileSync("letter.typ", typst);
 execSync("typst compile letter.typ letter.pdf");
 ```
 
+```typescript
+// 11. Convert .docx to .odt — pure ESM, zero new dependencies, browser-safe
+import { docxToOdt } from "odf-kit/docx";
+
+const { bytes, warnings } = await docxToOdt(readFileSync("report.docx"));
+writeFileSync("report.odt", bytes);
+if (warnings.length > 0) console.warn(warnings);
+
+// With options
+const { bytes: bytes2 } = await docxToOdt(readFileSync("report.docx"), {
+  pageFormat: "letter",
+  styleMap: { "Section Title": 1 }, // map custom Word style → heading level
+});
+```
+
 ---
 
 ## Installation
@@ -152,6 +175,7 @@ import { OdtDocument, OdsDocument, htmlToOdt, markdownToOdt, tiptapToOdt, fillTe
 import { readOdt, odtToHtml } from "odf-kit/odt-reader";
 import { readOds, odsToHtml } from "odf-kit/ods-reader";
 import { odtToTypst, modelToTypst }          from "odf-kit/typst";
+import { docxToOdt }                         from "odf-kit/docx";
 ```
 
 Works in Node.js, browsers, Deno, Bun, and Cloudflare Workers. Runtime dependencies: [fflate](https://github.com/101arrowz/fflate) for ZIP, [marked](https://marked.js.org/) for Markdown parsing.
@@ -680,6 +704,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
@@ -694,6 +755,27 @@ execSync("typst compile letter.typ letter.pdf");
 
 ## API Reference
 
+### docxToOdt
+
+```typescript
+import { docxToOdt } from "odf-kit/docx"
+
+const { bytes, warnings } = await docxToOdt(input, options?)
+
+interface DocxToOdtOptions {
+  pageFormat?:         "A4" | "letter" | "legal" | "A3" | "A5";
+  orientation?:        "portrait" | "landscape";
+  preservePageLayout?: boolean;              // default: true — read layout from DOCX
+  styleMap?:           Record<string, number>; // custom style name → heading level
+  metadata?:           { title?: string; creator?: string; description?: string };
+}
+
+interface DocxToOdtResult {
+  bytes:    Uint8Array;   // the .odt file
+  warnings: string[];     // content that could not be fully converted
+}
+```
+
 ### htmlToOdt / markdownToOdt
 
 ```typescript
@@ -817,7 +899,7 @@ ESM only. Zero Node-specific APIs in the library source — enforced at the Type
 - **Two runtime dependencies** — fflate (ZIP) and marked (Markdown parsing). No transitive dependencies.
 - **Spec-compliant output** — every generated file passes the OASIS ODF validator. Enforced on every commit by CI.
 - **Multiple ODF formats** — ODT documents and ODS spreadsheets from the same library.
-- **Eight complete capability modes** — build ODT, build ODS, convert HTML→ODT, convert Markdown→ODT, convert TipTap JSON→ODT, fill templates, read, convert to Typst/PDF.
+- **Nine complete capability modes** — build ODT, build ODS, convert HTML→ODT, convert Markdown→ODT, convert TipTap JSON→ODT, convert DOCX→ODT, fill templates, read, convert to Typst/PDF.
 - **TipTap/ProseMirror integration** — direct JSON→ODT conversion for any TipTap-based editor, no intermediate HTML step.
 - **Zero-dependency Typst emitter** — the only JavaScript library with built-in ODT→Typst conversion for PDF generation.
 - **TypeScript-first** — full types across all sub-exports.
@@ -834,6 +916,7 @@ ESM only. Zero Node-specific APIs in the library source — enforced at the Type
 | Convert HTML → ODT | ✅ | ❌ | ❌ |
 | Convert Markdown → ODT | ✅ | ❌ | ❌ |
 | Convert TipTap JSON → ODT | ✅ | ❌ | ❌ |
+| Convert DOCX → ODT | ✅ native, browser-safe | ❌ | ❌ |
 | Fill .odt templates | ✅ | ❌ | ✅ .docx only |
 | Read .odt files | ✅ | ❌ | ❌ |
 | Convert to HTML | ✅ | ❌ | ❌ |
@@ -852,6 +935,10 @@ odf-kit targets ODF 1.2 (ISO/IEC 26300). Generated files include proper ZIP pack
 
 ## Version history
 
+**v0.10.0** — `docxToOdt()` via `odf-kit/docx`. Native DOCX→ODT converter — pure ESM, zero new dependencies, browser-safe. Preserves text, headings, formatting, tables, lists, images (actual dimensions), hyperlinks, bookmarks, footnotes, page layout, headers/footers, and tracked changes. Spec-validated against ECMA-376 5th edition. 1053 tests passing.
+
+**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.
@@ -886,14 +973,20 @@ odf-kit targets ODF 1.2 (ISO/IEC 26300). Generated files include proper ZIP pack
 - [Generate ODT files in the browser](https://githubnewbie0.github.io/odf-kit/guides/generate-odt-browser.html)
 - [Fill ODT templates in JavaScript](https://githubnewbie0.github.io/odf-kit/guides/fill-odt-template-javascript.html)
 - [Convert ODT to HTML in JavaScript](https://githubnewbie0.github.io/odf-kit/guides/odt-to-html-javascript.html)
+- [Convert DOCX to ODT in JavaScript](https://githubnewbie0.github.io/odf-kit/guides/docx-to-odt.html)
 - [ODT to PDF via Typst](https://githubnewbie0.github.io/odf-kit/guides/odt-to-typst-pdf.html)
 - [Generate ODT without LibreOffice](https://githubnewbie0.github.io/odf-kit/guides/generate-odt-without-libreoffice.html)
 - [ODF government compliance](https://githubnewbie0.github.io/odf-kit/guides/odf-government-compliance.html)
 - [simple-odf alternative](https://githubnewbie0.github.io/odf-kit/guides/simple-odf-alternative.html)
 - [docxtemplater alternative for ODF](https://githubnewbie0.github.io/odf-kit/guides/docxtemplater-odf-alternative.html)
 - [ODT JavaScript ecosystem](https://githubnewbie0.github.io/odf-kit/guides/odt-javascript-ecosystem.html)
+- [Free DOCX to ODT converter (online tool)](https://githubnewbie0.github.io/odf-kit/tools/docx-to-odt.html)
 - [Free ODT to HTML converter (online tool)](https://githubnewbie0.github.io/odf-kit/tools/odt-to-html.html)
 - [Free ODT to PDF converter (online tool)](https://githubnewbie0.github.io/odf-kit/tools/odt-to-pdf.html)
+- [Free XLSX to ODS converter (online tool)](https://githubnewbie0.github.io/odf-kit/tools/xlsx-to-ods.html)
+- [Free Markdown to ODT converter (online tool)](https://githubnewbie0.github.io/odf-kit/tools/markdown-to-odt.html)
+- [Free HTML to ODT converter (online tool)](https://githubnewbie0.github.io/odf-kit/tools/html-to-odt.html)
+- [Free ODS to HTML converter (online tool)](https://githubnewbie0.github.io/odf-kit/tools/ods-to-html.html)
 
 ---
 

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"}