@jasy/pdf 1.0.0-alpha.9 → 1.0.0-beta.1

package/dist/svg/css.js

@@ -0,0 +1,115 @@
+import { SvgUnsupportedError } from "./errors.js";
+const COMMENTS = /\/\*[\s\S]*?\*\//g;
+/** One compound selector, e.g. `rect.st0#a`. Anything structural is refused, not approximated. */
+function parseSelector(selector, order) {
+    const text = selector.trim();
+    if (/[\s>+~]/.test(text)) {
+        throw new SvgUnsupportedError(`the CSS selector "${text}" (it combines elements)`, "Only flat selectors are resolved. Re-export with presentation attributes instead.");
+    }
+    if (text.includes(":") || text.includes("[")) {
+        throw new SvgUnsupportedError(`the CSS selector "${text}" (pseudo-class or attribute selector)`, "Only a tag, .class and #id are resolved. Re-export with presentation attributes instead.");
+    }
+    const classes = [...text.matchAll(/\.([\w-]+)/g)].map((m) => m[1]);
+    const id = /#([\w-]+)/.exec(text)?.[1];
+    const tag = /^[\w-]+/.exec(text)?.[0];
+    // The usual a-b-c weights, flattened: an id beats any number of classes, a class beats a tag.
+    const weight = (id ? 10000 : 0) + classes.length * 100 + (tag ? 1 : 0);
+    return { tag, id, classes, weight, order };
+}
+function parseDeclarations(body) {
+    const out = {};
+    for (const declaration of body.split(";")) {
+        const colon = declaration.indexOf(":");
+        if (colon === -1)
+            continue;
+        const property = declaration.slice(0, colon).trim();
+        // `!important` would need a second cascade level; exporters do not emit it, so it is refused
+        // rather than silently treated as a normal declaration.
+        const value = declaration.slice(colon + 1).trim();
+        if (!property)
+            continue;
+        if (/!\s*important$/i.test(value)) {
+            throw new SvgUnsupportedError(`"!important" in a <style> block`, "Remove it, or re-export with presentation attributes.");
+        }
+        out[property] = value;
+    }
+    return out;
+}
+/**
+ * Parses every `<style>` block's text into rules, in source order.
+ *
+ * The brace matching is done by hand rather than with one regex: `@media print { .a { … } }` nests,
+ * and a regex that skips to the first balanced-looking block silently applies the INNER rule while
+ * never seeing the at-rule that guards it.
+ */
+export function parseStylesheet(css) {
+    const text = css.replace(COMMENTS, "");
+    const rules = [];
+    let order = 0;
+    let i = 0;
+    while (i < text.length) {
+        const open = text.indexOf("{", i);
+        if (open === -1)
+            break;
+        // A statement at-rule (`@import "a";`) ends at its semicolon. Taking everything up to the next
+        // brace as one prelude would swallow the rule that follows it.
+        const head = text.slice(i, open);
+        const prelude = head.slice(head.lastIndexOf(";") + 1).trim();
+        let depth = 1;
+        let j = open + 1;
+        while (j < text.length && depth > 0) {
+            if (text[j] === "{")
+                depth++;
+            else if (text[j] === "}")
+                depth--;
+            j++;
+        }
+        if (prelude.startsWith("@")) {
+            // An at-rule is DROPPED, not reported - which is what CSS itself does with one it cannot
+            // evaluate, and what the corpus demanded: 68 of 10,819 real files carry a `@media
+            // (prefers-color-scheme)` or a `@keyframes` that can never apply to a static page, and
+            // refusing them meant those files did not render at all.
+            // The exception is a query that always holds for print, whose rules DO apply.
+            const [at, ...rest] = prelude.split(/\s+/);
+            // A media list applies if ANY of its components does - `@media print, screen` is for print too.
+            const applies = at === "@media" &&
+                rest
+                    .join(" ")
+                    .split(",")
+                    .some((q) => ["print", "all", ""].includes(q.trim()));
+            if (applies) {
+                // Its body is a nested stylesheet; parse it in place so the rules keep their source order.
+                for (const rule of parseStylesheet(text.slice(open + 1, j - 1))) {
+                    rules.push({ ...rule, order: order++ });
+                }
+            }
+            i = j;
+            continue;
+        }
+        const declarations = parseDeclarations(text.slice(open + 1, j - 1));
+        for (const selector of prelude.split(",")) {
+            if (selector.trim() === "")
+                continue;
+            rules.push({ ...parseSelector(selector, order++), declarations });
+        }
+        i = j;
+    }
+    return rules;
+}
+/**
+ * The declarations that apply to one element, weakest first - so a caller can just assign them in
+ * order and let the last one win, as the cascade does.
+ */
+export function declarationsFor(rules, tagName, attributes) {
+    if (rules.length === 0)
+        return {};
+    const classes = (attributes.class ?? "").trim().split(/\s+/).filter(Boolean);
+    const matched = rules.filter((rule) => (rule.tag === undefined || rule.tag === tagName) &&
+        (rule.id === undefined || rule.id === attributes.id) &&
+        rule.classes.every((name) => classes.includes(name)));
+    matched.sort((a, b) => a.weight - b.weight || a.order - b.order);
+    const out = {};
+    for (const rule of matched)
+        Object.assign(out, rule.declarations);
+    return out;
+}

