@stll/folio-core 0.1.2 → 0.2.0

package/dist/prosemirror/utils/visualLineNavigation.js

@@ -0,0 +1,217 @@
+import { findVerticalScrollParent } from "../../utils/findVerticalScrollParent.js";
+import { TextSelection } from "prosemirror-state";
+//#region src/prosemirror/utils/visualLineNavigation.ts
+/**
+* Visual line navigation helpers — implements Word/Google-Docs-style
+* ArrowUp / ArrowDown with sticky X across visual lines (not just
+* paragraphs). Lifted from packages/react/src/paged-editor/
+* useVisualLineNavigation.ts so both adapters share the algorithm.
+*
+* Frontend-agnostic: takes a `getContainer: () => HTMLElement | null`
+* callback and a mutable sticky-state object, returns the same
+* function quartet React's hook returns.
+*
+* @packageDocumentation
+* @internal
+*/
+const CONTENT_LINE_SELECTOR = ".layout-page-content .layout-line";
+/** @internal */
+function createVisualLineState() {
+	return {
+		stickyX: null,
+		lastVisualLineIndex: -1
+	};
+}
+function scrollIntoViewIfNeeded(el) {
+	const container = findVerticalScrollParent(el);
+	if (!container) return;
+	const elRect = el.getBoundingClientRect();
+	const containerRect = container.getBoundingClientRect();
+	const margin = 40;
+	if (elRect.bottom > containerRect.bottom - margin) container.scrollTop += elRect.bottom - containerRect.bottom + margin;
+	else if (elRect.top < containerRect.top + margin) container.scrollTop -= containerRect.top - elRect.top + margin;
+}
+/** @internal */
+function getCaretClientX(container, pmPos) {
+	const spans = container.querySelectorAll("span[data-pm-start][data-pm-end]");
+	for (const span of Array.from(spans)) {
+		const spanEl = span;
+		const pmStart = Number(spanEl.dataset["pmStart"]);
+		const pmEnd = Number(spanEl.dataset["pmEnd"]);
+		if (spanEl.classList.contains("layout-run-tab")) {
+			if (pmPos >= pmStart && pmPos < pmEnd) return spanEl.getBoundingClientRect().left;
+			continue;
+		}
+		if (pmPos >= pmStart && pmPos <= pmEnd && span.firstChild?.nodeType === Node.TEXT_NODE) {
+			const textNode = span.firstChild;
+			const charIndex = Math.min(pmPos - pmStart, textNode.length);
+			const ownerDoc = spanEl.ownerDocument;
+			if (!ownerDoc) continue;
+			const range = ownerDoc.createRange();
+			range.setStart(textNode, charIndex);
+			range.setEnd(textNode, charIndex);
+			return range.getBoundingClientRect().left;
+		}
+	}
+	const emptyRuns = container.querySelectorAll(".layout-empty-run");
+	for (const emptyRun of Array.from(emptyRuns)) {
+		const paragraph = emptyRun.closest(".layout-paragraph");
+		if (!paragraph) continue;
+		const pmStart = Number(paragraph.dataset["pmStart"]);
+		const pmEnd = Number(paragraph.dataset["pmEnd"]);
+		if (pmPos >= pmStart && pmPos <= pmEnd) return emptyRun.getBoundingClientRect().left;
+	}
+	return null;
+}
+/** @internal */
+function findLineElementAtPosition(container, pmPos) {
+	const allLines = container.querySelectorAll(CONTENT_LINE_SELECTOR);
+	for (const line of Array.from(allLines)) {
+		const lineEl = line;
+		const spans = lineEl.querySelectorAll("span[data-pm-start][data-pm-end]");
+		for (const span of Array.from(spans)) {
+			const s = span;
+			const start = Number(s.dataset["pmStart"]);
+			const end = Number(s.dataset["pmEnd"]);
+			if (pmPos >= start && pmPos <= end) return lineEl;
+		}
+	}
+	for (const line of Array.from(allLines)) {
+		const lineEl = line;
+		const paragraph = lineEl.closest(".layout-paragraph");
+		if (!paragraph) continue;
+		const pStart = Number(paragraph.dataset["pmStart"]);
+		const pEnd = Number(paragraph.dataset["pmEnd"]);
+		if (pmPos >= pStart && pmPos <= pEnd) {
+			if (paragraph.querySelector(".layout-line") === lineEl) return lineEl;
+		}
+	}
+	return null;
+}
+/** @internal */
+function findPositionOnLineAtClientX(lineEl, clientX) {
+	const spans = lineEl.querySelectorAll("span[data-pm-start][data-pm-end]");
+	if (spans.length === 0) {
+		const paragraph = lineEl.closest(".layout-paragraph");
+		if (paragraph?.dataset["pmStart"]) return Number(paragraph.dataset["pmStart"]) + 1;
+		return null;
+	}
+	for (const span of Array.from(spans)) {
+		const spanEl = span;
+		const rect = spanEl.getBoundingClientRect();
+		const pmStart = Number(spanEl.dataset["pmStart"]);
+		const pmEnd = Number(spanEl.dataset["pmEnd"]);
+		if (spanEl.classList.contains("layout-run-tab")) {
+			if (clientX >= rect.left && clientX <= rect.right) return clientX < (rect.left + rect.right) / 2 ? pmStart : pmEnd;
+			continue;
+		}
+		if (clientX >= rect.left && clientX <= rect.right) {
+			const textNode = spanEl.firstChild;
+			if (!textNode || textNode.nodeType !== Node.TEXT_NODE) return pmStart;
+			const text = textNode;
+			const ownerDoc = spanEl.ownerDocument;
+			if (!ownerDoc) return pmStart;
+			let lo = 0;
+			let hi = text.length;
+			while (lo < hi) {
+				const mid = Math.floor((lo + hi) / 2);
+				const r = ownerDoc.createRange();
+				r.setStart(text, mid);
+				r.setEnd(text, mid);
+				if (clientX < r.getBoundingClientRect().left) hi = mid;
+				else lo = mid + 1;
+			}
+			if (lo > 0 && lo <= text.length) {
+				const r = ownerDoc.createRange();
+				r.setStart(text, lo - 1);
+				r.setEnd(text, lo - 1);
+				const leftX = r.getBoundingClientRect().left;
+				r.setStart(text, Math.min(lo, text.length));
+				r.setEnd(text, Math.min(lo, text.length));
+				const rightX = r.getBoundingClientRect().left;
+				if (Math.abs(clientX - leftX) < Math.abs(clientX - rightX)) return pmStart + (lo - 1);
+			}
+			return pmStart + Math.min(lo, pmEnd - pmStart);
+		}
+	}
+	let closestSpan = null;
+	let closestDist = Infinity;
+	for (const span of Array.from(spans)) {
+		const spanEl = span;
+		const rect = spanEl.getBoundingClientRect();
+		const dist = clientX < rect.left ? rect.left - clientX : clientX - rect.right;
+		if (dist < closestDist) {
+			closestDist = dist;
+			closestSpan = spanEl;
+		}
+	}
+	if (!closestSpan) return null;
+	return clientX < closestSpan.getBoundingClientRect().left ? Number(closestSpan.dataset["pmStart"]) : Number(closestSpan.dataset["pmEnd"]);
+}
+/**
+* Handle PM ArrowUp / ArrowDown with visual-line awareness + sticky
+* X. Returns true if the event was handled and PM should not run
+* its default behaviour. Mutates `state` so consecutive presses
+* keep the same sticky X.
+*
+* @internal
+*/
+function handleVisualLineKeyDown(state, view, event, container) {
+	if (event.key !== "ArrowUp" && event.key !== "ArrowDown") {
+		if ([
+			"ArrowLeft",
+			"ArrowRight",
+			"Home",
+			"End"
+		].includes(event.key) || event.key.length === 1 && !event.ctrlKey && !event.metaKey) {
+			state.stickyX = null;
+			state.lastVisualLineIndex = -1;
+		}
+		return false;
+	}
+	if (event.ctrlKey || event.metaKey) {
+		state.stickyX = null;
+		state.lastVisualLineIndex = -1;
+		return false;
+	}
+	if (!container) return false;
+	const allLines = Array.from(container.querySelectorAll(CONTENT_LINE_SELECTOR));
+	if (allLines.length === 0) return false;
+	const { from, anchor } = view.state.selection;
+	if (state.stickyX === null) {
+		const clientX = getCaretClientX(container, from);
+		if (clientX === null) return false;
+		state.stickyX = clientX;
+	}
+	let currentIndex;
+	if (state.lastVisualLineIndex >= 0 && state.lastVisualLineIndex < allLines.length) currentIndex = state.lastVisualLineIndex;
+	else {
+		const currentLine = findLineElementAtPosition(container, from);
+		if (!currentLine) return false;
+		currentIndex = allLines.indexOf(currentLine);
+		if (currentIndex === -1) return false;
+	}
+	const targetIndex = event.key === "ArrowUp" ? currentIndex - 1 : currentIndex + 1;
+	if (targetIndex < 0 || targetIndex >= allLines.length) {
+		state.lastVisualLineIndex = -1;
+		return false;
+	}
+	const targetLine = allLines[targetIndex];
+	const newPos = findPositionOnLineAtClientX(targetLine, state.stickyX);
+	if (newPos === null) return false;
+	state.lastVisualLineIndex = targetIndex;
+	const { state: pmState, dispatch } = view;
+	const clampedPos = Math.max(0, Math.min(newPos, pmState.doc.content.size));
+	try {
+		const sel = event.shiftKey ? TextSelection.create(pmState.doc, anchor, clampedPos) : TextSelection.create(pmState.doc, clampedPos);
+		dispatch(pmState.tr.setSelection(sel));
+	} catch {
+		const $newPos = pmState.doc.resolve(clampedPos);
+		const sel = event.shiftKey ? TextSelection.between(pmState.doc.resolve(anchor), $newPos) : TextSelection.near($newPos);
+		dispatch(pmState.tr.setSelection(sel));
+	}
+	scrollIntoViewIfNeeded(targetLine);
+	return true;
+}
+//#endregion
+export { createVisualLineState, findLineElementAtPosition, findPositionOnLineAtClientX, getCaretClientX, handleVisualLineKeyDown };

