@stll/folio-core 0.63.1 → 0.64.0

package/dist/layout-painter/renderPage.d.ts

@@ -301,6 +301,12 @@ export type PainterPaintedDetail = {
   container: HTMLElement;
   pageCount: number;
 };
+/**
+ * Paint `shell` and its buffer neighbours now, ahead of the observer, so a
+ * navigation can scroll straight onto painted content instead of passing blank
+ * shells. No-op for containers `renderPages` did not virtualize.
+ */
+export declare function renderPagesAround(container: HTMLElement, shell: HTMLElement): void;
 /**
  * Force every virtualized page shell in `container` to be fully rendered.
  *

package/dist/layout-painter/renderPage.js

@@ -8,6 +8,7 @@ import { DEFAULT_FONT_FAMILY } from "../layout-engine/measure/measureHelpers.js"
 import { measureParagraph } from "../layout-engine/measure/measureParagraph.js";
 import { resolveTableInlineOffset } from "../layout-engine/measure/tableInlinePlacement.js";
 import { NOTE_SEPARATOR_RULE_THICKNESS, NOTE_SEPARATOR_WIDTH_FRACTION, floatingTextBoxReservesBand, floatingTextBoxWrapsText, isFloatingImageRun, isFloatingTextBoxBlock, isTextWrappingFloatingImageRun, stripFlowBlockPmAnchors } from "../layout-engine/types.js";
+import { getEditorScrollRoot } from "../paged-layout/editorScrollRoot.js";
 import { cssBorderStyle } from "../utils/borderCss.js";
 import { resolveFontFamily } from "../utils/fontResolver.js";
 import { borderToStyle } from "../utils/formatToStyle.js";
@@ -1527,6 +1528,8 @@ function applyContainerStyles(container, pageGap) {
 */
 const VIRTUALIZATION_BUFFER = 1;
 const VIRTUALIZATION_ROOT_MARGIN_PX = 1e3;
