@stll/folio-core 0.54.2 → 0.56.0

package/dist/controller/canonicalInput.js

@@ -0,0 +1,377 @@
+import { handleEditorBeforeInput } from "../prosemirror/textInput.js";
+import { createCanonicalComposition } from "./canonicalComposition.js";
+import { deletionRange, isCanonicalJoinBoundary } from "./canonicalSession.js";
+import { ReplaceStep } from "prosemirror-transform";
+import { Selection, TextSelection } from "prosemirror-state";
+//#region src/controller/canonicalInput.ts
+const CANONICAL_COMPOSITION_INPUT_TYPES = [
+	"insertCompositionText",
+	"insertFromComposition",
+	"deleteCompositionText",
+	"deleteByComposition"
+];
+/** Native changes require a preceding, classified input event at the same state. */
+const createCanonicalInputBoundary = (options) => {
+	const composition = createCanonicalComposition({
+		begin: () => options.beginComposition?.() ?? true,
+		end: () => options.endComposition?.(),
+		replace: options.replace,
+		refuse: options.refuse
+	});
+	let proposal = { type: "idle" };
+	let authorizedInput = null;
+	let groupClosed = false;
+	const beginGesture = (lifecycle = "new") => {
+		if (lifecycle === "new") composition.forgetCompleted();
+		proposal = { type: "idle" };
+		authorizedInput = null;
+		groupClosed = false;
+	};
+	const closeGroup = () => {
+		if (groupClosed) return;
+		groupClosed = true;
+		options.breakUndoGroup?.();
+	};
+	const repaint = (view) => {
+		queueMicrotask(() => {
+			if (!view.isDestroyed) view.updateState(view.state);
+		});
+	};
+	const refuseEvent = (event, reason) => {
+		event.preventDefault();
+		closeGroup();
+		if (!composition.active && proposal.type !== "refused") options.refuse(reason);
+		if (!composition.active) proposal = { type: "refused" };
+		return true;
+	};
+	const refuseClipboardGesture = (event, reason) => {
+		event.preventDefault();
+		closeGroup();
+		options.refuse(reason);
+		return true;
+	};
+	const refuseNativeMutation = (view) => {
+		if (!composition.active && proposal.type !== "refused") {
+			options.refuse("Unclassified native text is unavailable in this session.");
+			proposal = { type: "refused" };
+		}
+		repaint(view);
+	};
+	const takeNativeProposal = (state, transaction) => {
+		const pending = proposal;
+		if (pending.type !== "replacement") return null;
+		proposal = { type: "idle" };
+		if (pending.state !== state || transaction.steps.length !== 1) return null;
+		const step = transaction.steps.at(0);
+		if (!(step instanceof ReplaceStep) || "structure" in step && step.structure === true || step.from !== pending.input.from || step.to !== pending.input.to) return null;
+		if (step.slice.openStart !== 0 || step.slice.openEnd !== 0) return null;
+		let text = "";
+		let plain = true;
+		step.slice.content.forEach((node) => {
+			if (!node.isText) plain = false;
+			text += node.text ?? "";
+		});
+		if (!plain || text !== pending.input.text) return null;
+		return state.tr.insertText(text, step.from, step.to).doc.eq(transaction.doc) ? pending.input : null;
+	};
+	return {
+		reset: () => {
+			proposal = { type: "idle" };
+			authorizedInput = null;
+			composition.reset();
+		},
+		get isComposing() {
+			return composition.active;
+		},
+		acceptComposition: composition.accept,
+		handleTextInput: (view, from, to, text) => {
+			if (composition.active || composition.pendingFinal) return false;
+			const pending = proposal;
+			if (authorizedInput?.view === view && authorizedInput.state === view.state) {
+				options.replace({
+					from,
+					to,
+					text,
+					semantic: "typing"
+				});
+				return true;
+			}
+			if (pending.type === "replacement" && pending.state === view.state && pending.input.from === from && pending.input.to === to && pending.input.text === text) {
+				proposal = { type: "idle" };
+				options.replace(pending.input);
+				return true;
+			}
+			refuseNativeMutation(view);
+			return true;
+		},
+		handleKeyDown: (view, event) => {
+			if (event.isComposing || event.keyCode === 229) return false;
+			beginGesture();
+			if (composition.active) {
+				if (event.key === "Escape") {
+					event.preventDefault();
+					composition.cancel(view);
+					return true;
+				}
+				if (event.metaKey || event.ctrlKey) {
+					event.preventDefault();
+					return true;
+				}
+				return false;
+			}
+			const modifier = event.metaKey || event.ctrlKey;
+			if (modifier || event.altKey || /^(?:Arrow|Home$|End$|Page|Escape$|Tab$)/u.test(event.key)) closeGroup();
+			if (modifier && event.key.toLowerCase() === "z") {
+				event.preventDefault();
+				if (event.shiftKey) options.redo();
+				else options.undo();
+				return true;
+			}
+			if (modifier && event.key.toLowerCase() === "y") {
+				event.preventDefault();
+				options.redo();
+				return true;
+			}
+			if (modifier && event.key.toLowerCase() === "a") {
+				event.preventDefault();
+				view.dispatch(view.state.tr.setSelection(TextSelection.create(view.state.doc, Selection.atStart(view.state.doc).from, Selection.atEnd(view.state.doc).to)));
+				return true;
+			}
+			if (modifier && (event.key.toLowerCase() === "b" || event.key.toLowerCase() === "i" || event.key.toLowerCase() === "u") && options.command !== void 0) {
+				event.preventDefault();
+				switch (event.key.toLowerCase()) {
+					case "b":
+						options.command("toggleBold");
+						break;
+					case "i":
+						options.command("toggleItalic");
+						break;
+					case "u":
+						options.command("toggleUnderline");
+						break;
+				}
+				return true;
+			}
+			if (modifier && event.altKey && event.key.toLowerCase() === "v" && options.pastePlainText) {
+				event.preventDefault();
+				closeGroup();
+				options.pastePlainText(view);
+				return true;
+			}
+			if (event.key === "Enter") {
+				if (view.composing) return refuseEvent(event, "Paragraph structure edits are unavailable during composition.");
+				event.preventDefault();
+				closeGroup();
+				if (options.structure === void 0) return refuseEvent(event, "Paragraph structure edits are unavailable in this session.");
+				if (modifier) options.structure("pageBreak");
+				else options.structure(event.shiftKey ? "lineBreak" : "split");
+				return true;
+			}
+			if (event.key === "Tab" && !modifier && !event.altKey && options.structure !== void 0) {
+				event.preventDefault();
+				if (view.state.selection.$from.parent.attrs["numPr"]?.kind === "reference") options.structure(event.shiftKey ? "outdent" : "indent");
+				else if (!event.shiftKey) options.structure("tab");
+				return true;
+			}
+			if (event.key !== "Backspace" && event.key !== "Delete") return false;
+			event.preventDefault();
+			if (modifier || event.altKey || view.composing || composition.active) {
+				closeGroup();
+				if (!composition.active) options.refuse("Only plain character deletion is available in this session.");
+				return true;
+			}
+			if (view.state.selection.empty && options.structure !== void 0 && isCanonicalJoinBoundary(view.state, event.key === "Backspace" ? "backward" : "forward")) {
+				closeGroup();
+				options.structure(event.key === "Backspace" ? "joinBackward" : "joinForward");
+				return true;
+			}
+			const range = deletionRange(view.state, event.key === "Backspace" ? "backward" : "forward");
+			if (range.isErr()) {
+				closeGroup();
+				options.refuse(range.error.message);
+			} else options.replace({
+				...range.value,
+				text: "",
+				semantic: event.key === "Backspace" ? "deleteBackward" : "deleteForward"
+			});
+			return true;
+		},
+		handleDOMEvents: {
+			keydown: (view, event) => {
+				if (event.isComposing || event.keyCode === 229) return true;
+				if (!composition.active || event.key !== "Escape") return false;
+				event.preventDefault();
+				composition.cancel(view);
+				return true;
+			},
+			compositionstart: (view) => {
+				beginGesture();
+				composition.start(view);
+				return false;
+			},
+			compositionend: (view) => {
+				composition.ended(view);
+				return false;
+			},
+			mousedown: (view) => {
+				composition.recover(view);
+				beginGesture();
+				closeGroup();
+				return false;
+			},
+			blur: (view) => {
+				composition.recover(view);
+				beginGesture();
+				closeGroup();
+				repaint(view);
+				return false;
+			},
+			beforeinput: (view, event) => {
+				beginGesture(event.inputType === "insertFromComposition" ? "compositionFinal" : "new");
+				if (event.isComposing || CANONICAL_COMPOSITION_INPUT_TYPES.some((inputType) => inputType === event.inputType)) {
+					if (composition.active) {
+						composition.authorizeNative(view);
+						return false;
+					}
+					if (event.inputType === "insertFromComposition" && composition.authorizeLateFinal(view, event.data)) return false;
+					return refuseEvent(event, "Composition has no captured canonical baseline.");
+				}
+				if (composition.active) {
+					const nativeFinal = view.composing && (event.inputType === "insertText" || event.inputType === "insertReplacementText");
+					const nativeStillComposing = view.composing;
+					const recovered = composition.recover(view);
+					composition.forgetCompleted();
+					proposal = { type: "idle" };
+					if (nativeFinal && (recovered.type === "refused" && nativeStillComposing || (recovered.type === "committed" || recovered.type === "refused") && recovered.text !== null && recovered.text === event.data)) {
+						event.preventDefault();
+						return true;
+					}
+				}
+				if (event.inputType === "insertText" || event.inputType === "insertReplacementText") {
+					if (event.cancelable) {
+						if (view.composing && event.inputType === "insertText" && event.data !== null) {
+							event.preventDefault();
+							proposal = { type: "idle" };
+							options.replace({
+								from: view.state.selection.from,
+								to: view.state.selection.to,
+								text: event.data,
+								semantic: "typing"
+							});
+							return true;
+						}
+						proposal = { type: "idle" };
+						authorizedInput = {
+							view,
+							state: view.state
+						};
+						try {
+							if (handleEditorBeforeInput(view, event)) return true;
+							return refuseEvent(event, "This native replacement cannot be addressed safely.");
+						} finally {
+							authorizedInput = null;
+						}
+					}
+					if (event.inputType !== "insertText" || event.data === null) return refuseEvent(event, "This native replacement cannot be addressed safely.");
+					proposal = {
+						type: "replacement",
+						state: view.state,
+						input: {
+							from: view.state.selection.from,
+							to: view.state.selection.to,
+							text: event.data,
+							semantic: "typing"
+						}
+					};
+					return false;
+				}
+				if ((event.inputType === "insertParagraph" || event.inputType === "insertLineBreak") && event.cancelable && options.structure !== void 0) {
+					event.preventDefault();
+					closeGroup();
+					options.structure(event.inputType === "insertParagraph" ? "split" : "lineBreak");
+					return true;
+				}
+				if (event.inputType === "deleteContentBackward" || event.inputType === "deleteContentForward") {
+					const selection = view.state.selection;
+					const backward = event.inputType === "deleteContentBackward";
+					if (event.cancelable && selection.empty && options.structure !== void 0 && isCanonicalJoinBoundary(view.state, backward ? "backward" : "forward")) {
+						event.preventDefault();
+						closeGroup();
+						options.structure(backward ? "joinBackward" : "joinForward");
+						return true;
+					}
+					const range = deletionRange(view.state, event.inputType === "deleteContentBackward" ? "backward" : "forward");
+					if (range.isErr()) return refuseEvent(event, range.error.message);
+					const input = {
+						...range.value,
+						text: "",
+						semantic: event.inputType === "deleteContentBackward" ? "deleteBackward" : "deleteForward"
+					};
+					if (event.cancelable) {
+						event.preventDefault();
+						options.replace(input);
+						return true;
+					}
+					proposal = {
+						type: "replacement",
+						state: view.state,
+						input
+					};
+					return false;
+				}
+				if (event.inputType === "historyUndo" || event.inputType === "historyRedo") {
+					event.preventDefault();
+					if (event.inputType === "historyUndo") options.undo();
+					else options.redo();
+					return true;
+				}
+				return refuseEvent(event, `Input ${event.inputType} is unavailable in this session.`);
+			},
+			input: (view) => {
+				if (composition.active || composition.pendingFinal) {
+					composition.flushed(view);
+					return false;
+				}
+				const pending = proposal;
+				queueMicrotask(() => {
+					if (view.isDestroyed) return;
+					view.updateState(view.state);
+					if (proposal === pending && !composition.active) proposal = { type: "idle" };
+				});
+				return false;
+			},
+			paste: (_view, event) => {
+				beginGesture();
+				closeGroup();
+				if (composition.active) return refuseClipboardGesture(event, "Composition must finish before pasting.");
+				return false;
+			},
+			cut: (view, event) => {
+				beginGesture();
+				if (composition.active) return refuseClipboardGesture(event, "Composition must finish before cutting.");
+				if (options.cut !== void 0) {
+					closeGroup();
+					return options.cut(view, event);
+				}
+				return refuseEvent(event, "The canonical clipboard owner is unavailable.");
+			},
+			drop: (_view, event) => {
+				beginGesture();
+				closeGroup();
+				if (composition.active) return refuseClipboardGesture(event, "Composition must finish before dropping.");
+				return false;
+			}
+		},
+		/** Returns a classified intent only; the proposed PM document is never authoritative. */
+		takeNativeProposal,
+		refuseNativeMutation,
+		commitNativeProposal: (view, transaction) => {
+			const input = takeNativeProposal(view.state, transaction);
+			if (!input) return false;
+			options.replace(input);
+			return true;
+		}
+	};
+};
+//#endregion
+export { CANONICAL_COMPOSITION_INPUT_TYPES, createCanonicalInputBoundary };

