@weasel-js/svg 1.6.0 → 1.7.0

package/README.md

@@ -83,6 +83,53 @@ 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.
 
+## Scene nodes, both ways
+
+`svgNodesToKitDrafts(parseSvg(text), nextId)` lowers a document to scene-node
+drafts the kit's built-in path, text and image painters draw, and registers
+the document's markers. Containers carry no opacity, so an element or group
+`opacity` is multiplied into the paints of the leaves under it. `nextId` is
+handed the node each id is for, and `options.leaf` maps each leaf's kit data
+into data of your own shape, from the source node's metadata too.
+
+`svgNodesFromKit(scene)` goes the other way: containers become groups, and
+each leaf is written the way its painter draws it, with the pose baked into
+the geometry and box-relative paints resolved into that box. Hand
+`serializeSvg` the result. Options pick the roots, skip nodes (a hidden
+layer), replace a leaf's lowering or decorate a group. The per-leaf pieces are
+public too: `svgLeafFromKit`, `svgPaintFromKit`, `svgStrokeFromKit`,
+`svgImageFromKit`.
+
+## Stroke markers
+
+A marker reference goes out as `marker-start` / `-mid` / `-end="url(#id)"` with
+one `<marker>` def per distinct reference. The path keeps its full-length `d`:
+baking the kit's inset in would have a re-import trim the line a second time.
+The cost is that other renderers draw the line under a hollow head.
+
+| Reference | Def id | What the def carries |
+|---|---|---|
+| `'arrow'` | `arrow` | `markerUnits="strokeWidth"` |
+| `{ key: 'arrow', size: 3 }` | `arrow-s3` | `markerUnits="userSpaceOnUse"`, `wzl:key="arrow"`, `wzl:size="3"` |
+| `{ key: 'arrow', size: { px: 6 } }` | `arrow-s6px` | the same, drawn at 6 user units, `wzl:size="6px"` |
+
+Any entry with a nonzero inset adds `wzl:inset` in marker units, and the root
+declares the `wzl` namespace whenever one of these attributes appears. `orient`
+is `auto-start-reverse`, because the kit turns every start head around, or an
+entry's fixed angle in degrees. An entry with its own `toSvg` writes its own
+def and gets none of the `wzl` attributes (a sized reference to one warns). A
+reference to a key nothing registered writes no attribute.
+
+On import, `url(#id)` naming a registered key reads back as that key, so an
+unsized built-in needs no def. A def with `wzl:key` and `wzl:size` reads back
+as that sized reference, registering the def's geometry under the key if
+nothing else has. Any other `<marker>` becomes an entry in
+`ParseResult.markers`, keyed by its id plus a hash of what it draws, and
+`svgNodesToKitDrafts` registers it. It is minted per reference rather than per
+def, because a `userSpaceOnUse` size and an `orient="auto"` start both depend on
+the referencing stroke. `wzl:inset` restores the inset; without it the inset is
+0. A reference to a marker neither registered nor defined warns and is dropped.
+
 ## Raster images
 
 `<image>` parses to an `SvgImageNode` holding the `href` verbatim — an

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { Mat3 } from '@weasel-js/geom';
-import { Path, FillStyle, ScreenLength, StrokeAlign, StyledRun, TextStyle, TextVerticalAlign, Stroke, MarkerEntry, TilePatternSpec, ImageNodeData, IngestCtx } from '@weasel-js/core';
+import { Path, FillStyle, ScreenLength, StrokeAlign, MarkerRef, StyledRun, TextStyle, TextVerticalAlign, Stroke, MarkerEntry, TilePatternSpec, ImageNodeData, IngestCtx } from '@weasel-js/core';
 
 /**
  * Public types for `@weasel-js/svg`. The package exposes a flat,
@@ -99,10 +99,12 @@ interface SvgStroke {
      *  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;
-    markerEnd?: string;
+    /** `marker-start` / `marker-mid` / `marker-end` as the kit's `MarkerRef`: the
+     *  bare `url(#id)` key, or a key with the `size` the serializer writes into a
+     *  def of its own. */
+    markerStart?: MarkerRef;
+    markerMid?: MarkerRef;
+    markerEnd?: MarkerRef;
 }
 /**
  * Leaf node: a path geometry plus fill/stroke. All other v1 shapes
@@ -390,6 +392,104 @@ declare function tilePreviewSvg(spec: TilePatternSpec, background?: string): str
 /** `tilePreviewSvg` packed as a `url(...)` value for CSS `background-image`. */
 declare function tilePreviewCssUrl(spec: TilePatternSpec, background?: string): string;
 
