resvg-napi 0.1.2 → 0.2.0

package/README.md

@@ -1,5 +1,9 @@
 # resvg-napi
 
+[![npm](https://img.shields.io/npm/v/resvg-napi)](https://www.npmjs.com/package/resvg-napi)
+[![conformance](https://img.shields.io/badge/resvg%20conformance-1715%2F1715-brightgreen)](#conformance)
+[![licence](https://img.shields.io/npm/l/resvg-napi)](#licence)
+
 Node.js bindings for [resvg](https://github.com/linebender/resvg) 0.48: render
 SVG to PNG, and read back what usvg made of the document — the resolved tree,
 text metrics, paint, geometry.
@@ -45,10 +49,17 @@ one knows what it is:
 const n = doc.node('surname')
 n.kind           // 'group' | 'path' | 'image' | 'text'
 n.path()         // geometry, fill, stroke — null unless it is a shape
-n.text()         // chunks, layouted spans, positioned glyphs
+n.text()         // chunks, layouted spans, positioned glyphs, decoration
 n.renderPng()    // that element alone, cropped to its own extent
 ```
 
+A span carries what it is drawn with, down to the lines through it:
+
+```js
+const span = n.text().chunks[0].spans[0]
+span.decoration.underline?.fill?.paint  // …and .overline, .lineThrough
+```
+
 Paint is a discriminated union, so TypeScript narrows it:
 
 ```ts
@@ -64,7 +75,8 @@ that distinction bites.
 
 **Fonts.** `FontDatabase` is `fontdb` itself: `loadSystemFonts()`,
 `loadFontData(buffer)`, `loadFontFile(path)`, `faces()`, `query()`, and the
-generic-family setters. `pendingFonts()` on a parsed document names the
+generic-family setters. A face reports its `families`, `weight`, `style`
+(`'normal' | 'italic' | 'oblique'`) and whether it is `monospaced`. `pendingFonts()` on a parsed document names the
 families it wanted and did not get; `pendingImages()` does the same for hrefs.
 
 **Definitions.** `linearGradients()`, `radialGradients()`, `patterns()`,
@@ -75,6 +87,21 @@ Something missing? The generator keeps a report of every upstream member it
 left alone, with the reason. `RESVG_NAPI_CODEGEN_LOG=1 cargo build` prints it,
 and [CONTRIBUTING.md](CONTRIBUTING.md) explains what the reasons mean.
 
+## Conformance
+
+resvg's own test corpus, rendered through these bindings: **1715 of 1715 match**
+the reference PNGs upstream asserts on, within 1/255 per channel — a tolerance
+measured rather than chosen, with the reason recorded in
+[`scripts/conformance.mjs`](scripts/conformance.mjs).
+
+```bash
+npm run conformance:fetch   # the corpus, at the tag Cargo.toml pins
+npm run conformance         # 15 seconds including the fetch
+```
+
+CI runs it on every pull request, so a resvg bump that changes a render shows up
+as a diff rather than passing unnoticed.
+
 ## Platforms
 
 Thirteen targets.

package/fit.d.mts

@@ -0,0 +1,62 @@
+/**
+ * Horizontal text fitting, driven by `data-maxwidth`.
+ *
+ * Declarations for `fit.mjs`, which is JavaScript with JSDoc: written by hand,
+ * unlike `index.d.ts`, so they can drift. `npm run typecheck` reads them.
+ */
+
+/** A `Resvg` instance, however the caller chose to build one. */
+type Renderer = {
+  node(id: string): { extent(): { width: number } | null } | null
+}
+
+/** One element carrying a width constraint, and what is needed to rewrite it. */
+export interface WidthConstraint {
+  /** The element's opening tag, verbatim. */
+  tag: string
+  /** The tag name: `text`, `tspan`, ... */
+  name: string
+  /** The attribute text inside that tag, verbatim. */
+  attrs: string
+  /** The element's `id`, or null when it had none and one must be generated. */
+  id: string | null
+  /** The limit, in the document's own units -- not canvas pixels. */
+  max: number
+  /** Byte offset of the tag in the source string. */
+  index: number
+}
+
+/** One element that was compressed, and by how much. */
+export interface Adjustment {
+  id: string
+  /** Measured width before, in the document's units. */
+  from: number
+  /** The limit it was fitted to. */
+  to: number
+  /** The horizontal scale applied: `to / from`. */
+  factor: number
+  /** Measured width after, as a check on the one-pass assumption. */
+  measured: number
+}
+
+export interface FitResult {
+  /** The source, with a `scale(k 1)` composed onto each fitted element. */
+  svg: string
+  adjustments: Adjustment[]
+  /** Constraints that could not be honoured, each saying why. */
+  problems: string[]
+}
+
+/** Elements carrying a width constraint, with the tag text needed to rewrite it. */
+export function findWidthConstraints(svg: string): WidthConstraint[]
+
+/**
+ * Fits every `data-maxwidth` element by compressing it horizontally.
+ *
+ * @param svg     source, after any templating
+ * @param render  `(svg) => Resvg`; supply fonts and options here
+ */
+export function fitTextWidths(
+  svg: string,
+  render: (svg: string) => Renderer,
+): FitResult