@stll/folio-core 0.1.2 → 0.2.0

package/dist/layout-painter/imageLayout.js

@@ -0,0 +1,161 @@
+import { pixelsToEmu } from "../utils/units.js";
+//#region src/layout-painter/imageLayout.ts
+const LAYOUT_IMAGE_CLASSES = {
+	/** Inline image rendered inside `.layout-line`. */
+	runImage: "layout-run-image",
+	/** Block (centered, topAndBottom) image. */
+	blockImage: "layout-block-image",
+	/** Anchored image rendered in the page-level floating layer. */
+	pageFloatingImage: "layout-page-floating-image",
+	/** Anchored image rendered inside a table cell's floating layer. */
+	cellFloatingImage: "layout-cell-floating-image",
+	pageContent: "layout-page-content",
+	paragraph: "layout-paragraph"
+};
+const IMAGE_HIT_SELECTOR = [
+	`.${LAYOUT_IMAGE_CLASSES.pageFloatingImage}`,
+	`.${LAYOUT_IMAGE_CLASSES.cellFloatingImage}`,
+	`.${LAYOUT_IMAGE_CLASSES.blockImage}`,
+	`.${LAYOUT_IMAGE_CLASSES.runImage}`
+].join(", ");
+/**
+* Walk up from a click target to the nearest rendered image element, returning
+* just the element (no PM position parsing). Used by the left-click selection
+* path in both adapters — `data-pm-start` is read separately by callers that
+* need the position. Returns the element when the click was directly on an
+* inline `<img.layout-run-image>` OR inside one of the container classes
+* registered in `LAYOUT_IMAGE_CLASSES`.
+*/
+function findImageElement(target) {
+	if (!(target instanceof HTMLElement)) return null;
+	if (target.tagName === "IMG" && target.classList.contains(LAYOUT_IMAGE_CLASSES.runImage)) return target;
+	const container = target.closest(IMAGE_HIT_SELECTOR);
+	if (container && container.dataset["pmStart"]) return container;
+	return null;
+}
+/**
+* Capture the rendered position of an inline image as EMUs, normalised to
+* unzoomed coordinates. Returns horizontal offset relative to the page
+* content area (column origin) and vertical offset relative to the
+* containing paragraph — matches the OOXML attrs the resolver writes
+* (`relativeFrom: 'column'` / `relativeFrom: 'paragraph'`).
+*
+* `zoom` defaults to 1; pass the editor's current zoom factor when the
+* pages container has a CSS scale applied so `getBoundingClientRect` deltas
+* are converted back to authored-pixel space before going to EMU.
+*
+* Returns undefined for non-inline images or detached DOM.
+*/
+function captureInlinePositionEmu(imageEl, zoom = 1) {
+	if (!imageEl.classList.contains(LAYOUT_IMAGE_CLASSES.runImage)) return;
+	const pageContent = imageEl.closest(`.${LAYOUT_IMAGE_CLASSES.pageContent}`);
+	const paragraph = imageEl.closest(`.${LAYOUT_IMAGE_CLASSES.paragraph}`);
+	if (!pageContent || !paragraph) return;
+	const imgRect = imageEl.getBoundingClientRect();
+	const pageRect = pageContent.getBoundingClientRect();
+	const paraRect = paragraph.getBoundingClientRect();
+	const safeZoom = zoom > 0 ? zoom : 1;
+	return {
+		horizontalEmu: Math.round(pixelsToEmu((imgRect.left - pageRect.left) / safeZoom)),
+		verticalEmu: Math.round(pixelsToEmu((imgRect.top - paraRect.top) / safeZoom))
+	};
+}
+/**
+* Map an image's current OOXML attrs onto the menu's choice vocabulary so the
+* menu can highlight the active option. Returns null for `topAndBottom` and
+* any unknown wrap type — those don't have a directional menu entry.
+*
+* `cssFloat` accepts both `null` and `undefined` so framework adapters can
+* use either as their "unset" sentinel without an extra normalisation step.
+*/
+function deriveLayoutChoice(wrapType, cssFloat) {
+	if (wrapType === "inline") return "inline";
+	if (wrapType === "behind") return "behind";
+	if (wrapType === "inFront") return "inFront";
+	if (wrapType === "square" || wrapType === "tight" || wrapType === "through") return cssFloat === "right" ? "squareRight" : "squareLeft";
+	return null;
+}
+/** Mirrors Word's Wrap Text menu — five directional options. */
+const IMAGE_LAYOUT_OPTIONS = [
+	{
+		choice: "inline",
+		i18nLabelKey: "inLineWithText",
+		i18nDescKey: "inLineWithText",
+		iconHint: "inline"
+	},
+	{
+		choice: "squareLeft",
+		i18nLabelKey: "squareLeft",
+		i18nDescKey: "squareLeft",
+		iconHint: "squareLeft"
+	},
+	{
+		choice: "squareRight",
+		i18nLabelKey: "squareRight",
+		i18nDescKey: "squareRight",
+		iconHint: "squareRight"
+	},
+	{
+		choice: "behind",
+		i18nLabelKey: "behindText",
+		i18nDescKey: "behindText",
+		iconHint: "behind"
+	},
+	{
+		choice: "inFront",
+		i18nLabelKey: "inFrontOfText",
+		i18nDescKey: "inFrontOfText",
+		iconHint: "inFront"
+	}
+];
+/**
+* Whether a given option is enabled for an image with the given current wrap
+* type. Every option stays clickable — picking the option that matches the
+* current state is a no-op (the PM command early-returns), which matches
+* Word's behavior. Kept around for forward-compatibility (e.g. future
+* read-only mode), but currently always returns true.
+*/
+function isImageLayoutOptionEnabled(_option, _currentWrapType) {
+	return true;
+}
+/**
+* Translate the legacy toolbar wrap-type vocabulary (`wrapLeft` / `wrapRight`
+* / `square` / `tight` / `through` / `topAndBottom` / `behind` / `inFront` /
+* `inline`) into an `ImageLayoutTarget` so toolbar dispatch shares the same PM
+* command path as the right-click menu.
+*
+* Returns `undefined` for unknown values; callers should treat that as
+* "no-op".
+*/
+function toolbarValueToLayoutTarget(value) {
+	switch (value) {
+		case "inline": return "inline";
+		case "square":
+		case "tight":
+		case "through": return "squareLeft";
+		case "topAndBottom": return "topAndBottom";
+		case "behind": return "behind";
+		case "inFront": return "inFront";
+		case "wrapRight": return "squareLeft";
+		case "wrapLeft": return "squareRight";
+		default: return;
+	}
+}
+/**
+* Build the painter's `block.id → { block, measure }` lookup from the parallel
+* blocks/measures arrays. Shared by both adapters' paint step.
+*/
+function buildBlockLookup(blocks, measures) {
+	const lookup = /* @__PURE__ */ new Map();
+	for (let i = 0; i < blocks.length; i++) {
+		const block = blocks[i];
+		const measure = measures[i];
+		if (block && measure) lookup.set(String(block.id), {
+			block,
+			measure
+		});
+	}
+	return lookup;
+}
+//#endregion
+export { IMAGE_LAYOUT_OPTIONS, LAYOUT_IMAGE_CLASSES, buildBlockLookup, captureInlinePositionEmu, deriveLayoutChoice, findImageElement, isImageLayoutOptionEnabled, toolbarValueToLayoutTarget };

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

