@jasy/pdf 1.0.0-alpha.1 → 1.0.0-alpha.10

package/dist/api/forms.js

@@ -0,0 +1,189 @@
+import { TextFieldElement } from "../elements/forms/text-field-element.js";
+import { CheckboxElement } from "../elements/forms/checkbox-element.js";
+import { RadioElement } from "../elements/forms/radio-element.js";
+import { ChoiceElement } from "../elements/forms/choice-element.js";
+import { PushButtonElement } from "../elements/forms/push-button-element.js";
+import { SignatureFieldElement } from "../elements/forms/signature-element.js";
+import { toColor } from "./color.js";
+import { Column, Row } from "./layout.js";
+import { Text } from "./text.js";
+const toOptions = (opts) => opts.map((o) => (typeof o === "string" ? { value: o } : o));
+/**
+ * An interactive text field the reader of the PDF can type into (AcroForm /Tx). Place it like any element -
+ * in a `Column`, `Row`, `Box` or a table cell; it reserves its box and becomes a fillable widget.
+ *
+ * ```ts
+ * TextField({ name: "email", border: "gray", height: 22 })
+ * ```
+ */
+export function TextField(opts) {
+    return new TextFieldElement({
+        ...opts,
+        color: opts.color !== undefined ? toColor(opts.color) : undefined,
+        border: opts.border !== undefined ? toColor(opts.border) : undefined,
+        background: opts.background !== undefined ? toColor(opts.background) : undefined,
+    });
+}
+/**
+ * An interactive checkbox (AcroForm /Btn). It bakes its own checkmark appearance, so the tick shows in
+ * any viewer, in print, and under PDF/A - not only in ones that regenerate appearances.
+ *
+ * ```ts
+ * Row({ gap: 6, align: "center" }, [Checkbox({ name: "agree" }), Text("I agree")])
+ * ```
+ */
+export function Checkbox(opts) {
+    const box = new CheckboxElement({
+        ...opts,
+        color: opts.color !== undefined ? toColor(opts.color) : undefined,
+        border: opts.border !== undefined ? toColor(opts.border) : undefined,
+        background: opts.background !== undefined ? toColor(opts.background) : undefined,
+    });
+    // Without a label the box IS the element, so nothing wraps it and the output is unchanged.
+    if (opts.label === undefined)
+        return box;
+    return Row({ gap: opts.labelGap ?? 8, align: "center" }, [
+        box,
+        Text(opts.label, { size: opts.labelSize ?? 12, color: opts.labelColor }),
+    ]);
+}
+/** A single radio button. Use `RadioGroup` for the common labelled-list layout, or this for custom ones. */
+export function Radio(opts) {
+    return new RadioElement({
+        ...opts,
+        color: opts.color !== undefined ? toColor(opts.color) : undefined,
+        border: opts.border !== undefined ? toColor(opts.border) : undefined,
+        background: opts.background !== undefined ? toColor(opts.background) : undefined,
+    });
+}
+/**
+ * A labelled group of mutually-exclusive radio buttons. Sugar over `Radio` + `Text`: it lays each option
+ * out as a button-and-label row in a `Column`, and marks the one whose `value` matches the group `value`.
+ *
+ * ```ts
+ * RadioGroup({ name: "size", value: "m" }, [
+ *   { value: "s", label: "Small" },
+ *   { value: "m", label: "Medium" },
+ *   { value: "l", label: "Large" },
+ * ])
+ * ```
+ */
+export function RadioGroup(opts, options) {
+    const rows = options.map((o) => Row({ gap: 8, align: "center" }, [
+        Radio({
+            group: opts.name,
+            value: o.value,
+            selected: o.value === opts.value,
+            required: opts.required,
+            hidden: opts.hidden,
+            print: opts.print,
+            size: opts.size,
+            color: opts.color,
+            border: opts.border,
+            background: opts.background,
+        }),
+        Text(o.label, { size: opts.labelSize ?? 12, color: opts.labelColor }),
+    ]));
+    return Column({ gap: opts.gap ?? 8 }, rows);
+}
+const choiceStyle = (o) => ({
+    align: o.align,
+    tooltip: o.tooltip,
+    readOnly: o.readOnly,
+    required: o.required,
+    hidden: o.hidden,
+    print: o.print,
+    width: o.width,
+    height: o.height,
+    fontSize: o.fontSize,
+    color: o.color !== undefined ? toColor(o.color) : undefined,
+    border: o.border !== undefined ? toColor(o.border) : undefined,
+    background: o.background !== undefined ? toColor(o.background) : undefined,
+    borderWidth: o.borderWidth,
+});
+/**
+ * A dropdown / combo box (AcroForm /Ch). Options are plain strings or `{ value, label }`.
+ *
+ * ```ts
+ * Dropdown({ name: "country", value: "de" }, [{ value: "de", label: "Germany" }, "France"])
+ * ```
+ */
+export function Dropdown(opts, options) {
+    return new ChoiceElement({
+        name: opts.name,
+        options: toOptions(options),
+        combo: true,
+        editable: opts.editable,
+        value: opts.value,
+        ...choiceStyle(opts),
+    });
+}
+/** `Select` is an alias for `Dropdown`. */
+export const Select = Dropdown;
+/**
+ * A scrollable list box (AcroForm /Ch). Give it a `height` to show more rows. Set `multiSelect` for
+ * several selections at once.
+ */
+export function ListBox(opts, options) {
+    return new ChoiceElement({
+        name: opts.name,
+        options: toOptions(options),
+        combo: false,
+        multiSelect: opts.multiSelect,
+        value: opts.value,
+        values: opts.values,
+        ...choiceStyle(opts),
+    });
+}
+const toAction = (a) => {
+    if (a === undefined)
+        return undefined;
+    if (a === "reset")
+        return { kind: "reset" };
+    return "submit" in a ? { kind: "submit", url: a.submit } : { kind: "url", url: a.open };
+};
+/**
+ * A clickable push button (AcroForm /Btn). It holds no value - it fires an action. Its caption is baked
+ * into the appearance, so the button looks the same in every viewer and in print.
+ *
+ * ```ts
+ * PushButton({ name: "send", label: "Submit", action: { submit: "https://example.com/f" }, width: 120 })
+ * PushButton({ name: "clear", label: "Reset", action: "reset", width: 90 })
+ * ```
+ */
+export function PushButton(opts) {
+    return new PushButtonElement({
+        name: opts.name,
+        label: opts.label,
+        action: toAction(opts.action),
+        tooltip: opts.tooltip,
+        readOnly: opts.readOnly,
+        required: opts.required,
+        hidden: opts.hidden,
+        print: opts.print,
+        width: opts.width,
+        height: opts.height,
+        fontSize: opts.fontSize,
+        color: opts.color !== undefined ? toColor(opts.color) : undefined,
+        border: opts.border !== undefined ? toColor(opts.border) : undefined,
+        background: opts.background !== undefined ? toColor(opts.background) : undefined,
+        borderWidth: opts.borderWidth,
+    });
+}
+/**
+ * A signature field (AcroForm /Sig) - a placeholder someone can sign later in a PDF tool. jasy creates
+ * the field and draws its empty "sign here" box; it does not apply signatures itself (real signing needs
+ * a certificate and a byte-range digest).
+ *
+ * ```ts
+ * SignatureField({ name: "approver", label: "Signature", width: 240 })
+ * ```
+ */
+export function SignatureField(opts) {
+    return new SignatureFieldElement({
+        ...opts,
+        color: opts.color !== undefined ? toColor(opts.color) : undefined,
+        border: opts.border !== undefined ? toColor(opts.border) : undefined,
+        background: opts.background !== undefined ? toColor(opts.background) : undefined,
+    });
+}

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,8 +1,13 @@
-export * from "./color";
-export * from "./insets";
-export * from "./text";
-export * from "./layout";
-export * from "./content";
-export * from "./structure";
-export * from "./table";
-export * from "./descriptor";
+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";
+export * from "./content.js";
+export * from "./page-builder.js";
+export * from "./structure.js";
+export * from "./table.js";
+export * from "./forms.js";
+export * from "./descriptor.js";

