@json-to-office/core-docx 0.12.0 → 0.14.0

package/dist/plugin/createDocumentGenerator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"createDocumentGenerator.d.ts","sourceRoot":"","sources":["../../src/plugin/createDocumentGenerator.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,KAAK,WAAW,EAAwB,MAAM,WAAW,CAAC;AAEnE,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAG9E,OAAO,KAAK,EAEV,wBAAwB,EAKzB,MAAM,SAAS,CAAC;AAcjB;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC,kEAAkE;IAClE,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,kFAAkF;IAClF,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IAC3C,4CAA4C;IAC5C,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,2BAA2B;IAC3B,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,qEAAqE;IACrE,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B,oFAAoF;IACpF,KAAK,CAAC,EAAE,eAAe,CAAC;CACzB;AAseD;;GAEG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,wBAAwB,GAChC,wBAAwB,CAAC,SAAS,EAAE,CAAC,CAavC"}
+{"version":3,"file":"createDocumentGenerator.d.ts","sourceRoot":"","sources":["../../src/plugin/createDocumentGenerator.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,KAAK,WAAW,EAAwB,MAAM,WAAW,CAAC;AAEnE,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAG9E,OAAO,KAAK,EAEV,wBAAwB,EAOzB,MAAM,SAAS,CAAC;AAejB;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC,kEAAkE;IAClE,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,kFAAkF;IAClF,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IAC3C,4CAA4C;IAC5C,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,2BAA2B;IAC3B,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,qEAAqE;IACrE,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B,oFAAoF;IACpF,KAAK,CAAC,EAAE,eAAe,CAAC;CACzB;AAiiBD;;GAEG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,wBAAwB,GAChC,wBAAwB,CAAC,SAAS,EAAE,CAAC,CAavC"}

package/dist/plugin/example/index.js

@@ -225,7 +225,7 @@ var init_minimal_docx_theme = __esm({
           size: 11
         },
         mono: {
-          family: "SF Mono",
+          family: "Menlo",
           size: 10
         },
         light: {
@@ -543,7 +543,7 @@ var init_modern_docx_theme = __esm({
       fonts: {
         heading: { family: "Helvetica", size: 28 },
         body: { family: "Helvetica", size: 11 },
-        mono: { family: "SF Mono", size: 10 },
+        mono: { family: "Menlo", size: 10 },
         light: { family: "Helvetica", size: 28 }
       },
       page: {
@@ -1888,7 +1888,8 @@ import {
 } from "@json-to-office/shared-docx/validation/unified";
 import {
   DuplicateComponentError,
-  ComponentValidationError as ComponentValidationError2
+  ComponentValidationError as ComponentValidationError2,
+  UnknownPreservedComponentError
 } from "@json-to-office/shared/plugin";
 function validateComponentProps(schema, props, componentName) {
   return validateCustomComponentProps(schema.propsSchema, props, {
@@ -1955,6 +1956,9 @@ function getValidatedProps(schema, props) {
 }
 var cleanComponentProps = getValidatedProps;
 
+// src/plugin/createDocumentGenerator.ts
+import { UnknownPreservedComponentError as UnknownPreservedComponentError2 } from "@json-to-office/shared/plugin";
+
 // src/plugin/schema.ts
 import { Type } from "@sinclair/typebox";
 import { latestVersion } from "@json-to-office/shared-docx";
@@ -2199,7 +2203,8 @@ async function processDocument(document, theme, themeName) {
     metadata,
     sections,
     theme: effectiveTheme,
-    themeName
+    themeName,
+    trackRevisions: document.props.trackRevisions
   };
 }
 function createDocumentMetadata(props) {
@@ -2658,7 +2663,7 @@ Suggestion: ${suggestion}`
 import {
   Document,
   Paragraph as Paragraph7,
-  TextRun as TextRun5,
+  TextRun as TextRun6,
   AlignmentType as AlignmentType5,
   BookmarkStart as BookmarkStart2,
   BookmarkEnd as BookmarkEnd2
@@ -3991,6 +3996,99 @@ var CacheKeyGenerator = class {
   }
 };
 
+// src/utils/revisionUtils.ts
+import { TextRun as TextRun3, InsertedTextRun, DeletedTextRun } from "docx";
+var DEFAULT_REVISION_AUTHOR = "json-to-office";
+var DEFAULT_REVISION_DATE = "1970-01-01T00:00:00Z";
+var RevisionIdRegistry = class {
+  counter = 0;
+  next() {
+    this.counter += 1;
+    return this.counter;
+  }
+  /** Test-only: deterministic ids for snapshot assertions. */
+  clear() {
+    this.counter = 0;
+  }
+};
+var globalRevisionIdRegistry = new RevisionIdRegistry();
+var PLACEHOLDER_PATTERN = /\{[^}]+\}/;
+function segmentRuns(text, makeRun) {
+  const lines = text.split("\n");
+  return lines.map(
+    (line, index) => makeRun(index === 0 ? { text: line } : { text: line, break: 1 })
+  );
+}
+function createRevisionRuns(revision, baseStyle) {
+  const author = revision.author || DEFAULT_REVISION_AUTHOR;
+  const date = revision.date || DEFAULT_REVISION_DATE;
+  const runs = [];
+  for (const segment of revision.segments) {
+    if (!segment.text) continue;
+    const text = normalizeUnicodeText(segment.text);
+    if (segment.type === "insert") {
+      runs.push(
+        ...segmentRuns(
+          text,
+          (options) => new InsertedTextRun({
+            ...options,
+            ...baseStyle,
+            id: globalRevisionIdRegistry.next(),
+            author,
+            date
+          })
+        )
+      );
+    } else if (segment.type === "delete") {
+      runs.push(
+        ...segmentRuns(
+          text,
+          (options) => new DeletedTextRun({
+            ...options,
+            ...baseStyle,
+            id: globalRevisionIdRegistry.next(),
+            author,
+            date
+          })
+        )
+      );
+    } else if (PLACEHOLDER_PATTERN.test(text)) {
+      runs.push(
+        ...processTextWithPlaceholders(text, baseStyle, {})
+      );
+    } else {
+      runs.push(
+        ...segmentRuns(
+          text,
+          (options) => new TextRun3({ ...options, ...baseStyle })
+        )
+      );
+    }
+  }
+  return runs;
+}
+function componentHasRevision(component) {
+  const props = component.props;
+  if (props) {
+    if (props.revision) return true;
+    const items = props.items;
+    if (Array.isArray(items)) {
+      if (items.some(
+        (item) => typeof item === "object" && item !== null && "revision" in item && item.revision
+      )) {
+        return true;
+      }
+    }
+  }
+  const children = component.children;
+  if (Array.isArray(children)) {
+    return children.some(
+      (child) => typeof child === "object" && child !== null && componentHasRevision(child)
+    );
+  }
+  return false;
+}
+
 // src/core/cached-render.ts
 import { createHash as createHash2 } from "crypto";
 var componentCache = null;
@@ -4030,7 +4128,7 @@ function initializeComponentCache(cache) {
   }
 }
 async function renderComponentWithCache(component, theme, themeName, context, bypassCache = false) {
-  const forceBypassForType = component.name === "toc" || component.name === "section";
+  const forceBypassForType = component.name === "toc" || component.name === "section" || componentHasRevision(component);
   if (!componentCache) {
     initializeComponentCache();
   }
@@ -4069,7 +4167,7 @@ async function renderComponentWithCache(component, theme, themeName, context, by
 // src/core/content.ts
 import {
   Paragraph,
-  TextRun as TextRun3,
+  TextRun as TextRun4,
   Table,
   TableRow,
   TableCell,
@@ -4219,24 +4317,43 @@ function createText(content, theme, themeName, options = {}) {
       underline: options.underline ? { type: "single" } : void 0
     }
   };
-  const textRuns = parseTextWithDecorators(normalizedContent, baseTextStyle, {
-    boldColor: options.boldColor,
-    enableHyperlinks: true
-  });
-  if (options.bookmarkId) {
-    globalBookmarkRegistry.register(
-      options.bookmarkId,
-      normalizedContent,
-      "paragraph"
-    );
-    children.push(
-      new Bookmark({
-        id: options.bookmarkId,
-        children: textRuns
-      })
-    );
+  if (options.revision) {
+    const revisionRuns = createRevisionRuns(options.revision, baseTextStyle);
+    if (options.bookmarkId) {
+      globalBookmarkRegistry.register(
+        options.bookmarkId,
+        normalizedContent,
+        "paragraph"
+      );
+      children.push(
+        new Bookmark({
+          id: options.bookmarkId,
+          children: revisionRuns
+        })
+      );
+    } else {
+      children.push(...revisionRuns);
+    }
   } else {
-    children.push(...textRuns);
+    const textRuns = parseTextWithDecorators(normalizedContent, baseTextStyle, {
+      boldColor: options.boldColor,
+      enableHyperlinks: true
+    });
+    if (options.bookmarkId) {
+      globalBookmarkRegistry.register(
+        options.bookmarkId,
+        normalizedContent,
+        "paragraph"
+      );
+      children.push(
+        new Bookmark({
+          id: options.bookmarkId,
+          children: textRuns
+        })
+      );
+    } else {
+      children.push(...textRuns);
+    }
   }
   const isFloating = !!options.floating;
   const frameOptions = isFloating && options.floating ? mapFrameOptions(options.floating, theme, themeName) : void 0;
@@ -4357,7 +4474,24 @@ function createHeading(text, level, theme, _themeName, options = {}) {
       underline: options.underline ? { type: "single" } : void 0
     }
   };
-  if (options.bookmarkId) {
+  if (options.revision) {
+    const revisionRuns = createRevisionRuns(options.revision, baseTextStyle);
+    if (options.bookmarkId) {
+      globalBookmarkRegistry.register(
+        options.bookmarkId,
+        normalizedText,
+        "heading"
+      );
+      children.push(
+        new Bookmark({
+          id: options.bookmarkId,
+          children: revisionRuns
+        })
+      );
+    } else {
+      children.push(...revisionRuns);
+    }
+  } else if (options.bookmarkId) {
     globalBookmarkRegistry.register(
       options.bookmarkId,
       normalizedText,
@@ -4372,7 +4506,7 @@ function createHeading(text, level, theme, _themeName, options = {}) {
       headingTextChildren.push(...textRuns);
     } else {
       headingTextChildren.push(
-        new TextRun3({ text: normalizedText, ...baseTextStyle })
+        new TextRun4({ text: normalizedText, ...baseTextStyle })
       );
     }
     children.push(
@@ -4389,7 +4523,7 @@ function createHeading(text, level, theme, _themeName, options = {}) {
       });
       children.push(...textRuns);
     } else {
-      children.push(new TextRun3({ text: normalizedText, ...baseTextStyle }));
+      children.push(new TextRun4({ text: normalizedText, ...baseTextStyle }));
     }
   }
   return new Paragraph({
@@ -4529,10 +4663,11 @@ function createList(items, _theme, _themeName, options = {}) {
   items.forEach((item, index) => {
     const itemText = typeof item === "string" ? item : item.text;
     const itemLevel = typeof item === "object" ? item.level || 0 : 0;
-    if (!itemText.trim()) {
+    const itemRevision = typeof item === "object" ? item.revision : void 0;
+    if (!itemText.trim() && !itemRevision) {
       return;
     }
-    const textRuns = parseTextWithDecorators(
+    const textRuns = itemRevision ? createRevisionRuns(itemRevision, {}) : parseTextWithDecorators(
       itemText,
       {},
       {
@@ -4945,7 +5080,7 @@ async function createTable(columns, tableConfig, theme, themeName, _options = {}
         } catch (error) {
           const imageSource = imageComp.props.base64 || imageComp.props.path || "unknown";
           cellChildren = [
-            new TextRun3({
+            new TextRun4({
               text: `[IMAGE: ${imageSource.substring(0, 50)}${imageSource.length > 50 ? "..." : ""}]`,
               font: mergedStyle.font,
               size: mergedStyle.size,
@@ -4955,7 +5090,7 @@ async function createTable(columns, tableConfig, theme, themeName, _options = {}
         }
       } else {
         cellChildren = [
-          new TextRun3({
+          new TextRun4({
             text: `[Unsupported component type: ${cell.name}]`,
             font: mergedStyle.font,
             size: mergedStyle.size,
@@ -5352,7 +5487,9 @@ function renderHeadingComponent(component, theme, themeName) {
       keepNext: config.keepNext,
       keepLines: config.keepLines,
       // Bookmark ID for internal linking
-      bookmarkId
+      bookmarkId,
+      // Tracked-change segments (rendered as native Word revisions)
+      revision: config.revision
     }
   );
   return [header];
@@ -5396,7 +5533,7 @@ function parseMarkdownList(text) {
 function renderParagraphComponent(component, theme, themeName) {
   if (!isParagraphComponent(component)) return [];
   const resolvedConfig = component.props;
-  const listData = parseMarkdownList(resolvedConfig.text);
+  const listData = resolvedConfig.revision ? null : parseMarkdownList(resolvedConfig.text);
   if (listData) {
     const reference = globalNumberingRegistry.generateReference("markdown-list");
     const levels = [];
@@ -5473,7 +5610,9 @@ function renderParagraphComponent(component, theme, themeName) {
     // Pass keepLines property
     keepLines: resolvedConfig.keepLines,
     // Pass bookmark ID for internal linking
-    bookmarkId: resolvedConfig.id
+    bookmarkId: resolvedConfig.id,
+    // Tracked-change segments (rendered as native Word revisions)
+    revision: resolvedConfig.revision
   });
   return [text];
 }
@@ -6103,7 +6242,7 @@ import {
   Paragraph as Paragraph6,
   TableOfContents,
   AlignmentType as AlignmentType4,
-  TextRun as TextRun4,
+  TextRun as TextRun5,
   StyleLevel
 } from "docx";
 function parseDepthRange(rawDepth, fieldName, defaultFrom = 1, defaultTo = 3) {
@@ -6158,7 +6297,7 @@ function renderTocComponent(component, theme, context) {
     paragraphs.push(
       new Paragraph6({
         children: [
-          new TextRun4({
+          new TextRun5({
             text: componentProps.title,
             bold: true,
             size: 28
@@ -6456,8 +6595,10 @@ async function renderDocument(structure, layout, options) {
     styles: createWordStyles(structure.theme),
     sections,
     features: {
-      updateFields: true
+      updateFields: true,
       // Required for TOC fields to update correctly
+      // Word opens the document in review mode (further edits are tracked)
+      ...structure.trackRevisions && { trackRevisions: true }
     },
     // Add numbering configurations if any lists were rendered
     ...numberingConfigs.length > 0 && {
@@ -6502,7 +6643,7 @@ async function renderHeaderFooterComponents(components, theme, themeName, _conte
         elements.push(
           new Paragraph7({
             children: [
-              new TextRun5({
+              new TextRun6({
                 text: "[IMAGE: Missing path or base64 property]",
                 font: getThemeFonts(theme).body.family,
                 size: 20,
@@ -6584,7 +6725,7 @@ async function renderHeaderFooterComponents(components, theme, themeName, _conte
         elements.push(
           new Paragraph7({
             children: [
-              new TextRun5({
+              new TextRun6({
                 text: `[IMAGE: ${imageComp.props.path}]`,
                 font: getThemeFonts(theme).body.family,
                 size: 20,
@@ -6829,17 +6970,19 @@ function createBuilderImpl(state) {
     }
     return getThemeWithFallback(themeName);
   }
-  async function processDocumentComponents(components, warningsCollector, resolvedTheme, depth = 0) {
+  async function processDocumentComponents(components, preserveSet, warningsCollector, resolvedTheme, depth = 0) {
     if (depth > 20) {
       throw new Error(
         "Maximum component nesting depth exceeded (20). Check for circular component references."
       );
     }
-    const processedComponents = [];
+    const standardOut = [];
+    const preservedOut = [];
     for (const componentData of components) {
       const componentName = componentData?.name;
       if (!componentName) {
-        processedComponents.push(componentData);
+        standardOut.push(componentData);
+        preservedOut.push(componentData);
         continue;
       }
       const customComponent = componentMap.get(componentName);
@@ -6862,12 +7005,14 @@ function createBuilderImpl(state) {
           );
           let nestedChildren;
           if (componentWithName.children && Array.isArray(componentWithName.children)) {
-            nestedChildren = await processDocumentComponents(
+            const nested = await processDocumentComponents(
               componentWithName.children,
+              preserveSet,
               warningsCollector,
               resolvedTheme,
               depth + 1
             );
+            nestedChildren = nested.standard;
           }
           const versionLabel = componentWithName.version ? `${customComponent.name}@${componentWithName.version}` : customComponent.name;
           const addWarning = (message, context) => {
@@ -6887,15 +7032,21 @@ function createBuilderImpl(state) {
           const resultComponents = Array.isArray(result) ? result : [result];
           const processedResult = await processDocumentComponents(
             resultComponents,
+            preserveSet,
             warningsCollector,
             resolvedTheme,
             depth + 1
           );
-          processedComponents.push(...processedResult);
+          standardOut.push(...processedResult.standard);
+          if (preserveSet && preserveSet.has(componentName)) {
+            preservedOut.push(componentData);
+          } else {
+            preservedOut.push(...processedResult.preserved);
+          }
           if (state.debug) {
             console.log(
               `Processed custom component '${versionLabel}':`,
-              processedResult
+              processedResult.standard
             );
           }
         } catch (error) {
@@ -6910,20 +7061,26 @@ function createBuilderImpl(state) {
         if ("children" in componentData && Array.isArray(componentData.children)) {
           const processedNested = await processDocumentComponents(
             componentData.children,
+            preserveSet,
             warningsCollector,
             resolvedTheme,
             depth + 1
           );
-          processedComponents.push({
+          standardOut.push({
+            ...componentData,
+            children: processedNested.standard
+          });
+          preservedOut.push({
             ...componentData,
-            children: processedNested
+            children: processedNested.preserved
           });
         } else {
-          processedComponents.push(componentData);
+          standardOut.push(componentData);
+          preservedOut.push(componentData);
         }
       }
     }
-    return processedComponents;
+    return { standard: standardOut, preserved: preservedOut };
   }
   function addComponent(component) {
     if (!component.name) {
@@ -6948,8 +7105,24 @@ function createBuilderImpl(state) {
       newState
     );
   }
-  async function generate(document) {
+  function resolvePreserveSet(options) {
+    const list = options?.preserveCustomComponents;
+    if (!list || list.length === 0) {
+      return void 0;
+    }
+    const registered = new Set(state.componentNames);
+    const unknown = list.filter((n) => !registered.has(n));
+    if (unknown.length > 0) {
+      throw new UnknownPreservedComponentError2(
+        unknown,
+        Array.from(state.componentNames)
+      );
+    }
+    return new Set(list);
+  }
+  async function generate(document, options) {
     try {
+      const preserveSet = resolvePreserveSet(options);
       const internalDocument = document;
       validateDocument(
         internalDocument,
@@ -6973,14 +7146,15 @@ function createBuilderImpl(state) {
           context: { code: w.code }
         });
       }
-      const processedComponents = await processDocumentComponents(
+      const processed = await processDocumentComponents(
         mode.doc.children || [],
+        preserveSet,
         warnings,
         modedTheme
       );
       const processedDocument = {
         ...mode.doc,
-        children: processedComponents
+        children: processed.standard
       };
       const [modedDoc] = normalizeDocument(processedDocument);
       await resolveDocumentFonts(modedDoc, modedTheme, state.fonts, warnings);
@@ -6989,9 +7163,15 @@ function createBuilderImpl(state) {
       const generatedDocument = await renderDocument(structure, layout, {
         services: state.services
       });
+      const preservedDefinition = preserveSet ? {
+        ...mode.doc,
+        children: processed.preserved
+      } : void 0;
       return {
         document: generatedDocument,
-        warnings: warnings.length > 0 ? warnings : null
+        warnings: warnings.length > 0 ? warnings : null,
+        standardDefinition: modedDoc,
+        preservedDefinition
       };
     } catch (error) {
       if (state.debug) {
@@ -7000,16 +7180,40 @@ function createBuilderImpl(state) {
       throw error;
     }
   }
-  async function generateBuffer(document) {
-    const { document: doc, warnings } = await generate(document);
+  async function generateBuffer(document, options) {
+    const {
+      document: doc,
+      warnings,
+      standardDefinition,
+      preservedDefinition
+    } = await generate(document, options);
     const buffer = await Packer.toBuffer(doc);
-    return { buffer, warnings };
+    return { buffer, warnings, standardDefinition, preservedDefinition };
   }
-  async function generateFile(document, outputPath) {
-    const { buffer, warnings } = await generateBuffer(document);
+  async function generateFile(document, outputPath, options) {
+    const { buffer, warnings, standardDefinition, preservedDefinition } = await generateBuffer(document, options);
     const fs4 = await import("fs/promises");
     await fs4.writeFile(outputPath, new Uint8Array(buffer));
-    return { warnings };
+    let preservedOutputPath;
+    if (preservedDefinition !== void 0) {
+      const path3 = await import("path");
+      preservedOutputPath = options?.preservedOutputPath ?? (() => {
+        const ext = path3.extname(outputPath);
+        const base = ext ? outputPath.slice(0, -ext.length) : outputPath;
+        return `${base}-preserved.json`;
+      })();
+      await fs4.writeFile(
+        preservedOutputPath,
+        JSON.stringify(preservedDefinition, null, 2),
+        "utf8"
+      );
+    }
+    return {
+      warnings,
+      standardDefinition,
+      preservedDefinition,
+      preservedOutputPath
+    };
   }
   function getComponentNames() {
     return Array.from(state.componentNames);
@@ -7043,6 +7247,10 @@ function createBuilderImpl(state) {
       };
     }
   }
+  async function getStandardComponentsDefinition(document) {
+    const { standardDefinition } = await generate(document);
+    return standardDefinition;
+  }
   function generateSchema(includeStandardComponents = true) {
     return generatePluginDocumentSchema(
       state.components,
@@ -7056,40 +7264,6 @@ function createBuilderImpl(state) {
       options
     );
   }
-  async function getStandardComponentsDefinition(document) {
-    try {
-      const internalDocument = document;
-      validateDocument(
-        internalDocument,
-        state.components
-      );
-      const themeName = internalDocument.props.theme || "minimal";
-      const docTheme = resolveDocumentTheme(themeName);
-      const warnings = [];
-      const mode = applyExportMode({
-        doc: internalDocument,
-        theme: docTheme,
-        fonts: state.fonts
-      });
-      const modedTheme = mode.theme;
-      const processedComponents = await processDocumentComponents(
-        mode.doc.children || [],
-        warnings,
-        modedTheme
-      );
-      const processedDocument = {
-        ...mode.doc,
-        children: processedComponents
-      };
-      const [finalReportComponent] = normalizeDocument(processedDocument);
-      return finalReportComponent;
-    } catch (error) {
-      if (state.debug) {
-        console.error("Error getting standard components definition:", error);
-      }
-      throw error;
-    }
-  }
   return Object.freeze({
     addComponent,
     generate,