@jasy/pdf 1.0.0-beta.3 → 1.0.0-beta.4

package/dist/text/line-breaker.d.ts

@@ -1,6 +1,7 @@
 import type { FontStyle } from "../utils/pdf-object-manager.js";
 import type { FontMetrics } from "../utils/font-metrics.js";
 import type { TextSegment } from "../elements/text-element.js";
+import { type RunFont } from "./advance.js";
 import { type WordSplitting } from "./word-splitting.js";
 /**
  * How far a JUSTIFIED line's spaces may be squeezed to keep one more word on it.
@@ -27,18 +28,20 @@ export interface LineOptions {
     splitting?: WordSplitting;
     /** Whether the run gets the font's ligatures. Changes which glyphs are drawn, hence the width. */
     ligatures?: boolean;
+    /** Only the first N lines belong to this element: a paragraph split across pages, continued on the
+     *  next one. Applied after `maxLines`, so every pass that breaks the text sees the same lines. */
+    shownLines?: number;
 }
-/** Default font for segments that don't override it. */
-export interface SegmentDefaults {
+/** What a span that does not set its own draws with: the paragraph's font and spacing. */
+export interface RunDefaults {
     fontFamily: string;
     fontSize: number;
     fontStyle: FontStyle;
     /** Extra space after every glyph, in points; a segment may override it. Default 0. */
     letterSpacing?: number;
-    /** Same knobs as the string path - see `LineOptions.splitting`. */
-    splitting?: WordSplitting;
-    ligatures?: boolean;
 }
+/** Everything the breaker reads besides the spans: what they inherit, and how lines end. */
+export type SegmentDefaults = RunDefaults & LineOptions;
 /** What happens to text beyond `maxLines`: `"clip"` drops it, `"ellipsis"` ends the last kept line
  *  with an ellipsis. Mirrors Flutter's `TextOverflow`. */
 export type TextOverflow = "clip" | "ellipsis";
@@ -47,40 +50,40 @@ export type TextOverflow = "clip" | "ellipsis";
 export interface SegmentLine {
     segments: TextSegment[];
     width: number;
+    /** Where the line begins in the source: the span, and the offset in that span's content. */
+    start: SegmentPosition;
+    end: LineEnd;
+}
+export interface SegmentPosition {
+    segment: number;
+    offset: number;
 }
 /**
- * Break a plain string into lines that each fit within `maxWidth`, splitting on
- * spaces (greedy: a word stays on the current line unless it would overflow).
- *
- * Single source of truth for plain-string wrapping: both height measurement and
- * rendering call this, so they can never disagree. Depends only on `FontMetrics`,
- * not the PDF byte writer - the future fragmentation pass can reuse it.
- */
-/**
- * The width of `text` set as ONE line, accumulated in EXACTLY the order `wrapStringIntoLines` builds a
- * line: the first word, then `+ (space + word)` each time. The order matters because floating-point
+ * The width of `text` set as ONE line, accumulated in EXACTLY the order the breaker builds a line: the
+ * first word, then `+ (space + word)` each time. The order matters because floating-point
  * addition is not associative - a box sized by a differently-grouped sum can be one bit too small for
  * the very line the breaker then measures, and the text wraps inside a box made to fit it. That is not
  * hypothetical: it is what split a footer sized to its own content.
  */
-export declare function singleLineWidth(text: string, font: {
-    fontFamily: string;
-    fontSize: number;
-    fontStyle: FontStyle;
-}, metrics: FontMetrics, letterSpacing?: number, wordSpacing?: number): number;
+export declare function singleLineWidth(text: string, font: RunFont, metrics: FontMetrics, letterSpacing?: number, wordSpacing?: number): number;
 export declare function wrapStringIntoLines(text: string, fontFamily: string, fontSize: number, fontStyle: FontStyle, maxWidth: number, metrics: FontMetrics, maxLines?: number, overflow?: TextOverflow, letterSpacing?: number, options?: LineOptions): string[];
+/** How a line ends - which is what justification and splitting a paragraph across pages need. */
+export type LineEnd = "soft" | "hard" | "split" | "hyphen" | "end";
+/** A broken line, and where it came from: `start` is the offset in the source text it begins at. */
+export interface BrokenLine {
+    text: string;
+    start: number;
+    end: LineEnd;
+}
 /**
- * Break styled segments into lines that fit within `maxWidth`. Same greedy word-splitting as the
- * string breaker; each line keeps the segments that landed on it, which is what `line-metrics.ts`
- * later derives the line's height from. Single source of truth: both height measurement and
- * rendering call this.
+ * `wrapStringIntoLines`, with each line's source offset and ending. The ONE breaking pass both share,
+ * so a line's position in the source can never disagree with the line itself.
  */
-export declare function breakSegmentsIntoLines(segments: TextSegment[], defaults: SegmentDefaults, maxWidth: number, metrics: FontMetrics, maxLines?: number, overflow?: TextOverflow): SegmentLine[];
+export declare function breakStringIntoLines(text: string, fontFamily: string, fontSize: number, fontStyle: FontStyle, maxWidth: number, metrics: FontMetrics, maxLines?: number, overflow?: TextOverflow, letterSpacing?: number, options?: LineOptions): BrokenLine[];
 /**
- * Inverse of `breakSegmentsIntoLines`: flatten broken lines back into a `TextSegment[]`
- * that re-wraps to exactly those lines. The wrap consumed the space at each line break,
- * so re-insert one between lines (unless the piece already ends with one) - otherwise the
- * last word of a line and the first of the next would fuse ("a b" + "c d" -> "a bc d").
- * Used by text fragmentation to rebuild the fitted/remainder halves of a split paragraph.
+ * Break text - spans; a plain string is one - into lines that fit within `maxWidth`, greedily: a word
+ * stays on the current line unless it would overflow. Each line keeps the segments that landed on it,
+ * which is what `line-metrics.ts` derives the line's height from. The one breaker: measuring,
+ * fragmenting and drawing all call this.
  */
-export declare function segmentLinesToSegments(lines: SegmentLine[]): TextSegment[];
+export declare function breakSegmentsIntoLines(segments: TextSegment[], defaults: SegmentDefaults, maxWidth: number, metrics: FontMetrics, maxLines?: number, overflow?: TextOverflow): SegmentLine[];