@jasy/pdf 1.0.0-alpha.6 → 1.0.0-alpha.8

package/dist/utils/ttf-parser.js

@@ -3,6 +3,21 @@
 // text width the same way AFMParser does for the standard-14. Embedding/subsetting come later.
 import { i16, latin1FromBytes, u8, u16, u32 } from "./bytes.js";
 const IDENTITY = [1, 0, 0, 1, 0, 0];
+/** Sorts x-intervals and unions the overlapping ones. */
+export function mergeSpans(spans) {
+    if (spans.length === 0)
+        return spans;
+    const sorted = [...spans].sort((a, b) => a[0] - b[0]);
+    const out = [sorted[0]];
+    for (const [start, end] of sorted.slice(1)) {
+        const last = out[out.length - 1];
+        if (start <= last[1])
+            last[1] = Math.max(last[1], end);
+        else
+            out.push([start, end]);
+    }
+    return out;
+}
 function isIdentity(m) {
     return m[0] === 1 && m[1] === 0 && m[2] === 0 && m[3] === 1 && m[4] === 0 && m[5] === 0;
 }
@@ -37,6 +52,15 @@ export class TTFParser {
         // FontDescriptor metrics, in PDF glyph space (1000 units / em).
         this.ascent = 0;
         this.descent = 0;
+        // Extra leading the font asks for between two lines (hhea), same glyph space. Often 0.
+        this.lineGap = 0;
+        // Decoration metrics in RAW font units (divide by unitsPerEm). `post` always carries the underline
+        // pair; `OS/2` only carries sxHeight/sCapHeight from version 2 on, so those may stay 0 and are
+        // then measured off the glyph outlines instead (see `decoration()`).
+        this.underlinePositionRaw = 0; // negative = below the baseline
+        this.underlineThicknessRaw = 0;
+        this.xHeightRaw = 0;
+        this.capHeightRaw = 0;
         this.bbox = [0, 0, 0, 0];
         this.numGlyphs = 0;
         this.numHMetrics = 0;
@@ -53,6 +77,16 @@ export class TTFParser {
         // COLR v1: base glyph id → the absolute offset of its Paint table (a recursive paint graph).
         this.colrBaseV1 = new Map();
         this.colrLayerListOffset = 0; // absolute offset of the v1 LayerList (paint-offset array)
+        // Kerning: (leftGid << 16 | rightGid) -> value in FONT UNITS (from the `kern` table and/or GPOS).
+        this.kernPairs = new Map();
+        this.hasKerning = false;
+        // GPOS Type 2 (pair positioning) subtables, in absolute byte offsets. Queried per pair (format 2
+        // is class-based, so it cannot be enumerated into `kernPairs` up front). Preferred over `kern`.
+        this.gposPairPos = [];
+        // Memoised getKerning results, keyed (leftGid << 16 | rightGid) -> em/1000. A GPOS lookup walks
+        // subtables (coverage + classDef) per pair, and a long document repeats the same pairs thousands
+        // of times, so the first lookup of a pair pays; the rest are O(1).
+        this.kernCache = new Map();
         this.readTableDirectory();
         const head = this.table("head").offset;
         this.unitsPerEm = u16(this.data, head + 18);
@@ -67,6 +101,8 @@ export class TTFParser {
         const hhea = this.table("hhea").offset;
         this.ascent = this.toGlyphSpace(i16(this.data, hhea + 4));
         this.descent = this.toGlyphSpace(i16(this.data, hhea + 6));
+        this.lineGap = this.toGlyphSpace(i16(this.data, hhea + 8));
+        this.readDecorationMetrics();
         this.indexToLocFormat = i16(this.data, head + 50);
         this.readHmtx();
         this.readCmap();
@@ -74,6 +110,19 @@ export class TTFParser {
             this.readColr();
             this.readCpal();
         }
+        // Kerning tables are optional and only ever make text prettier; a malformed one must degrade to
+        // "no kerning", never break font loading. Guard both.
+        try {
+            if (this.tables["kern"])
+                this.readKern();
+            if (this.tables["GPOS"])
+                this.readGpos();
+        }
+        catch {
+            this.kernPairs.clear();
+            this.gposPairPos = [];
+            this.hasKerning = false;
+        }
     }
     // The raw font bytes, for the /FontFile2 stream.
     getData() {
@@ -131,6 +180,325 @@ export class TTFParser {
             width += this.getCharWidth(ch, fontSize);
         return width;
     }
+    // `post` carries the underline pair (always, from its header); `OS/2` carries the x- and cap-height
+    // but only from version 2 on. Both tables are optional in principle, so nothing here may throw.
+    readDecorationMetrics() {
+        const post = this.tables["post"];
+        if (post) {
+            this.underlinePositionRaw = i16(this.data, post.offset + 8);
+            this.underlineThicknessRaw = i16(this.data, post.offset + 10);
+        }
+        const os2 = this.tables["OS/2"];
+        if (os2 && u16(this.data, os2.offset) >= 2) {
+            this.xHeightRaw = i16(this.data, os2.offset + 86);
+            this.capHeightRaw = i16(this.data, os2.offset + 88);
+        }
+    }
+    /**
+     * Underline / strikethrough geometry, as fractions of the em.
+     *
+     * A font without `post` (rare) gets the classic 10% below the baseline at 5% thickness - the same
+     * numbers all 14 standard AFMs happen to declare, so it is a measured convention rather than an
+     * invention. A font whose `OS/2` predates version 2 has no x- or cap-height, so we MEASURE them off
+     * the outlines of `x` and `H` instead of guessing.
+     */
+    decoration() {
+        if (this.cachedDecoration)
+            return this.cachedDecoration;
+        const em = this.unitsPerEm;
+        const xHeight = this.xHeightRaw || this.outlineTop(0x78); // "x"
+        const capHeight = this.capHeightRaw || this.outlineTop(0x48); // "H"
+        this.cachedDecoration = {
+            underlinePosition: this.underlinePositionRaw ? -this.underlinePositionRaw / em : 0.1,
+            underlineThickness: this.underlineThicknessRaw ? this.underlineThicknessRaw / em : 0.05,
+            xHeight: xHeight / em,
+            capHeight: capHeight / em,
+        };
+        return this.cachedDecoration;
+    }
+    /** The highest ON-CURVE point of a code point's outline, in font units; 0 for a missing glyph.
+     *  A quadratic's control point may sit above the curve, so it is not a bound - and `x`/`H` have
+     *  flat tops in any face where this fallback matters. */
+    outlineTop(codePoint) {
+        let top = 0;
+        for (const cmd of this.getGlyphPath(this.getGlyphIndex(codePoint))) {
+            if (cmd.type !== "Z" && cmd.y > top)
+                top = cmd.y;
+        }
+        return top;
+    }
+    /**
+     * Where a glyph's INK crosses a horizontal band, as x-intervals in font units (pen origin at 0).
+     * This is what lets an underline step around a descender ("skip-ink"), the way a browser does.
+     *
+     * Scanline fill: sample a few horizontal lines across the band, find every place the outline
+     * crosses them, and pair the crossings up into filled spans. A handful of scanlines is plenty -
+     * the band is a few percent of the em tall, and a descender stem does not wander inside it.
+     *
+     * `yTop` / `yBottom` are in font units, y UP from the baseline (so both are negative under it).
+     * Returns [] for a glyph with no outline (a space, an unmapped code point, a composite we cannot
+     * decompose) - the caller then leaves the line unbroken there, which is the safe direction.
+     */
+    inkSpansInBand(codePoint, yTop, yBottom) {
+        const path = this.getGlyphPath(this.getGlyphIndex(codePoint));
+        if (path.length === 0)
+            return [];
+        // Flatten to straight edges; a quadratic becomes a short polyline (the band is thin, so a
+        // coarse subdivision is already below the printing resolution).
+        const edges = [];
+        let startX = 0;
+        let startY = 0;
+        let curX = 0;
+        let curY = 0;
+        const edge = (x, y) => {
+            edges.push([curX, curY, x, y]);
+            curX = x;
+            curY = y;
+        };
+        for (const cmd of path) {
+            if (cmd.type === "M") {
+                [curX, curY] = [cmd.x, cmd.y];
+                [startX, startY] = [cmd.x, cmd.y];
+            }
+            else if (cmd.type === "L") {
+                edge(cmd.x, cmd.y);
+            }
+            else if (cmd.type === "Q") {
+                const [x0, y0] = [curX, curY];
+                const STEPS = 8;
+                for (let i = 1; i <= STEPS; i++) {
+                    const t = i / STEPS;
+                    const u = 1 - t;
+                    edge(u * u * x0 + 2 * u * t * cmd.cx + t * t * cmd.x, u * u * y0 + 2 * u * t * cmd.cy + t * t * cmd.y);
+                }
+            }
+            else {
+                edge(startX, startY); // Z: close the contour
+            }
+        }
+        const SCANLINES = 5;
+        const spans = [];
+        for (let i = 0; i < SCANLINES; i++) {
+            const y = yTop + ((yBottom - yTop) * i) / (SCANLINES - 1);
+            const xs = [];
+            for (const [x0, y0, x1, y1] of edges) {
+                if (y0 === y1)
+                    continue;
+                // Half-open test so a vertex on the scanline is counted exactly once.
+                if (y >= Math.min(y0, y1) && y < Math.max(y0, y1)) {
+                    xs.push(x0 + ((y - y0) / (y1 - y0)) * (x1 - x0));
+                }
+            }
+            xs.sort((a, b) => a - b);
+            for (let k = 0; k + 1 < xs.length; k += 2)
+                spans.push([xs[k], xs[k + 1]]);
+        }
+        return mergeSpans(spans);
+    }
+    /** True if the font declares any horizontal kerning (kern table or GPOS). */
+    kerns() {
+        return this.hasKerning;
+    }
+    /** Kerning between two glyphs, in em/1000 (the standard-14 unit); 0 if the pair is not kerned.
+     *  Negative tightens, matching the AFM sign. GPOS wins over the legacy `kern` table when both
+     *  exist (it is what a modern shaper uses, and can carry more pairs). */
+    getKerning(leftGid, rightGid) {
+        const key = (leftGid << 16) | rightGid;
+        const cached = this.kernCache.get(key);
+        if (cached !== undefined)
+            return cached;
+        let units;
+        if (this.gposPairPos.length > 0)
+            units = this.gposKern(leftGid, rightGid);
+        if (units === undefined)
+            units = this.kernPairs.get(key);
+        const em = units === undefined ? 0 : Math.round((units * 1000) / this.unitsPerEm);
+        this.kernCache.set(key, em);
+        return em;
+    }
+    // The legacy `kern` table, format 0 (an explicit list of glyph-pair adjustments). Only horizontal
+    // format-0 subtables are read; GPOS (parsed separately) supersedes this in modern fonts, but old
+    // TrueType (DejaVu, FreeSans) carries its kerning here.
+    readKern() {
+        const base = this.tables["kern"].offset;
+        // The OpenType (Microsoft) header is version:u16 = 0, nTables:u16. (Apple's is a u32 version; the
+        // fonts we target use the OpenType form.)
+        if (u16(this.data, base) !== 0)
+            return;
+        const nTables = u16(this.data, base + 2);
+        let p = base + 4;
+        for (let t = 0; t < nTables; t++) {
+            const length = u16(this.data, p + 2);
+            const coverage = u16(this.data, p + 4);
+            const format = coverage >> 8;
+            const horizontal = (coverage & 0x1) === 1;
+            if (format === 0 && horizontal) {
+                const nPairs = u16(this.data, p + 6);
+                let q = p + 14; // past nPairs, searchRange, entrySelector, rangeShift
+                for (let i = 0; i < nPairs; i++) {
+                    const left = u16(this.data, q);
+                    const right = u16(this.data, q + 2);
+                    const value = i16(this.data, q + 4);
+                    this.kernPairs.set((left << 16) | right, value);
+                    q += 6;
+                }
+            }
+            p += length;
+        }
+        if (this.kernPairs.size > 0)
+            this.hasKerning = true;
+    }
+    // GPOS pair-adjustment kerning. We collect the PairPos (lookup type 2) subtables of the `kern`
+    // FEATURE only - not every pair-positioning lookup - so this is kerning, not arbitrary shaping.
+    // Script/language selection is skipped: the `kern` feature is the same across the Latin scripts we
+    // target, so a flat scan of the feature list for tag "kern" is correct here. Only pair positioning
+    // (type 2) is read; the rest of GPOS (mark attachment, cursive, contextual) is not kerning.
+    readGpos() {
+        const base = this.tables["GPOS"].offset;
+        const featureListOffset = base + u16(this.data, base + 6);
+        const lookupListOffset = base + u16(this.data, base + 8);
+        // Every lookup index referenced by a "kern" feature.
+        const kernLookups = new Set();
+        const featureCount = u16(this.data, featureListOffset);
+        for (let i = 0; i < featureCount; i++) {
+            const rec = featureListOffset + 2 + i * 6;
+            const tag = String.fromCharCode(this.data[rec], this.data[rec + 1], this.data[rec + 2], this.data[rec + 3]);
+            if (tag !== "kern")
+                continue;
+            const feature = featureListOffset + u16(this.data, rec + 4);
+            const lookupIndexCount = u16(this.data, feature + 2);
+            for (let j = 0; j < lookupIndexCount; j++) {
+                kernLookups.add(u16(this.data, feature + 4 + j * 2));
+            }
+        }
+        if (kernLookups.size === 0)
+            return;
+        // The PairPos subtables of those lookups (a lookup of another type in the set is ignored).
+        const lookupCount = u16(this.data, lookupListOffset);
+        for (const idx of kernLookups) {
+            if (idx >= lookupCount)
+                continue;
+            const lookup = lookupListOffset + u16(this.data, lookupListOffset + 2 + idx * 2);
+            if (u16(this.data, lookup) !== 2)
+                continue; // lookupType 2 = pair adjustment
+            const subTableCount = u16(this.data, lookup + 4);
+            for (let s = 0; s < subTableCount; s++) {
+                this.gposPairPos.push(lookup + u16(this.data, lookup + 6 + s * 2));
+            }
+        }
+        if (this.gposPairPos.length > 0)
+            this.hasKerning = true;
+    }
+    // The XAdvance adjustment on the LEFT glyph for a pair, in font units, from the first PairPos
+    // subtable that covers it; undefined if none does. (Kerning only ever uses value1's XAdvance.)
+    gposKern(leftGid, rightGid) {
+        for (const sub of this.gposPairPos) {
+            const posFormat = u16(this.data, sub);
+            const coverage = sub + u16(this.data, sub + 2);
+            const covIndex = this.coverageIndex(coverage, leftGid);
+            if (covIndex < 0)
+                continue;
+            const valueFormat1 = u16(this.data, sub + 4);
+            const valueFormat2 = u16(this.data, sub + 6);
+            const v1size = TTFParser.valueRecordSize(valueFormat1);
+            const v2size = TTFParser.valueRecordSize(valueFormat2);
+            if (posFormat === 1) {
+                const pairSet = sub + u16(this.data, sub + 10 + covIndex * 2);
+                const pairValueCount = u16(this.data, pairSet);
+                const recSize = 2 + v1size + v2size;
+                for (let i = 0; i < pairValueCount; i++) {
+                    const rec = pairSet + 2 + i * recSize;
+                    if (u16(this.data, rec) === rightGid) {
+                        return this.xAdvance(rec + 2, valueFormat1);
+                    }
+                }
+            }
+            else if (posFormat === 2) {
+                const classDef1 = sub + u16(this.data, sub + 8);
+                const classDef2 = sub + u16(this.data, sub + 10);
+                const class2Count = u16(this.data, sub + 14);
+                const c1 = this.classOf(classDef1, leftGid);
+                const c2 = this.classOf(classDef2, rightGid);
+                const recSize = v1size + v2size;
+                const record = sub + 16 + (c1 * class2Count + c2) * recSize;
+                return this.xAdvance(record, valueFormat1);
+            }
+        }
+        return undefined;
+    }
+    static valueRecordSize(valueFormat) {
+        let bits = 0;
+        for (let m = valueFormat; m; m >>= 1)
+            bits += m & 1;
+        return bits * 2;
+    }
+    // The XAdvance field of a GPOS value record, or 0 if the format has none. XAdvance (bit 0x0004) is
+    // preceded by XPlacement (0x0001) and YPlacement (0x0002), each an i16 when present.
+    xAdvance(recordOffset, valueFormat) {
+        if ((valueFormat & 0x0004) === 0)
+            return 0;
+        let off = recordOffset;
+        if (valueFormat & 0x0001)
+            off += 2;
+        if (valueFormat & 0x0002)
+            off += 2;
+        return i16(this.data, off);
+    }
+    // Coverage index of a glyph, or -1. Format 1: sorted glyph list. Format 2: sorted ranges.
+    coverageIndex(offset, gid) {
+        const format = u16(this.data, offset);
+        if (format === 1) {
+            const count = u16(this.data, offset + 2);
+            let lo = 0;
+            let hi = count - 1;
+            while (lo <= hi) {
+                const mid = (lo + hi) >> 1;
+                const g = u16(this.data, offset + 4 + mid * 2);
+                if (gid < g)
+                    hi = mid - 1;
+                else if (gid > g)
+                    lo = mid + 1;
+                else
+                    return mid;
+            }
+            return -1;
+        }
+        if (format === 2) {
+            const rangeCount = u16(this.data, offset + 2);
+            for (let i = 0; i < rangeCount; i++) {
+                const rec = offset + 4 + i * 6;
+                const start = u16(this.data, rec);
+                const end = u16(this.data, rec + 2);
+                if (gid >= start && gid <= end)
+                    return u16(this.data, rec + 4) + (gid - start);
+            }
+        }
+        return -1;
+    }
+    // Class of a glyph in a ClassDef, or 0 (the default class). Format 1: run from a start glyph.
+    // Format 2: ranges. Glyphs not listed are class 0.
+    classOf(offset, gid) {
+        const format = u16(this.data, offset);
+        if (format === 1) {
+            const startGlyph = u16(this.data, offset + 2);
+            const glyphCount = u16(this.data, offset + 4);
+            if (gid >= startGlyph && gid < startGlyph + glyphCount) {
+                return u16(this.data, offset + 6 + (gid - startGlyph) * 2);
+            }
+            return 0;
+        }
+        if (format === 2) {
+            const rangeCount = u16(this.data, offset + 2);
+            for (let i = 0; i < rangeCount; i++) {
+                const rec = offset + 4 + i * 6;
+                const start = u16(this.data, rec);
+                const end = u16(this.data, rec + 2);
+                if (gid >= start && gid <= end)
+                    return u16(this.data, rec + 4);
+            }
+        }
+        return 0;
+    }
     table(tag) {
         const t = this.tables[tag];
         if (!t)

package/dist/validators/element-validator.js

@@ -41,9 +41,13 @@ export class Validator {
         }
     }
     static validateFlexElement(element) {
-        // Ensure flexible elements have valid flex values
-        if (element.getFlex() <= 0) {
-            throw new Error(`Flexible element ${element.constructor.name} has invalid flex value`);
+        // Ensure flexible elements have valid flex values. The message names what the CALLER wrote, not the
+        // element class: `Spacer` and `Expanded` are what exists in their document, `ExpandedElement` is not.
+        const flex = element.getFlex();
+        if (flex <= 0) {
+            throw new Error(`@jasy/pdf: Spacer/Expanded needs a flex above 0, got ${flex}. Flex is a SHARE of the leftover ` +
+                "space, so 0 would claim none - which is what leaving the element out does. For a fixed gap " +
+                "use the `gap` of the surrounding Column or Row, or a Box with a height.");
         }
         // Ensure a flexible element does not contain another flexible element
         if (hasChildProp(element)) {

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "@jasy/pdf",
-  "version": "1.0.0-alpha.6",
+  "version": "1.0.0-alpha.8",
   "description": "Declarative, component-based PDF generation in pure TypeScript - Flutter-style components, real AFM font metrics, a hand-rolled PDF writer. No headless browser, no Java.",
   "keywords": [
     "declarative",
+    "e-invoice",
     "factur-x",
     "invoice",
     "layout",
@@ -12,6 +13,7 @@
     "pdf-a",
     "pdf-generation",
     "typescript",
+    "xrechnung",
     "zugferd"
   ],
   "license": "MIT",
@@ -30,7 +32,12 @@
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
-    }
+    },
+    "./edit": {
+      "types": "./dist/edit/index.d.ts",
+      "default": "./dist/edit/index.js"
+    },
+    "./package.json": "./package.json"
   },
   "dependencies": {
     "fflate": "^0.8.3",