@jasy/pdf 1.0.0-alpha.1

package/README.md

@@ -0,0 +1,171 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/jasy-pdf/jasy/main/docs/logo.png" width="130" alt="jasy">
+</p>
+
+<h1 align="center">jasy</h1>
+
+<p align="center">
+  <b>ZUGFeRD &amp; XRechnung e-invoices in pure TypeScript - generate, validate, read.</b><br>
+  A Flutter-style PDF engine underneath. The EN-16931 maths done <i>for</i> you. Zero Java, zero upload.
+</p>
+
+<p align="center">
+  <code>npm i @jasy/zugferd</code> &nbsp;·&nbsp; <code>npx @jasy/cli</code> &nbsp;·&nbsp; MIT
+</p>
+
+---
+
+## Don't believe us. Point it at your own invoice.
+
+```bash
+npx @jasy/cli validate ./your-invoice.pdf
+```
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/jasy-pdf/jasy/main/docs/validate.png" width="430" alt="jasy validate: VALID">
+</p>
+
+That `✓` is the **same official KoSIT Schematron + veraPDF the big players run** - against the EN 16931
+**and** the German XRechnung (BR-DE) rules, plus PDF/A-3. Your file, your terminal, in seconds. No
+account, no upload, nothing leaves your machine.
+
+> Java has **Mustang**. PHP has **horstoeko**. Python has **factur-x**.<br>
+> Node had nothing. **Now it has jasy.**
+
+---
+
+## You bring the line items. jasy does the rest.
+
+You never compute a total, a VAT breakdown or a rounding again. You hand jasy the line items - it
+**derives** the document totals and the EN-16931 VAT breakdown, spec-correct. That is *why* the
+invoices validate: the amounts are correct **by construction**, so the single biggest class of
+EN-16931 failures (the BR-CO total checks) simply cannot happen.
+
+```ts
+import { renderZugferd } from "@jasy/zugferd";
+
+const { bytes, xml } = await renderZugferd({
+  number: "RE-2026-001",
+  issueDate: "2026-06-17",
+  currency: "EUR",
+  seller: { name: "Northwind Studio GmbH", vatId: "DE123456789",
+            address: { city: "Berlin", postCode: "10115", country: "DE" } },
+  buyer:  { name: "Globex Corporation Ltd",
+            address: { city: "Munich", postCode: "80331", country: "DE" } },
+  lines: [
+    { name: "Brand identity design", quantity: 2, unit: "HUR", netUnitPrice: 100,
+      vat: { category: "S", ratePercent: 19 } },
+  ],
+});
+// bytes -> a valid ZUGFeRD PDF/A-3   ·   xml -> the embedded EN-16931 XML
+// totals, tax breakdown and rounding: computed for you.
+```
+
+One object in. A conformant, human-readable PDF/A-3 **and** the EN-16931 CII/UBL XML out. ZUGFeRD and
+XRechnung work out of the box - no config, no template wrangling.
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/jasy-pdf/jasy/main/docs/invoice.png" width="450" alt="a generated ZUGFeRD invoice">
+</p>
+
+---
+
+## The whole loop, from the terminal
+
+```bash
+jasy read invoice.pdf               # identify + show: parties, line items, totals
+jasy validate invoice.pdf           # EN 16931 + XRechnung + PDF/A (exit 1 if invalid)
+jasy export invoice.pdf -o out.xlsx # read it back: JSON · TXT · Excel
+```
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/jasy-pdf/jasy/main/docs/read.png" width="520" alt="the jasy terminal: invoice + checks + export">
+</p>
+
+Reads **CII and UBL**, real third-party invoices included - not just our own output.
+
+---
+
+## A PDF engine that reads like Flutter
+
+Underneath it all is a declarative, component-based PDF engine - written from the byte stream up, no
+headless browser, no `pdf-lib`. You describe the document; it lays it out and paginates.
+
+```ts
+import { Document, Page, Column, Text, renderToBytes } from "@jasy/pdf";
+
+const pdf = await renderToBytes(
+  Document([
+    Page({ size: "A4", margin: 48 }, [
+      Column({ gap: 8 }, [
+        Text("Invoice RE-2026-001", { size: 24, bold: true, color: "steelblue" }),
+        Text("Thank you for your business.", { color: "gray" }),
+      ]),
+    ]),
+  ]),
+);
+```
+
+Real text layout (Adobe AFM metrics, kerning, word-wrap), flexbox-style `gap` / `justify` / `align`,
+boxes with radius and alpha, images, custom TrueType fonts, and **real pagination** - content that
+overflows flows onto the next page, headers and footers repeat.
+
+---
+
+## Under the hood - and every bit is real
+
+This is not a wrapper around someone else's renderer. It is built from the byte stream up, and you can
+verify all of it:
+
+- **Hand-rolled PDF writer.** No `pdf-lib`, no PDFKit, no Java, no headless Chrome - the byte stream is ours.
+- **Font subsetting.** Only the glyphs you actually use are embedded, with the PDF/A subset tag - a
+  740 KB font ships as a ~76 KB subset, and the text stays copy- and searchable.
+- **Compression.** Content streams and images are FlateDecode-compressed; the spreadsheets `jasy export`
+  writes are real `.xlsx` ZIPs we deflate with our own writer and CRC32, zero dependencies.
+- **Real font metrics.** Text is laid out with the Adobe AFM metrics of the standard-14 fonts - kerning
+  and word-wrap are *computed*, not guessed.
+- **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.
+- **Schematron, local.** The official EN-16931 + XRechnung rules run via saxon-js (the real XSLT, in pure
+  JS) - no Java, no upload.
+
+---
+
+## Packages
+
+| Package | What it is |
+| --- | --- |
+| **[@jasy/zugferd](https://www.npmjs.com/package/@jasy/zugferd)** | ZUGFeRD / XRechnung: your data → PDF/A-3 + EN-16931 XML, with local validation. **The prize.** |
+| **[@jasy/cli](https://www.npmjs.com/package/@jasy/cli)** | the `jasy` terminal: read · validate · export, headless **and** interactive |
+| **[@jasy/pdf](https://www.npmjs.com/package/@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.
+- **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.
+- **100% local.** No upload, no service, no account - DSGVO-safe by construction.
+
+---
+
+## Honest scope
+
+jasy targets the documents that matter here: invoices, reports, quotes, datasheets. It is **not** a
+LaTeX / WeasyPrint replacement - no microtypography, hyphenation or bidi, and arbitrary multi-page flow
+of *any* content is still maturing. For e-invoices (a table, totals, a footer) it is complete - they
+even paginate. We would rather under-promise and over-deliver in the demo above.
+
+> **Status:** young and pre-1.0. The API can still shift between minor versions. Everything shown here
+> works and is tested.
+
+---
+
+<p align="center">
+  MIT &nbsp;·&nbsp; built by <a href="https://github.com/jasy-pdf">Florian Heuberger</a>
+</p>

package/dist/api/args.d.ts

@@ -0,0 +1,10 @@
+import { PDFElement } from "../elements/pdf-element";
+/**
+ * Lets a container factory be called either `F(children)` or `F(opts, children)` - the
+ * same ergonomic shape across Document/Page/Column/Row/Box. When the first argument is the
+ * child array, options default to empty.
+ */
+export declare function splitArgs<O>(a: O | PDFElement[], b?: PDFElement[]): {
+    opts: O;
+    children: PDFElement[];
+};

package/dist/api/args.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.splitArgs = splitArgs;
+/**
+ * Lets a container factory be called either `F(children)` or `F(opts, children)` - the
+ * same ergonomic shape across Document/Page/Column/Row/Box. When the first argument is the
+ * child array, options default to empty.
+ */
+function splitArgs(a, b) {
+    if (Array.isArray(a))
+        return { opts: {}, children: a };
+    return { opts: a, children: b !== null && b !== void 0 ? b : [] };
+}

package/dist/api/color.d.ts

@@ -0,0 +1,24 @@
+import { Color } from "../common/color";
+/**
+ * Every way to name a colour. 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 colour 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 colour means the same thing no matter how it was written.
+ */
+export declare function toColor(input: ColorInput): Color;

package/dist/api/color.js

@@ -0,0 +1,215 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.rgb = rgb;
+exports.rgba = rgba;
+exports.toColor = toColor;
+const color_1 = require("../common/color");
+/** Channels 0–255, fully opaque. */
+function rgb(r, g, b) {
+    return new color_1.Color(r, g, b, 1);
+}
+/** Channels 0–255, alpha 0–1. */
+function rgba(r, g, b, a) {
+    return new color_1.Color(r, g, b, a);
+}
+/**
+ * Normalizes any `ColorInput` to an engine `Color`. The single funnel every factory uses,
+ * so a colour means the same thing no matter how it was written.
+ */
+function toColor(input) {
+    var _a;
+    if (input instanceof color_1.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_1.Color(named[0], named[1], named[2], (_a = named[3]) !== null && _a !== void 0 ? _a : 1);
+    throw new Error(`Unknown color: "${input}"`);
+}
+/** 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_1.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_1.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],
+};

package/dist/api/content.d.ts

@@ -0,0 +1,36 @@
+import { ImageElement, CustomImage } from "../elements/image-element";
+import { PDFElement } from "../elements/pdf-element";
+import { ColorInput } from "./color";
+import { Insets } from "./insets";
+/** A horizontal rule (locked §4). */
+export interface DividerOptions {
+    /** Line colour (default a light grey). */
+    color?: ColorInput;
+    /** Line thickness in points (default 1). */
+    thickness?: number;
+    /** Space above/below the rule (default a small vertical gap). */
+    margin?: Insets;
+}
+/**
+ * A horizontal rule that spans the parent's width. Maps to a `LineElement` (hiding its
+ * `xEnd`/`yEnd` mechanics) wrapped in a `PaddingElement` - the line has no height of its
+ * own, so the padding gives it vertical room and centres the rule. Use inside a Column.
+ */
+export declare function Divider(opts?: DividerOptions): PDFElement;
+/** An image source: a local file path, or a `CustomImage` (e.g. a browser-supplied image). */
+export type ImageSource = string | CustomImage;
+/** How the image fills its box (locked §4). Mirrors CSS `object-fit`. */
+export type ImageFit = "none" | "contain" | "cover" | "fill";
+export interface ImageOptions {
+    width?: number;
+    height?: number;
+    /** Fit within the box (default `none`). */
+    fit?: ImageFit;
+    /** Corner radius in points (rounds the image box). */
+    radius?: number;
+}
+/**
+ * An image. `src` is a local file path (wrapped in a `CustomLocalImage`) or a ready
+ * `CustomImage` for non-filesystem sources. Maps to an `ImageElement`.
+ */
+export declare function Image(src: ImageSource, opts?: ImageOptions): ImageElement;

package/dist/api/content.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Divider = Divider;
+exports.Image = Image;
+const line_element_1 = require("../elements/line-element");
+const padding_element_1 = require("../elements/layout/padding-element");
+const image_element_1 = require("../elements/image-element");
+const color_1 = require("./color");
+const insets_1 = require("./insets");
+const DEFAULT_DIVIDER_COLOR = "lightgray";
+const DEFAULT_DIVIDER_MARGIN = { y: 6 };
+/**
+ * A horizontal rule that spans the parent's width. Maps to a `LineElement` (hiding its
+ * `xEnd`/`yEnd` mechanics) wrapped in a `PaddingElement` - the line has no height of its
+ * own, so the padding gives it vertical room and centres the rule. Use inside a Column.
+ */
+function Divider(opts = {}) {
+    var _a, _b, _c;
+    const line = new line_element_1.LineElement({
+        x: 0,
+        y: 0,
+        xEnd: 0, // resolved to the parent's width at layout time
+        yEnd: 0, // horizontal: no vertical span
+        color: (0, color_1.toColor)((_a = opts.color) !== null && _a !== void 0 ? _a : DEFAULT_DIVIDER_COLOR),
+        strokeWidth: (_b = opts.thickness) !== null && _b !== void 0 ? _b : 1,
+    });
+    return new padding_element_1.PaddingElement({
+        margin: (0, insets_1.toEdges)((_c = opts.margin) !== null && _c !== void 0 ? _c : DEFAULT_DIVIDER_MARGIN),
+        child: line,
+    });
+}
+const FIT = {
+    none: image_element_1.BoxFit.none,
+    contain: image_element_1.BoxFit.contain,
+    cover: image_element_1.BoxFit.cover,
+    fill: image_element_1.BoxFit.fill,
+};
+/**
+ * An image. `src` is a local file path (wrapped in a `CustomLocalImage`) or a ready
+ * `CustomImage` for non-filesystem sources. Maps to an `ImageElement`.
+ */
+function Image(src, opts = {}) {
+    return new image_element_1.ImageElement({
+        image: typeof src === "string" ? new image_element_1.CustomLocalImage(src) : src,
+        width: opts.width,
+        height: opts.height,
+        fit: opts.fit ? FIT[opts.fit] : undefined,
+        radius: opts.radius,
+    });
+}

package/dist/api/descriptor.d.ts

@@ -0,0 +1,25 @@
+import { PDFElement } from "../elements/pdf-element";
+import { PDFDocumentElement } from "../elements/pdf-document-element";
+/**
+ * The framework-agnostic contract (the firewall). A binding (Vue/React, or any tree-builder)
+ * produces a tree of these plain descriptors; `build` turns each node into an engine element
+ * through the SAME factories the programmatic API uses - one mapping, shared by every binding.
+ */
+export interface Descriptor {
+    type: string;
+    props?: Record<string, any>;
+    children?: DescriptorChild[];
+}
+export type DescriptorChild = Descriptor | string;
+/** A registry entry: turn a node's props + raw children into an engine element. */
+export type ElementFactory = (props: any, children: DescriptorChild[]) => PDFElement;
+/**
+ * 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
+ * existing type of the same name.
+ */
+export declare function registerElement(type: string, factory: ElementFactory): void;
+/** Turns one descriptor node (or bare string → `Text`) into an engine element. */
+export declare function build(node: DescriptorChild): PDFElement;
+/** Builds a descriptor tree whose root is a `document` into the renderable root element. */
+export declare function buildDocument(root: Descriptor): PDFDocumentElement;

package/dist/api/descriptor.js

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerElement = registerElement;
+exports.build = build;
+exports.buildDocument = buildDocument;
+const text_1 = require("./text");
+const layout_1 = require("./layout");
+const content_1 = require("./content");
+const structure_1 = require("./structure");
+// Element children (Column/Row/Box/Page/…) → built recursively. Text/Paragraph children are
+// strings or `span` descriptors and become content instead.
+function elementChildren(children) {
+    return children.map(build);
+}
+function textOf(node) {
+    var _a;
+    if (typeof node === "string")
+        return node;
+    const first = (_a = node.children) === null || _a === void 0 ? void 0 : _a[0];
+    return typeof first === "string" ? first : "";
+}
+function toSegment(c) {
+    if (typeof c === "string")
+        return (0, text_1.span)(c);
+    if (c.type === "span")
+        return (0, text_1.span)(textOf(c), c.props);
+    throw new Error(`A Text child must be a string or a span, got "${c.type}"`);
+}
+function textContent(children) {
+    if (children.length === 1 && typeof children[0] === "string")
+        return children[0];
+    return children.map(toSegment);
+}
+const REGISTRY = {
+    document: (props, children) => (0, structure_1.Document)(props, elementChildren(children)),
+    page: (props, children) => (0, structure_1.Page)(props, elementChildren(children)),
+    column: (props, children) => (0, layout_1.Column)(props, elementChildren(children)),
+    row: (props, children) => (0, layout_1.Row)(props, elementChildren(children)),
+    box: (props, children) => (0, layout_1.Box)(props, elementChildren(children)),
+    padding: (props, children) => { var _a; return (0, layout_1.Padding)((_a = props.insets) !== null && _a !== void 0 ? _a : 0, elementChildren(children)[0]); },
+    expanded: (props, children) => (0, layout_1.Expanded)(props, elementChildren(children)[0]),
+    spacer: (props) => (0, layout_1.Spacer)(props === null || props === void 0 ? void 0 : props.flex),
+    divider: (props) => (0, content_1.Divider)(props),
+    image: (props) => (0, content_1.Image)(props.src, props),
+    text: (props, children) => (0, text_1.Text)(textContent(children), props),
+    paragraph: (props, children) => (0, text_1.Paragraph)(textContent(children), props),
+};
+/**
+ * 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
+ * existing type of the same name.
+ */
+function registerElement(type, factory) {
+    REGISTRY[type] = factory;
+}
+/** Turns one descriptor node (or bare string → `Text`) into an engine element. */
+function build(node) {
+    var _a, _b;
+    if (typeof node === "string")
+        return (0, text_1.Text)(node);
+    const factory = REGISTRY[node.type];
+    if (!factory)
+        throw new Error(`Unknown element type: "${node.type}"`);
+    return factory((_a = node.props) !== null && _a !== void 0 ? _a : {}, (_b = node.children) !== null && _b !== void 0 ? _b : []);
+}
+/** Builds a descriptor tree whose root is a `document` into the renderable root element. */
+function buildDocument(root) {
+    if (root.type !== "document")
+        throw new Error(`Expected a "document" root, got "${root.type}"`);
+    return build(root);
+}

package/dist/api/index.d.ts

@@ -0,0 +1,8 @@
+export * from "./color";
+export * from "./insets";
+export * from "./text";
+export * from "./layout";
+export * from "./content";
+export * from "./structure";
+export * from "./table";
+export * from "./descriptor";

package/dist/api/index.js

@@ -0,0 +1,27 @@
+"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);

package/dist/api/insets.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 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
+ * for whichever shape fits and never think about the engine order.
+ */
+export type Insets = number | {
+    x?: number;
+    y?: number;
+} | {
+    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];