reamkit 1.29.0 → 1.31.0

package/dist/esm/layout/styled-layout.d.ts

@@ -7,6 +7,7 @@ import { LaidOutDocument, PageItem } from './page-doc.js';
 import { AttachedFile } from '../pdf/embedded-file.js';
 import { SignaturePlaceholder } from '../pdf/signature.js';
 import { PdfEncryptOptions } from '../pdf/encryption.js';
+import { Sheet } from './turned-section.js';
 import { StructTreeBuilder } from '../pdf/struct-tree.js';
 /**
  * PDF/A conformance string: part 1 (ISO 19005-1, PDF 1.4) / 2 (ISO 19005-2) / 3
@@ -24,15 +25,27 @@ export interface PdfAProfile {
     readonly version: '1.4' | '1.7';
 }
 /**
- * E-PARITY: renderer-compatibility profile for the line-height model.
- *   `'ream'` (default) — Ream's flat 1.2× leading; byte-identical to before.
- *   `'word'` — leading from the font's OS/2 usWin metrics (the GDI cell box).
- *   `'libreoffice'` — leading from hhea (or OS/2 typo when USE_TYPO_METRICS is set).
+ * E-PARITY: renderer-compatibility profile — how lines are measured, broken
+ * and stacked.
+ *   `'ream'` (default) — kerned measuring, Knuth-Plass breaking, and the line
+ *     height the document asks for (see {@link TypesetBy}).
+ *   `'word'` — kern-free measuring, first-fit breaking, and lines as Word sets
+ *     them whatever the document.
+ *   `'libreoffice'` — first-fit breaking, lines from the face in hand: hhea, or
+ *     the OS/2 typo line when USE_TYPO_METRICS is set.
  *
- * Opt-in: a profile emulates that renderer's vertical rhythm for closer visual
- * parity. It never changes default (`'ream'`) output.
+ * Opt-in: a profile emulates that renderer for closer visual parity.
  */
 export type LayoutProfile = 'ream' | 'word' | 'libreoffice';
+/**
+ * The application whose rules a document is set by: `'word'` stands its
+ * lines as tall as the faces on them make them (§17.3.1.33, see
+ * `fontLeadingPt`) rather than Ream's flat 1.2× of the size, and gives every
+ * horizontal table border the room it is wide (§17.4.38, see
+ * `withBorderBands`) rather than none. A Word document's reader asks for it
+ * (see `FlowDoc.typesetBy`).
+ */
+export type TypesetBy = 'word';
 /**
  * The full option set the layout engine and PDF emitter consume: the resolved
  * font registry, the style/numbering tables, the section model and page
@@ -46,6 +59,8 @@ export interface StyledRenderOptions {
     readonly registry: FontRegistry;
     /** Renderer-compatibility profile for the line-height model (default `'ream'`). */
     readonly layoutProfile?: LayoutProfile;
+    /** The application whose rules the document is set by (see {@link TypesetBy}). */
+    readonly typesetBy?: TypesetBy;
     /**
      * Per-run font resolution: when supplied, each text run picks the registry of
      * its declared family (sans→arimo / serif→tinos / mono→cousine via the run's
@@ -173,6 +188,12 @@ export interface StyledRenderOptions {
      * TOP margin, not the left.
      */
     readonly gutterAtTop?: boolean;
+    /**
+     * [MS-DOCX] `compatibilityMode` — the version of Word whose layout the
+     * document asks for; a Word document that states none is an older Word's
+     * (see {@link legacyTableOutdent}).
+     */
+    readonly compatibilityMode?: number;
     /**
      * §7.6 PDF encryption (AES-256, R6). Only honoured on the ASYNC conversion
      * path (WebCrypto); mutually exclusive with `pdfA` (ISO 19005 forbids
@@ -302,6 +323,12 @@ export interface SectionRenderCtx {
     }>;
     readonly headerSet: HeaderFooterSet;
     readonly footerSet: HeaderFooterSet;
+    /**
+     * §17.10 — where the body starts and ends on a page that shows each band:
+     * below the header band and above the footer band that page carries, each
+     * as tall as it is. Absent ⇒ every page takes `marginTop`/`marginBottom`.
+     */
+    readonly bandMargins?: Readonly<Record<HfBand, BodyMargins>>;
     readonly titlePg: boolean;
     readonly evenAndOddHeaders: boolean;
     /**
@@ -316,10 +343,24 @@ export interface SectionRenderCtx {
      * paragraph in it. Absent on a bare context built outside a layout run.
      */
     readonly options?: StyledRenderOptions;
+    /**
+     * §17.6.20 — the sheet a section whose lines run DOWN it prints on. Such a
+     * section's body is laid out in the frame its text reads in, which the
+     * geometry above describes — the sheet turned back a quarter — and turned
+     * onto this sheet page by page, while its header and footer are laid out
+     * on the sheet itself (see ./turned-section). Absent ⇒ the frame is the sheet.
+     */
+    readonly sheet?: Sheet;
+}
+type HfBand = 'default' | 'first' | 'even';
+/** The distances from the paper's top and bottom edges to the body's. */
+interface BodyMargins {
+    readonly top: number;
+    readonly bottom: number;
 }
 interface HfBandEntry {
     readonly commands: Array<PageItem>;
-    readonly renderDynamic?: (pageNumber: number, totalPages: number) => Array<PageItem>;
+    readonly renderDynamic?: (pageText: string, totalPages: number) => Array<PageItem>;
     /** Laid-out height of the band, so the body can be kept clear of it. */
     readonly heightPt?: number;
 }