@stll/folio-core 0.45.0 → 0.47.0

package/dist/docx/inlineWrapperContent.d.ts

@@ -0,0 +1,166 @@
+import { document_d_exports } from "../types/document.js";
+//#region src/docx/inlineWrapperContent.d.ts
+/**
+ * What a run-level tracked-change wrapper keeps inside itself (CT_RunTrackChange).
+ *
+ * Runs, links, fields, bookmark boundaries, equations, nested revisions and
+ * markup folio does not model.
+ *
+ * The transparent wrappers are admitted too: `w:bdo` / `w:dir` state how their
+ * content is laid out, and `w:sdt` states what the content is bound to.
+ * Neither says anything about the revision, so lifting one out of a revision
+ * takes its text out of the revision with it.
+ *
+ * The range markers are not: a `w:commentRangeStart` or `w:moveFromRangeStart`
+ * inside a revision is a marker the revision does not own, and the pairing
+ * passes read it as a paragraph-level sibling.
+ */
+declare const TRACKED_CHANGE_WRAPPER_CONTENT: {
+  readonly inlineWrapper: true;
+  readonly bookmarkEnd: true;
+  readonly bookmarkStart: true;
+  readonly complexField: true;
+  readonly deletion: true;
+  readonly hyperlink: true;
+  readonly inlineSdt: true;
+  readonly insertion: true;
+  readonly mathEquation: true;
+  readonly moveFrom: true;
+  readonly moveTo: true;
+  readonly preservedInline: true;
+  readonly run: true;
+  readonly simpleField: true;
+  readonly commentRangeEnd: false;
+  readonly commentRangeStart: false;
+  readonly commentReference: false;
+  readonly moveFromRangeEnd: false;
+  readonly moveFromRangeStart: false;
+  readonly moveToRangeEnd: false;
+  readonly moveToRangeStart: false;
+};
+/**
+ * What an inline content control keeps inside `<w:sdtContent>`.
+ *
+ * Mirror of upstream eigenpal/docx-editor PR #482 (commit 29f95751d), plus
+ * the bidirectional wrapper: OOXML allows runs, hyperlinks, simple/complex
+ * fields, nested SDTs, tracked insertions/deletions/moves, math, markup folio
+ * does not model, and the bidirectional controls directly inside
+ * `<w:sdtContent>`.
+ *
+ * The bookmark boundaries are admitted for the reason the revision wrapper
+ * admits them: `CT_SdtContentRun` reaches `EG_RangeMarkupElements` through
+ * `EG_RunLevelElts`, so the marker is valid where Word wrote it, and lifting
+ * it out changes what the bookmark covers. A range whose extent was the
+ * control's content comes back covering the control plus whatever follows, so
+ * a `REF` field or a link to it resolves to the wrong text.
+ *
+ * The other range markers are not: a `w:commentRangeStart` or a
+ * `w:moveFromRangeStart` inside the control is a marker the control does not
+ * own, and the pairing passes read it as a paragraph-level sibling.
+ */
+declare const INLINE_SDT_CONTENT: {
+  readonly inlineWrapper: true;
+  readonly bookmarkEnd: true;
+  readonly bookmarkStart: true;
+  readonly complexField: true;
+  readonly deletion: true;
+  readonly hyperlink: true;
+  readonly inlineSdt: true;
+  readonly insertion: true;
+  readonly mathEquation: true;
+  readonly moveFrom: true;
+  readonly moveTo: true;
+  readonly preservedInline: true;
+  readonly run: true;
+  readonly simpleField: true;
+  readonly commentRangeEnd: false;
+  readonly commentRangeStart: false;
+  readonly commentReference: false;
+  readonly moveFromRangeEnd: false;
+  readonly moveFromRangeStart: false;
+  readonly moveToRangeEnd: false;
+  readonly moveToRangeStart: false;
+};
+/**
+ * What a `w:hyperlink` keeps inside itself (CT_Hyperlink).
+ *
+ * Runs, the bookmark boundaries a link's target sits on, markup folio does not
+ * model, and the four transparent wrappers: `CT_Hyperlink` is `EG_PContent`,
+ * which declares `w:bdo`, `w:dir`, `w:smartTag` and the run-level
+ * `w:customXml`, so `w:hyperlink > w:bdo > w:r` is a link an author may write
+ * and folio reads it as authored.
+ *
+ * A revision is not admitted, and the exclusion is the model's, not the
+ * schema's: OOXML nests `w:ins` inside `w:hyperlink` and folio nests the link
+ * inside the revision, so the paragraph parser hoists one around the link.
+ */
+declare const HYPERLINK_CONTENT: {
+  readonly bookmarkEnd: true;
+  readonly bookmarkStart: true;
+  readonly inlineWrapper: true;
+  readonly preservedInline: true;
+  readonly run: true;
+  readonly commentRangeEnd: false;
+  readonly commentRangeStart: false;
+  readonly commentReference: false;
+  readonly complexField: false;
+  readonly deletion: false;
+  readonly hyperlink: false;
+  readonly inlineSdt: false;
+  readonly insertion: false;
+  readonly mathEquation: false;
+  readonly moveFrom: false;
+  readonly moveFromRangeEnd: false;
+  readonly moveFromRangeStart: false;
+  readonly moveTo: false;
+  readonly moveToRangeEnd: false;
+  readonly moveToRangeStart: false;
+  readonly simpleField: false;
+};
+/**
+ * What a `w:fldSimple` keeps inside itself (CT_SimpleField).
+ *
+ * The cached result's runs and the link one may carry, the same four
+ * transparent wrappers `EG_PContent` declares, and markup folio does not
+ * model. `w:fldData` is the field's own child rather than its content, so it
+ * rides `dispatchChildren`'s sink like any other capture.
+ */
+declare const SIMPLE_FIELD_CONTENT: {
+  readonly hyperlink: true;
+  readonly inlineWrapper: true;
+  readonly preservedInline: true;
+  readonly run: true;
+  readonly bookmarkEnd: false;
+  readonly bookmarkStart: false;
+  readonly commentRangeEnd: false;
+  readonly commentRangeStart: false;
+  readonly commentReference: false;
+  readonly complexField: false;
+  readonly deletion: false;
+  readonly inlineSdt: false;
+  readonly insertion: false;
+  readonly mathEquation: false;
+  readonly moveFrom: false;
+  readonly moveFromRangeEnd: false;
+  readonly moveFromRangeStart: false;
+  readonly moveTo: false;
+  readonly moveToRangeEnd: false;
+  readonly moveToRangeStart: false;
+  readonly simpleField: false;
+};
+/**
+ * Whether a revision wrapper keeps this content inside itself.
+ *
+ * Generic in the input so a caller that has already narrowed its content
+ * keeps that narrowing: filtering a list the bidirectional wrappers are
+ * already flattened out of must not put one back into the result type.
+ */
+declare const isTrackedChangeWrapperChild: <Content extends document_d_exports.ParagraphContent>(content: Content) => content is Extract<Content, document_d_exports.TrackedRunContent>;
+/** Whether an inline content control keeps this content inside `<w:sdtContent>`. */
+declare const isInlineSdtContent: <Content extends document_d_exports.ParagraphContent>(content: Content) => content is Extract<Content, document_d_exports.InlineSdt["content"][number]>;
+/** Whether a `w:hyperlink` keeps this content inside itself. */
+declare const isHyperlinkContent: <Content extends document_d_exports.ParagraphContent>(content: Content) => content is Extract<Content, document_d_exports.Hyperlink["children"][number]>;
+/** Whether a `w:fldSimple` keeps this content inside itself. */
+declare const isSimpleFieldContent: <Content extends document_d_exports.ParagraphContent>(content: Content) => content is Extract<Content, document_d_exports.SimpleField["content"][number]>;
+//#endregion
+export { HYPERLINK_CONTENT, INLINE_SDT_CONTENT, SIMPLE_FIELD_CONTENT, TRACKED_CHANGE_WRAPPER_CONTENT, isHyperlinkContent, isInlineSdtContent, isSimpleFieldContent, isTrackedChangeWrapperChild };

