@stll/folio-core 0.20.0 → 0.22.0

package/dist/docx/server/build.js

@@ -0,0 +1,265 @@
+import { TaggedError } from "better-result";
+//#region src/docx/server/build.ts
+/**
+* Headless document builders.
+*
+* Thin constructors for the `@stll/docx-core` model so a server can assemble
+* a report in code (`createEmptyDocument` → push blocks → `createDocx`)
+* without hand-writing model literals. They build model values only; the
+* serializer owns the OOXML.
+*/
+/** Character style applied to hyperlink text; present in the bundled style sets. */
+const HYPERLINK_STYLE_ID = "Hyperlink";
+/** Character style applied to the endnote reference mark. */
+const ENDNOTE_REFERENCE_STYLE_ID = "EndnoteReference";
+/** Paragraph style applied to endnote body paragraphs. */
+const ENDNOTE_TEXT_STYLE_ID = "EndnoteText";
+/** Table style used by `table()`; present in the bundled style sets. */
+const TABLE_STYLE_ID = "TableGrid";
+/** `w:tblW w:type="pct"` is in fiftieths of a percent: 5000 = 100%. */
+const FULL_WIDTH_PCT = 5e3;
+const HEADING_LEVELS = [
+	1,
+	2,
+	3,
+	4,
+	5,
+	6
+];
+/** Outline levels a `TOC \o` switch may name (ECMA-376 `w:outlineLvl` 0-8). */
+const TOC_LEVEL_MIN = 1;
+const TOC_LEVEL_MAX = 9;
+/**
+* A builder received a value outside the model's domain (a zero `gridSpan`,
+* a negative column width, a reversed TOC range). Thrown at the boundary so
+* the invalid value never reaches the serializer.
+*/
+var InvalidFolioReportBuilderOptionsError = class extends TaggedError("InvalidFolioReportBuilderOptionsError")() {};
+const assertPositiveInteger = (value, path) => {
+	if (!Number.isInteger(value) || value < 1) throw new InvalidFolioReportBuilderOptionsError({
+		message: `${path} must be a positive integer, got ${String(value)}`,
+		path
+	});
+};
+const assertHeadingLevel = (level) => {
+	if (!HEADING_LEVELS.some((known) => known === level)) throw new InvalidFolioReportBuilderOptionsError({
+		message: `level must be one of ${HEADING_LEVELS.join(", ")}, got ${String(level)}`,
+		path: "level"
+	});
+};
+const assertTocLevels = ({ from, to }) => {
+	const inRange = (value) => Number.isInteger(value) && value >= TOC_LEVEL_MIN && value <= TOC_LEVEL_MAX;
+	if (!inRange(from) || !inRange(to) || from > to) throw new InvalidFolioReportBuilderOptionsError({
+		message: `levels must satisfy ${TOC_LEVEL_MIN} <= from <= to <= ${TOC_LEVEL_MAX}, got ${String(from)}-${String(to)}`,
+		path: "levels"
+	});
+};
+const run = (text, formatting) => ({
+	type: "run",
+	...formatting ? { formatting } : {},
+	content: [{
+		type: "text",
+		text
+	}]
+});
+const paragraph = (content, formatting) => ({
+	type: "paragraph",
+	...formatting ? { formatting } : {},
+	content: typeof content === "string" ? [run(content)] : content
+});
+/** A paragraph in the `Heading<level>` style. */
+const heading = ({ text, level }) => {
+	assertHeadingLevel(level);
+	return paragraph(text, { styleId: `Heading${level}` });
+};
+/** An empty paragraph carrying a hard page break. */
+const pageBreak = () => ({
+	type: "paragraph",
+	content: [{
+		type: "run",
+		content: [{
+			type: "break",
+			breakType: "page"
+		}]
+	}]
+});
+/**
+* An external (`href`) or in-document (`anchor`, a bookmark name) link. The
+* relationship for an external link is minted when the document is written.
+*/
+const hyperlink = ({ text, formatting, tooltip, href, anchor }) => ({
+	type: "hyperlink",
+	...href !== void 0 ? { href } : { anchor },
+	...tooltip !== void 0 ? { tooltip } : {},
+	children: [run(text, {
+		styleId: HYPERLINK_STYLE_ID,
+		...formatting
+	})]
+});
+let nextBookmarkId = 0;
+/** `content` wrapped in a named bookmark, the target of `hyperlink({ anchor })`. */
+const bookmark = ({ name, content, id }) => {
+	const bookmarkId = id ?? nextBookmarkId++;
+	const start = {
+		type: "bookmarkStart",
+		id: bookmarkId,
+		name
+	};
+	const end = {
+		type: "bookmarkEnd",
+		id: bookmarkId
+	};
+	return [
+		start,
+		...content,
+		end
+	];
+};
+const cellWidth = (columnWidths, gridIndex, gridSpan) => {
+	if (!columnWidths) return;
+	let width = 0;
+	for (let column = gridIndex; column < gridIndex + gridSpan; column++) {
+		const columnWidth = columnWidths.at(column);
+		if (columnWidth === void 0) return;
+		width += columnWidth;
+	}
+	return width;
+};
+const buildCell = ({ spec, columnWidths, gridIndex, shading, textFormatting }) => {
+	const resolved = typeof spec === "string" ? {
+		content: [paragraph([run(spec, textFormatting)])],
+		shading
+	} : {
+		...spec,
+		shading: spec.shading ?? shading
+	};
+	const gridSpan = resolved.gridSpan ?? 1;
+	assertPositiveInteger(gridSpan, "gridSpan");
+	const width = cellWidth(columnWidths, gridIndex, gridSpan);
+	const formatting = {
+		...width !== void 0 ? { width: {
+			type: "dxa",
+			value: width
+		} } : {},
+		...resolved.shading ? { shading: resolved.shading } : {},
+		...resolved.gridSpan !== void 0 ? { gridSpan: resolved.gridSpan } : {},
+		...resolved.vMerge !== void 0 ? { vMerge: resolved.vMerge } : {}
+	};
+	return {
+		type: "tableCell",
+		...Object.keys(formatting).length > 0 ? { formatting } : {},
+		content: resolved.content.length > 0 ? resolved.content : [paragraph([])]
+	};
+};
+const buildRow = ({ cells, columnWidths, shading, textFormatting, header }) => {
+	const built = [];
+	let gridIndex = 0;
+	for (const spec of cells) {
+		const cell = buildCell({
+			spec,
+			columnWidths,
+			gridIndex,
+			shading,
+			textFormatting
+		});
+		built.push(cell);
+		gridIndex += cell.formatting?.gridSpan ?? 1;
+	}
+	return {
+		type: "tableRow",
+		...header ? { formatting: {
+			header: true,
+			cantSplit: true
+		} } : {},
+		cells: built
+	};
+};
+/**
+* A full-width grid table in the `TableGrid` style. A string cell becomes one
+* plain paragraph; an object cell supplies its own paragraphs plus optional
+* shading and horizontal (`gridSpan`) or vertical (`vMerge`) merge.
+*/
+const table = ({ header, rows, columnWidths, headerShading, repeatHeader = true }) => {
+	columnWidths?.forEach((width, index) => assertPositiveInteger(width, `columnWidths[${index}]`));
+	const builtRows = [];
+	if (header) builtRows.push(buildRow({
+		cells: header,
+		columnWidths,
+		shading: headerShading,
+		textFormatting: { bold: true },
+		header: repeatHeader
+	}));
+	for (const cells of rows) builtRows.push(buildRow({
+		cells,
+		columnWidths,
+		shading: void 0,
+		textFormatting: void 0,
+		header: false
+	}));
+	return {
+		type: "table",
+		formatting: {
+			styleId: TABLE_STYLE_ID,
+			width: {
+				type: "pct",
+				value: FULL_WIDTH_PCT
+			},
+			layout: columnWidths ? "fixed" : "autofit"
+		},
+		...columnWidths ? { columnWidths } : {},
+		rows: builtRows
+	};
+};
+/**
+* Register an endnote on `doc` and return the reference run to place in body
+* text. Allocates the next free endnote id (Word reserves 0 and -1 for the
+* separator notes) and pushes the note into `doc.package.endnotes`.
+*/
+const endnote = (doc, content) => {
+	const endnotes = doc.package.endnotes ?? [];
+	doc.package.endnotes = endnotes;
+	const id = Math.max(0, ...endnotes.map((note) => note.id)) + 1;
+	const note = {
+		type: "endnote",
+		id,
+		content: typeof content === "string" ? [paragraph(content, { styleId: ENDNOTE_TEXT_STYLE_ID })] : content
+	};
+	endnotes.push(note);
+	return {
+		type: "run",
+		formatting: { styleId: ENDNOTE_REFERENCE_STYLE_ID },
+		content: [{
+			type: "endnoteRef",
+			id
+		}]
+	};
+};
+const DEFAULT_TOC_LEVELS = {
+	from: 1,
+	to: 3
+};
+const DEFAULT_TOC_PLACEHOLDER = "Update the field to build the table of contents.";
+/**
+* A paragraph holding a dirty `TOC` field, so the consumer recomputes the
+* table on open. Set `package.settings.updateFields` as well to have Word
+* recompute without prompting for each field.
+*/
+const createTableOfContentsField = ({ levels = DEFAULT_TOC_LEVELS, hyperlinks = true, placeholderText = DEFAULT_TOC_PLACEHOLDER } = {}) => {
+	assertTocLevels(levels);
+	const switches = [`\\o "${levels.from}-${levels.to}"`];
+	if (hyperlinks) switches.push("\\h");
+	switches.push("\\z", "\\u");
+	return {
+		type: "paragraph",
+		content: [{
+			type: "complexField",
+			instruction: `TOC ${switches.join(" ")}`,
+			fieldType: "TOC",
+			fieldCode: [],
+			fieldResult: [run(placeholderText)],
+			dirty: true
+		}]
+	};
+};
+//#endregion
+export { HEADING_LEVELS, InvalidFolioReportBuilderOptionsError, bookmark, createTableOfContentsField, endnote, heading, hyperlink, pageBreak, paragraph, run, table };

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