package/dist/api/index.js

@@ -1,27 +1,16 @@
-"use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __exportStar = (this && this.__exportStar) || function(m, exports) {
-    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
-};
-Object.defineProperty(exports, "__esModule", { value: true });
 // The intuitive API layer: declarative factory functions + input normalizers that compile
 // down to the core engine elements. A thin, curated surface ON TOP of the engine - the
 // core classes stay untouched and remain exported for power users.
-__exportStar(require("./color"), exports);
-__exportStar(require("./insets"), exports);
-__exportStar(require("./text"), exports);
-__exportStar(require("./layout"), exports);
-__exportStar(require("./content"), exports);
-__exportStar(require("./structure"), exports);
-__exportStar(require("./table"), exports);
-__exportStar(require("./descriptor"), exports);
+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";
+export * from "./content.js";
+export * from "./page-builder.js";
+export * from "./structure.js";
+export * from "./table.js";
+export * from "./forms.js";
+export * from "./descriptor.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,21 +1,28 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.toEdges = toEdges;
-/** Normalizes any `Insets` to the engine's `[top, right, bottom, left]`. */
-function toEdges(i) {
-    var _a, _b, _c, _d, _e, _f;
-    if (typeof i === "number")
-        return [i, i, i, i];
+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" || 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 = (_a = o.x) !== null && _a !== void 0 ? _a : 0;
-        const y = (_b = o.y) !== null && _b !== void 0 ? _b : 0;
+        const x = spec(o.x);
+        const y = spec(o.y);
         return [y, x, y, x];
     }
-    return [(_c = o.top) !== null && _c !== void 0 ? _c : 0, (_d = o.right) !== null && _d !== void 0 ? _d : 0, (_e = o.bottom) !== null && _e !== void 0 ? _e : 0, (_f = o.left) !== null && _f !== void 0 ? _f : 0];
+    return [spec(o.top), spec(o.right), spec(o.bottom), spec(o.left)];
 }