@jasy/pdf 1.0.0-alpha.8 → 1.0.0-alpha.9

package/README.md

@@ -140,7 +140,7 @@ verify all of it:
 - **PDF/A-3, matched not approximated.** The conformance graph is hand-built and **passes veraPDF**, the
   official ISO 19005 validator.
 - **Byte-exact round-trips.** Generate and parse are inverses: `generate → parse → regenerate` reproduces
-  the identical XML. 307 tests hold the line.
+  the identical XML. Over 900 tests hold the line across the workspace.
 - **Schematron, local.** The official EN-16931 + XRechnung rules run via saxon-js (the real XSLT, in pure
   JS) - no Java, no upload.
 
@@ -158,8 +158,9 @@ verify all of it:
 
 ## Why you can trust it
 
-- **307 tests, green.** The generator and the parser are **byte-exact inverses**:
-  `generate → parse → regenerate` reproduces the identical XML. Nothing is silently lost.
+- **Over 900 tests, green** across the workspace (850 in the engine alone). The generator and the parser
+  are **byte-exact inverses**: `generate → parse → regenerate` reproduces the identical XML. Nothing is
+  silently lost.
 - **The same rules the authorities use** - the official KoSIT EN-16931 + XRechnung Schematron, and the
   official **veraPDF** for the full ISO 19005 (PDF/A) check.
 - **Proven on real third-party invoices**, not only our own.

package/dist/api/content.d.ts

@@ -2,7 +2,7 @@ import { ImageElement, CustomImage } from "../elements/image-element.js";
 import { PDFElement } from "../elements/pdf-element.js";
 import { ColorInput } from "./color.js";
 import { Insets } from "./insets.js";
