@json-to-office/core-docx 2.1.0 → 2.4.0

package/dist/index.js

@@ -17,6 +17,7 @@ var __export = (target, all) => {
 // src/themes/defaults.ts
 function ensureThemeDefaults(theme) {
   return {
+    ...theme,
     $schema: theme.$schema,
     name: theme.name || "default",
     displayName: theme.displayName || "Default Theme",
@@ -27,6 +28,7 @@ function ensureThemeDefaults(theme) {
       ...theme.colors || {}
     },
     fonts: {
+      ...theme.fonts || {},
       heading: { ...DEFAULT_FONTS.heading, ...theme.fonts?.heading || {} },
       body: { ...DEFAULT_FONTS.body, ...theme.fonts?.body || {} },
       mono: { ...DEFAULT_FONTS.mono, ...theme.fonts?.mono || {} },
@@ -11298,6 +11300,15 @@ function createRenderContext(document, theme, themeName) {
 }
 
 // src/quality/facts.ts
+import {
+  chartEncodingFor,
+  collectColorLiterals,
+  collectFontFamilies,
+  collectPlaceholders,
+  hasUnitMarker,
+  normalizeHex,
+  normalizeHighchartsChart
+} from "@json-to-office/quality";
 import { DEFAULT_DOCX_RENDERER_ID as DEFAULT_DOCX_RENDERER_ID2 } from "@json-to-office/shared-docx";
 
 // src/core/generationContext.ts
@@ -11539,6 +11550,164 @@ function tableFact(props, path4, availableWidthTwips) {
     explicitWidths
   };
 }
+var SERIES_COLOR_TOKENS = [
+  "primary",
+  "accent",
+  "secondary",
+  "accent4",
+  "accent5",
+  "accent6"
+];
+function chartFact(node, props, path4, paletteTokens) {
+  const base = {
+    id: `docx:chart:${path4}`,
+    kind: "docx/chart",
+    path: path4,
+    componentName: typeof node.name === "string" ? node.name : "",
+    paletteTokens
+  };
+  if (node.name === "highcharts") {
+    const shape = normalizeHighchartsChart(props.options);
+    return {
+      ...base,
+      chartType: shape.chartType,
+      encoding: shape.encoding,
+      threeD: shape.threeD,
+      seriesCount: shape.seriesCount,
+      categoryCount: shape.categoryCount,
+      seriesColorsStated: shape.seriesColorsStated,
+      seriesColorsPath: `${path4}/props/options`,
+      ...shape.valueAxisMin !== void 0 && {
+        valueAxisMin: shape.valueAxisMin
+      },
+      unitStated: shape.unitStated,
+      annotation: {
+        stated: shape.annotationStated,
+        path: path4,
+        slot: "props.options.caption.text"
+      }
+    };
+  }
+  const chartType = typeof props.type === "string" ? props.type : "";
+  if (chartType === "") return void 0;
+  const series = Array.isArray(props.data) ? props.data : [];
+  const categoryCount = Math.max(
+    0,
+    ...series.map((entry) => {
+      const record = asRecord(entry);
+      const labels = Array.isArray(record?.labels) ? record.labels.length : 0;
+      const values = Array.isArray(record?.values) ? record.values.length : 0;
+      return Math.max(labels, values);
+    })
+  );
+  const caption = typeof props.caption === "string" ? props.caption : "";
+  const title = typeof props.title === "string" ? props.title : "";
+  return {
+    ...base,
+    chartType,
+    encoding: chartEncodingFor(chartType),
+    // No 3D type exists in the DOCX chart schema — `office-open` draws none —
+    // so this is always false here, and stays a field rather than an omission
+    // so both formats answer the same questions.
+    threeD: false,
+    seriesCount: series.length,
+    categoryCount,
+    seriesColorsStated: Array.isArray(props.chartColors) && props.chartColors.length > 0,
+    seriesColorsPath: `${path4}/props/chartColors`,
+    // No `valueAxisMin`: a DOCX chart has no axis-floor property, so the
+    // baseline is always the renderer's, which starts a bar at zero.
+    unitStated: hasUnitMarker(
+      typeof props.valAxisTitle === "string" ? props.valAxisTitle : ""
+    ) || hasUnitMarker(title) || hasUnitMarker(caption),
+    annotation: {
+      stated: caption.trim() !== "",
+      path: path4,
+      slot: "props.caption"
+    }
+  };
+}
+var DOCX_ALIGNMENTS = /* @__PURE__ */ new Set(["left", "center", "right", "justify"]);
+function resolvedCellText(content) {
+  return typeof content === "string" ? content : "[component]";
+}
+function statesOwnBorders(authored) {
+  if (!authored) return false;
+  if (authored.borderSize !== void 0 || authored.borderColor !== void 0 || authored.hideBorders !== void 0) {
+    return true;
+  }
+  const layers = [
+    asRecord(authored.cellDefaults),
+    asRecord(authored.headerCellDefaults)
+  ];
+  if (layers.some(
+    (layer) => layer?.borderSize !== void 0 || layer?.borderColor !== void 0
+  )) {
+    return true;
+  }
+  const columns = Array.isArray(authored.columns) ? authored.columns : [];
+  return columns.some((column) => {
+    const record = asRecord(column);
+    const defaults = asRecord(record?.cellDefaults);
+    return defaults?.borderSize !== void 0 || defaults?.borderColor !== void 0;
+  });
+}
+function tableDesignFact(props, path4, theme, themeName, authored) {
+  const authoredColumns = Array.isArray(props.columns) ? props.columns : [];
+  if (authoredColumns.length === 0) return void 0;
+  const model = resolveTableModel(
+    props,
+    theme,
+    themeName
+  );
+  const bodyRows = model.rows;
+  const drawnRows = bodyRows.length + (model.header ? 1 : 0);
+  if (drawnRows === 0) return void 0;
+  const fullGrid = statesOwnBorders(authored) && [...model.header ? [model.header] : [], ...bodyRows].every(
+    (row) => row.cells.every(
+      (cell) => ["top", "right", "bottom", "left"].every(
+        (side) => !cell.borders[side].hidden && cell.borders[side].size > 0
+      )
+    )
+  );
+  const columns = authoredColumns.map(
+    (column, index) => {
+      const authoredColumn = asRecord(column) ?? {};
+      const cells = Array.isArray(authoredColumn.cells) ? authoredColumn.cells : [];
+      const alignments = /* @__PURE__ */ new Set();
+      const values = [];
+      bodyRows.forEach((row) => {
+        const cell = row.cells[index];
+        if (!cell || cell.missing) return;
+        values.push(resolvedCellText(cell.content));
+        alignments.add(cell.horizontalAlignment);
+      });
+      const header = model.header?.cells[index];
+      return {
+        index,
+        path: `${path4}/props/columns/${index}`,
+        ...header?.content !== void 0 && {
+          header: resolvedCellText(header.content)
+        },
+        values,
+        alignment: alignments.size === 1 ? [...alignments][0] : alignments.size === 0 ? "left" : "mixed",
+        hasCellDefaults: asRecord(authoredColumn.cellDefaults) !== void 0,
+        hasHeader: asRecord(authoredColumn.header) !== void 0,
+        cellsWithOwnAlignment: cells.flatMap((cell, cellIndex) => {
+          const alignment2 = asRecord(cell)?.horizontalAlignment;
+          return typeof alignment2 === "string" && DOCX_ALIGNMENTS.has(alignment2) && alignment2 !== "right" ? [cellIndex] : [];
+        })
+      };
+    }
+  );
+  return {
+    id: `docx:table-design:${path4}`,
+    kind: "docx/table",
+    path: path4,
+    columns,
+    rowCount: drawnRows,
+    fullGrid
+  };
+}
 var TWIPS_PER_POINT3 = 20;
 var SINGLE_LINE_RATIO = 1.2;
 function finiteNumber(value) {
@@ -11567,20 +11736,23 @@ function characterSpacingPt(spacing) {
   if (rule === void 0 || value === void 0) return 0;
   return rule.type === "condensed" ? -value / TWIPS_PER_POINT3 : value / TWIPS_PER_POINT3;
 }
-function pointerExists(root, pointer) {
+function nodeAtPointer(root, pointer) {
   let current = root;
   for (const token of pointer.split("/").slice(1)) {
     if (Array.isArray(current)) {
       const index = Number(token);
-      if (!Number.isInteger(index)) return false;
+      if (!Number.isInteger(index)) return void 0;
       current = current[index];
       continue;
     }
     const record = asRecord(current);
-    if (!record) return false;
+    if (!record) return void 0;
     current = record[token];
   }
-  return current !== void 0;
+  return current;
+}
+function pointerExists(root, pointer) {
+  return nodeAtPointer(root, pointer) !== void 0;
 }
 function styleKey(node, props) {
   if (node.name === "heading") {
@@ -11761,6 +11933,67 @@ function prepareDocxQualityDocument(document, options = {}) {
       ...fact.relatedPaths && { relatedPaths: fact.relatedPaths }
     };
   };
+  const paletteHexes = {};
+  for (const [token, value] of Object.entries(
+    resolved.theme.colors ?? {}
+  )) {
+    if (typeof value !== "string") continue;
+    const hex = normalizeHex(value);
+    if (hex) paletteHexes[token] = hex;
+  }
+  const paletteTokens = SERIES_COLOR_TOKENS.filter(
+    (token) => paletteHexes[token] !== void 0
+  );
+  const authoredPropsAt = (pointer) => asRecord(asRecord(nodeAtPointer(context.document, pointer))?.props);
+  addFact({
+    id: "docx:theme",
+    kind: "docx/theme",
+    path: "/props",
+    themeName: context.themeName,
+    paletteHexes,
+    // `heading` and `body` only. A theme also names `mono` and `light`, but
+    // those paint nothing until a component asks for them — counting an
+    // unused `Courier New` against a document's family budget would flag a
+    // report that only ever uses one typeface.
+    fontFamilies: [
+      ...new Set(
+        ["heading", "body"].flatMap((role) => {
+          const family = asRecord(
+            resolved.theme.fonts?.[role]
+          )?.family;
+          return typeof family === "string" && family.trim() !== "" ? [family] : [];
+        })
+      )
+    ]
+  });
+  collectColorLiterals(document).forEach((literal, index) => {
+    addFact({
+      id: `docx:color:${index}:${literal.path}`,
+      kind: "docx/color",
+      path: literal.path,
+      raw: literal.raw,
+      hex: literal.hex
+    });
+  });
+  collectFontFamilies(document).forEach((use, index) => {
+    addFact({
+      id: `docx:font:${index}:${use.path}`,
+      kind: "docx/font-family",
+      path: use.path,
+      family: use.family
+    });
+  });
+  collectPlaceholders(document).forEach((occurrence, index) => {
+    addFact({
+      id: `docx:placeholder:${index}:${occurrence.path}`,
+      kind: "docx/placeholder",
+      path: occurrence.path,
+      text: occurrence.text,
+      placeholderKind: occurrence.match.kind,
+      pattern: occurrence.match.pattern,
+      excerpt: occurrence.match.excerpt
+    });
+  });
   let previousVisitPath;
   let lastFrame;
   let flowIndex = 0;
@@ -11770,6 +12003,18 @@ function prepareDocxQualityDocument(document, options = {}) {
     if (node.name === "table") {
       const fact = tableFact(props, path4, page.availableWidthTwips);
       if (fact) addFact(fact);
+      const design = tableDesignFact(
+        props,
+        path4,
+        resolved.theme,
+        context.themeName,
+        authoredPropsAt(path4)
+      );
+      if (design) addFact(design);
+    }
+    if (node.name === "chart" || node.name === "highcharts") {
+      const fact = chartFact(node, props, path4, paletteTokens);
+      if (fact) addFact(fact);
     }
     if (node.name === "paragraph" || node.name === "text-box") {
       const floating = asRecord(props.floating);
@@ -12193,9 +12438,17 @@ import {
 
 // src/quality/rules.ts
 import {
+  chartInfoDesignFindings,
+  DEFAULT_MAXIMUM_CHART_SERIES,
+  DEFAULT_MAXIMUM_PIE_SLICES,
+  fontCountFinding,
   mergeQualityProfiles,
+  nearestPaletteToken,
+  offPaletteFinding,
+  placeholderFinding,
   QUALITY_CODES,
-  QualityEngine
+  QualityEngine,
+  tableInfoDesignFindings
 } from "@json-to-office/quality";
 
 // src/quality/text-metrics.ts
@@ -12661,6 +12914,179 @@ var docxLineBoxRule = {
     });
   }
 };
+var docxPlaceholderRule = {
+  id: "docx/placeholder-text",
+  code: QUALITY_CODES.PLACEHOLDER_TEXT,
+  category: "integrity",
+  defaultSeverity: "warning",
+  defaultCertainty: "deterministic",
+  formats: ["docx"],
+  evaluate: ({ facts }) => facts.filter(
+    (fact) => fact.kind === "docx/placeholder"
+  ).map(
+    (fact) => placeholderFinding({
+      path: fact.path,
+      kind: fact.placeholderKind,
+      pattern: fact.pattern,
+      excerpt: fact.excerpt
+    })
+  )
+};
+var DEFAULT_MAX_FONT_FAMILIES = 3;
+var docxFontCountRule = {
+  id: "docx/font-count",
+  code: QUALITY_CODES.FONT_COUNT,
+  category: "brand",
+  defaultSeverity: "warning",
+  defaultCertainty: "deterministic",
+  formats: ["docx"],
+  defaultParameters: { maximumFamilies: DEFAULT_MAX_FONT_FAMILIES },
+  evaluate: ({ facts, configuration }) => {
+    const maximum = numberParameter(
+      configuration.parameters,
+      "maximumFamilies",
+      DEFAULT_MAX_FONT_FAMILIES
+    );
+    const theme = facts.find(
+      (fact) => fact.kind === "docx/theme"
+    );
+    const families = new Set(theme?.fontFamilies ?? []);
+    const extraPaths = [];
+    for (const fact of facts) {
+      if (fact.kind !== "docx/font-family") continue;
+      const use = fact;
+      if (!families.has(use.family)) extraPaths.push(use.path);
+      families.add(use.family);
+    }
+    if (families.size <= maximum) return [];
+    return [
+      fontCountFinding({
+        path: theme?.path ?? "/props",
+        families: [...families].sort(),
+        maximum,
+        relatedPaths: [...new Set(extraPaths)]
+      })
+    ];
+  }
+};
+var docxPaletteRule = {
+  id: "docx/palette-adherence",
+  code: QUALITY_CODES.OFF_PALETTE,
+  category: "brand",
+  defaultSeverity: "info",
+  defaultCertainty: "deterministic",
+  formats: ["docx"],
+  evaluate: ({ facts }) => {
+    const theme = facts.find(
+      (fact) => fact.kind === "docx/theme"
+    );
+    const palette = theme?.paletteHexes ?? {};
+    const known = new Set(Object.values(palette));
+    return facts.filter((fact) => fact.kind === "docx/color").filter((fact) => !known.has(fact.hex)).map((fact) => {
+      const nearest = nearestPaletteToken(fact.hex, palette);
+      return offPaletteFinding({
+        path: fact.path,
+        raw: fact.raw,
+        hex: fact.hex,
+        ...nearest && { nearest }
+      });
+    });
+  }
+};
+var DEFAULT_MAX_TABLE_ROWS_PER_PAGE = 25;
+var docxChartRule = {
+  id: "docx/chart-design",
+  code: QUALITY_CODES.CHART_OVERLOADED,
+  category: "information-design",
+  defaultSeverity: "warning",
+  defaultCertainty: "deterministic",
+  formats: ["docx"],
+  defaultParameters: {
+    maximumSeries: DEFAULT_MAXIMUM_CHART_SERIES,
+    maximumSlices: DEFAULT_MAXIMUM_PIE_SLICES
+  },
+  evaluate: ({ facts, configuration }) => {
+    const maximumSeries = numberParameter(
+      configuration.parameters,
+      "maximumSeries",
+      DEFAULT_MAXIMUM_CHART_SERIES
+    );
+    const maximumSlices = numberParameter(
+      configuration.parameters,
+      "maximumSlices",
+      DEFAULT_MAXIMUM_PIE_SLICES
+    );
+    return facts.filter((fact) => fact.kind === "docx/chart").flatMap((fact) => {
+      const fix = seriesColorFix(fact);
+      return chartInfoDesignFindings(fact, {
+        maximumSeries,
+        maximumSlices,
+        ...fix && { seriesColorFix: fix }
+      });
+    });
+  }
+};
+function seriesColorFix(fact) {
+  if (fact.componentName !== "chart") return void 0;
+  if (fact.seriesCount < 1 || fact.paletteTokens.length === 0) return void 0;
+  const tokens = Array.from(
+    { length: fact.seriesCount },
+    (_, index) => fact.paletteTokens[index % fact.paletteTokens.length]
+  );
+  return [{ op: "add", path: fact.seriesColorsPath, value: tokens }];
+}
+var docxTableDesignRule = {
+  id: "docx/table-design",
+  code: QUALITY_CODES.TABLE_NUMERIC_ALIGN,
+  category: "information-design",
+  defaultSeverity: "warning",
+  defaultCertainty: "deterministic",
+  formats: ["docx"],
+  defaultParameters: { maximumRows: DEFAULT_MAX_TABLE_ROWS_PER_PAGE },
+  evaluate: ({ facts, configuration }) => {
+    const maximumRows = numberParameter(
+      configuration.parameters,
+      "maximumRows",
+      DEFAULT_MAX_TABLE_ROWS_PER_PAGE
+    );
+    return facts.filter((fact) => fact.kind === "docx/table").flatMap(
+      (fact) => tableInfoDesignFindings(fact, {
+        maximumRows,
+        rowSurface: "page",
+        rowSeverity: "info",
+        alignFix: alignColumnRight
+      })
+    );
+  }
+};
+function alignColumnRight(column) {
+  const operations = [
+    column.hasCellDefaults ? {
+      op: "add",
+      path: `${column.path}/cellDefaults/horizontalAlignment`,
+      value: "right"
+    } : {
+      op: "add",
+      path: `${column.path}/cellDefaults`,
+      value: { horizontalAlignment: "right" }
+    }
+  ];
+  if (column.hasHeader) {
+    operations.push({
+      op: "add",
+      path: `${column.path}/header/horizontalAlignment`,
+      value: "right"
+    });
+  }
+  for (const index of column.cellsWithOwnAlignment) {
+    operations.push({
+      op: "add",
+      path: `${column.path}/cells/${index}/horizontalAlignment`,
+      value: "right"
+    });
+  }
+  return operations;
+}
 var DOCX_QUALITY_RULES = {
   id: "docx/default",
   rules: [
@@ -12669,7 +13095,12 @@ var DOCX_QUALITY_RULES = {
     docxTextFitRule,
     docxFrameCollisionRule,
     docxSvgTextBoundsRule,
-    docxLineBoxRule
+    docxLineBoxRule,
+    docxPlaceholderRule,
+    docxChartRule,
+    docxTableDesignRule,
+    docxFontCountRule,
+    docxPaletteRule
   ]
 };
 var DOCX_QUALITY_PROFILES = {
@@ -13042,34 +13473,36 @@ function validateDocument(document, customComponents, options) {
   const errors = [...documentResult.errors || []];
   function validateComponents(components, pathPrefix = "children") {
     components.forEach((componentData, index) => {
-      const customComponent = customComponents.find(
-        (cc) => cc.name === componentData.name
-      );
-      if (!customComponent) {
+      if (!componentData || typeof componentData !== "object" || Array.isArray(componentData)) {
         return;
       }
-      const versionEntry = resolveComponentVersion(
-        customComponent.name,
-        customComponent.versions,
-        componentData.version
-      );
-      const validation = validateComponentProps(
-        versionEntry,
-        componentData.props,
-        customComponent.name,
-        // Reject unknown custom props unless the caller allows them.
-        { clean: options?.allowUnknownFields === true }
+      const customComponent = customComponents.find(
+        (cc) => cc.name === componentData.name
       );
-      if (!validation.valid && validation.errors) {
-        const indexedErrors = validation.errors.map(
-          (error) => ({
-            ...error,
-            path: `${pathPrefix}[${index}].${error.path}`
-          })
+      if (customComponent) {
+        const versionEntry = resolveComponentVersion(
+          customComponent.name,
+          customComponent.versions,
+          componentData.version
+        );
+        const validation = validateComponentProps(
+          versionEntry,
+          componentData.props,
+          customComponent.name,
+          // Reject unknown custom props unless the caller allows them.
+          { clean: options?.allowUnknownFields === true }
         );
-        errors.push(...indexedErrors);
+        if (!validation.valid && validation.errors) {
+          const indexedErrors = validation.errors.map(
+            (error) => ({
+              ...error,
+              path: `${pathPrefix}[${index}].${error.path}`
+            })
+          );
+          errors.push(...indexedErrors);
+        }
       }
-      if (componentData.children && Array.isArray(componentData.children)) {
+      if (Array.isArray(componentData.children)) {
         validateComponents(
           componentData.children,
           `${pathPrefix}[${index}].children`