@stll/folio-core 0.0.1-placeholder.0 → 0.1.0

package/dist/controller/hiddenEditorManager.d.ts

@@ -0,0 +1,93 @@
+import { document_d_exports } from "../types/document.js";
+import { HiddenEditorApi } from "./hiddenEditorApi.js";
+import { HiddenEditorStateReason } from "../layout-engine/layoutInstrumentation.js";
+import { ExtensionManager } from "../prosemirror/extensions/ExtensionManager.js";
+import { EditorState, Plugin, Transaction } from "prosemirror-state";
+import { EditorView } from "prosemirror-view";
+import * as YProseMirror from "y-prosemirror";
+import * as Yjs from "yjs";
+import { XmlFragment } from "yjs";
+
+//#region src/controller/hiddenEditorManager.d.ts
+type YProseMirrorModule = typeof YProseMirror;
+type YjsModule = typeof Yjs;
+type CollaborationModules = {
+  yProseMirror: YProseMirrorModule;
+  yjs: YjsModule;
+};
+type CollaborationAwareness = {
+  clientID: number;
+  getStates: () => Map<number, unknown>;
+  off: (event: "change" | "update", handler: () => void) => void;
+  on: (event: "change" | "update", handler: () => void) => void;
+};
+type HiddenProseMirrorCollaboration = {
+  awareness?: CollaborationAwareness | undefined;
+  onSeeded?: (() => void) | undefined;
+  shouldSeed?: boolean | undefined;
+  yXmlFragment: XmlFragment;
+};
+type HiddenProseMirrorRemoteSelection = {
+  anchor: number;
+  clientId: number;
+  color: string;
+  head: number;
+  name: string;
+};
+declare const collectRemoteSelections: (state: EditorState, awareness: CollaborationAwareness, collaborationModules: CollaborationModules) => HiddenProseMirrorRemoteSelection[];
+/**
+ * Create ProseMirror state from document
+ *
+ * When an ExtensionManager is provided, it supplies the schema and plugins.
+ * Otherwise falls back to the default singleton schema with no extension plugins.
+ */
+type CreateHiddenEditorStateOptions = {
+  document: document_d_exports.Document | null;
+  styles?: document_d_exports.StyleDefinitions | null | undefined;
+  manager?: ExtensionManager | undefined;
+  externalPlugins?: Plugin[] | undefined;
+  collaboration?: HiddenProseMirrorCollaboration | undefined;
+  collaborationModules?: CollaborationModules | null | undefined;
+  reason?: HiddenEditorStateReason | undefined;
+};
+declare function createHiddenEditorState(options: CreateHiddenEditorStateOptions): EditorState;
+type HiddenEditorManagerDeps = {
+  getHost: () => HTMLElement | null;
+  getDocument: () => document_d_exports.Document | null;
+  getStyles: () => document_d_exports.StyleDefinitions | null | undefined;
+  getExtensionManager: () => ExtensionManager | undefined;
+  getExternalPlugins: () => Plugin[];
+  getCollaboration: () => HiddenProseMirrorCollaboration | undefined;
+  getCollaborationModules: () => CollaborationModules | null;
+  getPrecomputedInitialState: () => EditorState | null | undefined;
+  getReadOnly: () => boolean;
+  /**
+   * Caller-provided stable identity of the loaded document: the same key across
+   * internal edits (so typing does not trigger an external re-sync) and a
+   * distinct key per loaded file. Authoritative when present; a metadata
+   * signature is used as a fallback when undefined.
+   */
+  getDocumentKey: () => string | undefined; /** Document context for the API's `getDocument` (PM state -> Document). */
+  getDocumentContext: () => document_d_exports.Document | null;
+  onTransaction: (transaction: Transaction, newState: EditorState) => void;
+  onSelectionChange: (state: EditorState) => void;
+  onKeyDown: (view: EditorView, event: KeyboardEvent) => boolean;
+  onReadOnlyEditAttempt: () => void;
+  onEditorViewReady: (view: EditorView) => void;
+  onEditorViewDestroy: () => void;
+  onRemoteSelectionsChange: (selections: HiddenProseMirrorRemoteSelection[]) => void;
+};
+type HiddenEditorManager = {
+  /** Request the view (sets the requested flag, then attempts creation). */ensureView: () => void; /** Re-attempt a previously-requested-but-deferred creation (no-op otherwise). */
+  retryViewCreation: () => void;
+  isViewRequested: () => boolean;
+  destroyView: () => void;
+  syncExternalDocument: () => void;
+  syncEditable: () => void;
+  getView: () => EditorView | null;
+  isInitialized: () => boolean;
+  api: HiddenEditorApi;
+};
+declare const createHiddenEditorManager: (deps: HiddenEditorManagerDeps) => HiddenEditorManager;
+//#endregion
+export { CollaborationModules, CreateHiddenEditorStateOptions, HiddenEditorManager, HiddenEditorManagerDeps, HiddenProseMirrorCollaboration, HiddenProseMirrorRemoteSelection, collectRemoteSelections, createHiddenEditorManager, createHiddenEditorState };

