@stll/folio-core 0.47.7 → 0.48.0

package/dist/headless-layout.d.ts

@@ -17,9 +17,13 @@ import { Result } from "better-result";
  * names.
  */
 type DocumentPaintFeatures = DocumentFeatures;
-/** A story this entry does not paginate, named so a caller can see the hole. */
+/**
+ * A story this entry does not paginate, named so a caller can see the hole.
+ * Every story is laid out now, so `story` admits none; a story that stops
+ * being laid out widens it again, and {@link UNPAGINATED_STORIES} must name it.
+ */
 type HeadlessLayoutGap = {
-  readonly story: "endnote";
+  readonly story: never;
   readonly detail: string;
 };
 declare const HeadlessLayoutError_base: import("better-result").TaggedErrorClass<"HeadlessLayoutError">;
@@ -70,6 +74,11 @@ type HeadlessLayoutResult = {
   readonly embeddedFonts: readonly EmbeddedFont[];
   readonly unsupported: readonly HeadlessLayoutGap[];
 };
+/**
+ * Parse and paginate a package. Fails rather than defaulting when no
+ * measurement backend is installed: a layout measured by the wrong provider
+ * is wrong in a way no downstream check catches.
+ */
 declare const layoutDocxHeadless: (input: DocxInput, options?: HeadlessLayoutOptions) => Promise<Result<HeadlessLayoutResult, HeadlessLayoutError>>;
 //#endregion
 export { DocumentPaintFeatures, HeadlessLayoutError, HeadlessLayoutGap, HeadlessLayoutOptions, HeadlessLayoutResult, layoutDocxHeadless };

package/dist/headless-layout.js

@@ -6,11 +6,14 @@ import { parseDocx } from "./docx/parser.js";
 import { buildHeaderFooterFieldValues } from "./fields/resolveFieldValues.js";
 import { extractEmbeddedFonts } from "./fonts/embeddedFonts.js";
 import { buildFontAlternates } from "./fonts/fontAlternates.js";
+import { prepareEndnoteAreas, resolveEndnotePosition, spliceEndnoteAreas, trailingEndnoteIds } from "./layout-bridge/convert/endnoteLayout.js";
 import { buildFootnoteContentMap, collectEndnoteRefs, collectFootnoteRefs, computeNoteDisplayNumbers, remapNoteMarkerText } from "./layout-bridge/convert/footnoteLayout.js";
 import { convertHeaderFooterToContent } from "./layout-bridge/convert/headerFooterLayout.js";
 import { toFlowBlocks } from "./layout-bridge/convert/toFlowBlocks.js";
 import { resolveSectionHeaderFooterRefs } from "./layout-engine/headerFooterRefs.js";
 import { layoutDocument } from "./layout-engine/index.js";
+import { collectRequestedHyphenationDictionaries } from "./layout-engine/measure/hyphenationDictionaries.js";
+import { preloadHyphenationDictionaries } from "./layout-engine/measure/hyphenationPreload.js";
 import { measureBlocks } from "./layout-engine/measure/measureBlocks.js";
 import { getMeasureProvider } from "./layout-engine/measure/measureProvider.js";
 import "./layout-engine/types.js";
@@ -34,14 +37,14 @@ import { createHash } from "node:crypto";
 *
 * ## The other stories
 *
-* Headers, footers and footnotes are separate OOXML stories that the editor
-* lays out as their own ProseMirror views, but neither conversion needs a view:
-* `convertHeaderFooterToContent` and `buildFootnoteContentMap` run the same
-* `toFlowBlocks → measureBlocks` chain the body runs. This entry therefore lays
-* them out too and returns them as {@link HeadlessLayoutResult.furniture}, so
-* an export paints the pages the editor paints rather than bare bodies.
-* Endnotes remain unpaginated and say so through
-* {@link HeadlessLayoutResult.unsupported}.
+* Headers, footers and notes are separate OOXML stories that the editor
+* lays out as their own ProseMirror views, but no conversion needs a view:
+* `convertHeaderFooterToContent`, `buildFootnoteContentMap` and
+* `prepareEndnoteAreas` run the same `toFlowBlocks → measureBlocks` chain the
+* body runs. This entry therefore lays them out too: headers, footers and
+* footnotes come back as {@link HeadlessLayoutResult.furniture}, and endnotes
+* paginate with the body, so an export paints the pages the editor paints
+* rather than bare bodies.
 *
 * What this entry still does not do is push the body down for a header taller
 * than its margin: the editor's margin clearing lives in the controller, and a
