@stll/folio-core 0.45.0 → 0.47.0

package/dist/docx/numberingReference.d.ts

@@ -1,21 +1,14 @@
+import { XmlElement } from "./xmlParser.js";
+import { NO_NUMBERING_NUM_ID, NO_PARAGRAPH_NUMBERING, ParagraphNumberingOverride, ParagraphNumberingOverride as ParagraphNumberingOverride$1, ParagraphNumberingReference, ParagraphNumberingSlots, ResolvedParagraphNumbering, isNumberingReference, mergeParagraphNumbering, paragraphNumberingFromSlots, paragraphNumberingLevel, paragraphNumberingReference, paragraphNumberingReferenceId, paragraphNumberingSlots, resolveParagraphNumbering, sameEffectiveParagraphNumbering, sameStatedParagraphNumbering } from "@stll/docx-core/model";
 //#region src/docx/numberingReference.d.ts
 /**
- * The reserved `w:numId` value that means "no numbering".
+ * What a `<w:numPr>` states: absent (the tier states nothing), the reserved
+ * cancellation, a reference, or a level alone.
  *
- * ECMA-376 (17.9.18 `numId`, 17.9.19 `numPr`) reserves 0: it names no `w:num`,
- * it switches numbering off, and on a style it cancels the numbering the style
- * would otherwise inherit through `w:basedOn` (Word writes it on, for example,
- * a heading-based style that must not be numbered). It must therefore survive a
- * round trip: dropping the `w:numPr` would hand the numbering back.
+ * `w:numberingChange` is not read here. It is a historical record of what a
+ * reviewer changed, not a statement about this paragraph's numbering, and it
+ * travels as captured markup.
  */
-declare const NO_NUMBERING_NUM_ID = 0;
-/**
- * Whether a `w:numId` names a numbering definition to resolve.
- *
- * Every lookup or validation against `numbering.nums` goes through this: an
- * absent id has nothing to resolve, and {@link NO_NUMBERING_NUM_ID} is the
- * "none" sentinel, never a dangling reference.
- */
-declare const isNumberingReference: (numId: number | undefined) => numId is number;
+declare const readParagraphNumbering: (numPr: XmlElement | null | undefined) => ParagraphNumberingOverride$1 | undefined;
 //#endregion
-export { NO_NUMBERING_NUM_ID, isNumberingReference };
+export { NO_NUMBERING_NUM_ID, NO_PARAGRAPH_NUMBERING, type ParagraphNumberingOverride, type ParagraphNumberingReference, type ParagraphNumberingSlots, type ResolvedParagraphNumbering, isNumberingReference, mergeParagraphNumbering, paragraphNumberingFromSlots, paragraphNumberingLevel, paragraphNumberingReference, paragraphNumberingReferenceId, paragraphNumberingSlots, readParagraphNumbering, resolveParagraphNumbering, sameEffectiveParagraphNumbering, sameStatedParagraphNumbering };

package/dist/docx/numberingReference.js

@@ -1,21 +1,22 @@
+import { findChild, parseNumberingLevelAttribute, parseNumericAttribute } from "./xmlParser.js";
+import { NO_NUMBERING_NUM_ID, NO_PARAGRAPH_NUMBERING, isNumberingReference, mergeParagraphNumbering, paragraphNumberingFromSlots, paragraphNumberingFromSlots as paragraphNumberingFromSlots$1, paragraphNumberingLevel, paragraphNumberingReference, paragraphNumberingReferenceId, paragraphNumberingSlots, resolveParagraphNumbering, sameEffectiveParagraphNumbering, sameStatedParagraphNumbering } from "@stll/docx-core/model";
 //#region src/docx/numberingReference.ts
 /**
-* The reserved `w:numId` value that means "no numbering".
+* What a `<w:numPr>` states: absent (the tier states nothing), the reserved
+* cancellation, a reference, or a level alone.
 *
-* ECMA-376 (17.9.18 `numId`, 17.9.19 `numPr`) reserves 0: it names no `w:num`,
-* it switches numbering off, and on a style it cancels the numbering the style
-* would otherwise inherit through `w:basedOn` (Word writes it on, for example,
-* a heading-based style that must not be numbered). It must therefore survive a
-* round trip: dropping the `w:numPr` would hand the numbering back.
+* `w:numberingChange` is not read here. It is a historical record of what a
+* reviewer changed, not a statement about this paragraph's numbering, and it
+* travels as captured markup.
 */