package/dist/controller/canonicalInputTimer.d.ts

@@ -0,0 +1,7 @@
+//#region src/controller/canonicalInputTimer.d.ts
+/** Shared by timer producers and browser diagnostics, regardless of bundling. */
+declare const CANONICAL_INPUT_TIMER_OWNER = "folio.canonical-input-timer";
+/** Mark the scheduled wrapper, never the caller's potentially shared callback. */
+declare const setCanonicalInputTimer: (callback: () => void, delay: number) => NodeJS.Timeout;
+//#endregion
+export { CANONICAL_INPUT_TIMER_OWNER, setCanonicalInputTimer };

package/dist/controller/canonicalInputTimer.js

@@ -0,0 +1,11 @@
+//#region src/controller/canonicalInputTimer.ts
+/** Shared by timer producers and browser diagnostics, regardless of bundling. */
+const CANONICAL_INPUT_TIMER_OWNER = "folio.canonical-input-timer";
+/** Mark the scheduled wrapper, never the caller's potentially shared callback. */
+const setCanonicalInputTimer = (callback, delay) => {
+	const ownedCallback = () => callback();
+	Object.defineProperty(ownedCallback, Symbol.for(CANONICAL_INPUT_TIMER_OWNER), { value: true });
+	return setTimeout(ownedCallback, delay);
+};
+//#endregion
+export { CANONICAL_INPUT_TIMER_OWNER, setCanonicalInputTimer };

