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

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

@@ -0,0 +1,264 @@
+import { document_d_exports } from "../types/document.js";
+import { FootnoteContent, HeaderFooterContent, ImageRun, Page, isFloatingImageRun } from "../layout-engine/types.js";
+import { RenderContext, emuToPixels } from "./renderUtils.js";
+import { BlockLookup } from "./index.js";
+
+//#region src/layout-painter/renderPage.d.ts
+/**
+ * Page-level floating image that has been extracted from paragraphs.
+ * These are positioned absolutely within the page's content area.
+ */
+type PageFloatingImage = {
+  src: string;
+  width: number;
+  height: number;
+  alt?: string;
+  transform?: string;
+  /**
+   * Opacity in [0, 1] from `<a:alphaModFix amt>`. Undefined / 1 means fully
+   * opaque. eigenpal #424 (opacity render pipeline).
+   */
+  opacity?: number; /** Which side: 'left' for left margin, 'right' for right margin */
+  side: "left" | "right"; /** X position relative to content area (0 = left edge of content) */
+  x: number; /** Y position relative to content area (0 = top of content) */
+  y: number; /** Wrap distances */
+  distTop: number;
+  distBottom: number;
+  distLeft: number;
+  distRight: number; /** ProseMirror start position for click-to-select */
+  pmStart?: number; /** ProseMirror end position */
+  pmEnd?: number; /** OOXML wrapText: which side(s) TEXT flows on */
+  wrapText?: "bothSides" | "left" | "right" | "largest"; /** Wrap type (square, tight, through, topAndBottom, behind, inFront) */
+  wrapType?: string;
+  /**
+   * Whether this image creates a text-wrap exclusion zone (line widths shrink
+   * around it). False for `behind`/`inFront` (wrapNone) and `topAndBottom`.
+   */
+  affectsTextWrap: boolean;
+  /**
+   * Whether this image paints behind body text. True only for `wrapType ===
+   * "behind"` — the page-level layer is split into a behind-text and
+   * above-text layer so wrapNone semantics survive in the DOM.
+   */
+  behindDoc: boolean;
+};
+/**
+ * CSS class names for page elements
+ */
+declare const PAGE_CLASS_NAMES: {
+  page: string;
+  content: string;
+  header: string;
+  footer: string;
+};
+declare const getDefaultPageFontFamily: () => string;
+/**
+ * A single footnote item ready for rendering at page bottom.
+ */
+type FootnoteRenderItem = {
+  /** Display number (e.g. "1", "2") */displayNumber: string; /** Plain text content */
+  text?: string; /** Pre-measured structured footnote content. */
+  content?: Pick<FootnoteContent, "blocks" | "measures" | "height">;
+};
+/**
+ * Options for rendering a page
+ */
+type RenderPageOptions = {
+  /** Document to create elements in (default: window.document) */document?: Document; /** Bookmark name -> 1-indexed page, for resolving PAGEREF fields at paint. */
+  bookmarkPages?: ReadonlyMap<string, number>; /** Bookmark name -> paragraph text, for resolving REF fields at paint. */
+  bookmarkText?: ReadonlyMap<string, string>; /** Field run `pmStart` -> precomputed SEQ value, for resolving SEQ fields. */
+  seqValues?: ReadonlyMap<number, number>; /** Section index -> page count in that section, for SECTIONPAGES fields. */
+  sectionPageCounts?: ReadonlyMap<number, number>; /** Custom page class name */
+  pageClassName?: string; /** Show page borders (for debugging) */
+  showBorders?: boolean; /** Background color for pages */
+  backgroundColor?: string; /** Drop shadow on pages */
+  showShadow?: boolean; /** Header content to render (used for all pages, or pages 2+ when titlePg is set). */
+  headerContent?: HeaderFooterContent; /** Footer content to render (used for all pages, or pages 2+ when titlePg is set). */
+  footerContent?: HeaderFooterContent; /** Header content by part relationship id, used for section-scoped rendering. */
+  headerContentByRId?: ReadonlyMap<string, HeaderFooterContent>; /** Footer content by part relationship id, used for section-scoped rendering. */
+  footerContentByRId?: ReadonlyMap<string, HeaderFooterContent>; /** Header content for the first page only (when titlePg is set). */
+  firstPageHeaderContent?: HeaderFooterContent; /** Footer content for the first page only (when titlePg is set). */
+  firstPageFooterContent?: HeaderFooterContent; /** Whether different first page headers/footers are enabled (w:titlePg). */
+  titlePg?: boolean; /** Distance from page top to header content. */
+  headerDistance?: number; /** Distance from page bottom to footer content. */
+  footerDistance?: number; /** Block lookup for rendering actual content. */
+  blockLookup?: BlockLookup; /** OOXML page borders from section properties. */
+  pageBorders?: {
+    top?: document_d_exports.BorderSpec;
+    bottom?: document_d_exports.BorderSpec;
+    left?: document_d_exports.BorderSpec;
+    right?: document_d_exports.BorderSpec;
+    display?: "allPages" | "firstPage" | "notFirstPage";
+    offsetFrom?: "page" | "text";
+    zOrder?: "front" | "back";
+  }; /** Theme for resolving border colors. */
+  theme?: document_d_exports.Theme | null; /** Footnotes to render at the bottom of this page. */
+  footnoteArea?: FootnoteRenderItem[];
+  /**
+   * Document watermark to paint behind page content. Applies to every
+   * page that doesn't have a more specific match in
+   * `watermarkByHeaderRId` — the right shape for single-header
+   * documents.
+   */
+  watermark?: document_d_exports.Watermark;
+  /**
+   * Per-header-rId watermarks. When a section uses titlePg, even/odd,
+   * or section-scoped headers, each page's active header may carry a
+   * different watermark; this map lets `applySectionHeaderFooterOptions`
+   * select the right one without painting one header's watermark over
+   * the others.
+   */
+  watermarkByHeaderRId?: ReadonlyMap<string, document_d_exports.Watermark>;
+  /**
+   * Resolved image src for a picture watermark. The renderer cannot
+   * resolve `imageRId` itself — relationship-id → asset URL belongs to
+   * the package layer; without a resolved src a picture watermark is
+   * silently skipped.
+   */
+  watermarkImageSrc?: string;
+};
+type HeaderFooterLayoutInfo = {
+  flowTop: number;
+  flowLeft: number;
+  contentWidth: number;
+  pageWidth: number;
+  pageHeight: number;
+  margins: {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+  };
+};
+/**
+ * Resolve the CSS `left` (px string) for an anchored object (image or text box)
+ * in a header/footer, honoring `wp:positionH` (relativeTo page/margin, align
+ * left/center/right, or posOffset). Shared by floating images and text boxes so
+ * a page-centered banner in the header lands centered like Word, not pinned to
+ * the left. Ported from eigenpal/docx-editor#700.
+ */
+declare function resolveHeaderFooterFloatLeft(width: number, h: {
+  relativeTo?: string;
+  posOffset?: number;
+  align?: string;
+  alignment?: string;
+} | undefined, layout: HeaderFooterLayoutInfo): string;
+/**
+ * Page geometry needed to translate OOXML `relativeFrom` anchors into
+ * painter coordinates. All values are in CSS pixels. Mirrors the upstream
+ * (eigenpal docx-editor) `PageGeometry` shape introduced in #424 so the
+ * anchor math stays identical across the two codebases.
+ */
+type PageGeometry = {
+  pageWidth: number;
+  pageHeight: number;
+  marginLeft: number;
+  marginTop: number;
+  marginRight: number;
+  marginBottom: number;
+  contentWidth: number;
+  contentHeight: number;
+};
+/**
+ * Resolved on-page coordinates for an anchored floating image.
+ * `x` / `y` are in content-area-relative pixels (content origin = (0, 0)).
+ * `side` feeds the text-wrap exclusion zone helper.
+ */
+type AnchoredImagePosition = {
+  x: number;
+  y: number;
+  side: "left" | "right";
+};
+/**
+ * Resolve the on-page coordinates of an anchored floating image.
+ *
+ * Pure function — no DOM, no side effects — so the math is unit-testable
+ * without spinning up a full page render. Used by
+ * `extractFloatingImagesFromParagraph` for body anchors; mirrors the
+ * upstream painter helper introduced in eigenpal #424.
+ *
+ * The OOXML position is `posOffset` (EMUs from the relativeFrom origin)
+ * XOR `align` (symbolic top|center|bottom / left|center|right). When
+ * neither is present, the spec means "anchor at the band origin"; for
+ * paragraph/line that's the paragraph itself, otherwise the band origin
+ * picked by `relativeFrom`.
+ */
+declare function resolveAnchoredImagePosition(imgRun: ImageRun, fragmentY: number, geometry: PageGeometry): AnchoredImagePosition;
+/**
+ * Render floating images into a page-level layer.
+ *
+ * `layerMode === "behind"` paints below body text (used for `behindDoc`
+ * wrapNone images, e.g. full-page letterhead backgrounds). `"front"` paints
+ * above text (default for `inFront` wrapNone and side-wrapping images).
+ */
+declare function renderFloatingImagesLayer(floatingImages: PageFloatingImage[], doc: Document, layerMode?: "front" | "behind"): HTMLElement;
+/**
+ * Calculate the painter's actual footnote-area height in pixels:
+ * separator slot + per-footnote content (or fallback line) + per-footnote
+ * `marginBottom` spacing the painter applies in `renderFootnoteArea`. Used
+ * to clamp the paginator's reservation if it under-estimated, so dense
+ * stacks never overflow past the page bottom. Mirrors the upstream helper
+ * from eigenpal/docx-editor#485, extended for folio's fallback rendering
+ * and any wrapper margin so the helper matches the painted stack.
+ */
+declare function calculateFootnoteAreaRenderHeight(footnotes: FootnoteRenderItem[]): number;
+/**
+ * Render the footnote area at the bottom of a page.
+ * Includes a separator line (33% width) and footnote entries.
+ */
+declare function renderFootnoteArea(footnotes: FootnoteRenderItem[], contentWidth: number, doc: Document, context?: RenderContext): HTMLElement;
+/**
+ * Render a single page to DOM
+ *
+ * @param page - The page to render
+ * @param context - Rendering context
+ * @param options - Rendering options
+ * @returns The page DOM element
+ */
+declare function renderPage(page: Page, context: RenderContext, options?: RenderPageOptions): HTMLElement;
+declare function applySectionHeaderFooterOptions(page: Page, pageOptions: RenderPageOptions, options: RenderPageOptions): boolean;
+/**
+ * Compute a fingerprint string for a page that changes when its content changes.
+ * Used to detect which pages need re-rendering on incremental updates.
+ */
+declare function computePageFingerprint(page: Page, blockLookup?: BlockLookup): string;
+/**
+ * Render multiple pages to a container with virtualization for large documents.
+ *
+ * For documents with fewer than VIRTUALIZATION_THRESHOLD pages, all pages
+ * are rendered eagerly. For larger documents, only pages near the visible
+ * viewport are fully rendered — off-screen pages are lightweight shells
+ * with correct dimensions to preserve scroll position.
+ *
+ * An IntersectionObserver watches page elements and populates/clears
+ * content as pages scroll into and out of view.
+ */
+declare function renderPages(pages: Page[], container: HTMLElement, options?: RenderPageOptions & {
+  pageGap?: number;
+  footnotesByPage?: Map<number, FootnoteRenderItem[]>;
+}): void;
+declare const PAINTER_PAINTED_EVENT: "painter:painted";
+type PainterPaintedDetail = {
+  container: HTMLElement;
+  pageCount: number;
+};
+/**
+ * Find the page shell whose layout fragments cover (or are nearest
+ * before) a given ProseMirror position. Returns null if the
+ * container has no virtualization state — callers should fall back
+ * to the cheaper run-level DOM query in that case.
+ *
+ * Uses the layout-side Page records (always present even when a
+ * page's content hasn't rendered yet under virtualization), so the
+ * caller can scroll to the correct page shell and let the
+ * IntersectionObserver populate it on demand. This avoids the
+ * "many clicks to arrive" failure mode where a per-run DOM query
+ * only finds runs in the currently-rendered buffer and steps the
+ * viewport one buffer at a time.
+ */
+declare function findPageShellForPmPos(container: HTMLElement, pmPos: number): {
+  element: HTMLElement;
+  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 };