@weasel-js/svg 1.11.1 → 1.13.0-rc.0

package/README.md

@@ -105,13 +105,16 @@ 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.
+into data of your own shape, from the source node's metadata too. `options.mark`
+says which `<g>`s are marks with children, as the export's `mark` decorator
+tagged them.
 
 `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
+layer), replace a leaf's lowering, or decorate a group or a mark with children
+so the import can tell the two apart. The per-leaf pieces are
 public too: `svgLeafFromKit`, `svgPaintFromKit`, `svgStrokeFromKit`,
 `svgImageFromKit`.
 

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { Affine } from '@weasel-js/geom';
 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';
+import { Path, Paint, ScreenLength, StrokeAlign, MarkerRef, VertexWidth, StrokeNib, StyledRun, TextStyle, TextVerticalAlign, Fill, Stroke, PoseLinear, MarkerEntry, TextPoseLayout, RenderNeeds, TilePatternSpec, IngestCtx, Inherit, ImageNodeData, NodeClip } from '@weasel-js/core';
 
 /**
  * Media Queries 4 evaluation against a fixed environment.
@@ -134,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.
@@ -143,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
@@ -172,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"`. */
@@ -218,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
@@ -491,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
@@ -508,6 +542,19 @@ interface SupportsOptions {
  */
 declare function evaluateSupports(condition: string, opts?: SupportsOptions): boolean;
 
+/**
+ * Parse each file and insert its node tree, one undo step per file. Pass it
+ * as `<SceneCanvas ingestion={{ svg: { unpack: unpackSvgFiles } }}>`.
+ *
+ * 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. 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>;
+
 /**
  * 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
@@ -532,8 +579,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[];
@@ -552,7 +600,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;
@@ -562,10 +610,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. */
@@ -576,8 +626,11 @@ interface SvgKitTreeNode {
     /** 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. */
+    /** The kit's `SceneNode.clip`: `'outline'` writes the node's children
+     *  clipped to its outline, as core's `clipOutline` reads it. */
+    clip?: NodeClip;
+    /** The node's copies, as the kit's `SceneNode.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
@@ -593,18 +646,37 @@ 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;
-    /** Decorate the group written for a container, e.g. with `meta`. */
+    /** 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 `<g>` written for a scene group, e.g. with `meta`. */
     group?(id: TId, group: SvgGroupNode): SvgGroupNode;
+    /** Decorate the `<g>` written for a mark with children, so a reader can
+     *  tell it from a group: `svgNodesToKitDrafts`'s `mark` option reads one
+     *  back. Given, the `<g>` holds the mark's own element, then one `<g>` of its
+     *  children carrying the mark's clip, then a transformed `<g>` of that for
+     *  each copy; a mark whose children are all left out holds its own element
+     *  alone. Not called for a mark whose own element is itself a group, or that
+     *  draws nothing. */
+    mark?(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. A hidden node is written hidden, with its subtree as it is.
+ * Walk a scene's tree into `SvgNode`s ready for `serializeSvg`: a group
+ * becomes a `<g>` of its children, in z-order, drawing nothing of its own; a
+ * mark is written by {@link svgLeafFromKit} unless `options.leaf` says
+ * otherwise, and a mark with children is a `<g>` holding that element and then
+ * its children, or one `<g>` of them when `options.mark` decorates it. 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. */
@@ -620,30 +692,45 @@ type SvgDraftPose = SvgDraftBounds & {
     transform?: PoseLinear;
 };
 
+/**
+ * Parse an SVG file into **native scene nodes** — path/text leaves under
+ * containers that mirror the source `<g>` structure — instead of the default
+ * single embedded-image node.
+ *
+ * Leaf data targets the kit's built-in painters. Poses are absolute AABBs, and
+ * the renderer rebases stored geometry into the pose box, so placement and
+ * fit-clamping operate on poses alone and never rewrite path coordinates.
+ * Stroke widths, dashes, font sizes, and letter spacing live in data, so
+ * they take the clamp separately.
+ */
+
 /**
  * One node the unpack wants the scene to materialize, in parent-before-child
  * order (a draft's `parentId` always names an earlier draft, or `null` for
  * roots). `hidden` is the source node's, for the caller to map onto whatever
  * it hides a node with.
  *
- * A container's `data` is empty unless its `<g>` is clipped. A scene container
- * clips to what its painter draws, so a clipped one holds the clip as an
- * unpainted path, `{ path, fill: null }`, and its `pose` is the clip's box
- * rather than its children's.
+ * A group's `data` is empty unless its `<g>` is clipped. A clipped one declares
+ * `clip: 'outline'` and holds the clip as an unpainted path,
+ * `{ path, fill: null }`, which is the outline a group clips to; its `pose` is
+ * the clip's box rather than its children's. A mark declares a clip only when
+ * it is read from a `<g>` `options.mark` claims.
  */
 type SvgSceneDraft<TData = Record<string, unknown>> = {
-    kind: 'container';
+    kind: 'group';
     id: string;
     parentId: string | null;
     pose: SvgDraftPose;
     data: SvgKitLeafData;
+    clip?: NodeClip;
     hidden?: true;
 } | {
-    kind: 'leaf';
+    kind: 'mark';
     id: string;
     parentId: string | null;
     pose: SvgDraftPose;
     data: TData;
+    clip?: NodeClip;
     hidden?: true;
 };
 /** A leaf `SvgNode`: everything but a group. */
@@ -661,6 +748,14 @@ interface SvgNodesToKitDraftsOptions<TData> {
      *  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;
+    /** Whether a `<g>` is a mark with children, as `svgNodesFromKit`'s `mark`
+     *  option writes one: its first element is drafted as the mark, the
+     *  children of the `<g>` after it as the mark's, hidden where that `<g>` is,
+     *  with its clip as the mark's `clip: 'outline'`, and anything after that,
+     *  such as baked copies, as the mark's further children. A clip on the
+     *  claimed `<g>` itself clips the mark as a group around it. A `<g>` whose
+     *  first element is a group, or whose second is not, is a group. */
+    mark?(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
@@ -690,17 +785,5 @@ declare function strokeDataFromSvg(stroke: SvgStroke | undefined, box: SvgDraftB
  * data; a group whose leaves it all leaves out is dropped like an empty one.
  */
 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 undo step per file. Pass it
- * as `<SceneCanvas ingestion={{ svg: { unpack: unpackSvgFiles } }}>`.
- *
- * 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. 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, escapeAttr, escapeText, 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 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 };