package/dist/controller/canonicalOperations.d.ts

@@ -0,0 +1,22 @@
+import { document_d_exports } from "../types/document.js";
+import { CreateHeaderFooterOp, DOCUMENT_OP_TYPES, DocumentOp, FormattingPatch, FormattingPatch as FormattingPatch$1, OpStory, RemoveHeaderFooterOp, SetSectionPropsOp, TextPosition } from "@stll/docx-core/ops";
+//#region src/controller/canonicalOperations.d.ts
+declare const canonicalFinalSectionIndex: (document: document_d_exports.Document) => number;
+declare const withCanonicalParagraphIds: (content: document_d_exports.BlockContent[], document: document_d_exports.Document) => document_d_exports.BlockContent[];
+type CreateCanonicalHeaderFooterOptions = {
+  document: document_d_exports.Document;
+  position: "header" | "footer";
+  referenceType: document_d_exports.HeaderFooterType;
+  sectionIndex?: number;
+};
+declare const createCanonicalHeaderFooterOperation: ({ document, position, referenceType, sectionIndex }: CreateCanonicalHeaderFooterOptions) => CreateHeaderFooterOp;
+type RemoveCanonicalHeaderFooterOptions = {
+  document: document_d_exports.Document;
+  position: "header" | "footer";
+  rId: string;
+};
+/** Remove each explicit binding, leaving inherited sections to inherit the remaining parts. */
+declare const removeCanonicalHeaderFooterOperations: ({ document, position, rId }: RemoveCanonicalHeaderFooterOptions) => RemoveHeaderFooterOp[];
+declare const createCanonicalSectionPropertiesOperation: (document: document_d_exports.Document, patch: FormattingPatch$1<document_d_exports.SectionProperties>) => SetSectionPropsOp;
+//#endregion
+export { DOCUMENT_OP_TYPES, type DocumentOp, type FormattingPatch, type OpStory, type TextPosition, canonicalFinalSectionIndex, createCanonicalHeaderFooterOperation, createCanonicalSectionPropertiesOperation, removeCanonicalHeaderFooterOperations, withCanonicalParagraphIds };

