svg-vectordrawable 0.1.1 → 0.2.0

package/README.md

@@ -12,7 +12,7 @@ npm i svg-vectordrawable
 
 ## Why another one?
 
-`svg2vectordrawable` is unmaintained (last release 2022), pins `svgo@2`, and ignores
+`svg2vectordrawable` is unmaintained (last release 2022), depends on `svgo@^2.8`, and ignores
 `gradientTransform` (Figma radial gradients render at the wrong place). This library is on
 `svgo@4`, bakes `gradientTransform` into the Android coordinates, and **fails loud** instead of
 emitting plausible‑but‑wrong output.
@@ -22,19 +22,74 @@ emitting plausible‑but‑wrong output.
 ```ts
 import { convert } from 'svg-vectordrawable';
 
-const { xml, warnings } = convert(svgString, {
+const { xml, warnings, minSdk } = convert(svgString, {
     optimize: true, // run svgo normalization first (recommended)
     currentColor: '#000', // value substituted for `currentColor`
     floatPrecision: 3,
     fillBlackForUnfilled: true, // unfilled paths get black (SVG default)
     xmlTag: false, // prepend <?xml ...?>
     tint: '#FFFFFFFF', // android:tint on <vector> (Android color literal)
-    strict: false, // throw on unsupported constructs instead of warning
+    strict: false, // true: throw on lossy and approximated output; 'lossy': only on lossy output
+    minSdk: 21, // warn (`min-sdk-exceeded`) when the output needs a higher API level
+    rules: {}, // per-code severity, overrides `strict` (see below)
     onWarn: (w) => console.warn(w.code, w.message),
 });
 ```
 
-`convert` is synchronous and returns `{ xml, warnings }`.
+`convert` is synchronous and returns `{ xml, warnings, minSdk }`. `minSdk` is the Android API level the
+output needs: 24 when it uses gradients or `fillType="evenOdd"`, otherwise 21.
+
+### Preview
+
+`vectorDrawableToSvg` turns a VectorDrawable back into SVG, to preview the result in a browser or a PR:
+
+```ts
+import { convert, vectorDrawableToSvg } from 'svg-vectordrawable';
+const preview = vectorDrawableToSvg(convert(svg).xml, { density: 2, applyTint: true });
+```
+
+### Warnings, errors and `rules`
+
+Every construct that cannot be converted faithfully emits a warning with a stable `code` (listed in
+the exported `WARNING_CODES`). Each code has a category (exported `WARNING_CATEGORIES`): **lossy**
+(content lost or wrong), **approximation** (rendering slightly differs) or **info** (Android lint
+style, API level). `strict: true` turns lossy and approximation warnings into errors, `strict: 'lossy'`
+only lossy ones; info warnings are never raised by `strict`. `rules` sets the severity per code
+(`'off' | 'warn' | 'error'`) and wins over `strict`. Errors are thrown as a
+`ConversionError` carrying the offending `warning`, so you can fall back (e.g. to a PNG):
+
+```ts
+import { convert, ConversionError } from 'svg-vectordrawable';
+
+try {
+    // Reject anything lossy, but accept approximated group opacity.
+    const { xml } = convert(svg, { strict: true, rules: { 'opacity-approximated': 'warn' } });
+} catch (err) {
+    if (err instanceof ConversionError) console.log('cannot convert:', err.warning.code);
+    else throw err;
+}
+```
+
+| Code                           | Meaning                                                                                      |
+| ------------------------------ | -------------------------------------------------------------------------------------------- |
+| `unsupported-element`          | `<text>`, `<image>`, `<foreignObject>`, `<switch>` — skipped                                 |
+| `unsupported-attribute`        | non-clip `mask`, `filter`, `marker*`, `vector-effect`, `paint-order`, `arcs` joins — ignored |
+| `unsupported-stroke-dasharray` | dash pattern that cannot be resolved (`em`/`ex` units) — drawn solid                         |
+| `unsupported-stroke-gradient`  | no longer emitted (gradient strokes are supported); kept for compatibility                   |
+| `unsupported-paint`            | `<pattern>` paint — fallback color or black                                                  |
+| `unsupported-style`            | CSS left in a `<style>` that could not be applied to elements — ignored                      |
+| `unsupported-clip-path`        | `objectBoundingBox` clip, evenodd clip with crossing contours, unconvertible content         |
+| `gradient-approximated`        | radial focal point; elliptical radial on a path that also has a solid stroke                 |
+| `opacity-approximated`         | opacity folded onto overlapping children / fill+stroke — overlaps look darker                |
+| `missing-gradient`             | `url(#id)` paint pointing at nothing, no fallback — black                                    |
+| `missing-clip-path`            | `clip-path` pointing at nothing — ignored                                                    |
+| `group-skew`                   | skewed `<g>` baked into path geometry                                                        |
+| `gradient-under-skew`          | gradient placement under a baked skew is approximate                                         |
+| `gradient-bbox-unavailable`    | `objectBoundingBox` gradient without a measurable path box                                   |
+| `empty-path`                   | shape without geometry — skipped                                                             |
+| `min-sdk-exceeded` (info)      | the output needs a higher API level than the `minSdk` option                                 |
+| `large-vector` (info)          | `android:width`/`height` above 200 dp (Android lint `VectorRaster`)                          |
+| `long-path-data` (info, off)   | a `pathData` longer than 800 characters (lint `VectorPath`); enable it with `rules`          |
 
 Node file helpers:
 