@@ -0,0 +1,62 @@
+import { document_d_exports } from "../../types/document.js";
+//#region src/docx/server/createBilingualDocument.d.ts
+type BilingualRowKind = "paragraph" | "heading" | "listItem";
+/** One translatable unit: a source paragraph and its right-column copy. */
+type BilingualParagraphRef = {
+  /** `paraId` of the untouched source paragraph (left column). */
+  sourceParaId: string | undefined;
+  /** `paraId` minted for the right-column copy; stable across re-runs. */
+  targetParaId: string;
+  /** Plain text of the source paragraph. */
+  sourceText: string;
+};
+type BilingualRow = ({
+  kind: BilingualRowKind;
+  /** Equals `targetParaId`; the handle callers use to address the row. */
+  rowId: string;
+} & BilingualParagraphRef) | {
+  kind: "table";
+  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[];
+};
+type BilingualTableParagraphRef = {
+  paraId: string | undefined;
+  sourceText: string;
+};
+type BilingualBorders = "none" | "grid";
+type CreateBilingualDocumentOptions = {
+  /**
+   * Suffix for cloned style ids and names (for example `"en"` turns
+   * `Heading1` into `Heading1-en`). Must be a non-empty token of letters,
+   * digits, or `-`.
+   */
+  targetStyleSuffix: string;
+  /** Table borders; legal practice is usually `"none"`. Default `"none"`. */
+  borders?: BilingualBorders;
+};
+type CreateBilingualDocumentResult = {
+  document: document_d_exports.Document;
+  rows: BilingualRow[];
+  /** Non-fatal fidelity notes (for example an unresolvable numbering style link). */
+  warnings: string[];
+};
+declare const InvalidBilingualDocumentOptionsError_base: import("better-result").TaggedErrorClass<"InvalidBilingualDocumentOptionsError", {
+  message: string;
+  option: "targetStyleSuffix";
+}>;
+declare class InvalidBilingualDocumentOptionsError extends InvalidBilingualDocumentOptionsError_base {}
+declare function createBilingualDocument(source: document_d_exports.Document, options: CreateBilingualDocumentOptions): CreateBilingualDocumentResult;
+/**
+ * Re-derive the row manifest from a document produced by
+ * {@link createBilingualDocument}. Detection is structural: a top-level table
+ * whose rows are all either a left | right pair of single-paragraph cells or
+ * one cell spanning both columns. Rows are returned in document order; the
+ * right paragraph's `paraId` is the row handle, as at creation.
+ */
+declare function readBilingualDocument(document: document_d_exports.Document): BilingualRow[];
+//#endregion
+export { BilingualBorders, BilingualParagraphRef, BilingualRow, BilingualRowKind, BilingualTableParagraphRef, CreateBilingualDocumentOptions, CreateBilingualDocumentResult, InvalidBilingualDocumentOptionsError, createBilingualDocument, readBilingualDocument };