package/dist/docx/inlineWrapperContent.js

@@ -0,0 +1,165 @@
+//#region src/docx/inlineWrapperContent.ts
+/**
+* What a run-level tracked-change wrapper keeps inside itself (CT_RunTrackChange).
+*
+* Runs, links, fields, bookmark boundaries, equations, nested revisions and
+* markup folio does not model.
+*
+* The transparent wrappers are admitted too: `w:bdo` / `w:dir` state how their
+* content is laid out, and `w:sdt` states what the content is bound to.
+* Neither says anything about the revision, so lifting one out of a revision
+* takes its text out of the revision with it.
+*
+* The range markers are not: a `w:commentRangeStart` or `w:moveFromRangeStart`
+* inside a revision is a marker the revision does not own, and the pairing
+* passes read it as a paragraph-level sibling.
+*/
+const TRACKED_CHANGE_WRAPPER_CONTENT = {
+	inlineWrapper: true,
+	bookmarkEnd: true,
+	bookmarkStart: true,
+	complexField: true,
+	deletion: true,
+	hyperlink: true,
+	inlineSdt: true,
+	insertion: true,
+	mathEquation: true,
+	moveFrom: true,
+	moveTo: true,
+	preservedInline: true,
+	run: true,
+	simpleField: true,
+	commentRangeEnd: false,
+	commentRangeStart: false,
+	commentReference: false,
+	moveFromRangeEnd: false,
+	moveFromRangeStart: false,
+	moveToRangeEnd: false,
+	moveToRangeStart: false
+};
+/**
+* What an inline content control keeps inside `<w:sdtContent>`.
+*
+* Mirror of upstream eigenpal/docx-editor PR #482 (commit 29f95751d), plus
+* the bidirectional wrapper: OOXML allows runs, hyperlinks, simple/complex
+* fields, nested SDTs, tracked insertions/deletions/moves, math, markup folio
+* does not model, and the bidirectional controls directly inside
+* `<w:sdtContent>`.
+*
+* The bookmark boundaries are admitted for the reason the revision wrapper
+* admits them: `CT_SdtContentRun` reaches `EG_RangeMarkupElements` through
+* `EG_RunLevelElts`, so the marker is valid where Word wrote it, and lifting
+* it out changes what the bookmark covers. A range whose extent was the
+* control's content comes back covering the control plus whatever follows, so
+* a `REF` field or a link to it resolves to the wrong text.
+*
+* The other range markers are not: a `w:commentRangeStart` or a
+* `w:moveFromRangeStart` inside the control is a marker the control does not
+* own, and the pairing passes read it as a paragraph-level sibling.
+*/
+const INLINE_SDT_CONTENT = {
+	inlineWrapper: true,
+	bookmarkEnd: true,
+	bookmarkStart: true,
+	complexField: true,
+	deletion: true,
+	hyperlink: true,
+	inlineSdt: true,
+	insertion: true,
+	mathEquation: true,
+	moveFrom: true,
+	moveTo: true,
+	preservedInline: true,
+	run: true,
+	simpleField: true,
+	commentRangeEnd: false,
+	commentRangeStart: false,
+	commentReference: false,
+	moveFromRangeEnd: false,
+	moveFromRangeStart: false,
+	moveToRangeEnd: false,
+	moveToRangeStart: false
+};
+/**
+* What a `w:hyperlink` keeps inside itself (CT_Hyperlink).
+*
+* Runs, the bookmark boundaries a link's target sits on, markup folio does not
+* model, and the four transparent wrappers: `CT_Hyperlink` is `EG_PContent`,
+* which declares `w:bdo`, `w:dir`, `w:smartTag` and the run-level
+* `w:customXml`, so `w:hyperlink > w:bdo > w:r` is a link an author may write
+* and folio reads it as authored.
+*
+* A revision is not admitted, and the exclusion is the model's, not the
+* schema's: OOXML nests `w:ins` inside `w:hyperlink` and folio nests the link
+* inside the revision, so the paragraph parser hoists one around the link.
+*/
+const HYPERLINK_CONTENT = {
+	bookmarkEnd: true,
+	bookmarkStart: true,
+	inlineWrapper: true,
+	preservedInline: true,
+	run: true,
+	commentRangeEnd: false,
+	commentRangeStart: false,
+	commentReference: false,
+	complexField: false,
+	deletion: false,
+	hyperlink: false,
+	inlineSdt: false,
+	insertion: false,
+	mathEquation: false,
+	moveFrom: false,
+	moveFromRangeEnd: false,
+	moveFromRangeStart: false,
+	moveTo: false,
+	moveToRangeEnd: false,
+	moveToRangeStart: false,
+	simpleField: false
+};
+/**
+* What a `w:fldSimple` keeps inside itself (CT_SimpleField).
+*
+* The cached result's runs and the link one may carry, the same four
+* transparent wrappers `EG_PContent` declares, and markup folio does not
+* model. `w:fldData` is the field's own child rather than its content, so it
+* rides `dispatchChildren`'s sink like any other capture.
+*/
+const SIMPLE_FIELD_CONTENT = {
+	hyperlink: true,
+	inlineWrapper: true,
+	preservedInline: true,
+	run: true,
+	bookmarkEnd: false,
+	bookmarkStart: false,
+	commentRangeEnd: false,
+	commentRangeStart: false,
+	commentReference: false,
+	complexField: false,
+	deletion: false,
+	inlineSdt: false,
+	insertion: false,
+	mathEquation: false,
+	moveFrom: false,
+	moveFromRangeEnd: false,
+	moveFromRangeStart: false,
+	moveTo: false,
+	moveToRangeEnd: false,
+	moveToRangeStart: false,
+	simpleField: false
+};
+/**
+* Whether a revision wrapper keeps this content inside itself.
+*
+* Generic in the input so a caller that has already narrowed its content
+* keeps that narrowing: filtering a list the bidirectional wrappers are
+* already flattened out of must not put one back into the result type.
+*/
+const isTrackedChangeWrapperChild = (content) => TRACKED_CHANGE_WRAPPER_CONTENT[content.type];
+/** Whether an inline content control keeps this content inside `<w:sdtContent>`. */
+const isInlineSdtContent = (content) => INLINE_SDT_CONTENT[content.type];
+/** Whether a `w:hyperlink` keeps this content inside itself. */
+const isHyperlinkContent = (content) => HYPERLINK_CONTENT[content.type];
+/** Whether a `w:fldSimple` keeps this content inside itself. */
+const isSimpleFieldContent = (content) => SIMPLE_FIELD_CONTENT[content.type];
+//#endregion
+export { HYPERLINK_CONTENT, INLINE_SDT_CONTENT, SIMPLE_FIELD_CONTENT, TRACKED_CHANGE_WRAPPER_CONTENT, isHyperlinkContent, isInlineSdtContent, isSimpleFieldContent, isTrackedChangeWrapperChild };