@@ -242,6 +242,21 @@ type PainterPaintedDetail = {
   container: HTMLElement;
   pageCount: number;
 };
+/**
+ * Force every virtualized page shell in `container` to be fully rendered.
+ *
+ * Virtualization keeps off-screen pages as empty shells, so cloning the pages
+ * container for print (or any DOM snapshot) yields blank pages past the visible
+ * band. Callers that need every page populated — print, export-to-HTML, pdf
+ * snapshot — should call this first.
+ *
+ * No-op for small documents (rendered eagerly) or containers that were never
+ * managed by `renderPages`. Returns the number of shells populated by this
+ * call (useful for tests).
+ *
+ * Ported from eigenpal/docx-editor `layout-painter/renderPage/virtualization.ts`.
+ */
+declare function renderAllPagesNow(container: HTMLElement): number;
 /**
  * Find the page shell whose layout fragments cover (or are nearest
  * before) a given ProseMirror position. Returns null if the
@@ -261,4 +276,4 @@ declare function findPageShellForPmPos(container: HTMLElement, pmPos: number): {
   isExact: boolean;
 } | null;
 //#endregion
-export { AnchoredImagePosition, FootnoteRenderItem, type HeaderFooterContent, HeaderFooterLayoutInfo, PAGE_CLASS_NAMES, PAINTER_PAINTED_EVENT, PageFloatingImage, PageGeometry, PainterPaintedDetail, type RenderContext, RenderPageOptions, applySectionHeaderFooterOptions, calculateFootnoteAreaRenderHeight, computePageFingerprint, emuToPixels, findPageShellForPmPos, getDefaultPageFontFamily, isFloatingImageRun, renderFloatingImagesLayer, renderFootnoteArea, renderPage, renderPages, resolveAnchoredImagePosition, resolveHeaderFooterFloatLeft };
+export { AnchoredImagePosition, FootnoteRenderItem, type HeaderFooterContent, HeaderFooterLayoutInfo, PAGE_CLASS_NAMES, PAINTER_PAINTED_EVENT, PageFloatingImage, PageGeometry, PainterPaintedDetail, type RenderContext, RenderPageOptions, applySectionHeaderFooterOptions, calculateFootnoteAreaRenderHeight, computePageFingerprint, emuToPixels, findPageShellForPmPos, getDefaultPageFontFamily, isFloatingImageRun, renderAllPagesNow, renderFloatingImagesLayer, renderFootnoteArea, renderPage, renderPages, resolveAnchoredImagePosition, resolveHeaderFooterFloatLeft };

package/dist/layout-painter/renderPage.js

@@ -1668,6 +1668,33 @@ function populatePageShell(shell, pageDataMap, totalPages, options) {
 	if (container instanceof HTMLElement) emitPainterPainted(container);
 }
 /**
+* Force every virtualized page shell in `container` to be fully rendered.
+*
+* Virtualization keeps off-screen pages as empty shells, so cloning the pages
+* container for print (or any DOM snapshot) yields blank pages past the visible
+* band. Callers that need every page populated — print, export-to-HTML, pdf
+* snapshot — should call this first.
+*
+* No-op for small documents (rendered eagerly) or containers that were never
+* managed by `renderPages`. Returns the number of shells populated by this
+* call (useful for tests).
+*
+* Ported from eigenpal/docx-editor `layout-painter/renderPage/virtualization.ts`.
+*/
+function renderAllPagesNow(container) {
+	const state = container.__pageRenderState;
+	if (!state) return 0;
+	const { pageStates, totalPages, currentOptions, pageDataMap } = state;
+	let populated = 0;
+	for (const { element } of pageStates) {
+		const data = pageDataMap.get(element);
+		if (!data || data.rendered) continue;
+		populatePageShell(element, pageDataMap, totalPages, currentOptions);
+		populated++;
+	}
+	return populated;
+}
+/**
 * Surgically replace only the content area of a rendered page shell.
 * Preserves header/footer elements to avoid blinking.
 */
