@zeke-02/docx-editor-core 0.1.0

package/dist/layout-bridge/toFlowBlocks.d.ts

@@ -0,0 +1,130 @@
+/**
+ * ProseMirror to FlowBlock Converter
+ *
+ * Converts a ProseMirror document into FlowBlock[] for the layout engine.
+ * Tracks pmStart/pmEnd positions for click-to-position mapping.
+ *
+ * The deep import `@eigenpal/.../layout-bridge/toFlowBlocks` is part of the
+ * public surface (Vue adapter + tests), so the per-domain helpers under
+ * ./toFlowBlocks/ are re-exported from here to keep that path stable.
+ * @packageDocumentation
+ * @public
+ */
+import { Node } from 'prosemirror-model';
+import { BorderStyle, FlowBlock } from '../layout-engine/types.js';
+import { T as Theme } from '../styles-BBv7doYK.js';
+import { o as NumberFormat } from '../content-CmqAwdFL.js';
+import '../formatting-_OXU8gLB.js';
+import '../colors-C3vA7HUU.js';
+import '../docx/wrapTypes.js';
+
+/**
+ * Shared types and primitive helpers used across toFlowBlocks sub-modules.
+ */
+
+/**
+ * Options for the conversion.
+ */
+type ToFlowBlocksOptions = {
+    /** Default font family. */
+    defaultFont?: string;
+    /** Default font size in points. */
+    defaultSize?: number;
+    /** Theme for resolving theme colors. */
+    theme?: Theme | null;
+    /** Page content height in pixels (pageHeight - marginTop - marginBottom). Images taller than this are scaled down to fit. */
+    pageContentHeight?: number;
+    /**
+     * Document-wide `w:defaultTabStop` (§17.6.13) in twips. Stamped onto each
+     * paragraph's attrs so the layout-time list-marker helper can snap body
+     * text to the default tab grid when no custom `w:tabs` are defined.
+     * Default 720 twips (Word's spec default).
+     */
+    defaultTabStopTwips?: number;
+    /**
+     * @internal Allocated by toFlowBlocks() and threaded through table /
+     * text-box conversion so list numbering stays continuous across containers.
+     * Keyed by abstractNumId when known (ECMA-376 §17.9.18: numIds sharing one
+     * abstractNum share counter state); falls back to numId.
+     */
+    listCounters?: Map<number, number[]>;
+    /**
+     * @internal Tracks `${numId}:${ilvl}` pairs whose startOverride has already
+     * been applied. Per ECMA-376 §17.9.27 the override fires the first time
+     * each level of a numId is encountered, so a numId with overrides on
+     * multiple ilvls fires each one independently.
+     */
+    listSeenNumIds?: Set<string>;
+};
+/**
+ * Reset the block ID counter (useful for testing).
+ */
+declare function resetBlockIdCounter(): void;
+
+/**
+ * Border Conversion
+ *
+ * Shared OOXML BorderSpec → layout-engine BorderStyle conversion, used by
+ * paragraph borders, table cell borders, and header/footer borders.
+ */
+
+/**
+ * Convert an OOXML BorderSpec to a layout-engine BorderStyle.
+ * Shared by paragraph borders, cell borders, and header/footer borders.
+ */
+declare function convertBorderSpecToLayout(border: {
+    style?: string;
+    size?: number;
+    space?: number;
+    color?: {
+        rgb?: string;
+        themeColor?: string;
+        themeTint?: string;
+        themeShade?: string;
+    };
+}, theme?: Theme | null): BorderStyle | undefined;
+
+/**
+ * List Marker Resolution
+ *
+ * Helpers for rendering OOXML list markers from the counter stack:
+ *   - format numbers as decimal/roman/letter per ECMA-376 §17.9.16 numFmt
+ *   - resolve lvlText templates ("%1.%2.") against the counter stack
+ *   - drive the per-paragraph counter increment, including startOverride.
+ */
+
+/**
+ * Resolve an OOXML lvlText template like "%1.%2." against the counter stack
+ * and per-level numFmt list (ECMA-376 §17.9.11).
+ *
+ * When a referenced counter has no value yet (e.g. "%2" referenced from a
+ * level-0 paragraph), the placeholder AND the punctuation immediately
+ * following it are dropped — matches Word's behavior so "%1.%2." renders
+ * "1." rather than "1..".
+ *
+ * Exported for unit testing.
+ */
+declare function resolveListTemplate(template: string, counters: number[], levelNumFmts: NumberFormat[] | undefined): string;
+
+/**
+ * ProseMirror to FlowBlock Converter
+ *
+ * Converts a ProseMirror document into FlowBlock[] for the layout engine.
+ * Tracks pmStart/pmEnd positions for click-to-position mapping.
+ *
+ * The deep import `@eigenpal/.../layout-bridge/toFlowBlocks` is part of the
+ * public surface (Vue adapter + tests), so the per-domain helpers under
+ * ./toFlowBlocks/ are re-exported from here to keep that path stable.
+ * @packageDocumentation
+ * @public
+ */
+
+/**
+ * Convert a ProseMirror document to FlowBlock array.
+ *
+ * Walks the document tree, converting each node to the appropriate block type.
+ * Tracks pmStart/pmEnd positions for each block for click-to-position mapping.
+ */
+declare function toFlowBlocks(doc: Node, options?: ToFlowBlocksOptions): FlowBlock[];
+
+export { type ToFlowBlocksOptions, convertBorderSpecToLayout, resetBlockIdCounter, resolveListTemplate, toFlowBlocks };