package/dist/svg/errors.d.ts

@@ -0,0 +1,24 @@
+/**
+ * SVG is a document format, not a graphics format: it carries CSS, text layout, filters, masks and
+ * animation. Filters and masks are PIXEL operations, so no vector backend can express them - which is
+ * why every complete SVG renderer owns a rasterizer, and why every PDF library ships a subset instead.
+ *
+ * We ship a subset too. The difference is what happens at its edge: an element we cannot draw is a
+ * NAMED ERROR, never a silent skip. Two reasons, and the second is the important one.
+ *
+ * 1. A silently dropped element leaves a logo that renders and is quietly wrong - the fill missing,
+ *    the icon half there - and nobody finds out. (react-pdf skips, and its `<style>` handling loses
+ *    every fill of an Illustrator export made with the default "Internal CSS" option.)
+ * 2. It keeps every later stage a MINOR. Supporting something new turns an error into a picture, which
+ *    can never break a document that worked. Going the other way - from silently skipping to drawing -
+ *    would change existing output.
+ */
+/** An element or attribute value we deliberately do not support yet. */
+export declare class SvgUnsupportedError extends Error {
+    readonly feature: string;
+    constructor(feature: string, hint: string);
+}
+/** The file is not SVG we can read at all - malformed, or with no root `<svg>`. */
+export declare class SvgParseError extends Error {
+    constructor(message: string);
+}

package/dist/svg/errors.js

@@ -0,0 +1,30 @@
+/**
+ * SVG is a document format, not a graphics format: it carries CSS, text layout, filters, masks and
+ * animation. Filters and masks are PIXEL operations, so no vector backend can express them - which is
+ * why every complete SVG renderer owns a rasterizer, and why every PDF library ships a subset instead.
+ *
+ * We ship a subset too. The difference is what happens at its edge: an element we cannot draw is a
+ * NAMED ERROR, never a silent skip. Two reasons, and the second is the important one.
+ *
+ * 1. A silently dropped element leaves a logo that renders and is quietly wrong - the fill missing,
+ *    the icon half there - and nobody finds out. (react-pdf skips, and its `<style>` handling loses
+ *    every fill of an Illustrator export made with the default "Internal CSS" option.)
+ * 2. It keeps every later stage a MINOR. Supporting something new turns an error into a picture, which
+ *    can never break a document that worked. Going the other way - from silently skipping to drawing -
+ *    would change existing output.
+ */
+/** An element or attribute value we deliberately do not support yet. */
+export class SvgUnsupportedError extends Error {
+    constructor(feature, hint) {
+        super(`@jasy/pdf: ${feature} is not supported yet. ${hint}`);
+        this.feature = feature;
+        this.name = "SvgUnsupportedError";
+    }
+}
+/** The file is not SVG we can read at all - malformed, or with no root `<svg>`. */
+export class SvgParseError extends Error {
+    constructor(message) {
+        super(`@jasy/pdf: ${message}`);
+        this.name = "SvgParseError";
+    }
+}