@@ -42,6 +97,7 @@ Node file helpers:
 import { convertFile, convertDir } from 'svg-vectordrawable';
 convertFile('icon.svg', 'res/drawable/icon.xml');
 convertDir('svg/', 'res/drawable/');
+convertDir('svg/', 'res/drawable/', {}, { androidNames: true }); // valid Android resource names
 ```
 
 ### CLI
@@ -53,6 +109,10 @@ svgvd icon.svg --stdout        # print to stdout
 svgvd -s '<svg>…</svg>'        # convert an inline SVG string
 svgvd icon.svg --xml-tag --tint '#FFFFFFFF'
 svgvd icon.svg --strict        # fail on anything not representable
+svgvd icon.svg --strict --rule opacity-approximated=warn   # per-code severity
+svgvd icon.svg --strict=lossy  # fail only when content would be lost
+svgvd icon.svg --min-sdk 21    # warn when the output needs a higher API level
+svgvd icons/ -o res/drawable/ --android-names   # Arrow-Left.svg → arrow_left.xml (valid resource names)
 ```
 
 ### Browser
@@ -65,39 +125,67 @@ import { convert } from 'svg-vectordrawable/browser';
 const { xml } = convert(svgString);
 ```
 
+`svg-vectordrawable/browser-lite` is the same API without svgo (116 KB instead of 1.1 MB for the
+IIFE build): conversion always runs with `optimize: false`, so `<style>` CSS is not inlined and
+shapes are converted as authored.
+
 ## What it handles
 
-| Feature                                                                                                                                  | Status     |
-| ---------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
-| Paths, `fill`, `stroke` (width/cap/join/miter), `fill-rule` → `fillType`                                                                 | ✅         |
-| Shapes (`rect`/`circle`/`ellipse`/`line`/`poly*`) → path                                                                                 | ✅         |
-| Colors: `#rgb[a]`, `#rrggbb[aa]`, `rgb()/rgba()`, `hsl()/hsla()`, named, `currentColor`                                                  | ✅         |
-| Attribute inheritance (incl. presentation attrs on the `<svg>` root and `<g>`)                                                           | ✅         |
-| Inline `style="…"` and `<style>` (via svgo)                                                                                              | ✅         |
-| Linear & radial **gradients**, `gradientTransform`, **`objectBoundingBox`** (via path bbox), `href` sharing, `spreadMethod` → `tileMode` | ✅         |
-| `<g transform>` → `<group>` (translate/rotate/scale); **skew/shear baked into geometry**                                                 | ✅         |
-| **`<use>` / `<symbol>`** references — inlined before conversion                                                                          | ✅         |
-| `clip-path` → `<clip-path>`                                                                                                              | ✅ (basic) |
-| `opacity` folded into `fillAlpha`/`strokeAlpha`                                                                                          | ✅         |
+| Feature                                                                                                                                                   | Status |
+| --------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ |
+| Paths, `fill`, `stroke` (width/cap/join/miter), `fill-rule` → `fillType`                                                                                  | ✅     |
+| Shapes (`rect`/`circle`/`ellipse`/`line`/`poly*`) → path                                                                                                  | ✅     |
+| Colors: `#rgb[a]`, `#rrggbb[aa]`, `rgb()/rgba()`, `hsl()/hsla()`, named, `currentColor`                                                                   | ✅     |
+| Attribute inheritance (incl. presentation attrs on the `<svg>` root and `<g>`)                                                                            | ✅     |
+| Inline `style="…"` and `<style>` (via svgo)                                                                                                               | ✅     |
+| Linear & radial **gradients**, `gradientTransform`, **`objectBoundingBox`** (via path bbox), `href` sharing, `spreadMethod` → `tileMode`                  | ✅     |
+| `<g transform>` → `<group>` (translate/rotate/scale); **skew/shear baked into geometry**                                                                  | ✅     |
+| **`<use>` / `<symbol>`** references — inlined before conversion                                                                                           | ✅     |
+| `clip-path` → `<clip-path>` (on shapes and `<g>`, incl. `<use>` / transformed clip content)                                                               | ✅     |
+| `opacity` folded into `fillAlpha`/`strokeAlpha` (root `<svg>` opacity → exact `android:alpha`)                                                            | ✅     |
+| `viewBox` origin, `preserveAspectRatio` (meet / slice / none), nested `<svg>`, `<a>`, `display` / `visibility`, units (`px`/`in`/`cm`/`mm`/`pt`/`pc`/`%`) | ✅     |
 
 ## Known limitations
 
 A VectorDrawable simply cannot represent some SVG features. These are **warned** (or throw in
 `strict` mode), never silently mis‑rendered:
 