package/dist/docx/inlineWrapperParser.d.ts

@@ -0,0 +1,11 @@
+import { document_d_exports } from "../types/document.js";
+import { XmlElement } from "./xmlParser.js";
+//#region src/docx/inlineWrapperParser.d.ts
+/** The elements that spell a transparent inline wrapper. */
+declare const INLINE_WRAPPER_ELEMENTS: readonly ["bdo", "dir", "smartTag", "customXml"];
+/** One of them, as the child dispatcher names it. */
+type InlineWrapperElement = (typeof INLINE_WRAPPER_ELEMENTS)[number];
+/** The wrapper `element` spells, around content the caller has already read. */
+declare const inlineWrapperOf: (element: InlineWrapperElement, node: XmlElement, content: document_d_exports.ParagraphContent[]) => document_d_exports.InlineWrapper;
+//#endregion
+export { INLINE_WRAPPER_ELEMENTS, InlineWrapperElement, inlineWrapperOf };

package/dist/docx/inlineWrapperParser.js

@@ -0,0 +1,60 @@
+import { captureVerbatimXml } from "./verbatimCapture.js";
+import { findChild, getAttribute } from "./xmlParser.js";
+import { BIDI_CONTROLS } from "@stll/docx-core/model";
+//#region src/docx/inlineWrapperParser.ts
+/** The elements that spell a transparent inline wrapper. */
+const INLINE_WRAPPER_ELEMENTS = [
+	"bdo",
+	"dir",
+	"smartTag",
+	"customXml"
+];
+/**
+* A `w:bdo` or `w:dir`: a bidirectional override or embedding. Both hold
+* inline content and change only how it is laid out, so the wrapper carries
+* its direction and nothing else.
+*/
+const bidiWrapper = (node, control, content) => {
+	const wrapper = {
+		type: "inlineWrapper",
+		kind: "bidi",
+		control,
+		content
+	};
+	const direction = getAttribute(node, "w", "val");
+	if (direction === "ltr" || direction === "rtl") wrapper.direction = direction;
+	return wrapper;
+};
+/**
+* A `w:smartTag` or a run-level `w:customXml`. Both name an element in another
+* vocabulary around content that is ordinary inline content; what the wrapper
+* adds is its name, its namespace and a properties bag folio replays rather
+* than reads. The `w:element` attribute is required by both content models,
+* and a tag without one names nothing, so it is read as the empty string
+* rather than refused: the content is what matters.
+*/
+const taggedWrapper = (node, kind, content) => {
+	const wrapper = {
+		type: "inlineWrapper",
+		kind,
+		element: getAttribute(node, "w", "element") ?? "",
+		content
+	};
+	const uri = getAttribute(node, "w", "uri");
+	if (uri !== null) wrapper.uri = uri;
+	const properties = findChild(node, "w", kind === "smartTag" ? "smartTagPr" : "customXmlPr");
+	if (properties) wrapper.propertiesXml = captureVerbatimXml(properties);
+	return wrapper;
+};
+/** The wrapper `element` spells, around content the caller has already read. */
+const inlineWrapperOf = (element, node, content) => {
+	switch (element) {
+		case "bdo": return bidiWrapper(node, BIDI_CONTROLS.override, content);
+		case "dir": return bidiWrapper(node, BIDI_CONTROLS.embedding, content);
+		case "smartTag": return taggedWrapper(node, "smartTag", content);
+		case "customXml": return taggedWrapper(node, "customXml", content);
+		default: return element;
+	}
+};
+//#endregion
+export { INLINE_WRAPPER_ELEMENTS, inlineWrapperOf };

