@weasel-js/svg 1.11.0 → 1.12.0

package/README.md

@@ -183,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, VertexWidth, StrokeNib, StyledRun, TextStyle, TextVerticalAlign, Fill, Stroke, PoseLinear, MarkerEntry, TextPoseLayout, 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, Inherit, ImageNodeData, IngestCtx } from '@weasel-js/core';
 
 /**
  * Media Queries 4 evaluation against a fixed environment.
@@ -133,6 +134,17 @@ interface SvgStroke {
     vertexWidths?: VertexWidth[];
     nib?: StrokeNib;
 }
+/**
+ * Which of a node's paints its own element sets none of, so that it takes the
+ * paint of the enclosing `<g>` that does. Its `fill` and `stroke` still hold
+ * what that resolves to.
+ */
+interface SvgInherits {
+    fill?: true;
+    /** Set only when the element sets no `stroke-*` or `marker-*` property
+     *  either: the stroke is taken whole. */
+    stroke?: true;
+}
 /**
  * Leaf node: a path geometry plus fill/stroke. Other shapes (`<rect>`,
  * `<ellipse>`, etc.) are lowered to this on parse.
@@ -142,6 +154,7 @@ interface SvgPathNode {
     path: Path;
     fill: SvgPaint;
     stroke?: SvgStroke;
+    inherits?: SvgInherits;
     /** Element-level opacity (`opacity="..."`), 0..1. */
     opacity?: number;
     /** Element-level rotation in **radians**, pivoting around the AABB
@@ -171,6 +184,12 @@ interface SvgGroupNode {
      *  unions them and a `Path` holds one outline. */
     clip?: Path;
     opacity?: number;
+    /** The fill its children take when they set none — written as the group's
+     *  own `fill`. Absent when neither it nor an enclosing group sets one. */
+    fill?: SvgPaint;
+    /** As `fill`, for the stroke; absent too when the one in effect is none. */
+    stroke?: SvgStroke;
+    inherits?: SvgInherits;
     /** Kept by `ParseOptions.keepHidden` from content SVG does not render:
      *  `display="none"` here, or a leaf under `visibility="hidden"`. Written
      *  back as `display="none"`. */
@@ -217,6 +236,7 @@ interface SvgTextNode {
      */
     fill?: Fill | null;
     stroke?: Stroke;
+    inherits?: SvgInherits;
     /** Element-level opacity (`opacity="..."`), 0..1. */
     opacity?: number;
     /** Element-level rotation in **radians**, pivoting around the unrotated
@@ -441,18 +461,19 @@ declare function nativeSvgSpace(space: string | null | undefined): boolean;
 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.
+ * Escaping for the XML this package writes by hand.
  *
- * 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`.
+ * 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.
  */
-
-/** Serialize a weasel `Path` to an SVG `d=` attribute string. */
-declare function serializePathD(given: Path): string;
+/** 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
@@ -489,6 +510,21 @@ 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;
 
+/** CSS Selectors 4 specificity. */
+/** A selector's specificity as (ids, classes, types). */
+type Specificity = readonly [number, number, number];
+/** Negative when `a` is less specific than `b`, positive when more, 0 when equal. */
+declare function compareSpecificity(a: Specificity, b: Specificity): number;
+/** CSS Selectors 4 specificity of one complex selector (no comma list). */
+declare function specificity(selector: string): Specificity;
+
+/**
+ * Split `s` on `sep` wherever it sits outside strings and (), [] nesting.
+ * With `dropBlocks`, a `{…}` block at depth zero is discarded along with the
+ * prelude before it, back to the previous separator.
+ */
+declare function splitTopLevel(s: string, sep: string, dropBlocks?: boolean): string[];
+
 /**
  * `@supports` evaluation. A declaration test asks whether this parser would
  * honor the declaration ({@link isDeclarationHonored}), not whether a browser
@@ -530,8 +566,9 @@ interface SvgKitPose {
  *  `svgNodesToKitDrafts` writes. */
 interface SvgKitLeafData {
     path?: Path;
-    fill?: Fill | null;
-    stroke?: Stroke | null;
+    /** `'inherit'` takes the enclosing container's. */
+    fill?: Fill | Inherit | null;
+    stroke?: Stroke | Inherit | null;
     text?: string;
     style?: TextStyle;
     runs?: readonly StyledRun[];
@@ -550,7 +587,7 @@ interface SvgKitLeafData {
 declare function svgPaintFromKit(fill: Paint | 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;
+declare function svgStrokeFromKit(raw: 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;
@@ -560,10 +597,12 @@ declare function svgImageFromKit(image: ImageNodeData['image'], pose: SvgKitPose
  * 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.
+ * An `'inherit'` fill or stroke is none here, with no container to read;
+ * {@link svgNodesFromKit} resolves it first.
+ *
+ * A fill or stroke that paints nothing is written `none`. Under a pose
+ * `transform` a stroke's 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 | SvgGroupNode | null;
 /** One node as {@link svgNodesFromKit} reads it. */
@@ -591,8 +630,11 @@ interface SvgNodesFromKitOptions<TId extends string = string> {
     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;
+    /** Lower a leaf yourself; `null` leaves it out. Defaults to {@link svgLeafFromKit}.
+     *  `inherited` is what the leaf's `'inherit'` fields resolve to; write those
+     *  as these, and the walk marks the result as inheriting where SVG's
+     *  cascade can carry them. */
+    leaf?(id: TId, node: SvgKitTreeNode, inherited: SvgKitInherited): SvgNode | null;
     /** Decorate the group written for a container, e.g. with `meta`. */
     group?(id: TId, group: SvgGroupNode): SvgGroupNode;
 }
@@ -603,6 +645,12 @@ interface SvgNodesFromKitOptions<TId extends string = string> {
  * 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[];
+/** What a leaf's `'inherit'` fill and stroke resolve to — its nearest
+ *  enclosing container's; `null` for none. */
+interface SvgKitInherited {
+    fill: Fill | null;
+    stroke: Stroke | null;
+}
 
 /** 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. */
@@ -701,4 +749,4 @@ declare function svgNodesToKitDrafts<TData = Record<string, unknown>>(input: Par
  */
 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, serializePathD, 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 Specificity, 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, compareSpecificity, escapeAttr, escapeText, evaluateMediaQuery, evaluateSupports, fillDataFromSvg, nativeSvgKind, nativeSvgSpace, parseSvg, serializeSvg, specificity, splitTopLevel, strokeDataFromSvg, svgImageFromKit, svgLeafFromKit, svgNeeds, svgNodesFromKit, svgNodesToKitDrafts, svgPaintFromKit, svgStrokeFromKit, tilePreviewCssUrl, tilePreviewSvg, unpackSvgFiles, warmSvg };