-const NO_NUMBERING_NUM_ID = 0;
-/**
-* Whether a `w:numId` names a numbering definition to resolve.
-*
-* Every lookup or validation against `numbering.nums` goes through this: an
-* absent id has nothing to resolve, and {@link NO_NUMBERING_NUM_ID} is the
-* "none" sentinel, never a dangling reference.
-*/
-const isNumberingReference = (numId) => numId !== void 0 && numId !== 0;
+const readParagraphNumbering = (numPr) => {
+	if (!numPr) return;
+	const numIdElement = findChild(numPr, "w", "numId");
+	const ilvlElement = findChild(numPr, "w", "ilvl");
+	return paragraphNumberingFromSlots$1({
+		numId: numIdElement ? parseNumericAttribute(numIdElement, "w", "val") : void 0,
+		ilvl: ilvlElement ? parseNumberingLevelAttribute(ilvlElement) : void 0
+	});
+};
 //#endregion
-export { NO_NUMBERING_NUM_ID, isNumberingReference };
+export { NO_NUMBERING_NUM_ID, NO_PARAGRAPH_NUMBERING, isNumberingReference, mergeParagraphNumbering, paragraphNumberingFromSlots, paragraphNumberingLevel, paragraphNumberingReference, paragraphNumberingReferenceId, paragraphNumberingSlots, readParagraphNumbering, resolveParagraphNumbering, sameEffectiveParagraphNumbering, sameStatedParagraphNumbering };

package/dist/docx/numberingReferenceNormalization.js

@@ -1,4 +1,4 @@
-import { isNumberingReference } from "./numberingReference.js";
+import { NO_PARAGRAPH_NUMBERING as NO_PARAGRAPH_NUMBERING$1, paragraphNumberingReferenceId as paragraphNumberingReferenceId$1 } from "./numberingReference.js";
 import { visitDocxParagraphs } from "./paragraphTraversal.js";
 import { PARSE_WARNING_CODES } from "@stll/docx-core/model";
 //#region src/docx/numberingReferenceNormalization.ts
