@json-to-office/core-docx 3.3.0 → 4.0.0

package/dist/index.js

@@ -246,6 +246,7 @@ var init_minimal_docx_theme = __esm({
       name: "minimal",
       displayName: "Minimal Clean",
       description: "A quiet, warm minimal theme \u2014 Calibri throughout, sage-green ink on ivory neutrals, a large tracked-tight bold title, wide margins and hairline rules",
+      whenToUse: "Quiet documents where the type carries the tone: notes, briefs, drafts and internal papers that want warmth without decoration.",
       version: "4.0.0",
       colors: {
         primary: "#2B302B",
@@ -435,6 +436,7 @@ var init_devportal_docx_theme = __esm({
       name: "devportal",
       displayName: "Field Editorial",
       description: "A compact editorial theme \u2014 Helvetica in near-black ink with a burnt-orange accent, tight condensed titles, letterspaced labels, warm tinted fills and hairline rules",
+      whenToUse: "Developer and product documentation, API guides and technical handbooks: dense text, code and tables that need compact, letterspaced structure.",
       version: "4.0.0",
       colors: {
         primary: "#12191F",
@@ -633,6 +635,7 @@ var init_vermilion_docx_theme = __esm({
       name: "vermilion",
       displayName: "Vermilion Editorial",
       description: "Poster-red editorial system \u2014 vermilion display headings, ink text, warm creams and hairline rules",
+      whenToUse: "Editorial and annual-report work that wants a strong red display voice: covers, feature-style sections, reports built around a few large headings.",
       version: "1.0.0",
       colors: {
         primary: "#282829",
@@ -851,6 +854,7 @@ var init_consulting_docx_theme = __esm({
       name: "consulting",
       displayName: "Consulting House",
       description: "The house style for client and technical reports \u2014 near-black ink, three greys and one deep-blue accent, Calibri body under Arial headings, hairline rules, no fills behind body text, safe fonts only",
+      whenToUse: "Client and technical reports, memos and anything a client will read as the house's own work; the default choice for a report unless the brief names a brand.",
       version: "1.0.0",
       colors: {
         primary: "#1A1F26",
@@ -11876,8 +11880,10 @@ import {
 } from "@json-to-office/quality";
 import { DEFAULT_DOCX_RENDERER_ID as DEFAULT_DOCX_RENDERER_ID2 } from "@json-to-office/shared-docx";
 import {
+  designCanvas as designCanvas2,
   designColors as designColors2,
-  resolveDesignColor as resolveDesignColor2
+  resolveDesignColor as resolveDesignColor2,
+  typeScaleSizes
 } from "@json-to-office/shared";
 
 // src/core/generationContext.ts
@@ -12817,6 +12823,93 @@ function walkActive(node, path4, page, visit) {
     (child, index) => walkActive(child, `${path4}/children/${index}`, page, visit)
   );
 }
+function textSizeFact(node, props, path4, typography, role) {
+  const size = effectiveFontSize(node, props, typography);
+  if (size === void 0) return void 0;
+  return {
+    id: `docx:text-size:${path4}`,
+    kind: "docx/text-size",
+    path: path4,
+    role: role ?? styleKey(node, props),
+    fontSizePt: size.fontSizePt,
+    authored: size.authored,
+    ...size.authored && { sizePath: `${path4}/props/font/size` }
+  };
+}
+function tableTextSizeFacts(props, authored, path4, typography, page) {
+  const facts = [];
+  const sizeOf = (holder) => finiteNumber(asRecord(asRecord(holder)?.font)?.size);
+  const authoredSize = (holder, pointer, role) => {
+    const size = sizeOf(holder);
+    if (size === void 0) return;
+    facts.push({
+      id: `docx:text-size:${pointer}`,
+      kind: "docx/text-size",
+      path: pointer,
+      role,
+      fontSizePt: size,
+      authored: true,
+      sizePath: `${pointer}/font/size`
+    });
+  };
+  const cellContent = (holder, pointer, role) => {
+    const content = asRecord(holder)?.content;
+    if (asRecord(content) === void 0) return;
+    walkActive(content, `${pointer}/content`, page, (node, nodePath) => {
+      if (node.name !== "paragraph" && node.name !== "heading") return;
+      const nodeProps = asRecord(node.props) ?? {};
+      if (typeof nodeProps.text !== "string" || nodeProps.text.trim() === "")
+        return;
+      const fact = textSizeFact(node, nodeProps, nodePath, typography, role);
+      if (fact) facts.push(fact);
+    });
+  };
+  if (authored) {
+    authoredSize(
+      authored.cellDefaults,
+      `${path4}/props/cellDefaults`,
+      "tableCell"
+    );
+    authoredSize(
+      authored.headerCellDefaults,
+      `${path4}/props/headerCellDefaults`,
+      "tableHeader"
+    );
+    const columns = Array.isArray(authored.columns) ? authored.columns : [];
+    columns.forEach((column, index) => {
+      const record = asRecord(column) ?? {};
+      const columnPath = `${path4}/props/columns/${index}`;
+      authoredSize(
+        record.cellDefaults,
+        `${columnPath}/cellDefaults`,
+        "tableCell"
+      );
+      authoredSize(record.header, `${columnPath}/header`, "tableHeader");
+      cellContent(record.header, `${columnPath}/header`, "tableHeader");
+      const cells = Array.isArray(record.cells) ? record.cells : [];
+      cells.forEach((cell, cellIndex) => {
+        authoredSize(cell, `${columnPath}/cells/${cellIndex}`, "tableCell");
+        cellContent(cell, `${columnPath}/cells/${cellIndex}`, "tableCell");
+      });
+    });
+  }
+  for (const [key, role] of [
+    ["cellDefaults", "tableCell"],
+    ["headerCellDefaults", "tableHeader"]
+  ]) {
+    const size = sizeOf(props[key]);
+    if (size === void 0) continue;
+    facts.push({
+      id: `docx:text-size:${path4}:${role}`,
+      kind: "docx/text-size",
+      path: path4,
+      role,
+      fontSizePt: size,
+      authored: false
+    });
+  }
+  return facts;
+}
 function prepareDocxQualityDocument(document, options = {}) {
   const themed = options.context ?? resolveThemeContext(normalizeDocument(document)[0], {
     customThemes: options.customThemes,
@@ -12886,6 +12979,43 @@ function prepareDocxQualityDocument(document, options = {}) {
     const header = part("header");
     const footer = part("footer");
     inherited = { header, footer };
+    for (const kind of ["header", "footer"]) {
+      if (!Array.isArray(props[kind])) continue;
+      const drawnByBlock = !Array.isArray(
+        asRecord(
+          asRecord(
+            (Array.isArray(themed.document.children) ? themed.document.children : [])[index]
+          )?.props
+        )?.[kind]
+      );
+      const part2 = props[kind];
+      const visitChrome = (child, childPath) => {
+        if (child.name !== "paragraph" && child.name !== "heading") return;
+        const childProps = asRecord(child.props) ?? {};
+        if (typeof childProps.text !== "string" || childProps.text.trim() === "")
+          return;
+        const fact = textSizeFact(
+          child,
+          childProps,
+          childPath,
+          typography,
+          kind
+        );
+        if (fact)
+          addFact({
+            ...fact,
+            generated: drawnByBlock || authoredPath(childPath) !== childPath
+          });
+      };
+      part2.forEach(
+        (child, childIndex) => walkActive(
+          child,
+          `/children/${index}/props/${kind}/${childIndex}`,
+          basePage,
+          visitChrome
+        )
+      );
+    }
     addFact({
       id: `docx:section-chrome:${index}`,
       kind: "docx/section-chrome",
@@ -12919,12 +13049,34 @@ function prepareDocxQualityDocument(document, options = {}) {
     (value) => `#${resolveDesignColor2(value, visualColors)}`
   ) ?? SERIES_COLOR_TOKENS.filter((token) => paletteHexes[token] !== void 0);
   const authoredPropsAt = (pointer) => asRecord(asRecord(nodeAtPointer(context.document, pointer))?.props);
+  const roleSizesPt = {};
+  for (const key of Object.keys(typography.styles)) {
+    const size = effectiveFontSize(
+      { name: "paragraph" },
+      { themeStyle: key },
+      typography
+    );
+    if (size) roleSizesPt[key] = size.fontSizePt;
+  }
+  const scale = resolved.theme.typography?.scale?.[designCanvas2("docx", resolved.theme.page?.size)];
+  const typeScalePt = [
+    .../* @__PURE__ */ new Set([
+      ...Object.values(roleSizesPt),
+      ...["heading", "body", "mono", "light"].flatMap((role) => {
+        const size = resolveFontSize(resolved.theme, role);
+        return size === void 0 ? [] : [size];
+      }),
+      ...scale ? typeScaleSizes(scale) : []
+    ])
+  ].sort((a, b) => a - b);
   addFact({
     id: "docx:theme",
     kind: "docx/theme",
     path: "/props",
     themeName: context.themeName,
     paletteHexes,
+    typeScalePt,
+    roleSizesPt,
     // `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
@@ -12977,6 +13129,15 @@ function prepareDocxQualityDocument(document, options = {}) {
     if (node.name === "table") {
       const fact = tableFact(props, path4, page.availableWidthTwips);
       if (fact) addFact(fact);
+      for (const size of tableTextSizeFacts(
+        props,
+        authoredPropsAt(path4),
+        path4,
+        typography,
+        page
+      )) {
+        addFact({ ...size, generated: authoredPath(size.path) !== size.path });
+      }
       const design = tableDesignFact(
         props,
         path4,
@@ -13035,6 +13196,10 @@ function prepareDocxQualityDocument(document, options = {}) {
     if (node.name === "paragraph" || node.name === "heading") {
       const fact = lineBoxFact(node, props, path4, typography, context.document);
       if (fact) addFact(fact);
+      if (typeof props.text === "string" && props.text.trim() !== "") {
+        const fact2 = textSizeFact(node, props, path4, typography);
+        if (fact2) addFact({ ...fact2, generated: authoredPath(path4) !== path4 });
+      }
     }
     if (node.name === "image" || node.name === "visual") {
       for (const fact of svgTextFacts(props, path4)) addFact(fact);
@@ -13607,6 +13772,7 @@ function numberParameter(parameters, name, fallback) {
 }
 var docxTableWidthRule = {
   id: "docx/table-width",
+  description: "Explicit column widths that sum past the usable width of their section.",
   code: QUALITY_CODES.TABLE_WIDTH_OVERFLOW,
   category: "integrity",
   defaultSeverity: "warning",
@@ -13654,6 +13820,7 @@ var docxTableWidthRule = {
 };
 var docxHeadingHierarchyRule = {
   id: "docx/heading-hierarchy",
+  description: "A heading that skips a level and breaks the outline.",
   code: QUALITY_CODES.HEADING_SKIP,
   category: "hierarchy",
   defaultSeverity: "info",
@@ -13697,6 +13864,7 @@ function frameTextFacts(facts) {
 }
 var docxTextFitRule = {
   id: "docx/text-fit",
+  description: "A word too wide for its floating frame, or a frame whose wrapped text runs off the sheet.",
   code: QUALITY_CODES.TEXT_OVERFLOW,
   category: "integrity",
   defaultSeverity: "warning",
@@ -13770,6 +13938,7 @@ var docxTextFitRule = {
 var FRAME_COLLISION_MIN_WIDTH_TWIPS = 240;
 var docxFrameCollisionRule = {
   id: "docx/frame-collision",
+  description: "Two page-anchored frames whose estimated text lands on the same region of a page.",
   code: QUALITY_CODES.FRAME_COLLISION,
   category: "integrity",
   defaultSeverity: "warning",
@@ -13866,6 +14035,7 @@ var docxFrameCollisionRule = {
 };
 var docxSvgTextBoundsRule = {
   id: "docx/svg-text-bounds",
+  description: "A text baseline outside an inline SVG\u2019s viewBox, so the words are never painted.",
   code: QUALITY_CODES.SVG_TEXT_CLIPPED,
   category: "integrity",
   defaultSeverity: "warning",
@@ -13901,6 +14071,7 @@ function tenths(value) {
 }
 var docxLineBoxRule = {
   id: "docx/line-box",
+  description: "An `exactly` line box shorter than the capitals it has to hold.",
   code: QUALITY_CODES.LINE_BOX_COLLAPSE,
   category: "legibility",
   defaultSeverity: "warning",
@@ -13954,6 +14125,7 @@ var docxLineBoxRule = {
 };
 var docxPlaceholderRule = {
   id: "docx/placeholder-text",
+  description: "An unfilled scaffold slot, or leftover filler copy.",
   code: QUALITY_CODES.PLACEHOLDER_TEXT,
   category: "integrity",
   defaultSeverity: "warning",
@@ -13972,6 +14144,7 @@ var docxPlaceholderRule = {
 };
 var docxSlotBudgetRule = {
   id: "docx/slot-budget",
+  description: "A block slot holding more words than its budget allows \u2014 a takeaway past the word count the block sets.",
   code: QUALITY_CODES.SLOT_BUDGET,
   category: "composition",
   defaultSeverity: "warning",
@@ -13995,6 +14168,7 @@ var docxSlotBudgetRule = {
 var DEFAULT_MAX_FONT_FAMILIES = 3;
 var docxFontCountRule = {
   id: "docx/font-count",
+  description: "Distinct font families the document can paint.",
   code: QUALITY_CODES.FONT_COUNT,
   category: "brand",
   defaultSeverity: "warning",
@@ -14031,6 +14205,7 @@ var docxFontCountRule = {
 };
 var docxPaletteRule = {
   id: "docx/palette-adherence",
+  description: "A literal colour the resolved theme does not define.",
   code: QUALITY_CODES.OFF_PALETTE,
   category: "brand",
   defaultSeverity: "info",
@@ -14056,6 +14231,7 @@ var docxPaletteRule = {
 var DEFAULT_MAX_TABLE_ROWS_PER_PAGE = 25;
 var docxChartRule = {
   id: "docx/chart-design",
+  description: "What a chart claims about its numbers: the comparison, the palette, the unit and the caption.",
   code: QUALITY_CODES.CHART_OVERLOADED,
   category: "information-design",
   defaultSeverity: "warning",
@@ -14097,6 +14273,7 @@ function seriesColorFix(fact) {
 }
 var docxTableDesignRule = {
   id: "docx/table-design",
+  description: "How a table lays its numbers out: alignment, rounding, rules and length.",
   code: QUALITY_CODES.TABLE_NUMERIC_ALIGN,
   category: "information-design",
   defaultSeverity: "warning",
@@ -14154,6 +14331,7 @@ function stringListParameter(parameters, name) {
 }
 var docxRequiredChromeRule = {
   id: "docx/required-chrome",
+  description: "A block slot with a role a profile or policy requires \u2014 a takeaway, a source \u2014 left empty. Off until one names roles.",
   code: QUALITY_CODES.CHROME_MISSING,
   category: "consistency",
   defaultSeverity: "warning",
@@ -14177,6 +14355,7 @@ var docxRequiredChromeRule = {
 var SECTION_CHROME_PARTS = ["header", "footer", "pageNumber"];
 var docxRunningHeadRule = {
   id: "docx/running-head",
+  description: "A body section without the running head a profile or policy expects. Off until one names parts.",
   code: QUALITY_CODES.CHROME_MISSING,
   category: "consistency",
   defaultSeverity: "warning",
@@ -14209,6 +14388,170 @@ var docxRunningHeadRule = {
     });
   }
 };
+var SIZE_TOLERANCE_PT = 0.25;
+function themeFact(facts) {
+  return facts.find(
+    (fact) => fact.kind === "docx/theme"
+  );
+}
+function textSizeFacts(facts) {
+  return facts.filter(
+    (fact) => fact.kind === "docx/text-size"
+  );
+}
+function roleDriftFacts(facts, theme) {
+  const byRole = /* @__PURE__ */ new Map();
+  for (const fact of textSizeFacts(facts)) {
+    byRole.set(fact.role, [...byRole.get(fact.role) ?? [], fact]);
+  }
+  const drifting = /* @__PURE__ */ new Map();
+  for (const [role, members] of byRole) {
+    const sizes = [...new Set(members.map((fact) => fact.fontSizePt))].sort(
+      (a, b) => a - b
+    );
+    if (sizes.length < 2) continue;
+    const expected = theme?.roleSizesPt[role];
+    if (expected === void 0) continue;
+    for (const fact of members) {
+      if (fact.sizePath !== void 0 && !fact.generated && Math.abs(fact.fontSizePt - expected) > SIZE_TOLERANCE_PT)
+        drifting.set(fact, { expected, sizes });
+    }
+  }
+  return drifting;
+}
+function nearestSize(size, scale) {
+  let best;
+  for (const candidate of scale) {
+    if (best === void 0 || Math.abs(candidate - size) < Math.abs(best - size))
+      best = candidate;
+  }
+  return best;
+}
+var docxTypeScaleRule = {
+  id: "docx/type-scale",
+  description: "An authored size the theme never paints: not a style, not a font role, not a step of its scale. Off until a profile or policy enables it.",
+  code: QUALITY_CODES.TYPE_OFF_SCALE,
+  category: "consistency",
+  defaultSeverity: "warning",
+  defaultCertainty: "deterministic",
+  formats: ["docx"],
+  defaultEnabled: false,
+  evaluate: ({ facts }) => {
+    const theme = themeFact(facts);
+    const scale = theme?.typeScalePt ?? [];
+    if (scale.length === 0) return [];
+    const drifting = roleDriftFacts(facts, theme);
+    const offScale = textSizeFacts(facts).filter(
+      (fact) => fact.sizePath !== void 0 && !fact.generated && !drifting.has(fact) && !scale.some(
+        (size) => Math.abs(size - fact.fontSizePt) <= SIZE_TOLERANCE_PT
+      )
+    );
+    const groups = /* @__PURE__ */ new Map();
+    for (const fact of offScale) {
+      const key = `${fact.role}@${fact.fontSizePt}`;
+      groups.set(key, [...groups.get(key) ?? [], fact]);
+    }
+    return [...groups.values()].map((members) => {
+      const [first] = members;
+      const nearest = nearestSize(first.fontSizePt, scale);
+      const sizePaths = members.map((fact) => fact.sizePath);
+      const count = members.length === 1 ? "" : ` (${members.length} places, patched together)`;
+      return {
+        path: sizePaths[0],
+        ...sizePaths.length > 1 && { relatedPaths: sizePaths.slice(1) },
+        message: `${first.fontSizePt}pt is not a size the ${theme.themeName} theme paints; the nearest on its scale is ${nearest}pt${count}.`,
+        suggestion: `Use ${nearest}pt, or drop the size and let the "${first.role}" style set it.`,
+        context: { role: first.role, scale, paths: sizePaths },
+        evidence: {
+          actual: first.fontSizePt,
+          expected: nearest,
+          unit: "pt",
+          values: { source: "theme" }
+        },
+        fixes: sizePaths.map((path4) => ({
+          op: "replace",
+          path: path4,
+          value: nearest
+        }))
+      };
+    });
+  }
+};
+var docxSizeCountRule = {
+  id: "docx/size-count",
+  description: "More distinct text sizes than maximumSizes allows, blocks included. Off until a profile or policy enables it.",
+  code: QUALITY_CODES.TYPE_SIZE_COUNT,
+  category: "consistency",
+  defaultSeverity: "warning",
+  defaultCertainty: "deterministic",
+  formats: ["docx"],
+  defaultEnabled: false,
+  defaultParameters: { maximumSizes: 8 },
+  evaluate: ({ facts, configuration, profile }) => {
+    const maximum = numberParameter(
+      configuration.parameters,
+      "maximumSizes",
+      8
+    );
+    const firstPathBySize = /* @__PURE__ */ new Map();
+    for (const fact of textSizeFacts(facts)) {
+      const size = Math.round(fact.fontSizePt * 4) / 4;
+      if (!firstPathBySize.has(size)) firstPathBySize.set(size, fact.path);
+    }
+    if (firstPathBySize.size <= maximum) return [];
+    const sizes = [...firstPathBySize.keys()].sort((a, b) => a - b);
+    return [
+      {
+        path: themeFact(facts)?.path ?? "/props",
+        relatedPaths: sizes.map((size) => firstPathBySize.get(size)),
+        message: `The document paints ${sizes.length} distinct text sizes (${sizes.join(", ")}pt); the ${profile?.id ?? "selected"} profile allows ${maximum}.`,
+        suggestion: "Keep to the theme styles \u2014 title, headings, body, label, source \u2014 and drop the ad-hoc sizes.",
+        context: { sizes, maximum },
+        evidence: {
+          actual: sizes.length,
+          expected: maximum,
+          values: { source: "profile" }
+        }
+      }
+    ];
+  }
+};
+var docxRoleDriftRule = {
+  id: "docx/role-drift",
+  description: "One heading level, table role or paragraph style painted at two sizes; the theme size is the fix. Off until a profile or policy enables it.",
+  code: QUALITY_CODES.TYPE_ROLE_DRIFT,
+  category: "consistency",
+  defaultSeverity: "warning",
+  defaultCertainty: "deterministic",
+  formats: ["docx"],
+  defaultEnabled: false,
+  evaluate: ({ facts }) => {
+    const theme = themeFact(facts);
+    const findings = [];
+    for (const [fact, { expected, sizes }] of roleDriftFacts(facts, theme)) {
+      const keeper = textSizeFacts(facts).find(
+        (member) => member.role === fact.role && Math.abs(member.fontSizePt - expected) <= SIZE_TOLERANCE_PT
+      );
+      const others = sizes.filter((size) => size !== fact.fontSizePt);
+      const sizePath = fact.sizePath;
+      findings.push({
+        path: sizePath,
+        ...keeper && { relatedPaths: [keeper.path] },
+        message: `"${fact.role}" is painted at ${fact.fontSizePt}pt here and at ${others.join("pt, ")}pt elsewhere; the theme sets it at ${expected}pt.`,
+        suggestion: `Drop the size so "${fact.role}" paints at the theme's ${expected}pt.`,
+        context: { role: fact.role, sizes },
+        evidence: {
+          actual: fact.fontSizePt,
+          expected,
+          unit: "pt",
+          values: { role: fact.role, source: "theme" }
+        },
+        fixes: [{ op: "replace", path: sizePath, value: expected }]
+      });
+    }
+    return findings;
+  }
+};
 var DOCX_QUALITY_RULES = {
   id: "docx/default",
   rules: [
@@ -14225,14 +14568,17 @@ var DOCX_QUALITY_RULES = {
     docxFontCountRule,
     docxPaletteRule,
     docxRequiredChromeRule,
-    docxRunningHeadRule
+    docxRunningHeadRule,
+    docxTypeScaleRule,
+    docxSizeCountRule,
+    docxRoleDriftRule
   ]
 };
 var DOCX_QUALITY_PROFILES = {
   "client-report": {
     id: "client-report",
     formats: ["docx"],
-    description: "Client or public-administration report: a running head with page numbers on every section after the cover, a takeaway and a source wherever a block declares them, no heading skipped.",
+    description: "Client or public-administration report: a running head with page numbers on every section after the cover, a takeaway and a source wherever a block declares them, no heading skipped, and every size on the theme scale with at most eight in play.",
     rules: {
       "docx/required-chrome": {
         parameters: { required: ["takeaway", "source"] }
@@ -14243,7 +14589,10 @@ var DOCX_QUALITY_PROFILES = {
           fromSection: 1
         }
       },
-      "docx/heading-hierarchy": { severity: "warning" }
+      "docx/heading-hierarchy": { severity: "warning" },
+      "docx/type-scale": { enabled: true },
+      "docx/size-count": { enabled: true, parameters: { maximumSizes: 8 } },
+      "docx/role-drift": { enabled: true }
     }
   },
   "executive-report": {