@@ -1792,4 +1819,4 @@ function depopulatePageShell(shell, pageDataMap) {
 	}
 }
 //#endregion
-export { PAGE_CLASS_NAMES, PAINTER_PAINTED_EVENT, applySectionHeaderFooterOptions, calculateFootnoteAreaRenderHeight, computePageFingerprint, emuToPixels, findPageShellForPmPos, getDefaultPageFontFamily, isFloatingImageRun, renderFloatingImagesLayer, renderFootnoteArea, renderPage, renderPages, resolveAnchoredImagePosition, resolveHeaderFooterFloatLeft };
+export { PAGE_CLASS_NAMES, PAINTER_PAINTED_EVENT, applySectionHeaderFooterOptions, calculateFootnoteAreaRenderHeight, computePageFingerprint, emuToPixels, findPageShellForPmPos, getDefaultPageFontFamily, isFloatingImageRun, renderAllPagesNow, renderFloatingImagesLayer, renderFootnoteArea, renderPage, renderPages, resolveAnchoredImagePosition, resolveHeaderFooterFloatLeft };

package/dist/layout-painter/renderParagraph.js

@@ -3,6 +3,7 @@ import { resolveFontFamily } from "../utils/fontResolver.js";
 import "../utils/fontWeights.js";
 import { calculateTabWidth } from "../prosemirror/utils/tabCalculator.js";
 import { inlineImageBoundingBox, parseRotationDegrees, rotatedBoundingBox } from "../utils/rotationBoundingBox.js";
+import { hasCjk, segmentByScript } from "../utils/scriptSegments.js";
 import { isFloatingImageRun } from "../layout-engine/types.js";
 import { getListMarkerInlineWidth } from "../layout-engine/measure/listMarkerWidth.js";
 import { applySdtDataAttrs } from "./sdtBoundary.js";
@@ -11,7 +12,6 @@ import { ommlToMathml } from "../docx/mathToMathml.js";
 import { evaluateFieldInstruction } from "../fields/evaluateField.js";
 import { AUTHOR_COLORS, getAuthorColorIdx } from "../utils/authorColors.js";
 import { detectBaseDirection } from "../utils/baseDirection.js";
-import { hasCjk, segmentByScript } from "../utils/scriptSegments.js";
 import { getAutomaticTextColorForBackground } from "./documentColors.js";
 import { resolveImageLineAlign } from "./renderUtils.js";
 //#region src/layout-painter/renderParagraph.ts