package/dist/controller/hiddenEditorManager.js

@@ -0,0 +1,308 @@
+import { ensureBaseDirectionInState } from "../prosemirror/extensions/features/AutoBidiDetectionExtension.js";
+import { createDocumentStylesPlugin } from "../prosemirror/plugins/documentStyles.js";
+import { ensureParaIdsInState } from "../prosemirror/extensions/features/ParaIdAllocatorExtension.js";
+import { schema } from "../prosemirror/schema/index.js";
+import { createEmptyDoc, toProseDoc } from "../prosemirror/conversion/toProseDoc.js";
+import { createHiddenEditorApi } from "./hiddenEditorApi.js";
+import { recordHiddenEditorPhase, recordHiddenEditorStateCreate } from "../layout-engine/layoutInstrumentation.js";
+import { suppressHiddenEditorScrollToSelection } from "../paged-layout/hiddenEditorScroll.js";
+import { isReadOnlyEditKey } from "../paged-layout/readOnlyEditAttempt.js";
+import { panic } from "better-result";
+import { EditorState } from "prosemirror-state";
+import { EditorView } from "prosemirror-view";
+//#region src/controller/hiddenEditorManager.ts
+/**
+* Hidden-editor view lifecycle manager
+*
+* Framework-agnostic owner of the off-screen ProseMirror EditorView. Holds the
+* view plus the bookkeeping that decides when an incoming document is a truly
+* external change (vs. an internal edit echoed back through props), builds the
+* editor state and `editorProps`, and composes the slice-2a imperative API so
+* the API and the lifecycle share one view owner. The React adapter
+* (`HiddenProseMirror`) keeps the input refs and its effects (which decide
+* *when* to act) and drives this manager through the methods below.
+*/
+const normalizeSeedState = (state) => ensureBaseDirectionInState(ensureParaIdsInState(state));
+const isObjectRecord = (value) => typeof value === "object" && value !== null;
+const isYSyncState = (value, yjs) => {
+	if (!isObjectRecord(value)) return false;
+	const binding = value["binding"];
+	return value["doc"] instanceof yjs.Doc && value["type"] instanceof yjs.XmlFragment && isObjectRecord(binding) && binding["mapping"] instanceof Map;
+};
+const readAwarenessCursor = (state) => {
+	if (!isObjectRecord(state)) return null;
+	const cursor = state["cursor"];
+	if (!isObjectRecord(cursor)) return null;
+	const anchor = cursor["anchor"];
+	const head = cursor["head"];
+	if (!isObjectRecord(anchor) || !isObjectRecord(head)) return null;
+	return {
+		anchor,
+		head
+	};
+};
+const readAwarenessUser = (state, clientId) => {
+	if (!isObjectRecord(state) || !isObjectRecord(state["user"])) return {
+		color: "var(--doc-image-selection)",
+		name: `User ${clientId}`
+	};
+	const user = state["user"];
+	return {
+		color: typeof user["color"] === "string" ? user["color"] : "var(--doc-image-selection)",
+		name: typeof user["name"] === "string" ? user["name"] : `User ${clientId}`
+	};
+};
+const collectRemoteSelections = (state, awareness, collaborationModules) => {
+	const syncState = collaborationModules.yProseMirror.ySyncPluginKey.getState(state);
+	if (!isYSyncState(syncState, collaborationModules.yjs)) return [];
+	const selections = [];
+	for (const [clientId, remoteState] of awareness.getStates()) {
+		if (clientId === awareness.clientID) continue;
+		const cursor = readAwarenessCursor(remoteState);
+		if (cursor === null) continue;
+		const anchor = collaborationModules.yProseMirror.relativePositionToAbsolutePosition(syncState.doc, syncState.type, collaborationModules.yjs.createRelativePositionFromJSON(cursor.anchor), syncState.binding.mapping);
+		const head = collaborationModules.yProseMirror.relativePositionToAbsolutePosition(syncState.doc, syncState.type, collaborationModules.yjs.createRelativePositionFromJSON(cursor.head), syncState.binding.mapping);
+		if (anchor === null || head === null) continue;
+		const user = readAwarenessUser(remoteState, clientId);
+		selections.push({
+			anchor,
+			clientId,
+			color: user.color,
+			head,
+			name: user.name
+		});
+	}
+	return selections;
+};
+const HIDDEN_EDITOR_ATTRIBUTES = {
+	"aria-label": "Document content",
+	"aria-multiline": "true",
+	autocapitalize: "off",
+	autocomplete: "off",
+	autocorrect: "off",
+	role: "textbox",
+	spellcheck: "false",
+	translate: "no"
+};
+function createHiddenEditorState(options) {
+	const { document, styles, manager, externalPlugins = [], collaboration, collaborationModules, reason = "mount" } = options;
+	recordHiddenEditorStateCreate(reason);
+	const activeSchema = manager?.getSchema() ?? schema;
+	let localDoc = createEmptyDoc();
+	if (document) {
+		const startedAt = performance.now();
+		localDoc = styles === void 0 || styles === null ? toProseDoc(document) : toProseDoc(document, { styles });
+		recordHiddenEditorPhase(reason, "to-prose-doc", performance.now() - startedAt);
+	}
+	const styleResolverPlugin = createDocumentStylesPlugin(styles ?? document?.package.styles);
+	const plugins = [
+		...externalPlugins,
+		...manager?.getPlugins() ?? [],
+		styleResolverPlugin
+	];
+	if (collaboration) {
+		if (!collaborationModules) panic("Collaboration modules must be loaded before creating collaborative editor state.");
+		if (collaboration.shouldSeed && collaboration.yXmlFragment.length === 0) {
+			const seedState = normalizeSeedState(EditorState.create({
+				doc: localDoc,
+				schema: activeSchema,
+				plugins
+			}));
+			collaborationModules.yProseMirror.prosemirrorToYXmlFragment(seedState.doc, collaboration.yXmlFragment);
+			collaboration.onSeeded?.();
+		}
+		let { doc } = collaborationModules.yProseMirror.initProseMirrorDoc(collaboration.yXmlFragment, activeSchema);
+		const initializedState = normalizeSeedState(EditorState.create({
+			doc,
+			schema: activeSchema,
+			plugins
+		}));
+		if (!initializedState.doc.eq(doc)) {
+			collaborationModules.yProseMirror.prosemirrorToYXmlFragment(initializedState.doc, collaboration.yXmlFragment);
+			({doc} = collaborationModules.yProseMirror.initProseMirrorDoc(collaboration.yXmlFragment, activeSchema));
+		}
+		const startedAt = performance.now();
+		const state = normalizeSeedState(EditorState.create({
+			doc,
+			schema: activeSchema,
+			plugins
+		}));
+		recordHiddenEditorPhase(reason, "editor-state", performance.now() - startedAt);
+		return state;
+	}
+	const startedAt = performance.now();
+	const state = normalizeSeedState(EditorState.create({
+		doc: localDoc,
+		schema: activeSchema,
+		plugins
+	}));
+	recordHiddenEditorPhase(reason, "editor-state", performance.now() - startedAt);
+	return state;
+}
+function getDocumentIdentity(doc) {
+	if (!doc) return "empty";
+	const meta = doc.package.properties;
+	return `${meta?.created ? String(meta.created) : ""}-${meta?.modified ? String(meta.modified) : ""}-${meta?.title ?? ""}`;
+}
+function syncHiddenEditorAccessibility(view, readOnly) {
+	const { dom } = view;
+	if (!dom.hasAttribute("tabindex")) dom.tabIndex = 0;
+	dom.setAttribute("aria-readonly", readOnly ? "true" : "false");
+}
+const createHiddenEditorManager = (deps) => {
+	let view = null;
+	let isDestroying = false;
+	let requested = false;
+	let isInitialized = false;
+	let lastDocumentId = null;
+	let lastCollaborationFragment = null;
+	const currentDocumentIdentity = () => deps.getDocumentKey() ?? getDocumentIdentity(deps.getDocument());
+	const tryCreate = () => {
+		if (!requested || view !== null || isDestroying) return;
+		const host = deps.getHost();
+		if (!host) return;
+		const collaboration = deps.getCollaboration();
+		const collaborationModules = deps.getCollaborationModules();
+		if (collaboration && !collaborationModules) return;
+		const precomputedInitialState = deps.getPrecomputedInitialState();
+		const document = deps.getDocument();
+		const styles = deps.getStyles();
+		const extensionManager = deps.getExtensionManager();
+		const externalPlugins = deps.getExternalPlugins();
+		const editorProps = {
+			state: precomputedInitialState && !collaboration ? precomputedInitialState : createHiddenEditorState({
+				document,
+				styles,
+				manager: extensionManager,
+				externalPlugins,
+				collaboration,
+				collaborationModules,
+				reason: "mount"
+			}),
+			attributes: HIDDEN_EDITOR_ATTRIBUTES,
+			editable: () => !deps.getReadOnly(),
+			dispatchTransaction: (transaction) => {
+				if (!view || isDestroying) return;
+				if (deps.getReadOnly() && transaction.docChanged) {
+					deps.onReadOnlyEditAttempt();
+					return;
+				}
+				const newState = view.state.apply(transaction);
+				view.updateState(newState);
+				deps.onTransaction(transaction, newState);
+				if (transaction.selectionSet || transaction.docChanged) deps.onSelectionChange(newState);
+				const currentCollaboration = deps.getCollaboration();
+				const currentCollaborationModules = deps.getCollaborationModules();
+				if (currentCollaboration?.awareness && currentCollaborationModules) deps.onRemoteSelectionsChange(collectRemoteSelections(newState, currentCollaboration.awareness, currentCollaborationModules));
+			},
+			handleKeyDown: (pmView, event) => {
+				if (deps.getReadOnly() && isReadOnlyEditKey(event)) {
+					deps.onReadOnlyEditAttempt();
+					event.preventDefault();
+					return true;
+				}
+				return deps.onKeyDown(pmView, event);
+			},
+			handleScrollToSelection: suppressHiddenEditorScrollToSelection,
+			handleDOMEvents: {
+				focus: () => false,
+				blur: () => false,
+				beforeinput: (_view, event) => {
+					if (!deps.getReadOnly()) return false;
+					deps.onReadOnlyEditAttempt();
+					event.preventDefault();
+					return true;
+				},
+				paste: (_view, event) => {
+					if (!deps.getReadOnly()) return false;
+					deps.onReadOnlyEditAttempt();
+					event.preventDefault();
+					return true;
+				},
+				drop: (_view, event) => {
+					if (!deps.getReadOnly()) return false;
+					deps.onReadOnlyEditAttempt();
+					event.preventDefault();
+					return true;
+				}
+			}
+		};
+		const viewStartedAt = performance.now();
+		view = new EditorView(host, editorProps);
+		recordHiddenEditorPhase("mount", "editor-view", performance.now() - viewStartedAt);
+		syncHiddenEditorAccessibility(view, deps.getReadOnly());
+		isInitialized = true;
+		lastDocumentId = currentDocumentIdentity();
+		lastCollaborationFragment = collaboration?.yXmlFragment ?? null;
+		deps.onEditorViewReady(view);
+	};
+	const ensureView = () => {
+		requested = true;
+		tryCreate();
+	};
+	const retryViewCreation = () => {
+		tryCreate();
+	};
+	const isViewRequested = () => requested;
+	const destroyView = () => {
+		if (view && !isDestroying) {
+			isDestroying = true;
+			deps.onEditorViewDestroy();
+			view.destroy();
+			view = null;
+			isDestroying = false;
+		}
+	};
+	const syncExternalDocument = () => {
+		if (!view || isDestroying) return;
+		const collaboration = deps.getCollaboration();
+		const collaborationModules = deps.getCollaborationModules();
+		if (collaboration && !collaborationModules) return;
+		const document = deps.getDocument();
+		const currentDocId = currentDocumentIdentity();
+		const currentCollaborationFragment = collaboration?.yXmlFragment ?? null;
+		const collaborationSourceChanged = currentCollaborationFragment !== lastCollaborationFragment;
+		if (collaboration && !collaborationSourceChanged) return;
+		if (isInitialized && currentDocId === lastDocumentId && !collaborationSourceChanged) return;
+		isInitialized = true;
+		lastDocumentId = currentDocId;
+		lastCollaborationFragment = currentCollaborationFragment;
+		const newState = createHiddenEditorState({
+			document,
+			styles: deps.getStyles(),
+			manager: deps.getExtensionManager(),
+			externalPlugins: deps.getExternalPlugins(),
+			collaboration,
+			collaborationModules,
+			reason: "external-document"
+		});
+		const updateStartedAt = performance.now();
+		view.updateState(newState);
+		recordHiddenEditorPhase("external-document", "update-state", performance.now() - updateStartedAt);
+		syncHiddenEditorAccessibility(view, deps.getReadOnly());
+		deps.onSelectionChange(newState);
+	};
+	const syncEditable = () => {
+		if (!view) return;
+		syncHiddenEditorAccessibility(view, deps.getReadOnly());
+	};
+	return {
+		ensureView,
+		retryViewCreation,
+		isViewRequested,
+		destroyView,
+		syncExternalDocument,
+		syncEditable,
+		getView: () => view,
+		isInitialized: () => isInitialized,
+		api: createHiddenEditorApi({
+			getView: () => view,
+			getDocumentContext: deps.getDocumentContext,
+			isDestroying: () => isDestroying,
+			ensureView,
+			isViewRequested
+		})
+	};
+};
+//#endregion
+export { collectRemoteSelections, createHiddenEditorManager, createHiddenEditorState };