@@ -40,9 +40,9 @@ const normalizeNumberingReferences = ({ documentBody, numbering, headers, footer
 		endnotes
 	}, (paragraph) => {
 		const formatting = paragraph.formatting;
-		const numId = formatting?.numPr?.numId;
-		if (!formatting || !isNumberingReference(numId) || resolvesNumbering(numId, numbering)) return;
-		formatting.numPr = { numId: 0 };
+		const numId = paragraphNumberingReferenceId$1(formatting?.numPr);
+		if (!formatting || numId === void 0 || resolvesNumbering(numId, numbering)) return;
+		formatting.numPr = NO_PARAGRAPH_NUMBERING$1;
 		delete formatting.numPrFromStyle;
 		delete paragraph.listRendering;
 		unnumberedDanglingReferences += 1;
@@ -53,9 +53,9 @@ const normalizeStyleNumberingReferences = ({ styles, numbering }) => {
 	const unnumberedStyleIds = [];
 	for (const style of styles) {
 		const pPr = style.pPr;
-		const numId = pPr?.numPr?.numId;
-		if (!pPr || !isNumberingReference(numId) || resolvesNumbering(numId, numbering)) continue;
-		pPr.numPr = { numId: 0 };
+		const numId = paragraphNumberingReferenceId$1(pPr?.numPr);
+		if (!pPr || numId === void 0 || resolvesNumbering(numId, numbering)) continue;
+		pPr.numPr = NO_PARAGRAPH_NUMBERING$1;
 		unnumberedStyleIds.push(style.styleId);
 	}
 	return { unnumberedStyleIds };

package/dist/docx/ooxmlCounterFormatter.d.ts

@@ -3,6 +3,6 @@ import { document_d_exports } from "../types/document.js";
 /** Zero-pad a counter to `width` digits (the `decimalZero` family). */
 declare const padDecimal: (value: number, width: number) => string;
 /** Format one OOXML numbering counter using Microsoft Word display semantics. */
-declare const formatOoxmlCounter: (value: number, format: document_d_exports.NumberFormat | undefined) => string;
+declare const formatOoxmlCounter: (value: number, format: document_d_exports.CounterFormat | undefined) => string;
 //#endregion
 export { formatOoxmlCounter, padDecimal };

package/dist/docx/ooxmlCounterFormatter.js

@@ -103,7 +103,10 @@ const formatOoxmlCounter = (value, format) => {
 		case "hindiCounting":
 		case "thaiLetters":
 		case "thaiNumbers":
-		case "thaiCounting": return String(value);
+		case "thaiCounting":
+		case "bahtText":
+		case "dollarText":
+		case "custom": return String(value);
 		case "decimalZero": return padDecimal(value, 2);
 		case "decimalZero3": return padDecimal(value, 3);
 		case "decimalZero4": return padDecimal(value, 4);

package/dist/docx/paraIdAttribute.d.ts

@@ -0,0 +1,111 @@
+import { XmlElement } from "./xmlParser.js";
+//#region src/docx/paraIdAttribute.d.ts
+/**
+ * The namespaces a paraId-valued attribute may be written in: the Word 2010,
+ * 2012 and 2018 wordml extensions.
+ *
+ * The 2018 URI is read from the serializer's table rather than retyped, so the
+ * spelling folio writes and the spelling it accepts cannot drift.
+ */
+declare const PARA_ID_NAMESPACE_URIS: ReadonlySet<string>;
+/** The paraId this element carries, or `undefined` when it carries none. */
+declare const paraIdAttribute: (element: XmlElement) => string | undefined;
+/** The paraId of the parent this element names, by the same rule. */
+declare const paraIdParentAttribute: (element: XmlElement) => string | undefined;
+/**
+ * The textId this element carries: a paragraph identity written beside
+ * `paraId`, in the same namespaces and by the same rule.
+ */
+declare const textIdAttribute: (element: XmlElement) => string | undefined;
+/**
+ * How a save addresses one paragraph of the part it is patching.
+ *
+ * Word 2010+ writes a `w14:paraId` on every paragraph; LibreOffice, Google
+ * Docs, python-docx and docx4j write none, and a package can carry both (Word
+ * stamps what it rewrites and leaves the rest). folio mints an id for every
+ * paragraph that arrives without one, so the model always has a key — but a
+ * minted key names nothing in the file, and looking it up there answers
+ * "absent" for every paragraph at once. Naming the two cases apart is what lets
+ * the patcher keep the id lookup where the file has an id and fall back to
+ * position only where it does not.
+ */
+type ParagraphIdentity =
+/** The source part writes this paraId, so the id locates the paragraph. */
+{
+  type: "authored";
+  paraId: string;
+  ordinal: number;
+} |
+/** The model's id was minted at parse; the ordinal locates the paragraph. */
+{
+  type: "minted";
+  paraId: string;
+  ordinal: number;
+} |
+/** Neither side writes an id: nothing can name this paragraph to change it. */
+{
+  type: "anonymous";
+  ordinal: number;
+};
+/**
+ * What comparing two paragraph sequences by ordinal is worth.
+ *
+ * An ordinal only locates a paragraph when the two sequences agree on the
+ * paragraph order, and the ids they carry are the witnesses to that. The
+ * witnesses answer two separate questions, so they are reported separately
+ * rather than folded into one boolean: `consistent` says no id contradicts the
+ * ordinals, and `sharedOrdinals` counts the ids that actively confirm them. A
+ * caller comparing two views of ONE document already knows it is the same
+ * document, so absence of contradiction is its whole burden; a caller asking
+ * whether two containers of two DIFFERENT documents are the same container
+ * needs confirmation as well, or every equal-length container would pair with
+ * every other. Deciding that here, once, is what stops the save and the
+ * comparison from drifting into two answers about the same paragraphs.
+ */
+type ParagraphOrdinalAlignment = {
+  /** No id sits at one ordinal on one side and a different one on the other. */
+  consistent: boolean;
+  /** Ordinals carrying the same id on both sides. */
+  sharedOrdinals: number;
+};
+/**
+ * Line two paragraph sequences up by ordinal, judged by the ids they carry.
+ *
+ * An id only testifies when both sides carry it: one side alone says nothing,
+ * because a producer's id can be absent from a model that could not read it and
+ * a minted id is absent from the file it was minted for. An id both sides carry
+ * at the same ordinal confirms the alignment; at different ordinals, or written
+ * twice on either side, it refutes it.
+ */
+declare const alignParagraphOrdinals: (base: readonly ParagraphIdentity[], revised: readonly ParagraphIdentity[]) => ParagraphOrdinalAlignment;
+/**
+ * Every paragraph's identity, plus whether ordinals may be trusted.
+ *
+ * `ordinalsAligned` is the evidence a `minted` splice needs. Both sequences
+ * describe one document — the source part and the model parsed from it — so
+ * {@link alignParagraphOrdinals}'s `consistent` is the whole of the question: a
+ * package with ids on some paragraphs proves its own alignment through them,
+ * and one with none is aligned vacuously behind the paragraph-count check the
+ * caller already runs.
+ */
+type ParagraphIdentityPlan = {
+  identities: readonly ParagraphIdentity[];
+  ordinalsAligned: boolean;
+};
+type ResolveParagraphIdentitiesOptions = {
+  /** The paraId written on each `<w:p>` of the source part, in document order. */
+  sourceParaIds: readonly (string | undefined)[];
+  /** The paraId the model serialized for each `<w:p>`, in the same order. */
+  serializedParaIds: readonly (string | undefined)[];
+};
+/**
+ * Decide each serialized paragraph's identity against the source part.
+ *
+ * A paraId the source writes exactly once is `authored`; the same id written
+ * twice stays `authored` and is left for the caller's ambiguity check, so a
+ * duplicate is refused rather than silently addressed by position. An id the
+ * source does not write at all is `minted`.
+ */
+declare const resolveParagraphIdentities: ({ sourceParaIds, serializedParaIds }: ResolveParagraphIdentitiesOptions) => ParagraphIdentityPlan;
+//#endregion
+export { PARA_ID_NAMESPACE_URIS, ParagraphIdentity, ParagraphIdentityPlan, ParagraphOrdinalAlignment, ResolveParagraphIdentitiesOptions, alignParagraphOrdinals, paraIdAttribute, paraIdParentAttribute, resolveParagraphIdentities, textIdAttribute };

package/dist/docx/paraIdAttribute.js

@@ -0,0 +1,142 @@
+import { OOXML_NAMESPACES } from "./serializer/partNamespaces.js";
+import { NAMESPACES, WORDPROCESSINGML_NAMESPACE_URIS, getAttributeByNamespaceUri } from "./xmlParser.js";
+//#region src/docx/paraIdAttribute.ts
+/**
+* The one reader for "the paraId written on this element".
+*
+* A `paraId` is a join key: `w15:commentEx/@w15:paraId`,
+* `w16cex:comment/@w16cex:paraId` and `w15:paraIdParent` all name a paragraph
+* through the `w14:paraId` it carries. Three Word generations write the same
+* key under three prefixes, and a producer is free to bind any of those
+* namespaces to a prefix of its own choosing, so the key must be resolved by
+* namespace URI. Resolving it by local name alone is worse than missing it: an
+* unrelated `vendor:paraId` would key a comment into another thread and carry
+* that thread's date, parent and resolved state.
+*
+* Every reader of the key calls this, so no call site can come to disagree
+* with another about which attribute is a paraId.
+*/
+/**
+* The namespaces a paraId-valued attribute may be written in: the Word 2010,
+* 2012 and 2018 wordml extensions.
+*
+* The 2018 URI is read from the serializer's table rather than retyped, so the
+* spelling folio writes and the spelling it accepts cannot drift.
+*/
+const PARA_ID_NAMESPACE_URIS = /* @__PURE__ */ new Set([
+	NAMESPACES.w14,
+	NAMESPACES.w15,
+	OOXML_NAMESPACES.w16cex.uri
+]);
+/**
+* The conventional prefixes, read literally as a last resort.
+*
+* A part that writes `w14:paraId` without declaring `xmlns:w14` is malformed,
+* and no URI lookup can resolve it; Word reads those files, so folio does too.
+*/
+const CONVENTIONAL_PARA_ID_PREFIXES = [
+	"w14",
+	"w15",
+	"w16cex"
+];
+const paraIdValuedAttribute = (element, localName) => {
+	const byUri = getAttributeByNamespaceUri(element, PARA_ID_NAMESPACE_URIS, localName);
+	if (byUri !== null) return byUri;
+	for (const prefix of CONVENTIONAL_PARA_ID_PREFIXES) {
+		const literal = element.attributes?.[`${prefix}:${localName}`];
+		if (literal !== void 0) return String(literal);
+	}
+	const inWordprocessingml = getAttributeByNamespaceUri(element, WORDPROCESSINGML_NAMESPACE_URIS, localName);
+	if (inWordprocessingml !== null) return inWordprocessingml;
+	const literalW = element.attributes?.[`w:${localName}`];
+	return literalW === void 0 ? void 0 : String(literalW);
+};
+/** The paraId this element carries, or `undefined` when it carries none. */
+const paraIdAttribute = (element) => paraIdValuedAttribute(element, "paraId");
+/** The paraId of the parent this element names, by the same rule. */
+const paraIdParentAttribute = (element) => paraIdValuedAttribute(element, "paraIdParent");
+/**
+* The textId this element carries: a paragraph identity written beside
+* `paraId`, in the same namespaces and by the same rule.
+*/
+const textIdAttribute = (element) => paraIdValuedAttribute(element, "textId");
+/** Ordinal per id, or `null` when the sequence writes that id more than once. */
+const ordinalsById = (identities) => {
+	const byId = /* @__PURE__ */ new Map();
+	for (const identity of identities) {
+		if (identity.type === "anonymous") continue;
+		byId.set(identity.paraId, byId.has(identity.paraId) ? null : identity.ordinal);
+	}
+	return byId;
+};
+/**
+* Line two paragraph sequences up by ordinal, judged by the ids they carry.
+*
+* An id only testifies when both sides carry it: one side alone says nothing,
+* because a producer's id can be absent from a model that could not read it and
+* a minted id is absent from the file it was minted for. An id both sides carry
+* at the same ordinal confirms the alignment; at different ordinals, or written
+* twice on either side, it refutes it.
+*/
+const alignParagraphOrdinals = (base, revised) => {
+	if (base.length !== revised.length) return {
+		consistent: false,
+		sharedOrdinals: 0
+	};
+	const baseOrdinals = ordinalsById(base);
+	const revisedOrdinals = ordinalsById(revised);
+	let sharedOrdinals = 0;
+	for (const [paraId, baseOrdinal] of baseOrdinals) {
+		const revisedOrdinal = revisedOrdinals.get(paraId);
+		if (revisedOrdinal === void 0) continue;
+		if (baseOrdinal === null || revisedOrdinal === null || baseOrdinal !== revisedOrdinal) return {
+			consistent: false,
+			sharedOrdinals: 0
+		};
+		sharedOrdinals += 1;
+	}
+	return {
+		consistent: true,
+		sharedOrdinals
+	};
+};
+/**
+* Decide each serialized paragraph's identity against the source part.
+*
+* A paraId the source writes exactly once is `authored`; the same id written
+* twice stays `authored` and is left for the caller's ambiguity check, so a
+* duplicate is refused rather than silently addressed by position. An id the
+* source does not write at all is `minted`.
+*/
+const resolveParagraphIdentities = ({ sourceParaIds, serializedParaIds }) => {
+	const sourceIdentities = sourceParaIds.map((paraId, ordinal) => paraId === void 0 ? {
+		type: "anonymous",
+		ordinal
+	} : {
+		type: "authored",
+		paraId,
+		ordinal
+	});
+	const sourceIds = new Set(sourceParaIds.filter((paraId) => paraId !== void 0));
+	const identities = serializedParaIds.map((paraId, ordinal) => {
+		if (paraId === void 0) return {
+			type: "anonymous",
+			ordinal
+		};
+		return sourceIds.has(paraId) ? {
+			type: "authored",
+			paraId,
+			ordinal
+		} : {
+			type: "minted",
+			paraId,
+			ordinal
+		};
+	});
+	return {
+		identities,
+		ordinalsAligned: alignParagraphOrdinals(sourceIdentities, identities).consistent
+	};
+};
+//#endregion
+export { PARA_ID_NAMESPACE_URIS, alignParagraphOrdinals, paraIdAttribute, paraIdParentAttribute, resolveParagraphIdentities, textIdAttribute };

package/dist/docx/paragraphParser.d.ts

@@ -1,27 +1,15 @@
 import { document_d_exports } from "../types/document.js";
 import { NumberingMap } from "./numberingParser.js";
-import { StyleMap } from "./styleParser.js";
 import { XmlElement } from "./xmlParser.js";
+import { StyleMap } from "./styleParser.js";
 //#region src/docx/paragraphParser.d.ts
-/**
- * Parse paragraph formatting properties (w:pPr)
- *
- * Handles ALL pPr properties:
- * - w:jc (alignment: left, center, right, both/justify)
- * - w:spacing (before, after, line, lineRule)
- * - w:ind (left, right, firstLine, hanging)
- * - w:pBdr (paragraph borders: top, bottom, left, right, between)
- * - w:shd (paragraph shading/background)
- * - w:tabs (tab stops with positions and types)
- * - w:keepNext, w:keepLines, w:widowControl, w:pageBreakBefore
- * - w:bidi (right-to-left)
- * - w:numPr (list info)
- * - w:pStyle (style reference)
- * - w:outlineLvl (outline level)
- * - w:framePr (frame properties)
- * - w:rPr (default run properties)
- */
-declare function parseParagraphProperties(pPr: XmlElement | null, theme: document_d_exports.Theme | null, styles?: StyleMap): document_d_exports.ParagraphFormatting | undefined;
+declare function parseParagraphPropertyChanges(pPr: XmlElement | null, theme: document_d_exports.Theme | null, currentFormatting: document_d_exports.ParagraphFormatting | undefined): document_d_exports.ParagraphPropertyChange[] | undefined;
+type ParseParagraphOptions = {
+  inHeaderFooter?: boolean;
+  rootXmlns?: Record<string, string>;
+  /** Delay run merging until a source-position-dependent enrichment pass completes. */
+  runConsolidation?: "immediate" | "deferred";
+};
 /**
  * Parse a paragraph element (w:p)
  *
@@ -34,10 +22,7 @@ declare function parseParagraphProperties(pPr: XmlElement | null, theme: documen
  * @param options - Parsing options for context-specific body behavior
  * @returns Parsed Paragraph object
  */
-declare function parseParagraph(node: XmlElement, styles: StyleMap | null, theme: document_d_exports.Theme | null, numbering: NumberingMap | null, rels?: document_d_exports.RelationshipMap | null, media?: Map<string, document_d_exports.MediaFile> | null, options?: {
-  inHeaderFooter?: boolean;
-  rootXmlns?: Record<string, string>;
-}): document_d_exports.Paragraph;
+declare function parseParagraph(node: XmlElement, styles: StyleMap | null, theme: document_d_exports.Theme | null, numbering: NumberingMap | null, rels?: document_d_exports.RelationshipMap | null, media?: Map<string, document_d_exports.MediaFile> | null, options?: ParseParagraphOptions): document_d_exports.Paragraph;
 /**
  * Get plain text from a paragraph
  *
@@ -82,4 +67,4 @@ declare function hasStyle(paragraph: document_d_exports.Paragraph, styleId: stri
  */
 declare function getTemplateVariable(paragraph: document_d_exports.Paragraph): string | null;
 //#endregion
-export { getListLevel, getParagraphText, getTemplateVariable, hasStyle, isEmptyParagraph, isListItem, parseParagraph, parseParagraphProperties };
+export { getListLevel, getParagraphText, getTemplateVariable, hasStyle, isEmptyParagraph, isListItem, parseParagraph, parseParagraphPropertyChanges };