@weasel-js/svg 1.10.0 → 1.11.0

package/README.md

@@ -4,7 +4,7 @@ SVG import/export for @weasel-js/core: parse SVG strings into weasel-native shap
 
 Part of [weasel](https://github.com/orochi235/weasel), a domain-agnostic 2D
 scene-graph canvas kit for React. See the
-[API reference](https://orochi235.github.io/weasel/api/).
+[API reference](https://orochi235.github.io/weasel/#pkg/svg).
 
 ## Install
 
@@ -37,6 +37,16 @@ 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.
 
+**SVG text does not wrap.** By default a `<text>` is written one line per
+hard break, pitched at the node's font size times its line height, and a
+wrapping or justified node keeps that only in `data-weasel-*` attributes for
+weasel's own reader. Pass `serializeSvg(nodes, { textLayout: layoutTextPose })`
+to write the lines the renderer draws instead: each line is a `<tspan>` at the
+layout's `x` and baseline `y`, each word of a line the layout justified gets
+its own `x`, and a line holding a larger run sits where the renderer puts it.
+The layout measures with the registered fonts, so `await warmSvg(nodes, {
+textLayout })` first; a node no face could measure is written the default way.
+
 ## Paints SVG cannot express
 
 SVG has `<linearGradient>`, `<radialGradient>` and `<pattern>` and nothing

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { Mat3 } from '@weasel-js/geom';
-import { Path, Paint, ScreenLength, StrokeAlign, MarkerRef, StyledRun, TextStyle, TextVerticalAlign, Fill, Stroke, PoseLinear, MarkerEntry, RenderNeeds, TilePatternSpec, ImageNodeData, IngestCtx } from '@weasel-js/core';
+import { Affine } from '@weasel-js/geom';
+import { Path, Paint, ScreenLength, StrokeAlign, MarkerRef, VertexWidth, StrokeNib, StyledRun, TextStyle, TextVerticalAlign, Fill, Stroke, PoseLinear, MarkerEntry, TextPoseLayout, RenderNeeds, TilePatternSpec, ImageNodeData, IngestCtx } from '@weasel-js/core';
 
 /**
  * Media Queries 4 evaluation against a fixed environment.
@@ -74,10 +74,10 @@ interface NamespacedElement {
 }
 /**
  * 2x3 affine matrix in SVG's `matrix(a b c d e f)` order, mapping
- * `[x', y'] = [a*x + c*y + e, b*x + d*y + f]`. It is geom's `Mat3`, so the
+ * `[x', y'] = [a*x + c*y + e, b*x + d*y + f]`. It is geom's `Affine`, so the
  * two are interchangeable without a conversion.
  */
-type Matrix = Mat3;
+type Matrix = Affine;
 
 /** The identity matrix. */
 declare const IDENTITY_MATRIX: Matrix;
@@ -125,6 +125,13 @@ interface SvgStroke {
     markerStart?: MarkerRef;
     markerMid?: MarkerRef;
     markerEnd?: MarkerRef;
+    /** The kit stroke's `vertexWidths` and `nib`. SVG has no variable width, so
+     *  the serializer writes such a stroke's outline as a filled shape after the
+     *  path, and keeps these in the private namespace for the parser. An entry
+     *  of `vertexWidths`, or one side of a pair, that is not a number of zero or
+     *  more takes `width`. */
+    vertexWidths?: VertexWidth[];
+    nib?: StrokeNib;
 }
 /**
  * Leaf node: a path geometry plus fill/stroke. Other shapes (`<rect>`,
@@ -372,6 +379,18 @@ interface SerializeOptions {
      * line, since whitespace inside it is content.
      */
     pretty?: boolean;
+    /**
+     * The lines a text node lays out into — pass core's `layoutTextPose`, the
+     * layout the renderer draws with. With it, each line is written as a
+     * `<tspan>` at the layout's own `x` and baseline `y`, a justified line
+     * gives each word its own `x`, and a line holding a larger run is pitched
+     * as the renderer pitches it, so a reader that cannot wrap draws the lines
+     * where weasel does. A node it returns nothing for, or lays out to zero
+     * width because no face could measure it, is written without it: one line
+     * per hard break, at the node's own pitch. Fonts it reads must have loaded;
+     * `warmSvg(nodes, { textLayout })` loads them.
+     */
+    textLayout?: (node: SvgTextNode) => TextPoseLayout | null | undefined;
 }
 
 /**
@@ -410,28 +429,48 @@ declare function nativeSvgKind(kind: string): boolean;
  *  but renderers other than weasel blend it in sRGB. */
 declare function nativeSvgSpace(space: string | null | undefined): boolean;
 
+/**
+ * Serialize a `SvgNode[]` tree to an SVG document string. Every path leaf is
+ * emitted as a `<path>`, even shapes that started as `<rect>` etc.
+ */
+
 /**
  * Produce an SVG document string. The root `viewBox` is `opts.viewBox` if
  * supplied, otherwise a tight bounding box around every leaf.
  */
 declare function serializeSvg(nodes: SvgNode[], opts?: SerializeOptions): string;
 
+/**
+ * Serialize a weasel `Path` to an SVG `d=` attribute string. `RectPath`
+ * lowers to `M h v h Z`; `PolygonPath` walks the (commands, coords)
+ * arrays, emitting one SVG command per kit command, with corner shapes
+ * expanded into the geometry they draw.
+ *
+ * Output uses absolute commands only and a small amount of whitespace
+ * compression (no leading zeros stripped beyond what `Number.toString`
+ * already does). Numbers are rounded to ~6 decimals via `trimNumber`.
+ */
+
+/** Serialize a weasel `Path` to an SVG `d=` attribute string. */
+declare function serializePathD(given: Path): string;
+
 /**
  * What `serializeSvg(nodes)` reads that loads on demand: the paint kind of
  * every fill and stroke it writes as a paint server, and the face of every
  * run whose script size it takes from font metrics. The kinds come from the
  * serializer's own paint pre-pass, so the two cannot disagree. Registered
- * kinds are included.
+ * kinds are included. Given the `textLayout` the export will run, every face
+ * a text node is set in, which that layout measures with.
  */
-declare function svgNeeds(nodes: readonly SvgNode[]): RenderNeeds;
+declare function svgNeeds(nodes: readonly SvgNode[], opts?: Pick<SerializeOptions, 'textLayout'>): RenderNeeds;
 /**
- * Load what {@link svgNeeds} lists, so a `serializeSvg(nodes)` issued after it
- * resolves writes every paint server's def and every script size from the
- * face it renders in. Only those load: a lazily registered kind or font the
+ * Load what {@link svgNeeds} lists, so a `serializeSvg(nodes, opts)` issued
+ * after it resolves writes every paint server's def, and every script size and
+ * laid-out line from the face it renders in. Only those load: a lazily registered kind or font the
  * nodes do not use is never fetched, and cannot fail the export. A kind
  * nothing registered is passed over; the export warns about it instead.
  */
-declare function warmSvg(nodes: readonly SvgNode[]): Promise<void>;
+declare function warmSvg(nodes: readonly SvgNode[], opts?: Pick<SerializeOptions, 'textLayout'>): Promise<void>;
 
 /**
  * Map between SVG `<pattern>` elements and weasel's pattern paints.
@@ -497,6 +536,12 @@ interface SvgKitLeafData {
     style?: TextStyle;
     runs?: readonly StyledRun[];
     verticalAlign?: TextVerticalAlign;
+    /** A text node's paint over its whole box, under the glyphs. */
+    background?: Fill | null;
+    /** A text node's inset from its box to its text, on every side. */
+    padding?: number;
+    /** `'clip'` cuts a text node's text at its box. */
+    overflow?: 'visible' | 'clip';
     image?: ImageNodeData['image'];
 }
 /** A kit paint as an `SvgPaint`. `null` is `fill="none"`; a box-relative
@@ -512,19 +557,26 @@ declare function svgImageFromKit(image: ImageNodeData['image'], pose: SvgKitPose
 /**
  * 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.
+ * draws. A text node with a `background` is a group: the box, then the text.
+ * One that clips is a group clipped to its box as it is drawn, turned with it.
  *
  * 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. Under a pose `transform`
  * its stroke width takes the uniform part of the stretch, as `parseSvg` reads
  * a stroke under a skewed element.
  */
-declare function svgLeafFromKit(data: SvgKitLeafData, pose: SvgKitPose): SvgPathNode | SvgTextNode | SvgImageNode | null;
+declare function svgLeafFromKit(data: SvgKitLeafData, pose: SvgKitPose): SvgPathNode | SvgTextNode | SvgImageNode | SvgGroupNode | null;
 /** One node as {@link svgNodesFromKit} reads it. */
 interface SvgKitTreeNode {
     kind: string;
     data: unknown;
     pose: SvgKitPose;
+    /** The kit's `SceneNode.hidden`: written with `display="none"`, which
+     *  `parseSvg(…, { keepHidden: true })` reads back as `hidden`. */
+    hidden?: boolean;
+    /** A container's copies, as the kit's `ContainerNode.copiesFromPose`
+     *  draws them: each is written as a transformed group of its children. */
+    copiesFromPose?(pose: SvgKitPose, node: never): readonly Matrix[] | null;
 }
 /** The read side of a scene that {@link svgNodesFromKit} walks. A kit
  *  `Scene` is one as it stands. */
@@ -548,7 +600,7 @@ interface SvgNodesFromKitOptions<TId extends string = string> {
  * 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.
+ * otherwise. A hidden node is written hidden, with its subtree as it is.
  */
 declare function svgNodesFromKit<TId extends string>(tree: SvgKitTree<TId>, options?: SvgNodesFromKitOptions<TId>): SvgNode[];
 
@@ -603,6 +655,10 @@ interface SvgNodesToKitDraftsOptions<TData> {
         pose: SvgDraftPose;
         data: SvgKitLeafData;
     }, source: SvgLeafNode): TData | null;
+    /** Keep a group that draws nothing, which is otherwise dropped — for one
+     *  whose metadata means something with no children under it. It is drafted
+     *  with its clip's box, or a zero box at the origin. */
+    keepEmpty?(source: SvgGroupNode): boolean;
 }
 /** Lower an `SvgPaint` onto the paint of the `kit:path` painter's
  *  `data.fill` — a `Paint`, or `null` for SVG's `fill="none"` (the painter
@@ -620,7 +676,8 @@ declare function strokeDataFromSvg(stroke: SvgStroke | undefined, box: SvgDraftB
  * 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, or its clip's box when it has one; leaves
- * carry kit-painter-native data. Empty groups are dropped.
+ * carry kit-painter-native data. Empty groups are dropped unless
+ * `options.keepEmpty` keeps them, and so is a group holding only those.
  *
  * Handed a whole `ParseResult`, it also registers the document's markers
  * (`parsed.markers`), without which the strokes naming them draw bare.
@@ -638,9 +695,10 @@ declare function svgNodesToKitDrafts<TData = Record<string, unknown>>(input: Par
  * Each file is fit-clamped to 90% of the visible viewport and centered on the
  * drop point (or the viewport center), with later files cascading by a fixed
  * offset. A multi-root file is wrapped in one container so it arrives as a
- * single selectable unit. A file that fails to parse, or parses to nothing,
+ * single selectable unit. Content the file hides arrives hidden
+ * (`SceneNode.hidden`) rather than being left out. A file that fails to parse, or parses to nothing,
  * is skipped with a `console.warn`.
  */
 declare function unpackSvgFiles(files: File[], ctx: IngestCtx): Promise<void>;
 