@@ -1075,6 +1075,7 @@ function renderParagraphFragment(fragment, block, measure, context, options = {}
 	fragmentEl.className = PARAGRAPH_CLASS_NAMES.fragment;
 	fragmentEl.style.position = "relative";
 	fragmentEl.dataset["blockId"] = String(fragment.blockId);
+	if (block.paraId) fragmentEl.dataset["paraId"] = block.paraId;
 	fragmentEl.dataset["fromLine"] = String(fragment.fromLine);
 	fragmentEl.dataset["toLine"] = String(fragment.toLine);
 	applyPmPositions(fragmentEl, fragment.pmStart, fragment.pmEnd);

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

@@ -1,6 +1,29 @@
 import { SdtGroup } from "../layout-engine/types.js";
+import { Node } from "prosemirror-model";
 
 //#region src/layout-painter/sdtBoundary.d.ts
 declare function applySdtDataAttrs(el: HTMLElement, sdtGroups: readonly SdtGroup[] | undefined): void;
+/**
+ * Identities of every block-level content control (`w:sdt`) that encloses the
+ * given selection — used to keep a control's boundary visible while the caret
+ * is inside it (Word-style focus), independent of mouse hover. Both ends of a
+ * range are collected so a selection straddling a control still lights it up.
+ *
+ * Ported from eigenpal/docx-editor `layout-painter/sdtBoundary.ts`. Upstream
+ * keyed the set on `sdt@${pos}` to match per-control boundary boxes; this fork
+ * stamps the SDT node's PM position as `data-sdt-pm-pos` on the painted block
+ * elements (see `applySdtDataAttrs`), so the identity here is the stringified
+ * `$pos.before(d)` — which is exactly that PM position — keeping the returned
+ * ids in lockstep with what `applySdtFocus` hit-tests against.
+ */
+declare function enclosingSdtGroupIds(doc: Node, from: number, to: number): Set<string>;
+/**
+ * Toggle the `.is-focused` reveal class on every painted block whose enclosing
+ * content control encloses the caret. Kept separate from any hover-driven
+ * reveal so the two paths never clear each other. Matches the fork's
+ * `data-sdt-pm-pos` stamping (upstream matched `.layout-block-sdt-box`'s
+ * `data-sdt-group-id`, which this fork does not paint).
+ */
+declare function applySdtFocus(container: HTMLElement, focusedIds: Set<string>): void;
 //#endregion
-export { applySdtDataAttrs };
+export { applySdtDataAttrs, applySdtFocus, enclosingSdtGroupIds };

package/dist/layout-painter/sdtBoundary.js

@@ -24,5 +24,44 @@ function applySdtDataAttrs(el, sdtGroups) {
 		alias: g.alias ?? null
 	})));
 }
+/**
+* Identities of every block-level content control (`w:sdt`) that encloses the
+* given selection — used to keep a control's boundary visible while the caret
+* is inside it (Word-style focus), independent of mouse hover. Both ends of a
+* range are collected so a selection straddling a control still lights it up.
+*
+* Ported from eigenpal/docx-editor `layout-painter/sdtBoundary.ts`. Upstream
+* keyed the set on `sdt@${pos}` to match per-control boundary boxes; this fork
+* stamps the SDT node's PM position as `data-sdt-pm-pos` on the painted block
+* elements (see `applySdtDataAttrs`), so the identity here is the stringified
+* `$pos.before(d)` — which is exactly that PM position — keeping the returned
+* ids in lockstep with what `applySdtFocus` hit-tests against.
+*/
+function enclosingSdtGroupIds(doc, from, to) {
+	const ids = /* @__PURE__ */ new Set();
+	const max = doc.content.size;
+	const collect = (pos) => {
+		const $pos = doc.resolve(Math.max(0, Math.min(pos, max)));
+		for (let d = 1; d <= $pos.depth; d++) if ($pos.node(d).type.name === "blockSdt") ids.add(String($pos.before(d)));
+	};
+	collect(from);
+	if (to !== from) collect(to);
+	return ids;
+}
+/**
+* Toggle the `.is-focused` reveal class on every painted block whose enclosing
+* content control encloses the caret. Kept separate from any hover-driven
+* reveal so the two paths never clear each other. Matches the fork's
+* `data-sdt-pm-pos` stamping (upstream matched `.layout-block-sdt-box`'s
+* `data-sdt-group-id`, which this fork does not paint).
+*/
+function applySdtFocus(container, focusedIds) {
+	const boxes = container.querySelectorAll("[data-sdt-boundary]");
+	for (const box of boxes) {
+		const id = box.dataset["sdtPmPos"];
+		const on = id != null && focusedIds.has(id);
+		if (on !== box.classList.contains("is-focused")) box.classList.toggle("is-focused", on);
+	}
+}
 //#endregion