package/dist/style-engine/index.d.ts

@@ -1,3 +1,3 @@
-import { ResolvedParagraphStyle } from "../prosemirror/styles/styleResolver.js";
+import { ResolvedParagraphStyle, TableCellParagraphSpacingOverlay } from "../prosemirror/styles/styleResolver.js";
 import { StyleEngine, StyleEngineCacheStats, StyleEngineOptions, createStyleEngine } from "./styleEngine.js";
-export { type ResolvedParagraphStyle, type StyleEngine, type StyleEngineCacheStats, type StyleEngineOptions, createStyleEngine };
+export { type ResolvedParagraphStyle, type StyleEngine, type StyleEngineCacheStats, type StyleEngineOptions, type TableCellParagraphSpacingOverlay, createStyleEngine };

package/dist/style-engine/styleEngine.d.ts

@@ -1,5 +1,5 @@
 import { document_d_exports } from "../types/document.js";
-import { ResolvedParagraphStyle } from "../prosemirror/styles/styleResolver.js";
+import { ResolvedParagraphStyle, TableCellParagraphSpacingOverlay } from "../prosemirror/styles/styleResolver.js";
 
 //#region src/style-engine/styleEngine.d.ts
 /** Engine construction options. */
@@ -41,6 +41,19 @@ type StyleEngine = {
    * Returned object is cached and must not be mutated.
    */
   resolveParagraphStyle: (styleId: string | undefined | null) => ResolvedParagraphStyle;
+  /**
+   * Resolve the paragraph cascade for a paragraph inside a table cell,
+   * layering the enclosing table style's paragraph-spacing fields between
+   * docDefaults and the paragraph's own style chain — see
+   * {@link StyleResolver.resolveParagraphStyleInTable}.
+   *
+   * Pass the *same* `tableParagraphOverlay` object reference for every
+   * paragraph governed by the same table style region (folio's table
+   * conversion already computes it once per region) — the cache below keys
+   * on object identity, so a fresh object per call defeats memoization.
+   * Returned object is cached and must not be mutated.
+   */
+  resolveParagraphStyleInTable: (styleId: string | undefined | null, tableParagraphOverlay: TableCellParagraphSpacingOverlay | undefined) => ResolvedParagraphStyle;
   /**
    * Resolve a run/character style with docDefaults applied.
    * Returns `undefined` when the cascade yields nothing.

package/dist/style-engine/styleEngine.js

@@ -23,6 +23,7 @@ function createStyleEngine(styleDefinitions, options) {
 	const paragraphCache = /* @__PURE__ */ new Map();
 	const runCache = /* @__PURE__ */ new Map();
 	const ownPropsCache = /* @__PURE__ */ new Map();
+	let tableOverlayCache = /* @__PURE__ */ new WeakMap();
 	let hits = 0;
 	let misses = 0;
 	const memoize = (cache, key, compute) => {
@@ -40,6 +41,18 @@ function createStyleEngine(styleDefinitions, options) {
 		cache.set(key, { value });
 		return value;
 	};
+	const memoizeInTable = (styleId, tableParagraphOverlay) => {
+		if (!cacheEnabled) {
+			misses += 1;
+			return resolver.resolveParagraphStyleInTable(styleId, tableParagraphOverlay);
+		}
+		let overlayCache = tableOverlayCache.get(tableParagraphOverlay);
+		if (!overlayCache) {
+			overlayCache = /* @__PURE__ */ new Map();
+			tableOverlayCache.set(tableParagraphOverlay, overlayCache);
+		}
+		return memoize(overlayCache, cacheKey(styleId), () => resolver.resolveParagraphStyleInTable(styleId, tableParagraphOverlay));
+	};
 	return {
 		getStyle: (styleId) => resolver.getStyle(styleId),
 		hasStyle: (styleId) => resolver.hasStyle(styleId),
@@ -50,12 +63,14 @@ function createStyleEngine(styleDefinitions, options) {
 		getParagraphStyles: () => resolver.getParagraphStyles(),
 		getTableStyles: () => resolver.getTableStyles(),
 		resolveParagraphStyle: (styleId) => memoize(paragraphCache, cacheKey(styleId), () => resolver.resolveParagraphStyle(styleId)),
+		resolveParagraphStyleInTable: (styleId, tableParagraphOverlay) => tableParagraphOverlay === void 0 ? memoize(paragraphCache, cacheKey(styleId), () => resolver.resolveParagraphStyleInTable(styleId, void 0)) : memoizeInTable(styleId, tableParagraphOverlay),
 		resolveRunStyle: (styleId) => memoize(runCache, cacheKey(styleId), () => resolver.resolveRunStyle(styleId)),
 		getRunStyleOwnProperties: (styleId) => memoize(ownPropsCache, cacheKey(styleId), () => resolver.getRunStyleOwnProperties(styleId)),
 		invalidate: () => {
 			paragraphCache.clear();
 			runCache.clear();
 			ownPropsCache.clear();
+			tableOverlayCache = /* @__PURE__ */ new WeakMap();
 			hits = 0;
 			misses = 0;
 		},

package/dist/utils/colorResolver.d.ts

@@ -16,6 +16,13 @@ declare function resolveColor(color: document_d_exports.ColorValue | undefined |
  * @param highlight - Highlight color name (e.g., "yellow", "cyan")
  * @returns CSS color string or empty string for "none"
  */
+/**
+ * Resolve a `ColorValue` to a bare 6-digit hex string (no leading `#`), or
+ * `undefined` for an `auto`/absent color. Theme colors resolve through the
+ * document theme; explicit `rgb` values are upper-cased. Used by adapters that
+ * need a normalized hex (e.g. comparing a cell fill against a swatch).
+ */
+declare function resolveColorToHex(color: document_d_exports.ColorValue | undefined | null, theme: document_d_exports.Theme | null | undefined): string | undefined;
 declare function resolveHighlightColor(highlight: string | undefined): string;
 /**
  * Resolve a shading fill or pattern color to CSS
@@ -155,4 +162,4 @@ declare function generateThemeTintShadeMatrix(colorScheme?: document_d_exports.T
  */
 declare function colorsEqual(color1: document_d_exports.ColorValue | undefined | null, color2: document_d_exports.ColorValue | undefined | null, theme: document_d_exports.Theme | null | undefined): boolean;
 //#endregion
-export { STANDARD_TEXT_COLORS, ThemeMatrixCell, blendColors, colorsEqual, createRgbColor, createThemeColor, darkenColor, ensureHexPrefix, generateThemeTintShadeMatrix, getContrastingColor, getThemeTintShadeHex, isBlack, isWhite, lightenColor, parseColorString, resolveColor, resolveHighlightColor, resolveHighlightToCss, resolveShadingColor };
+export { STANDARD_TEXT_COLORS, ThemeMatrixCell, blendColors, colorsEqual, createRgbColor, createThemeColor, darkenColor, ensureHexPrefix, generateThemeTintShadeMatrix, getContrastingColor, getThemeTintShadeHex, isBlack, isWhite, lightenColor, parseColorString, resolveColor, resolveColorToHex, resolveHighlightColor, resolveHighlightToCss, resolveShadingColor };

package/dist/utils/colorResolver.js

@@ -218,6 +218,17 @@ function resolveColor(color, theme, defaultColor = "000000") {
 * @param highlight - Highlight color name (e.g., "yellow", "cyan")
 * @returns CSS color string or empty string for "none"
 */
+/**
+* Resolve a `ColorValue` to a bare 6-digit hex string (no leading `#`), or
+* `undefined` for an `auto`/absent color. Theme colors resolve through the
+* document theme; explicit `rgb` values are upper-cased. Used by adapters that
+* need a normalized hex (e.g. comparing a cell fill against a swatch).
+*/
+function resolveColorToHex(color, theme) {
+	if (!color || color.auto) return void 0;
+	if (color.themeColor && theme) return resolveColor(color, theme).slice(1);
+	if (color.rgb && color.rgb !== "auto") return color.rgb.toUpperCase().replace(/^#/, "");
+}
 function resolveHighlightColor(highlight) {
 	if (!highlight || highlight === "none") return "";
 	const hex = HIGHLIGHT_COLORS[highlight];
@@ -554,4 +565,4 @@ function colorsEqual(color1, color2, theme) {
 	return resolveColor(color1, theme).toUpperCase() === resolveColor(color2, theme).toUpperCase();
 }
 //#endregion
-export { STANDARD_TEXT_COLORS, blendColors, colorsEqual, createRgbColor, createThemeColor, darkenColor, ensureHexPrefix, generateThemeTintShadeMatrix, getContrastingColor, getThemeTintShadeHex, isBlack, isWhite, lightenColor, parseColorString, resolveColor, resolveHighlightColor, resolveHighlightToCss, resolveShadingColor };
+export { STANDARD_TEXT_COLORS, blendColors, colorsEqual, createRgbColor, createThemeColor, darkenColor, ensureHexPrefix, generateThemeTintShadeMatrix, getContrastingColor, getThemeTintShadeHex, isBlack, isWhite, lightenColor, parseColorString, resolveColor, resolveColorToHex, resolveHighlightColor, resolveHighlightToCss, resolveShadingColor };

package/dist/utils/findVerticalScrollParent.d.ts

@@ -0,0 +1,20 @@
+//#region src/utils/findVerticalScrollParent.d.ts
+/**
+ * Pure DOM helpers — locate the element that vertically scrolls the paginated
+ * editor. Shared by scroll-to-position, arrow-key line navigation, and drag
+ * auto-scroll so every framework adapter uses the same logic.
+ */
+/**
+ * First ancestor of `el` with `overflow-y: auto|scroll` and a scrollable
+ * overflow height. The walk starts at `el.parentElement` (it does not treat
+ * `el` itself as the scroller). Returns `null` when no such ancestor exists
+ * before `document.documentElement`.
+ */
+declare function findVerticalScrollParent(el: HTMLElement): HTMLElement | null;
+/**
+ * Same as {@link findVerticalScrollParent} but falls back to
+ * `document.documentElement` so callers always get a valid scroll target.
+ */
+declare function findVerticalScrollParentOrRoot(el: HTMLElement): HTMLElement;
+//#endregion
+export { findVerticalScrollParent, findVerticalScrollParentOrRoot };

package/dist/utils/findVerticalScrollParent.js

@@ -0,0 +1,30 @@
+//#region src/utils/findVerticalScrollParent.ts
+/**
+* Pure DOM helpers — locate the element that vertically scrolls the paginated
+* editor. Shared by scroll-to-position, arrow-key line navigation, and drag
+* auto-scroll so every framework adapter uses the same logic.
+*/
+/**
+* First ancestor of `el` with `overflow-y: auto|scroll` and a scrollable
+* overflow height. The walk starts at `el.parentElement` (it does not treat
+* `el` itself as the scroller). Returns `null` when no such ancestor exists
+* before `document.documentElement`.
+*/
+function findVerticalScrollParent(el) {
+	let parent = el.parentElement;
+	while (parent && parent !== document.documentElement) {
+		const { overflowY } = getComputedStyle(parent);
+		if ((overflowY === "auto" || overflowY === "scroll") && parent.scrollHeight > parent.clientHeight + 1) return parent;
+		parent = parent.parentElement;
+	}
+	return null;
+}
+/**
+* Same as {@link findVerticalScrollParent} but falls back to
+* `document.documentElement` so callers always get a valid scroll target.
+*/
+function findVerticalScrollParentOrRoot(el) {
+	return findVerticalScrollParent(el) ?? document.documentElement;
+}
+//#endregion
+export { findVerticalScrollParent, findVerticalScrollParentOrRoot };

package/dist/utils/fontResolver.d.ts

@@ -7,7 +7,7 @@ type ResolvedFont = {
   /** Google Font name to load (null if no mapping available) */googleFont: string | null; /** CSS font-family value with proper fallback stack */
   cssFallback: string; /** Original font name from the DOCX */
   originalFont: string; /** Whether this font has a Google Fonts equivalent */
-  hasGoogleEquivalent: boolean; /** OS/2 single-line ratio: (usWinAscent + usWinDescent) / unitsPerEm (no external leading) */
+  hasGoogleEquivalent: boolean; /** Single-line height ratio (single-line height ÷ font size). See `FontLineHeight`. */
   singleLineRatio: number;
 };
 /**
@@ -15,10 +15,29 @@ type ResolvedFont = {
  */
 type FontCategory = "sans-serif" | "serif" | "monospace" | "cursive" | "fantasy" | "system-ui";
 /**
- * Default OS/2 single-line ratio for unmapped fonts.
+ * Default single-line ratio for unmapped fonts.
  * Middle of the common range (1.07–1.27) for standard DOCX fonts.
  */
 declare const DEFAULT_SINGLE_LINE_RATIO = 1.15;
+/**
+ * True when `family` is a known East-Asian (CJK) typeface — a direct
+ * `FONT_MAPPINGS` CJK entry or a romanized alias of one. Used by the measurer
+ * to decide whether a run's `w:eastAsia` font can supply the line height for
+ * CJK text, or whether Word would font-link to a default East-Asian face
+ * instead (see `CJK_FALLBACK_FONT_FAMILY`). Unmapped families return false:
+ * we cannot know their metrics, so the caller falls back.
+ */
+declare function isCjkFont(family: string): boolean;
+/**
+ * Font family whose `singleLineRatio` stands in for Word's default East-Asian
+ * face when a CJK-text run declares no usable CJK font (its `w:eastAsia` slot
+ * is absent or names a Latin face like "Century"). Word font-links those
+ * glyphs to the OS default East-Asian font and takes THAT face's taller line
+ * height; MS Mincho carries the measured ratio for it
+ * (`JP_MEASURED_LINE_HEIGHT`, ≈1.303). Line-height resolution only — never
+ * used for width measurement or painting.
+ */
+declare const CJK_FALLBACK_FONT_FAMILY = "MS Mincho";
 declare function resolveFontFamily(docxFontName: string): ResolvedFont;
 /**
  * Resolve a theme font reference to actual font names
@@ -58,4 +77,4 @@ declare function getGoogleFontEquivalent(docxFontName: string): string | null;
  */
 declare function hasGoogleFontEquivalent(docxFontName: string): boolean;
 //#endregion
-export { DEFAULT_SINGLE_LINE_RATIO, ResolvedFont, buildFontFamilyString, getGoogleFontEquivalent, getGoogleFontsToLoad, hasGoogleFontEquivalent, resolveFontFamily, resolveThemeFont };
+export { CJK_FALLBACK_FONT_FAMILY, DEFAULT_SINGLE_LINE_RATIO, ResolvedFont, buildFontFamilyString, getGoogleFontEquivalent, getGoogleFontsToLoad, hasGoogleFontEquivalent, isCjkFont, resolveFontFamily, resolveThemeFont };