@weasel-js/svg 1.4.4 → 1.5.1

package/README.md

@@ -40,6 +40,49 @@ answer, and the alternative is unrepresentable anyway (see above). It only
 shows up on foreign SVG that sets decoration on a group and cancels it on a
 child.
 
+## Paints SVG cannot express
+
+SVG has `<linearGradient>`, `<radialGradient>` and `<pattern>` and nothing
+else, so a conic gradient — or any paint kind a consumer registers — has no
+element to serialize into. Both go out as a def in weasel's own namespace,
+declared on the root as `xmlns:wzl="urn:weasel-js:svg"` only when a document
+holds such a paint:
+
+```xml
+<defs><wzl:conicGradient id="grad0" gradientUnits="objectBoundingBox"
+  cx="0.5" cy="0.5" angle="0.25"><stop offset="0" stop-color="#ff0000"/>
+  <stop offset="1" stop-color="#0000ff"/></wzl:conicGradient></defs>
+<path fill="url(#grad0) #ff0000" d="…"/>
+```
+
+The color after the reference is SVG's own paint fallback: this package reads
+the def back and reproduces the paint exactly, every other renderer skips the
+def it does not know and paints that flat color instead. A registered kind's
+`toSvg` gets the same treatment, with the fallback taken from its `colorOf` —
+or `none` when the kind has no single color, so an unresolvable reference
+paints nothing rather than something arbitrary.
+
+That cuts both ways on import: a `fill="url(#mesh1) #c04a3f"` from Inkscape,
+whose mesh gradients this package does not model, imports as flat `#c04a3f`
+rather than as a dropped fill.
+
+### A gradient's blend space
+
+A gradient's `interpolate` — `'oklab'` or `'oklch'` — has no SVG spelling
+either: `color-interpolation` carries `sRGB` and `linearRGB` only. It goes out
+as `wzl:interpolate` on the gradient's *own* element, which stays
+`<linearGradient>` or `<radialGradient>`:
+
+```xml
+<linearGradient id="grad0" gradientUnits="objectBoundingBox"
+  x1="0" y1="0" x2="1" y2="0" wzl:interpolate="oklch">…</linearGradient>
+```
+
+No fallback color rides along, because a foreign renderer still paints the
+gradient — it just blends the stops in sRGB, which moves the midpoint rather
+than losing the paint. A space this package does not know is dropped on import
+rather than carried through.
+
 ## Raster images
 
 `<image>` parses to an `SvgImageNode` holding the `href` verbatim — an

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { Path, FillStyle, StyledRun, TextStyle, Stroke, TilePatternSpec, IngestCtx } from '@weasel-js/core';
+import { Path, FillStyle, StrokeAlign, StyledRun, TextStyle, TextVerticalAlign, Stroke, MarkerEntry, TilePatternSpec, IngestCtx } from '@weasel-js/core';
 
 /**
  * Public types for `@weasel-js/svg`. The package exposes a flat,
@@ -91,6 +91,10 @@ interface SvgStroke {
      * attribute may render with longer miters than the source SVG intended.
      */
     miterLimit?: number;
+    /** The kit stroke's `align`. SVG has no stroke alignment, so the serializer
+     *  writes the stroke centered and says so through `onWarn`; the parser
+     *  never sets it. */
+    align?: StrokeAlign;
     /** `marker-start` / `marker-mid` / `marker-end`, as the bare `url(#id)` key. */
     markerStart?: string;
     markerMid?: string;
@@ -126,20 +130,16 @@ interface SvgGroupNode {
     kind: 'group';
     children: SvgNode[];
     transform?: Matrix;
+    /** Clips the group's contents. Serializes to a `<clipPath>` def plus
+     *  `clip-path="url(#id)"`, and lives in the same space as `children` —
+     *  SVG applies the group's own `transform` to the clip as well.
+     *  A `<clipPath>` of more than one shape parses back as no clip: SVG
+     *  unions them and a `Path` holds one outline. */
+    clip?: Path;
     opacity?: number;
     /** Opaque per-element bag for declared namespaces. See `NamespaceMeta`. */
     meta?: NamespaceMeta;
 }
