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

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, IngestCtx, Inherit, ImageNodeData, NodeClip } from '@weasel-js/core';
+import { Path, Paint, ScreenLength, StrokeAlign, MarkerRef, VertexWidth, StrokeNib, BooleanShapeOp, 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.
@@ -194,6 +194,11 @@ interface SvgGroupNode {
      *  `display="none"` here, or a leaf under `visibility="hidden"`. Written
      *  back as `display="none"`. */
     hidden?: boolean;
+    /** Set on the `<g>` of a boolean group's children, which follows the path
+     *  the group draws: the operation that path is of them. Written as
+     *  `data-weasel-boolean`; `parseSvg` keeps such a `<g>` hidden even without
+     *  `keepHidden`. */
+    boolean?: BooleanShapeOp;
     /** Opaque per-element bag for declared namespaces. See `NamespaceMeta`. */
     meta?: NamespaceMeta;
 }
@@ -498,8 +503,10 @@ declare function warmSvg(nodes: readonly SvgNode[], opts?: Pick<SerializeOptions
  *
  * The tile's shapes are written for any SVG consumer to render, and the spec
  * itself goes on a `data-weasel-tile` attribute, which weasel reads back
- * rather than reverse-engineering it from geometry. A `texture` paint has no
- * vector form and exports as nothing, with a warning.
+ * rather than reverse-engineering it from geometry. An `image` paint is a
+ * pattern holding one `<image>` that fills the tile, the form other editors
+ * write a bitmap pattern in too, and is read back from that structure. A
+ * `texture` paint has no vector form and exports as nothing, with a warning.
  */
 
 /**
@@ -632,13 +639,24 @@ interface SvgKitTreeNode {
     /** 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 kit's `SceneNode.consumesChildren`: a boolean group, written as the
+     *  path it derives then a hidden `<g>` of its children (`SvgGroupNode.boolean`). */
+    consumesChildren?: boolean;
 }
 /** The read side of a scene that {@link svgNodesFromKit} walks. A kit
- *  `Scene` is one as it stands. */
+ *  `Scene` is one as it stands. With `composition`, a node's pose is stored in
+ *  the frame of the nearest container above it that defines one, as a scene's
+ *  is; without, every pose is world. */
 interface SvgKitTree<TId extends string = string> {
     readonly roots: readonly TId[];
     childrenOf(id: TId): readonly TId[];
     get(id: TId): SvgKitTreeNode | undefined;
+    readonly composition?: {
+        compose(parent: never, child: never): unknown;
+    };
+    /** The path a node derives, in the frame its children are stored in. A kit
+     *  `Scene` needs none: its document is read for it. */
+    derivedPathOf?(id: TId): Path | null;
 }
 /** Options for {@link svgNodesFromKit}. */
 interface SvgNodesFromKitOptions<TId extends string = string> {
@@ -697,7 +715,8 @@ type SvgDraftPose = SvgDraftBounds & {
  * 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
+ * Leaf data targets the kit's built-in painters. Poses are world AABBs, which
+ * an inserter makes local to their containers' frames, 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
@@ -732,6 +751,10 @@ type SvgSceneDraft<TData = Record<string, unknown>> = {
     data: TData;
     clip?: NodeClip;
     hidden?: true;
+    /** A boolean group of the drafts under it, as `svgNodesFromKit` writes one: give it core's
+     *  `booleanGroupFields()` and this as `data.boolean`. Its data's `path` is the result as the
+     *  file drew it, which the derivation replaces. */
+    boolean?: BooleanShapeOp;
 };
 /** A leaf `SvgNode`: everything but a group. */
 type SvgLeafNode = Exclude<SvgNode, SvgGroupNode>;
@@ -783,6 +806,8 @@ declare function strokeDataFromSvg(stroke: SvgStroke | undefined, box: SvgDraftB
  *
  * `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.
+ * A boolean group `svgNodesFromKit` wrote is drafted as a mark with `boolean`,
+ * its operands under it and shown.
  */
 declare function svgNodesToKitDrafts<TData = Record<string, unknown>>(input: ParseResult | readonly SvgNode[], nextId: (source: SvgNode) => string, options?: SvgNodesToKitDraftsOptions<TData>): SvgSceneDraft<TData>[];