-export { applySdtDataAttrs };
+export { applySdtDataAttrs, applySdtFocus, enclosingSdtGroupIds };

package/dist/managers/AutoSaveManager.d.ts

@@ -0,0 +1,89 @@
+import { document_d_exports } from "../types/document.js";
+import { Subscribable } from "./Subscribable.js";
+
+//#region src/managers/AutoSaveManager.d.ts
+/** Auto-save status. */
+type AutoSaveStatus = "idle" | "saving" | "saved" | "error";
+/** Configuration for {@link AutoSaveManager}. */
+type AutoSaveManagerOptions = {
+  /** Storage key for localStorage (default: 'docx-editor-autosave'). */storageKey?: string; /** Save interval in milliseconds (default: 30000 - 30 seconds). */
+  interval?: number; /** Maximum age of auto-save before it is considered stale (default: 24 hours). */
+  maxAge?: number; /** Whether to save on document change with debounce (default: true). */
+  saveOnChange?: boolean; /** Debounce delay for saveOnChange in milliseconds (default: 2000). */
+  debounceDelay?: number; /** Callback when save succeeds. */
+  onSave?: (timestamp: Date) => void; /** Callback when save fails. */
+  onError?: (error: Error) => void; /** Callback when recovery data is found. */
+  onRecoveryAvailable?: (savedDocument: SavedDocumentData) => void;
+};
+/** Saved document data structure. */
+type SavedDocumentData = {
+  /** The document. */document: document_d_exports.Document; /** When the document was saved (ISO string). */
+  savedAt: string; /** Version for format compatibility. */
+  version: number; /** Optional document identifier. */
+  documentId?: string;
+};
+/** AutoSaveManager snapshot for UI consumption. */
+type AutoSaveSnapshot = {
+  status: AutoSaveStatus;
+  lastSaveTime: Date | null;
+  hasRecoveryData: boolean;
+  isEnabled: boolean;
+};
+declare class AutoSaveManager extends Subscribable<AutoSaveSnapshot> {
+  private readonly storageKey;
+  private readonly interval;
+  private readonly maxAge;
+  private readonly saveOnChange;
+  private readonly debounceDelay;
+  private readonly onSaveCallback;
+  private readonly onErrorCallback;
+  private readonly onRecoveryAvailableCallback;
+  private readonly storageAvailable;
+  private currentDocument;
+  private lastSavedJson;
+  private intervalTimer;
+  private debounceTimer;
+  private status;
+  private lastSaveTime;
+  private hasRecoveryData;
+  private isEnabled;
+  constructor(options?: AutoSaveManagerOptions);
+  /** Update the current document. Triggers a debounced save if enabled. */
+  onDocumentChanged(document: document_d_exports.Document | null): void;
+  /** Manually trigger a save. */
+  save(): boolean;
+  /** Clear auto-saved data from storage. */
+  clear(): void;
+  /** Get recovery data from storage. */
+  getRecoveryData(): SavedDocumentData | null;
+  /** Accept recovery and return the document. */
+  acceptRecovery(): document_d_exports.Document | null;
+  /** Dismiss recovery and clear saved data. */
+  dismissRecovery(): void;
+  /** Enable auto-save and start the interval timer. */
+  enable(): void;
+  /** Disable auto-save and stop all timers. */
+  disable(): void;
+  /** Start the interval timer. Call after enabling or on init. */
+  startInterval(): void;
+  /** Save synchronously on destroy (best-effort). */
+  destroy(): void;
+  private checkRecoveryData;
+  private persistToStorage;
+  private debounceSave;
+  private stopTimers;
+  private updateStatus;
+  private emitSnapshot;
+}
+/** Format last save time for display. */
+declare function formatLastSaveTime(date: Date | null): string;
+/** Get auto-save status label. */
+declare function getAutoSaveStatusLabel(status: AutoSaveStatus): string;
+/** Get storage size used by auto-save (bytes). */
+declare function getAutoSaveStorageSize(storageKey?: string): number;
+/** Format storage size for display. */
+declare function formatStorageSize(bytes: number): string;
+/** Check whether auto-save is supported. */
+declare function isAutoSaveSupported(): boolean;
+//#endregion
+export { AutoSaveManager, AutoSaveManagerOptions, AutoSaveSnapshot, AutoSaveStatus, SavedDocumentData, formatLastSaveTime, formatStorageSize, getAutoSaveStatusLabel, getAutoSaveStorageSize, isAutoSaveSupported };