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

package/README.md

@@ -142,7 +142,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. Over 1,600 tests hold the line across the workspace.
+  the identical XML. Over 2,400 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.
 - **Vectors, not bitmaps.** `Image("logo.svg")` keeps a logo a VECTOR - our own SVG reader and our own
@@ -166,13 +166,14 @@ verify all of it:
 | **[@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                              |
 | **[@jasy/vue](https://npmx.dev/@jasy/vue)**             | author PDFs as Vue components - and render them in the browser                                 |
+| **[@jasy/react](https://npmx.dev/@jasy/react)**         | author PDFs as React components - and render them in the browser                               |
 | **[@jasy/nuxt](https://npmx.dev/@jasy/nuxt)**           | the Nuxt module: zero-config PDFs, client **or** server                                        |
 
 ---
 
 ## Why you can trust it
 
-- **Over 1,600 tests, green** across the workspace (1,190 in the engine alone). The generator and the parser
+- **Over 2,400 tests, green** across the workspace (over 1,700 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

package/dist/api/color.d.ts

@@ -1,24 +1 @@
-import { Color } from "../common/color.js";
-/**
- * Every way to name a color. The FORM picks the convention, so there is never a guess
- * (locked design §2):
- *
- * | form                      | example                  | meaning                        |
- * |---------------------------|--------------------------|--------------------------------|
- * | named (full CSS set)      | `"steelblue"`, `"transparent"` | the ~148 CSS color names |
- * | hex 6 / 3                 | `"#1450aa"` / `"#14a"`   | CSS RGB                        |
- * | hex 8 / 4                 | `"#1450aacc"` / `"#14ac"`| CSS RGBA (alpha LAST)          |
- * | number                    | `0xff1450aa`             | Flutter ARGB (alpha FIRST)     |
- * | `rgb()` / `rgba()`        | `rgb(20,90,170)`         | channels 0–255 (`rgba` a=0–1)  |
- * | `Color` instance          | `new Color(20,90,170)`   | the engine layer, still valid  |
- */
-export type ColorInput = string | number | Color;
-/** Channels 0–255, fully opaque. */
-export declare function rgb(r: number, g: number, b: number): Color;
-/** Channels 0–255, alpha 0–1. */
-export declare function rgba(r: number, g: number, b: number, a: number): Color;
-/**
- * Normalizes any `ColorInput` to an engine `Color`. The single funnel every factory uses,
- * so a color means the same thing no matter how it was written.
- */
-export declare function toColor(input: ColorInput): Color;
+export * from "../common/color-input.js";

package/dist/api/color.js

@@ -1,278 +1,2 @@
-import { Color } from "../common/color.js";
-/** Channels 0–255, fully opaque. */
-export function rgb(r, g, b) {
-    return new Color(r, g, b, 1);
-}
-/** Channels 0–255, alpha 0–1. */
-export function rgba(r, g, b, a) {
-    return new Color(r, g, b, a);
-}
-/**
- * Normalizes any `ColorInput` to an engine `Color`. The single funnel every factory uses,
- * so a color means the same thing no matter how it was written.
- */
-export function toColor(input) {
-    if (input instanceof Color)
-        return input;
-    if (typeof input === "number")
-        return fromArgbNumber(input);
-    const s = input.trim().toLowerCase();
-    if (s.startsWith("#"))
-        return fromHex(s);
-    const named = CSS_COLORS[s];
-    if (named)
-        return new Color(named[0], named[1], named[2], named[3] ?? 1);
-    const call = /^([a-z-]+)\(([^)]*)\)$/.exec(s);
-    if (call)
-        return fromFunction(call[1], call[2], input);
-    throw new Error(`Unknown color: "${input}"`);
-}
-/**
- * The CSS colour FUNCTIONS. `rgb()`/`rgba()` and `hsl()`/`hsla()` are the sRGB family, so they convert
- * exactly and are supported; a wide-gamut function (`color()`, `lab()`, `oklch()`) is named and
- * refused rather than silently squashed into sRGB, since the result would be a colour nobody chose.
- *
- * Both syntaxes are accepted, because both occur in the wild: the legacy comma form
- * `rgb(20, 90, 170)` and the modern space form with an optional slash-alpha `rgb(20 90 170 / 50%)`.
- */
-function fromFunction(name, body, original) {
-    if (name !== "rgb" && name !== "rgba" && name !== "hsl" && name !== "hsla") {
-        throw new Error(`Unsupported color function "${name}()" in "${String(original)}". ` +
-            `Use a hex value, a CSS colour name, rgb()/rgba() or hsl()/hsla().`);
-    }
-    const [main, alphaPart] = body.split("/");
-    const parts = main
-        .trim()
-        .split(/[\s,]+/)
-        .filter(Boolean);
-    const alphaText = alphaPart !== undefined ? alphaPart.trim() : parts[3];
-    if (parts.length < 3)
-        throw new Error(`Unknown color: "${String(original)}"`);
-    const alpha = alphaText === undefined ? 1 : ratio(alphaText, original);
-    const [a, b, c] = parts;
-    if (name === "rgb" || name === "rgba") {
-        return new Color(channel(a, original), channel(b, original), channel(c, original), alpha);
-    }
-    const [r, g, bl] = hslToRgb(number(a, original), ratio(b, original), ratio(c, original));
-    return new Color(r, g, bl, alpha);
-}
-const NUMERIC = /^[+-]?(\d+\.?\d*|\.\d+)([eE][+-]?\d+)?$/;
-/**
- * One component of a colour function. `Number.parseFloat` stops at the first character it cannot use
- * and returns what it had, so `rgb(20abc, 90, 170)` would silently become `rgb(20, 90, 170)` - a
- * colour nobody wrote. The whole token has to be a number.
- */
-function number(text, original) {
-    const t = text.trim();
-    if (!NUMERIC.test(t))
-        throw new Error(`Unknown color: "${String(original)}"`);
-    return Number(t);
-}
-/** An rgb channel: 0-255, or a percentage of 255. */
-const channel = (text, original) => text.trim().endsWith("%")
-    ? (number(text.trim().slice(0, -1), original) / 100) * 255
-    : number(text, original);
-/** A 0..1 ratio written either as a number or as a percentage (alpha, saturation, lightness). */
-const ratio = (text, original) => text.trim().endsWith("%")
-    ? number(text.trim().slice(0, -1), original) / 100
-    : number(text, original);
-/** CSS hue-saturation-lightness to 0-255 channels. */
-function hslToRgb(hue, s, l) {
-    const h = ((hue % 360) + 360) % 360;
-    const c = (1 - Math.abs(2 * l - 1)) * s;
-    const x = c * (1 - Math.abs(((h / 60) % 2) - 1));
-    const m = l - c / 2;
-    const sector = Math.floor(h / 60) % 6;
-    const rgbPrime = [
-        [c, x, 0],
-        [x, c, 0],
-        [0, c, x],
-        [0, x, c],
-        [x, 0, c],
-        [c, 0, x],
-    ][sector];
-    return rgbPrime.map((v) => Math.round((v + m) * 255));
-}
-/** Flutter ARGB: 0xAARRGGBB, alpha FIRST. A 6-digit number has alpha 0x00 = transparent. */
-function fromArgbNumber(n) {
-    const a = (n >>> 24) & 0xff;
-    const r = (n >>> 16) & 0xff;
-    const g = (n >>> 8) & 0xff;
-    const b = n & 0xff;
-    return new Color(r, g, b, a / 255);
-}
-/** CSS hex: #RGB, #RGBA, #RRGGBB, #RRGGBBAA. Alpha is LAST. */
-function fromHex(s) {
-    const hex = s.slice(1);
-    const expand = (h) => h
-        .split("")
-        .map((c) => c + c)
-        .join("");
-    let full;
-    if (hex.length === 3 || hex.length === 4)
-        full = expand(hex);
-    else if (hex.length === 6 || hex.length === 8)
-        full = hex;
-    else
-        throw new Error(`Invalid hex color: "${s}"`);
-    const r = parseInt(full.slice(0, 2), 16);
-    const g = parseInt(full.slice(2, 4), 16);
-    const b = parseInt(full.slice(4, 6), 16);
-    const a = full.length === 8 ? parseInt(full.slice(6, 8), 16) / 255 : 1;
-    if ([r, g, b].some(Number.isNaN))
-        throw new Error(`Invalid hex color: "${s}"`);
-    return new Color(r, g, b, a);
-}
-// The full CSS named-color set (~148, incl. the synonyms grey/gray and `transparent`).
-// [r, g, b] or [r, g, b, alpha]. Lower-cased keys; `toColor` lower-cases the input.
-const CSS_COLORS = {
-    transparent: [0, 0, 0, 0],
-    aliceblue: [240, 248, 255],
-    antiquewhite: [250, 235, 215],
-    aqua: [0, 255, 255],
-    aquamarine: [127, 255, 212],
-    azure: [240, 255, 255],
-    beige: [245, 245, 220],
-    bisque: [255, 228, 196],
-    black: [0, 0, 0],
-    blanchedalmond: [255, 235, 205],
-    blue: [0, 0, 255],
-    blueviolet: [138, 43, 226],
-    brown: [165, 42, 42],
-    burlywood: [222, 184, 135],
-    cadetblue: [95, 158, 160],
-    chartreuse: [127, 255, 0],
-    chocolate: [210, 105, 30],
-    coral: [255, 127, 80],
-    cornflowerblue: [100, 149, 237],
-    cornsilk: [255, 248, 220],
-    crimson: [220, 20, 60],
-    cyan: [0, 255, 255],
-    darkblue: [0, 0, 139],
-    darkcyan: [0, 139, 139],
-    darkgoldenrod: [184, 134, 11],
-    darkgray: [169, 169, 169],
-    darkgrey: [169, 169, 169],
-    darkgreen: [0, 100, 0],
-    darkkhaki: [189, 183, 107],
-    darkmagenta: [139, 0, 139],
-    darkolivegreen: [85, 107, 47],
-    darkorange: [255, 140, 0],
-    darkorchid: [153, 50, 204],
-    darkred: [139, 0, 0],
-    darksalmon: [233, 150, 122],
-    darkseagreen: [143, 188, 143],
-    darkslateblue: [72, 61, 139],
-    darkslategray: [47, 79, 79],
-    darkslategrey: [47, 79, 79],
-    darkturquoise: [0, 206, 209],
-    darkviolet: [148, 0, 211],
-    deeppink: [255, 20, 147],
-    deepskyblue: [0, 191, 255],
-    dimgray: [105, 105, 105],
-    dimgrey: [105, 105, 105],
-    dodgerblue: [30, 144, 255],
-    firebrick: [178, 34, 34],
-    floralwhite: [255, 250, 240],
-    forestgreen: [34, 139, 34],
-    fuchsia: [255, 0, 255],
-    gainsboro: [220, 220, 220],
-    ghostwhite: [248, 248, 255],
-    gold: [255, 215, 0],
-    goldenrod: [218, 165, 32],
-    gray: [128, 128, 128],
-    grey: [128, 128, 128],
-    green: [0, 128, 0],
-    greenyellow: [173, 255, 47],
-    honeydew: [240, 255, 240],
-    hotpink: [255, 105, 180],
-    indianred: [205, 92, 92],
-    indigo: [75, 0, 130],
-    ivory: [255, 255, 240],
-    khaki: [240, 230, 140],
-    lavender: [230, 230, 250],
-    lavenderblush: [255, 240, 245],
-    lawngreen: [124, 252, 0],
-    lemonchiffon: [255, 250, 205],
-    lightblue: [173, 216, 230],
-    lightcoral: [240, 128, 128],
-    lightcyan: [224, 255, 255],
-    lightgoldenrodyellow: [250, 250, 210],
-    lightgray: [211, 211, 211],
-    lightgrey: [211, 211, 211],
-    lightgreen: [144, 238, 144],
-    lightpink: [255, 182, 193],
-    lightsalmon: [255, 160, 122],
-    lightseagreen: [32, 178, 170],
-    lightskyblue: [135, 206, 250],
-    lightslategray: [119, 136, 153],
-    lightslategrey: [119, 136, 153],
-    lightsteelblue: [176, 196, 222],
-    lightyellow: [255, 255, 224],
-    lime: [0, 255, 0],
-    limegreen: [50, 205, 50],
-    linen: [250, 240, 230],
-    magenta: [255, 0, 255],
-    maroon: [128, 0, 0],
-    mediumaquamarine: [102, 205, 170],
-    mediumblue: [0, 0, 205],
-    mediumorchid: [186, 85, 211],
-    mediumpurple: [147, 112, 219],
-    mediumseagreen: [60, 179, 113],
-    mediumslateblue: [123, 104, 238],
-    mediumspringgreen: [0, 250, 154],
-    mediumturquoise: [72, 209, 204],
-    mediumvioletred: [199, 21, 133],
-    midnightblue: [25, 25, 112],
-    mintcream: [245, 255, 250],
-    mistyrose: [255, 228, 225],
-    moccasin: [255, 228, 181],
-    navajowhite: [255, 222, 173],
-    navy: [0, 0, 128],
-    oldlace: [253, 245, 230],
-    olive: [128, 128, 0],
-    olivedrab: [107, 142, 35],
-    orange: [255, 165, 0],
-    orangered: [255, 69, 0],
-    orchid: [218, 112, 214],
-    palegoldenrod: [238, 232, 170],
-    palegreen: [152, 251, 152],
-    paleturquoise: [175, 238, 238],
-    palevioletred: [219, 112, 147],
-    papayawhip: [255, 239, 213],
-    peachpuff: [255, 218, 185],
-    peru: [205, 133, 63],
-    pink: [255, 192, 203],
-    plum: [221, 160, 221],
-    powderblue: [176, 224, 230],
-    purple: [128, 0, 128],
-    rebeccapurple: [102, 51, 153],
-    red: [255, 0, 0],
-    rosybrown: [188, 143, 143],
-    royalblue: [65, 105, 225],
-    saddlebrown: [139, 69, 19],
-    salmon: [250, 128, 114],
-    sandybrown: [244, 164, 96],
-    seagreen: [46, 139, 87],
-    seashell: [255, 245, 238],
-    sienna: [160, 82, 45],
-    silver: [192, 192, 192],
-    skyblue: [135, 206, 235],
-    slateblue: [106, 90, 205],
-    slategray: [112, 128, 144],
-    slategrey: [112, 128, 144],
-    snow: [255, 250, 250],
-    springgreen: [0, 255, 127],
-    steelblue: [70, 130, 180],
-    tan: [210, 180, 140],
-    teal: [0, 128, 128],
-    thistle: [216, 191, 216],
-    tomato: [255, 99, 71],
-    turquoise: [64, 224, 208],
-    violet: [238, 130, 238],
-    wheat: [245, 222, 179],
-    white: [255, 255, 255],
-    whitesmoke: [245, 245, 245],
-    yellow: [255, 255, 0],
-    yellowgreen: [154, 205, 50],
-};
+// Lives in `common/` because the engine reads it too; this is its public face.
+export * from "../common/color-input.js";

package/dist/api/content.d.ts

@@ -31,14 +31,19 @@ export interface SvgOptions extends BoundsInput {
 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";
+/** Where an image sits in its own box - the image's counterpart of a Text's `align`. */
+export type ImageAlign = "center" | "top" | "bottom" | "left" | "right" | "top left" | "top right" | "bottom left" | "bottom right";
 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` (the image's own size); with any explicit size or an
-     *  `aspectRatio`, `fill` - the image scales into its box, as `<img width height>` does. */
+    /** How the image fills its box (CSS `object-fit`). Default `fill`. Given no size, the box is the image's
+     *  own size, scaled down to fit what is offered (never up) - so `fill` draws it undistorted. */
     fit?: ImageFit;
+    /** Where the image sits in its box when `fit` leaves space or cuts it off. Default `"center"`; a
+     *  portrait in a `cover` box keeps its top with `"top"`. */
+    align?: ImageAlign;
     /** Corner radius in points (rounds the image box). */
     radius?: RadiusInput;
     /** Alternate text for accessibility (tagged PDF): describes the image for screen readers. With `alt`

package/dist/api/content.js

@@ -33,6 +33,17 @@ const FIT = {
     cover: BoxFit.cover,
     fill: BoxFit.fill,
 };
+const IMAGE_ALIGN = {
+    center: { x: 0.5, y: 0.5 },
+    top: { x: 0.5, y: 0 },
+    bottom: { x: 0.5, y: 1 },
+    left: { x: 0, y: 0.5 },
+    right: { x: 1, y: 0.5 },
+    "top left": { x: 0, y: 0 },
+    "top right": { x: 1, y: 0 },
+    "bottom left": { x: 0, y: 1 },
+    "bottom right": { x: 1, y: 1 },
+};
 export function Canvas(a, b) {
     const opts = typeof a === "function" ? {} : a;
     const paint = typeof a === "function" ? a : b;
@@ -118,6 +129,10 @@ export function Image(src, opts = {}) {
         if (opts.radius !== undefined) {
             throw new Error("@jasy/pdf: radius is not supported for an SVG yet - wrap it in a Box instead.");
         }
+        if (opts.align !== undefined) {
+            throw new Error("@jasy/pdf: align is not supported for an SVG yet - it is always drawn centred in its box. " +
+                "Size the box to the drawing, or place it with the parent's align.");
+        }
         return Svg(src, opts);
     }
     return rasterImage(src, opts);
@@ -125,12 +140,6 @@ export function Image(src, opts = {}) {
 function rasterImage(src, opts = {}) {
     const w = opts.width !== undefined ? toDimension(opts.width) : undefined;
     const h = opts.height !== undefined ? toDimension(opts.height) : 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"
             ? isImageUrl(src)
@@ -144,7 +153,8 @@ function rasterImage(src, opts = {}) {
         widthFactor: w?.factor,
         heightFactor: h?.factor,
         ...toBounds(opts),
-        fit,
+        fit: opts.fit ? FIT[opts.fit] : undefined,
+        align: opts.align ? IMAGE_ALIGN[opts.align] : undefined,
         radius: opts.radius !== undefined ? toRadius(opts.radius) : undefined,
         alt: opts.alt,
     })

package/dist/api/descriptor.js

@@ -2,8 +2,9 @@ import { Text, Paragraph, span } from "./text.js";
 import { Column, Row, Box, Padding, Spacer, PageBreak, keepTogether, Expanded, Positioned, Link, Anchor, Bookmark, Rotated, RotatedBox, } from "./layout.js";
 import { Canvas, Divider, Image, Svg } from "./content.js";
 import { Page, Document, DefaultTextStyle } from "./structure.js";
-import { PageNumber, PageCount } from "./page-builder.js";
+import { PageBuilder, PageCount, PageNumber, SubPageCount, SubPageNumber, } from "./page-builder.js";
 import { Table } from "./table.js";
+import { ColumnBreak, Flow, FlowWithoutRegionError, Region, SplitView, } from "./flow.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.
@@ -104,6 +105,20 @@ const REGISTRY = {
         const body = rows.filter((r) => !r.props?.header);
         return Table({ ...props, header: header ? rowCells(header) : undefined }, body.map(rowCells));
     },
+    // A Flow's `page` is a function prop: the binding renders one page of the template per call.
+    flow: (props, children) => Flow({
+        gap: props.gap,
+        balance: props.balance,
+        template: (info) => {
+            const page = props.page?.(info) ?? [];
+            if (page.length === 0)
+                throw new FlowWithoutRegionError();
+            return wrappedChild(page);
+        },
+    }, elementChildren(children)),
+    region: (props) => Region(props),
+    "column-break": () => ColumnBreak(),
+    "split-view": (props, children) => SplitView(props, elementChildren(children)),
     positioned: (props, children) => Positioned(props, elementChildren(children)[0]),
     "default-text-style": (props, children) => DefaultTextStyle(props, elementChildren(children)),
     // Navigation. `Link` takes exactly one of `href` (a URL) or `to` (an `Anchor` name) - the factory
@@ -114,10 +129,22 @@ const REGISTRY = {
     // Transforms.
     rotated: (props, children) => Rotated(props, wrappedChild(children)),
     "rotated-box": (props, children) => RotatedBox(props, wrappedChild(children)),
-    // Page numbers. `PageBuilder` itself is deliberately NOT exposed: it takes a closure, which a template
-    // cannot express. These two cover what the closure exists for.
+    // Page numbers. A binding renders `build` per page, like a Flow's `page`; nothing built is an empty
+    // Column, so a builder can show something on some pages only.
+    "page-builder": (props) => {
+        // A descriptor posted as JSON loses its functions; say so here, not mid-layout.
+        if (typeof props.build !== "function") {
+            throw new Error("A page-builder needs a `build` function prop (lost if the descriptor went through JSON).");
+        }
+        return PageBuilder((info) => {
+            const built = props.build(info) ?? [];
+            return built.length === 0 ? Column([]) : wrappedChild(built);
+        });
+    },
     "page-number": (props) => PageNumber(props),
     "page-count": (props) => PageCount(props),
+    "sub-page-number": (props) => SubPageNumber(props),
+    "sub-page-count": (props) => SubPageCount(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

package/dist/api/flow.d.ts

@@ -0,0 +1,55 @@
+import { FlowElement, type FlowTemplate } from "../elements/layout/flow-element.js";
+import { RegionElement } from "../elements/layout/region-element.js";
+import { ColumnBreakElement } from "../elements/layout/column-break-element.js";
+import { PDFElement } from "../elements/pdf-element.js";
+import { BoundsInput, SizeInput } from "./dimension.js";
+export type { FlowPage, FlowTemplate } from "../elements/layout/flow-element.js";
+export { FlowRegionsEmptyError, FlowUnboundedError, FlowWithoutRegionError, RegionInPageBuilderError, } from "../elements/layout/flow-element.js";
+export { RegionOutsideFlowError, RegionReusedError } from "../elements/layout/region-element.js";
+export interface FlowOptions {
+    /** The layout of one page of the Flow, built per page; its `Region`s are where the content goes. */
+    template: FlowTemplate;
+    /** Space between the content's elements, in points. */
+    gap?: number;
+    /** On the last page, spread the content so the Regions come out about equally full (default false). */
+    balance?: boolean;
+}
+/**
+ * Content flowing through the `Region`s of a template: the first Region full, then the next, then the
+ * next page. It takes its height from where it sits - the rest of the page, or a box with a height.
+ *
+ * @experimental The shape may still change.
+ */
+export declare function Flow(opts: FlowOptions, content: PDFElement[]): FlowElement;
+export interface RegionOptions extends BoundsInput {
+    width?: SizeInput;
+    height?: SizeInput;
+}
+/**
+ * A place in a `Flow`'s template that the content flows through, in tree order. Sized by the layout
+ * around it (`Expanded`, `width`, `height`); with nothing given it fills what it is offered.
+ *
+ * @experimental
+ */
+export declare function Region(opts?: RegionOptions): RegionElement;
+/** Continue in the next `Region` of the Flow it sits in (from the last one, the next page's first). */
+export declare function ColumnBreak(): ColumnBreakElement;
+export interface SplitViewOptions {
+    /** How many columns, side by side and equally wide (default 2). */
+    columns?: number;
+    /** Gap between both the columns and the content's elements (default 0). */
+    gap?: number;
+    /** Gap between the content's elements (overrides `gap`). */
+    rowGap?: number;
+    /** Gap between the columns (overrides `gap`). */
+    colGap?: number;
+    /** On the last page, columns of about equal height, as CSS columns are (default true). */
+    balance?: boolean;
+}
+/**
+ * Newspaper columns: the content fills the first column, then the next, then the next page. A `Flow`
+ * with a ready template - for anything else (a title area, columns of different widths) build your own.
+ *
+ * @experimental
+ */
+export declare function SplitView(opts: SplitViewOptions, content: PDFElement[]): FlowElement;

package/dist/api/flow.js

@@ -0,0 +1,71 @@
+import { ContainerElement } from "../elements/container-element.js";
+import { FlowElement } from "../elements/layout/flow-element.js";
+import { RegionElement } from "../elements/layout/region-element.js";
+import { ColumnBreakElement } from "../elements/layout/column-break-element.js";
+import { toBounds, toDimension } from "./dimension.js";
+import { Expanded, Row } from "./layout.js";
+export { FlowRegionsEmptyError, FlowUnboundedError, FlowWithoutRegionError, RegionInPageBuilderError, } from "../elements/layout/flow-element.js";
+export { RegionOutsideFlowError, RegionReusedError } from "../elements/layout/region-element.js";
+/**
+ * Content flowing through the `Region`s of a template: the first Region full, then the next, then the
+ * next page. It takes its height from where it sits - the rest of the page, or a box with a height.
+ *
+ * @experimental The shape may still change.
+ */
+export function Flow(opts, content) {
+    return new FlowElement({
+        content: new ContainerElement({ x: 0, y: 0, children: content, gap: opts.gap }),
+        template: opts.template,
+        balance: opts.balance,
+    });
+}
+/**
+ * A place in a `Flow`'s template that the content flows through, in tree order. Sized by the layout
+ * around it (`Expanded`, `width`, `height`); with nothing given it fills what it is offered.
+ *
+ * @experimental
+ */
+export function Region(opts = {}) {
+    const w = opts.width !== undefined ? toDimension(opts.width) : undefined;
+    const h = opts.height !== undefined ? toDimension(opts.height) : undefined;
+    return new RegionElement({
+        width: w?.points,
+        height: h?.points,
+        widthFactor: w?.factor,
+        heightFactor: h?.factor,
+        ...toBounds(opts),
+    })
+        .withAlignSelf(opts.alignSelf)
+        .withOrder(opts.order)
+        .withFlexShrink(opts.flexShrink);
+}
+/** Continue in the next `Region` of the Flow it sits in (from the last one, the next page's first). */
+export function ColumnBreak() {
+    return new ColumnBreakElement();
+}
+/** A value as the author wrote it: `"2"` quoted, `NaN` as NaN. */
+const shown = (value) => typeof value === "string" ? JSON.stringify(value) : String(value);
+/**
+ * Newspaper columns: the content fills the first column, then the next, then the next page. A `Flow`
+ * with a ready template - for anything else (a title area, columns of different widths) build your own.
+ *
+ * @experimental
+ */
+export function SplitView(opts, content) {
+    const columns = opts.columns ?? 2;
+    if (!Number.isInteger(columns) || columns < 1) {
+        throw new Error(`Invalid SplitView columns ${shown(columns)}: use a whole number of 1 or more.`);
+    }
+    for (const key of ["gap", "rowGap", "colGap"]) {
+        const value = opts[key];
+        if (value !== undefined && !(Number.isFinite(value) && value >= 0)) {
+            throw new Error(`Invalid SplitView ${key} ${shown(value)}: use a number of points, 0 or more.`);
+        }
+    }
+    const colGap = opts.colGap ?? opts.gap;
+    return Flow({
+        gap: opts.rowGap ?? opts.gap,
+        balance: opts.balance ?? true,
+        template: () => Row({ gap: colGap }, Array.from({ length: columns }, () => Expanded(Region()))),
+    }, content);
+}

package/dist/api/gradient.d.ts

@@ -1,53 +1 @@
-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;
+export * from "../common/gradient.js";