@beyondwork/docx-react-component 1.0.36 → 1.0.38

package/src/io/export/serialize-numbering.ts

@@ -3,6 +3,7 @@ import {
   isSyntheticDocxNullAbstractDefinition,
   isSyntheticDocxNullNumberingInstance,
 } from "../ooxml/numbering-sentinels.ts";
+import { twip } from "./twip.ts";
 
 export const WORD_NUMBERING_CONTENT_TYPE =
   "application/vnd.openxmlformats-officedocument.wordprocessingml.numbering+xml";
@@ -48,14 +49,18 @@ export function serializeParagraphNumberingProperties(
     return "";
   }
 
-  return `<w:numPr><w:ilvl w:val="${numbering.level}"/><w:numId w:val="${escapeAttribute(
-    stripCanonicalPrefix(numbering.numberingInstanceId, "num:"),
+  return `<w:numPr><w:ilvl w:val="${clampIlvl(numbering.level)}"/><w:numId w:val="${escapeAttribute(
+    clampNonNegativeIdString(
+      stripCanonicalPrefix(numbering.numberingInstanceId, "num:"),
+    ),
   )}"/></w:numPr>`;
 }
 
 function serializeAbstractDefinition(definition: NumberingCatalog["abstractDefinitions"][string]): string {
   const abstractNumId = escapeAttribute(
-    stripCanonicalPrefix(definition.abstractNumberingId, "abstract-num:"),
+    clampNonNegativeIdString(
+      stripCanonicalPrefix(definition.abstractNumberingId, "abstract-num:"),
+    ),
   );
   const levels = [...definition.levels]
     .sort((left, right) => left.level - right.level)
@@ -69,7 +74,10 @@ function serializeLevel(
   level: NumberingCatalog["abstractDefinitions"][string]["levels"][number],
   serializedLevel = level.level,
 ): string {
-  const start = level.startAt !== undefined ? `<w:start w:val="${level.startAt}"/>` : "";
+  const start =
+    level.startAt !== undefined
+      ? `<w:start w:val="${clampStart(level.startAt)}"/>`
+      : "";
   const paragraphStyle = level.paragraphStyleId
     ? `<w:pStyle w:val="${escapeAttribute(level.paragraphStyleId)}"/>`
     : "";
@@ -80,7 +88,7 @@ function serializeLevel(
     : "";
   const paragraphProperties = serializeLevelParagraphGeometry(level.paragraphGeometry);
 
-  return `<w:lvl w:ilvl="${serializedLevel}">${start}<w:numFmt w:val="${escapeAttribute(
+  return `<w:lvl w:ilvl="${clampIlvl(serializedLevel)}">${start}<w:numFmt w:val="${escapeAttribute(
     level.format,
   )}"/><w:lvlText w:val="${escapeAttribute(level.text)}"/>${paragraphStyle}${isLegal}${suffix}${justification}${paragraphProperties}</w:lvl>`;
 }
@@ -93,7 +101,10 @@ function serializeLevelOverride(
     return "";
   }
 
-  const start = level.startAt !== undefined ? `<w:start w:val="${level.startAt}"/>` : "";
+  const start =
+    level.startAt !== undefined
+      ? `<w:start w:val="${clampStart(level.startAt)}"/>`
+      : "";
   const format = level.format ? `<w:numFmt w:val="${escapeAttribute(level.format)}"/>` : "";
   const text = level.text !== undefined
     ? `<w:lvlText w:val="${escapeAttribute(level.text)}"/>`
