@eigenpal/docx-editor-core 0.0.0

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

@@ -0,0 +1,322 @@
+/**
+ * Layout Engine - Main Entry Point
+ *
+ * Converts blocks + measures into positioned fragments on pages.
+ *
+ * @experimental Stable enough for the first-party React adapter, but the
+ * API may change in minor releases until a third-party adapter validates
+ * it. Pin a version range if you depend on this directly.
+ * @packageDocumentation
+ * @public
+ */
+import { Page, PageMargins, ColumnLayout, Fragment, FlowBlock, Measure, SectionBreakBlock, Layout, TableMeasure, LayoutOptions } from './types.js';
+export { BlockId, BorderStyle, CellBorderSpec, CellBorders, ColumnBreakBlock, ColumnBreakMeasure, DEFAULT_TEXTBOX_MARGINS, DEFAULT_TEXTBOX_WIDTH, DocumentPosition, FieldRun, FloatingTablePosition, FootnoteContent, FragmentBase, HeaderFooterContentHeights, HeaderFooterLayout, HitTestResult, HyperlinkInfo, ImageBlock, ImageFragment, ImageMeasure, ImageRun, ImageRunPosition, LineBreakRun, ListNumPr, MeasuredLine, MeasuredLineSegment, PageBreakBlock, PageBreakMeasure, ParagraphAttrs, ParagraphBlock, ParagraphBorders, ParagraphFragment, ParagraphIndent, ParagraphMeasure, ParagraphSpacing, Run, RunFormatting, SectionBreakMeasure, TabAlignment, TabRun, TabStop, TableBlock, TableCell, TableCellMeasure, TableFragment, TableRow, TableRowMeasure, TextBoxBlock, TextBoxFragment, TextBoxMeasure, TextRun, WrapTextDirection, assertExhaustiveFlowBlock } from './types.js';
+
+/**
+ * Paginator - manages page state during layout
+ *
+ * Tracks the current page, cursor position, and available space.
+ * Creates new pages when content doesn't fit.
+ */
+
+/**
+ * Current state of a page being laid out.
+ */
+type PageState = {
+    /** The page being built. */
+    page: Page;
+    /** Current Y position (cursor) from page top. */
+    cursorY: number;
+    /** Current column index (0-based). */
+    columnIndex: number;
+    /** Top margin of content area. */
+    topMargin: number;
+    /** Bottom boundary of content area (page height - bottom margin). */
+    contentBottom: number;
+    /** Accumulated trailing spacing (space after previous block). */
+    trailingSpacing: number;
+};
+/**
+ * Options for creating a paginator.
+ */
+type PaginatorOptions = {
+    /** Page size (width, height). */
+    pageSize: {
+        w: number;
+        h: number;
+    };
+    /** Page margins. */
+    margins: PageMargins;
+    /** Column configuration (optional). */
+    columns?: ColumnLayout;
+    /** Per-page footnote reserved heights (pageNumber → height in pixels). */
+    footnoteReservedHeights?: Map<number, number>;
+    /** Callback when a new page is created. */
+    onNewPage?: (state: PageState) => void;
+};
+/**
+ * Creates a paginator for managing page layout state.
+ */
+declare function createPaginator(options: PaginatorOptions): {
+    /** All pages created so far. */
+    pages: Page[];
+    /** All page states. */
+    states: PageState[];
+    /** Column width in pixels (use getColumnWidth() for current value after updates). */
+    readonly columnWidth: number;
+    /** Get current column layout (returns copy to prevent external mutation). */
+    readonly columns: {
+        count: number;
+        gap: number;
+        equalWidth?: boolean;
+        separator?: boolean;
+    };
+    /** Get current state. */
+    getCurrentState: () => PageState;
+    /** Get available height in current column. */
+    getAvailableHeight: () => number;
+    /** Get content width for the active section. */
+    getContentWidth: () => number;
+    /** Check if height fits in current column. */
+    fits: (height: number) => boolean;
+    /** Ensure height fits, advancing if needed. */
+    ensureFits: (height: number) => PageState;
+    /** Add a fragment to current page. */
+    addFragment: (fragment: Fragment, height: number, spaceBefore?: number, spaceAfter?: number) => {
+        state: PageState;
+        x: number;
+        y: number;
+    };
+    /** Force a page break. */
+    forcePageBreak: () => PageState;
+    /** Force a column break. */
+    forceColumnBreak: () => PageState;
+    /** Get X position for column. */
+    getColumnX: (columnIndex: number) => number;
+    /** Update column layout (for section breaks). */
+    updateColumns: (newColumns: ColumnLayout) => void;
+    /** Update page size/margins for subsequent pages. */
+    updatePageLayout: (newPageSize?: {
+        w: number;
+        h: number;
+    }, newMargins?: PageMargins, applyImmediately?: boolean) => void;
+};
+type Paginator = ReturnType<typeof createPaginator>;
+
+/**
+ * Keep Together Logic - Handle keepNext and keepLines paragraph properties
+ *
+ * DOCX paragraphs can have keepNext (keep with next paragraph) and keepLines
+ * (keep all lines together) properties that affect pagination.
+ */
+
+/**
+ * A chain of consecutive keepNext paragraphs.
+ */
+type KeepNextChain = {
+    /** Index of the first paragraph in the chain. */
+    startIndex: number;
+    /** Index of the last paragraph in the chain. */
+    endIndex: number;
+    /** All paragraph indices in the chain. */
+    memberIndices: number[];
+    /** Index of the anchor paragraph (first non-keepNext after chain), or -1 if none. */
+    anchorIndex: number;
+};
+/**
+ * Pre-scan blocks to find all keepNext chains.
+ *
+ * A keepNext chain is a sequence of consecutive paragraphs with keepNext=true,
+ * followed by an anchor paragraph (the first non-keepNext paragraph).
+ * The entire chain must stay on the same page as the anchor's first line.
+ *
+ * Returns a map from chain start index to chain info.
+ */
+declare function computeKeepNextChains(blocks: FlowBlock[]): Map<number, KeepNextChain>;
+/**
+ * Calculate the total height needed to keep a chain together.
+ *
+ * Includes all chain members plus the first line of the anchor paragraph.
+ */
+declare function calculateChainHeight(chain: KeepNextChain, blocks: FlowBlock[], measures: Measure[]): number;
+/**
+ * Get the set of indices that are mid-chain (not chain starters).
+ * These should skip the keepNext check since their chain starter already decided.
+ */
+declare function getMidChainIndices(chains: Map<number, KeepNextChain>): Set<number>;
+/**
+ * Check if a paragraph has keepLines property (all lines must stay together).
+ */
+declare function hasKeepLines(block: FlowBlock): boolean;
+/**
+ * Check if a paragraph should start on a new page (pageBreakBefore).
+ */
+declare function hasPageBreakBefore(block: FlowBlock): boolean;
+
+/**
+ * Section Breaks - Handle page layout changes at section boundaries
+ *
+ * Sections in DOCX can have different page sizes, margins, columns, and orientations.
+ * This module manages the state transitions between sections during layout.
+ */
+
+/**
+ * State tracking for sections during layout.
+ * Uses active/pending pattern to schedule changes at page boundaries.
+ */
+type SectionState = {
+    /** Currently active top margin. */
+    activeTopMargin: number;
+    /** Currently active bottom margin. */
+    activeBottomMargin: number;
+    /** Currently active left margin. */
+    activeLeftMargin: number;
+    /** Currently active right margin. */
+    activeRightMargin: number;
+    /** Scheduled top margin for next page. */
+    pendingTopMargin: number | null;
+    /** Scheduled bottom margin for next page. */
+    pendingBottomMargin: number | null;
+    /** Scheduled left margin for next page. */
+    pendingLeftMargin: number | null;
+    /** Scheduled right margin for next page. */
+    pendingRightMargin: number | null;
+    /** Currently active page size. */
+    activePageSize: {
+        w: number;
+        h: number;
+    };
+    /** Scheduled page size for next page. */
+    pendingPageSize: {
+        w: number;
+        h: number;
+    } | null;
+    /** Currently active column layout. */
+    activeColumns: ColumnLayout;
+    /** Scheduled column layout for next page. */
+    pendingColumns: ColumnLayout | null;
+    /** Currently active orientation. */
+    activeOrientation: 'portrait' | 'landscape' | null;
+    /** Scheduled orientation for next page. */
+    pendingOrientation: 'portrait' | 'landscape' | null;
+    /** Whether any pages have been created yet. */
+    hasAnyPages: boolean;
+};
+/**
+ * Decision about what happens at a section break.
+ */
+type BreakDecision = {
+    /** Force a page break. */
+    forcePageBreak: boolean;
+    /** Force a mid-page region change (for column layout changes). */
+    forceMidPageRegion: boolean;
+    /** Required page parity (even or odd). */
+    requiredParity?: 'even' | 'odd';
+};
+/**
+ * Create initial section state from default options.
+ */
+declare function createInitialSectionState(margins: PageMargins, pageSize: {
+    w: number;
+    h: number;
+}, columns?: ColumnLayout): SectionState;
+/**
+ * Schedule section break effects by analyzing the break type and updating state.
+ *
+ * This determines what layout changes should occur (page break, column changes)
+ * and schedules the new section properties to be applied at the appropriate boundary.
+ */
+declare function scheduleSectionBreak(block: SectionBreakBlock, state: SectionState, _baseMargins: PageMargins): {
+    decision: BreakDecision;
+    state: SectionState;
+};
+/**
+ * Apply pending section state to active state at a page boundary.
+ * Transfers all pending values to active and clears pending.
+ */
+declare function applyPendingToActive(state: SectionState): SectionState;
+/**
+ * Get the effective margins for the current section state.
+ * Returns active margins, or pending if scheduled.
+ */
+declare function getEffectiveMargins(state: SectionState): PageMargins;
+/**
+ * Get the effective page size for the current section state.
+ */
+declare function getEffectivePageSize(state: SectionState): {
+    w: number;
+    h: number;
+};
+/**
+ * Get the effective columns for the current section state.
+ */
+declare function getEffectiveColumns(state: SectionState): ColumnLayout;
+
+/**
+ * Page index (0-based) whose layout fragments cover `pmPos`, or null if none.
+ * Used when the painted DOM may not yet have `[data-pm-start]` for this position (virtualization).
+ *
+ * Range semantics: `[pmStart, pmEnd)` — half-open, matching ProseMirror's
+ * `pos + nodeSize` convention. Boundary positions belong to the next fragment,
+ * so when a fragment ends at the same position the next one starts, the next
+ * fragment wins (avoids returning the previous page for the start of the
+ * next paragraph).
+ */
+declare function findPageIndexContainingPmPos(layout: Layout, pmPos: number): number | null;
+
+/**
+ * Layout Engine - Main Entry Point
+ *
+ * Converts blocks + measures into positioned fragments on pages.
+ *
+ * @experimental Stable enough for the first-party React adapter, but the
+ * API may change in minor releases until a third-party adapter validates
+ * it. Pin a version range if you depend on this directly.
+ * @packageDocumentation
+ * @public
+ */
+
+/**
+ * Page-flow geometry resolved from a single section's properties.
+ * Exported so the React paged editor can reuse the same shape when
+ * measuring blocks per section width — keeping pagination and
+ * measurement consistent.
+ */
+type SectionLayoutConfig = {
+    pageSize: {
+        w: number;
+        h: number;
+    };
+    margins: PageMargins;
+    /** Optional. Sections without explicit columns inherit `{ count: 1 }`. */
+    columns?: ColumnLayout;
+};
+/**
+ * Walk `blocks` once and collect per-section geometry. `configs` has one
+ * entry per section break plus a trailing `finalConfig`. `breakIndices` is
+ * 1-to-1 with the inner break entries (same length as `configs.length - 1`).
+ * Callers that need the break `type` can read it from
+ * `(blocks[breakIndices[i]] as SectionBreakBlock).type`.
+ *
+ * @internal
+ */
+declare function collectSectionConfigs(blocks: FlowBlock[], initialConfig: SectionLayoutConfig, finalConfig: SectionLayoutConfig): {
+    configs: SectionLayoutConfig[];
+    breakIndices: number[];
+};
+/**
+ * Layout a document: convert blocks + measures into pages with positioned fragments.
+ *
+ * Algorithm:
+ * 1. Walk blocks in order with their corresponding measures
+ * 2. For each block, create appropriate fragment(s)
+ * 3. Use paginator to manage page/column state
+ * 4. Handle page breaks, section breaks, and keepNext chains
+ */
+declare function layoutDocument(blocks: FlowBlock[], measures: Measure[], options?: LayoutOptions): Layout;
+/**
+ * Calculate total height of header rows from their measures.
+ */
+declare function getHeaderRowsHeight(measure: TableMeasure, headerRowCount: number): number;
+
+export { type BreakDecision, ColumnLayout, FlowBlock, Fragment, type KeepNextChain, Layout, LayoutOptions, Measure, Page, PageMargins, type PageState, type Paginator, type PaginatorOptions, SectionBreakBlock, type SectionLayoutConfig, type SectionState, TableMeasure, applyPendingToActive, calculateChainHeight, collectSectionConfigs, computeKeepNextChains, createInitialSectionState, createPaginator, findPageIndexContainingPmPos, getEffectiveColumns, getEffectiveMargins, getEffectivePageSize, getHeaderRowsHeight, getMidChainIndices, hasKeepLines, hasPageBreakBefore, layoutDocument, scheduleSectionBreak };

