@stll/folio-core 0.54.2 → 0.56.0

package/dist/controller/canonicalInlineProjection.js

@@ -0,0 +1,393 @@
+import { readNoteMarkerAttrs } from "../internal/noteMarkerAttrs.js";
+import { readFootnoteRefMarkAttrs, readPreservedXmlAttrs } from "../prosemirror/attrs/index.js";
+import { bookmarkMarkerFromAttrs, readBookmarkBoundaryAttrs } from "../prosemirror/bookmarkBoundaryAttrs.js";
+import { HYPHEN_TEXT_CARRIERS } from "../prosemirror/conversion/hyphenTextCarriers.js";
+import { readMoveRangeBoundaryAttrs } from "../prosemirror/moveRangeBoundaryAttrs.js";
+import { readRangeAnchorAttrs } from "../prosemirror/rangeAnchorAttrs.js";
+import { PRESERVED_XML_LEVELS } from "../prosemirror/schema/nodes.js";
+import { Result, TaggedError, panic } from "better-result";
+import { hasIllegalXmlCharacters } from "@stll/docx-core";
+import { inlineLeafSpans, paragraphLogicalText } from "@stll/docx-core/ops";
+//#region src/controller/canonicalInlineProjection.ts
+const CANONICAL_SOURCE_INLINE_POLICIES = {
+	run: "container",
+	hyperlink: "container",
+	insertion: "container",
+	deletion: "container",
+	moveFrom: "container",
+	moveTo: "container",
+	inlineWrapper: "container",
+	inlineSdt: "control",
+	simpleField: "leaf",
+	complexField: "leaf",
+	mathEquation: "leaf",
+	preservedInline: "leaf",
+	bookmarkStart: "leaf",
+	bookmarkEnd: "leaf",
+	commentRangeStart: "leaf",
+	commentRangeEnd: "leaf",
+	commentReference: "leaf",
+	moveFromRangeStart: "leaf",
+	moveFromRangeEnd: "leaf",
+	moveToRangeStart: "leaf",
+	moveToRangeEnd: "leaf",
+	text: "text",
+	tab: "leaf",
+	break: "leaf",
+	symbol: "leaf",
+	footnoteRef: "leaf",
+	endnoteRef: "leaf",
+	noteMarker: "leaf",
+	fieldChar: "rawField",
+	instrText: "rawField",
+	softHyphen: "leaf",
+	noBreakHyphen: "leaf",
+	renderedPageBreak: "layout",
+	preservedXml: "leaf",
+	drawing: "leaf",
+	shape: "leaf"
+};
+const CANONICAL_NATIVE_INLINE_POLICIES = {
+	text: "text",
+	bookmarkBoundary: "markers",
+	moveRangeBoundary: "markers",
+	rangeAnchor: "markers",
+	noteMarker: "noteMarker",
+	preservedXml: "capture",
+	field: "unit",
+	structuredField: "unit",
+	hardBreak: "unit",
+	image: "unit",
+	math: "unit",
+	pageBreakRun: "unit",
+	shape: "unit",
+	symbol: "unit",
+	tab: "unit",
+	textBoxAnchor: "unit",
+	commentReference: "unit",
+	renderedPageBreak: "refused",
+	sdt: "refused"
+};
+const nativePolicies = new Map(Object.entries(CANONICAL_NATIVE_INLINE_POLICIES));
+var InlineProjectionError = class extends TaggedError("InlineProjectionError") {};
+const refuse = (message) => Result.err(new InlineProjectionError({ message }));
+/** Every source variant makes a decision before conversion can discard its positions. */
+const canonicalInlineSourceIssue = (items, context = "paragraph") => {
+	for (const item of items) switch (CANONICAL_SOURCE_INLINE_POLICIES[item.type]) {
+		case "control":
+			if (context === "fieldPayload" && item.type === "inlineSdt") {
+				const issue = canonicalInlineSourceIssue(item.content, context);
+				if (issue !== null) return issue;
+				break;
+			}
+			return "Canonical editing cannot preserve inline content-control boundary positions.";
+		case "rawField":
+			if (context === "fieldPayload") break;
+			return "Canonical editing cannot preserve unstructured field instructions; a structured field is required.";
+		case "layout": return "Canonical editing cannot preserve cached rendered page-break positions.";
+		case "text":
+			if (item.type === "text" && (hasIllegalXmlCharacters(item.text) || /[\t\r\n]/u.test(item.text))) return "Canonical text requires valid XML characters and explicit tab or break elements.";
+			break;
+		case "container": {
+			if ((item.type === "insertion" || item.type === "deletion") && item.resolutionJoins !== void 0 && item.content.some((child) => child.type === "hyperlink")) return "Canonical editing cannot preserve hyperlink wrapper review provenance.";
+			const children = sourceContainerChildren(item);
+			const issue = canonicalInlineSourceIssue(children, context);
+			if (issue !== null) return issue;
+			break;
+		}
+		case "leaf": {
+			let children = [];
+			if (item.type === "simpleField") children = item.content;
+			if (item.type === "complexField") children = [...item.fieldCode, ...item.fieldResult];
+			const issue = canonicalInlineSourceIssue(children, "fieldPayload");
+			if (issue !== null) return issue;
+			break;
+		}
+		default:
+	}
+	return null;
+};
+const sourceContainerChildren = (item) => {
+	switch (item.type) {
+		case "hyperlink": return item.children;
+		case "run":
+		case "insertion":
+		case "deletion":
+		case "moveFrom":
+		case "moveTo":
+		case "inlineWrapper": return item.content;
+		default: return panic(`Source policy incorrectly classified ${item.type} as a container.`);
+	}
+};
+/** Native positions and deletion geometry read the same inline-cell classification. */
+const canonicalNativeCells = (paragraph) => {
+	const cells = [];
+	let issue;
+	paragraph.forEach((node, from) => {
+		if (issue !== void 0) return;
+		const to = from + node.nodeSize;
+		switch (nativePolicies.get(node.type.name)) {
+			case "text": {
+				const reference = node.marks.find(({ type }) => type.name === "footnoteRef");
+				if (!reference) {
+					cells.push({
+						type: "text",
+						text: node.text ?? "",
+						from,
+						to,
+						node
+					});
+					return;
+				}
+				const attrs = readFootnoteRefMarkAttrs(reference);
+				if (!attrs.ok) {
+					issue = "Canonical editing requires valid note-reference mark attributes.";
+					return;
+				}
+				const label = String(attrs.value.id);
+				const text = node.text ?? "";
+				if (label.length === 0 || text.length % label.length !== 0 || text !== label.repeat(text.length / label.length)) {
+					issue = "Canonical editing cannot map the rendered note-reference labels.";
+					return;
+				}
+				for (let offset = 0; offset < text.length; offset += label.length) cells.push({
+					type: "markedUnit",
+					sourceType: attrs.value.noteType === "endnote" ? "endnoteRef" : "footnoteRef",
+					label,
+					from: from + offset,
+					to: from + offset + label.length,
+					node
+				});
+				return;
+			}
+			case "unit":
+				cells.push({
+					type: "unit",
+					from,
+					to,
+					node
+				});
+				return;
+			case "markers":
+				if (node.type.name === "bookmarkBoundary") {
+					const attrs = readBookmarkBoundaryAttrs(node);
+					if (!attrs.ok) {
+						issue = "Canonical editing requires valid bookmark boundary attributes.";
+						return;
+					}
+					cells.push({
+						type: "zeroWidth",
+						sources: [bookmarkMarkerFromAttrs(attrs.value)],
+						from,
+						to,
+						node
+					});
+				} else if (node.type.name === "moveRangeBoundary") {
+					const attrs = readMoveRangeBoundaryAttrs(node);
+					if (!attrs.ok) {
+						issue = "Canonical editing requires valid move-range boundary attributes.";
+						return;
+					}
+					cells.push({
+						type: "zeroWidth",
+						sources: [attrs.value],
+						from,
+						to,
+						node
+					});
+				} else {
+					const attrs = readRangeAnchorAttrs(node);
+					if (!attrs.ok) {
+						issue = "Canonical editing requires a valid collapsed range anchor.";
+						return;
+					}
+					cells.push({
+						type: "zeroWidth",
+						sources: [attrs.value.start, attrs.value.end],
+						from,
+						to,
+						node
+					});
+				}
+				return;
+			case "noteMarker": {
+				const attrs = readNoteMarkerAttrs(node);
+				if (!attrs.ok) {
+					issue = "Canonical editing requires a valid automatic note marker.";
+					return;
+				}
+				cells.push({
+					type: "zeroWidth",
+					sources: [{
+						type: "noteMarker",
+						kind: attrs.value.kind
+					}],
+					from,
+					to,
+					node
+				});
+				return;
+			}
+			case "capture": {
+				const attrs = readPreservedXmlAttrs(node);
+				if (!attrs.ok) {
+					issue = "Canonical editing requires valid preserved inline markup.";
+					return;
+				}
+				if (attrs.value.level === PRESERVED_XML_LEVELS.inline && attrs.value.text === "") cells.push({
+					type: "zeroWidth",
+					sources: [{
+						type: "preservedInline",
+						xml: attrs.value.xml,
+						text: ""
+					}],
+					from,
+					to,
+					node
+				});
+				else cells.push({
+					type: "unit",
+					from,
+					to,
+					node
+				});
+				return;
+			}
+			case "refused":
+				issue = `Canonical editing cannot preserve ${node.type.name} boundary positions.`;
+				return;
+			case void 0:
+				issue = `Canonical editing has no position mapping for inline ${node.type.name}.`;
+				return;
+			default:
+		}
+	});
+	return issue === void 0 ? Result.ok(cells) : refuse(issue);
+};
+const sameSourceMarker = (left, right) => {
+	switch (left.type) {
+		case "bookmarkStart":
+		case "bookmarkEnd":
+		case "commentRangeStart":
+		case "commentRangeEnd":
+		case "moveFromRangeStart":
+		case "moveFromRangeEnd":
+		case "moveToRangeStart":
+		case "moveToRangeEnd": return right.type === left.type && left.id === right.id;
+		case "noteMarker": return right.type === "noteMarker" && left.kind === right.kind;
+		case "preservedInline": return right.type === "preservedInline" && left.xml === right.xml && left.text === right.text;
+		default: return false;
+	}
+};
+/** Bind rendered gaps to the operation owner's source leaf ordinals, including collapsed pairs. */
+const projectCanonicalInline = ({ source, paragraph, pairedBookmarkIds }) => {
+	const native = canonicalNativeCells(paragraph);
+	if (native.isErr()) return native;
+	const spans = inlineLeafSpans(source.content);
+	const erasedBookmarks = /* @__PURE__ */ new Set();
+	const collectErasedBookmarks = (items, context) => {
+		for (const item of items) {
+			if (item.type === "bookmarkStart" || item.type === "bookmarkEnd") {
+				if (context === "paragraph" && !pairedBookmarkIds.has(item.id)) erasedBookmarks.add(item);
+				continue;
+			}
+			if (CANONICAL_SOURCE_INLINE_POLICIES[item.type] !== "container") continue;
+			collectErasedBookmarks(sourceContainerChildren(item), item.type === "run" || item.type === "inlineWrapper" ? context : "nested");
+		}
+	};
+	collectErasedBookmarks(source.content, "paragraph");
+	const text = paragraphLogicalText(source);
+	const boundaries = Array.from({ length: text.length + 1 }, () => []);
+	let index = 0;
+	let consumed = 0;
+	const addGap = (position, gap) => {
+		const gaps = boundaries.at(gap.offset);
+		if (!gaps) panic(`Source leaf offset ${gap.offset} exceeds paragraph ${source.paraId}.`);
+		const existing = gaps.findIndex((entry) => entry.position === position);
+		const entry = {
+			position,
+			zeroWidthBefore: gap.zeroWidthBefore
+		};
+		if (existing < 0) gaps.push(entry);
+		else gaps[existing] = entry;
+	};
+	const consumeErasedLeaves = (position) => {
+		while (consumed === 0) {
+			const span = spans.at(index);
+			if (!span || span.before.offset !== span.after.offset || !(erasedBookmarks.has(span.node) || CANONICAL_SOURCE_INLINE_POLICIES[span.node.type] === "container" && sourceContainerChildren(span.node).length === 0)) break;
+			index += 1;
+			if (position !== null) addGap(position, span.after);
+		}
+	};
+	addGap(0, {
+		offset: 0,
+		zeroWidthBefore: 0
+	});
+	for (const cell of native.value) {
+		consumeErasedLeaves(cell.from);
+		let span = spans.at(index);
+		if (!span) return refuse(`Canonical editing cannot map native ${cell.node.type.name} to a source leaf.`);
+		addGap(cell.from, consumed === 0 ? span.before : {
+			offset: span.before.offset + consumed,
+			zeroWidthBefore: 0
+		});
+		switch (cell.type) {
+			case "zeroWidth":
+				for (const marker of cell.sources) {
+					consumeErasedLeaves(null);
+					span = spans.at(index);
+					if (!span || consumed !== 0 || span.before.offset !== span.after.offset || !sameSourceMarker(span.node, marker)) return refuse(`Canonical editing cannot preserve ${marker.type} source boundary positions.`);
+					index += 1;
+				}
+				if (!span) return refuse("Canonical editing lost a source range boundary.");
+				addGap(cell.to, span.after);
+				break;
+			case "unit":
+			case "markedUnit":
+				if (cell.type === "markedUnit" && (span.node.type !== "footnoteRef" && span.node.type !== "endnoteRef" || span.node.type !== cell.sourceType || String(span.node.id) !== cell.label)) return refuse("Canonical editing cannot preserve note-reference identity.");
+				if (consumed !== 0 || span.node.type === "text" || span.after.offset - span.before.offset !== 1) return refuse(`Canonical editing cannot map ${span.node.type} to one native inline unit.`);
+				index += 1;
+				addGap(cell.to, span.after);
+				break;
+			case "text":
+				for (let unit = 0; unit < cell.text.length; unit += 1) {
+					consumeErasedLeaves(cell.from + unit);
+					span = spans.at(index);
+					if (!span) return refuse("Canonical editing cannot map missing source text to native text positions.");
+					let value;
+					switch (span.node.type) {
+						case "text":
+							value = span.node.text;
+							break;
+						case "softHyphen":
+						case "noBreakHyphen":
+							value = HYPHEN_TEXT_CARRIERS[span.node.type];
+							break;
+						default: return refuse(`Canonical editing cannot map ${span.node.type} to native text positions.`);
+					}
+					if (value.charAt(consumed) !== cell.text.charAt(unit)) return refuse("Canonical editing cannot preserve the source text carrier.");
+					consumed += 1;
+					addGap(cell.from + unit + 1, {
+						offset: span.before.offset + consumed,
+						zeroWidthBefore: 0
+					});
+					if (consumed === value.length) {
+						index += 1;
+						consumed = 0;
+					}
+				}
+				break;
+			default:
+		}
+	}
+	consumeErasedLeaves(paragraph.content.size);
+	const missing = spans.at(index);
+	if (missing || consumed !== 0) return refuse(`Canonical editing cannot display the source positions of ${missing?.node.type ?? "incomplete text"}.`);
+	if (boundaries.some((gaps) => gaps.length === 0)) return refuse("Canonical editing lost a source character boundary.");
+	return Result.ok({
+		text,
+		boundaries
+	});
+};
+//#endregion
+export { CANONICAL_NATIVE_INLINE_POLICIES, CANONICAL_SOURCE_INLINE_POLICIES, canonicalInlineSourceIssue, canonicalNativeCells, projectCanonicalInline };

