@json-to-office/core-docx 0.15.0 → 0.17.0

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;AAojBD;;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(
@@ -2038,7 +2038,8 @@ import {
   isTableComponent,
   isListComponent,
   isTocComponent,
-  isHighchartsComponent
+  isHighchartsComponent,
+  isVisualComponent
 } from "@json-to-office/shared-docx";
 
 // src/utils/formatters.ts
@@ -2131,6 +2132,9 @@ function resolveListProps(props, theme) {
 function resolveHighchartsProps(props, _theme) {
   return props;
 }
+function resolveVisualProps(props, _theme) {
+  return props;
+}
 function getCustomComponentDefaults(theme, componentName) {
   const defaults = getComponentDefaults(theme);
   return defaults?.[componentName] || {};
@@ -2160,7 +2164,8 @@ var RESOLVER_MAP = {
   section: resolveSectionProps,
   columns: resolveColumnsProps,
   list: resolveListProps,
-  highcharts: resolveHighchartsProps
+  highcharts: resolveHighchartsProps,
+  visual: resolveVisualProps
 };
 function resolveComponentDefaults(component, theme) {
   if (!component.props) return component;
@@ -4141,7 +4146,7 @@ function initializeComponentCache(cache) {
   }
 }
 async function renderComponentWithCache(component, theme, themeName, context, bypassCache = false) {
-  const forceBypassForType = component.name === "toc" || component.name === "section" || componentHasRevision(component);
+  const forceBypassForType = component.name === "toc" || component.name === "section" || component.name === "visual" || componentHasRevision(component);
   if (!componentCache) {
     initializeComponentCache();
   }
@@ -6393,21 +6398,61 @@ function isNodeEnvironment() {
   return typeof process !== "undefined" && process.versions != null && process.versions.node != null && typeof process.versions.node === "string";
 }
 
+// src/utils/serviceClient.ts
+var DEFAULT_TIMEOUT_MS = 3e4;
+function resolveServiceUrl(propsUrl, servicesUrl, defaultUrl) {
+  const raw = (propsUrl || servicesUrl || defaultUrl).trim();
+  const withScheme = /^https?:\/\//i.test(raw) ? raw : `http://${raw}`;
+  return withScheme.replace(/\/+$/, "");
+}
+async function postJsonToService(opts) {
+  const resolvedHeaders = typeof opts.headers === "function" ? await opts.headers(opts.body) : opts.headers;
+  const headers = {
+    "Content-Type": "application/json",
+    ...resolvedHeaders
+  };
+  const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  let response;
+  try {
+    response = await fetch(`${opts.url}${opts.path}`, {
+      method: "POST",
+      headers,
+      body: JSON.stringify(opts.body),
+      signal: controller.signal
+    });
+  } catch (error) {
+    if (error?.name === "AbortError") {
+      throw new Error(
+        `${opts.serviceLabel} timed out after ${timeoutMs}ms at ${opts.url}.`
+      );
+    }
+    const cause = error instanceof Error ? error.message : String(error);
+    throw new Error(opts.onUnreachable(opts.url, cause));
+  } finally {
+    clearTimeout(timer);
+  }
+  if (!response.ok) {
+    throw new Error(
+      `${opts.serviceLabel} returned ${response.status}: ${response.statusText}`
+    );
+  }
+  return response;
+}
+
 // src/components/highcharts.ts
 var DEFAULT_EXPORT_SERVER_URL = "http://localhost:7801";
-function getExportServerUrl(propsUrl, servicesUrl) {
-  const raw = propsUrl || servicesUrl || DEFAULT_EXPORT_SERVER_URL;
-  return raw.startsWith("http") ? raw : `http://${raw}`;
-}
 async function generateChart(config, servicesConfig) {
   if (!isNodeEnvironment()) {
     throw new Error(
       "Highcharts export server requires a Node.js environment. Chart generation is not available in browser environments."
     );
   }
-  const serverUrl = getExportServerUrl(
+  const serverUrl = resolveServiceUrl(
     config.serverUrl,
-    servicesConfig?.serverUrl
+    servicesConfig?.serverUrl,
+    DEFAULT_EXPORT_SERVER_URL
   );
   const requestBody = {
     infile: config.options,
@@ -6415,26 +6460,15 @@ async function generateChart(config, servicesConfig) {
     b64: true,
     scale: config.scale
   };
-  const resolvedHeaders = typeof servicesConfig?.headers === "function" ? await servicesConfig.headers(requestBody) : servicesConfig?.headers;
-  const headers = {
-    "Content-Type": "application/json",
-    ...resolvedHeaders
-  };
-  const response = await fetch(`${serverUrl}/export`, {
-    method: "POST",
-    headers,
-    body: JSON.stringify(requestBody)
-  }).catch((error) => {
-    throw new Error(
-      `Highcharts Export Server is not running at ${serverUrl}. Start it with: npx highcharts-export-server --enableServer true
-Cause: ${error instanceof Error ? error.message : String(error)}`
-    );
+  const response = await postJsonToService({
+    url: serverUrl,
+    path: "/export",
+    body: requestBody,
+    headers: servicesConfig?.headers,
+    serviceLabel: "Highcharts export server",
+    onUnreachable: (url, cause) => `Highcharts Export Server is not running at ${url}. Start it with: npx highcharts-export-server --enableServer true
+Cause: ${cause}`
   });
-  if (!response.ok) {
-    throw new Error(
-      `Highcharts export server returned ${response.status}: ${response.statusText}`
-    );
-  }
   const base64Data = await response.text();
   const base64DataUri = `data:image/png;base64,${base64Data}`;
   const width = config.options.chart.width;
@@ -6468,6 +6502,109 @@ async function renderHighchartsComponent(component, theme, themeName, context) {
   return imageParagraphs;
 }
 
+// src/components/visual.ts
+import {
+  clampVisualDpi,
+  DEFAULT_VISUAL_DPI
+} from "@json-to-office/shared";
+var DEFAULT_RASTERIZE_SERVER_URL = "http://localhost:7802";
+var PIXELS_PER_INCH = 96;
+function buildVisualPresentation(props) {
+  const { canvas, elements } = props;
+  const presentationProps = {
+    slideWidth: canvas.width,
+    slideHeight: canvas.height
+  };
+  if (canvas.theme) presentationProps.theme = canvas.theme;
+  const slideProps = {};
+  if (canvas.background) slideProps.background = canvas.background;
+  return {
+    name: "pptx",
+    props: presentationProps,
+    children: [
+      {
+        name: "slide",
+        props: slideProps,
+        children: elements ?? []
+      }
+    ]
+  };
+}
+function defaultVisualWidthPx(props) {
+  return Math.round(props.canvas.width * PIXELS_PER_INCH);
+}
+function visualToImageOptions(props) {
+  return {
+    width: props.width ?? defaultVisualWidthPx(props),
+    ...props.height !== void 0 && { height: props.height },
+    alignment: props.alignment ?? "center",
+    ...props.caption !== void 0 && { caption: props.caption },
+    ...props.spacing !== void 0 && { spacing: props.spacing },
+    ...props.floating !== void 0 && { floating: props.floating },
+    ...props.keepNext !== void 0 && { keepNext: props.keepNext },
+    ...props.keepLines !== void 0 && { keepLines: props.keepLines }
+  };
+}
+async function rasterize(presentation, dpi, propsServerUrl, serviceConfig) {
+  if (!isNodeEnvironment()) {
+    throw new Error(
+      "Visual rasterization requires a Node.js environment. It is not available in browser environments."
+    );
+  }
+  if (serviceConfig?.render) {
+    return serviceConfig.render({ presentation, dpi });
+  }
+  const serverUrl = resolveServiceUrl(
+    propsServerUrl,
+    serviceConfig?.serverUrl,
+    DEFAULT_RASTERIZE_SERVER_URL
+  );
+  const response = await postJsonToService({
+    url: serverUrl,
+    path: "/rasterize",
+    body: { presentation, dpi },
+    headers: serviceConfig?.headers,
+    serviceLabel: "PPTX rasterization service",
+    onUnreachable: (url, cause) => `PPTX rasterization service is not reachable at ${url}. Configure services.pptx with a \`render\` callback or a running \`serverUrl\`.
+Cause: ${cause}`
+  });
+  let result;
+  try {
+    result = await response.json();
+  } catch {
+    throw new Error(
+      "PPTX rasterization service returned a non-JSON response (expected { base64DataUri, width, height })."
+    );
+  }
+  if (!result?.base64DataUri) {
+    throw new Error(
+      "PPTX rasterization service returned a malformed response (missing base64DataUri)."
+    );
+  }
+  return result;
+}
+async function renderVisualComponent(component, theme, themeName, context) {
+  if (!isVisualComponent(component)) return [];
+  const props = component.props;
+  const serviceConfig = context?.services?.pptx;
+  const presentation = buildVisualPresentation(props);
+  const dpi = clampVisualDpi(
+    props.dpi ?? serviceConfig?.dpi ?? DEFAULT_VISUAL_DPI
+  );
+  const result = await rasterize(
+    presentation,
+    dpi,
+    props.serverUrl,
+    serviceConfig
+  );
+  return await createImage(
+    result.base64DataUri,
+    theme,
+    themeName,
+    visualToImageOptions(props)
+  );
+}
+
 // src/components/text-space-after.ts
 import { Type as Type2 } from "@sinclair/typebox";
 
@@ -6624,7 +6761,7 @@ async function renderDocument(structure, layout, options) {
     }
   });
 }
-async function renderHeaderFooterComponents(components, theme, themeName, _context) {
+async function renderHeaderFooterComponents(components, theme, themeName, context) {
   if (!components || components.length === 0) {
     return [];
   }
@@ -6756,6 +6893,14 @@ async function renderHeaderFooterComponents(components, theme, themeName, _conte
     } else if (isTableComponent(component)) {
       const tables = await renderTableComponent(component, theme, themeName);
       elements.push(...tables);
+    } else if (isVisualComponent(component)) {
+      const visualEls = await renderVisualComponent(
+        component,
+        theme,
+        themeName,
+        context
+      );
+      elements.push(...visualEls);
     }
   }
   return elements;
@@ -6876,6 +7021,8 @@ async function renderComponent(component, theme, themeName, context) {
       themeName,
       context
     );
+  } else if (isVisualComponent(component)) {
+    return await renderVisualComponent(component, theme, themeName, context);
   } else if (isSectionComponent(component)) {
     return await renderSectionComponent(component, theme, themeName, context);
   }
@@ -7140,10 +7287,26 @@ 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 baseThemeName = internalDocument.props.theme || "minimal";
       const docTheme = resolveDocumentTheme(baseThemeName);
       const warnings = [];
@@ -7237,21 +7400,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: [
@@ -7301,7 +7464,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);
 }