+/** Painted pages stay painted within three viewport heights of the viewport. */
+const VIRTUALIZATION_RETAIN_MARGIN_PERCENT = 300;
 const INITIAL_EAGER_RENDER_PAGES = 3;
 /**
 * Minimum page count before virtualization kicks in.
@@ -1555,7 +1558,7 @@ function renderPages(pages, container, options = {}) {
 	if (prevState && prevState.optionsHash === currentOptionsHash && useVirtualization) {
 		const prevShells = prevState.pageStates;
 		const prevDataMap = prevState.pageDataMap;
-		const observer = pc.__pageObserver;
+		const observers = pc.__pageObservers;
 		const totalPagesChanged = prevState.totalPages !== totalPages;
 		const fieldContextChanged = prevState.fieldContextHash !== currentFieldContextHash;
 		const commonCount = Math.min(prevShells.length, pages.length);
@@ -1619,13 +1622,16 @@ function renderPages(pages, container, options = {}) {
 					index: i,
 					rendered: false
 				});
-				if (observer) observer.observe(pageEl);
+				observers?.populate.observe(pageEl);
+				observers?.retain.observe(pageEl);
 			}
 		}
 		if (pages.length < prevShells.length) {
 			for (let i = prevShells.length - 1; i >= pages.length; i--) {
 				const shell = prevShells[i].element;
-				if (observer) observer.unobserve(shell);
+				observers?.populate.unobserve(shell);
+				observers?.retain.unobserve(shell);
+				prevState.retainedShells.delete(shell);
 				prevDataMap.delete(shell);
 				removeRenderedPage(shell);
 			}
@@ -1641,10 +1647,11 @@ function renderPages(pages, container, options = {}) {
 		emitPainterPainted(container);
 		return;
 	}
-	const prevObserver = pc.__pageObserver;
-	if (prevObserver) {
-		prevObserver.disconnect();
-		delete pc.__pageObserver;
+	const prevObservers = pc.__pageObservers;
+	if (prevObservers) {
+		prevObservers.populate.disconnect();
+		prevObservers.retain.disconnect();
+		delete pc.__pageObservers;
 	}
 	const pageShellClass = options.pageClassName ?? PAGE_CLASS_NAMES.page;
 	const isPageShell = (el) => el.className.split(/\s+/u).includes(pageShellClass);
@@ -1683,52 +1690,42 @@ function renderPages(pages, container, options = {}) {
 		index: i,
 		rendered: false
 	});
-	const observer = new IntersectionObserver((entries) => {
+	const observerRoot = getEditorScrollRoot(container);
+	const populate = new IntersectionObserver((entries) => {
 		const renderState = pc.__pageRenderState;
 		if (!renderState) return;
-		const { currentOptions: liveOptions, totalPages: liveTotalPages, pageDataMap: liveDataMap } = renderState;
 		for (const entry of entries) {
-			if (!(entry.target instanceof HTMLElement)) continue;
-			const shell = entry.target;
-			const data = liveDataMap.get(shell);
-			if (!data) continue;
-			if (entry.isIntersecting) {
-				populatePageShell(shell, liveDataMap, liveTotalPages, liveOptions);
-				for (let offset = -1; offset <= VIRTUALIZATION_BUFFER; offset++) {
-					const neighborIdx = data.index + offset;
-					if (neighborIdx >= 0 && neighborIdx < renderState.pageStates.length && neighborIdx !== data.index) populatePageShell(renderState.pageStates[neighborIdx].element, liveDataMap, liveTotalPages, liveOptions);
-				}
-			}
-		}
-		const viewportHeight = window.innerHeight;
-		const nearThreshold = viewportHeight * 3;
-		const nearIndices = /* @__PURE__ */ new Set();
-		let depopulated = false;
-		for (const [el, data] of liveDataMap) {
-			if (!data.rendered) continue;
-			const rect = el.getBoundingClientRect();
-			if (rect.bottom > -nearThreshold && rect.top < viewportHeight + nearThreshold) nearIndices.add(data.index);
-		}
-		for (const [el, data] of liveDataMap) {
-			if (!data.rendered) continue;
-			let keepRendered = false;
-			for (const nearIdx of nearIndices) if (Math.abs(data.index - nearIdx) <= 2) {
-				keepRendered = true;
-				break;
-			}
-			if (!keepRendered && nearIndices.size > 0) {
-				depopulatePageShell(el, liveDataMap);
-				depopulated = true;
-			}
+			if (!(entry.target instanceof HTMLElement) || !entry.isIntersecting) continue;
+			const data = renderState.pageDataMap.get(entry.target);
+			if (data) populatePageRange(renderState, data.index);
 		}
-		if (depopulated) emitPainterPainted(container);
 	}, {
-		root: null,
+		root: observerRoot,
 		rootMargin: `${VIRTUALIZATION_ROOT_MARGIN_PX}px 0px ${VIRTUALIZATION_ROOT_MARGIN_PX}px 0px`
 	});