package/dist/controller/canonicalInput.d.ts

@@ -0,0 +1,54 @@
+import { EditorState, Transaction } from "prosemirror-state";
+import { EditorView } from "prosemirror-view";
+//#region src/controller/canonicalInput.d.ts
+declare const CANONICAL_COMPOSITION_INPUT_TYPES: readonly ["insertCompositionText", "insertFromComposition", "deleteCompositionText", "deleteByComposition"];
+type ReplaceTextInput = {
+  from: number;
+  to: number;
+  text: string;
+} & ({
+  semantic: "composition";
+  compositionPhase?: "correction";
+} | {
+  semantic?: "typing" | "deleteBackward" | "deleteForward";
+  compositionPhase?: never;
+});
+type CanonicalInputOptions = {
+  replace: (input: ReplaceTextInput) => void;
+  structure?: (type: "split" | "joinBackward" | "joinForward" | "lineBreak" | "pageBreak" | "tab" | "indent" | "outdent") => void;
+  command?: (name: "toggleBold" | "toggleItalic" | "toggleUnderline") => void;
+  breakUndoGroup?: () => void;
+  beginComposition?: () => boolean;
+  endComposition?: () => void;
+  pastePlainText?: (view: EditorView) => void;
+  cut?: (view: EditorView, event: ClipboardEvent) => boolean;
+  undo: () => boolean;
+  redo: () => boolean;
+  refuse: (reason: string) => void;
+};
+/** Native changes require a preceding, classified input event at the same state. */
+declare const createCanonicalInputBoundary: (options: CanonicalInputOptions) => {
+  reset: () => void;
+  readonly isComposing: boolean;
+  acceptComposition: (view: EditorView, transaction: Transaction) => boolean;
+  handleTextInput: (view: EditorView, from: number, to: number, text: string) => boolean;
+  handleKeyDown: (view: EditorView, event: KeyboardEvent) => boolean;
+  handleDOMEvents: {
+    keydown: (view: EditorView, event: KeyboardEvent) => boolean;
+    compositionstart: (view: EditorView) => boolean;
+    compositionend: (view: EditorView) => boolean;
+    mousedown: (view: EditorView) => boolean;
+    blur: (view: EditorView) => boolean;
+    beforeinput: (view: EditorView, event: InputEvent) => boolean;
+    input: (view: EditorView) => boolean;
+    paste: (_view: EditorView, event: Event) => boolean;
+    cut: (view: EditorView, event: ClipboardEvent) => boolean;
+    drop: (_view: EditorView, event: Event) => boolean;
+  };
+  /** Returns a classified intent only; the proposed PM document is never authoritative. */
+  takeNativeProposal: (state: EditorState, transaction: Transaction) => ReplaceTextInput | null;
+  refuseNativeMutation: (view: EditorView) => void;
+  commitNativeProposal: (view: EditorView, transaction: Transaction) => boolean;
+};
+//#endregion
+export { CANONICAL_COMPOSITION_INPUT_TYPES, createCanonicalInputBoundary };