-export { DEFAULT_MEDIA_ENVIRONMENT, IDENTITY_MATRIX, type Matrix, type NamespaceMeta, type NamespacedElement, type ParseOptions, type ParseResult, type SerializeOptions, type SupportsOptions, type SvgDraftBounds, type SvgDraftPose, type SvgGroupNode, type SvgImageNode, type SvgKitLeafData, type SvgKitPose, type SvgKitTree, type SvgKitTreeNode, type SvgLeafNode, type SvgMediaEnvironment, type SvgNode, type SvgNodesFromKitOptions, type SvgNodesToKitDraftsOptions, type SvgPaint, type SvgPathNode, type SvgSceneDraft, type SvgStroke, type SvgTextNode, evaluateMediaQuery, evaluateSupports, fillDataFromSvg, nativeSvgKind, nativeSvgSpace, parseSvg, serializeSvg, strokeDataFromSvg, svgImageFromKit, svgLeafFromKit, svgNeeds, svgNodesFromKit, svgNodesToKitDrafts, svgPaintFromKit, svgStrokeFromKit, tilePreviewCssUrl, tilePreviewSvg, unpackSvgFiles, warmSvg };
+export { DEFAULT_MEDIA_ENVIRONMENT, IDENTITY_MATRIX, type Matrix, type NamespaceMeta, type NamespacedElement, type ParseOptions, type ParseResult, type SerializeOptions, type SupportsOptions, type SvgDraftBounds, type SvgDraftPose, type SvgGroupNode, type SvgImageNode, type SvgKitLeafData, type SvgKitPose, type SvgKitTree, type SvgKitTreeNode, type SvgLeafNode, type SvgMediaEnvironment, type SvgNode, type SvgNodesFromKitOptions, type SvgNodesToKitDraftsOptions, type SvgPaint, type SvgPathNode, type SvgSceneDraft, type SvgStroke, type SvgTextNode, evaluateMediaQuery, evaluateSupports, fillDataFromSvg, nativeSvgKind, nativeSvgSpace, parseSvg, serializePathD, serializeSvg, strokeDataFromSvg, svgImageFromKit, svgLeafFromKit, svgNeeds, svgNodesFromKit, svgNodesToKitDrafts, svgPaintFromKit, svgStrokeFromKit, tilePreviewCssUrl, tilePreviewSvg, unpackSvgFiles, warmSvg };