odf-kit 0.10.0 → 0.10.1

package/CHANGELOG.md

@@ -5,6 +5,29 @@ 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
@@ -202,6 +225,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.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
@@ -221,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
 ```
 
-## Ten ways to work with ODF files
+## Eleven ways to work with ODF files
 
 ```typescript
 // 1. Build an ODT document from scratch
@@ -145,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
@@ -160,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.
@@ -739,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
@@ -862,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.
@@ -879,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 | ✅ | ❌ | ❌ |
@@ -897,6 +935,8 @@ 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.
@@ -933,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "odf-kit",
-  "version": "0.10.0",
+  "version": "0.10.1",
   "description": "Generate, fill, read, and convert OpenDocument Format (.odt) files in JavaScript and TypeScript. Works in Node.js and browsers.",
   "type": "module",
   "main": "./dist/index.js",
@@ -47,6 +47,37 @@
       "import": "./dist/docx/index.js"
     }
   },
+  "typesVersions": {
+    "*": {
+      "odt": [
+        "./dist/odt/index.d.ts"
+      ],
+      "odt-reader": [
+        "./dist/reader/index.d.ts"
+      ],
+      "ods": [
+        "./dist/ods/index.d.ts"
+      ],
+      "ods-reader": [
+        "./dist/ods-reader/index.d.ts"
+      ],
+      "xlsx": [
+        "./dist/xlsx/index.d.ts"
+      ],
+      "template": [
+        "./dist/template/index.d.ts"
+      ],
+      "reader": [
+        "./dist/reader/index.d.ts"
+      ],
+      "typst": [
+        "./dist/typst/index.d.ts"
+      ],
+      "docx": [
+        "./dist/docx/index.d.ts"
+      ]
+    }
+  },
   "files": [
     "dist",
     "LICENSE",