@stll/folio-core 0.29.0 → 0.31.0

package/dist/docx/serializer/runSerializer.js

@@ -1,5 +1,6 @@
 import { HIGHLIGHT_COLOR_VALUES } from "../../types/documentEnumValues.js";
 import { isValidHexColor } from "../../utils/colorResolver.js";
+import { roundHorizontalScalePercentForSerialization } from "../../utils/horizontalScale.js";
 import { THEME_COLOR_TO_DRAWING_SCHEME } from "../drawingUtils.js";
 import { requiresXmlSpacePreserve } from "../textWhitespace.js";
 import { serializeParagraph } from "./paragraphSerializer.js";
@@ -127,7 +128,8 @@ function serializeTextFormatting(formatting) {
 	const colorXml = serializeColorElement(formatting.color);
 	if (colorXml) parts.push(colorXml);
 	if (formatting.spacing !== void 0) parts.push(`<w:spacing w:val="${intAttr(formatting.spacing)}"/>`);
-	if (formatting.scale !== void 0) parts.push(`<w:w w:val="${intAttr(formatting.scale)}"/>`);
+	const horizontalScale = roundHorizontalScalePercentForSerialization(formatting.scale);
+	if (horizontalScale !== void 0) parts.push(`<w:w w:val="${intAttr(horizontalScale)}"/>`);
 	if (formatting.kerning !== void 0) parts.push(`<w:kern w:val="${intAttr(formatting.kerning)}"/>`);
 	if (formatting.position !== void 0) parts.push(`<w:position w:val="${intAttr(formatting.position)}"/>`);
 	if (formatting.fontSize !== void 0) parts.push(`<w:sz w:val="${intAttr(formatting.fontSize)}"/>`);
@@ -448,6 +450,16 @@ function serializeDrawingContent(content) {
 function serializeShapeTextBody(blocks) {
 	return blocks.map((block) => block.type === "paragraph" ? serializeParagraph(block) : serializeTable(block, serializeParagraph)).join("");
 }
+const serializeTextBodyAnchor = (anchor) => {
+	switch (anchor) {
+		case "top": return "t";
+		case "middle": return "ctr";
+		case "bottom": return "b";
+		case "distributed": return "dist";
+		case "justified": return "just";
+		default: return anchor;
+	}
+};
 function serializeGeometryAdjustments(shape) {
 	if (!shape.geometryAdjustments || shape.geometryAdjustments.length === 0) return "<a:avLst/>";
 	return `<a:avLst>${shape.geometryAdjustments.map(({ name, formula }) => `<a:gd name="${escapeXml(name)}" fmla="${escapeXml(formula)}"/>`).join("")}</a:avLst>`;
@@ -484,7 +496,7 @@ function serializeShapeContent(content) {
 		const tb = shape.textBody;
 		const bpAttrs = ["rot=\"0\"", "vert=\"horz\""];
 		if (tb.textWrap) bpAttrs.push(`wrap="${tb.textWrap}"`);
-		if (tb.anchor) bpAttrs.push(`anchor="${tb.anchor === "middle" ? "ctr" : tb.anchor}"`);
+		if (tb.anchor) bpAttrs.push(`anchor="${serializeTextBodyAnchor(tb.anchor)}"`);
 		if (tb.anchorCenter) bpAttrs.push("anchorCtr=\"1\"");
 		if (tb.margins) {
 			if (tb.margins.left != null) bpAttrs.push(`lIns="${intAttr(tb.margins.left)}"`);

package/dist/docx/server/createBilingualDocument.d.ts

@@ -16,18 +16,28 @@ type BilingualRow = ({
   rowId: string;
 } & BilingualParagraphRef) | {
   kind: "table";
+  layout: "inline";
   rowId: string;
   /**
    * Every paragraph inside the table, in document order. The table is not
    * copied, so these are the paragraphs to translate in place.
    */
   paragraphs: BilingualTableParagraphRef[];
+} | {
+  kind: "table";
+  layout: "stacked";
+  /** Equals the first target paragraph id. */
+  rowId: string;
+  /** Source/target paragraph pairs in table document order. */
+  paragraphs: BilingualParagraphRef[];
 };
 type BilingualTableParagraphRef = {
   paraId: string | undefined;
   sourceText: string;
 };
 type BilingualBorders = "none" | "grid";
+declare const BILINGUAL_TABLE_LAYOUTS: readonly ["inline", "stacked"];
+type BilingualTableLayout = (typeof BILINGUAL_TABLE_LAYOUTS)[number];
 type CreateBilingualDocumentOptions = {
   /**
    * Suffix for cloned style ids and names (for example `"en"` turns
@@ -37,6 +47,13 @@ type CreateBilingualDocumentOptions = {
   targetStyleSuffix: string;
   /** Table borders; legal practice is usually `"none"`. Default `"none"`. */
   borders?: BilingualBorders;
+  /**
+   * Layout for source tables. `"inline"` keeps one full-width table whose
+   * paragraphs are translated in place. `"stacked"` keeps the source table
+   * and adds an independently addressable target copy below it. Default
+   * `"inline"`.
+   */
+  tableLayout?: BilingualTableLayout;
   /**
    * Paragraph handles exposed by Folio's canonical AI-edit snapshot for the
    * source DOCX. Only these paragraphs may become translation rows.
@@ -52,7 +69,7 @@ type CreateBilingualDocumentResult = {
 declare const InvalidBilingualDocumentOptionsError_base: import("better-result").TaggedErrorClass<"InvalidBilingualDocumentOptionsError">;
 declare class InvalidBilingualDocumentOptionsError extends InvalidBilingualDocumentOptionsError_base<{
   message: string;
-  option: "targetStyleSuffix";
+  option: "tableLayout" | "targetStyleSuffix";
 }> {}
 declare function createBilingualDocument(source: document_d_exports.Document, options: CreateBilingualDocumentOptions): CreateBilingualDocumentResult;
 /**
@@ -60,8 +77,8 @@ declare function createBilingualDocument(source: document_d_exports.Document, op
  * {@link createBilingualDocument}. A dedicated table-style discriminator keeps
  * ordinary two-column source tables from being mistaken for bilingual output;
  * the expected row structure is validated as a second check. Rows are returned
- * in document order; the right paragraph's `paraId` is the row handle.
+ * in document order.
  */
 declare function readBilingualDocument(document: document_d_exports.Document, editableParagraphIds: ReadonlySet<string>): BilingualRow[];
 //#endregion
-export { BilingualBorders, BilingualParagraphRef, BilingualRow, BilingualRowKind, BilingualTableParagraphRef, CreateBilingualDocumentOptions, CreateBilingualDocumentResult, InvalidBilingualDocumentOptionsError, createBilingualDocument, readBilingualDocument };
+export { BILINGUAL_TABLE_LAYOUTS, BilingualBorders, BilingualParagraphRef, BilingualRow, BilingualRowKind, BilingualTableLayout, BilingualTableParagraphRef, CreateBilingualDocumentOptions, CreateBilingualDocumentResult, InvalidBilingualDocumentOptionsError, createBilingualDocument, readBilingualDocument };

package/dist/docx/server/createBilingualDocument.js

@@ -17,13 +17,15 @@ import { TaggedError } from "better-result";
 *
 * Section breaks cannot live inside a table cell, so the body is split at
 * paragraphs carrying `sectionProperties`: each section becomes its own table
-* and the break paragraph stays between the tables. A source table (parties,
-* signature block) is kept once, in a row spanning both columns: it is signed
-* and read once, and its labels are translated inline rather than duplicated.
+* and the break paragraph stays between the tables. Source tables (parties,
+* signature blocks) can either span both columns for inline translation or be
+* followed by a full-width target copy, depending on `tableLayout`.
 * Structural-only paragraphs are also kept once between tables; they have no
 * independently editable text for a translation row to address.
 */
+const BILINGUAL_TABLE_LAYOUTS = ["inline", "stacked"];
 const STYLE_SUFFIX_PATTERN = /^[A-Za-z0-9-]+$/u;
+const DEFAULT_TABLE_LAYOUT = BILINGUAL_TABLE_LAYOUTS[0];
 var InvalidBilingualDocumentOptionsError = class extends TaggedError("InvalidBilingualDocumentOptionsError") {};
 var UneditableBilingualManifestError = class extends TaggedError("UneditableBilingualManifestError") {};
 const FULL_WIDTH_PCT = 5e3;
@@ -56,12 +58,18 @@ const TABLE_BORDERS = {
 		insideV: GRID_BORDER
 	}
 };
+const isBilingualTableLayout = (value) => typeof value === "string" && BILINGUAL_TABLE_LAYOUTS.some((layout) => layout === value);
 function createBilingualDocument(source, options) {
 	if (!STYLE_SUFFIX_PATTERN.test(options.targetStyleSuffix)) throw new InvalidBilingualDocumentOptionsError({
 		message: `targetStyleSuffix must match ${STYLE_SUFFIX_PATTERN}; received ${JSON.stringify(options.targetStyleSuffix)}`,
 		option: "targetStyleSuffix"
 	});
+	if (options.tableLayout !== void 0 && !isBilingualTableLayout(options.tableLayout)) throw new InvalidBilingualDocumentOptionsError({
+		message: `tableLayout must be one of ${BILINGUAL_TABLE_LAYOUTS.join(", ")}; received ${JSON.stringify(options.tableLayout)}`,
+		option: "tableLayout"
+	});
 	const borders = options.borders ?? "none";
+	const tableLayout = options.tableLayout ?? DEFAULT_TABLE_LAYOUT;
 	const warnings = [];
 	const styles = source.package.styles;
 	const numbering = source.package.numbering;
@@ -128,12 +136,36 @@ function createBilingualDocument(source, options) {
 			content.push(block);
 			continue;
 		}
-		rows.push({
-			kind: "table",
-			rowId: paragraphs.at(0)?.paraId ?? tableRowHandle(rows.length),
-			paragraphs
-		});
-		sectionRows.push(buildSpanningRow(block));
+		if (tableLayout === "inline") {
+			rows.push({
+				kind: "table",
+				layout: "inline",
+				rowId: paragraphs.at(0)?.paraId ?? tableRowHandle(rows.length),
+				paragraphs
+			});
+			sectionRows.push(buildInlineTableRow(block));
+			continue;
+		}
+		if (tableLayout === "stacked") {
+			const target = cloneTableForTarget({
+				table: block,
+				editableParagraphIds: options.editableParagraphIds,
+				paraIds,
+				styleCloner,
+				cloner
+			});
+			rows.push({
+				kind: "table",
+				layout: "stacked",
+				rowId: target.paragraphs.at(0)?.targetParaId ?? tableRowHandle(rows.length),
+				paragraphs: target.paragraphs
+			});
+			sectionRows.push(buildStackedTableRow({
+				source: block,
+				target: target.table
+			}));
+			continue;
+		}
 	}
 	flushSection();
 	return {
@@ -367,6 +399,33 @@ const collectTableParagraphs = (table) => {
 	else out.push(...collectTableParagraphs(item));
 	return out;
 };
+const cloneTableForTarget = ({ table, editableParagraphIds, paraIds, styleCloner, cloner }) => {
+	const paragraphs = [];
+	const cloneTable = (source) => ({
+		...structuredClone(source),
+		rows: source.rows.map((row) => ({
+			...structuredClone(row),
+			cells: row.cells.map((cell) => ({
+				...structuredClone(cell),
+				content: cell.content.map((item) => {
+					if (item.type === "table") return cloneTable(item);
+					const targetParaId = paraIds.mint(item.paraId);
+					const copy = cloneParagraphForTarget(item, targetParaId, styleCloner, cloner);
+					if (item.paraId !== void 0 && editableParagraphIds.has(item.paraId)) paragraphs.push({
+						sourceParaId: item.paraId,
+						targetParaId,
+						sourceText: getParagraphText(item)
+					});
+					return copy;
+				})
+			}))
+		}))
+	});
+	return {
+		table: cloneTable(table),
+		paragraphs
+	};
+};
 const buildRow = (left, right, styleById, textWidth) => {
 	const columnWidth = Math.floor(textWidth / 2);
 	const geometry = resolveHorizontalParagraphGeometry(left, styleById);
@@ -411,16 +470,21 @@ const projectParagraphIntoColumn = (paragraph, geometry, sourceWidth, columnWidt
 	const maxSideIndent = Math.max(0, columnWidth - MIN_COLUMN_TEXT_WIDTH_TWIPS);
 	let indentLeft = projectSideIndent(geometry.indentLeft, scale, maxSideIndent);
 	let indentRight = projectSideIndent(geometry.indentRight, scale, maxSideIndent);
-	if (indentLeft + indentRight - maxSideIndent > 0) {
-		const total = indentLeft + indentRight;
-		indentLeft = Math.round(indentLeft / total * maxSideIndent);
+	const indentFirstLine = geometry.indentFirstLine === void 0 ? void 0 : Math.max(-maxSideIndent, Math.round(geometry.indentFirstLine * scale));
+	const minimumLeftIndent = Math.min(maxSideIndent, Math.max(0, -(indentFirstLine ?? 0)));
+	indentLeft = Math.max(indentLeft, minimumLeftIndent);
+	const flexibleLeft = indentLeft - minimumLeftIndent;
+	const flexibleTotal = flexibleLeft + indentRight;
+	const flexibleMaximum = maxSideIndent - minimumLeftIndent;
+	if (flexibleTotal > flexibleMaximum) {
+		indentLeft = minimumLeftIndent + Math.round(flexibleLeft / flexibleTotal * flexibleMaximum);
 		indentRight = maxSideIndent - indentLeft;
 	}
 	const formatting = {
 		...paragraph.formatting,
-		...geometry.indentLeft !== void 0 && { indentLeft },
+		...(geometry.indentLeft !== void 0 || minimumLeftIndent > 0) && { indentLeft },
 		...geometry.indentRight !== void 0 && { indentRight },
-		...geometry.indentFirstLine !== void 0 && { indentFirstLine: Math.round(geometry.indentFirstLine * scale) },
+		...indentFirstLine !== void 0 && { indentFirstLine },
 		...geometry.hangingIndent !== void 0 && { hangingIndent: geometry.hangingIndent },
 		...geometry.tabs !== void 0 && { tabs: geometry.tabs.map((tab) => ({
 			...tab,
@@ -445,7 +509,7 @@ const buildCell = (paragraph) => ({
 	content: [paragraph]
 });
 /** A source table kept once, across both columns. */
-const buildSpanningRow = (table) => ({
+const buildInlineTableRow = (table) => ({
 	type: "tableRow",
 	formatting: { cantSplit: true },
 	cells: [{
@@ -464,6 +528,33 @@ const buildSpanningRow = (table) => ({
 		}]
 	}]
 });
+const buildStackedTableRow = ({ source, target }) => ({
+	type: "tableRow",
+	formatting: { cantSplit: false },
+	cells: [{
+		type: "tableCell",
+		formatting: {
+			width: {
+				value: FULL_WIDTH_PCT,
+				type: "pct"
+			},
+			gridSpan: 2,
+			verticalAlign: "top"
+		},
+		content: [
+			source,
+			{
+				type: "paragraph",
+				content: []
+			},
+			target,
+			{
+				type: "paragraph",
+				content: []
+			}
+		]
+	}]
+});
 const buildTable = (rows, borders, textWidth) => ({
 	type: "table",
 	formatting: {
@@ -537,7 +628,7 @@ const createParaIdMinter = (taken) => {
 * {@link createBilingualDocument}. A dedicated table-style discriminator keeps
 * ordinary two-column source tables from being mistaken for bilingual output;
 * the expected row structure is validated as a second check. Rows are returned
-* in document order; the right paragraph's `paraId` is the row handle.
+* in document order.
 */
 function readBilingualDocument(document, editableParagraphIds) {
 	const styleById = new Map((document.package.styles?.styles ?? []).map((style) => [style.styleId, style]));
@@ -549,12 +640,54 @@ function readBilingualDocument(document, editableParagraphIds) {
 			const [left, right] = row.cells;
 			if (!left) continue;
 			if (!right) {
-				const paragraphs = left.content.filter((item) => item.type === "table").flatMap(collectTableParagraphs).filter((paragraph) => paragraph.paraId !== void 0 && editableParagraphIds.has(paragraph.paraId)).map((paragraph) => ({
+				const nestedTables = left.content.filter((item) => item.type === "table");
+				const sourceTable = nestedTables.at(0);
+				if (!sourceTable) {
+					missingHandleCount += 1;
+					continue;
+				}
+				if (nestedTables.length === 2) {
+					const targetTable = nestedTables.at(1);
+					if (!targetTable) continue;
+					const sourceParagraphs = collectTableParagraphs(sourceTable);
+					const targetParagraphs = collectTableParagraphs(targetTable);
+					if (sourceParagraphs.length !== targetParagraphs.length) {
+						missingHandleCount += 1;
+						continue;
+					}
+					const paragraphs = [];
+					for (const [index, source] of sourceParagraphs.entries()) {
+						if (source.paraId === void 0 || !editableParagraphIds.has(source.paraId)) continue;
+						const target = targetParagraphs.at(index);
+						if (target?.paraId === void 0 || target.paraId === source.paraId || !editableParagraphIds.has(target.paraId)) {
+							missingHandleCount += 1;
+							continue;
+						}
+						paragraphs.push({
+							sourceParaId: source.paraId,
+							targetParaId: target.paraId,
+							sourceText: getParagraphText(source)
+						});
+					}
+					rows.push({
+						kind: "table",
+						layout: "stacked",
+						rowId: paragraphs.at(0)?.targetParaId ?? tableRowHandle(rows.length),
+						paragraphs
+					});
+					continue;
+				}
+				if (nestedTables.length !== 1) {
+					missingHandleCount += 1;
+					continue;
+				}
+				const paragraphs = collectTableParagraphs(sourceTable).filter((paragraph) => paragraph.paraId !== void 0 && editableParagraphIds.has(paragraph.paraId)).map((paragraph) => ({
 					paraId: paragraph.paraId,
 					sourceText: getParagraphText(paragraph)
 				}));
 				rows.push({
 					kind: "table",
+					layout: "inline",
 					rowId: paragraphs.at(0)?.paraId ?? tableRowHandle(rows.length),
 					paragraphs
 				});
@@ -582,26 +715,24 @@ function readBilingualDocument(document, editableParagraphIds) {
 		}
 	}
 	if (missingHandleCount > 0) throw new UneditableBilingualManifestError({
-		message: "Bilingual manifest contains handles absent from the Folio AI-edit snapshot.",
+		message: "Bilingual manifest structure or handles do not match the Folio AI-edit snapshot.",
 		missingHandleCount
 	});
 	return rows;
 }
 const isBilingualTable = (table) => {
 	if (table.formatting?.styleId !== BILINGUAL_TABLE_STYLE_ID) return false;
-	let pairs = 0;
 	for (const row of table.rows) {
 		const cells = row.cells;
 		if (cells.length === 2) {
 			if (!cells.every((cell) => cell.content.length === 1 && cell.content[0]?.type === "paragraph")) return false;
-			pairs += 1;
 			continue;
 		}
 		if (cells.length === 1 && cells[0]?.formatting?.gridSpan === 2) continue;
 		return false;
 	}
-	return pairs > 0;
+	return table.rows.length > 0;
 };
 const isParagraphWithId = (value) => "type" in value && value.type === "paragraph" && "paraId" in value && typeof value.paraId === "string";
 //#endregion
-export { InvalidBilingualDocumentOptionsError, createBilingualDocument, readBilingualDocument };
+export { BILINGUAL_TABLE_LAYOUTS, InvalidBilingualDocumentOptionsError, createBilingualDocument, readBilingualDocument };

package/dist/docx/styleParser.js

@@ -1,4 +1,5 @@
 import { isValidHexColor } from "../utils/colorResolver.js";
+import { parseHorizontalScalePercent } from "../utils/horizontalScale.js";
 import { mergeParagraphFormatting } from "../utils/paragraphFormattingMerge.js";
 import { mergeStyleTextFormatting } from "../utils/textFormattingMerge.js";
 import { BorderStyleSchema, ConditionalStyleTypeSchema, EmphasisMarkSchema, FontHintSchema, FontThemeSchema, HighlightColorSchema, LineSpacingRuleSchema, ParagraphAlignmentSchema, ShadingPatternSchema, StyleTypeSchema, TabLeaderSchema, TabStopAlignmentSchema, TableCellTextDirectionSchema, TableRowHeightRuleSchema, TableWidthTypeSchema, TextEffectSchema, ThemeColorSlotSchema, UnderlineStyleSchema, narrowEnum } from "./parserEnums.js";
@@ -137,7 +138,7 @@ function parseRunProperties(rPr, theme) {
 	}
 	const w = findChild(rPr, "w", "w");
 	if (w) {
-		const val = parseNumericAttribute(w, "w", "val");
+		const val = parseHorizontalScalePercent(getAttribute(w, "w", "val"));
 		if (val !== void 0) formatting.scale = val;
 	}
 	const kern = findChild(rPr, "w", "kern");

package/dist/docx/textBoxParser.js

@@ -4,6 +4,16 @@ import { findByFullName, findChildByLocalName, findChildrenByLocalName, getAttri
 //#region src/docx/textBoxParser.ts
 /** Default text box margins in EMUs (0.1 inch) */
 const DEFAULT_MARGIN_EMU = 91440;
+const parseTextBoxVerticalAlign = (value) => {
+	switch (value) {
+		case "t": return "top";
+		case "ctr": return "middle";
+		case "b": return "bottom";
+		case "dist": return "distributed";
+		case "just": return "justified";
+		default: return;
+	}
+};
 /**
 * Parse text body properties from wps:bodyPr
 * Returns margins/insets for the text box
@@ -16,6 +26,8 @@ function parseBodyProperties(bodyPr) {
 	if (findChildByLocalName(bodyPr, "spAutoFit")) result.autoFit = "shape";
 	else if (findChildByLocalName(bodyPr, "normAutofit")) result.autoFit = "normal";
 	else if (findChildByLocalName(bodyPr, "noAutofit")) result.autoFit = "none";
+	const verticalAlign = parseTextBoxVerticalAlign(getAttribute(bodyPr, null, "anchor"));
+	if (verticalAlign) result.verticalAlign = verticalAlign;
 	const lIns = parseNumericAttribute(bodyPr, null, "lIns");
 	const rIns = parseNumericAttribute(bodyPr, null, "rIns");
 	const tIns = parseNumericAttribute(bodyPr, null, "tIns");
@@ -131,6 +143,7 @@ function parseTextBox(drawingEl) {
 	if (bodyProps.margins) textBox.margins = bodyProps.margins;
 	if (bodyProps.autoFit) textBox.autoFit = bodyProps.autoFit;
 	if (bodyProps.textWrap) textBox.textWrap = bodyProps.textWrap;
+	if (bodyProps.verticalAlign) textBox.verticalAlign = bodyProps.verticalAlign;
 	if (isAnchor) {
 		const position = parseAnchorPosition(container);
 		if (position) textBox.position = position;
@@ -174,6 +187,7 @@ function parseTextBoxFromShape(wsp, size, position, wrap) {
 	if (bodyProps.margins) textBox.margins = bodyProps.margins;
 	if (bodyProps.autoFit) textBox.autoFit = bodyProps.autoFit;
 	if (bodyProps.textWrap) textBox.textWrap = bodyProps.textWrap;
+	if (bodyProps.verticalAlign) textBox.verticalAlign = bodyProps.verticalAlign;
 	if (position) textBox.position = position;
 	if (wrap) textBox.wrap = wrap;
 	return textBox;