@stll/folio-core 0.55.0 → 0.56.0

package/dist/controller/canonicalClipboardResources.js

@@ -0,0 +1,382 @@
+import { visitParagraphRuns } from "../docx/paragraphTraversal.js";
+import { resolveStyleInheritance } from "../docx/styleParser.js";
+import { resolveParagraphBodyRunFormatting } from "../prosemirror/runStyleFormatting.js";
+import { cascadeStyleTextFormatting } from "../prosemirror/styles/styleToggleCascade.js";
+import { createStyleEngine } from "../style-engine/styleEngine.js";
+import { FONT_THEME_VALUES } from "../types/documentEnumValues.js";
+import { isValidHexColor, resolveColorToHex } from "../utils/colorResolver.js";
+import { resolveThemeFont } from "../utils/fontResolver.js";
+import { mergeParagraphFormatting } from "../utils/paragraphFormattingMerge.js";
+import { Result, panic } from "better-result";
+import { BODY_TEXT_OUTLINE_LEVEL, NO_PARAGRAPH_NUMBERING, isThemeColor, themeColorSlot } from "@stll/docx-core/model";
+import { DOCUMENT_OP_REFUSAL_REASONS, DOCUMENT_OP_TYPES, DocumentOpRefusal } from "@stll/docx-core/ops";
+//#region src/controller/canonicalClipboardResources.ts
+const STYLE_REFERENCE_FIELDS = /* @__PURE__ */ new Set([
+	"styleId",
+	"basedOn",
+	"next",
+	"link",
+	"pStyle",
+	"numStyleLink",
+	"styleLink"
+]);
+const visitReferences = (value, visitor) => {
+	if (typeof value !== "object" || value === null) return;
+	if (Array.isArray(value)) {
+		for (const item of value) visitReferences(item, visitor);
+		return;
+	}
+	for (const [key, item] of Object.entries(value)) {
+		if (key === "listRendering") continue;
+		visitor(key, item, value);
+		visitReferences(item, visitor);
+	}
+};
+/** Normalized HTML states effective CSS; foreign style names carry no package ownership. */
+const flattenClipboardStyleReferences = (paragraphs) => {
+	visitReferences(paragraphs, (key, _value, owner) => {
+		if (STYLE_REFERENCE_FIELDS.has(key)) Reflect.deleteProperty(owner, key);
+	});
+};
+const refused = (message) => Result.err(new DocumentOpRefusal({
+	opType: DOCUMENT_OP_TYPES.SET_PACKAGE_RESOURCES,
+	reason: DOCUMENT_OP_REFUSAL_REASONS.STRUCTURE_MISMATCH,
+	message
+}));
+const THEME_FONT_SLOTS = new Map(Object.entries({
+	asciiTheme: "ascii",
+	hAnsiTheme: "hAnsi",
+	eastAsiaTheme: "eastAsia",
+	csTheme: "cs"
+}));
+const THEME_FONT_REFERENCES = new Set(FONT_THEME_VALUES);
+const lowerSourceTheme = ({ value, source }) => {
+	let unavailable;
+	visitReferences(value, (key, item, owner) => {
+		if (unavailable !== void 0) return;
+		const fontSlot = THEME_FONT_SLOTS.get(key);
+		if (fontSlot !== void 0 && typeof item === "string") {
+			const explicit = Reflect.get(owner, fontSlot);
+			const font = (THEME_FONT_REFERENCES.has(item) ? resolveThemeFont(item, source.package.theme?.fontScheme) : null) || (typeof explicit === "string" ? explicit : void 0);
+			if (font === void 0 || font.length === 0) {
+				unavailable = `The source package does not resolve theme font ${item}.`;
+				return;
+			}
+			Reflect.set(owner, fontSlot, font);
+			Reflect.deleteProperty(owner, key);
+			return;
+		}
+		if (key !== "themeColor") return;
+		if (item === "none") return;
+		if (Reflect.get(owner, "auto") === true) {
+			Reflect.deleteProperty(owner, "themeColor");
+			Reflect.deleteProperty(owner, "themeTint");
+			Reflect.deleteProperty(owner, "themeShade");
+			return;
+		}
+		const rgb = Reflect.get(owner, "rgb");
+		const tint = Reflect.get(owner, "themeTint");
+		const shade = Reflect.get(owner, "themeShade");
+		if (typeof item !== "string" || !isThemeColor(item)) {
+			if (typeof rgb !== "string" || !isValidHexColor(rgb)) {
+				unavailable = "A source theme colour has no known slot or explicit RGB value.";
+				return;
+			}
+			Reflect.deleteProperty(owner, "themeColor");
+			Reflect.deleteProperty(owner, "themeTint");
+			Reflect.deleteProperty(owner, "themeShade");
+			return;
+		}
+		const slot = themeColorSlot(item);
+		const schemeColour = slot === void 0 ? void 0 : source.package.theme?.colorScheme?.[slot];
+		if (schemeColour === void 0 || !isValidHexColor(schemeColour)) {
+			unavailable = `The source package does not resolve theme colour ${item}.`;
+			return;
+		}
+		const resolved = resolveColorToHex({
+			themeColor: item,
+			...typeof rgb === "string" ? { rgb } : {},
+			...typeof tint === "string" ? { themeTint: tint } : {},
+			...typeof shade === "string" ? { themeShade: shade } : {}
+		}, source.package.theme);
+		if (resolved === void 0) {
+			unavailable = `The source package does not resolve theme colour ${item}.`;
+			return;
+		}
+		Reflect.set(owner, "rgb", resolved);
+		Reflect.deleteProperty(owner, "themeColor");
+		Reflect.deleteProperty(owner, "themeTint");
+		Reflect.deleteProperty(owner, "themeShade");
+	});
+	return unavailable === void 0 ? Result.ok(void 0) : refused(unavailable);
+};
+const NEUTRAL_PARAGRAPH_PROPERTIES = {
+	bidi: false,
+	keepNext: false,
+	keepLines: false,
+	widowControl: true,
+	pageBreakBefore: false,
+	contextualSpacing: false,
+	beforeAutospacing: false,
+	afterAutospacing: false,
+	hangingIndent: false,
+	suppressLineNumbers: false,
+	suppressAutoHyphens: false,
+	runInWithNext: false,
+	alignment: "start",
+	indentLeft: 0,
+	indentRight: 0,
+	indentFirstLine: 0,
+	outlineLevel: BODY_TEXT_OUTLINE_LEVEL,
+	numPr: NO_PARAGRAPH_NUMBERING,
+	tabs: [],
+	spaceBefore: 0,
+	spaceAfter: 0,
+	lineSpacing: 240,
+	lineSpacingRule: "auto"
+};
+const NEUTRAL_RUN_PROPERTIES = {
+	color: { auto: true },
+	highlight: "none",
+	underline: { style: "none" },
+	spacing: 0,
+	position: 0,
+	kerning: 0,
+	vertAlign: "baseline"
+};
+const materializeClipboardDefaults = ({ source, destination, paragraphs }) => {
+	const sourceDefinitions = structuredClone(source.package.styles);
+	if (sourceDefinitions !== void 0) {
+		const sourceMap = new Map(sourceDefinitions.styles.map((style) => [style.styleId, style]));
+		sourceDefinitions.styles = sourceDefinitions.styles.map((style) => resolveStyleInheritance(style, sourceMap));
+	}
+	const engine = createStyleEngine(sourceDefinitions);
+	const destinationDefaults = createStyleEngine(destination.package.styles).resolveParagraphStyle(void 0);
+	const neutralizeBooleanDefaults = (formatting, defaults) => {
+		for (const [key, value] of Object.entries(defaults ?? {})) if (typeof value === "boolean" && Reflect.get(formatting, key) === void 0) Reflect.set(formatting, key, false);
+	};
+	let unavailable;
+	const recordRefusal = (message) => {
+		unavailable ??= message;
+	};
+	for (const paragraph of paragraphs) {
+		const authored = paragraph.formatting;
+		const implicitStyle = engine.getDefaultParagraphStyle();
+		const styleId = authored?.styleId ?? implicitStyle?.styleId;
+		const resolved = engine.resolveParagraphStyle(styleId);
+		const formatting = mergeParagraphFormatting(resolved.paragraphFormatting, authored) ?? (destinationDefaults.paragraphFormatting === void 0 ? void 0 : {});
+		if (formatting !== void 0) {
+			if (authored?.numPr === void 0 && sourceDefinitions?.docDefaults?.pPr?.numPr === void 0) delete formatting.numPr;
+			if (authored?.numPrFromStyle === void 0) delete formatting.numPrFromStyle;
+			if (authored?.preserved !== void 0) formatting.preserved = authored.preserved;
+			for (const [key, value] of Object.entries(destinationDefaults.paragraphFormatting ?? {})) {
+				if (key === "preserved" || key === "styleId" || key === "runProperties" || key === "spacingExplicit" || value === void 0 || Reflect.get(formatting, key) !== void 0 || Reflect.get(resolved.paragraphFormatting ?? {}, key) !== void 0) continue;
+				const neutral = Reflect.get(NEUTRAL_PARAGRAPH_PROPERTIES, key);
+				if (neutral === void 0) {
+					recordRefusal(`The source package does not resolve inherited paragraph property ${key}.`);
+					continue;
+				}
+				Reflect.set(formatting, key, structuredClone(neutral));
+			}
+			if (authored?.styleId === void 0 && implicitStyle !== void 0 && engine.hasStyle(implicitStyle.styleId)) formatting.styleId = implicitStyle.styleId;
+			paragraph.formatting = formatting;
+		}
+		const inherited = resolveParagraphBodyRunFormatting({
+			styleId,
+			styleResolver: engine
+		});
+		const materializeRun = (direct) => {
+			const named = direct?.styleId;
+			const cascade = cascadeStyleTextFormatting([
+				{
+					cascade: named === void 0 ? inherited.defaultToggleCascade : inherited.baseToggleCascade,
+					type: "carried"
+				},
+				{
+					formatting: named === void 0 ? void 0 : engine.getRunStyleOwnProperties(named),
+					type: "style"
+				},
+				{
+					formatting: direct,
+					type: "direct"
+				}
+			]).formatting ?? {};
+			neutralizeBooleanDefaults(cascade, destinationDefaults.runFormatting);
+			const themeLowered = lowerSourceTheme({
+				value: cascade,
+				source
+			});
+			if (themeLowered.isErr()) recordRefusal(themeLowered.error.message);
+			for (const [slot, value] of Object.entries(destinationDefaults.runFormatting?.fontFamily ?? {})) {
+				const concreteSlot = THEME_FONT_SLOTS.get(slot) ?? slot;
+				if (value === void 0 || Reflect.get(cascade.fontFamily ?? {}, concreteSlot) !== void 0) continue;
+				if (slot === "hint") {
+					cascade.fontFamily = {
+						...cascade.fontFamily,
+						hint: "default"
+					};
+					continue;
+				}
+				recordRefusal(`The source package does not resolve inherited font slot ${slot}.`);
+			}
+			for (const [key, value] of Object.entries(destinationDefaults.runFormatting ?? {})) {
+				if (key === "preserved" || key === "styleId" || value === void 0 || Reflect.get(cascade, key) !== void 0) continue;
+				const neutral = Reflect.get(NEUTRAL_RUN_PROPERTIES, key);
+				if (neutral === void 0) {
+					recordRefusal(`The source package does not resolve inherited run property ${key}.`);
+					continue;
+				}
+				Reflect.set(cascade, key, structuredClone(neutral));
+			}
+			if (direct?.preserved !== void 0) cascade.preserved = direct.preserved;
+			return cascade;
+		};
+		visitParagraphRuns(paragraph, (run) => {
+			const runFormatting = materializeRun(run.formatting);
+			if (runFormatting !== void 0) run.formatting = runFormatting;
+			for (const change of run.propertyChanges ?? []) {
+				const previous = materializeRun(change.previousFormatting);
+				const current = materializeRun(change.currentFormatting);
+				if (previous !== void 0) change.previousFormatting = previous;
+				if (current !== void 0 && Object.hasOwn(change, "currentFormatting")) change.currentFormatting = current;
+			}
+		});
+		for (const change of paragraph.propertyChanges ?? []) {
+			const previous = change.previousFormatting;
+			const before = mergeParagraphFormatting(engine.resolveParagraphStyle(previous?.styleId).paragraphFormatting, previous);
+			if (before !== void 0) {
+				if (previous?.numPr === void 0) delete before.numPr;
+				if (previous?.preserved !== void 0) before.preserved = previous.preserved;
+				change.previousFormatting = before;
+			}
+		}
+		if (paragraph.content.length === 0) {
+			const markFormatting = materializeRun(paragraph.formatting?.runProperties);
+			if (markFormatting !== void 0) paragraph.formatting = {
+				...paragraph.formatting,
+				runProperties: markFormatting
+			};
+		}
+	}
+	return unavailable === void 0 ? Result.ok(void 0) : refused(unavailable);
+};
+/** Import the transitive style/numbering dependencies of the clipboard, retaining destination defaults. */
+const importClipboardStyles = ({ destination, source, paragraphs }) => {
+	const clonedParagraphs = structuredClone([...paragraphs]);
+	const materialized = materializeClipboardDefaults({
+		source,
+		destination,
+		paragraphs: clonedParagraphs
+	});
+	if (materialized.isErr()) return materialized;
+	const sourceStyles = /* @__PURE__ */ new Map();
+	for (const style of source.package.styles?.styles ?? []) {
+		if (sourceStyles.has(style.styleId)) return refused("The source package contains duplicate style identities.");
+		sourceStyles.set(style.styleId, style);
+	}
+	const styleQueue = [];
+	const numberingQueue = [];
+	const selectedStyles = /* @__PURE__ */ new Set();
+	const numberingIds = /* @__PURE__ */ new Set();
+	const selectReferences = (key, value) => {
+		if (STYLE_REFERENCE_FIELDS.has(key) && typeof value === "string" && !selectedStyles.has(value)) {
+			selectedStyles.add(value);
+			styleQueue.push(value);
+		}
+		if (key === "numId" && typeof value === "number" && !numberingIds.has(value)) {
+			numberingIds.add(value);
+			numberingQueue.push(value);
+		}
+	};
+	for (const paragraph of clonedParagraphs) visitReferences(paragraph, selectReferences);
+	const sourceNums = source.package.numbering?.nums ?? [];
+	const sourceAbstracts = source.package.numbering?.abstractNums ?? [];
+	const nums = new Map(sourceNums.map((num) => [num.numId, num]));
+	const abstracts = new Map(sourceAbstracts.map((abstract) => [abstract.abstractNumId, abstract]));
+	if (nums.size !== sourceNums.length || abstracts.size !== sourceAbstracts.length) return refused("The source package contains duplicate numbering identities.");
+	let styleIndex = 0;
+	let numberingIndex = 0;
+	while (styleIndex < styleQueue.length || numberingIndex < numberingQueue.length) {
+		while (styleIndex < styleQueue.length) {
+			const id = styleQueue.at(styleIndex++);
+			if (id === void 0) return refused("A clipboard style dependency was lost.");
+			const style = sourceStyles.get(id);
+			if (style === void 0) return refused(`The source package does not define clipboard style ${id}.`);
+			visitReferences(style, selectReferences);
+		}
+		while (numberingIndex < numberingQueue.length) {
+			const id = numberingQueue.at(numberingIndex++);
+			if (id === void 0) return refused("A clipboard numbering dependency was lost.");
+			const num = nums.get(id);
+			if (num === void 0) return refused(`The source package does not define clipboard numbering ${id}.`);
+			const abstract = abstracts.get(num.abstractNumId);
+			if (abstract === void 0) return refused("A clipboard numbering instance has no abstract definition.");
+			visitReferences(num, selectReferences);
+			visitReferences(abstract, selectReferences);
+		}
+	}
+	for (const id of selectedStyles) {
+		const ancestors = /* @__PURE__ */ new Set();
+		let ancestor = id;
+		while (ancestor !== void 0) {
+			if (ancestors.has(ancestor)) return refused("The source clipboard style inheritance contains a cycle.");
+			ancestors.add(ancestor);
+			ancestor = sourceStyles.get(ancestor)?.basedOn;
+		}
+	}
+	const occupied = new Set(destination.package.styles?.styles.map(({ styleId }) => styleId));
+	const reserved = /* @__PURE__ */ new Set([...occupied, ...selectedStyles]);
+	const styleIds = /* @__PURE__ */ new Map();
+	for (const id of [...selectedStyles].toSorted()) {
+		if (!occupied.has(id)) {
+			styleIds.set(id, id);
+			continue;
+		}
+		let ordinal = 1;
+		let importedId = `${id}_clipboard${ordinal}`;
+		while (reserved.has(importedId)) importedId = `${id}_clipboard${++ordinal}`;
+		reserved.add(importedId);
+		styleIds.set(id, importedId);
+	}
+	const remap = (key, value, owner) => {
+		if (!STYLE_REFERENCE_FIELDS.has(key) || typeof value !== "string") return;
+		const mapped = styleIds.get(value);
+		if (mapped === void 0) panic("A selected clipboard style has no allocated destination identity.");
+		Reflect.set(owner, key, mapped);
+	};
+	const importedStyles = [];
+	for (const id of [...selectedStyles].toSorted()) {
+		const style = sourceStyles.get(id);
+		if (style === void 0) return refused("A selected clipboard style has no source definition.");
+		const imported = structuredClone(style);
+		visitReferences(imported, remap);
+		const lowered = lowerSourceTheme({
+			value: imported,
+			source
+		});
+		if (lowered.isErr()) return lowered;
+		if (imported.default === true) delete imported.default;
+		importedStyles.push(imported);
+	}
+	for (const paragraph of clonedParagraphs) {
+		visitReferences(paragraph, remap);
+		const lowered = lowerSourceTheme({
+			value: paragraph,
+			source
+		});
+		if (lowered.isErr()) return lowered;
+	}
+	const prior = destination.package.styles;
+	const styles = importedStyles.length === 0 ? prior : {
+		...prior,
+		styles: [...prior?.styles ?? [], ...importedStyles]
+	};
+	return Result.ok({
+		styles,
+		paragraphs: clonedParagraphs,
+		styleIds,
+		numberingIds
+	});
+};
+//#endregion
+export { flattenClipboardStyleReferences, importClipboardStyles };