@@ -101,12 +112,17 @@ function serializeLevelOverride(
   const paragraphStyle = level.paragraphStyleId
     ? `<w:pStyle w:val="${escapeAttribute(level.paragraphStyleId)}"/>`
     : "";
+  // ST_OnOff element (A.3):
+  // - true  → <w:isLgl/>.
+  // - false → <w:isLgl w:val="false"/> (explicit override of a parent
+  //            abstract level that declared legal numbering on).
+  // - undefined → omit.
   const isLegal =
-    level.isLegalNumbering === undefined
-      ? ""
-      : level.isLegalNumbering
-        ? "<w:isLgl/>"
-        : `<w:isLgl w:val="0"/>`;
+    level.isLegalNumbering === true
+      ? "<w:isLgl/>"
+      : level.isLegalNumbering === false
+        ? `<w:isLgl w:val="false"/>`
+        : "";
   const suffix = level.suffix ? `<w:suff w:val="${escapeAttribute(level.suffix)}"/>` : "";
   const justification = level.paragraphGeometry?.justification
     ? `<w:lvlJc w:val="${escapeAttribute(level.paragraphGeometry.justification)}"/>`
@@ -114,13 +130,19 @@ function serializeLevelOverride(
   const paragraphProperties = serializeLevelParagraphGeometry(level.paragraphGeometry);
   const body = `${start}${format}${text}${paragraphStyle}${isLegal}${suffix}${justification}${paragraphProperties}`;
 
-  return body.length > 0 ? `<w:lvl w:ilvl="${serializedLevel}">${body}</w:lvl>` : "";
+  return body.length > 0
+    ? `<w:lvl w:ilvl="${clampIlvl(serializedLevel)}">${body}</w:lvl>`
+    : "";
 }
 
 function serializeInstance(instance: NumberingCatalog["instances"][string]): string {
-  const numId = escapeAttribute(stripCanonicalPrefix(instance.numberingInstanceId, "num:"));
+  const numId = escapeAttribute(
+    clampNonNegativeIdString(stripCanonicalPrefix(instance.numberingInstanceId, "num:")),
+  );
   const abstractNumId = escapeAttribute(
-    stripCanonicalPrefix(instance.abstractNumberingId, "abstract-num:"),
+    clampNonNegativeIdString(
+      stripCanonicalPrefix(instance.abstractNumberingId, "abstract-num:"),
+    ),
   );
   const overrides = [...instance.overrides]
     .sort((left, right) => left.level - right.level)
@@ -132,11 +154,13 @@ function serializeInstance(instance: NumberingCatalog["instances"][string]): str
 
 function serializeOverride(override: NumberingCatalog["instances"][string]["overrides"][number]): string {
   const startOverride =
-    override.startAt !== undefined ? `<w:startOverride w:val="${override.startAt}"/>` : "";
+    override.startAt !== undefined
+      ? `<w:startOverride w:val="${clampStart(override.startAt)}"/>`
+      : "";
   const levelDefinition = override.levelDefinition
     ? serializeLevelOverride(override.levelDefinition, override.level)
     : "";
-  return `<w:lvlOverride w:ilvl="${override.level}">${startOverride}${levelDefinition}</w:lvlOverride>`;
+  return `<w:lvlOverride w:ilvl="${clampIlvl(override.level)}">${startOverride}${levelDefinition}</w:lvlOverride>`;
 }
 
 function serializeLevelParagraphGeometry(
@@ -150,13 +174,13 @@ function serializeLevelParagraphGeometry(
   if (paragraphGeometry.spacing) {
     const attrs: string[] = [];
     if (paragraphGeometry.spacing.before !== undefined) {
-      attrs.push(`w:before="${paragraphGeometry.spacing.before}"`);
+      attrs.push(`w:before="${twip(paragraphGeometry.spacing.before)}"`);
     }
     if (paragraphGeometry.spacing.after !== undefined) {
-      attrs.push(`w:after="${paragraphGeometry.spacing.after}"`);
+      attrs.push(`w:after="${twip(paragraphGeometry.spacing.after)}"`);
     }
     if (paragraphGeometry.spacing.line !== undefined) {
-      attrs.push(`w:line="${paragraphGeometry.spacing.line}"`);
+      attrs.push(`w:line="${twip(paragraphGeometry.spacing.line)}"`);
     }
     if (paragraphGeometry.spacing.lineRule !== undefined) {
       attrs.push(`w:lineRule="${paragraphGeometry.spacing.lineRule}"`);
@@ -169,16 +193,16 @@ function serializeLevelParagraphGeometry(
   if (paragraphGeometry.indentation) {
     const attrs: string[] = [];
     if (paragraphGeometry.indentation.left !== undefined) {
-      attrs.push(`w:left="${paragraphGeometry.indentation.left}"`);
+      attrs.push(`w:left="${twip(paragraphGeometry.indentation.left)}"`);
     }
     if (paragraphGeometry.indentation.right !== undefined) {
-      attrs.push(`w:right="${paragraphGeometry.indentation.right}"`);
+      attrs.push(`w:right="${twip(paragraphGeometry.indentation.right)}"`);
     }
     if (paragraphGeometry.indentation.firstLine !== undefined) {
-      attrs.push(`w:firstLine="${paragraphGeometry.indentation.firstLine}"`);
+      attrs.push(`w:firstLine="${twip(paragraphGeometry.indentation.firstLine)}"`);
     }
     if (paragraphGeometry.indentation.hanging !== undefined) {
-      attrs.push(`w:hanging="${paragraphGeometry.indentation.hanging}"`);
+      attrs.push(`w:hanging="${twip(paragraphGeometry.indentation.hanging)}"`);
     }
     if (attrs.length > 0) {
       children.push(`<w:ind ${attrs.join(" ")}/>`);
@@ -189,7 +213,7 @@ function serializeLevelParagraphGeometry(
     const tabsXml = paragraphGeometry.tabStops.map((tab) => {
       const leader = tab.leader === "middleDot" ? "middledot" : tab.leader;
       const leaderAttr = leader ? ` w:leader="${leader}"` : "";
-      return `<w:tab w:val="${tab.align}" w:pos="${tab.position}"${leaderAttr}/>`;
+      return `<w:tab w:val="${tab.align}" w:pos="${twip(tab.position)}"${leaderAttr}/>`;
     }).join("");
     children.push(`<w:tabs>${tabsXml}</w:tabs>`);
   }
@@ -197,6 +221,72 @@ function serializeLevelParagraphGeometry(
   return children.length > 0 ? `<w:pPr>${children.join("")}</w:pPr>` : "";
 }
 
+/**
+ * ST_DecimalNumberOrPercent / ST_DecimalNumber based ilvl/numId/abstractNumId
+ * attributes are integer-typed. Ilvl is bounded 0-8 by the schema.
+ * Negative ids violate MinInclusive ≥ 0 and make the validator fail.
+ * These clampers normalise at the authoring edge (A.6 MinInclusive clamp).
+ */
+function clampIlvl(value: number | undefined): number {
+  if (value === undefined || !Number.isFinite(value)) return 0;
+  const rounded = Math.round(value);
+  if (rounded < 0) {
+    warnClamp("w:ilvl", rounded, 0);
+    return 0;
+  }
+  if (rounded > 8) {
+    warnClamp("w:ilvl", rounded, 8);
+    return 8;
+  }
+  return rounded;
+}
+
+function clampStart(value: number | undefined): number {
+  if (value === undefined || !Number.isFinite(value)) return 1;
+  const rounded = Math.round(value);
+  // w:start MinInclusive per the schema is 0 (0 is legal for Word-created
+  // lists that begin with a 0-based custom format). Negative values fail.
+  if (rounded < 0) {
+    warnClamp("w:start", rounded, 0);
+    return 0;
+  }
+  return rounded;
+}
+
+/**
+ * Clamp a stringified id attribute (w:numId / w:abstractNumId) to the
+ * schema's MinInclusive=0. Accepts the canonical id string (produced by
+ * `stripCanonicalPrefix`) and returns a string safe to embed as a value.
+ * If the string is non-numeric or positive it passes through unchanged.
+ */
+function clampNonNegativeIdString(value: string): string {
+  const parsed = Number.parseInt(value, 10);
+  if (!Number.isFinite(parsed)) return value;
+  if (parsed < 0) {
+    warnClamp("w:numId/w:abstractNumId", parsed, 0);
+    return "0";
+  }
+  return value;
+}
+
+let warnedClamps = 0;
+const WARNED_CLAMPS_MAX = 20;
+function warnClamp(attr: string, from: number, to: number): void {
+  if (warnedClamps >= WARNED_CLAMPS_MAX) return;
+  warnedClamps += 1;
+  // Only warn outside of production builds. The test runner shows these
+  // via console.warn automatically; in production this is a silent no-op
+  // so the Buffer cost is zero.
+  const proc = (globalThis as unknown as {
+    process?: { env?: Record<string, string | undefined> };
+  }).process;
+  if (proc?.env?.NODE_ENV !== "production") {
+    console.warn(
+      `[numbering] clamped ${attr} ${from} -> ${to} at MinInclusive (A.6 guard)`,
+    );
+  }
+}
+
 function compareSerializedIds(left: string, right: string): number {
   return stripKnownPrefix(left).localeCompare(stripKnownPrefix(right), "en", { numeric: true });
 }

package/src/io/export/serialize-tables.ts

@@ -10,13 +10,14 @@ import type {
   ParsedTableRow,
   ParsedTableWidth,
 } from "../ooxml/parse-tables.ts";
+import { twip } from "./twip.ts";
 
 export function serializeTable(table: ParsedTable): string {
   const propertiesXml = table.propertiesXml ?? buildTablePropertiesXml(table);
   const gridXml =
     table.gridColumns.length > 0
       ? `<w:tblGrid>${table.gridColumns
-          .map((width) => `<w:gridCol w:w="${width}"/>`)
+          .map((width) => `<w:gridCol w:w="${twip(width)}"/>`)
           .join("")}</w:tblGrid>`
       : "";
   const rowsXml = table.rows.map(serializeRow).join("");
@@ -46,6 +47,28 @@ function buildTablePropertiesXml(table: ParsedTable): string {
   if (table.alignment) {
     children.push(`<w:jc w:val="${table.alignment}"/>`);
   }
+  if (table.indent) {
+    children.push(`<w:tblInd w:w="${table.indent.value}" w:type="${table.indent.type}"/>`);
+  }
+  if (table.layoutMode) {
+    children.push(`<w:tblLayout w:type="${table.layoutMode}"/>`);
+  }
+  if (table.cellSpacing) {
+    children.push(`<w:tblCellSpacing w:w="${table.cellSpacing.value}" w:type="${table.cellSpacing.type}"/>`);
+  }
+  if (table.bidiVisual !== undefined) {
+    children.push(table.bidiVisual ? `<w:bidiVisual/>` : `<w:bidiVisual w:val="0"/>`);
+  }
+  if (table.caption !== undefined) {
+    children.push(`<w:tblCaption w:val="${escapeAttribute(table.caption)}"/>`);
+  }
+  if (table.description !== undefined) {
+    children.push(`<w:tblDescription w:val="${escapeAttribute(table.description)}"/>`);
+  }
+  if (table.floating) {
+    const floatingXml = serializeTableFloating(table.floating);
+    if (floatingXml) children.push(floatingXml);
+  }
   if (table.borders) {
     const bordersXml = serializeTableBorders(table.borders);
     if (bordersXml) children.push(`<w:tblBorders>${bordersXml}</w:tblBorders>`);
@@ -61,15 +84,43 @@ function buildTablePropertiesXml(table: ParsedTable): string {
   return children.length > 0 ? `<w:tblPr>${children.join("")}</w:tblPr>` : "";
 }
 
+function serializeTableFloating(floating: NonNullable<ParsedTable["floating"]>): string {
+  const attrs: string[] = [];
+  if (floating.horizontalAnchor) attrs.push(`w:horzAnchor="${floating.horizontalAnchor}"`);
+  if (floating.verticalAnchor) attrs.push(`w:vertAnchor="${floating.verticalAnchor}"`);
+  if (floating.horizontalAlign) attrs.push(`w:tblpXSpec="${floating.horizontalAlign}"`);
+  if (floating.horizontalOffset !== undefined) attrs.push(`w:tblpX="${floating.horizontalOffset}"`);
+  if (floating.verticalAlign) attrs.push(`w:tblpYSpec="${floating.verticalAlign}"`);
+  if (floating.verticalOffset !== undefined) attrs.push(`w:tblpY="${floating.verticalOffset}"`);
+  if (floating.leftFromText !== undefined) attrs.push(`w:leftFromText="${floating.leftFromText}"`);
+  if (floating.rightFromText !== undefined) attrs.push(`w:rightFromText="${floating.rightFromText}"`);
+  if (floating.topFromText !== undefined) attrs.push(`w:topFromText="${floating.topFromText}"`);
+  if (floating.bottomFromText !== undefined) attrs.push(`w:bottomFromText="${floating.bottomFromText}"`);
+  const tblpPr = attrs.length > 0 ? `<w:tblpPr ${attrs.join(" ")}/>` : "";
+  const overlap = floating.overlap !== undefined
+    ? `<w:tblOverlap w:val="${floating.overlap ? "overlap" : "never"}"/>`
+    : "";
+  return `${tblpPr}${overlap}`;
+}
+
 function buildRowPropertiesXml(row: ParsedTableRow): string {
   const children: string[] = [];
+  if (row.cnfStyle) {
+    children.push(`<w:cnfStyle w:val="${escapeAttribute(row.cnfStyle)}"/>`);
+  }
+  if (row.cantSplit !== undefined) {
+    children.push(row.cantSplit ? `<w:cantSplit/>` : `<w:cantSplit w:val="0"/>`);
+  }
   if (row.height !== undefined) {
     const hRuleAttr = row.heightRule ? ` w:hRule="${row.heightRule}"` : "";
-    children.push(`<w:trHeight w:val="${row.height}"${hRuleAttr}/>`);
+    children.push(`<w:trHeight w:val="${twip(row.height)}"${hRuleAttr}/>`);
   }
   if (row.isHeader) {
     children.push(`<w:tblHeader/>`);
   }
+  if (row.horizontalAlignment) {
+    children.push(`<w:jc w:val="${row.horizontalAlignment}"/>`);
+  }
   return children.length > 0 ? `<w:trPr>${children.join("")}</w:trPr>` : "";
 }
 
@@ -79,11 +130,14 @@ function ensureCellProperties(cell: ParsedTableCell): string {
   }
 
   const children: string[] = [];
+  if (cell.cnfStyle) {
+    children.push(`<w:cnfStyle w:val="${escapeAttribute(cell.cnfStyle)}"/>`);
+  }
   if (cell.width) {
     children.push(serializeWidth("tcW", cell.width));
   }
   if (cell.gridSpan && cell.gridSpan > 1) {
-    children.push(`<w:gridSpan w:val="${cell.gridSpan}"/>`);
+    children.push(`<w:gridSpan w:val="${twip(cell.gridSpan)}"/>`);
   }
   if (cell.verticalMerge) {
     children.push(
@@ -99,6 +153,19 @@ function ensureCellProperties(cell: ParsedTableCell): string {
   if (cell.shading) {
     children.push(serializeCellShading(cell.shading));
   }
+  if (cell.margins) {
+    const marginsXml = serializeTableCellMargins(cell.margins);
+    if (marginsXml) children.push(`<w:tcMar>${marginsXml}</w:tcMar>`);
+  }
+  if (cell.noWrap !== undefined) {
+    children.push(cell.noWrap ? `<w:noWrap/>` : `<w:noWrap w:val="0"/>`);
+  }
+  if (cell.fitText !== undefined) {
+    children.push(cell.fitText ? `<w:tcFitText/>` : `<w:tcFitText w:val="0"/>`);
+  }
+  if (cell.textDirection) {
+    children.push(`<w:textDirection w:val="${cell.textDirection}"/>`);
+  }
   if (cell.verticalAlign) {
     children.push(`<w:vAlign w:val="${cell.verticalAlign}"/>`);
   }
@@ -107,14 +174,14 @@ function ensureCellProperties(cell: ParsedTableCell): string {
 }
 
 function serializeWidth(element: string, width: ParsedTableWidth): string {
-  return `<w:${element} w:w="${width.value}" w:type="${width.type}"/>`;
+  return `<w:${element} w:w="${twip(width.value)}" w:type="${width.type}"/>`;
 }
 
 function serializeBorderSpec(element: string, spec: ParsedBorderSpec): string {
   const attrs: string[] = [];
   if (spec.value) attrs.push(`w:val="${spec.value}"`);
-  if (spec.size !== undefined) attrs.push(`w:sz="${spec.size}"`);
-  if (spec.space !== undefined) attrs.push(`w:space="${spec.space}"`);
+  if (spec.size !== undefined) attrs.push(`w:sz="${twip(spec.size)}"`);
+  if (spec.space !== undefined) attrs.push(`w:space="${twip(spec.space)}"`);
   if (spec.color) attrs.push(`w:color="${spec.color}"`);
   const attrsStr = attrs.length > 0 ? ` ${attrs.join(" ")}` : "";
   return `<w:${element}${attrsStr}/>`;
@@ -149,7 +216,8 @@ function serializeTableLook(tblLook: ParsedTableLook): string {
   ] as const) {
     const value = tblLook[key];
     if (value !== undefined) {
-      attrs.push(`${attr}="${value ? "1" : "0"}"`);
+      // ST_OnOff (A.3): emit "true"/"false", never "1"/"0".
+      attrs.push(`${attr}="${value ? "true" : "false"}"`);
     }
   }
   return attrs.length > 0 ? `<w:tblLook ${attrs.join(" ")}/>` : "";
@@ -166,9 +234,17 @@ function serializeCellShading(shading: ParsedCellShading): string {
 
 function serializeTableCellMargins(margins: ParsedCellMargins): string {
   const parts: string[] = [];
-  if (margins.top !== undefined) parts.push(`<w:top w:w="${margins.top}" w:type="dxa"/>`);
-  if (margins.left !== undefined) parts.push(`<w:left w:w="${margins.left}" w:type="dxa"/>`);
-  if (margins.bottom !== undefined) parts.push(`<w:bottom w:w="${margins.bottom}" w:type="dxa"/>`);
-  if (margins.right !== undefined) parts.push(`<w:right w:w="${margins.right}" w:type="dxa"/>`);
+  if (margins.top !== undefined) parts.push(`<w:top w:w="${twip(margins.top)}" w:type="dxa"/>`);
+  if (margins.left !== undefined) parts.push(`<w:left w:w="${twip(margins.left)}" w:type="dxa"/>`);
+  if (margins.bottom !== undefined) parts.push(`<w:bottom w:w="${twip(margins.bottom)}" w:type="dxa"/>`);
+  if (margins.right !== undefined) parts.push(`<w:right w:w="${twip(margins.right)}" w:type="dxa"/>`);
   return parts.join("");
 }
+
+function escapeAttribute(value: string): string {
+  return value
+    .replace(/&/gu, "&amp;")
+    .replace(/"/gu, "&quot;")
+    .replace(/</gu, "&lt;")
+    .replace(/>/gu, "&gt;");
+}