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

package/README.md

@@ -10,7 +10,7 @@
 </p>
 
 <p align="center">
-  <code>npm i @jasy/zugferd</code> &nbsp;·&nbsp; <code>npx @jasy/cli</code> &nbsp;·&nbsp; MIT
+  <code>npm i @jasy/e-invoice</code> &nbsp;·&nbsp; <code>npx @jasy/cli</code> &nbsp;·&nbsp; MIT
 </p>
 
 ---
@@ -42,7 +42,7 @@ invoices validate: the amounts are correct **by construction**, so the single bi
 EN-16931 failures (the BR-CO total checks) simply cannot happen.
 
 ```ts
-import { renderZugferd } from "@jasy/zugferd";
+import { renderZugferd } from "@jasy/e-invoice";
 
 const { bytes, xml } = await renderZugferd({
   number: "RE-2026-001",
@@ -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.
 
@@ -148,18 +148,19 @@ verify all of it:
 
 ## Packages
 
-| Package                                             | What it is                                                                                     |
-| --------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
-| **[@jasy/zugferd](https://npmx.dev/@jasy/zugferd)** | ZUGFeRD / XRechnung: your data → PDF/A-3 + EN-16931 XML, with local validation. **The prize.** |
-| **[@jasy/cli](https://npmx.dev/@jasy/cli)**         | the `jasy` terminal: read · validate · export, headless **and** interactive                    |
-| **[@jasy/pdf](https://npmx.dev/@jasy/pdf)**         | the declarative, Flutter-style PDF layout engine that powers them                              |
+| Package                                                 | What it is                                                                                     |
+| ------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| **[@jasy/e-invoice](https://npmx.dev/@jasy/e-invoice)** | ZUGFeRD / XRechnung: your data → PDF/A-3 + EN-16931 XML, with local validation. **The prize.** |
+| **[@jasy/cli](https://npmx.dev/@jasy/cli)**             | the `jasy` terminal: read · validate · export, headless **and** interactive                    |
+| **[@jasy/pdf](https://npmx.dev/@jasy/pdf)**             | the declarative, Flutter-style PDF layout engine that powers them                              |
 
 ---
 
 ## 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/descriptor.js

@@ -4,6 +4,7 @@ import { Divider, Image } from "./content.js";
 import { Page, Document, DefaultTextStyle } from "./structure.js";
 import { PageNumber, PageCount } from "./page-builder.js";
 import { Table } from "./table.js";
+import { Checkbox, Dropdown, ListBox, PushButton, RadioGroup, SignatureField, TextField, } from "./forms.js";
 // Element children (Column/Row/Box/Page/…) → built recursively. Text/Paragraph children are
 // strings or `span` descriptors and become content instead.
 function elementChildren(children) {
@@ -112,7 +113,29 @@ const REGISTRY = {
     // cannot express. These two cover what the closure exists for.
     "page-number": (props) => PageNumber(props),
     "page-count": (props) => PageCount(props),
+    // Form fields. The three list-like ones take their choices as a SECOND argument in TypeScript; a
+    // template has no second argument, so here they arrive as an `options` prop. `choiceList` accepts both
+    // the short spelling and the explicit one, because an export value and its label are usually the same
+    // string and having to write it twice is noise.
+    "text-field": (props) => TextField(props),
+    checkbox: (props) => Checkbox(props),
+    "radio-group": (props) => RadioGroup(props, radioChoices(props.options)),
+    dropdown: (props) => Dropdown(props, choiceList(props.options)),
+    "list-box": (props) => ListBox(props, choiceList(props.options)),
+    "push-button": (props) => PushButton(props),
+    "signature-field": (props) => SignatureField(props),
 };
+/** `["S", "M"]` or `[{ value: "DE", label: "Germany" }]` - both mean the same thing to a choice field. */
+function choiceList(raw) {
+    if (!Array.isArray(raw)) {
+        throw new Error("jasy: a choice field needs an `options` array (strings or {value, label}).");
+    }
+    return raw;
+}
+/** A radio button always shows a label, so the short spelling means "label is the value". */
+function radioChoices(raw) {
+    return choiceList(raw).map((o) => typeof o === "string" ? { value: o, label: o } : { value: o.value, label: o.label ?? o.value });
+}
 /**
  * Registers a custom element type, so a binding (or a user-defined component) can introduce
  * its own tag that resolves to an engine element through this same seam. Overwrites an

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;
+}