-- `<mask>`, `<filter>`, `<pattern>`, `<image>`, `<text>` — not representable.
-- `stroke-dasharray` and gradient **strokes** — dropped (VectorDrawable supports neither).
+- `<filter>`, `<pattern>`, `<image>`, `<text>` — not representable. A `<mask>` is converted to a
+  `<clip-path>` when it is clip-equivalent (opaque white content, or opaque content with `mask-type: alpha`);
+  any other mask (gray, translucent, stroked, gradient…) is warned with the reason.
+- `stroke-dasharray` in font-relative units (`em`, `ex`) — the stroke is drawn solid. Other dash
+  patterns are baked into the path geometry (VectorDrawable has no native dashes).
+- Radial gradients are circles in VectorDrawable. Elliptical radials (non-uniform `gradientTransform`,
+  `objectBoundingBox` on a non-square shape) are made exact by drawing the fill inside a `<group>`
+  carrying the ellipse's deformation; they stay approximated only when the same path also has a solid
+  stroke (it would be distorted). Focal points (`fx`/`fy`) are approximated (`gradient-approximated`).
+- CSS that svgo cannot inline (`@media`, `:hover`, complex selectors) — `unsupported-style`.
 - `gradientUnits="objectBoundingBox"` is resolved from the path's bounding box; only when that box
   is unavailable does it fall back to the viewport (with a warning).
-- `clip-path` on a `<g>` (vs. on a drawable element) is not applied.
+- `filter`, `marker-*`, non-clip `mask` references and `clipPathUnits="objectBoundingBox"` — warned, not applied.
+- Group `opacity` has no VectorDrawable equivalent: it is folded onto each child, which is exact only
+  when the children do not overlap (`opacity-approximated` otherwise).
 
 ## Robustness
 
