docxodus 7.1.0 → 9.0.0

package/dist/pagination.d.ts

@@ -117,6 +117,12 @@ export interface PaginationOptions {
     showPageNumbers?: boolean;
     /** Gap between pages in pixels. Default: 20 */
     pageGap?: number;
+    /**
+     * Whether ordinary paragraphs may be fragmented across page boundaries.
+     * Defaults to false for direct PaginationEngine callers; read-only viewer
+     * entry points opt in explicitly.
+     */
+    fragmentParagraphs?: boolean;
 }
 /**
  * Pagination engine that converts HTML with pagination metadata
@@ -133,9 +139,12 @@ export declare class PaginationEngine {
     private cssPrefix;
     private showPageNumbers;
     private pageGap;
+    private fragmentParagraphs;
     private hfRegistry;
     private footnoteRegistry;
     private pendingFootnoteContinuation;
+    /** Per-section `w:pgNumType` (start / format), read off the section wrappers. */
+    private pageNumbering;
     /**
      * Creates a new pagination engine.
      *
@@ -150,10 +159,106 @@ export declare class PaginationEngine {
      * @returns PaginationResult with page information
      */
     paginate(): PaginationResult;
+    /** Read each section's `w:pgNumType` off its wrapper (see {@link SectionPageNumbering}). */
+    private parsePageNumbering;
+    /**
+     * Fill in the page-number fields inside every page's cloned header/footer.
+     *
+     * A header/footer is authored once and cloned onto each page, so a PAGE field's single cached
+     * result would otherwise show the same number on every page — the whole reason the converter
+     * marks these. `data-field-format` (the field's own `\*` switch) wins over the section's format
+     * when present, which is exactly how Word resolves the two.
+     *
+     * Runs after layout because NUMPAGES cannot be known before the last page exists. The
+     * substituted text can therefore be marginally wider than the cached result the header was
+     * measured with; the header band clips, so the failure mode is a hair of overflow rather than
+     * a layout that disagrees with itself.
+     *
+     * Scoped to the CLONED header/footer regions on purpose. A page-number field in body text is
+     * ordinary run content that the editor may make editable, and committing an edited block writes
+     * back whatever text the DOM holds — rewriting it here would mean a body field commits a number
+     * the document never contained. Body content is also not cloned, so it does not have the problem
+     * this method exists to solve.
+     */
+    private substitutePageNumberFields;
     /**
      * Measures all content blocks in a section.
      */
     private measureBlocks;
+    /**
+     * Measures one element in the same hidden staging context used for the source blocks.
+     * This is intentionally DOM-based: table row heights cannot be inferred from individual
+     * rows because wrapping and collapsed borders change the height of a fragment.
+     */
+    private measureElement;
+    /**
+     * Returns the contiguous keep-with-next chain beginning at a block.
+     *
+     * A hard page break or a page-break-before directive is stronger than a
+     * keep-with-next directive, so it terminates the chain. The caller only
+     * keeps a chain together when the whole chain can fit on a fresh page.
+     */
+    private getKeepWithNextChain;
+    /**
+     * Measures the visible body height of a keep-with-next chain using the same
+     * collapsed-margin rules as normal block placement. The trailing margin is
+     * intentionally excluded, matching the individual block fit check.
+     */
+    private measureKeepWithNextChainBodyHeight;
+    /**
+     * Finds footnote references introduced by a sequence of blocks, preserving
+     * document order and excluding references already assigned to the page.
+     */
+    private collectNewFootnoteIds;
+    /**
+     * The shortest body available to a section's first, default, or even page.
+     * A row fragment must fit every variant, otherwise a later header/footer could
+     * send it through the oversized-block fallback again.
+     */
+    private smallestEffectiveContentHeight;
+    /**
+     * Builds a clone of a simple table wrapper containing a contiguous run of rows.
+     * Complex table features are deliberately rejected by the caller: a split across
+     * merged cells, nested tables, or footnotes cannot be made correct by cloning rows.
+     */
+    private createSimpleTableFragment;
+    /**
+     * Splits an oversized, ordinary table at row boundaries. This only participates
+     * in the existing oversized-block fallback; unsupported tables keep the previous
+     * overflow behavior rather than risking broken table semantics.
+     */
+    private trySplitSimpleOversizedTable;
+    /**
+     * A DOM endpoint that can finish a paragraph fragment. Endpoints are chosen
+     * after whitespace or at a run boundary so the paginator never deliberately
+     * cuts through an ordinary word merely to fill a little more of a page.
+     */
+    private paragraphFragmentEndpoints;
+    /**
+     * Whether a range contains visible text after ignoring bidi/zero-width marks.
+     * Paragraph fragmentation deliberately excludes non-textual descendants, so
+     * this is enough to reject empty head or tail fragments.
+     */
+    private hasVisibleFragmentText;
+    /**
+     * Phase one only handles text-like paragraph descendants. Objects, explicit
+     * line breaks, list markers, notes, and out-of-flow/inline-block content all
+     * require their own line-layout rules and retain the established whole-block
+     * fallback instead of risking broken content or duplicate anchors.
+     */
+    private canFragmentParagraph;
+    /**
+     * Builds one range-cloned paragraph fragment. Only the leading fragment keeps
+     * the source paragraph's addressability; continuations must not duplicate an
+     * id/data-anchor in the rendered document.
+     */
+    private createParagraphFragment;
+    /**
+     * Splits a simple paragraph at the largest DOM Range endpoint that fits the
+     * currently available body space. The caller then processes the tail normally,
+     * allowing it to fragment again on later pages when necessary.
+     */
+    private tryFragmentParagraph;
     /**
      * Parses the header/footer registry from the staging element.
      * Also measures heights during parsing for lazy-loading compatibility.
@@ -219,6 +324,20 @@ export declare class PaginationEngine {
      * Supports footnote continuation - long footnotes can split across pages.
      */
     private flowToPages;
+    /**
+     * Strip block addressing from a header/footer node cloned into a page box.
+     *
+     * A running story is authored ONCE and cloned onto every page, so the clones all carry the same
+     * `data-anchor` — on this document, 42 page boxes claiming one footer paragraph. Left editable,
+     * committing any one of them writes back through that single shared anchor, and the per-page
+     * page-number substitution makes it worse: each clone shows a DIFFERENT number, so a commit
+     * writes that page's number into the story as literal text and destroys the PAGE field.
+     *
+     * Page-box header/footer content is presentation. The docked editing bands
+     * (`editor-headerfooter.ts`) are the addressable affordance, and they exist precisely because a
+     * cloned node cannot be uniquely addressed.
+     */
+    private makeClonedStoryInert;
     /**
      * Creates a page container element.
      */

package/dist/pagination.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pagination.d.ts","sourceRoot":"","sources":["../src/pagination.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"pagination.d.ts","sourceRoot":"","sources":["../src/pagination.ts"],"names":[],"mappings":"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"}