package/dist/docx/nonVisualDrawingProps.d.ts

@@ -1,14 +1,6 @@
+import { document_d_exports } from "../types/document.js";
 import { XmlElement } from "./xmlParser.js";
 //#region src/docx/nonVisualDrawingProps.d.ts
-/** The authored name, alt text and title of a drawing object. */
-type NonVisualDrawingNames = {
-  /** `@name`, schema-required, so `""` means the object was never named. */
-  name?: string;
-  /** `@descr`: alt text, accessibility content. */
-  alt?: string;
-  /** `@title`. */
-  title?: string;
-};
 /**
  * Read `@name`, `@descr` and `@title` off a `CT_NonVisualDrawingProps` element.
  *
@@ -19,7 +11,7 @@ type NonVisualDrawingNames = {
  * tell the two apart. `@descr` and `@title` are optional and written only when
  * authored, so `""` in either is a string someone wrote.
  */
-declare const parseNonVisualDrawingNames: (element: XmlElement | null | undefined) => NonVisualDrawingNames;
+declare const parseNonVisualDrawingNames: (element: XmlElement | null | undefined) => document_d_exports.NonVisualDrawingNames;
 /**
  * The `name`, `descr` and `title` attributes of a `CT_NonVisualDrawingProps`
  * element, leading space included.
@@ -29,6 +21,6 @@ declare const parseNonVisualDrawingNames: (element: XmlElement | null | undefine
  * "Shape 3" would overwrite the author's own name for every drawing whose
  * name did not survive the model, and read back as authored content.
  */