-/**
- * Width given to an external `<text>` that carries no `data-weasel-width`:
- * large enough that line wrapping never fires, since SVG text flows from a
- * baseline and the source says nothing about a box.
- *
- * It is a wrap sentinel, not a measurement. Anything that treats a text
- * node's width as geometry — a union AABB, a fit-clamp — has to recognize it
- * and substitute an estimate, or one text node swamps the whole file.
- */
-declare const UNBOUNDED_TEXT_WIDTH = 99999;
 /**
  * Text leaf node. Mirrors the kit's `TextPose` shape — a bounding box plus
  * text content, optional rich-text `runs` (per-range styling), and an
@@ -150,9 +150,12 @@ declare const UNBOUNDED_TEXT_WIDTH = 99999;
  * `dominant-baseline="text-before-edge"` so `y` is the top of the text
  * box, plus `data-weasel-width` / `data-weasel-height` so weasel's
  * explicit box dimensions round-trip losslessly. External SVG text
- * (lacking the data-* attrs) imports with estimated dimensions —
- * {@link UNBOUNDED_TEXT_WIDTH} and
+ * (lacking the data-* attrs) imports with the width the kit's text layout
+ * measures — an em-based estimate when no registered font can — and
  * `height = fontSize * lineHeight * (lineCount || 1)`.
+ *
+ * `x` here is always the box's left edge. In the SVG it is the
+ * `text-anchor` point, and the parser and serializer convert between them.
  */
 interface SvgTextNode {
     kind: 'text';
@@ -166,6 +169,10 @@ interface SvgTextNode {
     runs?: StyledRun[];
     /** Node-wide typography. Defaults applied at render time via `resolveTextStyle`. */
     style?: TextStyle;
+    /** Where the laid-out text sits inside the box — `kit:text`'s
+     *  `data.verticalAlign`. SVG text has no box to align in, so this rides in
+     *  `data-weasel-vertical-align` and other readers draw the text top-aligned. */
+    verticalAlign?: TextVerticalAlign;
     /**
      * Node-wide glyph paint, the `FillStyle` / `Stroke` a kit text node holds
      * in `data.fill` / `data.stroke`. Not `SvgPaint`, which is the path
@@ -193,6 +200,12 @@ interface SvgTextNode {
  * a reference and only resolves when something downstream loads it.
  *
  * SVG's `preserveAspectRatio` is not modeled; the box is taken literally.
+ *
+ * With a `source` rect or a flip, the element is written as a `<g
+ * data-weasel-image>` holding a nested `<svg>` viewport at the box, whose
+ * `viewBox` is the source window over a unit-square `<image>` — plain SVG 1.1,
+ * which any reader crops and mirrors the same way, and which `parseSvg` reads
+ * back as one image node.
  */
 interface SvgImageNode {
     kind: 'image';
@@ -201,6 +214,20 @@ interface SvgImageNode {
     y: number;
     width: number;
     height: number;
+    /** The part of the bitmap drawn into the box, as fractions of the bitmap's
+     *  width and height from its top-left. Omitted draws the whole bitmap.
+     *  Fractions rather than bitmap pixels because this package never decodes
+     *  the image, so it cannot know its size. */
+    source?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    /** Mirror the drawn region within the box, as `ImageDrawCommand` does. The
+     *  box does not move. */
+    flipX?: boolean;
+    flipY?: boolean;
     /** Element-level opacity (`opacity="..."`), 0..1. */
     opacity?: number;
     /** Element-level rotation in **radians**, pivoting around the unrotated
@@ -247,6 +274,13 @@ interface ParseResult {
     height?: number;
     /** Text content of the first `<title>` child of `<svg>`, when present. */
     title?: string;
+    /**
+     * An entry for each document `<marker>` a stroke references under a key the
+     * marker registry does not know, keyed as the strokes in `nodes` now name
+     * them. Nothing draws them until they are registered (`registerMarker`),
+     * which `unpackSvgFiles` does.
+     */
+    markers?: MarkerEntry[];
 }
 /** Options for {@link serializeSvg}. */
 interface SerializeOptions {
@@ -261,9 +295,11 @@ interface SerializeOptions {
         height: number;
     };
     /**
-     * Called for paint that can't be expressed in SVG and is dropped — a
-     * conic gradient, or a pattern carrying a `TextureHandle` instead of a
-     * `TilePatternSpec`. Without this the loss is silent.
+     * Called for what the document cannot carry the way weasel draws it: a
+     * paint SVG cannot express (a pattern carrying a `TextureHandle` instead of
+     * a `TilePatternSpec`), a stroke aligned off its edge, text that wraps or
+     * sits lower than the top of its box. Each message is said once per call.
+     * Without this the loss is silent.
      */
     onWarn?: (message: string) => void;
     /** Emit `width="..."` on the root `<svg>`. */
@@ -401,4 +437,4 @@ declare function svgNodesToKitDrafts(nodes: readonly SvgNode[], nextId: () => st
  */
 declare function unpackSvgFiles(files: File[], ctx: IngestCtx): Promise<void>;
 
-export { IDENTITY_MATRIX, type Matrix, type NamespaceMeta, type NamespacedElement, type ParseOptions, type ParseResult, type SerializeOptions, type SvgDraftBounds, type SvgGroupNode, type SvgImageNode, type SvgNode, type SvgPaint, type SvgPathNode, type SvgSceneDraft, type SvgStroke, type SvgTextNode, UNBOUNDED_TEXT_WIDTH, parseSvg, serializeSvg, strokeDataFromSvg, svgNodesToKitDrafts, tilePreviewCssUrl, tilePreviewSvg, unpackSvgFiles };
+export { IDENTITY_MATRIX, type Matrix, type NamespaceMeta, type NamespacedElement, type ParseOptions, type ParseResult, type SerializeOptions, type SvgDraftBounds, type SvgGroupNode, type SvgImageNode, type SvgNode, type SvgPaint, type SvgPathNode, type SvgSceneDraft, type SvgStroke, type SvgTextNode, parseSvg, serializeSvg, strokeDataFromSvg, svgNodesToKitDrafts, tilePreviewCssUrl, tilePreviewSvg, unpackSvgFiles };