@json-to-office/shared-docx 0.13.1 → 0.14.0

package/dist/index.d.ts

@@ -1,10 +1,10 @@
+import { RevisionSegment, ComponentDefinition as ComponentDefinition$1, ComponentDefinitionSchema, ColumnsPropsSchema, ReportPropsSchema, SectionPropsSchema, HeadingPropsSchema, ParagraphPropsSchema, TextBoxPropsSchema, ImagePropsSchema, HighchartsPropsSchema, StatisticPropsSchema, TablePropsSchema, ListPropsSchema, TocPropsSchema } from './schemas/components.js';
+export { Alignment, AlignmentSchema, BaseComponentProps, BaseComponentPropsSchema, BorderSchema, ColumnsProps, HeadingLevel, HeadingLevelSchema, HeadingProps, HighchartsProps, ImageProps, Indent, IndentSchema, JustifiedAlignment, JustifiedAlignmentSchema, LineSpacing, LineSpacingSchema, ListProps, MarginsSchema, Numbering, NumberingSchema, ParagraphProps, ReportProps, Revision, RevisionSchema, RevisionSegmentSchema, SectionProps, Spacing, SpacingSchema, StandardComponentDefinitionSchema, StatisticProps, TableProps, TextBoxProps, TocProps } from './schemas/components.js';
 export { AddWarningFunction, ComponentSchemaConfig, DEFAULT_ERROR_CONFIG, ERROR_EMOJIS, ErrorFormatterConfig, GenerationWarning, ParsedSemver, ComponentDefinition as SharedComponentDefinition, ValidationError, ValidationResult, calculatePosition, clearComponentNamesCache, compareSemver, convertToJsonSchema, createComponentSchema, createErrorConfig, createJsonParseError, exportSchemaToFile, extractStandardComponentNames, fixSchemaReferences, formatErrorMessage, formatErrorSummary, getLiteralValue, getObjectSchemaPropertyNames, getSchemaMetadata, groupErrorsByPath, isLiteralSchema, isObjectSchema, isUnionSchema, isValidSemver, latestVersion, parseSemver, createComponentSchemaObject as sharedCreateComponentSchemaObject, transformValueError, transformValueErrors } from '@json-to-office/shared';
 import { DocumentValidationResult, ValidationError } from './schemas/document.js';
 export { JSON_SCHEMA_URLS, JsonComponentDefinitionSchema } from './schemas/document.js';
 export { DocumentMargins, FontDefinition, Fonts, HeadingDefinition, Page, PageDimensions, StyleDefinitions, ThemeConfigJson, ThemeConfigSchema, isValidThemeConfig } from './schemas/theme.js';
 export { GenerateDocumentRequest, GenerateDocumentRequestSchema, GenerateDocumentResponse, GenerateDocumentResponseSchema, ValidateDocumentRequest, ValidateDocumentRequestSchema, ValidateDocumentResponse, ValidateDocumentResponseSchema } from './schemas/api.js';
-import { ComponentDefinition as ComponentDefinition$1, ComponentDefinitionSchema, ColumnsPropsSchema, ReportPropsSchema, SectionPropsSchema, HeadingPropsSchema, ParagraphPropsSchema, TextBoxPropsSchema, ImagePropsSchema, HighchartsPropsSchema, StatisticPropsSchema, TablePropsSchema, ListPropsSchema, TocPropsSchema } from './schemas/components.js';
-export { Alignment, AlignmentSchema, BaseComponentProps, BaseComponentPropsSchema, BorderSchema, ColumnsProps, HeadingLevel, HeadingLevelSchema, HeadingProps, HighchartsProps, ImageProps, Indent, IndentSchema, JustifiedAlignment, JustifiedAlignmentSchema, LineSpacing, LineSpacingSchema, ListProps, MarginsSchema, Numbering, NumberingSchema, ParagraphProps, ReportProps, SectionProps, Spacing, SpacingSchema, StandardComponentDefinitionSchema, StatisticProps, TableProps, TextBoxProps, TocProps } from './schemas/components.js';
 import * as _sinclair_typebox from '@sinclair/typebox';
 import { Static } from '@sinclair/typebox';
 import { ValueError } from '@sinclair/typebox/value';
