@docen/docx 0.3.0 → 0.3.2

package/README.md

@@ -6,6 +6,8 @@
 
 > DOCX editor and converter powered by @office-open/docx with Tiptap editing layer, supporting bidirectional conversion between DOCX, HTML, and Markdown.
 
+> Need a ready-made visual editor? [`@docen/editor`](../editor/README.md) wraps this engine in a Fluent UI shell with the turnkey `<docen-document>` super-component.
+
 ## Features
 
 - 📝 **Tiptap Editor** — Full-featured WYSIWYG editor with DOCX-aware extensions
@@ -142,9 +144,6 @@ Standalone Functions (core)
         ↕ 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

package/dist/converters/docx.d.mts

@@ -1,4 +1,4 @@
-import { a as JSONContent } from "../core-omBKMRtl.mjs";
+import { a as JSONContent } from "../core-C9VunJ8o.mjs";
 import { PrepareStep } from "./prepare.mjs";
 import { DocumentOptions, OutputByType, OutputType, PackerOptions, parseDocument } from "@office-open/docx";
 
@@ -10,12 +10,26 @@ import { DocumentOptions, OutputByType, OutputType, PackerOptions, parseDocument
  * DocxManager handles tree walking, child assembly, and dispatching.
  */
 declare class DocxManager {
+  private numberingConfigs;
+  private orderedInstanceCounter;
+  private resolveStyles;
   compile(json: JSONContent): DocumentOptions;
+  /** Assemble a SectionOptions from compiled children + optional layout/headers/footers. */
+  private buildSection;
+  /**
+   * Compile resolved header/footer slots (JSONContent[] per slot) back into
+   * SectionChild[] per slot. Returns undefined when no slot has content.
+   */
+  private compileHeaderFooter;
+  /**
+   * Resolve a section's header/footer group (SectionChild[] per slot) into
+   * Tiptap JSON slots. Returns null when no slot has content.
+   */
+  private resolveHeaderFooter;
   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;
@@ -28,11 +42,74 @@ declare class DocxManager {
   private computeColumnWidths;
   private compileTableCellNode;
   private compileListFromNode;
+  /**
+   * Register (or reuse) an abstractNum for an ordered list's `start`, and
+   * return a fresh instance so this list counts independently of other lists
+   * that share the same definition.
+   */
+  private registerOrderedNumbering;
+  /**
+   * Prepend an inline checkbox SDT to a task paragraph. The SDT is tagged
+   * "docen-task" so resolve can tell task items apart from ordinary paragraphs
+   * that happen to contain an SDT.
+   */
+  private injectTaskCheckbox;
+  /**
+   * details → block-level group-SDT. The summary paragraph is tagged with a
+   * fixed style so resolve can split it back out; content blocks flatten in
+   * after it. (No native collapse in DOCX — structure round-trips, the view
+   * stays expanded.)
+   */
+  private compileDetailsNode;
   private compileInlineContent;
   private compileTextNode;
+  /** Emit a single run for `text` with all inline marks applied. */
+  private compileTextRun;
   private resolveSectionChild;
+  /** Wrap an opaque SectionChild in a passthrough atom (attrs.data = JSON). */
+  private resolvePassthrough;
+  /**
+   * Resolve a details group-SDT: the summary-style paragraph becomes
+   * detailsSummary, the remaining blocks fold into detailsContent.
+   */
+  private resolveDetailsSdt;
   private resolveParagraph;
-  private resolveListItem;
+  /** Look up a paragraph style's NAME from its styleId, via the styles table
+   *  carried on the current resolve(). Returns undefined outside resolve. */
+  private styleNameOf;
+  /** reference → level-0 format/start, for classifying numbering paragraphs. */
+  private buildNumberingLookup;
+  /**
+   * Walk section children, grouping consecutive list paragraphs into nested
+   * Tiptap lists. Non-list children resolve individually. DOCX flattens lists
+   * to a paragraph sequence (depth carried by `level`); this rebuilds the tree.
+   */
+  private resolveSectionChildren;
+  /** Classify a paragraph as a list item, or null if it isn't one. */
+  private detectList;
+  /**
+   * Rebuild nested Tiptap lists from a flat run of list paragraphs. Stack-based:
+   * each frame is an active list at a given depth; the `key` (level:type:
+   * reference) decides whether a paragraph continues the top list, starts a
+   * nested list, or splits off a new sibling list.
+   */
+  private buildListTree;
+  /** Classify a paragraph as a blockquote member by its signature. */
+  private detectBlockquote;
+  /**
+   * Rebuild a blockquote node from a run of signature-carrying paragraphs,
+   * stripping the indent/border signature so child paragraphs render clean.
+   */
+  private buildBlockquote;
+  /**
+   * Resolve a list-item paragraph to a Tiptap paragraph/heading node, stripping
+   * the list marker (bullet/numbering) and the leading task checkbox — those
+   * are expressed at the list/item level, not inside the paragraph.
+   */
+  private resolveListItemParagraph;
+  /** Return a copy of `para` with its leading docen-task checkbox SDT removed. */
+  private stripTaskCheckbox;
+  private resolveCodeBlock;
   private resolveTable;
   /**
    * Resolve a paragraph's inline content. @office-open collapses a plain-text
@@ -43,6 +120,8 @@ declare class DocxManager {
   private resolveInlineContent;
   private resolveParagraphChildren;
   private resolveParagraphChild;
+  /** Resolve an inline SDT (mention carrier; other inline SDTs unsupported). */
+  private resolveInlineSdt;
   private resolveRun;
   private resolveMarks;
   private resolveImage;
@@ -71,6 +150,17 @@ interface DocxGenerateOptions<T extends OutputType = "nodebuffer"> {
   prepare?: boolean | PrepareStep[];
   /** Packer options; `type` controls the output format (default `"nodebuffer"` → Buffer). */
   packer?: PackerOptions<T>;
+  /**
+   * Document-level options injected into the compiled `DocumentOptions` — core
+   * properties (`title`/`creator`/`description`/…), `styles`/`externalStyles`,
+   * `background`, `features`, `fonts`, etc. Excludes `sections` (always compiled
+   * from the JSON) and `numbering` (collected from ordered-list nodes).
+   *
+   * `styles`/`externalStyles` here take precedence over any `styles` carried on
+   * `json.attrs.styles` (e.g. from a prior `parseDOCX`); the two are mutually
+   * exclusive, so specifying `externalStyles` drops the compiled `styles`.
+   */
+  document?: Omit<Partial<DocumentOptions>, "sections" | "numbering">;
 }
 /**
  * Generate a DOCX file from Tiptap JSON (runtime model), asynchronously.
@@ -87,9 +177,9 @@ declare function generateDOCX<T extends OutputType = "nodebuffer">(json: JSONCon
  *
  * Pipeline: `DocxManager.compile` → `generateDocumentSync`. Does **not** run
  * `prepareDocument` (it is async); call `await prepareDocument(json)` first
- * when http images need embedding.
+ * when http images need embedding. `options.document` is still applied.
  */
-declare function generateDOCXSync<T extends OutputType = "nodebuffer">(json: JSONContent, packerOptions?: PackerOptions<T>): OutputByType[T];
+declare function generateDOCXSync<T extends OutputType = "nodebuffer">(json: JSONContent, options?: DocxGenerateOptions<T>): OutputByType[T];
 /**
  * Generate a DOCX file as a `ReadableStream<Uint8Array>` — for large documents
  * or streaming HTTP responses.