reamkit 1.16.0 → 1.18.0

package/dist/esm/layout/page-doc.d.ts

@@ -1,9 +1,10 @@
-import { BorderStyle } from '../core/document-model/index.js';
+import { BorderStyle, ImageCrop, PictureOutline, ShapeShadow } from '../core/document-model/index.js';
 import { Pt, ResourceId, ResourceStore } from '../core/ir/index.js';
 import { FontMeasure, ParsedTtf } from '../core/font/index.js';
 import { ResolvedParagraphProperties, ResolvedRunProperties } from '../core/style-cascade/index.js';
-import { PathSegment, VectorShape } from '../core/vector.js';
+import { PathSegment, StrokeStyle, VectorPath, VectorShape } from '../core/vector.js';
 import { PreparedImage } from '../core/images.js';
+import { MetaPicture } from '../core/metafile/picture.js';
 /** A font bound into a {@link LaidOutDocument}: the parsed face plus what layout/emit need from it. */
 export interface FontResource {
     readonly resourceName: string;
@@ -42,6 +43,17 @@ export interface TextToken {
      * element separate from the item body.
      */
     readonly listMarker?: true;
+    /**
+     * §17.3.3.1 — the token is the break of a `w:br w:type="column"`: what
+     * follows it belongs in the next column.
+     */
+    readonly columnBreak?: true;
+    /**
+     * §17.3.1.38 — the token IS a tab: its width is the distance to the stop it
+     * advances to, resolved once the line is known, and its text is whatever
+     * leader fills that gap.
+     */
+    readonly tab?: true;
     /**
      * The token falls inside a comment range (`commentRangeRefs`): the emitter
      * fills a soft highlight behind it (E-COMMENTS CM2c).
@@ -69,6 +81,39 @@ export interface ImageToken {
     readonly imageResourceName: string;
     readonly widthPt: number;
     readonly heightPt: number;
+    /** §20.1.2.2.24 — the frame the picture is drawn with, when it has one. */
+    readonly outline?: PictureOutline;
+    /** §20.1.8.40 — the drop shadow under the picture, when it casts one. */
+    readonly shadow?: ShapeShadow;
+    /** §14.1.2.10 — the contrast/brightness wash the picture is drawn through. */
+    readonly wash?: {
+        readonly gain: number;
+        readonly black: number;
+    };
+    /**
+     * MS-EMF / MS-WMF — the picture to DRAW in this token's box, for an inline
+     * metafile: it has no raster to place, so the emitter plays its primitives
+     * where the token stands.
+     */
+    readonly metafile?: MetafileDrawing;
+    /** §20.1.8.55 `a:srcRect` — the part of the source the frame shows. */
+    readonly crop?: ImageCrop;
+    /** §20.1.7.6 — degrees clockwise about the box's centre. */
+    readonly rotationDeg?: number;
+    /** §20.1.7.6 — the picture drawn mirrored in its box. */
+    readonly flipH?: boolean;
+    readonly flipV?: boolean;
+    /**
+     * §20.4.2.6 — where the picture itself sits inside the reserved box when the
+     * drawing asked for an effect extent: offsets from the box's left edge and
+     * from the baseline, plus the drawn size. Absent ⇒ the picture fills the box.
+     */
+    readonly drawBox?: {
+        readonly dxPt: number;
+        readonly dyPt: number;
+        readonly widthPt: number;
+        readonly heightPt: number;
+    };
     /** Constants kept to satisfy {@link Token} consumers — they never read these for images. */
     readonly isSpace: false;
     readonly bidiLevel: number;
@@ -121,6 +166,12 @@ export interface Line {
     readonly firstLine: boolean;
     readonly resolved: ResolvedParagraphProperties;
     isLastInParagraph: boolean;
+    /**
+     * ECMA-376 §17.15.1.35 — the line ends at a soft line break in a document
+     * that asked for `w:doNotExpandShiftReturn`, so justification leaves it at
+     * its natural width (as the paragraph's own last line is left).
+     */
+    readonly noJustify?: boolean;
     /**
      * Max ascent/descent contributed by math tokens (0 when none) — they straddle
      * the baseline, so the line height/descent must grow to fit them.
@@ -136,13 +187,39 @@ export interface Line {
     readonly metricDescentPt?: number;
 }
 /** An image bound into a {@link LaidOutDocument}: its resource name plus the decoded/validated bytes. */
+/**
+ * MS-EMF / MS-WMF — a metafile picture, ready to draw: paths and words in a
+ * local y-up frame whose origin is the picture box's bottom-left corner. The
+ * same vocabulary a chart's layout carries, because a metafile draws the same
+ * two things.
+ */
+export interface MetafileDrawing {
+    readonly shapes: ReadonlyArray<{
+        readonly paths: ReadonlyArray<VectorPath>;
+        readonly fillColorHex?: string;
+        readonly stroke?: StrokeStyle;
+    }>;
+    readonly texts: ReadonlyArray<{
+        readonly line: Line;
+        readonly x: number;
+        readonly y: number;
+        readonly rotationDeg?: number;
+    }>;
+}
 export interface ImageResource {
     readonly resourceName: string;
     /**
      * Decoded/validated at layout time (the probe); the emit phase replays it
-     * without touching the source bytes again.
+     * without touching the source bytes again. Absent for a METAFILE, which has
+     * no raster to embed: it is drawn as the primitives `metafile` holds.
      */
-    readonly prepared: PreparedImage;
+    readonly prepared?: PreparedImage;
+    /**
+     * MS-EMF / MS-WMF — the picture read out of the resource, in its own logical
+     * units. A metafile is a little drawing program, not a raster; the layout
+     * turns these into the same primitives a chart is made of.
+     */
+    readonly metafile?: MetaPicture;
 }
 /**
  * The fields every {@link PageItem} shares (ir-design §6, frozen at stage 6.4):
@@ -154,6 +231,11 @@ export interface ImageResource {
  * numbers — they are not page-frame coordinates.
  */
 export interface PageItemBase {
+    /**
+     * §20.4.2.3 — the float's `relativeHeight`. Items with one are sorted by it
+     * inside their layer before the page is written; the rest keep their order.
+     */
+    readonly z?: number;
     /**
      * Tagged PDF (§14.8): the logical structure node this item's content belongs
      * to. Set only on body content in tagged mode; undefined text in the line pass
@@ -225,6 +307,27 @@ export interface ImageItem extends PageItemBase {
     readonly width: Pt;
     readonly height: Pt;
     readonly imageResourceName: string;
+    /** §20.1.8.55 `a:srcRect` — the part of the source the frame shows. */
+    readonly crop?: ImageCrop;
+    /** §14.1.2.10 — the contrast/brightness wash the picture is drawn through. */
+    readonly wash?: {
+        readonly gain: number;
+        readonly black: number;
+    };
+    /** §20.1.7.6 — degrees clockwise about the box's centre. */
+    readonly rotationDeg?: number;
+    /** §20.1.7.6 — the picture drawn mirrored in its box. */
+    readonly flipH?: boolean;
+    readonly flipV?: boolean;
+    /**
+     * §20.1.8.14 — a picture FILL is the shape's outline painted with a picture,
+     * so it is clipped to that outline: the paths in the shape's local frame and
+     * the matrix that maps them onto the page.
+     */
+    readonly clip?: {
+        readonly paths: ReadonlyArray<VectorPath>;
+        readonly transform: readonly [number, number, number, number, number, number];
+    };
 }
 /**
  * DrawingML vector geometry. `shape.transform` maps the shape's local y-up frame

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

@@ -1,12 +1,12 @@
-import { BodyElement, Chart, Comment, DocumentInfo, Numbering, Section, SectionProperties, StyleSheet } from '../core/document-model/index.js';
+import { BodyElement, Chart, Comment, DocumentInfo, Numbering, Section, SectionProperties, ShapeFill, StyleSheet } from '../core/document-model/index.js';
 import { FontRegistry } from '../core/font/index.js';
 import { FamilyKey } from '../core/fonts/index.js';
 import { Hyphenator } from '../core/hyphenation/index.js';
+import { Pt, ResourceStore } from '../core/ir/index.js';
 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 { ResourceStore } from '../core/ir/index.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
@@ -75,6 +75,12 @@ export interface StyledRenderOptions {
      * `body[sections[N-1].endIndex..sections[N].endIndex)`).
      */
     readonly sections?: ReadonlyArray<Section>;
+    /**
+     * §17.6.5 — the pitch of the document grid the text is laid on. Set by the
+     * layout itself, per section (see {@link SectionRenderCtx.options}); callers
+     * state it on the section, not here.
+     */
+    readonly gridLinePitchPt?: Pt;
     /** Header/footer body content keyed by relationship id. */
     readonly headersFooters?: ReadonlyMap<string, ReadonlyArray<BodyElement>>;
     /**
@@ -149,6 +155,24 @@ export interface StyledRenderOptions {
      * converter fills this from the document's default `w:lang`.
      */
     readonly language?: string;
+    /**
+     * ECMA-376 §17.15.1.35 `w:doNotExpandShiftReturn` — when set, a justified
+     * line that ends at a soft line break (`w:br`) is drawn at its natural width
+     * instead of being stretched out to the measure.
+     */
+    readonly doNotExpandShiftReturn?: boolean;
+    /**
+     * ECMA-376 §17.2.1 `w:background` — the colour every page is painted before
+     * anything else is drawn on it. Absent ⇒ the paper's own white.
+     */
+    readonly pageBackgroundColorHex?: string;
+    /** §17.2.1 — the background's gradient or picture, when it has one. */
+    readonly pageBackgroundFill?: ShapeFill;
+    /**
+     * ECMA-376 §17.15.1.38 `w:gutterAtTop` — the binding space belongs to the
+     * TOP margin, not the left.
+     */
+    readonly gutterAtTop?: boolean;
     /**
      * §7.6 PDF encryption (AES-256, R6). Only honoured on the ASYNC conversion
      * path (WebCrypto); mutually exclusive with `pdfA` (ISO 19005 forbids
@@ -175,6 +199,12 @@ export type { DocumentInfo } from '../core/document-model/index.js';
 export declare const A4_WIDTH = 595;
 /** A4 page height in points (the page-geometry fallback). */
 export declare const A4_HEIGHT = 842;
+/**
+ * How far a space may be squeezed below its natural width — the shrink the
+ * line breaker offers when it weighs a line, and therefore the shrink the
+ * emitter owes it back when it draws one.
+ */
+export declare const GLUE_SHRINK_RATIO = 0.3;
 /**
  * §17.13.6.2 — a bookmark's GoTo destination: the page (0-based) and the y-up
  * top of the anchoring paragraph's first line.
@@ -274,6 +304,18 @@ export interface SectionRenderCtx {
     readonly footerSet: HeaderFooterSet;
     readonly titlePg: boolean;
     readonly evenAndOddHeaders: boolean;
+    /**
+     * §17.6.22 — the section begins on the page already in hand, at the point the
+     * one before it stopped, rather than on a fresh one.
+     */
+    readonly continuous: boolean;
+    /**
+     * The render options this section's content is laid out with: `options` plus
+     * whatever the section itself decides for its text — today only §17.6.5's
+     * document grid, which is a property of the SECTION and is needed by every
+     * paragraph in it. Absent on a bare context built outside a layout run.
+     */
+    readonly options?: StyledRenderOptions;
 }
 interface HfBandEntry {
     readonly commands: Array<PageItem>;