@docen/docx 0.3.5 → 0.4.0

package/README.md

@@ -6,7 +6,7 @@
 
 > 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.
+> Need a ready-made visual editor? [`@docen/editor`](../editor/README.md) wraps this engine in a Fluent UI host with the turnkey `<docen-document>` web component.
 
 ## Features
 

package/dist/{blockquote-DY80QC06.d.mts → blockquote-D-1aSxEn.d.mts}

@@ -1,3 +1,5 @@
+import { ParseAggregatorRule } from "./extensions/types.mjs";
+
 //#region src/extensions/blockquote.d.ts
 /**
  * Blockquote extension — owns the DOCX expression of a blockquote.
@@ -17,5 +19,7 @@ declare const BLOCKQUOTE_BORDER: {
 };
 /** Apply the blockquote signature (left indent + left border) to paragraph opts. */
 declare function applyBlockquoteStyle(paraObj: Record<string, unknown>): void;
+declare const parseDocxAggregator: ParseAggregatorRule;
+declare const Blockquote: import("@tiptap/core").Node<import("@tiptap/extension-blockquote").BlockquoteOptions, any>;
 //#endregion
-export { BLOCKQUOTE_INDENT_LEFT as n, applyBlockquoteStyle as r, BLOCKQUOTE_BORDER as t };
+export { parseDocxAggregator as a, applyBlockquoteStyle as i, BLOCKQUOTE_INDENT_LEFT as n, Blockquote as r, BLOCKQUOTE_BORDER as t };

package/dist/converters/docx.d.mts

@@ -1,4 +1,4 @@
-import { a as JSONContent } from "../core-DC0_-WcE.mjs";
+import { a as JSONContent, i as Extensions } from "../core-BqyLL84S.mjs";
 import { PrepareStep } from "./prepare.mjs";
 import { DocumentOptions, OutputByType, OutputType, PackerOptions, parseDocument } from "@office-open/docx";
 