package/dist/svg/gradients.d.ts

@@ -0,0 +1,34 @@
+import type { Gradient, GradientStop, PathCommand } from "../ir/display-list.js";
+import { type Attributes } from "./style.js";
+import type { XmlNode } from "./xml.js";
+/**
+ * `<linearGradient>` and `<radialGradient>`.
+ *
+ * The backend has painted shadings since colour emoji, and `Box({ bg: linearGradient(...) })` uses
+ * the same node - so this file only has to turn a `url(#id)` reference into that node. Two things
+ * make it more than a lookup:
+ *
+ * - **`gradientUnits` defaults to `objectBoundingBox`**, i.e. the coordinates are fractions of the
+ *   SHAPE's bounding box, not of the page. So a gradient cannot be resolved where it is defined,
+ *   only where it is used - which is why this takes the shape's commands.
+ * - **`href` chains.** Illustrator emits one gradient with the stops and a second that references it
+ *   and only moves the coordinates. Missing that leaves a shape with no stops at all.
+ */
+export interface GradientDef {
+    kind: "linear" | "radial";
+    attributes: Attributes;
+    stops: GradientStop[];
+    /** The `stop-opacity` of each stop, in the same order. */
+    opacities: number[];
+    /** The id this definition inherits from (`href` / `xlink:href`), without the `#`. */
+    href?: string;
+}
+/** Every gradient definition in the document, by id - they are referenced, not drawn in place. */
+export declare function gradientsOf(node: XmlNode, into?: Map<string, GradientDef>, depth?: number): Map<string, GradientDef>;
+/**
+ * Resolves a reference into an IR gradient positioned on `commands`.
+ *
+ * The anchors are mapped into the shape's own space, then through `gradientTransform` - so they end
+ * up in the SAME coordinates as the path, which is what the backend and the Y-flip both assume.
+ */
+export declare function resolveSvgGradient(def: GradientDef, defs: ReadonlyMap<string, GradientDef>, commands: readonly PathCommand[]): Gradient;

package/dist/svg/gradients.js