package/dist/controller/canonicalOperations.js

@@ -0,0 +1,85 @@
+import { visitDocxParagraphs } from "../docx/paragraphTraversal.js";
+import { generateHexId, isValidHexId } from "../utils/hexId.js";
+import { DOCUMENT_OP_TYPES, DOCUMENT_OP_TYPES as DOCUMENT_OP_TYPES$1 } from "@stll/docx-core/ops";
+//#region src/controller/canonicalOperations.ts
+/** Adapter command boundaries allocate identities; journaled operations remain deterministic. */
+const canonicalFinalSectionIndex = (document) => document.package.document.content.filter((block) => block.type === "paragraph" && block.sectionProperties !== void 0).length;
+const withCanonicalParagraphIds = (content, document) => {
+	const taken = /* @__PURE__ */ new Set();
+	const { document: documentBody, headers, footers, footnotes, endnotes } = document.package;
+	visitDocxParagraphs({
+		documentBody,
+		headers,
+		footers,
+		footnotes,
+		endnotes
+	}, (paragraph) => {
+		if (paragraph.paraId) taken.add(paragraph.paraId.toUpperCase());
+	});
+	const owned = structuredClone(content);
+	visitDocxParagraphs({ documentBody: { content: owned } }, (paragraph) => {
+		if (paragraph.paraId && isValidHexId(paragraph.paraId) && Number.parseInt(paragraph.paraId, 16) > 0 && Number.parseInt(paragraph.paraId, 16) < 2147483647 && !taken.has(paragraph.paraId.toUpperCase())) {
+			taken.add(paragraph.paraId.toUpperCase());
+			return;
+		}
+		let paraId = generateHexId();
+		while (taken.has(paraId)) paraId = generateHexId();
+		taken.add(paraId);
+		paragraph.paraId = paraId;
+	});
+	return owned;
+};
+const createCanonicalHeaderFooterOperation = ({ document, position, referenceType, sectionIndex = canonicalFinalSectionIndex(document) }) => {
+	const occupied = /* @__PURE__ */ new Set([
+		...document.package.headers?.keys() ?? [],
+		...document.package.footers?.keys() ?? [],
+		...document.package.relationships?.keys() ?? []
+	]);
+	const base = `rId_new_${position}_${referenceType}`;
+	let rId = base;
+	let suffix = 2;
+	while (occupied.has(rId)) rId = `${base}_${suffix++}`;
+	return {
+		type: DOCUMENT_OP_TYPES$1.CREATE_HEADER_FOOTER,
+		sectionIndex,
+		story: {
+			kind: position,
+			rId
+		},
+		referenceType,
+		content: withCanonicalParagraphIds([{
+			type: "paragraph",
+			content: []
+		}], document)
+	};
+};
+/** Remove each explicit binding, leaving inherited sections to inherit the remaining parts. */
+const removeCanonicalHeaderFooterOperations = ({ document, position, rId }) => {
+	const properties = [];
+	for (const block of document.package.document.content) if (block.type === "paragraph" && block.sectionProperties) properties.push(block.sectionProperties);
+	properties.push(document.package.document.finalSectionProperties ?? {});
+	const operations = [];
+	for (const [sectionIndex, section] of properties.entries()) {
+		const references = position === "header" ? section.headerReferences : section.footerReferences;
+		for (const reference of references ?? []) {
+			if (reference.rId !== rId) continue;
+			operations.push({
+				type: DOCUMENT_OP_TYPES$1.REMOVE_HEADER_FOOTER,
+				sectionIndex,
+				story: {
+					kind: position,
+					rId
+				},
+				referenceType: reference.type
+			});
+		}
+	}
+	return operations;
+};
+const createCanonicalSectionPropertiesOperation = (document, patch) => ({
+	type: DOCUMENT_OP_TYPES$1.SET_SECTION_PROPS,
+	sectionIndex: canonicalFinalSectionIndex(document),
+	patch
+});
+//#endregion
+export { DOCUMENT_OP_TYPES, canonicalFinalSectionIndex, createCanonicalHeaderFooterOperation, createCanonicalSectionPropertiesOperation, removeCanonicalHeaderFooterOperations, withCanonicalParagraphIds };

