@json-to-office/core-docx 0.16.0 → 0.17.1

package/dist/plugin/createDocumentGenerator.d.ts

@@ -1,6 +1,6 @@
 import { type ThemeConfig } from '../styles';
 import type { ServicesConfig, FontRuntimeOpts } from '@json-to-office/shared';
-import type { DocumentGeneratorBuilder } from './types';
+import type { DocumentGeneratorBuilder, GenerationValidationOptions } from './types';
 /**
  * Options for creating a document generator
  */
@@ -17,6 +17,12 @@ export interface DocumentGeneratorOptions {
     services?: ServicesConfig;
     /** Font resolution options — extraEntries, Google Fonts config, onResolved hook. */
     fonts?: FontRuntimeOpts;
+    /**
+     * Default validation behavior for every generate/generateBuffer/generateFile
+     * call. Per-call `options.validation` overrides these. Validation is on by
+     * default; pass `{ enabled: false }` to opt out.
+     */
+    validation?: GenerationValidationOptions;
 }
 /**
  * Create a document generator with chainable component registration.

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,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"}
+{"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,EAOxB,2BAA2B,EAC5B,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;IACxB;;;;OAIG;IACH,UAAU,CAAC,EAAE,2BAA2B,CAAC;CAC1C;AAgmBD;;GAEG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,wBAAwB,GAChC,wBAAwB,CAAC,SAAS,EAAE,CAAC,CAcvC"}

package/dist/plugin/example/index.js

@@ -1904,22 +1904,20 @@ import {
   ComponentValidationError as ComponentValidationError2,
   UnknownPreservedComponentError
 } from "@json-to-office/shared/plugin";
-function validateComponentProps(schema, props, componentName) {
+function validateComponentProps(schema, props, componentName, opts) {
   return validateCustomComponentProps(schema.propsSchema, props, {
-    clean: true,
-    applyDefaults: true,
+    clean: opts?.clean ?? true,
+    applyDefaults: opts?.applyDefaults ?? true,
     componentName
   });
 }
-function validateDocument(document, customComponents) {
+function validateDocument(document, customComponents, options) {
+  const knownCustomNames = new Set(customComponents.map((c) => c.name));
   const documentResult = validateDocumentUnified(document, {
-    clean: true,
-    applyDefaults: true
+    knownCustomNames,
+    allowUnknownFields: options?.allowUnknownFields
   });
-  if (!documentResult.valid) {
-    return { ...documentResult, success: false };
-  }
-  const errors = [];
+  const errors = [...documentResult.errors || []];
   function validateComponents(components, pathPrefix = "children") {
     components.forEach((componentData, index) => {
       const customComponent = customComponents.find(
@@ -1936,7 +1934,9 @@ function validateDocument(document, customComponents) {
       const validation = validateComponentProps(
         versionEntry,
         componentData.props,
-        customComponent.name
+        customComponent.name,
+        // Reject unknown custom props unless the caller allows them.
+        { clean: options?.allowUnknownFields === true }
       );
       if (!validation.valid && validation.errors) {
         const indexedErrors = validation.errors.map(
@@ -7133,7 +7133,7 @@ function createBuilderImpl(state) {
     }
     return getThemeWithFallback(themeName);
   }
-  async function processDocumentComponents(components, preserveSet, warningsCollector, resolvedTheme, depth = 0) {
+  async function processDocumentComponents(components, preserveSet, warningsCollector, resolvedTheme, validateEmitted, depth = 0) {
     if (depth > 20) {
       throw new Error(
         "Maximum component nesting depth exceeded (20). Check for circular component references."
@@ -7173,6 +7173,7 @@ function createBuilderImpl(state) {
               preserveSet,
               warningsCollector,
               resolvedTheme,
+              validateEmitted,
               depth + 1
             );
             nestedChildren = nested.standard;
@@ -7193,11 +7194,15 @@ function createBuilderImpl(state) {
             children: nestedChildren
           });
           const resultComponents = Array.isArray(result) ? result : [result];
+          if (validateEmitted) {
+            validateEmitted(resultComponents, versionLabel);
+          }
           const processedResult = await processDocumentComponents(
             resultComponents,
             preserveSet,
             warningsCollector,
             resolvedTheme,
+            validateEmitted,
             depth + 1
           );
           standardOut.push(...processedResult.standard);
@@ -7227,6 +7232,7 @@ function createBuilderImpl(state) {
             preserveSet,
             warningsCollector,
             resolvedTheme,
+            validateEmitted,
             depth + 1
           );
           standardOut.push({
@@ -7287,10 +7293,42 @@ function createBuilderImpl(state) {
     try {
       const preserveSet = resolvePreserveSet(options);
       const internalDocument = document;
-      validateDocument(
-        internalDocument,
-        state.components
-      );
+      const vOpts = {
+        ...state.validation,
+        ...options?.validation
+      };
+      if (vOpts.enabled !== false) {
+        const result = validateDocument(
+          internalDocument,
+          state.components,
+          { allowUnknownFields: vOpts.allowUnknownFields }
+        );
+        if (!result.valid) {
+          throw new ComponentValidationError2(
+            (result.errors ?? []).map((e) => ({
+              path: e.path ?? "",
+              message: e.message
+            })),
+            internalDocument
+          );
+        }
+      }
+      const validateEmitted = vOpts.enabled === false ? void 0 : (emitted, componentLabel) => {
+        const result = validateDocument(
+          { ...internalDocument, children: emitted },
+          state.components,
+          { allowUnknownFields: vOpts.allowUnknownFields }
+        );
+        if (!result.valid) {
+          throw new ComponentValidationError2(
+            (result.errors ?? []).map((e) => ({
+              path: e.path ?? "",
+              message: `custom component '${componentLabel}' emitted invalid output \u2014 ${e.message}`
+            })),
+            emitted
+          );
+        }
+      };
       const baseThemeName = internalDocument.props.theme || "minimal";
       const docTheme = resolveDocumentTheme(baseThemeName);
       const warnings = [];
@@ -7313,7 +7351,8 @@ function createBuilderImpl(state) {
         mode.doc.children || [],
         preserveSet,
         warnings,
-        modedTheme
+        modedTheme,
+        validateEmitted
       );
       const processedDocument = {
         ...mode.doc,
@@ -7384,21 +7423,21 @@ function createBuilderImpl(state) {
   function validate(document) {
     try {
       const internalDocument = document;
-      validateDocument(
+      const result = validateDocument(
         internalDocument,
         state.components
       );
-      return { valid: true };
-    } catch (error) {
-      if (error instanceof ComponentValidationError2) {
-        return {
-          valid: false,
-          errors: error.errors.map((e) => ({
-            path: e.path,
-            message: e.message
-          }))
-        };
+      if (result.valid) {
+        return { valid: true };
       }
+      return {
+        valid: false,
+        errors: (result.errors ?? []).map((e) => ({
+          path: e.path ?? "",
+          message: e.message
+        }))
+      };
+    } catch (error) {
       return {
         valid: false,
         errors: [
@@ -7448,7 +7487,8 @@ function createDocumentGenerator(options) {
     debug: options.debug ?? false,
     enableCache: options.enableCache ?? false,
     services: options.services,
-    fonts: options.fonts
+    fonts: options.fonts,
+    validation: options.validation
   };
   return createBuilderImpl(initialState);
 }