@@ -13,6 +13,21 @@ declare class DocxManager {
   private numberingConfigs;
   private orderedInstanceCounter;
   private resolveStyles;
+  private resolveNumberingLookup;
+  private markRender;
+  private markParse;
+  private nodeRender;
+  private nodeParse;
+  private blockRules;
+  private inlineRules;
+  private paragraphRules;
+  private aggregatorRules;
+  private resolveCtx;
+  constructor(extensions?: Extensions);
+  /** Reflective node renderDocx lookup: the node's DOCX opts, or {} when the
+   *  node type has no renderDocx hook (degrades to a plain paragraph). node.type
+   *  is optional on JSONContent — an absent type simply misses the map. */
+  private renderNodeOpts;
   compile(json: JSONContent): DocumentOptions;
   /** Assemble a SectionOptions from compiled children + optional layout/headers/footers. */
   private buildSection;
@@ -65,73 +80,30 @@ declare class DocxManager {
   private compileTextNode;
   /** Emit a single run for `text` with all inline marks applied. */
   private compileTextRun;
+  /**
+   * Wrap a run back into a w:ins/w:del container — the reverse of
+   * resolveTrackedChange. A literal-key ternary (`{insertion: body}` /
+   * `{deletion: body}`) lets TS narrow to the ParagraphChild branch without a
+   * cast, and `typeof` guards read `attrs` type-safely (no `as number/string`).
+   * stringifyDeletedRun emits `<w:delText>` automatically for deletion children.
+   */
+  private compileTrackedChangeRun;
   private resolveSectionChild;
   /** Wrap an opaque SectionChild in a passthrough atom (attrs.data = JSON). */
   private resolvePassthrough;
-  /**
-   * Resolve a table of contents into an editable `tableOfContents` container:
-   * `attrs.options` carries the field switches, `content` is the entry
-   * paragraphs. Each entry's inner HYPERLINK field has content-less runs that
-   * office-open parses as `null`; resolving the entries through
-   * `resolveSectionChild` → `resolveParagraphChildren` drops those nulls, so the
-   * TOC no longer reaches the generate path as an opaque blob of nulls (the
-   * `stringifyRunInline(null).break` crash). When `entries` is absent/empty
-   * (a fresh, unrendered TOC), keep the node valid for `content: "block+"` with
-   * a placeholder empty paragraph.
-   */
-  private resolveToc;
-  /**
-   * Resolve a details group-SDT: the summary-style paragraph becomes
-   * detailsSummary, the remaining blocks fold into detailsContent.
-   */
-  private resolveDetailsSdt;
   private resolveParagraph;
-  /** Heading level (1-9) for a paragraph, or undefined when it isn't a heading.
-   *  DOCX marks a heading several ways, checked in priority order:
-   *  1. office-open lifts a HeadingLevel pStyle ("Heading1".."Title") into `heading`.
-   *  2. An explicit `outlineLevel` (0-8 → 1-9) — Word's outline/TOC key off this
-   *     even without a heading pStyle; the Heading1-9 styles carry outlineLvl 0-8.
-   *  3. A pStyle that names a heading style: directly ("Heading7", which stays on
-   *     `style` because office-open's HeadingLevel type caps at 6), by localized
-   *     NAME ("heading 1"/"标题 1"), or via the `basedOn` chain (a custom style
-   *     "MyTitle" basedOn="Heading1"). `heading` and `style` carry the same pStyle.
-   *  `outlineLevel` is read loosely — office-open's public type omits the field
-   *  even though it round-trips (w:outlineLvl) at runtime. */
-  private detectHeadingLevel;
   /** 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.
+   * Walk a SectionChild[] block stream — a section's body, a header/footer
+   * slot, or a table cell's children (a cell is just another block stream). An
+   * aggregator rule (list/blockquote) claims consecutive paragraphs sharing its
+   * predicate and rebuilds them as a composite; everything else resolves
+   * individually via resolveSectionChild. The manager owns only the generic
+   * group-by loop — the predicate (belongs) + builder (build) come from each
+   * rule, so a custom composite plugs in by declaring parseDocxAggregator.
    */
   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
    * paragraph (a single run with no properties) to a bare string or a `{ text }`
@@ -141,12 +113,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;
-  private resolveHyperlink;
 }
 /**
  * Parse a DOCX file into Tiptap JSON (runtime model).
@@ -154,7 +122,7 @@ declare class DocxManager {
  * Combines @office-open/docx's `parseDocument` (DOCX binary → DocumentOptions)
  * with `DocxManager.resolve` (DocumentOptions → Tiptap JSON).
  */
-declare function parseDOCX(data: Parameters<typeof parseDocument>[0]): JSONContent;
+declare function parseDOCX(data: Parameters<typeof parseDocument>[0], extensions?: Extensions): JSONContent;
 /**
  * Options for {@link generateDOCX} / {@link generateDOCXStream}.
  */
@@ -182,6 +150,12 @@ interface DocxGenerateOptions<T extends OutputType = "nodebuffer"> {
    * exclusive, so specifying `externalStyles` drops the compiled `styles`.
    */
   document?: Omit<Partial<DocumentOptions>, "sections" | "numbering">;
+  /**
+   * Extension list used to build the conversion registry (default:
+   * `docxExtensions`). Pass `[...docxExtensions, MyMark]` to plug a custom
+   * mark/node into compile/resolve via its renderDocx/parseDocx hooks.
+   */
+  extensions?: Extensions;
 }
 /**
  * Generate a DOCX file from Tiptap JSON (runtime model), asynchronously.
@@ -212,10 +186,10 @@ declare function generateDOCXStream(json: JSONContent, options?: DocxGenerateOpt
 /**
  * Convert DocumentOptions (persistence model) to Tiptap JSON (runtime model).
  */
-declare function resolveDocument(docOpts: DocumentOptions): JSONContent;
+declare function resolveDocument(docOpts: DocumentOptions, extensions?: Extensions): JSONContent;
 /**
  * Convert Tiptap JSON (runtime model) to DocumentOptions (persistence model).
  */
-declare function compileDocument(json: JSONContent): DocumentOptions;
+declare function compileDocument(json: JSONContent, extensions?: Extensions): DocumentOptions;
 //#endregion
 export { type DocumentOptions, DocxGenerateOptions, DocxManager, compileDocument, generateDOCX, generateDOCXStream, generateDOCXSync, parseDOCX, resolveDocument };