-declare const serializeNonVisualDrawingNames: (names: NonVisualDrawingNames) => string;
-//#endregion
-export { NonVisualDrawingNames, parseNonVisualDrawingNames, serializeNonVisualDrawingNames };
+declare const serializeNonVisualDrawingNames: (names: document_d_exports.NonVisualDrawingNames) => string;
+type NonVisualDrawingNames = document_d_exports.NonVisualDrawingNames;
+export { type NonVisualDrawingNames, parseNonVisualDrawingNames, serializeNonVisualDrawingNames };

package/dist/docx/normalizeBaseDirection.js

@@ -44,13 +44,24 @@ const normalizeTable = (table, styles) => ({
 		...row,
 		cells: row.cells.map((cell) => ({
 			...cell,
-			content: cell.content.map((block) => block.type === "paragraph" ? normalizeParagraph(block, styles) : normalizeTable(block, styles))
+			content: cell.content.map((block) => normalizeCellBlock(block, styles))
 		}))
 	}))
 });
+const normalizeCellBlock = (block, styles) => {
+	switch (block.type) {
+		case "paragraph": return normalizeParagraph(block, styles);
+		case "table": return normalizeTable(block, styles);
+		case "preservedBlock":
+		case "bookmarkStart":
+		case "bookmarkEnd": return block;
+		default: return block;
+	}
+};
 const normalizeBlocks = (blocks, styles) => blocks.map((block) => {
 	if (block.type === "paragraph") return normalizeParagraph(block, styles);
 	if (block.type === "table") return normalizeTable(block, styles);
+	if (block.type === "preservedBlock" || block.type === "bookmarkStart" || block.type === "bookmarkEnd") return block;
 	return {
 		...block,
 		content: normalizeBlocks(block.content, styles)

package/dist/docx/numberingParser.d.ts

@@ -24,6 +24,29 @@ type NumberingMap = {
  * @returns NumberingMap with definitions and helper functions
  */
 declare function parseNumbering(numberingXml: string | null): NumberingMap;
+/** A `w:numFmt` as the model holds it: the token, plus what `custom` defers to. */
+type ResolvedNumFmt = Pick<document_d_exports.ListLevel, "numFmt" | "numFmtFormat">;
+/**
+ * The width a `custom` format's zero-padded first token counts to, or
+ * `undefined` for a pattern folio does not render.
+ *
+ * ECMA-376 §17.9.17: `@w:format` is an XSLT token list like
+ * "0001, 0002, 0003, ...". Word only emits zero-padded decimal customs this
+ * way; the width is the digit count of the first token, clamped to five.
+ */
+declare const customNumberFormatPadWidth: (format: string | undefined) => number | undefined;
+/**
+ * The `@w:format` a level's `w:numFmt` writes, which only `custom` carries.
+ *
+ * `custom` is the reserved member that defers to another attribute, so the
+ * comparison lives here, in the module the reserved-value registry names as
+ * its owner, rather than in the serializer that needs the answer.
+ */
+declare const customNumberFormatOf: (level: ResolvedNumFmt) => string | undefined;
+/** What the marker renderer counts a level in; `custom` decides by pad width. */
+declare const counterFormatOf: (level: ResolvedNumFmt) => document_d_exports.CounterFormat;
+/** {@link MARKER_ALIGNMENT} for a level that may not state a justification. */
+declare const markerAlignmentForLevel: (lvlJc: document_d_exports.ParagraphAlignment | undefined) => document_d_exports.ListRendering["markerAlignment"];
 declare const markerFormattingFromLevel: (formatting: document_d_exports.TextFormatting | undefined) => document_d_exports.ListMarkerFormatting | undefined;
 declare function getCachedNumberingMap(definitions: document_d_exports.NumberingDefinitions): NumberingMap;
 /**
@@ -54,7 +77,7 @@ declare function computeListRendering(numPr: {
  * @param formats - Array of number formats for each level
  * @returns Rendered marker text
  */
-declare function renderListMarker(lvlText: string, counters: number[], formats: document_d_exports.NumberFormat[]): string;
+declare function renderListMarker(lvlText: string, counters: number[], formats: document_d_exports.CounterFormat[]): string;
 /**
  * Get the bullet character for a bullet list level
  *
@@ -69,4 +92,4 @@ declare function isBulletLevel(level: document_d_exports.ListLevel): boolean;
 /** Whether a numbering level reserves horizontal space for a visible marker. */
 declare const numberingLevelHasMarkerSlot: (level: Pick<document_d_exports.ListLevel, "numFmt">) => boolean;
 //#endregion
-export { NumberingMap, computeListRendering, createNumberingMap, formatOoxmlCounter as formatNumber, getBulletCharacter, getCachedNumberingMap, isBulletLevel, markerFormattingFromLevel, numberingLevelHasMarkerSlot, padDecimal, parseNumbering, renderListMarker };
+export { NumberingMap, computeListRendering, counterFormatOf, createNumberingMap, customNumberFormatOf, customNumberFormatPadWidth, formatOoxmlCounter as formatNumber, getBulletCharacter, getCachedNumberingMap, isBulletLevel, markerAlignmentForLevel, markerFormattingFromLevel, numberingLevelHasMarkerSlot, padDecimal, parseNumbering, renderListMarker };