@zeke-02/docx-editor-core 0.1.0

package/dist/layout-bridge/index.d.mts

@@ -0,0 +1,462 @@
+/**
+ * Layout Bridge — measure, hit-test, and map between PM positions and pixels.
+ *
+ * @experimental Internal layer between the layout engine and rendering.
+ * The named exports below are the public contract for adapter authors,
+ * but the API is still evolving and may change in minor releases until
+ * a third-party adapter validates it.
+ * @packageDocumentation
+ * @public
+ */
+export { ToFlowBlocksOptions, convertBorderSpecToLayout, resetBlockIdCounter, resolveListTemplate, toFlowBlocks } from './toFlowBlocks.mjs';
+import { TableBlock, Fragment, FlowBlock, Measure, Page, TableFragment, TableMeasure, ParagraphBlock, ParagraphMeasure, Layout, PageMargins } from '../layout-engine/types.mjs';
+export { FloatingExclusionRect, FloatingImageZone, FloatingLineSegmentZone, FontMetrics, FontStyle, MeasureBlockFn, MeasureParagraphOptions, RunMeasurement, TextMeasurement, buildFontString, clampFloatingWrapMargins, clearAllCaches, clearFontMetricsCache, clearParagraphMeasureCache, clearTextWidthCache, findCharacterAtX, getCachedFontMetrics, getCachedParagraphMeasure, getCachedTextWidth, getCanvasContext, getFloatingMargins, getFontCacheSize, getFontMetrics, getParagraphCacheSize, getRunCharWidths, getTextCacheSize, getTotalCacheSize, getXForCharacter, halfPtToPx, hashParagraphBlock, measureBlocksWithFloats, measureParagraph, measureParagraphs, measureRun, measureText, measureTextWidth, ptToPx, pxToHalfPt, pxToPt, pxToTwips, rectsToFloatingZones, resetCanvasContext, setCachedFontMetrics, setCachedParagraphMeasure, setCachedTextWidth, setFontCacheSize, setParagraphCacheSize, setTextCacheSize, twipsToPx } from './measuring/index.mjs';
+export { DomCaretPosition, DomSelectionRect, clickToPositionDom, getCaretPositionFromDom, getSelectionRectsFromDom, clickToPositionDom as mouseToPosition } from './clickToPositionDom.mjs';
+export { C as ConvertFootnoteOptions, a as ConvertHeaderFooterOptions, F as FOOTNOTE_SEPARATOR_HEIGHT, H as HeaderFooterMetrics, M as MAX_FOOTNOTE_LAYOUT_PASSES, b as MeasureBlocksFn, S as StabilizeFootnoteLayoutArgs, c as StabilizeFootnoteLayoutResult, j as applyFootnotePresentation, d as buildFootnoteContentMap, e as buildFootnoteRenderItems, f as calculateFootnoteReservedHeights, k as calculateHeaderFooterVisualBounds, g as collectFootnoteRefs, l as computeHfCaretRectFromView, n as computeHfSelectionRectsFromView, o as convertFootnoteToContent, p as convertHeaderFooterPmDocToContent, h as convertHeaderFooterToContent, i as footnoteReservedHeightsEqual, q as invalidateHfDomCache, m as mapFootnotesToPages, r as normalizeHeaderFooterMeasureBlocks, t as resolveHeaderFooterVisualTop, s as stabilizeFootnoteLayout } from '../headerFooterLayout-72Vz7yp3.mjs';
+export { TABLE_INSERT_EDGE_PROXIMITY, TABLE_INSERT_HIDE_DELAY_MS, TableInsertHoverHit, TableInsertHoverInput, detectTableInsertHover } from './tableInsertHover.mjs';
+import { Document } from '../types/document.mjs';
+import { S as SectionProperties, u as HeaderFooter } from '../content-5Mrz6w_b.mjs';
+import 'prosemirror-model';
+import '../styles-EI2lxeEN.mjs';
+import '../formatting-BH4hcZiq.mjs';
+import '../colors-C3vA7HUU.mjs';
+import '../docx/wrapTypes.mjs';
+import 'prosemirror-view';
+import '../footnotes-lCH_P3N3.mjs';
+
+/**
+ * @internal Helpers for resolving DOCX table-width metadata into pixel widths.
+ */
+
+/**
+ * Resolve a DOCX width pair to pixels. `pct` values are 50ths of a percent
+ * (ECMA-376 §17.18.111 — 5000 means 100%). `dxa` / `auto` / unset are twips.
+ *
+ * @internal
+ */
+declare function resolveTableWidthPx(value: number | undefined, widthType: string | undefined, parentWidth: number): number | undefined;
+/** Total grid columns, derived from the widest row's accumulated colSpans. */
+declare function countTableColumns(tableBlock: TableBlock): number;
+/**
+ * Make `columnWidths` exactly `colCount` long with every entry positive.
+ * Missing trailing columns inherit the average of existing positives; zero
+ * or negative entries split the leftover `targetWidth` evenly. Callers
+ * scale down totals that exceed the target — this helper only fills gaps.
+ */
+declare function normalizeTableColumnWidths(columnWidths: number[], colCount: number, targetWidth: number): number[];
+
+/**
+ * Hit Testing Utilities
+ *
+ * Maps click coordinates to pages, fragments, and document positions.
+ * Used by the paged editor to translate user clicks into PM positions.
+ */
+
+/**
+ * A 2D point in page coordinate space.
+ */
+type Point = {
+    x: number;
+    y: number;
+};
+/**
+ * Result of hit-testing to find which page contains a point.
+ */
+type PageHit = {
+    /** Index of the page (0-based). */
+    pageIndex: number;
+    /** The page that was hit. */
+    page: Page;
+    /** Y position relative to the page top. */
+    pageY: number;
+};
+/**
+ * Result of hit-testing to find which fragment contains a point.
+ */
+type FragmentHit = {
+    /** The fragment that was hit. */
+    fragment: Fragment;
+    /** The corresponding flow block. */
+    block: FlowBlock;
+    /** The corresponding measurement. */
+    measure: Measure;
+    /** Page index (0-based). */
+    pageIndex: number;
+    /** Y position relative to the fragment top. */
+    localY: number;
+    /** X position relative to the fragment left. */
+    localX: number;
+};
+/**
+ * Result of hit-testing a table to find the cell.
+ */
+type TableCellHit = {
+    /** The table fragment. */
+    fragment: TableFragment;
+    /** The table block. */
+    block: TableBlock;
+    /** The table measure. */
+    measure: TableMeasure;
+    /** Page index (0-based). */
+    pageIndex: number;
+    /** Row index (0-based). */
+    rowIndex: number;
+    /** Column index (0-based). */
+    colIndex: number;
+    /** Paragraph block within the cell (first one). */
+    cellBlock?: ParagraphBlock;
+    /** Paragraph measure within the cell. */
+    cellMeasure?: ParagraphMeasure;
+    /** X position relative to cell content area. */
+    cellLocalX: number;
+    /** Y position relative to cell content area. */
+    cellLocalY: number;
+};
+/**
+ * Hit-test pages to find which page contains a given Y coordinate.
+ *
+ * Pages are stacked vertically with optional gaps between them.
+ * If the point is in a gap, returns the nearest page.
+ *
+ * @param layout - The layout containing pages.
+ * @param point - The point to test (only Y is used for page lookup).
+ * @returns PageHit if a page was found, null otherwise.
+ */
+declare function hitTestPage(layout: Layout, point: Point): PageHit | null;
+/**
+ * Calculate the Y offset of a page from the top of the document.
+ */
+declare function getPageTop(layout: Layout, pageIndex: number): number;
+/**
+ * Get the page index at a specific Y coordinate.
+ * Returns null if the coordinate is outside all pages.
+ */
+declare function getPageIndexAtY(layout: Layout, y: number): number | null;
+/**
+ * Hit-test fragments on a page to find which fragment contains a point.
+ *
+ * Fragments are checked in visual order (sorted by Y then X).
+ * Only considers paragraph and table fragments (not images for now).
+ *
+ * @param pageHit - The page hit result from hitTestPage.
+ * @param blocks - All flow blocks in the document.
+ * @param measures - All measurements corresponding to blocks.
+ * @param pagePoint - Point in page-relative coordinates.
+ * @returns FragmentHit if a fragment was found, null otherwise.
+ */
+declare function hitTestFragment(pageHit: PageHit, blocks: FlowBlock[], measures: Measure[], pagePoint: Point): FragmentHit | null;
+/**
+ * Hit-test to find image fragments (they may overlap other content).
+ */
+declare function hitTestImageFragment(pageHit: PageHit, blocks: FlowBlock[], measures: Measure[], pagePoint: Point): FragmentHit | null;
+/**
+ * Hit-test within a table fragment to find the specific cell.
+ *
+ * @param pageHit - The page hit result.
+ * @param blocks - All flow blocks.
+ * @param measures - All measurements.
+ * @param pagePoint - Point in page-relative coordinates.
+ * @returns TableCellHit if a table cell was found, null otherwise.
+ */
+declare function hitTestTableCell(pageHit: PageHit, blocks: FlowBlock[], measures: Measure[], pagePoint: Point): TableCellHit | null;
+/**
+ * Combined result of all hit testing.
+ */
+type HitTestResult = {
+    /** Page that was hit. */
+    pageHit: PageHit | null;
+    /** Fragment that was hit (if any). */
+    fragmentHit: FragmentHit | null;
+    /** Table cell that was hit (if fragment is a table). */
+    tableCellHit: TableCellHit | null;
+};
+/**
+ * Perform complete hit testing from document coordinates to the most specific element.
+ *
+ * @param layout - The layout containing pages.
+ * @param blocks - All flow blocks.
+ * @param measures - All measurements.
+ * @param point - Point in document coordinates (Y is cumulative from document top).
+ * @returns Complete hit test result.
+ */
+declare function hitTest(layout: Layout, blocks: FlowBlock[], measures: Measure[], point: Point): HitTestResult;
+/**
+ * Get the total document height (all pages + gaps).
+ */
+declare function getTotalDocumentHeight(layout: Layout): number;
+/**
+ * Get Y coordinate to scroll to for a specific page.
+ */
+declare function getScrollYForPage(layout: Layout, pageIndex: number): number;
+/**
+ * Get page bounds (top and bottom Y coordinates).
+ */
+declare function getPageBounds(layout: Layout, pageIndex: number): {
+    top: number;
+    bottom: number;
+} | null;
+
+/**
+ * Click-to-Position Mapping
+ *
+ * Maps click coordinates within a layout to ProseMirror document positions.
+ * Uses geometry-based calculation with canvas text measurement for accuracy.
+ *
+ * The main entry point `clickToPosition` takes fragment hit data and local
+ * coordinates and returns the PM position at the click point.
+ */
+
+/**
+ * Result of click-to-position mapping.
+ */
+type PositionResult = {
+    /** ProseMirror document position. */
+    pmPosition: number;
+    /** Character offset within the line (for debugging). */
+    charOffset: number;
+    /** Line index within the paragraph. */
+    lineIndex: number;
+};
+/**
+ * Map a click within a paragraph fragment to a PM position.
+ *
+ * @param fragmentHit - The fragment hit result from hitTestFragment.
+ * @returns Position result, or null if mapping fails.
+ */
+declare function clickToPositionInParagraph(fragmentHit: FragmentHit): PositionResult | null;
+/**
+ * Map a click within a table cell to a PM position.
+ *
+ * @param tableCellHit - The table cell hit result from hitTestTableCell.
+ * @returns PM position, or null if mapping fails.
+ */
+declare function clickToPositionInTableCell(tableCellHit: TableCellHit): number | null;
+/**
+ * Main entry point: Map a click to a PM position.
+ *
+ * This function takes the result of hit testing and returns the PM position.
+ *
+ * @param fragmentHit - Fragment hit from hitTestFragment.
+ * @param tableCellHit - Optional table cell hit from hitTestTableCell.
+ * @returns PM position, or null if mapping fails.
+ */
+declare function clickToPosition(fragmentHit: FragmentHit | null, tableCellHit?: TableCellHit | null): number | null;
+/**
+ * Map a PM position to X coordinates within a line (for caret positioning).
+ *
+ * @param block - The paragraph block.
+ * @param measure - The paragraph measure.
+ * @param pmPosition - The PM position to map.
+ * @param fragmentWidth - Width of the fragment.
+ * @returns X coordinate relative to fragment start, or null if not found.
+ */
+declare function positionToX(block: ParagraphBlock, measure: ParagraphMeasure, pmPosition: number, _fragmentWidth: number): {
+    x: number;
+    lineIndex: number;
+} | null;
+/**
+ * Get the bounding rect for a PM position (for caret rendering).
+ */
+declare function getPositionRect(block: ParagraphBlock, measure: ParagraphMeasure, pmPosition: number, fragmentX: number, fragmentY: number, fragmentWidth: number, fromLine: number): {
+    x: number;
+    y: number;
+    height: number;
+} | null;
+
+/**
+ * Selection Rectangles
+ *
+ * Converts ProseMirror selection ranges into screen rectangles for rendering
+ * selection highlights and the caret cursor.
+ *
+ * The main function `selectionToRects` takes a PM range and returns an array
+ * of rectangles that cover the selected text across all pages and fragments.
+ */
+
+/**
+ * A rectangle representing part of a selection.
+ */
+type SelectionRect = {
+    /** X coordinate in container space. */
+    x: number;
+    /** Y coordinate in container space. */
+    y: number;
+    /** Width of the rectangle. */
+    width: number;
+    /** Height of the rectangle (typically line height). */
+    height: number;
+    /** Page index (0-based). */
+    pageIndex: number;
+};
+/**
+ * Caret position for collapsed selection.
+ */
+type CaretPosition = {
+    /** X coordinate in container space. */
+    x: number;
+    /** Y coordinate in container space. */
+    y: number;
+    /** Height of the caret (line height). */
+    height: number;
+    /** Page index (0-based). */
+    pageIndex: number;
+};
+/**
+ * Convert a ProseMirror selection range to screen rectangles.
+ *
+ * @param layout - The document layout.
+ * @param blocks - All flow blocks.
+ * @param measures - All measurements.
+ * @param from - Start PM position.
+ * @param to - End PM position.
+ * @returns Array of rectangles covering the selection.
+ */
+declare function selectionToRects(layout: Layout, blocks: FlowBlock[], measures: Measure[], from: number, to: number): SelectionRect[];
+/**
+ * Get caret position for a collapsed selection.
+ *
+ * @param layout - The document layout.
+ * @param blocks - All flow blocks.
+ * @param measures - All measurements.
+ * @param pmPosition - The PM position.
+ * @returns Caret position, or null if not found.
+ */
+declare function getCaretPosition(layout: Layout, blocks: FlowBlock[], measures: Measure[], pmPosition: number): CaretPosition | null;
+/**
+ * Check if a selection spans multiple pages.
+ *
+ * @param rects - Selection rectangles.
+ * @returns True if selection spans multiple pages.
+ */
+declare function isMultiPageSelection(rects: SelectionRect[]): boolean;
+/**
+ * Get selection rectangles grouped by page.
+ *
+ * @param rects - Selection rectangles.
+ * @returns Map of page index to rectangles on that page.
+ */
+declare function groupRectsByPage(rects: SelectionRect[]): Map<number, SelectionRect[]>;
+
+/**
+ * Body-scoped DOM lookups for `data-pm-start` / `data-pm-end` markers.
+ *
+ * Headers and footers are parsed via a separate ProseMirror document
+ * (see `convertHeaderFooterToContent`), so HF runs end up with PM
+ * positions that overlap body PM positions. Any container-level
+ * `querySelector(...)` that doesn't restrict to `.layout-page-content`
+ * will match both trees and produce wrong results: phantom selection
+ * rectangles in headers, scroll-restore latching onto an HF span,
+ * caret resolution returning an HF position, etc.
+ *
+ * These helpers centralize the body-only scope so call sites can't
+ * forget the prefix. The match for HF lookups is `.layout-page-header`
+ * / `.layout-page-footer`; HF call sites should write their own queries
+ * scoped to those classes.
+ */
+/**
+ * All body-tree run spans carrying both `data-pm-start` and `data-pm-end`.
+ *
+ * This is the workhorse for caret resolution and selection-rect painting.
+ */
+declare function findBodyPmSpans(container: ParentNode): HTMLElement[];
+/**
+ * All body-tree empty-paragraph runs. Used as a caret fallback when a
+ * paragraph has no painted text spans.
+ */
+declare function findBodyEmptyRuns(container: ParentNode): HTMLElement[];
+/**
+ * All body-tree elements carrying a `data-pm-start` attribute.
+ *
+ * Includes paragraph elements as well as run spans, which is what scroll-
+ * anchor recovery needs. Distinct from {@link findBodyPmSpans}, which
+ * filters down to run spans only.
+ */
+declare function findBodyPmAnchors(container: ParentNode): HTMLElement[];
+/**
+ * First body-tree element whose `data-pm-start` exactly matches `pmStart`.
+ *
+ * Used for scroll anchors and image `NodeSelection` resolution where the
+ * caller already knows the exact PM position it wants to find. Returns
+ * `null` for non-finite inputs so callers don't need to guard.
+ */
+declare function findBodyPmAnchor(container: ParentNode, pmStart: number): HTMLElement | null;
+
+/**
+ * Shared table measurement helper.
+ *
+ * Both React's PagedEditor and Vue's useDocxEditor measure tables the
+ * same way: resolve column widths through `tableWidthUtils`, track
+ * column occupancy across vertically merged cells, then call back into
+ * the adapter's `measureBlock` for each cell's contained blocks.
+ *
+ * This module lives in core (not in either adapter) so a fix on one
+ * side automatically applies to both. The recursive cell-content
+ * measurement is delegated to the caller via `measureBlock` because
+ * each adapter's block coverage differs (React supports floating
+ * zones, footnotes, textBoxes; Vue is a subset).
+ */
+
+/**
+ * Visual height of a single block inside a table cell.
+ *
+ * A one-line paragraph that contains only image runs is laid out at the
+ * image's intrinsic height (plus the paragraph's explicit spacing), not
+ * a full text line — matching Word's per-cell layout. Everything else
+ * uses the measured `totalHeight` / `height`.
+ */
+declare function measureTableCellBlockVisualHeight(block: FlowBlock, blockMeasure: Measure): number;
+/**
+ * Measure a `TableBlock` against a content-width budget.
+ *
+ * `measureBlock` is the per-cell-content measurement callback the
+ * adapter uses for everything inside a cell. The adapter passes its
+ * own `measureBlock` so block coverage stays per-renderer.
+ */
+declare function measureTableBlock(tableBlock: TableBlock, contentWidth: number, measureBlock: (block: FlowBlock, contentWidth: number) => Measure): TableMeasure;
+
+/**
+ * Section-properties → page geometry helpers.
+ *
+ * Both adapters need the same translation from `SectionProperties` (twips
+ * + DOCX field names) into the layout engine's pixel-shaped `PageSize`
+ * and `PageMargins`. Living in core eliminates the subtle React/Vue
+ * drift that grows when each adapter ships its own twipsToPixels math.
+ */
+
+/** US Letter at 96 DPI — Word's default page size. */
+declare const DEFAULT_PAGE_WIDTH_PX = 816;
+/** US Letter at 96 DPI. */
+declare const DEFAULT_PAGE_HEIGHT_PX = 1056;
+/** 1 inch at 96 DPI — Word's default body margins. */
+declare const DEFAULT_BODY_MARGIN_PX = 96;
+/** Word's default `headerDistance` / `footerDistance` (0.5in = 48px). */
+declare const DEFAULT_HF_DISTANCE_PX = 48;
+/** Convert SectionProperties page size (twips) → pixel `{ w, h }`. */
+declare function getPageSize(sp: SectionProperties | null | undefined): {
+    w: number;
+    h: number;
+};
+/**
+ * Convert SectionProperties margins (twips) → pixel `PageMargins`.
+ *
+ * `header` / `footer` default to 48px (Word's 0.5-inch default) so the
+ * HF margin-extension math doesn't have to special-case undefined.
+ */
+declare function getMargins(sp: SectionProperties | null | undefined): PageMargins;
+/**
+ * Resolve the HeaderFooter pair (default + first-page) for a section.
+ *
+ * Mirrors React's lookup in DocxEditor.tsx: read `pkg.headers`/`footers`
+ * (Maps keyed by rId), resolve through `sp.headerReferences` /
+ * `footerReferences`. When `titlePg` is unset and only `first` HFs
+ * exist, they serve as the default — same Word fallback both adapters
+ * have shipped.
+ */
+declare function resolveHeaderFooter(doc: Document | null, sp: SectionProperties | null | undefined): {
+    header: HeaderFooter | null;
+    footer: HeaderFooter | null;
+    firstHeader: HeaderFooter | null;
+    firstFooter: HeaderFooter | null;
+};
+
+export { type CaretPosition, DEFAULT_BODY_MARGIN_PX, DEFAULT_HF_DISTANCE_PX, DEFAULT_PAGE_HEIGHT_PX, DEFAULT_PAGE_WIDTH_PX, type FragmentHit, type HitTestResult, type PageHit, type Point, type PositionResult, type SelectionRect, type TableCellHit, clickToPosition, clickToPositionInParagraph, clickToPositionInTableCell, countTableColumns, findBodyEmptyRuns, findBodyPmAnchor, findBodyPmAnchors, findBodyPmSpans, getCaretPosition, getMargins, getPageBounds, getPageIndexAtY, getPageSize, getPageTop, getPositionRect, getScrollYForPage, getTotalDocumentHeight, groupRectsByPage, hitTest, hitTestFragment, hitTestImageFragment, hitTestPage, hitTestTableCell, isMultiPageSelection, measureTableBlock, measureTableCellBlockVisualHeight, normalizeTableColumnWidths, positionToX, resolveHeaderFooter, resolveTableWidthPx, selectionToRects };