+/**
+ * Map between SVG `<linearGradient>` / `<radialGradient>` elements and
+ * weasel's `FillStyle` gradient variants. Definitions are indexed by id
+ * wherever in the document they appear, and looked up when a `fill` /
+ * `stroke` attribute references one as `url(#id)`. On serialize, we
+ * emit a fresh `<defs>` block with stable generated ids.
+ */
+
+/** `true` when SVG has a paint server for this kind, so the reference needs no
+ *  fallback color and the root needs no foreign namespace. */
+/** Whether SVG has its own paint server for paint kind `kind`: solids, the
+ *  linear and radial gradients, and patterns. Any other kind is written in
+ *  weasel's namespace with a fallback color, which other renderers paint flat. */
+declare function nativeSvgKind(kind: string): boolean;
+/** Whether a gradient interpolating through `space` blends the same in every
+ *  SVG renderer — only sRGB, the default. A perceptual space still exports,
+ *  but renderers other than weasel blend it in sRGB. */
+declare function nativeSvgSpace(space: string | null | undefined): boolean;
+
+/**
+ * The kit-to-SVG direction: scene leaves back to `SvgNode`s, the inverse of
+ * `svgNodesToKitDrafts`. Each leaf is written as the built-in painter that
+ * draws it would draw it — the pose baked into the geometry, box-relative
+ * paints resolved into that box — so `serializeSvg` over the result shows what
+ * the canvas shows.
+ */
+
+/** A leaf's box: where it is drawn, and the frame its box-relative paints
+ *  resolve against. */
+interface SvgKitPose {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    rotation?: number;
+}
+/** The leaf data the kit's path, text and image painters read — what
+ *  `svgNodesToKitDrafts` writes. */
+interface SvgKitLeafData {
+    path?: Path;
+    fill?: FillStyle | null;
+    stroke?: Stroke | null;
+    text?: string;
+    style?: TextStyle;
+    runs?: readonly StyledRun[];
+    verticalAlign?: TextVerticalAlign;
+    image?: ImageNodeData['image'];
+}
+/** A kit paint as an `SvgPaint`. `null` is `fill="none"`; a box-relative
+ *  gradient or pattern is resolved into `box`, since the geometry it paints
+ *  is written already placed there. */
+declare function svgPaintFromKit(fill: FillStyle | null, box: SvgKitPose): SvgPaint;
+/** A kit `Stroke` as an `SvgStroke` — the inverse of `strokeDataFromSvg`.
+ *  One with no paint or no width draws nothing and is written as no stroke. */
+declare function svgStrokeFromKit(stroke: Stroke | null | undefined, box: SvgKitPose): SvgStroke | undefined;
+/** Write a `kit:image` leaf as an `SvgImageNode` — the inverse of the image
+ *  arm of `svgNodesToKitDrafts`. The pose is the image's box. */
+declare function svgImageFromKit(image: ImageNodeData['image'], pose: SvgKitPose): SvgImageNode;
+/**
+ * Write one leaf as the `SvgNode` its built-in painter draws — image, text or
+ * path, in the order the painters claim a node. `null` for data none of them
+ * draws.
+ *
+ * A path with no `fill` takes `kit:path`'s fallback: the default shape fill
+ * when it has no stroke, and no fill when it has one.
+ */
+declare function svgLeafFromKit(data: SvgKitLeafData, pose: SvgKitPose): SvgPathNode | SvgTextNode | SvgImageNode | null;
+/** One node as {@link svgNodesFromKit} reads it. */
+interface SvgKitTreeNode {
+    kind: string;
+    data: unknown;
+    pose: SvgKitPose;
+}
+/** The read side of a scene that {@link svgNodesFromKit} walks. A kit
+ *  `Scene` is one as it stands. */
+interface SvgKitTree<TId extends string = string> {
+    readonly roots: readonly TId[];
+    childrenOf(id: TId): readonly TId[];
+    get(id: TId): SvgKitTreeNode | undefined;
+}
+interface SvgNodesFromKitOptions<TId extends string = string> {
+    /** Walk these ids, in this order, instead of the tree's roots. */
+    roots?: readonly TId[];
+    /** `false` leaves a node out, with everything under it — a hidden layer. */
+    include?(id: TId): boolean;
+    /** Lower a leaf yourself; `null` leaves it out. Defaults to {@link svgLeafFromKit}. */
+    leaf?(id: TId, node: SvgKitTreeNode): SvgNode | null;
+    /** Decorate the group written for a container, e.g. with `meta`. */
+    group?(id: TId, group: SvgGroupNode): SvgGroupNode;
+}
+/**
+ * Walk a scene's container tree into `SvgNode`s ready for `serializeSvg`:
+ * every `container` becomes a group of its children, in z-order, and every
+ * leaf goes through {@link svgLeafFromKit} unless `options.leaf` says
+ * otherwise.
+ */
+declare function svgNodesFromKit<TId extends string>(tree: SvgKitTree<TId>, options?: SvgNodesFromKitOptions<TId>): SvgNode[];
+
 /** Axis-aligned box, in the coordinate space of the SVG being unpacked. Used
  *  for the bounds a draft occupies before it becomes a scene node. */
 interface SvgDraftBounds {
@@ -406,7 +506,7 @@ type DraftPose = SvgDraftBounds & {
  * order (a draft's `parentId` always names an earlier draft, or `null` for
  * roots). Leaf `data` is kit-painter-native (see module doc).
  */
-type SvgSceneDraft = {
+type SvgSceneDraft<TData = Record<string, unknown>> = {
     kind: 'container';
     id: string;
     parentId: string | null;
@@ -416,8 +516,29 @@ type SvgSceneDraft = {
     id: string;
     parentId: string | null;
     pose: DraftPose;
-    data: Record<string, unknown>;
+    data: TData;
 };
+/** A leaf `SvgNode`: everything but a group. */
+type SvgLeafNode = Exclude<SvgNode, SvgGroupNode>;
+interface SvgNodesToKitDraftsOptions<TData> {
+    /** Lower a leaf yourself, from the kit data the default writes for it and
+     *  the node it came from — for data shaped other than the kit painters', or
+     *  metadata the document carries. `null` leaves it out. */
+    leaf?(id: string, draft: {
+        pose: DraftPose;
+        data: SvgKitLeafData;
+    }, source: SvgLeafNode): TData | null;
+}
+/** Lower an `SvgPaint` onto the `kit:path` painter's `data.fill` — a
+ *  `FillStyle`, or `null` for SVG's `fill="none"` (the painter skips the
+ *  fill rather than falling back to its default). A solid paint keeps its
+ *  `fill-opacity`.
+ *
+ *  A gradient rides through as the `FillStyle` it already is, normalized to
+ *  the leaf's own box: `objectBoundingBox` gradients already are, and a
+ *  `userSpaceOnUse` one is rebased so it survives the fit-clamp and the
+ *  drop-point placement that move the geometry out from under it. */
+declare function fillDataFromSvg(paint: SvgPaint | undefined, box: SvgDraftBounds): FillStyle | null | undefined;
 /** Lower an `SvgStroke` onto the leaf's `data.stroke`.
  *
  *  Everything the SVG carried — paint, width, cap, join, dash, miter limit,
@@ -426,16 +547,21 @@ type SvgSceneDraft = {
  *  `userSpaceOnUse` gradient survives the fit-clamp and the drop-point
  *  placement. */
 declare function strokeDataFromSvg(stroke: SvgStroke | undefined, box: SvgDraftBounds): Stroke | undefined;
-/** Write a `kit:image` leaf as an `SvgImageNode` — the inverse of the image
- *  arm of {@link svgNodesToKitDrafts}. The pose is the image's box. */
-declare function svgImageFromKit(image: ImageNodeData['image'], pose: DraftPose): SvgImageNode;
 /**
  * Walk an `SvgNode[]` tree and emit a flat, parent-before-child list of
  * {@link SvgSceneDraft}s. Each `<g>` becomes a container whose pose is the
  * union AABB of its descendants (the kit `group` action's convention);
  * path/text leaves carry kit-painter-native data. Empty groups are dropped.
+ *
+ * Handed a whole `ParseResult`, it also registers the document's markers
+ * (`parsed.markers`), without which the strokes naming them draw bare.
+ * Containers carry no opacity, so an element or group `opacity` is multiplied
+ * into the paints of every leaf under it.
+ *
+ * `nextId` is handed the node each id is for. `options.leaf` replaces a leaf's
+ * data; a group whose leaves it all leaves out is dropped like an empty one.
  */
-declare function svgNodesToKitDrafts(nodes: readonly SvgNode[], nextId: () => string): SvgSceneDraft[];
+declare function svgNodesToKitDrafts<TData = Record<string, unknown>>(input: ParseResult | readonly SvgNode[], nextId: (source: SvgNode) => string, options?: SvgNodesToKitDraftsOptions<TData>): SvgSceneDraft<TData>[];
 /**
  * Parse each file and insert its node tree — one undoable `applyOps` batch
  * per file. See the module doc for placement and wrapping policy. A file
@@ -444,4 +570,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, parseSvg, serializeSvg, strokeDataFromSvg, svgImageFromKit, 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 SvgKitLeafData, type SvgKitPose, type SvgKitTree, type SvgKitTreeNode, type SvgLeafNode, type SvgNode, type SvgNodesFromKitOptions, type SvgNodesToKitDraftsOptions, type SvgPaint, type SvgPathNode, type SvgSceneDraft, type SvgStroke, type SvgTextNode, fillDataFromSvg, nativeSvgKind, nativeSvgSpace, parseSvg, serializeSvg, strokeDataFromSvg, svgImageFromKit, svgLeafFromKit, svgNodesFromKit, svgNodesToKitDrafts, svgPaintFromKit, svgStrokeFromKit, tilePreviewCssUrl, tilePreviewSvg, unpackSvgFiles };