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

package/dist/text/glyph-coverage.js

@@ -39,19 +39,23 @@ const EQUIVALENTS = {
  * Replaces or removes what `fontFamily` cannot draw. Returns the input unchanged (and no allocation
  * beyond the scan) when everything is drawable, which is the overwhelmingly common case.
  */
-export function coverText(text, fontFamily, fontStyle, metrics) {
+export function coverText(text, fontFamily, fontStyle, metrics, 
+// Whether colour emoji count as drawable: in `Text` they are drawn from the emoji source; a form
+// field's appearance has only its own font.
+emoji = true) {
     let out = null; // built only once something has to change
     const dropped = [];
     let index = 0;
     for (const char of text) {
         const cp = char.codePointAt(0);
-        // A space and a line break are handled by the breaker, never drawn as a glyph.
+        // A space, a line break and a soft hyphen are handled by the breaker, never drawn as a glyph.
         const drawable = cp === 0x20 ||
             cp === 0x0a ||
+            cp === 0xad ||
             metrics.hasGlyph(cp, fontFamily, fontStyle) ||
             // Colour emoji is drawn from a fallback font or an image, NOT from the text font - it is missing
             // there by design, and removing it would delete the very thing `Document({ emoji })` exists for.
-            metrics.rendersAsEmoji?.(cp, fontFamily, fontStyle) === true;
+            (emoji && metrics.rendersAsEmoji?.(cp, fontFamily, fontStyle) === true);
         if (!drawable) {
             if (out === null)
                 out = text.slice(0, index);

package/dist/text/hyphen-breaks.d.ts

@@ -0,0 +1,17 @@
+export declare const NO_BREAKS: readonly number[];
+/** Whether a word holds anything it may break after: a hyphen or a soft hyphen. */
+export declare const mayBreak: (word: string) => boolean;
+/**
+ * Where a word may break, as offsets into it - after a hyphen (U+002D) as UAX #14 has it: never before
+ * it, never before a digit ("CODE-2", "2026-10-16", "-5" stay whole), never after one that starts the
+ * word; and after a soft hyphen (U+00AD), the break its author marked.
+ */
+export declare function hyphenBreaks(word: string): number[];
+/**
+ * What the line ending at break `k` draws of `word`: everything before it, and at a soft hyphen a REAL
+ * hyphen in its place - the only time a soft hyphen shows. The breaker draws this; measuring it measures
+ * what is drawn.
+ */
+export declare function headAt(word: string, k: number): string;
+/** A word cut at its break opportunities: the pieces no line can split, as they are drawn. */
+export declare function hyphenPieces(word: string): string[];

package/dist/text/hyphen-breaks.js

@@ -0,0 +1,54 @@
+import { SOFT_HYPHEN } from "./advance.js";
+import { HYPHEN } from "./word-splitting.js";
+// Where a word MAY break inside itself - pure text rules, no font and no line. Filling lines is
+// `line-breaker.ts`; this only answers which offsets are allowed.
+export const NO_BREAKS = [];
+/** Whether a word holds anything it may break after: a hyphen or a soft hyphen. */
+export const mayBreak = (word) => word.includes("-") || word.includes(SOFT_HYPHEN);
+/**
+ * Where a word may break, as offsets into it - after a hyphen (U+002D) as UAX #14 has it: never before
+ * it, never before a digit ("CODE-2", "2026-10-16", "-5" stay whole), never after one that starts the
+ * word; and after a soft hyphen (U+00AD), the break its author marked.
+ */
+export function hyphenBreaks(word) {
+    const out = [];
+    for (let i = 1; i < word.length - 1; i++) {
+        const next = word[i + 1];
+        if (NO_BREAK_BEFORE.has(next))
+            continue;
+        if (word[i] === SOFT_HYPHEN) {
+            out.push(i + 1);
+            continue;
+        }
+        if (word[i] !== "-")
+            continue;
+        if (next === "-" || (next >= "0" && next <= "9"))
+            continue;
+        out.push(i + 1);
+    }
+    return out;
+}
+// UAX #14 never breaks before closing punctuation, a slash or a quote (LB13, LB19): "Lohn-, Gehalts-",
+// "(well-known)", "Ein-/Ausgang" stay together.
+const NO_BREAK_BEFORE = new Set(")]}!?,.:;/\"'«»‘’“”");
+/**
+ * What the line ending at break `k` draws of `word`: everything before it, and at a soft hyphen a REAL
+ * hyphen in its place - the only time a soft hyphen shows. The breaker draws this; measuring it measures
+ * what is drawn.
+ */
+export function headAt(word, k) {
+    if (word[k - 1] !== SOFT_HYPHEN)
+        return word.slice(0, k);
+    // A soft hyphen right after a real one adds nothing: "ab-" + "cd", not "ab--".
+    return word[k - 2] === "-" ? word.slice(0, k - 1) : word.slice(0, k - 1) + HYPHEN;
+}
+/** A word cut at its break opportunities: the pieces no line can split, as they are drawn. */
+export function hyphenPieces(word) {
+    const breaks = mayBreak(word) ? hyphenBreaks(word) : NO_BREAKS;
+    if (breaks.length === 0)
+        return [word];
+    return [0, ...breaks].map((from, k) => {
+        const to = breaks[k];
+        return to === undefined ? word.slice(from) : headAt(word, to).slice(from);
+    });
+}

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,32 @@ 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;
+/** How one span is measured, broken and drawn. */
+export interface RunStyle {
+    font: RunFont;
+    letterSpacing: number;
+    wordSpacing: number;
+    splitting: WordSplitting;
+}
+/**
+ * A span's run style: what it sets itself, else what the paragraph sets. The ONE place a span inherits
+ * it, so breaking, drawing and the element's own sizing ask the same question.
+ */
+export declare function runStyleOf(seg: TextSegment, defaults: SegmentDefaults): RunStyle;
 /** 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 +62,51 @@ 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;
+    /** How far the line, as drawn, runs past the room it was broken in: above 0 only for a piece that
+     *  could not break. */
+    overrun: 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.
+ * A line's spaces, each as wide as its own span makes it - what justification spreads the slack over,
+ * and squeezes by at most `shrink` of their width.
  */
+export declare function lineGaps(segments: TextSegment[], defaults: SegmentDefaults, metrics: FontMetrics): {
+    gaps: number;
+    width: number;
+};
+export interface SegmentPosition {
+    segment: number;
+    offset: number;
+}
 /**
- * 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[];