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

package/dist/text/word-splitting.js

@@ -29,8 +29,8 @@ export function splitLongWord(word, room, font, metrics, letterSpacing, options)
         // the blunt one - which is what an e-mail address or an IBAN needs, having no valid point at all.
         const head = (hyphenate ? longestHyphenatedPrefix(rest, room, width, hyphenate) : null) ??
             (breakWord ? longestPrefix(rest, room, width) : null);
-        // Nothing fits - not even one character, or hyphenation found nothing and break-word is off.
-        // Leave the remainder whole and let it overflow, exactly as before.
+        // Hyphenation found nothing and break-word is off, or one character is all that is left: leave the
+        // remainder whole and let it overflow.
         if (head === null)
             break;
         // A hyphenator that returns text other than the word is not splitting it: leave it whole.
@@ -90,9 +90,15 @@ function longestPrefix(word, room, width) {
         taken += char;
         count += 1;
     }
-    // Not even one character fits: the box is narrower than a single glyph. Splitting cannot help, and
-    // looping on it would never terminate.
-    if (count === 0 || count === chars.length)
+    if (count === chars.length)
         return null;
+    // Not even one character fits - the box is narrower than a glyph: one character per line, as CSS
+    // `overflow-wrap` sets it. Each pass still takes one, so the loop ends.
+    if (count === 0) {
+        if (chars.length === 1)
+            return null;
+        taken = chars[0];
+        count = 1;
+    }
     return { text: taken, taken, rest: chars.slice(count).join(""), hyphen: false };
 }

package/dist/utils/flex-layout.d.ts