-import { SizeInput } from "./dimension.js";
+import { BoundsInput, SizeInput, RadiusInput } from "./dimension.js";
 /** A horizontal rule (locked §4). */
 export interface DividerOptions {
     /** Line color (default a light gray). */
@@ -22,15 +22,16 @@ export declare function Divider(opts?: DividerOptions): PDFElement;
 export type ImageSource = string | Uint8Array | CustomImage;
 /** How the image fills its box (locked §4). Mirrors CSS `object-fit`. */
 export type ImageFit = "none" | "contain" | "cover" | "fill";
-export interface ImageOptions {
+export interface ImageOptions extends BoundsInput {
     /** Size on each axis: points (fixed) or a percentage string like `"50%"` (a fraction of the offered
      *  space). Pin exactly ONE axis and the other follows the image's aspect ratio (CSS `height: auto`). */
     width?: SizeInput;
     height?: SizeInput;
-    /** Fit within the box (default `none`; `fill` when exactly one axis is pinned so it scales to fit). */
+    /** Fit within the box. Default `none`, except where the box was DERIVED rather than given outright -
+     *  exactly one axis pinned, or an `aspectRatio` - which defaults to `fill` so the image scales into it. */
     fit?: ImageFit;
     /** Corner radius in points (rounds the image box). */
-    radius?: number;
+    radius?: RadiusInput;
     /** Alternate text for accessibility (tagged PDF): describes the image for screen readers. With `alt`
      *  the image is a `Figure`; without it (and when rendered `accessible`) it counts as decoration. */
     alt?: string;

package/dist/api/content.js

@@ -3,7 +3,7 @@ import { PaddingElement } from "../elements/layout/padding-element.js";
 import { ImageElement, CustomLocalImage, CustomBytesImage, BoxFit, } from "../elements/image-element.js";
 import { toColor } from "./color.js";
 import { toEdges } from "./insets.js";
-import { toDimension } from "./dimension.js";
+import { toBounds, toDimension, toRadius, } from "./dimension.js";
 const DEFAULT_DIVIDER_COLOR = "lightgray";
 const DEFAULT_DIVIDER_MARGIN = { y: 6 };
 /**
@@ -38,10 +38,12 @@ const FIT = {
 export function Image(src, opts = {}) {
     const w = opts.width !== undefined ? toDimension(opts.width) : undefined;
     const h = opts.height !== undefined ? toDimension(opts.height) : undefined;
-    // Exactly one axis pinned -> the other is derived from the aspect ratio, so scale the image to the
-    // resulting box (fit: fill). Both or neither pinned keeps the default fit (none).
-    const autoScale = (opts.width !== undefined) !== (opts.height !== undefined);
-    const fit = opts.fit ? FIT[opts.fit] : autoScale ? BoxFit.fill : undefined;
+    // ANY explicit size scales the image into the box (fit: fill), which is what `<img width height>`
+    // does in HTML and what react-pdf does. Two pinned axes used to keep `none` - drawing the image at
+    // its pixel size regardless - so a logo asked for at 48x48 spanned a third of the page.
+    // An image with NO size given still draws at its intrinsic size, as an unsized `<img>` does.
+    const sized = opts.width !== undefined || opts.height !== undefined || opts.aspectRatio !== undefined;
+    const fit = opts.fit ? FIT[opts.fit] : sized ? BoxFit.fill : undefined;
     return new ImageElement({
         image: typeof src === "string"
             ? new CustomLocalImage(src)
@@ -52,8 +54,12 @@ export function Image(src, opts = {}) {
         height: h?.points,
         widthFactor: w?.factor,
         heightFactor: h?.factor,
+        ...toBounds(opts),
         fit,
-        radius: opts.radius,
+        radius: opts.radius !== undefined ? toRadius(opts.radius) : undefined,
         alt: opts.alt,
-    });
+    })
+        .withAlignSelf(opts.alignSelf)
+        .withOrder(opts.order)
+        .withFlexShrink(opts.flexShrink);
 }

package/dist/api/dimension.d.ts

@@ -1,3 +1,5 @@
+import type { Radii } from "../ir/display-list.js";
+import type { CrossAlign } from "../layout/alignment.js";
 /**
  * Size input for a Box's `width` / `height` (relative sizing). Either a number of PDF points (a
  * fixed size) or a percentage string like `"50%"` - a fraction of the space the parent offers on
@@ -18,3 +20,57 @@ export interface Dimension {
  * boundary so `resolveExtent` and the layout never see a negative size.
  */
 export declare function toDimension(value: SizeInput): Dimension;
+/** The bound and ratio options every sized factory accepts, in the public `SizeInput` form. */
+export interface BoundsInput {
+    /**
+     * This element's own cross-axis alignment inside its Column / Row (CSS `align-self`), overriding the
+     * container's `align`. On a `Spacer` / `Expanded` it is a no-op - a flex child fills the main axis and
+     * has no natural cross size to align.
+     */
+    alignSelf?: CrossAlign;
+    /**
+     * Where this child sits among its siblings (CSS `order`), lowest first, source order deciding ties.
+     * It moves the child in the LAYOUT only - the element tree is untouched, so a tagged PDF still
+     * exposes the source reading order. Default 0.
+     */
+    order?: number;
+    /**
+     * How willingly this child gives up main-axis space when the line overflows (CSS `flex-shrink`),
+     * weighted by its own size. **Default 0, deliberately unlike CSS's 1** - shrinking changes what a
+     * document looks like, so it is opted into per child rather than applied to everything at once.
+     */
+    flexShrink?: number;
+    minWidth?: SizeInput;
+    maxWidth?: SizeInput;
+    minHeight?: SizeInput;
+    maxHeight?: SizeInput;
+    /**
+     * width / height (CSS `aspect-ratio`). Fills in whichever axis you leave open, and sizes the box
+     * from the offered width when you leave both open. An explicit `min`/`max` still wins over it.
+     */
+    aspectRatio?: number;
+}
+/** Split `BoundsInput` into the points-and-factors form the elements take. */
+export declare function toBounds(o: BoundsInput): {
+    minWidth: number | undefined;
+    maxWidth: number | undefined;
+    minHeight: number | undefined;
+    maxHeight: number | undefined;
+    minWidthFactor: number | undefined;
+    maxWidthFactor: number | undefined;
+    minHeightFactor: number | undefined;
+    maxHeightFactor: number | undefined;
+    aspectRatio: number | undefined;
+};
+/**
+ * Corner radius input. A single number rounds all four corners; the object names them; the tuple is
+ * CSS order - `[topLeft, topRight, bottomRight, bottomLeft]`, clockwise from the top left.
+ */
+export type RadiusInput = number | {
+    topLeft?: number;
+    topRight?: number;
+    bottomRight?: number;
+    bottomLeft?: number;
+} | [number, number, number, number];
+/** Normalizes a `RadiusInput` to the engine's short corner names. */
+export declare function toRadius(r: RadiusInput): number | Radii;

package/dist/api/dimension.js

@@ -14,3 +14,30 @@ export function toDimension(value) {
         return { factor: parseFloat(m[1]) / 100 };
     throw new Error(`Invalid size "${value}": use a number of points or a percentage like "50%".`);
 }
+/** Split `BoundsInput` into the points-and-factors form the elements take. */
+export function toBounds(o) {
+    const d = (v) => (v !== undefined ? toDimension(v) : undefined);
+    const [minW, maxW, minH, maxH] = [d(o.minWidth), d(o.maxWidth), d(o.minHeight), d(o.maxHeight)];
+    if (o.aspectRatio !== undefined && !(o.aspectRatio > 0)) {
+        throw new Error(`Invalid aspectRatio ${o.aspectRatio}: it is width / height and must be above 0.`);
+    }
+    return {
+        minWidth: minW?.points,
+        maxWidth: maxW?.points,
+        minHeight: minH?.points,
+        maxHeight: maxH?.points,
+        minWidthFactor: minW?.factor,
+        maxWidthFactor: maxW?.factor,
+        minHeightFactor: minH?.factor,
+        maxHeightFactor: maxH?.factor,
+        aspectRatio: o.aspectRatio,
+    };
+}
+/** Normalizes a `RadiusInput` to the engine's short corner names. */
+export function toRadius(r) {
+    if (typeof r === "number")
+        return r;
+    if (Array.isArray(r))
+        return { tl: r[0], tr: r[1], br: r[2], bl: r[3] };
+    return { tl: r.topLeft, tr: r.topRight, br: r.bottomRight, bl: r.bottomLeft };
+}

package/dist/api/font-url.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Loading a font over the network for `doc.addFontFromUrl(...)`.
+ *
+ * `addFont` resolves its source AT REGISTRATION - a path is read there and then - and this keeps the
+ * same contract, differing only in being async. So the failure lands where you asked for the font,
+ * not somewhere inside a later render.
+ *
+ * `fetch` is used directly: it is in every browser and in Node since 18, so this needs no platform
+ * port, unlike the filesystem read beside it.
+ */
+/** One font file by URL, or a styled family of them. Mirrors `FontSource`, with strings meaning URLs. */
+export type UrlFontSource = string | {
+    normal: string;
+    bold?: string;
+    italic?: string;
+    boldItalic?: string;
+};
+/** Thrown when a font could not be fetched or is not one we can parse. Always says which URL. */
+export declare class FontUrlError extends Error {
+    constructor(message: string);
+}
+/** Fetch a whole `UrlFontSource`, in parallel for a family. */
+export declare function loadFontFromUrl(source: UrlFontSource): Promise<Uint8Array | {
+    normal: Uint8Array;
+    bold?: Uint8Array;
+    italic?: Uint8Array;
+    boldItalic?: Uint8Array;
+}>;

package/dist/api/font-url.js

@@ -0,0 +1,134 @@
+/**
+ * Loading a font over the network for `doc.addFontFromUrl(...)`.
+ *
+ * `addFont` resolves its source AT REGISTRATION - a path is read there and then - and this keeps the
+ * same contract, differing only in being async. So the failure lands where you asked for the font,
+ * not somewhere inside a later render.
+ *
+ * `fetch` is used directly: it is in every browser and in Node since 18, so this needs no platform
+ * port, unlike the filesystem read beside it.
+ */
+/** Thrown when a font could not be fetched or is not one we can parse. Always says which URL. */
+export class FontUrlError extends Error {
+    constructor(message) {
+        super(`@jasy/pdf: ${message}`);
+    }
+}
+/**
+ * What the first four bytes of an sfnt file say it is. Checked here because `TTFParser` does not look
+ * at them: it goes straight for the table directory, so an HTML error page or a WOFF would fail deep
+ * inside with `missing required table "head"` instead of saying what the file actually is.
+ */
+function describeSignature(bytes) {
+    const tag = String.fromCharCode(...bytes.subarray(0, 4));
+    const v = (bytes[0] << 24) | (bytes[1] << 16) | (bytes[2] << 8) | bytes[3];
+    if (v === 0x00010000 || tag === "true")
+        return { ok: true, what: "TrueType" };
+    if (tag === "OTTO")
+        return { ok: false, what: "an OpenType/CFF font, which jasy does not parse yet" };
+    if (tag === "wOFF")
+        return { ok: true, what: "WOFF" };
+    if (tag === "wOF2")
+        return { ok: false, what: "a WOFF2 font, which jasy does not parse yet" };
+    if (tag === "ttcf")
+        return { ok: false, what: "a TrueType Collection, which jasy does not parse yet" };
+    if (tag.startsWith("<") || tag === "%PDF")
+        return { ok: false, what: "not a font at all" };
+    return { ok: false, what: "not a font we recognise" };
+}
+/** How long one font may take to arrive before we give up. A hung server must not hang a render. */
+const TIMEOUT_MS = 15000;
+/**
+ * How large a font file may be. Generous on purpose - a full CJK face is tens of megabytes and is a
+ * legitimate thing to embed - but not unbounded: a URL pointing at the wrong file (a video, a disk
+ * image) would otherwise be read into memory in full before anyone notices it is not a font.
+ */
+const MAX_BYTES = 32 * 1024 * 1024;
+/** Read the body with a running ceiling, so an oversized response is dropped WHILE it arrives. */
+async function readBounded(response, url) {
+    // `Content-Length` is the cheap early exit; a server may omit or misstate it, so it is a hint only
+    // and the real ceiling is enforced below while reading.
+    const declared = Number(response.headers?.get?.("content-length") ?? NaN);
+    if (Number.isFinite(declared) && declared > MAX_BYTES) {
+        throw new FontUrlError(`the font at ${url} is ${declared} bytes; the limit is ${MAX_BYTES}`);
+    }
+    const body = response.body;
+    if (!body?.getReader) {
+        // No streaming body (an older runtime, or a stubbed response): fall back to reading it whole and
+        // checking afterwards. Weaker, but never worse than not checking at all.
+        const whole = new Uint8Array(await response.arrayBuffer());
+        if (whole.length > MAX_BYTES) {
+            throw new FontUrlError(`the font at ${url} is larger than the ${MAX_BYTES} byte limit`);
+        }
+        return whole;
+    }
+    const reader = body.getReader();
+    const chunks = [];
+    let total = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        total += value.length;
+        if (total > MAX_BYTES) {
+            await reader.cancel();
+            throw new FontUrlError(`the font at ${url} is larger than the ${MAX_BYTES} byte limit`);
+        }
+        chunks.push(value);
+    }
+    if (chunks.length === 1)
+        return chunks[0];
+    const out = new Uint8Array(total);
+    let at = 0;
+    for (const c of chunks) {
+        out.set(c, at);
+        at += c.length;
+    }
+    return out;
+}
+/** Fetch one font file and hand back its bytes, refusing anything we could not embed. */
+async function fetchFont(url) {
+    let response;
+    try {
+        response = await fetch(url, { signal: AbortSignal.timeout(TIMEOUT_MS) });
+    }
+    catch (e) {
+        const why = e?.name === "TimeoutError" || e?.name === "AbortError"
+            ? `it did not respond within ${TIMEOUT_MS} ms`
+            : String(e?.message ?? e);
+        throw new FontUrlError(`could not fetch the font at ${url}: ${why}`);
+    }
+    if (!response.ok) {
+        throw new FontUrlError(`the font at ${url} could not be fetched: HTTP ${response.status}`);
+    }
+    // Everything past here still talks to the network, so a failure mid-body must not escape as a raw
+    // TypeError - a caller catching FontUrlError would miss it.
+    let bytes;
+    try {
+        bytes = await readBounded(response, url);
+    }
+    catch (e) {
+        if (e instanceof FontUrlError)
+            throw e;
+        throw new FontUrlError(`the font at ${url} could not be read: ${String(e?.message ?? e)}`);
+    }
+    if (bytes.length < 4) {
+        throw new FontUrlError(`the font at ${url} is empty`);
+    }
+    const { ok, what } = describeSignature(bytes);
+    if (!ok) {
+        throw new FontUrlError(`the file at ${url} is ${what}. jasy embeds TrueType-flavoured fonts (.ttf and .woff)`);
+    }
+    return bytes;
+}
+/** Fetch a whole `UrlFontSource`, in parallel for a family. */
+export async function loadFontFromUrl(source) {
+    if (typeof source === "string")
+        return fetchFont(source);
+    const styles = ["normal", "bold", "italic", "boldItalic"];
+    const wanted = styles.filter((s) => source[s] !== undefined);
+    const loaded = await Promise.all(wanted.map((s) => fetchFont(source[s])));
+    const family = { normal: new Uint8Array() };
+    wanted.forEach((s, i) => (family[s] = loaded[i]));
+    return family;
+}

package/dist/api/gradient.d.ts

@@ -0,0 +1,53 @@
+import { type ColorInput } from "./color.js";
+import type { Gradient } from "../ir/display-list.js";
+/**
+ * Gradients for a box background.
+ *
+ * The public form is BOX-RELATIVE - an angle and some stops - because that is what an author knows
+ * when writing the document. The engine's `Gradient` wants absolute page coordinates, so the renderer
+ * resolves one against the box it is painting; see `resolveGradient`.
+ */
+/** A stop as written: a colour, optionally pinned to a position 0..1 along the axis. */
+export type StopInput = ColorInput | {
+    color: ColorInput;
+    at: number;
+};
+export interface LinearGradientInput {
+    kind: "linear";
+    /** Direction in degrees, CSS convention: 0 = to the top, 90 = to the right (default 180, downwards). */
+    angle: number;
+    stops: StopInput[];
+}
+export interface RadialGradientInput {
+    kind: "radial";
+    /** Centre as a fraction of the box, `[0.5, 0.5]` being the middle (the default). */
+    center: [number, number];
+    /** Outer radius as a fraction of the box's larger side (default 0.5, i.e. it touches the edges). */
+    radius: number;
+    stops: StopInput[];
+}
+export type GradientInput = LinearGradientInput | RadialGradientInput;
+export declare const isGradientInput: (v: unknown) => v is GradientInput;
+/**
+ * A linear gradient. `linearGradient("#fff", "#000")` runs top to bottom; pass `{ angle }` for any
+ * other direction, and `{ color, at }` for a stop that is not evenly spaced.
+ */
+export declare function linearGradient(...args: [...StopInput[]] | [{
+    angle?: number;
+    stops: StopInput[];
+}]): LinearGradientInput;
+/** A radial gradient, centred by default and reaching the edges. */
+export declare function radialGradient(...args: [...StopInput[]] | [{
+    center?: [number, number];
+    radius?: number;
+    stops: StopInput[];
+}]): RadialGradientInput;
+/**
+ * Resolve a box-relative gradient against the box it paints, into the absolute page coordinates the
+ * IR wants. Called by the renderer, which is the first place the box's geometry is known.
+ *
+ * The angle follows CSS: 0 points to the top and it turns clockwise, so 90 goes to the right. The
+ * axis runs through the box centre and is scaled so it spans the box on that diagonal - which is why
+ * a 45-degree gradient reaches the corners rather than stopping short of them.
+ */
+export declare function resolveGradient(g: GradientInput, x: number, y: number, width: number, height: number): Gradient;

package/dist/api/gradient.js

@@ -0,0 +1,97 @@
+import { toColor } from "./color.js";
+export const isGradientInput = (v) => typeof v === "object" && v !== null && "kind" in v && "stops" in v;
+/**
+ * A linear gradient. `linearGradient("#fff", "#000")` runs top to bottom; pass `{ angle }` for any
+ * other direction, and `{ color, at }` for a stop that is not evenly spaced.
+ */
+export function linearGradient(...args) {
+    const first = args[0];
+    if (args.length === 1 && typeof first === "object" && first !== null && "stops" in first) {
+        return { kind: "linear", angle: first.angle ?? 180, stops: first.stops };
+    }
+    return { kind: "linear", angle: 180, stops: args };
+}
+/** A radial gradient, centred by default and reaching the edges. */
+export function radialGradient(...args) {
+    const first = args[0];
+    if (args.length === 1 && typeof first === "object" && first !== null && "stops" in first) {
+        return {
+            kind: "radial",
+            center: first.center ?? [0.5, 0.5],
+            radius: first.radius ?? 0.5,
+            stops: first.stops,
+        };
+    }
+    return { kind: "radial", center: [0.5, 0.5], radius: 0.5, stops: args };
+}
+/**
+ * Spread the stops that carry no `at` evenly, first to last, the way CSS does - and check the pinned
+ * ones, because they end up in a PDF stitching function's `/Bounds`, which the format requires to be
+ * strictly increasing inside the domain. A bad offset there is not a wrong-looking gradient, it is a
+ * malformed file, so it is refused by name here rather than emitted.
+ */
+function toStops(stops) {
+    if (stops.length < 2) {
+        throw new Error("A gradient needs at least two colour stops.");
+    }
+    const last = stops.length - 1;
+    const out = stops.map((s, i) => {
+        const pinned = typeof s === "object" && s !== null && "at" in s;
+        const at = pinned ? s.at : i / last;
+        if (!Number.isFinite(at) || at < 0 || at > 1) {
+            throw new Error(`Invalid gradient stop position ${at}: it must be a number between 0 and 1.`);
+        }
+        return {
+            offset: at,
+            color: toColor(pinned ? s.color : s),
+        };
+    });
+    for (let i = 1; i < out.length; i++) {
+        if (out[i].offset <= out[i - 1].offset) {
+            throw new Error(`Gradient stops must move forward: stop ${i} sits at ${out[i].offset}, which is not after ` +
+                `${out[i - 1].offset}. (Two stops at the SAME position would be a hard colour edge in CSS; ` +
+                `PDF cannot express that in one shading, so it is refused rather than drawn wrongly.)`);
+        }
+    }
+    // A pinned first or last stop would otherwise be IGNORED - the shading's domain is always 0..1 and
+    // only the INTERIOR offsets reach /Bounds. Carrying the edge colour outwards is what CSS does.
+    if (out[0].offset > 0)
+        out.unshift({ offset: 0, color: out[0].color });
+    if (out[out.length - 1].offset < 1)
+        out.push({ offset: 1, color: out[out.length - 1].color });
+    return out;
+}
+/**
+ * Resolve a box-relative gradient against the box it paints, into the absolute page coordinates the
+ * IR wants. Called by the renderer, which is the first place the box's geometry is known.
+ *
+ * The angle follows CSS: 0 points to the top and it turns clockwise, so 90 goes to the right. The
+ * axis runs through the box centre and is scaled so it spans the box on that diagonal - which is why
+ * a 45-degree gradient reaches the corners rather than stopping short of them.
+ */
+export function resolveGradient(g, x, y, width, height) {
+    const stops = toStops(g.stops);
+    if (g.kind === "radial") {
+        const cx = x + g.center[0] * width;
+        const cy = y + g.center[1] * height;
+        const r = g.radius * Math.max(width, height);
+        return { type: "radial", x0: cx, y0: cy, r0: 0, x1: cx, y1: cy, r1: r, stops, extend: "pad" };
+    }
+    const rad = ((g.angle % 360) * Math.PI) / 180;
+    // CSS angles: 0 = up, clockwise. The engine lays out top-left down, so "up" is -y here.
+    const dx = Math.sin(rad);
+    const dy = -Math.cos(rad);
+    // Half the box's extent along the axis, so the line covers the whole box for any angle.
+    const half = (Math.abs(dx) * width + Math.abs(dy) * height) / 2;
+    const cx = x + width / 2;
+    const cy = y + height / 2;
+    return {
+        type: "linear",
+        x0: cx - dx * half,
+        y0: cy - dy * half,
+        x1: cx + dx * half,
+        y1: cy + dy * half,
+        stops,
+        extend: "pad",
+    };
+}

package/dist/api/index.d.ts

@@ -1,5 +1,7 @@
 export * from "./color.js";
 export * from "./insets.js";
+export * from "./gradient.js";
+export * from "./font-url.js";
 export * from "./dimension.js";
 export * from "./text.js";
 export * from "./layout.js";

package/dist/api/index.js

@@ -3,6 +3,8 @@
 // core classes stay untouched and remain exported for power users.
 export * from "./color.js";
 export * from "./insets.js";
+export * from "./gradient.js";
+export * from "./font-url.js";
 export * from "./dimension.js";
 export * from "./text.js";
 export * from "./layout.js";

package/dist/api/insets.d.ts

@@ -1,16 +1,23 @@
+import { SizeInput } from "./dimension.js";
+import type { EdgeSpecs } from "../layout/insets.js";
 /**
- * Spacing input for padding / margin (locked design §3). Units are PDF points. Every form
- * normalizes to the engine's `[top, right, bottom, left]` via `toEdges`, so you can reach
+ * Spacing input for padding / margin (locked design §3). Points, or a percentage string like `"5%"`.
+ * Every form normalizes to the engine's `[top, right, bottom, left]` via `toEdges`, so you can reach
  * for whichever shape fits and never think about the engine order.
+ *
+ * **A percentage resolves against the available WIDTH - on all four sides, top and bottom included.**
+ * That is the CSS rule, and Yoga's, so react-pdf behaves the same. It reads as wrong the first time and
+ * is what makes `padding-bottom: 56.25%` a 16:9 box on the web. A percentage needs a bounded width; in
+ * an unbounded region it resolves to 0, the same no-op a percentage SIZE gives there.
  */
-export type Insets = number | {
-    x?: number;
-    y?: number;
+export type Insets = SizeInput | {
+    x?: SizeInput;
+    y?: SizeInput;
 } | {
-    top?: number;
-    right?: number;
-    bottom?: number;
-    left?: number;
-} | [number, number, number, number];
-/** Normalizes any `Insets` to the engine's `[top, right, bottom, left]`. */
-export declare function toEdges(i: Insets): [number, number, number, number];
+    top?: SizeInput;
+    right?: SizeInput;
+    bottom?: SizeInput;
+    left?: SizeInput;
+} | [SizeInput, SizeInput, SizeInput, SizeInput];
+/** Normalizes any `Insets` to the engine's `[top, right, bottom, left]`, percentages still unresolved. */
+export declare function toEdges(i: Insets): EdgeSpecs;

package/dist/api/insets.js

@@ -1,17 +1,28 @@
-/** Normalizes any `Insets` to the engine's `[top, right, bottom, left]`. */
+import { toDimension } from "./dimension.js";
+// A fixed side stays a plain NUMBER, so the output is unchanged for every input that was legal before
+// this file learned percentages - `toEdges` is publicly exported and did not need to break.
+const spec = (v) => {
+    if (v === undefined)
+        return 0;
+    const d = toDimension(v);
+    return d.points ?? { factor: d.factor };
+};
+/** Normalizes any `Insets` to the engine's `[top, right, bottom, left]`, percentages still unresolved. */
 export function toEdges(i) {
-    if (typeof i === "number")
-        return [i, i, i, i];
+    if (typeof i === "number" || typeof i === "string") {
+        const s = spec(i);
+        return [s, s, s, s];
+    }
     if (Array.isArray(i))
-        return i;
+        return [spec(i[0]), spec(i[1]), spec(i[2]), spec(i[3])];
     // Axis form ({x, y}) and per-side form ({top,...}) are both all-optional objects (TS
     // can't discriminate them), so read through one shape: an axis key present picks the
     // axis interpretation (an empty object is all-zero either way).
     const o = i;
     if (o.x !== undefined || o.y !== undefined) {
-        const x = o.x ?? 0;
-        const y = o.y ?? 0;
+        const x = spec(o.x);
+        const y = spec(o.y);
         return [y, x, y, x];
     }
-    return [o.top ?? 0, o.right ?? 0, o.bottom ?? 0, o.left ?? 0];
+    return [spec(o.top), spec(o.right), spec(o.bottom), spec(o.left)];
 }