package/dist/controller/layoutPipeline.d.ts

@@ -0,0 +1,63 @@
+import { document_d_exports } from "../types/document.js";
+import { ColumnLayout, FlowBlock, FootnoteContent, HeaderFooterContent, Layout, Measure, PageHeaderFooterRefs, PageMargins } from "../layout-engine/types.js";
+import { LayoutRunReason } from "../layout-engine/layoutInstrumentation.js";
+import { DirtyRange } from "../paged-layout/incrementalMeasure.js";
+import { ConvertHeaderFooterOptions, HeaderFooterMetrics } from "../layout-bridge/convert/headerFooterLayout.js";
+import { FootnoteRenderItem } from "../layout-painter/renderPage.js";
+import { BlockLookup, LayoutPainter } from "../layout-painter/index.js";
+import { LayoutSelectionGate } from "../paged-layout/LayoutSelectionGate.js";
+import { TemplatePreviewEntry } from "../prosemirror/plugins/templatePreviewValues.js";
+import { LayoutSession } from "./layoutSession.js";
+import { EditorState } from "prosemirror-state";
+
+//#region src/controller/layoutPipeline.d.ts
+type LayoutRunOptions = {
+  dirtyRange?: DirtyRange;
+  forceFull?: boolean;
+  reason?: LayoutRunReason;
+};
+type LayoutOutcome = {
+  blocks?: FlowBlock[];
+  measures?: Measure[];
+  layout?: Layout;
+  blockLookup?: BlockLookup;
+};
+type LayoutPipelineDeps<THfPMs> = {
+  contentWidth: number;
+  columns: ColumnLayout | undefined;
+  pageSize: {
+    w: number;
+    h: number;
+  };
+  margins: PageMargins;
+  pageGap: number;
+  syncCoordinator: LayoutSelectionGate;
+  headerContent: document_d_exports.HeaderFooter | null | undefined;
+  footerContent: document_d_exports.HeaderFooter | null | undefined;
+  firstPageHeaderContent: document_d_exports.HeaderFooter | null | undefined;
+  firstPageFooterContent: document_d_exports.HeaderFooter | null | undefined;
+  headerContentRId: string | null | undefined;
+  footerContentRId: string | null | undefined;
+  firstPageHeaderContentRId: string | null | undefined;
+  firstPageFooterContentRId: string | null | undefined;
+  sectionHeaderFooterRefs: PageHeaderFooterRefs[] | undefined;
+  theme: document_d_exports.Theme | null | undefined;
+  sectionProperties: document_d_exports.SectionProperties | null | undefined;
+  document: document_d_exports.Document | null;
+  defaultTabStop: number | undefined;
+  styles: document_d_exports.StyleDefinitions | null | undefined;
+  layout: Layout | null;
+  hfPMs: THfPMs;
+  painter: LayoutPainter | null;
+  pagesContainer: HTMLDivElement | null;
+  session: LayoutSession;
+  renderHfFromContentOrPm: (hf: document_d_exports.HeaderFooter | null | undefined, rId: string | null | undefined, hfPMs: THfPMs, contentWidth: number, metrics: HeaderFooterMetrics, options: ConvertHeaderFooterOptions) => HeaderFooterContent | undefined;
+  renderHeaderFooterContentByRId: (source: Map<string, document_d_exports.HeaderFooter> | undefined, hfPMs: THfPMs, contentWidth: number, metrics: HeaderFooterMetrics, options: ConvertHeaderFooterOptions) => Map<string, HeaderFooterContent> | undefined;
+  documentFontsAreLoaded: () => boolean;
+  buildFootnoteRenderItems: (pageFootnoteMap: Map<number, number[]>, footnoteContentMap: Map<number, FootnoteContent>, doc: document_d_exports.Document | null) => Map<number, FootnoteRenderItem[]>;
+  describeInvalidHighlightMarks: (doc: EditorState["doc"]) => string;
+  emptyTemplatePreviewEntries: readonly TemplatePreviewEntry[];
+};
+declare function runLayoutPipeline<THfPMs>(deps: LayoutPipelineDeps<THfPMs>, state: EditorState, options?: LayoutRunOptions): LayoutOutcome;
+//#endregion
+export { LayoutOutcome, LayoutPipelineDeps, LayoutRunOptions, runLayoutPipeline };