@docen/docx 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Demo Macro
+
+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,156 @@
+# @docen/docx
+
+![npm version](https://img.shields.io/npm/v/@docen/docx)
+![npm downloads](https://img.shields.io/npm/dw/@docen/docx)
+![npm license](https://img.shields.io/npm/l/@docen/docx)
+
+> DOCX editor and converter powered by @office-open/docx with Tiptap editing layer, supporting bidirectional conversion between DOCX, HTML, and Markdown.
+
+## Features
+
+- 📝 **Tiptap Editor** — Full-featured WYSIWYG editor with DOCX-aware extensions
+- 🔄 **DOCX Round-trip** — Near-lossless DOCX ↔ Editor conversion via @office-open/docx
+- 🌐 **HTML Conversion** — Bidirectional Tiptap JSON ↔ HTML (editor path + standalone)
+- 📄 **Markdown Support** — Tiptap JSON ↔ Markdown conversion
+- 🎨 **DOCX Properties** — Custom Tiptap extensions carry shading, borders, indent, spacing, floating, crop
+- 🔗 **Template Patching** — Replace `{{placeholders}}` in DOCX templates with Tiptap-JSON content
+
+## Installation
+
+```bash
+# Install with pnpm
+$ pnpm add @docen/docx
+
+# Install with npm
+$ npm install @docen/docx
+```
+
+## Quick Start
+
+```typescript
+import { createDocxEditor, docxExtensions, parseDOCX, generateDOCX } from "@docen/docx";
+
+// Create editor
+const editor = createDocxEditor({
+  element: document.querySelector("#editor"),
+});
+
+// Load a DOCX file
+editor.commands.setContent(parseDOCX(buffer));
+
+// Save back to DOCX
+const output = await generateDOCX(editor.getJSON());
+```
+
+## API
+
+### Standalone Functions (Core)
+
+These work without an editor instance — for headless/server/batch use.
+
+```typescript
+import {
+  parseDOCX,
+  generateDOCX,
+  generateDOCXSync,
+  generateDOCXStream,
+  parseHTML,
+  generateHTML,
+  parseMarkdown,
+  generateMarkdown,
+} from "@docen/docx";
+
+// DOCX pipeline: DOCX binary ↔ Tiptap JSON
+const json = parseDOCX(buffer); // → JSONContent
+const buffer = await generateDOCX(json); // → Buffer (pre-fetches http images by default)
+const blob = await generateDOCX(json, { packer: { type: "blob" } }); // → Blob
+const sync = generateDOCXSync(json); // → Buffer (skips prepare)
+const stream = await generateDOCXStream(json); // → ReadableStream<Uint8Array>
+
+// HTML pipeline: HTML string ↔ Tiptap JSON
+const json = parseHTML("<p>Hello</p>"); // → JSONContent
+const html = generateHTML(json); // → string
+
+// Markdown pipeline: Markdown string ↔ Tiptap JSON
+const json = parseMarkdown("# Hello"); // → JSONContent
+const md = generateMarkdown(json); // → string
+```
+
+### Editor
+
+```typescript
+import { createDocxEditor, docxExtensions } from "@docen/docx";
+
+const editor = createDocxEditor({
+  element: document.querySelector("#editor"),
+  extensions: docxExtensions,
+  spellcheck: true,
+  editable: true,
+});
+```
+
+### Extension Commands (Thin Wrappers)
+
+Convenience commands that call standalone functions internally.
+
+```typescript
+// Load DOCX into editor (calls parseDOCX → setContent)
+editor.commands.importDocx(buffer);
+
+// Export editor content as DOCX (calls getJSON → generateDOCX)
+const buffer = await editor.commands.exportDocx();
+```
+
+### Template Patching
+
+Replace `{{placeholders}}` in a DOCX template with Tiptap-JSON content. Each
+patch's `content` is prepared (default: fetch http images) then compiled to DOCX.
+
+```typescript
+import { patchDOCX, parseHTML } from "@docen/docx";
+
+const result = await patchDOCX({
+  template: templateBuffer,
+  patches: {
+    title: { content: parseHTML("<h1>Report</h1>") },
+  },
+  outputType: "nodebuffer",
+});
+```
+
+### Advanced: Model Bridge
+
+`generateDOCX` runs `prepareDocument → compileDocument → generateDocument`
+internally. You rarely need these directly — reach for them only when working
+with the intermediate `DocumentOptions` (the OOXML persistence model):
+
+```typescript
+import { resolveDocument, compileDocument, prepareDocument } from "@docen/docx";
+
+const json = resolveDocument(docOpts); // DocumentOptions → JSONContent
+const docOpts = compileDocument(json); // JSONContent → DocumentOptions
+await prepareDocument(json); // in place: http image URLs → data URLs
+```
+
+## Architecture
+
+```
+Standalone Functions (core)
+  parseDOCX / generateDOCX / generateDOCXSync / generateDOCXStream / patchDOCX
+  parseHTML / generateHTML / parseMarkdown / generateMarkdown
+  resolveDocument / compileDocument / prepareDocument  (model bridge, advanced)
+        ↕ used by
+Tiptap Extension Commands (thin wrappers)
+  editor.commands.importDocx() / exportDocx()
+        ↕ used by
+@docen/ui (Fluent UI Web Components)
+  <docx-editor> toolbar / ribbon / menus
+```
+
+- **Runtime model**: Tiptap JSON with DOCX-rich attributes via custom extensions
+- **Persistence model**: DocumentOptions (complete OOXML expressiveness)
+- **Standalone functions are core** — extension commands are thin wrappers
+
+## License
+
+- [MIT](LICENSE) &copy; [Demo Macro](https://www.demomacro.com/)

package/dist/converters/docx.d.mts

@@ -0,0 +1,110 @@
+import { a as JSONContent } from "../core-omBKMRtl.mjs";
+import { PrepareStep } from "./prepare.mjs";
+import { DocumentOptions, OutputByType, OutputType, PackerOptions, parseDocument } from "@office-open/docx";
+
+//#region src/converters/docx.d.ts
+/**
+ * Manages DOCX serialization (Tiptap JSON ↔ DocumentOptions).
+ *
+ * Each extension provides renderDocx/parseDocx for its own attrs mapping.
+ * DocxManager handles tree walking, child assembly, and dispatching.
+ */
+declare class DocxManager {
+  compile(json: JSONContent): DocumentOptions;
+  resolve(docOpts: DocumentOptions): JSONContent;
+  private compileSectionChild;
+  private compileParagraphNode;
+  private compileHeadingNode;
+  private compileCodeBlock;
+  /** Simple text optimization: merge plain runs into text field */
+  private simplifyParagraph;
+  private compileTableNode;
+  /** Count grid columns from the first table row (summing colspan). */
+  private getTableColumnCount;
+  /**
+   * Compute tblGrid column widths (twips) from first-row cell colwidth attrs.
+   * Returns columnWidths array and the appropriate tableWidth.
+   */
+  private computeColumnWidths;
+  private compileTableCellNode;
+  private compileListFromNode;
+  private compileInlineContent;
+  private compileTextNode;
+  private resolveSectionChild;
+  private resolveParagraph;
+  private resolveListItem;
+  private resolveTable;
+  /**
+   * Resolve a paragraph's inline content. @office-open collapses a plain-text
+   * paragraph (a single run with no properties) to a bare string or a `{ text }`
+   * object with no `children` — recover that text here so it round-trips back to
+   * a text node instead of being dropped.
+   */
+  private resolveInlineContent;
+  private resolveParagraphChildren;
+  private resolveParagraphChild;
+  private resolveRun;
+  private resolveMarks;
+  private resolveImage;
+  private resolveHyperlink;
+}
+/**
+ * Parse a DOCX file into Tiptap JSON (runtime model).
+ *
+ * Combines @office-open/docx's `parseDocument` (DOCX binary → DocumentOptions)
+ * with `DocxManager.resolve` (DocumentOptions → Tiptap JSON).
+ */
+declare function parseDOCX(data: Parameters<typeof parseDocument>[0]): JSONContent;
+/**
+ * Options for {@link generateDOCX} / {@link generateDOCXStream}.
+ */
+interface DocxGenerateOptions<T extends OutputType = "nodebuffer"> {
+  /**
+   * Pre-compilation steps run on the JSON in place (default: `prepareImages()`).
+   * - `true` / `undefined`: default image pre-fetch (http(s) → embedded data URL)
+   * - `false`: skip preparation
+   * - `PrepareStep[]`: custom steps
+   *
+   * Required for http image URLs — image `renderDocx` drops images without
+   * embedded data (see extensions/image.ts). Mutates the JSON, like `prepareDocument`.
+   */
+  prepare?: boolean | PrepareStep[];
+  /** Packer options; `type` controls the output format (default `"nodebuffer"` → Buffer). */
+  packer?: PackerOptions<T>;
+}
+/**
+ * Generate a DOCX file from Tiptap JSON (runtime model), asynchronously.
+ *
+ * Pipeline: `prepareDocument` (default: fetch http images, in place) →
+ * `DocxManager.compile` → @office-open/docx's `generateDocument`. `packer.type`
+ * controls the output format (default: `"nodebuffer"` → Buffer). Non-blocking
+ * (fflate Web Workers). With the default `prepare`, the input `json` is mutated
+ * in place (http image URLs become embedded data URLs).
+ */
+declare function generateDOCX<T extends OutputType = "nodebuffer">(json: JSONContent, options?: DocxGenerateOptions<T>): Promise<OutputByType[T]>;
+/**
+ * Generate a DOCX file synchronously — fastest throughput, blocks the event loop.
+ *
+ * Pipeline: `DocxManager.compile` → `generateDocumentSync`. Does **not** run
+ * `prepareDocument` (it is async); call `await prepareDocument(json)` first
+ * when http images need embedding.
+ */
+declare function generateDOCXSync<T extends OutputType = "nodebuffer">(json: JSONContent, packerOptions?: PackerOptions<T>): OutputByType[T];
+/**
+ * Generate a DOCX file as a `ReadableStream<Uint8Array>` — for large documents
+ * or streaming HTTP responses.
+ *
+ * Pipeline: `prepareDocument` (default: fetch http images, in place) →
+ * `DocxManager.compile` → `generateDocumentStream`. Async due to preparation.
+ */
+declare function generateDOCXStream(json: JSONContent, options?: DocxGenerateOptions): Promise<ReadableStream<Uint8Array>>;
+/**
+ * Convert DocumentOptions (persistence model) to Tiptap JSON (runtime model).
+ */
+declare function resolveDocument(docOpts: DocumentOptions): JSONContent;
+/**
+ * Convert Tiptap JSON (runtime model) to DocumentOptions (persistence model).
+ */
+declare function compileDocument(json: JSONContent): DocumentOptions;
+//#endregion
+export { type DocumentOptions, DocxGenerateOptions, DocxManager, compileDocument, generateDOCX, generateDOCXStream, generateDOCXSync, parseDOCX, resolveDocument };