package/dist/layout-engine/index.js

@@ -0,0 +1 @@
+'use strict';var chunk44RUAQA2_js=require('../chunk-44RUAQA2.js'),chunkDROCYKAR_js=require('../chunk-DROCYKAR.js');require('../chunk-JFZIXFRC.js'),require('../chunk-DC7S76ZX.js');Object.defineProperty(exports,"applyPendingToActive",{enumerable:true,get:function(){return chunk44RUAQA2_js.k}});Object.defineProperty(exports,"calculateChainHeight",{enumerable:true,get:function(){return chunk44RUAQA2_js.c}});Object.defineProperty(exports,"collectSectionConfigs",{enumerable:true,get:function(){return chunk44RUAQA2_js.p}});Object.defineProperty(exports,"computeKeepNextChains",{enumerable:true,get:function(){return chunk44RUAQA2_js.b}});Object.defineProperty(exports,"createInitialSectionState",{enumerable:true,get:function(){return chunk44RUAQA2_js.i}});Object.defineProperty(exports,"createPaginator",{enumerable:true,get:function(){return chunk44RUAQA2_js.a}});Object.defineProperty(exports,"findPageIndexContainingPmPos",{enumerable:true,get:function(){return chunk44RUAQA2_js.o}});Object.defineProperty(exports,"getEffectiveColumns",{enumerable:true,get:function(){return chunk44RUAQA2_js.n}});Object.defineProperty(exports,"getEffectiveMargins",{enumerable:true,get:function(){return chunk44RUAQA2_js.l}});Object.defineProperty(exports,"getEffectivePageSize",{enumerable:true,get:function(){return chunk44RUAQA2_js.m}});Object.defineProperty(exports,"getHeaderRowsHeight",{enumerable:true,get:function(){return chunk44RUAQA2_js.r}});Object.defineProperty(exports,"getMidChainIndices",{enumerable:true,get:function(){return chunk44RUAQA2_js.d}});Object.defineProperty(exports,"hasKeepLines",{enumerable:true,get:function(){return chunk44RUAQA2_js.e}});Object.defineProperty(exports,"hasPageBreakBefore",{enumerable:true,get:function(){return chunk44RUAQA2_js.f}});Object.defineProperty(exports,"layoutDocument",{enumerable:true,get:function(){return chunk44RUAQA2_js.q}});Object.defineProperty(exports,"scheduleSectionBreak",{enumerable:true,get:function(){return chunk44RUAQA2_js.j}});Object.defineProperty(exports,"DEFAULT_TEXTBOX_MARGINS",{enumerable:true,get:function(){return chunkDROCYKAR_js.a}});Object.defineProperty(exports,"DEFAULT_TEXTBOX_WIDTH",{enumerable:true,get:function(){return chunkDROCYKAR_js.b}});Object.defineProperty(exports,"assertExhaustiveFlowBlock",{enumerable:true,get:function(){return chunkDROCYKAR_js.c}});

package/dist/layout-engine/index.mjs

@@ -0,0 +1 @@
+export{k as applyPendingToActive,c as calculateChainHeight,p as collectSectionConfigs,b as computeKeepNextChains,i as createInitialSectionState,a as createPaginator,o as findPageIndexContainingPmPos,n as getEffectiveColumns,l as getEffectiveMargins,m as getEffectivePageSize,r as getHeaderRowsHeight,d as getMidChainIndices,e as hasKeepLines,f as hasPageBreakBefore,q as layoutDocument,j as scheduleSectionBreak}from'../chunk-5N5DBQJV.mjs';export{a as DEFAULT_TEXTBOX_MARGINS,b as DEFAULT_TEXTBOX_WIDTH,c as assertExhaustiveFlowBlock}from'../chunk-7E5VBRDL.mjs';import'../chunk-QPFJJPIC.mjs';import'../chunk-QYUPLKLP.mjs';