package/dist/layout-bridge/toFlowBlocks.js

@@ -0,0 +1 @@
+'use strict';var chunkHKVAW3RE_js=require('../chunk-HKVAW3RE.js'),chunkIMKU4O3P_js=require('../chunk-IMKU4O3P.js');require('../chunk-DROCYKAR.js'),require('../chunk-F44ZLDZS.js'),require('../chunk-E4JMCA5X.js'),require('../chunk-HQPWFUP5.js'),require('../chunk-DV6GWBUJ.js'),require('../chunk-MJ5FQX7Q.js'),require('../chunk-4Q2IP5FW.js'),require('../chunk-DC7S76ZX.js');Object.defineProperty(exports,"convertBorderSpecToLayout",{enumerable:true,get:function(){return chunkHKVAW3RE_js.a}});Object.defineProperty(exports,"resolveListTemplate",{enumerable:true,get:function(){return chunkHKVAW3RE_js.b}});Object.defineProperty(exports,"toFlowBlocks",{enumerable:true,get:function(){return chunkHKVAW3RE_js.c}});Object.defineProperty(exports,"resetBlockIdCounter",{enumerable:true,get:function(){return chunkIMKU4O3P_js.d}});

package/dist/layout-bridge/toFlowBlocks.mjs

@@ -0,0 +1 @@
+export{a as convertBorderSpecToLayout,b as resolveListTemplate,c as toFlowBlocks}from'../chunk-5VBNOHRE.mjs';export{d as resetBlockIdCounter}from'../chunk-FCJWLEKT.mjs';import'../chunk-7E5VBRDL.mjs';import'../chunk-RFC2SXZ6.mjs';import'../chunk-6ZXL3EIP.mjs';import'../chunk-OEXVWIHW.mjs';import'../chunk-WLHNIXWC.mjs';import'../chunk-67LVRQIR.mjs';import'../chunk-VW22RZ6C.mjs';import'../chunk-QYUPLKLP.mjs';

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

@@ -0,0 +1,352 @@
+/**
+ * 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, TextBoxBlock, TableMeasure, LayoutOptions } from './types.mjs';
+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, TextBoxFragment, TextBoxMeasure, TextRun, WrapTextDirection, assertExhaustiveFlowBlock } from './types.mjs';
+export { isFloatingWrapType, isWrapNone, wrapsAroundText } from '../docx/wrapTypes.mjs';
+import '../content-5Mrz6w_b.mjs';
+import '../formatting-BH4hcZiq.mjs';
+import '../colors-C3vA7HUU.mjs';
+
+/**
+ * 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;
+
+/**
+ * Subset of {@link TextBoxBlock} needed to classify how a text box flows
+ * relative to surrounding content. Kept narrow so callers (measure, layout,
+ * paint) can pass partial views without rebuilding the full block.
+ *
+ * @public
+ */
+type TextBoxFlowAttrs = Pick<TextBoxBlock, 'displayMode' | 'wrapType'>;
+/**
+ * True when a text box participates in float layout — either via the
+ * `float` display mode (CSS-style) or via an OOXML `wrapType` that
+ * positions the box outside paragraph flow (`square`, `tight`, `through`,
+ * `behind`, `inFront`).
+ *
+ * @public
+ */
+declare function isFloatingTextBoxBlock(block: TextBoxFlowAttrs): boolean;
+/**
+ * True when a floating text box reserves an exclusion zone that narrows
+ * surrounding text lines. `wrapNone` (`behind` / `inFront`) and
+ * `topAndBottom` are floats that don't wrap text on their sides.
+ *
+ * @public
+ */
+declare function floatingTextBoxWrapsText(block: TextBoxFlowAttrs): boolean;
+
+/**
+ * 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, TextBoxBlock, type TextBoxFlowAttrs, applyPendingToActive, calculateChainHeight, collectSectionConfigs, computeKeepNextChains, createInitialSectionState, createPaginator, findPageIndexContainingPmPos, floatingTextBoxWrapsText, getEffectiveColumns, getEffectiveMargins, getEffectivePageSize, getHeaderRowsHeight, getMidChainIndices, hasKeepLines, hasPageBreakBefore, isFloatingTextBoxBlock, layoutDocument, scheduleSectionBreak };