package/dist/controller/canonicalPublicOperations.d.ts

@@ -0,0 +1,48 @@
+import { ApplyFolioDocumentOperationsOptions, FolioDocumentOperationResult, FolioDocumentOperationUndoHandle, FolioDocumentOperationUndoResult } from "../document-operations.js";
+import { CanonicalCommit, CanonicalSession } from "./canonicalSession.js";
+import { EditorState } from "prosemirror-state";
+import { OpStory } from "@stll/docx-core/ops";
+//#region src/controller/canonicalPublicOperations.d.ts
+/** A new public kind cannot bypass a canonical compiler/refusal decision. */
+declare const CANONICAL_PUBLIC_OPERATION_DISPOSITIONS: {
+  readonly replaceInBlock: "compile";
+  readonly replaceRange: "compile";
+  readonly replaceBlock: "compile";
+  readonly splitBlock: "compile";
+  readonly formatRange: "compile";
+  readonly mergeBlockWithNext: "compile";
+  readonly setBlockParagraphProperties: "publicOps.unsupportedInline";
+  readonly insertAfterBlock: "publicOps.unsupportedInline";
+  readonly insertBeforeBlock: "publicOps.unsupportedInline";
+  readonly deleteBlock: "publicOps.unsupportedInline";
+  readonly commentOnBlock: "publicOps.comments";
+  readonly commentOnRange: "publicOps.comments";
+  readonly insertTable: "publicOps.tableProjection";
+  readonly insertSignatureTable: "publicOps.tableProjection";
+  readonly deleteTable: "publicOps.tableProjection";
+  readonly insertTableRow: "publicOps.tableProjection";
+  readonly deleteTableRow: "publicOps.tableProjection";
+  readonly insertTableColumn: "publicOps.tableProjection";
+  readonly deleteTableColumn: "publicOps.tableProjection";
+  readonly mergeTableCells: "publicOps.tableProjection";
+  readonly splitTableCell: "publicOps.tableProjection";
+};
+type CanonicalPublicOperationOptions = Omit<ApplyFolioDocumentOperationsOptions, "view" | "createUndoHandle" | "createCommentId">;
+type CanonicalPublicOperationsOptions = {
+  session: CanonicalSession;
+  getState: (story: OpStory) => EditorState | null;
+  publish: (commit: CanonicalCommit) => boolean;
+};
+/** Handles address isolated journal groups; no second document or PM history is retained. */
+declare class CanonicalPublicOperations {
+  private readonly options;
+  private readonly handles;
+  private nextHandle;
+  private readonly handleNamespace;
+  constructor(options: CanonicalPublicOperationsOptions);
+  apply(options: CanonicalPublicOperationOptions): FolioDocumentOperationResult;
+  undo(handle: FolioDocumentOperationUndoHandle): FolioDocumentOperationUndoResult;
+  private resolve;
+}
+//#endregion
+export { CANONICAL_PUBLIC_OPERATION_DISPOSITIONS, CanonicalPublicOperationOptions, CanonicalPublicOperations };