@@ -17,6 +17,98 @@ export { ColumnsComponentDefaults, ComponentDefaults, HeadingComponentDefaults,
 export { C as ComponentValidationResult, E as EnhancedValueError, J as JsonValidationResult, T as ThemeValidationResult, V as ValidationOptions, c as createDocumentValidator, d as documentValidator, i as isValidDocument, s as strictDocumentValidator, v as validateDocument, a as validateDocumentWithSchema, b as validateJsonComponent, e as validateJsonComponentDoc, b as validateJsonDocument } from './document-validator-CiaGiy1v.js';
 import './schemas/font.js';
 
+/**
+ * Document diff engine
+ *
+ * Compares two json-to-office DOCX definitions and produces a redline
+ * document: a third definition (based on the new one) where text changes
+ * are expressed as `revision` segments that the renderer turns into native
+ * Word tracked changes (w:ins / w:del).
+ *
+ * Scope (v1):
+ * - paragraph / heading: word-level tracked changes
+ * - list: item-level alignment, word-level tracked changes per item
+ * - containers (section, columns, text-box, ...): recursed into
+ * - everything else (table, image, chart, ...): block replace, reported
+ *   as an *untracked* change in the summary — Word has no native revision
+ *   for these at the fidelity docx.js supports.
+ */
+/** Structural view of any component node — schemas validate elsewhere. */
+interface JsonNode {
+    name: string;
+    props?: Record<string, unknown>;
+    children?: JsonNode[];
+    [key: string]: unknown;
+}
+interface DiffDocumentsOptions {
+    /** Revision author shown in Word (default: "json-to-office") */
+    author?: string;
+    /** Revision timestamp, ISO 8601 (default: deterministic epoch) */
+    date?: string;
+}
+interface UntrackedChange {
+    /** JSON-pointer-ish location in the NEW document */
+    path: string;
+    kind: 'modified' | 'inserted' | 'deleted';
+    component: string;
+    detail: string;
+}
+interface DiffSummary {
+    /** Blocks rendered with native tracked changes */
+    tracked: {
+        modified: number;
+        inserted: number;
+        deleted: number;
+    };
+    /** Changes the redline cannot express as native revisions */
+    untracked: UntrackedChange[];
+    unchangedBlocks: number;
+    /** Aggregate fidelity caveats about the redline */
+    notes: string[];
+}
+interface DiffDocumentsResult {
+    /** Redline document definition (renderable as-is) */
+    document: JsonNode;
+    summary: DiffSummary;
+}
+/**
+ * Diff two DOCX definitions into a renderable redline document.
+ *
+ * Both inputs must be json-to-office DOCX definitions (root `name: "docx"`).
+ * The result is based on the NEW document; the root gains
+ * `trackRevisions: true` so Word opens it in review mode.
+ */
+declare function diffDocuments(oldDoc: JsonNode, newDoc: JsonNode, options?: DiffDocumentsOptions): DiffDocumentsResult;
+
+/**
+ * Word-level text diff
+ *
+ * Tokenizes text into words and whitespace, runs an LCS diff over the
+ * tokens, and emits revision segments. Pure, dependency-free.
+ */
+
+/**
+ * Anchored to the schema type so the diff engine can never emit segments
+ * the RevisionSchema would reject.
+ */
+type DiffSegment = RevisionSegment;
+/**
+ * Word-level diff between two strings.
+ *
+ * Returns merged segments in document order. Deleting everything and
+ * inserting everything (whole replace) is the degenerate output for
+ * completely different texts or oversized inputs.
+ */
+declare function diffWords(oldText: string, newText: string): DiffSegment[];
+/**
+ * Strip the inline markdown the renderer understands (bold/italic markers,
+ * hyperlinks) so revision segments — which render literally — never expose
+ * raw markers. Uses the exact decorator regex of textParser.ts (lazy
+ * [\s\S]*? content), so what the parser would style, this strips — including
+ * content containing '*' or '_' (e.g. **snake_case**).
+ */
+declare function stripMarkdown(text: string): string;
+
 /**
  * JSON parser
  * @module validation/parsers/json
@@ -208,6 +300,14 @@ declare const COMPONENT_SCHEMA_MAP: {
         componentDefaults: _sinclair_typebox.TOptional<_sinclair_typebox.TObject<{
             heading: _sinclair_typebox.TOptional<_sinclair_typebox.TObject<{
                 text: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+                lineSpacing: _sinclair_typebox.TOptional<_sinclair_typebox.TUnion<[_sinclair_typebox.TNumber, _sinclair_typebox.TObject<{
+                    type: _sinclair_typebox.TUnion<[_sinclair_typebox.TLiteral<"single">, _sinclair_typebox.TLiteral<"atLeast">, _sinclair_typebox.TLiteral<"exactly">, _sinclair_typebox.TLiteral<"double">, _sinclair_typebox.TLiteral<"multiple">]>;
+                    value: _sinclair_typebox.TOptional<_sinclair_typebox.TNumber>;
+                }>]>>;
+                spacing: _sinclair_typebox.TOptional<_sinclair_typebox.TObject<{
+                    before: _sinclair_typebox.TOptional<_sinclair_typebox.TNumber>;
+                    after: _sinclair_typebox.TOptional<_sinclair_typebox.TNumber>;
+                }>>;
                 level: _sinclair_typebox.TOptional<_sinclair_typebox.TUnion<[_sinclair_typebox.TLiteral<1>, _sinclair_typebox.TLiteral<2>, _sinclair_typebox.TLiteral<3>, _sinclair_typebox.TLiteral<4>, _sinclair_typebox.TLiteral<5>, _sinclair_typebox.TLiteral<6>]>>;
                 font: _sinclair_typebox.TOptional<_sinclair_typebox.TObject<{
                     size: _sinclair_typebox.TOptional<_sinclair_typebox.TNumber>;
@@ -231,14 +331,6 @@ declare const COMPONENT_SCHEMA_MAP: {
                     family: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
                 }>>;
                 alignment: _sinclair_typebox.TOptional<_sinclair_typebox.TUnion<[_sinclair_typebox.TLiteral<"left">, _sinclair_typebox.TLiteral<"center">, _sinclair_typebox.TLiteral<"right">, _sinclair_typebox.TLiteral<"justify">]>>;
-                spacing: _sinclair_typebox.TOptional<_sinclair_typebox.TObject<{
-                    before: _sinclair_typebox.TOptional<_sinclair_typebox.TNumber>;
-                    after: _sinclair_typebox.TOptional<_sinclair_typebox.TNumber>;
-                }>>;
-                lineSpacing: _sinclair_typebox.TOptional<_sinclair_typebox.TUnion<[_sinclair_typebox.TNumber, _sinclair_typebox.TObject<{
-                    type: _sinclair_typebox.TUnion<[_sinclair_typebox.TLiteral<"single">, _sinclair_typebox.TLiteral<"atLeast">, _sinclair_typebox.TLiteral<"exactly">, _sinclair_typebox.TLiteral<"double">, _sinclair_typebox.TLiteral<"multiple">]>;
-                    value: _sinclair_typebox.TOptional<_sinclair_typebox.TNumber>;
-                }>]>>;
                 pageBreak: _sinclair_typebox.TOptional<_sinclair_typebox.TBoolean>;
                 columnBreak: _sinclair_typebox.TOptional<_sinclair_typebox.TBoolean>;
                 numbering: _sinclair_typebox.TOptional<_sinclair_typebox.TBoolean>;
@@ -247,6 +339,10 @@ declare const COMPONENT_SCHEMA_MAP: {
             }>>;
             paragraph: _sinclair_typebox.TOptional<_sinclair_typebox.TObject<{
                 text: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+                spacing: _sinclair_typebox.TOptional<_sinclair_typebox.TObject<{
+                    before: _sinclair_typebox.TOptional<_sinclair_typebox.TNumber>;
+                    after: _sinclair_typebox.TOptional<_sinclair_typebox.TNumber>;
+                }>>;
                 font: _sinclair_typebox.TOptional<_sinclair_typebox.TObject<{
                     size: _sinclair_typebox.TOptional<_sinclair_typebox.TNumber>;
                     color: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
@@ -268,15 +364,13 @@ declare const COMPONENT_SCHEMA_MAP: {
                     }>>;
                     family: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
                 }>>;
-                themeStyle: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
-                boldColor: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
-                spacing: _sinclair_typebox.TOptional<_sinclair_typebox.TObject<{
-                    before: _sinclair_typebox.TOptional<_sinclair_typebox.TNumber>;
-                    after: _sinclair_typebox.TOptional<_sinclair_typebox.TNumber>;
-                }>>;
                 alignment: _sinclair_typebox.TOptional<_sinclair_typebox.TUnion<[_sinclair_typebox.TLiteral<"left">, _sinclair_typebox.TLiteral<"center">, _sinclair_typebox.TLiteral<"right">, _sinclair_typebox.TLiteral<"justify">]>>;
                 pageBreak: _sinclair_typebox.TOptional<_sinclair_typebox.TBoolean>;
                 columnBreak: _sinclair_typebox.TOptional<_sinclair_typebox.TBoolean>;
+                keepNext: _sinclair_typebox.TOptional<_sinclair_typebox.TBoolean>;
+                keepLines: _sinclair_typebox.TOptional<_sinclair_typebox.TBoolean>;
+                themeStyle: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+                boldColor: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
                 floating: _sinclair_typebox.TOptional<_sinclair_typebox.TObject<{
                     horizontalPosition: _sinclair_typebox.TOptional<_sinclair_typebox.TObject<{
                         relative: _sinclair_typebox.TOptional<_sinclair_typebox.TUnion<[_sinclair_typebox.TLiteral<"margin">, _sinclair_typebox.TLiteral<"page">, _sinclair_typebox.TLiteral<"text">]>>;
@@ -295,8 +389,6 @@ declare const COMPONENT_SCHEMA_MAP: {
                     width: _sinclair_typebox.TOptional<_sinclair_typebox.TNumber>;
                     height: _sinclair_typebox.TOptional<_sinclair_typebox.TNumber>;
                 }>>;
-                keepNext: _sinclair_typebox.TOptional<_sinclair_typebox.TBoolean>;
-                keepLines: _sinclair_typebox.TOptional<_sinclair_typebox.TBoolean>;
                 id: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
             }>>;
             image: _sinclair_typebox.TOptional<_sinclair_typebox.TObject<{
@@ -397,6 +489,14 @@ declare const COMPONENT_SCHEMA_MAP: {
                 items: _sinclair_typebox.TOptional<_sinclair_typebox.TArray<_sinclair_typebox.TUnion<[_sinclair_typebox.TString, _sinclair_typebox.TObject<{
                     text: _sinclair_typebox.TString;
                     level: _sinclair_typebox.TOptional<_sinclair_typebox.TNumber>;
+                    revision: _sinclair_typebox.TOptional<_sinclair_typebox.TObject<{
+                        author: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+                        date: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+                        segments: _sinclair_typebox.TArray<_sinclair_typebox.TObject<{
+                            type: _sinclair_typebox.TUnion<[_sinclair_typebox.TLiteral<"equal">, _sinclair_typebox.TLiteral<"insert">, _sinclair_typebox.TLiteral<"delete">]>;
+                            text: _sinclair_typebox.TString;
+                        }>>;
+                    }>>;
                 }>]>>>;
                 reference: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
                 levels: _sinclair_typebox.TOptional<_sinclair_typebox.TArray<_sinclair_typebox.TObject<{
@@ -425,6 +525,7 @@ declare const COMPONENT_SCHEMA_MAP: {
                 }>]>>;
             }>>;
         }>>;
+        trackRevisions: _sinclair_typebox.TOptional<_sinclair_typebox.TBoolean>;
         metadata: _sinclair_typebox.TOptional<_sinclair_typebox.TObject<{
             title: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
             subtitle: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
@@ -502,6 +603,14 @@ declare const COMPONENT_SCHEMA_MAP: {
         numbering: _sinclair_typebox.TOptional<_sinclair_typebox.TBoolean>;
         keepNext: _sinclair_typebox.TOptional<_sinclair_typebox.TBoolean>;
         keepLines: _sinclair_typebox.TOptional<_sinclair_typebox.TBoolean>;
+        revision: _sinclair_typebox.TOptional<_sinclair_typebox.TObject<{
+            author: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+            date: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+            segments: _sinclair_typebox.TArray<_sinclair_typebox.TObject<{
+                type: _sinclair_typebox.TUnion<[_sinclair_typebox.TLiteral<"equal">, _sinclair_typebox.TLiteral<"insert">, _sinclair_typebox.TLiteral<"delete">]>;
+                text: _sinclair_typebox.TString;
+            }>>;
+        }>>;
     }>;
     readonly paragraph: _sinclair_typebox.TObject<{
         text: _sinclair_typebox.TString;
@@ -556,6 +665,14 @@ declare const COMPONENT_SCHEMA_MAP: {
         keepNext: _sinclair_typebox.TOptional<_sinclair_typebox.TBoolean>;
         keepLines: _sinclair_typebox.TOptional<_sinclair_typebox.TBoolean>;
         id: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+        revision: _sinclair_typebox.TOptional<_sinclair_typebox.TObject<{
+            author: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+            date: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+            segments: _sinclair_typebox.TArray<_sinclair_typebox.TObject<{
+                type: _sinclair_typebox.TUnion<[_sinclair_typebox.TLiteral<"equal">, _sinclair_typebox.TLiteral<"insert">, _sinclair_typebox.TLiteral<"delete">]>;
+                text: _sinclair_typebox.TString;
+            }>>;
+        }>>;
     }>;
     readonly columns: _sinclair_typebox.TObject<{
         columns: _sinclair_typebox.TUnion<[_sinclair_typebox.TNumber, _sinclair_typebox.TArray<_sinclair_typebox.TObject<{
@@ -629,6 +746,14 @@ declare const COMPONENT_SCHEMA_MAP: {
         items: _sinclair_typebox.TArray<_sinclair_typebox.TUnion<[_sinclair_typebox.TString, _sinclair_typebox.TObject<{
             text: _sinclair_typebox.TString;
             level: _sinclair_typebox.TOptional<_sinclair_typebox.TNumber>;
+            revision: _sinclair_typebox.TOptional<_sinclair_typebox.TObject<{
+                author: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+                date: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+                segments: _sinclair_typebox.TArray<_sinclair_typebox.TObject<{
+                    type: _sinclair_typebox.TUnion<[_sinclair_typebox.TLiteral<"equal">, _sinclair_typebox.TLiteral<"insert">, _sinclair_typebox.TLiteral<"delete">]>;
+                    text: _sinclair_typebox.TString;
+                }>>;
+            }>>;
         }>]>>;
         reference: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
         levels: _sinclair_typebox.TOptional<_sinclair_typebox.TArray<_sinclair_typebox.TObject<{
@@ -909,4 +1034,4 @@ type ThemeName = 'minimal' | 'verizon' | 'a2a' | 'hitachi';
 
 declare const SHARED_DOCX_VERSION = "1.0.0";
 
-export { type ColumnsComponent, ColumnsPropsSchema, type ComponentDefinition, ComponentDefinitionSchema, type CoreValidationResult, ValidationError as DocumentValidationError, DocumentValidationResult, type FormattedError, type HeadingComponent, HeadingPropsSchema, type HighchartsComponent, HighchartsPropsSchema, type ImageComponent, ImagePropsSchema, JsonDocumentParser, JsonParsingError, JsonValidationError, type ListComponent, ListPropsSchema, type ParagraphComponent, ParagraphPropsSchema, type ReportComponent, ReportPropsSchema, SHARED_DOCX_VERSION, STANDARD_COMPONENTS, STANDARD_COMPONENTS_SET, type SectionComponent, SectionPropsSchema, type StandardComponentDefinition, type StandardComponentName, type StatisticComponent, StatisticPropsSchema, type TableComponent, TablePropsSchema, type TextBoxComponent, TextBoxPropsSchema, type TextSpaceAfterComponent, TextSpaceAfterPropsSchema, type ThemeName, type TocComponent, TocPropsSchema, createValidatedComponent, formatErrorReport, formatValidationError, formatValidationErrorStrings, formatValidationErrors, getErrorSummary, getValidationContext, getValidationErrors, hasCriticalErrors, isColumnsComponent, isHeadingComponent, isHighchartsComponent, isImageComponent, isListComponent, isParagraphComponent, isReportComponent, isSectionComponent, isStatisticComponent, isTableComponent, isTextBoxComponent, isTextSpaceAfterComponent, isTocComponent, isValidComponent, parseJsonComponent, parseJsonWithLineNumbers, safeValidateComponentDefinition, safeValidateComponentProps, transformAndValidate, validateComponent, validateComponentDefinition, validateComponents };
+export { type ColumnsComponent, ColumnsPropsSchema, type ComponentDefinition, ComponentDefinitionSchema, type CoreValidationResult, type DiffDocumentsOptions, type DiffDocumentsResult, type DiffSegment, type DiffSummary, ValidationError as DocumentValidationError, DocumentValidationResult, type FormattedError, type HeadingComponent, HeadingPropsSchema, type HighchartsComponent, HighchartsPropsSchema, type ImageComponent, ImagePropsSchema, JsonDocumentParser, type JsonNode, JsonParsingError, JsonValidationError, type ListComponent, ListPropsSchema, type ParagraphComponent, ParagraphPropsSchema, type ReportComponent, ReportPropsSchema, RevisionSegment, SHARED_DOCX_VERSION, STANDARD_COMPONENTS, STANDARD_COMPONENTS_SET, type SectionComponent, SectionPropsSchema, type StandardComponentDefinition, type StandardComponentName, type StatisticComponent, StatisticPropsSchema, type TableComponent, TablePropsSchema, type TextBoxComponent, TextBoxPropsSchema, type TextSpaceAfterComponent, TextSpaceAfterPropsSchema, type ThemeName, type TocComponent, TocPropsSchema, type UntrackedChange, createValidatedComponent, diffDocuments, diffWords, formatErrorReport, formatValidationError, formatValidationErrorStrings, formatValidationErrors, getErrorSummary, getValidationContext, getValidationErrors, hasCriticalErrors, isColumnsComponent, isHeadingComponent, isHighchartsComponent, isImageComponent, isListComponent, isParagraphComponent, isReportComponent, isSectionComponent, isStatisticComponent, isTableComponent, isTextBoxComponent, isTextSpaceAfterComponent, isTocComponent, isValidComponent, parseJsonComponent, parseJsonWithLineNumbers, safeValidateComponentDefinition, safeValidateComponentProps, stripMarkdown, transformAndValidate, validateComponent, validateComponentDefinition, validateComponents };