-Validated against ~10,700 real icons (Feather, Bootstrap Icons, Heroicons, Tabler) plus ~900
-Figma‑exported brand assets: 100% converted with the correct paint model (stroke icons stay
-strokes, filled icons stay fills). A sample (incl. gradients, `gradientTransform`, `objectBoundingBox`,
-`<use>`, sheared groups, clip-path) is **compiled with `aapt2`** — Android's own toolchain accepts
-the output — and a golden-snapshot suite locks the exact XML against regressions.
+- **Icon corpus in CI** (`scripts/corpus.mjs`): 9,251 icons (Feather, Bootstrap Icons, Heroicons,
+  Tabler, pinned versions) converted with and without svgo on every push — zero exceptions, zero
+  warnings required.
+- **Android toolchain**: the fixtures (gradients, `gradientTransform`, `objectBoundingBox`, `<use>`,
+  sheared groups, clip-path, nested transforms) are **compiled and linked with `aapt2`** against
+  `android.jar`, so attribute names and values are validated, not just XML well-formedness.
+- **Visual regression**: every fixture is rendered with resvg next to its VectorDrawable and must match
+  within 1% of inked pixels (`pnpm test:visual`).
+- **Android's own renderer**: the generated VectorDrawables are drawn by layoutlib (Android's Skia/hwui,
+  through Paparazzi on the JVM) and compared with the source SVG (`pnpm run validate:android`; needs a
+  full JDK 17+ and the Android SDK).
+- **Golden snapshots** lock the exact XML against regressions.
+
+## Documentation
+
+- [Migrating from `svg2vectordrawable`](docs/migration-from-svg2vectordrawable.md)
+- [Integrations](docs/integrations.md) (Node scripts, React Native icons, Gradle, Vite/webpack, CI)
+- [Comparison with `svg2vectordrawable` and Android Studio's Svg2Vector](docs/comparison.md)
 
 ## License
 

package/dist/browser-lite.d.ts

@@ -0,0 +1,162 @@
+import { Config } from 'svgo';
+
+/** Every warning code the converter can emit (stable, machine-readable). */
+declare const WARNING_CODES: readonly ["unsupported-element", "unsupported-attribute", "unsupported-stroke-dasharray", "unsupported-stroke-gradient", "unsupported-paint", "unsupported-clip-path", "missing-gradient", "missing-clip-path", "gradient-under-skew", "gradient-bbox-unavailable", "group-skew", "opacity-approximated", "gradient-approximated", "unsupported-style", "empty-path", "min-sdk-exceeded", "long-path-data", "large-vector"];
+/** Stable machine-readable warning codes. */
+type WarningCode = (typeof WARNING_CODES)[number];
+/**
+ * What a warning means for the output:
+ * - `lossy`: content is dropped or drawn wrong (an element, an attribute, a paint, a clip…);
+ * - `approximation`: everything is drawn, but the rendering differs slightly from the SVG;
+ * - `info`: the output is faithful; Android-side advice (API level, lint-style performance hints).
+ */
+type WarningCategory = 'lossy' | 'approximation' | 'info';
+/** The category of every warning code (see {@link WarningCategory}); drives the `strict` presets. */
+declare const WARNING_CATEGORIES: Readonly<Record<WarningCode, WarningCategory>>;
+/**
+ * `strict` presets: `true` turns every `lossy` and `approximation` warning into an error, `'lossy'`
+ * only the `lossy` ones. `info` codes are never escalated by `strict` (only by `rules`).
+ */
+type StrictMode = boolean | 'lossy';
+/** What to do with a warning: drop it, report it, or throw a `ConversionError`. */
+type Severity = 'off' | 'warn' | 'error';
+/** A non-fatal issue encountered during conversion. */
+interface Warning {
+    /** Stable machine-readable code, e.g. `unsupported-element`. */
+    code: WarningCode;
+    /** Human-readable explanation. */
+    message: string;
+    /** SVG element/attribute the warning relates to, when known. */
+    node?: string;
+}
+interface ConvertOptions {
+    /**
+     * Run svgo normalization first (inline styles, shapes→paths, bake transforms…).
+     * Strongly recommended; it is what makes conversion robust across SVG sources.
+     * @default true
+     */
+    optimize?: boolean;
+    /** Override the svgo config used for normalization (only when `optimize` is true). */
+    svgoConfig?: Config;
+    /** Decimal places kept for generated numbers (coordinates, radii). @default 3 */
+    floatPrecision?: number;
+    /** Concrete color substituted for `currentColor`. @default '#000000' */
+    currentColor?: string;
+    /**
+     * SVG paints unfilled shapes black by default. When true, paths without an
+     * explicit fill get `android:fillColor="#FF000000"`. @default true
+     */
+    fillBlackForUnfilled?: boolean;
+    /**
+     * Throw a `ConversionError` on the first warning of a category instead of reporting it:
+     * `true` for `lossy` and `approximation` codes, `'lossy'` for `lossy` codes only (see
+     * {@link WARNING_CATEGORIES}). `info` codes keep their default severity under any preset.
+     * @default false
+     */
+    strict?: StrictMode;
+    /**
+     * Per-code severity, overriding `strict` and the defaults. E.g.
+     * `{ strict: true, rules: { 'opacity-approximated': 'warn' } }` rejects anything lossy but
+     * tolerates approximated opacity; `{ rules: { 'long-path-data': 'warn' } }` enables that hint.
+     */
+    rules?: Partial<Record<WarningCode, Severity>>;
+    /** Indentation width (spaces). @default 4 */
+    indent?: number;
+    /** Prepend an XML declaration (`<?xml version="1.0" encoding="utf-8"?>`). @default false */
+    xmlTag?: boolean;
+    /** Add `android:tint` to the `<vector>`. Android color literal (e.g. `#AARRGGBB`), passed verbatim. */
+    tint?: string;
+    /** Called for every warning as it happens (in addition to the returned list). */
+    onWarn?: (warning: Warning) => void;
+    /**
+     * The app's `minSdk`: when the output needs a higher API level (see `ConvertResult.minSdk`),
+     * a `min-sdk-exceeded` warning names the features responsible. Unset: no check.
+     */
+    minSdk?: number;
+}
+interface ConvertResult {
+    /** The generated Android VectorDrawable XML. */
+    xml: string;
+    /** All non-fatal issues encountered. */
+    warnings: Warning[];
+    /**
+     * Lowest Android API level that renders the output natively: 24 when it uses gradients
+     * (`<aapt:attr>` complex colors) or `android:fillType`, otherwise 21 (VectorDrawable itself).
+     */
+    minSdk: number;
+}
+/** An RGBA color expressed as Android `#AARRGGBB`. */
+type AndroidColor = `#${string}`;
+
+/** Thrown when a warning's severity resolves to `'error'` (via `strict` or `rules`). */
+declare class ConversionError extends Error {
+    /** The warning that stopped the conversion. */
+    readonly warning: Warning;
+    constructor(warning: Warning);
+}
+
+/**
+ * VectorDrawable → SVG preview: re-serializes a VectorDrawable XML string into a standalone SVG string
+ * that renders the same picture, to preview a drawable in a browser, an image viewer or a PR review.
+ *
+ * Android semantics reproduced here (AndroidX `VectorDrawableCompat` / framework `VectorDrawable`):
+ * - `<vector>`: the viewport is stretched to width × height (no aspect preservation), `android:alpha`
+ *   applies to the whole drawing. `android:tint` / `android:tintMode` are ignored unless
+ *   {@link PreviewOptions.applyTint} is set (the default `src_in` mode recolors every pixel).
+ * - `<group>`: local matrix = T(translate + pivot) · R(rotation) · S(scale) · T(−pivot), i.e. Android
+ *   applies scale → rotate → translate around the pivot.
+ * - `<clip-path>`: clips every *subsequent* sibling of its group (and their descendants); several
+ *   clip-paths in a group, or nested groups, intersect. Clip paths use the non-zero rule.
+ * - `<path>`: no fill unless `fillColor`; no stroke unless `strokeColor` and `strokeWidth` > 0;
+ *   `fillAlpha` / `strokeAlpha` multiply the color alpha (or the gradient); defaults butt / miter / 4.
+ * - `<aapt:attr name="android:fillColor|strokeColor"><gradient>`: linear / radial gradients in the
+ *   path's coordinate space (= SVG `userSpaceOnUse`), `tileMode` clamp / repeated / mirror.
+ *
+ * Unsupported input throws an `Error` naming the construct: sweep gradients (no SVG equivalent),
+ * resource / theme references instead of color literals (`@color/…`, `?attr/…`), unknown elements,
+ * malformed XML, a missing or non-positive viewport. `trimPathStart` / `trimPathEnd` /
+ * `trimPathOffset` (never produced by the converter) are ignored.
+ *
+ * Deliberately self-contained (its own tiny XML parser, no import from the converter): the test
+ * harness uses it to validate the converter's output, so a converter bug cannot be masked by shared
+ * code. It has no Node-only dependency and is exported from the browser entry too.
+ */
+/** Options of {@link vectorDrawableToSvg}. */
+interface PreviewOptions {
+    /**
+     * Pixels per dp for the SVG `width` / `height` (default `1`, i.e. mdpi: `24dp` → `24`). Use e.g.
+     * `4` for an xxxhdpi-sized preview. The viewBox is the vector's viewport whatever the density.
+     */
+    density?: number;
+    /**
+     * Apply the vector's `android:tint` (color literal only) with its `android:tintMode` (default
+     * `src_in`; `src_over`, `src_atop`, `multiply`, `screen`, `add` supported) as an SVG filter.
+     * Default `false`: the tint is ignored and the drawing keeps its own colors.
+     */
+    applyTint?: boolean;
+}
+/**
+ * Converts a VectorDrawable XML string into an equivalent standalone SVG string (preview).
+ *
+ * The SVG `width` / `height` are the vector's `android:width` / `android:height` in dp times
+ * `options.density` (default 1), its `viewBox` the viewport, stretched with `preserveAspectRatio="none"`
+ * like Android. See the module documentation for the reproduced semantics and the unsupported input,
+ * which throws an `Error` (e.g. a sweep gradient or a `@color/…` reference).
+ *
+ * ```ts
+ * import { convert, vectorDrawableToSvg } from 'svg-vectordrawable';
+ * const preview = vectorDrawableToSvg(convert(svg).xml, { density: 4 });
+ * ```
+ */
+declare function vectorDrawableToSvg(xml: string, options?: PreviewOptions): string;
+
+/** Options of the lite build: no svgo normalization, hence no `svgoConfig` and `optimize` false. */
+type LiteConvertOptions = Omit<ConvertOptions, 'optimize' | 'svgoConfig'> & {
+    /** Always false in the lite build; `true` throws (use `svg-vectordrawable/browser`). */
+    optimize?: false;
+};
+
+/** Same as the main `convert`, with `optimize` forced to `false`. */
+declare function convert(svg: string, options?: LiteConvertOptions): ConvertResult;
+
+export { type AndroidColor, ConversionError, type LiteConvertOptions as ConvertOptions, type ConvertResult, type LiteConvertOptions, type PreviewOptions, type Severity, type StrictMode, WARNING_CATEGORIES, WARNING_CODES, type Warning, type WarningCategory, type WarningCode, convert, vectorDrawableToSvg };