modern-path2d 1.7.0 → 1.8.0

package/dist/index.mjs

@@ -1,4 +1,5 @@
 import earcut from 'earcut';
+import polygonClipping from 'polygon-clipping';
 
 function drawPoint(ctx, x, y, options = {}) {
   const { radius = 1 } = options;
@@ -297,6 +298,63 @@ class BoundingBox {
   }
 }
 
+function flatRingToPairs(r) {
+  const ring = [];
+  for (let i = 0; i < r.length; i += 2) {
+    ring.push([r[i], r[i + 1]]);
+  }
+  const first = ring[0];
+  const last = ring[ring.length - 1];
+  if (first && last && (first[0] !== last[0] || first[1] !== last[1])) {
+    ring.push([first[0], first[1]]);
+  }
+  return ring;
+}
+function ringsToGeom(rings) {
+  const valid = rings.filter((r) => r.length >= 6).map(flatRingToPairs);
+  if (!valid.length) {
+    return [];
+  }
+  let geom = [[valid[0]]];
+  for (let i = 1; i < valid.length; i++) {
+    geom = polygonClipping.xor(geom, [[valid[i]]]);
+  }
+  return geom;
+}
+function geomToRings(geom) {
+  const out = [];
+  for (const poly of geom) {
+    for (const ring of poly) {
+      const flat = [];
+      for (const [x, y] of ring) {
+        flat.push(x, y);
+      }
+      out.push(flat);
+    }
+  }
+  return out;
+}
+function polygonBoolean(op, ringsA, ringsB) {
+  const a = ringsToGeom(ringsA);
+  const b = ringsToGeom(ringsB);
+  let res;
+  switch (op) {
+    case "union":
+      res = polygonClipping.union(a, b);
+      break;
+    case "intersection":
+      res = polygonClipping.intersection(a, b);
+      break;
+    case "difference":
+      res = polygonClipping.difference(a, b);
+      break;
+    case "xor":
+      res = polygonClipping.xor(a, b);
+      break;
+  }
+  return geomToRings(res);
+}
+
 function catmullRom(t, p0, p1, p2, p3) {
   const v0 = (p2 - p0) * 0.5;
   const v1 = (p3 - p1) * 0.5;
@@ -861,22 +919,35 @@ function quadraticBezier(t, p0, p1, p2) {
   return quadraticBezierP0(t, p0) + quadraticBezierP1(t, p1) + quadraticBezierP2(t, p2);
 }
 
+function resolveLineJoin(join) {
+  switch (join) {
+    case "round":
+    case "bevel":
+    case "miter":
+      return join;
+    default:
+      return "miter";
+  }
+}
+function resolveLineStyle(style) {
+  return {
+    width: style?.strokeWidth ?? 1,
+    alignment: 0.5,
+    join: resolveLineJoin(style?.strokeLinejoin),
+    cap: style?.strokeLinecap ?? "butt",
+    miterLimit: style?.strokeMiterlimit ?? 10
+  };
+}
 const closePointEps = 1e-4;
 const curveEps = 1e-4;
 function strokeTriangulate(points, options = {}) {
   const {
     vertices = [],
     indices = [],
-    lineStyle = {
-      alignment: 0.5,
-      cap: "butt",
-      join: "miter",
-      width: 1,
-      miterLimit: 10
-    },
     flipAlignment = false,
     closed = true
   } = options;
+  const lineStyle = options.lineStyle ?? resolveLineStyle(options.style);
   const eps = closePointEps;
   if (points.length === 0) {
     return { vertices, indices };
@@ -2704,6 +2775,22 @@ class Curve {
   getControlPointRefs() {
     return [];
   }
+  /**
+   * Reverse the traversal direction in place (start ↔ end, same geometry). The base
+   * implementation reverses the order of the control-point *values*, which is correct for
+   * line / Bézier / spline primitives whose {@link getControlPointRefs} order matches their
+   * parametric order. {@link RoundCurve} (angle-based) and composites (child order) override it.
+   */
+  reverse() {
+    const refs = this.getControlPointRefs();
+    const n = refs.length;
+    const snapshot = refs.map((p) => p.clone());
+    for (let i = 0; i < n; i++) {
+      refs[i].copyFrom(snapshot[n - 1 - i]);
+    }
+    this.invalidate();
+    return this;
+  }
   applyTransform(transform) {
     const isFunction = typeof transform === "function";
     this.getControlPointRefs().forEach((p) => {
@@ -2831,6 +2918,22 @@ class Curve {
   getTangentAt(u, output) {
     return this.getTangent(this.getUToTMapping(u), output);
   }
+  /**
+   * PathKit-style sample at an absolute arc-length `distance` along the curve: the point, the unit
+   * tangent, and the tangent `angle` in radians. `distance` is clamped to `[0, getLength()]`, so
+   * passing `0`/`getLength()` always yields the endpoints. See {@link PathMeasure} for a wrapper.
+   */
+  getPosTan(distance) {
+    const length = this.getLength();
+    const u = length > 0 ? Math.min(Math.max(distance / length, 0), 1) : 0;
+    const t = this.getUToTMapping(u);
+    const tangent = this.getTangent(t);
+    return {
+      position: this.getPoint(t),
+      tangent,
+      angle: Math.atan2(tangent.y, tangent.x)
+    };
+  }
   getNormal(t, output = new Vector2()) {
     this.getTangent(t, output);
     return output.set(-output.y, output.x).normalize();
@@ -2926,10 +3029,28 @@ class Curve {
       options
     );
   }
+  /**
+   * Whether this curve forms a closed loop (its outline should be stroked without end caps,
+   * stitching the last vertex back to the first). The base test is purely geometric — the first
+   * sampled vertex coincides with the last. Curves that close without a duplicated endpoint
+   * (a full-revolution {@link RoundCurve}, rectangles, polygons) override this.
+   */
+  isClosed() {
+    const v = this._getCachedAdaptiveVertices();
+    const len = v.length;
+    if (len < 6) {
+      return false;
+    }
+    const eps = 1e-4;
+    return Math.abs(v[0] - v[len - 2]) < eps && Math.abs(v[1] - v[len - 1]) < eps;
+  }
   strokeTriangulate(options) {
     return strokeTriangulate(
       this.getAdaptiveVertices(),
-      options
+      {
+        ...options,
+        closed: options?.closed ?? this.isClosed()
+      }
     );
   }
   toCommands() {
@@ -3024,6 +3145,22 @@ class RoundCurve extends Curve {
   isClockwise() {
     return this.clockwise;
   }
+  /**
+   * A circle/ellipse arc is closed when it sweeps (at least) a full revolution — the sampled
+   * outline does not duplicate the start vertex, so the geometric first==last test in the base
+   * class would wrongly report a full circle as open and leave a seam gap in the stroke.
+   */
+  isClosed() {
+    return Math.abs(this.endAngle - this.startAngle) >= Math.PI * 2 - 1e-9 || super.isClosed();
+  }
+  reverse() {
+    const { startAngle, endAngle } = this;
+    this.startAngle = endAngle;
+    this.endAngle = startAngle;
+    this.clockwise = !this.clockwise;
+    this.invalidate();
+    return this;
+  }
   _getDeltaAngle() {
     const PI_2 = Math.PI * 2;
     let deltaAngle = this.endAngle - this.startAngle;
@@ -3280,9 +3417,25 @@ class RoundCurve extends Curve {
     return output;
   }
   getAdaptiveVertices(output = []) {
-    if (this.startAngle === 0 && this.endAngle === Math.PI * 2) {
+    const PI2 = Math.PI * 2;
+    if (this.startAngle === 0 && this.endAngle === PI2) {
       return this._getAdaptiveVerticesByCircle(output);
     }
+    if (Math.abs(this.endAngle - this.startAngle) >= PI2 - 1e-9) {
+      const tmp = this._getAdaptiveVerticesByCircle([]);
+      const n = tmp.length / 2;
+      if (this.endAngle > this.startAngle) {
+        for (let i = 0; i < tmp.length; i++) {
+          output.push(tmp[i]);
+        }
+      } else {
+        output.push(tmp[0], tmp[1]);
+        for (let i = n - 1; i >= 1; i--) {
+          output.push(tmp[i * 2], tmp[i * 2 + 1]);
+        }
+      }
+      return output;
+    }
     return this._getAdaptiveVerticesByArc(output);
   }
   copyFrom(source) {
@@ -3492,6 +3645,15 @@ class LineCurve extends Curve {
   getControlPointRefs() {
     return [this.p1, this.p2];
   }
+  // Swap endpoint *references* (not values) so corner Vector2s shared with adjacent
+  // segments stay intact and simply re-associate with the reversed segment.
+  reverse() {
+    const { p1, p2 } = this;
+    this.p1 = p2;
+    this.p2 = p1;
+    this.invalidate();
+    return this;
+  }
   getAdaptiveVertices(output = []) {
     output.push(
       this.p1.x,
@@ -3655,6 +3817,16 @@ class CompositeCurve extends Curve {
     });
     return output;
   }
+  /**
+   * A composite is closed when its single child is closed (e.g. a lone full-circle arc), or when
+   * its assembled outline returns to its start (rectangles, polygons, multi-segment loops).
+   */
+  isClosed() {
+    if (this.curves.length === 1) {
+      return this.curves[0].isClosed();
+    }
+    return super.isClosed();
+  }
   strokeTriangulate(options) {
     if (this.curves.length === 1) {
       return this.curves[0].strokeTriangulate(options);
@@ -3662,6 +3834,13 @@ class CompositeCurve extends Curve {
       return super.strokeTriangulate(options);
     }
   }
+  /** Reverse the sub-curve order and reverse each sub-curve, so the whole outline runs backwards. */
+  reverse() {
+    this.curves.reverse();
+    this.curves.forEach((curve) => curve.reverse());
+    this.invalidate();
+    return this;
+  }
   getFillVertices(options) {
     if (this.curves.length === 1) {
       return this.curves[0].getFillVertices(options);
@@ -3757,6 +3936,16 @@ class CubicBezierCurve extends Curve {
   getControlPointRefs() {
     return [this.p1, this.cp1, this.cp2, this.p2];
   }
+  // Swap endpoint and control-point references; keeps shared corner Vector2s intact.
+  reverse() {
+    const { p1, cp1, cp2, p2 } = this;
+    this.p1 = p2;
+    this.cp1 = cp2;
+    this.cp2 = cp1;
+    this.p2 = p1;
+    this.invalidate();
+    return this;
+  }
   _solveQuadratic(a, b, c) {
     if (Math.abs(a) < 1e-12) {
       if (Math.abs(b) < 1e-12)
@@ -3917,6 +4106,14 @@ class QuadraticBezierCurve extends Curve {
   getControlPointRefs() {
     return [this.p1, this.cp, this.p2];
   }
+  // Swap endpoint references (cp is symmetric); keeps shared corner Vector2s intact.
+  reverse() {
+    const { p1, p2 } = this;
+    this.p1 = p2;
+    this.p2 = p1;
+    this.invalidate();
+    return this;
+  }
   getAdaptiveVertices(output = []) {
     return getAdaptiveQuadraticBezierCurvePoints(
       this.p1.x,
@@ -4118,6 +4315,11 @@ class SplineCurve extends Curve {
   getControlPointRefs() {
     return this.points;
   }
+  reverse() {
+    this.points.reverse();
+    this.invalidate();
+    return this;
+  }
   copyFrom(source) {
     super.copyFrom(source);
     this.points = [];
@@ -4154,6 +4356,22 @@ class CurvePath extends CompositeCurve {
     this.addCommands(svgPathDataToCommands(data));
     return this;
   }
+  /**
+   * A sub-path is closed if it was explicitly closed (`autoClose`, i.e. a `Z`/`closePath`), or if
+   * it forms a geometric loop / wraps a single closed primitive (handled by the base class).
+   */
+  isClosed() {
+    return this.autoClose || super.isClosed();
+  }
+  /** Reverse direction, then refresh the {@link startPoint}/{@link currentPoint} cursors. */
+  reverse() {
+    super.reverse();
+    if (this.curves.length) {
+      this.startPoint = this.getPoint(0);
+      this.currentPoint = this.getPoint(1);
+    }
+    return this;
+  }
   _closeVertices(output) {
     if (this.autoClose && output.length >= 4 && (output[0] !== output[output.length - 2] && output[1] !== output[output.length - 1])) {
       output.push(output[0], output[1]);
@@ -4590,6 +4808,51 @@ class Path2D extends CompositeCurve {
     const fillRule = options.fillRule ?? this.style.fillRule ?? "nonzero";
     return pointInPolygons(point, this._getRings(), fillRule);
   }
+  /** Build a `Path2D` from flat rings (`[x0,y0,…]` per sub-path); closed-and-filled as sub-paths. */
+  static fromRings(rings, style = {}) {
+    const path = new Path2D(void 0, style);
+    for (const ring of rings) {
+      if (ring.length < 6) {
+        continue;
+      }
+      let end = ring.length;
+      if (ring[0] === ring[end - 2] && ring[1] === ring[end - 1]) {
+        end -= 2;
+      }
+      path.moveTo(ring[0], ring[1]);
+      for (let i = 2; i < end; i += 2) {
+        path.lineTo(ring[i], ring[i + 1]);
+      }
+      path.closePath();
+    }
+    return path;
+  }
+  /**
+   * Boolean (path) operation against another path, returning a NEW `Path2D` whose outline is the
+   * polygonal result. Curves are sampled before clipping, so the result is a polygonal
+   * approximation (see {@link polygonBoolean}). The result inherits this path's `style` unless
+   * overridden via `style`. Holes are emitted as oppositely-wound sub-paths (nonzero fill).
+   */
+  booleanOp(op, other, style) {
+    const rings = polygonBoolean(op, this._getRings(), other._getRings());
+    return Path2D.fromRings(rings, { ...this.style, ...style });
+  }
+  /** `this ∪ other` — the combined filled area. */
+  union(other, style) {
+    return this.booleanOp("union", other, style);
+  }
+  /** `this ∩ other` — only the overlapping area. */
+  intersection(other, style) {
+    return this.booleanOp("intersection", other, style);
+  }
+  /** `this − other` — this path with `other` cut away. */
+  difference(other, style) {
+    return this.booleanOp("difference", other, style);
+  }
+  /** `this ⊕ other` — areas covered by exactly one of the two paths. */
+  xor(other, style) {
+    return this.booleanOp("xor", other, style);
+  }
   /**
    * Test whether a point lies on this path's stroke. A hit on any sub-path counts.
    *
@@ -4689,7 +4952,7 @@ class Path2D extends CompositeCurve {
   }
   drawTo(ctx, style = {}) {
     style = { ...this.style, ...style };
-    const { fill = "#000", stroke = "none" } = style;
+    const { fill = "#000", stroke = "none", fillRule = "nonzero" } = style;
     ctx.beginPath();
     ctx.save();
     setCanvasContext(ctx, style);
@@ -4697,7 +4960,7 @@ class Path2D extends CompositeCurve {
       path.drawTo(ctx);
     });
     if (fill !== "none") {
-      ctx.fill();
+      ctx.fill(fillRule);
     }
     if (stroke !== "none") {
       ctx.stroke();
@@ -4903,6 +5166,44 @@ ${content}
   }
 }
 
+class PathMeasure {
+  constructor(curve) {
+    this.curve = curve;
+  }
+  /** Total arc length of the path. */
+  getLength() {
+    return this.curve.getLength();
+  }
+  /** Whether the path forms a closed loop (see {@link Curve.isClosed}). */
+  isClosed() {
+    return this.curve.isClosed();
+  }
+  /** Point + unit tangent + tangent angle at an absolute arc-length `distance` (clamped). */
+  getPosTan(distance) {
+    return this.curve.getPosTan(distance);
+  }
+  /** Point at an absolute arc-length `distance` (clamped to `[0, getLength()]`). */
+  getPosition(distance) {
+    return this.curve.getPosTan(distance).position;
+  }
+  /** Point + tangent at a normalized progress `t ∈ [0, 1]` along the path. */
+  getPosTanAtProgress(t) {
+    return this.curve.getPosTan(this.getLength() * t);
+  }
+  /**
+   * Evenly sample the path into `count + 1` {@link PosTan} entries (arc-length spaced), e.g. to
+   * lay glyphs along a path or drive an `animate(progress)`-style traversal.
+   */
+  sample(count = 100) {
+    const length = this.getLength();
+    const out = [];
+    for (let i = 0; i <= count; i++) {
+      out.push(this.curve.getPosTan(length * i / count));
+    }
+    return out;
+  }
+}
+
 class FFDControlGrid {
   constructor(rows, cols, width = 1, height = 1) {
     this.rows = rows;
@@ -4958,4 +5259,4 @@ function applyFFD(point, grid, width = grid.width, height = grid.height) {
   point.set(x, y);
 }
 
-export { ArcCurve, BoundingBox, CompositeCurve, CubicBezierCurve, Curve, CurvePath, EllipseCurve, EquilateralPolygonCurve, FFDControlGrid, LineCurve, PI, PI_2, Path2D, Path2DSet, PolygonCurve, QuadraticBezierCurve, RectangleCurve, RoundRectangleCurve, SplineCurve, Transform2D, Vector2, applyFFD, catmullRom, cubicBezier, drawPoint, fillTriangulate, getAdaptiveCubicBezierCurvePoints, getAdaptiveQuadraticBezierCurvePoints, getDirectedArea, getIntersectionPoint, nonzeroFillRule, parseArcCommand, parseCssArg, parseCssArgs, parseCssFunctions, parsePathDataArgs, pointInPolygon, pointInPolygons, pointToPolylineDistance, pointToSegmentDistance, quadraticBezier, setCanvasContext, strokeTriangulate, svgPathCommandsAddToPath2D, svgPathCommandsToData, svgPathDataToCommands, svgToDom, svgToPath2DSet, toKebabCase };
+export { ArcCurve, BoundingBox, CompositeCurve, CubicBezierCurve, Curve, CurvePath, EllipseCurve, EquilateralPolygonCurve, FFDControlGrid, LineCurve, PI, PI_2, Path2D, Path2DSet, PathMeasure, PolygonCurve, QuadraticBezierCurve, RectangleCurve, RoundRectangleCurve, SplineCurve, Transform2D, Vector2, applyFFD, catmullRom, cubicBezier, drawPoint, fillTriangulate, getAdaptiveCubicBezierCurvePoints, getAdaptiveQuadraticBezierCurvePoints, getDirectedArea, getIntersectionPoint, nonzeroFillRule, parseArcCommand, parseCssArg, parseCssArgs, parseCssFunctions, parsePathDataArgs, pointInPolygon, pointInPolygons, pointToPolylineDistance, pointToSegmentDistance, polygonBoolean, quadraticBezier, resolveLineStyle, setCanvasContext, strokeTriangulate, svgPathCommandsAddToPath2D, svgPathCommandsToData, svgPathDataToCommands, svgToDom, svgToPath2DSet, toKebabCase };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "modern-path2d",
   "type": "module",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "packageManager": "pnpm@9.15.1",
   "description": "A Path2D library, fully compatible with Web Path2D, with additional support for triangulate、animation、deformation etc.",
   "author": "wxm",
@@ -56,7 +56,8 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "earcut": "^3.0.2"
+    "earcut": "^3.0.2",
+    "polygon-clipping": "^0.15.7"
   },
   "devDependencies": {
     "@antfu/eslint-config": "^8.2.0",