@@ -29,7 +29,8 @@ export interface FlexAxis {
      * unbounded main axis and shrink-wraps as before.
      */
     measureConstraints(crossAvail: number, mainMax?: number): BoxConstraints;
-    /** Constraints for a flex child (fills the cross axis like a stretched child). */
+    /** Constraints for a flex child: its main extent is SET (it fills its share, whatever size it asked
+     *  for), across it is an ordinary child. */
     flexConstraints(mainExtent: number, crossAvail: number): BoxConstraints;
     /** Offset (from the stack's top-left) of a child at main position `mainPos`, cross `crossPos`. */
     offsetAt(mainPos: number, crossPos: number): Offset;
@@ -58,6 +59,7 @@ export declare class FlexLayoutHelper {
     static layout(children: PDFElement[], axis: FlexAxis, mainAvail: number, crossAvail: number, options: FlexOptions, ctx: LayoutContext, mode?: FlexMode): {
         mainUsed: number;
         crossUsed: number;
+        widestLine?: number;
     };
     /**
      * The wrapping path: split into lines, lay each one out, then place the lines across the axis.

package/dist/utils/flex-layout.js

@@ -9,7 +9,7 @@ export const VERTICAL_AXIS = {
     mainOf: (s) => s.height,
     crossOf: (s) => s.width,
     measureConstraints: (crossAvail, mainMax = Infinity) => BoxConstraints.loose(crossAvail, mainMax),
-    flexConstraints: (mainExtent, crossAvail) => BoxConstraints.loose(crossAvail, mainExtent),
+    flexConstraints: (mainExtent, crossAvail) => new BoxConstraints(0, crossAvail, mainExtent, mainExtent),
     offsetAt: (mainPos, crossPos) => ({ x: crossPos, y: mainPos }),
 };
 export const HORIZONTAL_AXIS = {
@@ -17,7 +17,7 @@ export const HORIZONTAL_AXIS = {
     mainOf: (s) => s.width,
     crossOf: (s) => s.height,
     measureConstraints: (crossAvail, mainMax = Infinity) => BoxConstraints.loose(mainMax, crossAvail),
-    flexConstraints: (mainExtent, crossAvail) => BoxConstraints.loose(mainExtent, crossAvail),
+    flexConstraints: (mainExtent, crossAvail) => new BoxConstraints(mainExtent, mainExtent, 0, crossAvail),
     offsetAt: (mainPos, crossPos) => ({ x: mainPos, y: crossPos }),
 };
 /** Cross-axis offset of a child of size `childCross` within `crossExtent`. */
@@ -123,12 +123,24 @@ export class FlexLayoutHelper {
         // Each line keeps SOURCE order internally: the ordering was applied above, and applying it again
         // per line would reverse twice.
         const lineOptions = { ...options, wrap: false, reverse: false, main: mainAlignOf(options) };
-        const measure = lines.map((line) => FlexLayoutHelper.layoutLine(line, axis, mainAvail, 
-        // Across a Column a child gets the column's width, as a block does in CSS (a paragraph wraps
-        // inside it); across a Row it is as tall as its content. Either way the line is only as big as
-        // what is on it, so `stretch` fills the line and not the container.
-        axis.mainHorizontal ? Infinity : crossAvail, 0, lineOptions, ctx, "measure", true));
-        const heights = measure.map((m) => m.crossUsed);
+        const measureAt = (line, cross) => FlexLayoutHelper.layoutLine(line, axis, mainAvail, cross, 0, lineOptions, ctx, "measure", true);
+        // Across a Column a child gets the column's width, as a block does in CSS (a paragraph wraps inside
+        // it); across a Row it is as tall as its content. Either way the line is only as big as what is on
+        // it, so `stretch` fills the line and not the container. A region-sized child (a Flow) has no
+        // content height: its line shares what the other lines leave of the Row's height.
+        const regionLine = (line) => axis.mainHorizontal && line.some((c) => c.needsRegion());
+        const measure = lines.map((line) => regionLine(line) ? null : measureAt(line, axis.mainHorizontal ? Infinity : crossAvail));
+        const regionLines = lines.filter(regionLine).length;
+        if (regionLines > 0) {
+            const taken = measure.reduce((n, m) => n + (m?.crossUsed ?? 0), 0) + Math.max(0, lines.length - 1) * gap;
+            const share = Math.max(0, crossAvail - taken) / regionLines;
+            lines.forEach((line, i) => {
+                if (regionLine(line))
+                    measure[i] = measureAt(line, share);
+            });
+        }
+        const sized = measure;
+        const heights = sized.map((m) => m.crossUsed);
         const totalCross = heights.reduce((n, h) => n + h, 0) + Math.max(0, lines.length - 1) * gap;
         // `alignContent` distributes the BLOCK of lines across the axis, using the same vocabulary the main
         // axis uses. Only meaningful in a bounded cross axis with room left over.
@@ -156,7 +168,12 @@ export class FlexLayoutHelper {
             if (i < lines.length - 1)
                 cursor += between;
         });
-        return { mainUsed: mainAvail, crossUsed: Math.max(totalCross, cursor) };
+        return {
+            mainUsed: mainAvail,
+            crossUsed: Math.max(totalCross, cursor),
+            // A child wider than the line runs past it, in a line of its own.
+            widestLine: Math.max(...sized.map((m) => m.mainUsed)),
+        };
     }
     /**
      * Lays out ONE flex line along `axis` and places every child. Fixed children take their natural main
@@ -193,6 +210,9 @@ export class FlexLayoutHelper {
             shrunkCap: new Map(),
             sharedCap: new Map(),
             shrunkBasis: new Map(),
+            flexFloor: new Map(),
+            flexCeil: new Map(),
+            flexExtent: new Map(),
         };
         measureLine(line);
         shrinkLine(line);
@@ -203,10 +223,11 @@ export class FlexLayoutHelper {
         const remaining = Number.isFinite(leftover) ? Math.max(leftover, 0) : 0;
         const weight = shareLeftover(line, remaining);
         const spacing = mainSpacing(mainAlignOf(options), gap, ordered.length, mainAvail, leftover, weight);
-        measureFlex(line, weight, remaining);
+        shareFlex(line, weight, remaining);
+        measureFlex(line, options.cross ?? "stretch");
         // The cross extent children align within: the bounded line size, else the tallest child.
         const crossExtent = crossAvail !== Infinity && !crossFromContent ? crossAvail : line.crossUsed;
-        return placeLine(line, options.cross ?? "stretch", crossExtent, crossOrigin, spacing, weight, remaining, mode);
+        return placeLine(line, options.cross ?? "stretch", crossExtent, crossOrigin, spacing, mode);
     }
 }
 /** A flex child's basis on this line: what it asked for, or less once the line has shrunk it. */
@@ -253,6 +274,17 @@ function measureLine(line) {
         if (flexible) {
             line.totalFlex += flexible.getFlex();
             line.totalBasis += flexible.getBasis(line.percentBase);
+            if (Number.isFinite(line.mainAvail)) {
+                // Down a column, a flex child keeps its content's height (CSS `min-height: auto`): squeezed
+                // below it, it would draw over the sibling that follows.
+                const content = axis.mainHorizontal
+                    ? 0
+                    : axis.mainOf(child.measure(axis.measureConstraints(line.crossAvail, Infinity), line.ctx));
+                const floor = Math.max(0, child.minIntrinsicMain(axis.mainHorizontal, line.ctx), content);
+                line.flexFloor.set(child, floor);
+                // A max below the floor loses, as in CSS.
+                line.flexCeil.set(child, Math.max(floor, child.maxExtent(axis.mainHorizontal)));
+            }
             continue;
         }
         const size = measureInto(line, child, axis.measureConstraints(line.crossAvail, mainCapFor(line, child)));
@@ -263,12 +295,17 @@ function measureLine(line) {
 /**
  * Step 2: the line overflows and some children said they would give space back. CSS weights a shrinker's
  * share by `shrink x its own size`, so a big item yields more than a small one - for a flex child that
- * size is its basis, so a Spacer (basis 0) gives nothing. A document that never overflows never gets past
- * the first test.
+ * size is its basis, so a Spacer (basis 0) gives nothing. A flex child counts at least at its floor, so
+ * its siblings make room for what it holds. A document that never overflows never gets past the first
+ * test.
  */
 function shrinkLine(line) {
     const { axis } = line;
-    const overflow = line.fixedMain + line.totalBasis + line.totalGap - line.mainAvail;
+    let reserved = 0;
+    for (const [child, floor] of line.flexFloor) {
+        reserved += Math.max(0, floor - flexibleOf(child).getBasis(line.percentBase));
+    }
+    const overflow = line.fixedMain + line.totalBasis + reserved + line.totalGap - line.mainAvail;
     if (!Number.isFinite(line.mainAvail) || !(overflow > 0))
         return;
     const shrinkers = line.children.filter((c) => {
@@ -382,30 +419,100 @@ function mainSpacing(main, gap, count, mainAvail, leftover, weight) {
     return { leading: 0, between: gap };
 }
 /**
- * Step 5: measure the flex children at their share, so a tall or wrapping flex cell counts toward the
- * line's cross extent before anything is placed.
+ * Step 5: each flex child's main extent - its basis plus its share of the leftover, held between its
+ * floor and its ceiling. CSS resolves that iteratively (Flexbox 9.7): clamp everyone, and by the sign of
+ * the total change freeze the ones held at their floor (it grew) or at their ceiling (it shrank); the
+ * rest share what is left again. Nothing clamped: the plain share.
  */
-function measureFlex(line, weight, remaining) {
+function shareFlex(line, weight, remaining) {
+    const items = [];
     for (const child of line.children) {
         const flexible = flexibleOf(child);
-        if (!flexible)
-            continue;
+        if (flexible)
+            items.push([child, flexible]);
+    }
+    // `totalFlex` is 0 when every flex child asked for `flex: 0` (a pure `flexBasis` slot). The share is
+    // then 0/0 - a NaN that becomes the offset of every later sibling. Such a child takes its basis.
+    const extentAt = (child, flexible, part, of) => basisOf(line, child, flexible) + (of > 0 ? (flexible.getFlex() / of) * part : 0);
+    for (const [child, flexible] of items) {
+        line.flexExtent.set(child, extentAt(child, flexible, remaining, weight));
+    }
+    // The flex children's part of the leftover; a Spacer stack's share (`shareLeftover`) stays its own.
+    let pot = weight > 0 ? (remaining * line.totalFlex) / weight : 0;
+    let active = items;
+    for (;;) {
+        let change = 0;
+        const clamped = new Map();
+        for (const [child] of active) {
+            const extent = line.flexExtent.get(child);
+            const held = Math.min(Math.max(extent, line.flexFloor.get(child) ?? 0), line.flexCeil.get(child) ?? Infinity);
+            if (held !== extent)
+                clamped.set(child, held);
+            change += held - extent;
+        }
+        if (clamped.size === 0)
+            return;
+        const froze = active.filter(([child]) => {
+            const held = clamped.get(child);
+            return (held !== undefined &&
+                (change > 0
+                    ? held > line.flexExtent.get(child)
+                    : change < 0
+                        ? held < line.flexExtent.get(child)
+                        : true));
+        });
+        for (const [child, flexible] of froze) {
+            const held = clamped.get(child);
+            pot -= held - basisOf(line, child, flexible);
+            line.flexExtent.set(child, held);
+        }
+        active = active.filter((item) => !froze.includes(item));
+        const activeFlex = active.reduce((n, [, flexible]) => n + flexible.getFlex(), 0);
+        for (const [child, flexible] of active) {
+            line.flexExtent.set(child, extentAt(child, flexible, Math.max(0, pot), activeFlex));
+        }
+    }
+}
+/**
+ * Step 6: measure the flex children at their extent, so a tall or wrapping flex cell counts toward the
+ * line's cross extent before anything is placed.
+ */
+function measureFlex(line, cross) {
+    for (const [child, mainExtent] of line.flexExtent) {
         // A pure `flexBasis` slot (`flex: 0`) has no share but still has a size across the line.
-        const share = weight > 0 ? (flexible.getFlex() / weight) * remaining : 0;
-        const mainExtent = basisOf(line, child, flexible) + share;
-        const size = measureInto(line, child, line.axis.flexConstraints(mainExtent, line.crossAvail));
+        const crossMax = (alignSelfOf(child) ?? cross) === "stretch"
+            ? line.crossAvail
+            : ownCross(line, child, mainExtent);
+        const size = measureInto(line, child, line.axis.flexConstraints(mainExtent, crossMax));
         line.crossUsed = Math.max(line.crossUsed, line.axis.crossOf(size));
     }
 }
 /**
- * Step 6: place each child at the running main position, offset across by its alignment. This is the
+ * Across the line, a flex child that is not stretched takes what its content needs and is aligned like
+ * any other item. Its content is measured against the line's cross bound - an unbounded one would stop a
+ * text in a Column from wrapping.
+ */
+function ownCross(line, child, mainExtent) {
+    const flexible = flexibleOf(child);
+    const content = flexible.layoutChildren()[0];
+    if (!content)
+        return 0;
+    // In the context it is laid out in: a wrapper on the way to the `Expanded` may hand one down.
+    let ctx = line.ctx;
+    for (let el = child; el !== flexible; el = el.proxied())
+        ctx = el.proxiedContext(ctx);
+    const constraints = line.axis.flexConstraints(mainExtent, line.crossAvail);
+    return line.axis.crossOf(content.measure(constraints, ctx));
+}
+/**
+ * Step 7: place each child at the running main position, offset across by its alignment. This is the
  * ONE layout a child gets. Measuring, it only sizes - and reuses a size already measured under the same
  * constraints, or the measuring itself would double at every level.
  *
  * `stretch` caps a child's cross to `crossExtent`, not `crossAvail`, so siblings end up equal across the
  * axis. A child may override the container with its own `alignSelf` (CSS).
  */
-function placeLine(line, cross, crossExtent, crossOrigin, spacing, weight, remaining, mode) {
+function placeLine(line, cross, crossExtent, crossOrigin, spacing, mode) {
     const { axis, ctx } = line;
     const place = (child, constraints, offset) => {
         if (mode === "layout")
@@ -421,21 +528,22 @@ function placeLine(line, cross, crossExtent, crossOrigin, spacing, weight, remai
     line.children.forEach((child, index) => {
         let mainExtent;
         const flexible = flexibleOf(child);
+        // A region-sized child (a Flow) takes the height the Row was given, never one its siblings make.
+        const regionSized = axis.mainHorizontal && child.needsRegion();
         if (flexible) {
-            // `totalFlex` is 0 when every flex child asked for `flex: 0` (a pure `flexBasis` slot). The share
-            // is then 0/0 - a NaN that becomes the offset of every later sibling. Such a child takes its basis.
-            const share = weight > 0 ? (flexible.getFlex() / weight) * remaining : 0;
-            mainExtent = basisOf(line, child, flexible) + share;
-            // A flex child fills the MAIN axis and its cross size is only known after layout, so `alignSelf`
-            // is a no-op here - and that has to hold for the CROSS CONSTRAINT too, or an `alignSelf: "start"`
-            // flex child would get an unbounded cross axis on a shrink-wrapping line.
-            const size = place(child, axis.flexConstraints(mainExtent, cross === "stretch" ? crossExtent : line.crossAvail), axis.offsetAt(mainPos, crossOrigin));
+            mainExtent = line.flexExtent.get(child);
+            const align = alignSelfOf(child) ?? cross;
+            // Stretched, it is capped at the line; otherwise it may take what the line offers, and is
+            // aligned by what it takes.
+            const cap = align === "stretch" && !regionSized ? crossExtent : line.crossAvail;
+            const own = align === "stretch" || regionSized ? cap : ownCross(line, child, mainExtent);
+            const size = place(child, axis.flexConstraints(mainExtent, cap), axis.offsetAt(mainPos, crossOrigin + crossOffset(align, crossExtent, own)));
             placedCross = Math.max(placedCross, axis.crossOf(size));
         }
         else {
             const align = alignSelfOf(child) ?? cross;
             const childCross = axis.crossOf(line.sizes.get(child));
-            const size = place(child, axis.measureConstraints(align === "stretch" ? crossExtent : line.crossAvail, mainCapFor(line, child)), axis.offsetAt(mainPos, crossOrigin + crossOffset(align, crossExtent, childCross)));
+            const size = place(child, axis.measureConstraints(align === "stretch" && !regionSized ? crossExtent : line.crossAvail, mainCapFor(line, child)), axis.offsetAt(mainPos, crossOrigin + crossOffset(align, crossExtent, childCross)));
             mainExtent = axis.mainOf(size);
             placedCross = Math.max(placedCross, axis.crossOf(size));
         }

package/dist/utils/image-helper.d.ts

@@ -3,11 +3,56 @@ declare global {
         getUint24(byteOffset: number, littleEndian?: boolean): number;
     }
 }
-interface ImageDimensions {
+/** Dots per inch, per axis. */
+export interface Resolution {
+    x: number;
+    y: number;
+}
+export interface ImageDimensions {
+    /** In pixels - what the XObject declares. */
+    width: number;
+    height: number;
+    /** The resolution the file declares; absent when it declares none. */
+    dpi?: Resolution;
+    /** How the stored pixels turn upright (EXIF, a JPEG only); absent when they already are. */
+    orientation?: Orientation;
+}
+/**
+ * EXIF orientation: 2 mirrored, 3 turned half, 4 flipped, 5 transposed, 6 turned a quarter clockwise,
+ * 7 transversed, 8 turned a quarter counterclockwise. 5-8 swap width and height.
+ */
+export type Orientation = 2 | 3 | 4 | 5 | 6 | 7 | 8;
+/**
+ * The matrix that turns the image's unit square upright, inside it - PDF's image space, y up, the first
+ * stored row at the top. Applied before the placement scales it, so the box stays the box.
+ */
+export declare const ORIENTATION_MATRIX: Record<Orientation, readonly number[]>;
+/** The resolution of a file that declares none: CSS's reference pixel, 1/96 inch. */
+export declare const DEFAULT_DPI = 96;
+/**
+ * An image's own size in points, upright: its pixels at the resolution the file declares, else 96 dpi,
+ * turned by its orientation.
+ */
+export declare function naturalSize(dims: ImageDimensions): {
     width: number;
     height: number;
+};
+/** Thrown for a JPEG we cannot embed as it is. Says what it is and what to do. */
+export declare class JpegFormatError extends Error {
+    constructor(message: string);
+}
+/** The colors an image's samples are in. */
+export type ImageColorSpace = "gray" | "rgb" | "cmyk";
+/** What an image's samples mean: their color space, and whether they are stored inverted. */
+export interface ImageColor {
+    space: ImageColorSpace;
+    /** Photoshop stores CMYK inverted (an Adobe `APP14` segment). */
+    inverted?: boolean;
 }
-export declare function getImageDimensions(buffer: Uint8Array): Promise<ImageDimensions>;
+/** The color of a JPEG as it is embedded (`DCTDecode`): the space it was saved in. */
+export declare function jpegColor(bytes: Uint8Array): ImageColor;
+/** Read from the header alone, synchronously - layout can ask it. */
+export declare function readImageDimensions(buffer: Uint8Array): ImageDimensions;
 /**
  * Converts the given image to grayscale and returns its binary data.
  * @param imagePath Path to the input image file.
@@ -26,19 +71,22 @@ export declare function decodePngToRgbFlate(pngBuffer: Uint8Array): Promise<{
     height: number;
 }>;
 export declare function convertImageToGrayscaleBuffer(imagePath: string): Promise<Uint8Array>;
+/** The drawn size of an image in its box, and where it sits there. */
 export interface FitResult {
     width: number;
     height: number;
     offsetX: number;
     offsetY: number;
 }
-export declare function applyContainFit(imageWidth: number, imageHeight: number, containerWidth: number, containerHeight: number): FitResult;
-export declare function applyCoverFit(imageWidth: number, imageHeight: number, containerWidth: number, containerHeight: number): FitResult;
+/** Where an image smaller or larger than its box sits in it, per axis: 0 = start, 0.5 = center, 1 = end. */
+export interface FitAlign {
+    x: number;
+    y: number;
+}
+/** Scaled to fit inside the box, whole image visible. */
+export declare function applyContainFit(imageWidth: number, imageHeight: number, containerWidth: number, containerHeight: number, align?: FitAlign): FitResult;
+/** Scaled to cover the box, the overhang cut off. */
+export declare function applyCoverFit(imageWidth: number, imageHeight: number, containerWidth: number, containerHeight: number, align?: FitAlign): FitResult;
 export declare function applyFillFit(containerWidth: number, containerHeight: number): FitResult;
-export declare function applyFitNone(imageWidth: number, imageHeight: number, containerWidth: number, containerHeight: number): {
-    width: number;
-    height: number;
-    offsetX: number;
-    offsetY: number;
-};
-export {};
+/** At its own size (`naturalSize`), the overhang cut off. */
+export declare function applyFitNone(imageWidth: number, imageHeight: number, containerWidth: number, containerHeight: number, align?: FitAlign): FitResult;