@weasel-js/svg 1.10.1 → 1.11.1

package/README.md

@@ -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
@@ -173,6 +183,14 @@ writes a `kit:image` leaf back as an `SvgImageNode`.
 in (a non-`none` value warns) and written back as `none`, so a source file
 that relied on letterboxing imports stretched.
 
+## Writing XML by hand
+
+`escapeAttr(s)` and `escapeText(s)` are the escaping this package writes XML
+with, for a caller writing its own. Both drop the characters XML 1.0 cannot
+hold, even as references, and turn a vertical tab or form feed into a line
+break. `escapeAttr` also writes tabs and line breaks as references, since a
+parser reads a literal one in an attribute as a space.
+
 ## License
 
 MIT

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import { Affine } 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';
+export { pathToD as serializePathD } 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.
@@ -125,6 +126,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 +380,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;
 }
 
 /**
@@ -421,22 +441,38 @@ declare function nativeSvgSpace(space: string | null | undefined): boolean;
  */
 declare function serializeSvg(nodes: SvgNode[], opts?: SerializeOptions): string;
 
+/**
+ * Escaping for the XML this package writes by hand.
+ *
+ * XML 1.0 cannot hold most C0 controls, U+FFFE, U+FFFF, or half a surrogate
+ * pair, even as character references, and a parser rejects the whole
+ * document over one. A vertical tab or form feed is a line break where text
+ * comes from (a word processor's clipboard), so those become `\n`; the rest
+ * are dropped.
+ */
+/** A parser turns a literal tab or line break in an attribute value into a
+ *  space, so those are written as character references. */
+declare function escapeAttr(s: string): string;
+/** A literal carriage return in content is read back as a newline. */
+declare function escapeText(s: string): 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.
@@ -502,6 +538,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
@@ -517,19 +559,23 @@ 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;
@@ -556,7 +602,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[];
 
@@ -611,6 +657,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
@@ -628,7 +678,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.
@@ -646,9 +697,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, escapeAttr, escapeText, evaluateMediaQuery, evaluateSupports, fillDataFromSvg, nativeSvgKind, nativeSvgSpace, parseSvg, serializeSvg, strokeDataFromSvg, svgImageFromKit, svgLeafFromKit, svgNeeds, svgNodesFromKit, svgNodesToKitDrafts, svgPaintFromKit, svgStrokeFromKit, tilePreviewCssUrl, tilePreviewSvg, unpackSvgFiles, warmSvg };