package/dist/controller/canonicalComposition.d.ts

@@ -9,15 +9,29 @@ type CompositionOptions = {
     to: number;
     text: string;
     semantic: "composition";
+    compositionPhase?: "correction";
   }) => void;
   refuse: (reason: string) => void;
 };
 type CompositionState = {
   type: "committed";
 } | {
-  type: "provisional" | "refused";
+  type: "provisional";
   baseline: EditorState;
+  view: EditorView;
   phase: "active" | "ended";
+} | {
+  type: "refused";
+  baseline: EditorState;
+  view: EditorView;
+  phase: "active" | "ended";
+  text: string | null;
+};
+type CompositionFinish = {
+  type: "idle" | "cancelled";
+} | {
+  type: "committed" | "refused";
+  text: string | null;
 };
 /** Native IME owns the provisional view; the captured canonical projection stays unchanged. */
 declare const createCanonicalComposition: (options: CompositionOptions) => {
@@ -25,10 +39,13 @@ declare const createCanonicalComposition: (options: CompositionOptions) => {
   readonly active: boolean;
   start: (view: EditorView) => void;
   ended: (view: EditorView) => void;
+  forgetCompleted: () => void;
+  readonly pendingFinal: boolean;
+  authorizeLateFinal: (view: EditorView, text: string | null) => boolean;
   authorizeNative: (view: EditorView) => void;
   flushed: (view: EditorView) => void;
-  recover: (view: EditorView) => void;
-  cancel: (view: EditorView) => void;
+  recover: (view: EditorView) => CompositionFinish;
+  cancel: (view: EditorView) => CompositionFinish;
   reset: () => void;
   accept: (view: EditorView, transaction: Transaction) => boolean;
 };