@@ -0,0 +1,156 @@
+import { Color } from "../common/color.js";
+import { SvgUnsupportedError } from "./errors.js";
+import { IDENTITY, isIdentity, parseTransform } from "./transform.js";
+import { svgColor } from "./style.js";
+import { boundsOf } from "../vector/path.js";
+import { ratio } from "./units.js";
+const localName = (tagName) => {
+    const colon = tagName.indexOf(":");
+    return colon === -1 ? tagName : tagName.slice(colon + 1);
+};
+const num = (value, fallback) => {
+    if (value === undefined)
+        return fallback;
+    const n = Number.parseFloat(value);
+    if (!Number.isFinite(n))
+        return fallback;
+    return value.trim().endsWith("%") ? n / 100 : n;
+};
+/** One `<stop>`, plus its own opacity - which is kept apart because only a UNIFORM one survives. */
+function readStop(element) {
+    const attributes = element.attributes;
+    const style = {};
+    for (const declaration of (attributes["style"] ?? "").split(";")) {
+        const colon = declaration.indexOf(":");
+        if (colon !== -1)
+            style[declaration.slice(0, colon).trim()] = declaration.slice(colon + 1).trim();
+    }
+    const read = (name) => style[name] ?? attributes[name];
+    const opacity = ratio(read("stop-opacity"));
+    const colorText = read("stop-color") ?? "#000000";
+    return {
+        stop: {
+            // Both are clamped: a PDF stitching function needs its bounds inside [0,1] and increasing, so
+            // a malformed file must not be able to produce one that a reader rejects.
+            offset: Math.max(0, Math.min(1, num(read("offset"), 0))),
+            color: colorText === "currentColor" ? new Color(0, 0, 0) : svgColor(colorText),
+        },
+        opacity,
+    };
+}
+/** Every gradient definition in the document, by id - they are referenced, not drawn in place. */
+export function gradientsOf(node, into = new Map(), depth = 0) {
+    // Bounded like the walk in `index.ts`: this recurses, and a pathological file must not blow the
+    // call stack with a raw RangeError.
+    if (node.type !== "element" || depth > 256)
+        return into;
+    const name = localName(node.tagName);
+    if (name === "linearGradient" || name === "radialGradient") {
+        const id = node.attributes["id"];
+        if (id !== undefined) {
+            const href = node.attributes["href"] ?? node.attributes["xlink:href"];
+            const read = node.children
+                .filter((c) => c.type === "element" && localName(c.tagName) === "stop")
+                .map(readStop);
+            into.set(id, {
+                kind: name === "linearGradient" ? "linear" : "radial",
+                attributes: node.attributes,
+                stops: read.map((r) => r.stop),
+                opacities: read.map((r) => r.opacity),
+                href: href?.startsWith("#") ? href.slice(1) : undefined,
+            });
+        }
+        return into;
+    }
+    for (const child of node.children)
+        gradientsOf(child, into, depth + 1);
+    return into;
+}
+/** Walks the `href` chain: the nearest definition wins for each attribute, stops come from the first
+ *  ancestor that has any. A cycle stops the walk rather than hanging. */
+function inherited(def, defs) {
+    const attributes = {};
+    let stops = [];
+    let opacities = [];
+    const seen = new Set();
+    let current = def;
+    while (current && !seen.has(current)) {
+        seen.add(current);
+        for (const [key, value] of Object.entries(current.attributes)) {
+            if (attributes[key] === undefined)
+                attributes[key] = value;
+        }
+        if (stops.length === 0) {
+            stops = current.stops;
+            opacities = current.opacities;
+        }
+        current = current.href === undefined ? undefined : defs.get(current.href);
+    }
+    return { attributes, stops, opacities };
+}
+const SPREAD = {
+    pad: "pad",
+    repeat: "repeat",
+    reflect: "reflect",
+};
+/**
+ * Resolves a reference into an IR gradient positioned on `commands`.
+ *
+ * The anchors are mapped into the shape's own space, then through `gradientTransform` - so they end
+ * up in the SAME coordinates as the path, which is what the backend and the Y-flip both assume.
+ */
+export function resolveSvgGradient(def, defs, commands) {
+    const { attributes, stops, opacities } = inherited(def, defs);
+    if (stops.length === 0) {
+        throw new SvgUnsupportedError("a gradient with no <stop> of its own or inherited", "Add stops, or replace the fill with a solid colour.");
+    }
+    // A PDF shading is DeviceRGB and has no alpha channel. One opacity across all stops IS
+    // expressible - it is just the shape's fill alpha - and 87 of the 125 real files that use
+    // `stop-opacity` at all are that case. Stops with DIFFERENT opacities would need a soft-mask
+    // luminosity group, so that stays named rather than drawn opaque.
+    const alpha = opacities[0] ?? 1;
+    if (opacities.some((o) => o !== alpha)) {
+        throw new SvgUnsupportedError("a gradient whose stops have DIFFERENT stop-opacity values", "A PDF shading has no alpha channel; only one opacity for the whole gradient is expressible.");
+    }
+    // SVG says an offset lower than the one before it is raised to match; a decreasing pair would
+    // otherwise become an invalid Domain in the shading function.
+    let previous = 0;
+    for (const stop of stops) {
+        stop.offset = previous = Math.max(previous, stop.offset);
+    }
+    const box = boundsOf(commands);
+    const onBox = (attributes["gradientUnits"] ?? "objectBoundingBox") === "objectBoundingBox";
+    // In objectBoundingBox units every coordinate is a FRACTION of the shape's box.
+    const px = (v) => (onBox ? box.x + v * box.width : v);
+    const py = (v) => (onBox ? box.y + v * box.height : v);
+    // A radius in box units is a fraction of the box's diagonal-ish size, per the SVG formula.
+    const pr = (v) => (onBox ? v * Math.sqrt((box.width ** 2 + box.height ** 2) / 2) : v);
+    const matrix = attributes["gradientTransform"]
+        ? parseTransform(attributes["gradientTransform"])
+        : IDENTITY;
+    const skewed = !isIdentity(matrix) && (matrix[1] !== 0 || matrix[2] !== 0 || matrix[0] !== matrix[3]);
+    const point = (x, y) => [
+        matrix[0] * x + matrix[2] * y + matrix[4],
+        matrix[1] * x + matrix[3] * y + matrix[5],
+    ];
+    const scale = Math.abs(matrix[0]);
+    const extend = SPREAD[attributes["spreadMethod"] ?? "pad"] ?? "pad";
+    if (def.kind === "linear") {
+        // Both anchors go through the transform, so a rotation or a shear lands correctly by itself.
+        const [x0, y0] = point(px(num(attributes["x1"], 0)), py(num(attributes["y1"], 0)));
+        const [x1, y1] = point(px(num(attributes["x2"], 1)), py(num(attributes["y2"], 0)));
+        return { type: "linear", x0, y0, x1, y1, stops, extend, alpha };
+    }
+    if (skewed) {
+        // A sheared or non-uniformly scaled radial gradient is an ELLIPSE. PDF's radial shading is
+        // circles only, so it cannot be expressed - naming it beats drawing a different shape.
+        throw new SvgUnsupportedError(`a radial gradient with gradientTransform="${attributes["gradientTransform"]}"`, "A non-uniform transform makes it elliptical, which a PDF shading cannot express.");
+    }
+    const cx = px(num(attributes["cx"], 0.5));
+    const cy = py(num(attributes["cy"], 0.5));
+    const r = pr(num(attributes["r"], 0.5)) * scale;
+    // The focal point defaults to the centre; it is where the gradient starts, at radius 0.
+    const [fx, fy] = point(attributes["fx"] === undefined ? cx : px(num(attributes["fx"], 0.5)), attributes["fy"] === undefined ? cy : py(num(attributes["fy"], 0.5)));
+    const [ox, oy] = point(cx, cy);
+    return { type: "radial", x0: fx, y0: fy, r0: 0, x1: ox, y1: oy, r1: r, stops, extend, alpha };
+}

package/dist/svg/index.d.ts

@@ -0,0 +1,22 @@
+import type { IRNode } from "../ir/display-list.js";
+export { SvgParseError, SvgUnsupportedError } from "./errors.js";
+/** Where the drawing goes on the page, in engine (top-left) points. */
+export interface SvgTarget {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** The intrinsic size of an SVG: its `width`/`height`, else its `viewBox`. */
+export interface SvgSize {
+    width: number;
+    height: number;
+}
+/** The intrinsic size, for sizing an `<Image>` that gives only one dimension (or none). */
+export declare function svgSize(source: string): SvgSize;
+/**
+ * An SVG document as display-list nodes, placed in `target`. Coordinates stay in the SVG's own user
+ * space and the mapping rides in the graphics state, so a stroke scales with the drawing - which is
+ * what SVG specifies and what a flattened implementation gets wrong.
+ */
+export declare function svgToIr(source: string, target: SvgTarget): IRNode[];