-	for (const shell of pageShells) observer.observe(shell);
-	pc.__pageObserver = observer;
+	const retain = new IntersectionObserver((entries) => {
+		const renderState = pc.__pageRenderState;
+		if (!renderState) return;
+		for (const entry of entries) {
+			if (!(entry.target instanceof HTMLElement)) continue;
+			if (entry.isIntersecting) renderState.retainedShells.add(entry.target);
+			else renderState.retainedShells.delete(entry.target);
+		}
+		sweepUnretainedPages(container, renderState);
+	}, {
+		root: observerRoot,
+		rootMargin: `${VIRTUALIZATION_RETAIN_MARGIN_PERCENT}% 0px ${VIRTUALIZATION_RETAIN_MARGIN_PERCENT}% 0px`
+	});
+	for (const shell of pageShells) {
+		populate.observe(shell);
+		retain.observe(shell);
+	}
+	pc.__pageObservers = {
+		populate,
+		retain
+	};
 	pc.__pageRenderState = {
+		retainedShells: /* @__PURE__ */ new Set(),
 		pageStates: pageShells.map((el) => ({
 			element: el,
 			fingerprint: null,
@@ -1775,6 +1772,45 @@ function populatePageShell(shell, pageDataMap, totalPages, options) {
 	const container = shell.parentElement;
 	if (container instanceof HTMLElement) emitPainterPainted(container);
 }
+/** Paint the page at `index` and its buffer neighbours. */
+function populatePageRange(state, index) {
+	const first = Math.max(0, index - VIRTUALIZATION_BUFFER);
+	const last = Math.min(state.pageStates.length - 1, index + VIRTUALIZATION_BUFFER);
+	for (let i = first; i <= last; i++) populatePageShell(state.pageStates[i].element, state.pageDataMap, state.totalPages, state.currentOptions);
+}
+/**
+* Depopulate painted pages more than one page beyond the buffer of every
+* retained shell. Reads the retention observer's last report, so it forces no
+* layout.
+*/
+function sweepUnretainedPages(container, state) {
+	const retainedIndices = [];
+	for (const shell of state.retainedShells) {
+		const data = state.pageDataMap.get(shell);
+		if (data) retainedIndices.push(data.index);
+	}
+	if (retainedIndices.length === 0) return;
+	let depopulated = false;
+	for (const [el, data] of state.pageDataMap) {
+		if (!data.rendered) continue;
+		if (!retainedIndices.some((retainedIndex) => Math.abs(data.index - retainedIndex) <= 2)) {
+			depopulatePageShell(el, state.pageDataMap);
+			depopulated = true;
+		}
+	}
+	if (depopulated) emitPainterPainted(container);
+}
+/**
+* Paint `shell` and its buffer neighbours now, ahead of the observer, so a
+* navigation can scroll straight onto painted content instead of passing blank
+* shells. No-op for containers `renderPages` did not virtualize.
+*/
+function renderPagesAround(container, shell) {
+	const state = container.__pageRenderState;
+	const data = state?.pageDataMap.get(shell);
+	if (!state || !data) return;
+	populatePageRange(state, data.index);
+}
 /**
 * Force every virtualized page shell in `container` to be fully rendered.
 *
@@ -1918,7 +1954,7 @@ function findPageShellForPmPos(container, pmPos) {
 			if (fragment.pmEnd !== void 0 && fragment.pmEnd > pageEnd) pageEnd = fragment.pmEnd;
 		}
 		if (pageStart === Number.POSITIVE_INFINITY) continue;
-		if (pageStart <= pmPos && pmPos <= pageEnd) return {
+		if (pageStart <= pmPos && pmPos < pageEnd) return {
 			element: shell,
 			isExact: true
 		};
@@ -1947,4 +1983,4 @@ function depopulatePageShell(shell, pageDataMap) {
 	}
 }
 //#endregion
-export { PAGE_CLASS_NAMES, PAINTER_PAINTED_EVENT, applySectionHeaderFooterOptions, calculateFootnoteAreaRenderHeight, computePageFingerprint, emuToPixels, findPageShellForPmPos, floatingTableReservesBand, getDefaultPageFontFamily, isFloatingImageRun, renderAllPagesNow, renderFloatingImagesLayer, renderFootnoteArea, renderPage, renderPages, resolveAnchoredImagePosition, resolveHeaderFooterFloatLeft, resolveHeaderFooterIntrinsicFrameHorizontalPosition, selectSectionHeaderFooterRIds };
+export { PAGE_CLASS_NAMES, PAINTER_PAINTED_EVENT, applySectionHeaderFooterOptions, calculateFootnoteAreaRenderHeight, computePageFingerprint, emuToPixels, findPageShellForPmPos, floatingTableReservesBand, getDefaultPageFontFamily, isFloatingImageRun, renderAllPagesNow, renderFloatingImagesLayer, renderFootnoteArea, renderPage, renderPages, renderPagesAround, resolveAnchoredImagePosition, resolveHeaderFooterFloatLeft, resolveHeaderFooterIntrinsicFrameHorizontalPosition, selectSectionHeaderFooterRIds };

package/dist/paged-layout/editorScrollRoot.d.ts

@@ -5,6 +5,10 @@ export declare const scrollEditorTo: (element: HTMLElement | null, options: Scro
 export declare const scrollEditorBy: (element: HTMLElement | null, delta: number) => void;
 type ScrollEditorElementOptions = {
   block?: "start" | "center" | "end" | "nearest";
+  /**
+   * Omitted: smooth (instant under `prefers-reduced-motion`) within two
+   * viewport heights, instant beyond.
+   */
   behavior?: ScrollBehavior;
   /** Space to leave between the target and the visible root edge. */
   margin?: number;

package/dist/paged-layout/editorScrollRoot.js

@@ -24,8 +24,15 @@ const nearestScrollOffset = ({ targetStart, targetEnd, viewportStart, viewportEn
 	if (below && targetSize <= viewportSize || above && targetSize > viewportSize) return targetEnd - viewportEnd;
 	return 0;
 };
+/**
+* Farthest move, in viewport heights, that the default behavior animates. A
+* longer smooth scroll passes page shells that virtualization paints one by
+* one before discarding them, and shows blank shells until it arrives.
+*/
+const SMOOTH_SCROLL_MAX_VIEWPORTS = 2;
+const navigationScrollBehavior = (distance, viewportHeight) => Math.abs(distance) > viewportHeight * SMOOTH_SCROLL_MAX_VIEWPORTS ? "instant" : prefersReducedMotionBehavior();
 /** Scroll only the marked root, including when the target is inside a scaled viewport. */
-const scrollEditorElementIntoView = (element, { block = "center", behavior = prefersReducedMotionBehavior(), margin = 0, rect } = {}) => {
+const scrollEditorElementIntoView = (element, { block = "center", behavior, margin = 0, rect } = {}) => {
 	const root = getEditorScrollRoot(element);
 	if (!root || !element) return;
 	const targetRect = rect ?? element.getBoundingClientRect();
@@ -62,10 +69,11 @@ const scrollEditorElementIntoView = (element, { block = "center", behavior = pre
 		viewportEnd: visibleLeft + root.clientWidth
 	});
 	if (top === root.scrollTop && left === root.scrollLeft) return;
+	const clampedTop = Math.max(0, top);
 	scrollEditorTo(root, {
-		top: Math.max(0, top),
+		top: clampedTop,
 		left: Math.max(0, left),
-		behavior
+		behavior: behavior ?? navigationScrollBehavior(clampedTop - root.scrollTop, root.clientHeight)
 	});
 };
 //#endregion

package/dist/paged-layout/scrollToPmPosition.js

@@ -1,5 +1,5 @@
 import { findBodyPmAnchor, findBodyPmAnchors } from "../layout-bridge/dom/findBodyPmSpans.js";
-import { findPageShellForPmPos } from "../layout-painter/renderPage.js";
+import { findPageShellForPmPos, renderPagesAround } from "../layout-painter/renderPage.js";
 import { getEditorScrollRoot, scrollEditorElementIntoView } from "./editorScrollRoot.js";
 import { isValidPmScrollPosition } from "./scrollNavigation.js";
 //#region src/paged-layout/scrollToPmPosition.ts
@@ -8,61 +8,51 @@ const PAGES_CONTAINER_CLASS = "paged-editor__pages";
 /** Scroll visible pages to a ProseMirror position. */
 const scrollPagesToPmPosition = (pageContainer, pmPos) => {
 	if (!isValidPmScrollPosition(pmPos)) return;
-	const exact = findBodyPmAnchor(pageContainer, pmPos);
-	if (exact) {
-		scrollEditorElementIntoView(exact);
-		return;
-	}
-	let runMatch = null;
-	for (const el of findBodyPmAnchors(pageContainer)) {
-		const start = Number(el.dataset["pmStart"]);
-		if (Number.isNaN(start)) continue;
-		const endAttr = el.dataset["pmEnd"];
-		const end = endAttr === void 0 ? start : Number(endAttr);
-		if (start <= pmPos && pmPos <= end) {
-			runMatch = el;
-			break;
-		}
-	}
-	if (runMatch) {
-		scrollEditorElementIntoView(runMatch);
+	const rendered = findBodyPmAnchor(pageContainer, pmPos) ?? findAnchorContaining(pageContainer, pmPos);
+	if (rendered) {
+		scrollEditorElementIntoView(rendered);
 		return;
 	}
 	const shellHit = findPageShellForPmPos(pageContainer, pmPos);
 	if (!shellHit) return;
 	const { element: shell } = shellHit;
-	scrollEditorElementIntoView(shell);
-	let attempts = 0;
-	const refine = () => {
-		attempts++;
-		const exactInShell = findBodyPmAnchor(shell, pmPos);
-		if (exactInShell) {
-			scrollEditorElementIntoView(exactInShell);
-			return;
-		}
-		let bestEl = null;
-		let bestStart = Number.NEGATIVE_INFINITY;
-		for (const el of findBodyPmAnchors(shell)) {
-			const start = Number(el.dataset["pmStart"]);
-			if (Number.isNaN(start)) continue;
-			const endAttr = el.dataset["pmEnd"];
-			const end = endAttr === void 0 ? start : Number(endAttr);
-			if (start <= pmPos && pmPos <= end) {
-				bestEl = el;
-				break;
-			}
-			if (start <= pmPos && start > bestStart) {
-				bestStart = start;
-				bestEl = el;
-			}
-		}
-		if (bestEl) {
-			scrollEditorElementIntoView(bestEl);
-			return;
-		}
-		if (attempts < 20) requestAnimationFrame(refine);
-	};
-	requestAnimationFrame(refine);
+	renderPagesAround(pageContainer, shell);
+	scrollEditorElementIntoView(findBodyPmAnchor(shell, pmPos) ?? findAnchorContaining(shell, pmPos) ?? findAnchorBefore(shell, pmPos) ?? shell);
+};
+const anchorRanges = (root) => {
+	const ranges = [];
+	for (const element of findBodyPmAnchors(root)) {
+		const start = Number(element.dataset["pmStart"]);
+		if (Number.isNaN(start)) continue;
+		const endAttr = element.dataset["pmEnd"];
+		ranges.push({
+			element,
+			start,
+			end: endAttr === void 0 ? start : Number(endAttr)
+		});
+	}
+	return ranges;
+};
+/**
+* First painted run whose range holds `pmPos` (block positions rarely match a
+* run start). Ranges are half-open, as page lookups are: a run ending where a
+* block starts belongs before it, so the end of a painted page never stands in
+* for the unpainted page that block opens. A run without an end holds only its
+* start.
+*/
+const findAnchorContaining = (root, pmPos) => {
+	for (const { element, start, end } of anchorRanges(root)) if (start <= pmPos && (pmPos < end || pmPos === start)) return element;
+	return null;
+};
+/** The painted run starting closest before `pmPos`. */
+const findAnchorBefore = (root, pmPos) => {
+	let best = null;
+	let bestStart = Number.NEGATIVE_INFINITY;
+	for (const { element, start } of anchorRanges(root)) if (start <= pmPos && start > bestStart) {
+		bestStart = start;
+		best = element;
+	}
+	return best;
 };
 /**
 * Scroll the paged layout that mirrors `view` so `pmPos` is centered

package/dist/utils/headingCollector.d.ts

@@ -5,6 +5,13 @@ import { Node } from "prosemirror-model";
  * Information about a heading found in the document.
  */
 export type HeadingInfo = {
+  /**
+   * Outline identity within this editing session: the paragraph's `paraId`,
+   * which the editor allocates for every body paragraph and which survives
+   * edits elsewhere in the document. A paragraph without one, or whose
+   * `paraId` an earlier heading already took, is identified by position.
+   */
+  id: string;
   /** The text content of the heading */
   text: string;
   /** Outline level (0 = Heading 1, 1 = Heading 2, etc.) */

package/dist/utils/headingCollector.js

@@ -1,6 +1,8 @@
 import { resolveHeadingLevel } from "../docx/builtInStyles.js";
 import { readOutlineLevelAttr } from "../prosemirror/outlineLevelAttr.js";
 //#region src/utils/headingCollector.ts
+/** Not hex, so it cannot collide with a `paraId` Word or the editor writes. */
+const POSITIONAL_HEADING_ID_PREFIX = "pos-";
 const RUN_IN_TITLE_MARKS = /* @__PURE__ */ new Set([
 	"bold",
 	"italic",
@@ -56,6 +58,7 @@ const headingText = (paragraph) => {
 */
 function collectHeadings(doc, styles) {
 	const headings = [];
+	const takenIds = /* @__PURE__ */ new Set();
 	doc.descendants((node, pos) => {
 		if (node.type.name !== "paragraph") return;
 		const level = resolveHeadingLevel({
@@ -64,7 +67,12 @@ function collectHeadings(doc, styles) {
 		}, styles);
 		if (level === void 0) return;
 		const text = headingText(node);
-		if (text.trim()) headings.push({
+		if (!text.trim()) return;
+		const paraId = node.attrs["paraId"];
+		const id = typeof paraId === "string" && paraId !== "" && !takenIds.has(paraId) ? paraId : `${POSITIONAL_HEADING_ID_PREFIX}${String(pos)}`;
+		takenIds.add(id);
+		headings.push({
+			id,
 			text: text.trim(),
 			level,
 			pmPos: pos

package/dist/utils/outlineHeadings.d.ts

@@ -0,0 +1,20 @@
+import { HeadingInfo } from "./headingCollector.js";
+import { Layout } from "../layout-engine/types.js";
+//#region src/utils/outlineHeadings.d.ts
+type ResolveOutlineHeadingsOptions = {
+  /** Headings collected from the document `layout` was computed from. */
+  collected: readonly HeadingInfo[];
+  layout: Layout | null;
+  previous: HeadingInfo[];
+};
+/**
+ * The outline's headings with page numbers from `layout`.
+ *
+ * A heading the layout does not place keeps the page number it last had under
+ * the same id, so the outline never shows a transient blank while a layout is
+ * pending. An unchanged entry is returned as its previous object and an
+ * unchanged list as the previous array, so consumers can skip work by identity.
+ */
+export declare const resolveOutlineHeadings: ({ collected, layout, previous }: ResolveOutlineHeadingsOptions) => HeadingInfo[];
+//#endregion
+export {};

package/dist/utils/outlineHeadings.js

@@ -0,0 +1,43 @@
+import { findPageIndexContainingPmPos } from "../layout-engine/pmPageIndex.js";
+//#region src/utils/outlineHeadings.ts
+const sameHeading = (a, b) => Object.values({
+	id: a.id === b.id,
+	text: a.text === b.text,
+	level: a.level === b.level,
+	pmPos: a.pmPos === b.pmPos,
+	pageNumber: (a.pageNumber ?? null) === (b.pageNumber ?? null)
+}).every(Boolean);
+const layoutPageNumber = (layout, pmPos) => {
+	const pageIndex = findPageIndexContainingPmPos(layout, pmPos);
+	return pageIndex === null ? null : layout.pages[pageIndex]?.number ?? null;
+};
+/**
+* The outline's headings with page numbers from `layout`.
+*
+* A heading the layout does not place keeps the page number it last had under
+* the same id, so the outline never shows a transient blank while a layout is
+* pending. An unchanged entry is returned as its previous object and an
+* unchanged list as the previous array, so consumers can skip work by identity.
+*/
+const resolveOutlineHeadings = ({ collected, layout, previous }) => {
+	const previousById = new Map(previous.map((heading) => [heading.id, heading]));
+	let changed = collected.length !== previous.length;
+	const next = [];
+	for (const [index, heading] of collected.entries()) {
+		const before = previousById.get(heading.id);
+		const pageNumber = (layout && layoutPageNumber(layout, heading.pmPos)) ?? before?.pageNumber ?? null;
+		const resolved = {
+			id: heading.id,
+			text: heading.text,
+			level: heading.level,
+			pmPos: heading.pmPos,
+			pageNumber
+		};
+		const kept = before && sameHeading(before, resolved) ? before : resolved;
+		if (kept !== previous[index]) changed = true;
+		next.push(kept);
+	}
+	return changed ? next : previous;
+};
+//#endregion
+export { resolveOutlineHeadings };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stll/folio-core",
-  "version": "0.63.1",
+  "version": "0.64.0",
   "description": "Headless, framework-neutral core of folio: the OOXML (.docx) parser, document model, ProseMirror integration, and page-layout engine. No React.",
   "keywords": [
     "document-model",