@@ -67,21 +70,9 @@ var HeadlessLayoutError = class extends TaggedError("HeadlessLayoutError") {};
 * than content that vanishes without a report, and a story that starts being
 * laid out cannot keep a stale entry, because removing it narrows the union.
 *
-* Endnotes are the only one left. They are collected at the end of the
-* document rather than reserved per page, so nothing in `Layout` and nothing in
-* the painter's render options places them yet; laying them out is a
-* pagination feature, not a conversion this entry could call.
+* None is left: endnotes, the last, paginate with the body.
 */
-const UNPAGINATED_STORIES = { endnote: {
-	story: "endnote",
-	detail: "Endnotes are their own story and are not paginated with the body."
-} };
-const hasStory = (document, story) => {
-	switch (story) {
-		case "endnote": return (document.package.endnotes?.length ?? 0) > 0;
-		default: return false;
-	}
-};
+const UNPAGINATED_STORIES = {};
 const readPaintFeatures = (document) => ({
 	pageBorders: (document.package.document.sections ?? []).some((section) => Object.values(section.properties.pageBorders ?? {}).some((border) => border !== void 0)),
 	watermark: getDocumentWatermark(document) !== void 0
@@ -178,26 +169,36 @@ const NONCE_LENGTH = 12;
 /** Whether `fontTable.xml` declares any embedded face at all. */
 const declaresEmbeddedFonts = (document) => (document.package.fontTable?.fonts ?? []).some((font) => font.embedRegular !== void 0 || font.embedBold !== void 0 || font.embedItalic !== void 0 || font.embedBoldItalic !== void 0);
 /**
-* Parse and paginate a package. Fails rather than defaulting when no
-* measurement backend is installed: a layout measured by the wrong provider
-* is wrong in a way no downstream check catches.
-*/
-/**
-* Whether any text in the package needs shaping.
+* Whether `test` holds for any record in the package's content model.
 *
 * Every story a page paints, body, headers, footers and notes alike, is built
 * from the same content model, so one walk over the package answers for all of
-* them. The answer decides whether the shaper is fetched at all: a document in
-* Latin, Cyrillic or Greek must not pay for an artifact it has no use for.
+* them. Headers and footers are keyed by relationship id in `Map`s, which
+* `Object.entries` sees as empty, so the walk descends into map values too.
 */
-const packageNeedsShaping = (value) => {
-	if (Array.isArray(value)) return value.some(packageNeedsShaping);
+const somePackageRecord = (value, test) => {
+	if (Array.isArray(value) || value instanceof Map) {
+		for (const child of value.values()) if (somePackageRecord(child, test)) return true;
+		return false;
+	}
 	if (typeof value !== "object" || value === null) return false;
 	const entries = Object.entries(value);
-	const text = entries.find(([key]) => key === "text")?.[1];
-	if (entries.find(([key]) => key === "type")?.[1] === "text" && typeof text === "string" && needsShaping(text)) return true;
-	return entries.some(([, child]) => packageNeedsShaping(child));
+	return test(entries) || entries.some(([, child]) => somePackageRecord(child, test));
 };
+/**
+* Whether any text in the package needs shaping. The answer decides whether
+* the shaper is fetched at all: a document in Latin, Cyrillic or Greek must not
+* pay for an artifact it has no use for.
+*/
+const packageNeedsShaping = (value) => somePackageRecord(value, (entries) => {
+	const text = entries.find(([key]) => key === "text")?.[1];
+	return entries.find(([key]) => key === "type")?.[1] === "text" && typeof text === "string" && needsShaping(text);
+});
+/**
+* Parse and paginate a package. Fails rather than defaulting when no
+* measurement backend is installed: a layout measured by the wrong provider
+* is wrong in a way no downstream check catches.
+*/
 const layoutDocxHeadless = async (input, options = {}) => {
 	const providerCheck = Result.try(() => getMeasureProvider().getFontMetrics({ fontSize: 11 }));
 	if (providerCheck.isErr()) return Result.err(new HeadlessLayoutError({
@@ -245,32 +246,49 @@ const layoutDocxHeadless = async (input, options = {}) => {
 	const margins = getMargins(firstSection);
 	const contentWidth = pageSize.w - margins.left - margins.right;
 	const pageContentHeight = pageSize.h - margins.top - margins.bottom;
+	const endnotePosition = resolveEndnotePosition(document.package.settings?.endnotePr?.position, finalSection);
 	const flowOptions = buildFlowOptions(document, pageContentHeight);
+	const bodyTrailingEndnoteIds = trailingEndnoteIds(document.package.endnotes, endnotePosition);
+	if (bodyTrailingEndnoteIds.size > 0) flowOptions.trailingEndnoteIds = bodyTrailingEndnoteIds;
 	const storyOptions = buildStoryOptions(flowOptions);
-	const laidOut = Result.try(() => {
-		const authored = toFlowBlocks(projected.value, flowOptions);
-		const footnotes = document.package.footnotes ?? [];
-		const endnotes = document.package.endnotes ?? [];
-		const footnoteRefs = collectFootnoteRefs(authored);
-		const footnoteNumbers = computeNoteDisplayNumbers(footnotes, footnoteRefs.map((ref) => ref.footnoteId));
-		const endnoteNumbers = computeNoteDisplayNumbers(endnotes, collectEndnoteRefs(authored).map((ref) => ref.endnoteId));
-		const endnoteNumberFormat = finalSection?.endnotePr?.numFmt ?? "lowerRoman";
-		const blocks = remapNoteMarkerText(authored, {
-			footnoteNumbers,
-			endnoteTexts: formatEndnoteTexts(endnoteNumbers, (displayNumber) => formatOoxmlCounter(displayNumber, endnoteNumberFormat))
-		});
-		const measures = measureBlocks(blocks, contentWidth);
-		const footnoteContentById = footnoteRefs.length === 0 ? void 0 : buildFootnoteContentMap(footnotes, footnoteRefs, contentWidth, {
-			...storyOptions,
-			measureBlocks
-		});
-		const footnoteHeightById = /* @__PURE__ */ new Map();
-		for (const [id, content] of footnoteContentById ?? []) footnoteHeightById.set(id, content.height + 0);
-		const sectionHeaderFooterRefs = resolveSectionHeaderFooterRefs(document);
-		const finalPageSize = getPageSize(finalSection);
-		const finalMargins = getMargins(finalSection);
-		return {
-			layout: layoutDocument(blocks, measures, {
+	const layOut = () => {
+		const laidOut = Result.try(() => {
+			const authored = toFlowBlocks(projected.value, flowOptions);
+			const footnotes = document.package.footnotes ?? [];
+			const endnotes = document.package.endnotes ?? [];
+			const footnoteRefs = collectFootnoteRefs(authored);
+			const footnoteNumbers = computeNoteDisplayNumbers(footnotes, footnoteRefs.map((ref) => ref.footnoteId));
+			const endnoteNumbers = computeNoteDisplayNumbers(endnotes, collectEndnoteRefs(authored).map((ref) => ref.endnoteId));
+			const endnoteNumberFormat = finalSection?.endnotePr?.numFmt ?? document.package.settings?.endnotePr?.numFmt ?? "lowerRoman";
+			const endnoteTexts = formatEndnoteTexts(endnoteNumbers, (displayNumber) => formatOoxmlCounter(displayNumber, endnoteNumberFormat));
+			const blocks = remapNoteMarkerText(authored, {
+				footnoteNumbers,
+				endnoteTexts
+			});
+			const measures = measureBlocks(blocks, contentWidth);
+			const footnoteContentById = footnoteRefs.length === 0 ? void 0 : buildFootnoteContentMap(footnotes, footnoteRefs, contentWidth, {
+				...storyOptions,
+				measureBlocks
+			});
+			const footnoteHeightById = /* @__PURE__ */ new Map();
+			for (const [id, content] of footnoteContentById ?? []) footnoteHeightById.set(id, content.height + 0);
+			const endnoteAreas = prepareEndnoteAreas({
+				blocks,
+				endnotes,
+				displayNumbers: endnoteNumbers,
+				displayTexts: endnoteTexts,
+				position: endnotePosition,
+				sections: sections.map(({ properties }) => properties),
+				options: {
+					...storyOptions,
+					measureBlocks
+				}
+			});
+			const flow = spliceEndnoteAreas(blocks, measures, endnoteAreas);
+			const sectionHeaderFooterRefs = resolveSectionHeaderFooterRefs(document);
+			const finalPageSize = getPageSize(finalSection);
+			const finalMargins = getMargins(finalSection);
+			const layoutOptions = {
 				pageSize,
 				margins,
 				pageNumbering: getPageNumbering(firstSection),
@@ -283,51 +301,79 @@ const layoutDocxHeadless = async (input, options = {}) => {
 				evenAndOddHeaders: document.package.settings?.evenAndOddHeaders === true,
 				mirrorMargins: readsMirrorMargins(document.package.settings),
 				...footnoteHeightById.size === 0 ? {} : { footnoteHeightById },
-				...sectionHeaderFooterRefs === void 0 ? {} : { sectionHeaderFooterRefs }
-			}),
-			blockLookup: buildBlockLookup(blocks, measures),
-			footnoteContentById
-		};
-	});
-	if (laidOut.isErr()) return Result.err(new HeadlessLayoutError({
-		message: "The document could not be paginated.",
-		cause: laidOut.error
-	}));
-	const { layout, blockLookup, footnoteContentById } = laidOut.value;
-	const stories = Result.try(() => {
-		const pageCount = layout.pages.length;
-		const now = options.now ?? /* @__PURE__ */ new Date();
-		const shared = {
-			contentWidth,
-			storyOptions,
-			pageCount,
-			now
-		};
-		return {
-			headerContentByRId: convertStories({
-				...shared,
-				parts: document.package.headers,
-				metrics: {
-					section: "header",
-					pageSize,
-					margins
-				}
-			}),
-			footerContentByRId: convertStories({
-				...shared,
-				parts: document.package.footers,
-				metrics: {
-					section: "footer",
-					pageSize,
-					margins
-				}
-			})
-		};
-	});
-	if (stories.isErr()) return Result.err(new HeadlessLayoutError({
-		message: "The header and footer stories could not be laid out.",
-		cause: stories.error
-	}));
+				...sectionHeaderFooterRefs === void 0 ? {} : { sectionHeaderFooterRefs },
+				...endnoteAreas === void 0 ? {} : { noteAreas: endnoteAreas.noteAreas }
+			};
+			const blockLookup = buildBlockLookup(flow.blocks, flow.measures);
+			for (const [blockId, noteStory] of endnoteAreas?.noteStoryByBlockId ?? []) {
+				const entry = blockLookup.get(blockId);
+				if (entry !== void 0) entry.noteStory = noteStory;
+			}
+			const continuationSeparator = endnoteAreas?.noteAreas.continuationSeparator;
+			if (continuationSeparator !== void 0) blockLookup.set(String(continuationSeparator.block.id), continuationSeparator);
+			return {
+				layout: layoutDocument(flow.blocks, flow.measures, layoutOptions),
+				blockLookup,
+				footnoteContentById
+			};
+		});
+		if (laidOut.isErr()) return Result.err(new HeadlessLayoutError({
+			message: "The document could not be paginated.",
+			cause: laidOut.error
+		}));
+		const { layout, blockLookup, footnoteContentById } = laidOut.value;
+		const stories = Result.try(() => {
+			const pageCount = layout.pages.length;
+			const now = options.now ?? /* @__PURE__ */ new Date();
+			const shared = {
+				contentWidth,
+				storyOptions,
+				pageCount,
+				now
+			};
+			return {
+				headerContentByRId: convertStories({
+					...shared,
+					parts: document.package.headers,
+					metrics: {
+						section: "header",
+						pageSize,
+						margins
+					}
+				}),
+				footerContentByRId: convertStories({
+					...shared,
+					parts: document.package.footers,
+					metrics: {
+						section: "footer",
+						pageSize,
+						margins
+					}
+				})
+			};
+		});
+		if (stories.isErr()) return Result.err(new HeadlessLayoutError({
+			message: "The header and footer stories could not be laid out.",
+			cause: stories.error
+		}));
+		return Result.ok({
+			layout,
+			blockLookup,
+			footnoteContentById,
+			...stories.value
+		});
+	};
+	let pass = collectRequestedHyphenationDictionaries(layOut);
+	if (pass.missing.size > 0) {
+		const loaded = await preloadHyphenationDictionaries(pass.missing);
+		if (loaded.isErr()) return Result.err(new HeadlessLayoutError({
+			message: "A hyphenation dictionary could not be loaded, and this document needs one.",
+			cause: loaded.error
+		}));
+		pass = collectRequestedHyphenationDictionaries(layOut);
+	}
+	if (pass.result.isErr()) return Result.err(pass.result.error);
+	const { layout, blockLookup, footnoteContentById, headerContentByRId, footerContentByRId } = pass.result.value;
 	const embeddedFonts = declaresEmbeddedFonts(document) ? await Result.tryPromise({
 		try: async () => {
 			const source = await toArrayBuffer(input);
@@ -356,13 +402,13 @@ const layoutDocxHeadless = async (input, options = {}) => {
 			...watermark === void 0 ? {} : { watermark },
 			watermarkByHeaderRId: watermarksByHeader,
 			...watermarkImageSrc === void 0 ? {} : { watermarkImageSrc },
-			headerContentByRId: stories.value.headerContentByRId,
-			footerContentByRId: stories.value.footerContentByRId,
+			headerContentByRId,
+			footerContentByRId,
 			titlePg: firstSection?.titlePg === true,
 			...footnoteContentById === void 0 ? {} : { footnoteContentById }
 		},
 		embeddedFonts: embeddedFonts.value,
-		unsupported: Object.values(UNPAGINATED_STORIES).filter((gap) => hasStory(document, gap.story))
+		unsupported: Object.values(UNPAGINATED_STORIES)
 	});
 };
 //#endregion

package/dist/internal/paragraphFormattingSerialization.js

@@ -3,7 +3,7 @@ import { serializeBorder } from "../docx/serializer/borderSerializer.js";
 import { serializeShading, serializeTextFormatting } from "../docx/serializer/textFormattingSerializer.js";
 import { intAttr } from "../docx/serializer/xmlUtils.js";
 import { TRANSITIONAL_NAME_BY_STRICT_NAME } from "../docx/strictNames.gen.js";
-import { sanitizeCapturedXmlElement } from "../docx/verbatimCapture.js";
+import { createCapturedXmlSanitizer } from "../docx/verbatimCapture.js";
 import { NAMESPACES, OOXML_NAMESPACE_SCOPE } from "../docx/xmlParser.js";
 import { escapeXmlAttribute, serializeOnOffElement } from "@stll/docx-core";
 import { outlineLevelStatedValue, paragraphNumberingSlots, sameEffectiveParagraphNumbering } from "@stll/docx-core/model";
@@ -86,12 +86,12 @@ const serializeNumbering = ({ numPr, numberingChangeXml, numberingInsertionXml }
 const NUMBERING_CHANGE_ROOT_NAME = /* @__PURE__ */ new Set(["numberingChange"]);
 const NUMBERING_INSERTION_ROOT_NAME = /* @__PURE__ */ new Set(["ins"]);
 const WORDPROCESSINGML_NAMESPACE = /* @__PURE__ */ new Set([NAMESPACES.w]);
-const replayableNumberingChangeXml = (numberingChangeXml) => sanitizeCapturedXmlElement(numberingChangeXml, {
+const replayableNumberingChangeXml = createCapturedXmlSanitizer({
 	allowedLocalNames: NUMBERING_CHANGE_ROOT_NAME,
 	allowedNamespaceUris: WORDPROCESSINGML_NAMESPACE,
 	inheritedNamespaceScope: OOXML_NAMESPACE_SCOPE
 });
-const replayableNumberingInsertionXml = (numberingInsertionXml) => sanitizeCapturedXmlElement(numberingInsertionXml, {
+const replayableNumberingInsertionXml = createCapturedXmlSanitizer({
 	allowedLocalNames: NUMBERING_INSERTION_ROOT_NAME,
 	allowedNamespaceUris: WORDPROCESSINGML_NAMESPACE,
 	inheritedNamespaceScope: OOXML_NAMESPACE_SCOPE

package/dist/layout-bridge/convert/endnoteLayout.d.ts

@@ -0,0 +1,65 @@
+import { document_d_exports } from "../../types/document.js";
+import { FlowBlock, Measure, NoteAreaLayout } from "../../layout-engine/types.js";
+import { ConvertFootnoteOptions, MeasureBlocksFn } from "./footnoteLayout.js";
+import { NoteStoryKey } from "../../types/editor-story.js";
+//#region src/layout-bridge/convert/endnoteLayout.d.ts
+/** One endnote area and the body position it follows. */
+type EndnoteArea = {
+  /**
+   * The body `sectionBreak` block the area precedes, counted from zero; `null`
+   * places it after the last body block.
+   */
+  beforeSectionBreak: number | null;
+  blocks: FlowBlock[];
+  measures: Measure[];
+};
+type PreparedEndnoteAreas = {
+  areas: readonly EndnoteArea[];
+  noteAreas: NoteAreaLayout;
+  /** The endnote each area content block belongs to, by block id. */
+  noteStoryByBlockId: ReadonlyMap<string, NoteStoryKey>;
+};
+type PrepareEndnoteAreasInput = {
+  /** The body's top-level flow blocks, markers already renumbered. */
+  blocks: readonly FlowBlock[];
+  endnotes: readonly document_d_exports.Endnote[] | undefined;
+  /** Endnote `w:id` → reference-order number, as the body markers show it. */
+  displayNumbers: ReadonlyMap<number, number>;
+  /** Endnote `w:id` → the formatted number the body marker shows. */
+  displayTexts: ReadonlyMap<number, string>;
+  position: document_d_exports.EndnotePosition;
+  /**
+   * Section properties by section index: `w:noEndnote`, and the column width
+   * an area wraps to in the section it follows.
+   */
+  sections: readonly (document_d_exports.SectionProperties | undefined)[];
+  options: ConvertFootnoteOptions & {
+    measureBlocks: MeasureBlocksFn;
+  };
+};
+/**
+ * Convert and measure every referenced endnote into the areas `w:pos` asks
+ * for. `undefined` when no reference names a note, so a document without
+ * endnotes lays out exactly as it did before.
+ */
+declare function prepareEndnoteAreas(input: PrepareEndnoteAreasInput): PreparedEndnoteAreas | undefined;
+/**
+ * The body blocks with each endnote area in place: before the section break
+ * that ends the section it follows, or after the last body block.
+ */
+declare function spliceEndnoteAreas(blocks: FlowBlock[], measures: Measure[], prepared: PreparedEndnoteAreas | undefined): {
+  blocks: FlowBlock[];
+  measures: Measure[];
+};
+/**
+ * The endnotes a `docEnd` area collects after the body's last block, for
+ * `toFlowBlocks`' `trailingEndnoteIds`. Empty for `sectEnd`, whose final area
+ * depends on where the references fall.
+ */
+declare function trailingEndnoteIds(endnotes: readonly document_d_exports.Endnote[] | undefined, position: document_d_exports.EndnotePosition): ReadonlySet<number>;
+/** `w:pos` for the document: the settings value, else the final section's. */
+declare function resolveEndnotePosition(settingsPosition: document_d_exports.EndnotePosition | undefined, finalSection: document_d_exports.SectionProperties | undefined): document_d_exports.EndnotePosition;
+/** The first column's width in a section: what an endnote area there wraps to. */
+declare function endnoteAreaWidth(section: document_d_exports.SectionProperties | undefined): number;
+//#endregion
+export { PrepareEndnoteAreasInput, PreparedEndnoteAreas, endnoteAreaWidth, prepareEndnoteAreas, resolveEndnotePosition, spliceEndnoteAreas, trailingEndnoteIds };