svg-path-commander 2.0.10 → 2.1.0

package/package.json

@@ -2,7 +2,7 @@
   "name": "svg-path-commander",
   "author": "thednp",
   "license": "MIT",
-  "version": "2.0.10",
+  "version": "2.1.0",
   "description": "Modern TypeScript tools for SVG",
   "source": "./src/index.ts",
   "main": "./dist/svg-path-commander.js",
@@ -38,28 +38,24 @@
   },
   "homepage": "http://thednp.github.io/svg-path-commander",
   "devDependencies": {
-    "@bahmutov/cypress-esbuild-preprocessor": "^2.2.2",
-    "@cypress/code-coverage": "^3.12.44",
-    "@types/istanbul-lib-instrument": "^1.7.7",
     "@typescript-eslint/eslint-plugin": "^5.62.0",
     "@typescript-eslint/parser": "^5.62.0",
-    "cypress": "^13.13.2",
+    "@vitest/browser": "^2.1.2",
+    "@vitest/coverage-istanbul": "^2.1.2",
+    "@vitest/ui": "^2.1.2",
     "dts-bundle-generator": "^9.5.1",
-    "eslint": "^8.57.0",
+    "eslint": "^8.57.1",
     "eslint-plugin-jsdoc": "^46.10.1",
     "eslint-plugin-prefer-arrow": "^1.2.3",
     "eslint-plugin-prettier": "^4.2.1",
-    "istanbul-lib-coverage": "^3.2.2",
-    "istanbul-lib-instrument": "^5.2.1",
-    "ncp": "^2.0.0",
-    "nyc": "^17.0.0",
+    "playwright": "^1.47.2",
     "prettier": "^2.8.8",
-    "rimraf": "^6.0.1",
-    "typescript": "^5.5.4",
-    "vite": "^5.4.0"
+    "typescript": "^5.6.2",
+    "vite": "^5.4.8",
+    "vitest": "^2.1.2"
   },
   "dependencies": {
-    "@thednp/dommatrix": "^2.0.7"
+    "@thednp/dommatrix": "^2.0.8"
   },
   "engines": {
     "node": ">=16",
@@ -67,17 +63,19 @@
   },
   "scripts": {
     "pre-test": "pnpm clean-coverage",
-    "badges": "npx -p dependency-version-badge update-badge typescript cypress eslint prettier vite",
-    "test": "pnpm pre-test && cypress run",
-    "cypress": "pnpm pre-test && npx cypress open",
-    "clean-coverage": "rimraf coverage .nyc_output",
-    "coverage:report": "nyc report --reporter=lcov --reporter=json --reporter=text --reporter=json-summary",
+    "badges": "npx -p dependency-version-badge update-badge typescript eslint prettier vitest vite",
+    "dev": "vite serve docs --port 3000",
+    "test": "pnpm pre-test && vitest --config vitest.config.mts",
+    "test-ui": "pnpm pre-test && vitest --config vitest.config-ui.mts --browser=chrome",
+    "clean-coverage": "rm -rf coverage .nyc_output",
     "format": "prettier --write \"src/**/*.ts\"",
+    "lint": "pnpm lint:ts && pnpm check:ts",
     "fix:ts": "eslint src --config .eslintrc.cjs --fix",
     "lint:ts": "eslint src --config .eslintrc.cjs",
-    "build": "pnpm lint:ts && pnpm build-vite && pnpm build-ts",
-    "build-vite": "vite build && pnpm build-docs",
+    "check:ts": "tsc --noEmit",
+    "build": "pnpm lint && pnpm build-vite && pnpm build-ts",
+    "build-vite": "vite build && pnpm copy-docs",
     "build-ts": "dts-bundle-generator --config ./dts.config.ts",
-    "build-docs": "ncp dist/svg-path-commander.js docs/svg-path-commander.js && ncp dist/svg-path-commander.js.map docs/svg-path-commander.js.map"
+    "copy-docs": "cp dist/svg-path-commander.js docs/svg-path-commander.js && cp dist/svg-path-commander.js.map docs/svg-path-commander.js.map"
   }
 }

package/src/convert/pathToAbsolute.ts

@@ -25,7 +25,7 @@ import type {
 const pathToAbsolute = (pathInput: string | PathArray): AbsoluteArray => {
   /* istanbul ignore else */
   if (isAbsoluteArray(pathInput)) {
-    return [...pathInput];
+    return pathInput.slice(0) as AbsoluteArray;
   }
 
   const path = parsePathString(pathInput);

package/src/convert/pathToCurve.ts

@@ -18,7 +18,7 @@ import { CurveArray, PathArray, PathCommand } from '../types';
 const pathToCurve = (pathInput: string | PathArray): CurveArray => {
   /* istanbul ignore else */
   if (isCurveArray(pathInput)) {
-    return [...pathInput];
+    return pathInput.slice(0) as CurveArray;
   }
 
   const path = normalizePath(pathInput);

package/src/convert/pathToRelative.ts

@@ -20,7 +20,7 @@ import isRelativeArray from '../util/isRelativeArray';
 const pathToRelative = (pathInput: string | PathArray): RelativeArray => {
   /* istanbul ignore else */
   if (isRelativeArray(pathInput)) {
-    return [...pathInput];
+    return pathInput.slice(0) as RelativeArray;
   }
 
   const path = parsePathString(pathInput);

package/src/index.ts

@@ -1,5 +1,7 @@
 import { PathArray, TransformObjectValues } from './types';
-import { Options, PathBBox, TransformEntries, TransformObject } from './interface';
+import type { Options, TransformEntries, TransformObject } from './interface';
+export * from './types';
+export * from './interface';
 import defaultOptions from './options/options';
 
 import error from './parser/error';
@@ -14,7 +16,7 @@ import getPathArea from './util/getPathArea';
 import getTotalLength from './util/getTotalLength';
 import getDrawDirection from './util/getDrawDirection';
 import getPointAtLength from './util/getPointAtLength';
-import pathLengthFactory from './util/pathLengthFactory';
+import pathFactory from './util/pathFactory';
 
 import getPropertiesAtLength from './util/getPropertiesAtLength';
 import getPropertiesAtPoint from './util/getPropertiesAtPoint';
@@ -41,6 +43,7 @@ import reversePath from './process/reversePath';
 import normalizePath from './process/normalizePath';
 import transformPath from './process/transformPath';
 import splitCubic from './process/splitCubic';
+import replaceArc from './process/replaceArc';
 
 import pathToAbsolute from './convert/pathToAbsolute';
 import pathToRelative from './convert/pathToRelative';
@@ -55,7 +58,7 @@ import pathToString from './convert/pathToString';
  *
  * @class
  * @author thednp <https://github.com/thednp/svg-path-commander>
- * @returns {SVGPathCommander} a new SVGPathCommander instance
+ * @returns a new SVGPathCommander instance
  */
 class SVGPathCommander {
   // bring main utilities to front
@@ -66,7 +69,7 @@ class SVGPathCommander {
   public static getTotalLength = getTotalLength;
   public static getDrawDirection = getDrawDirection;
   public static getPointAtLength = getPointAtLength;
-  public static pathLengthFactory = pathLengthFactory;
+  public static pathFactory = pathFactory;
   public static getPropertiesAtLength = getPropertiesAtLength;
   public static getPropertiesAtPoint = getPropertiesAtPoint;
   public static polygonLength = polygonLength;
@@ -87,6 +90,7 @@ class SVGPathCommander {
   public static roundPath = roundPath;
   public static splitPath = splitPath;
   public static splitCubic = splitCubic;
+  public static replaceArc = replaceArc;
   public static optimizePath = optimizePath;
   public static reverseCurve = reverseCurve;
   public static reversePath = reversePath;
@@ -103,8 +107,8 @@ class SVGPathCommander {
 
   /**
    * @constructor
-   * @param {string} pathValue the path string
-   * @param {any} config instance options
+   * @param pathValue the path string
+   * @param config instance options
    */
   constructor(pathValue: string, config?: Partial<Options>) {
     const instanceOptions = config || {};
@@ -115,13 +119,8 @@ class SVGPathCommander {
     }
 
     const segments = parsePathString(pathValue);
-    // if (typeof segments === 'string') {
-    //   throw TypeError(segments);
-    // }
-
     this.segments = segments;
-
-    const { width, height, cx, cy, cz } = this.getBBox();
+    const { width, height, cx, cy, cz } = this.bbox;
 
     // set instance options.round
     const { round: roundOption, origin: originOption } = instanceOptions;
@@ -138,7 +137,8 @@ class SVGPathCommander {
 
     // set instance options.origin
     // the SVGPathCommander class will always override the default origin
-    let origin: [number, number, number];
+    let origin = [cx, cy, cz] as [number, number, number];
+    /* istanbul ignore else @preserve */
     if (Array.isArray(originOption) && originOption.length >= 2) {
       const [originX, originY, originZ] = originOption.map(Number);
       origin = [
@@ -146,8 +146,6 @@ class SVGPathCommander {
         !Number.isNaN(originY) ? originY : cy,
         !Number.isNaN(originZ) ? originZ : cz,
       ];
-    } else {
-      origin = [cx, cy, cz];
     }
 
     this.round = round;
@@ -155,6 +153,12 @@ class SVGPathCommander {
 
     return this;
   }
+  get bbox() {
+    return getPathBBox(this.segments);
+  }
+  get length() {
+    return getTotalLength(this.segments);
+  }
 
   /**
    * Returns the path bounding box, equivalent to native `path.getBBox()`.
@@ -162,8 +166,8 @@ class SVGPathCommander {
    * @public
    * @returns the pathBBox
    */
-  getBBox(): PathBBox {
-    return getPathBBox(this.segments);
+  getBBox() {
+    return this.bbox;
   }
 
   /**
@@ -173,7 +177,7 @@ class SVGPathCommander {
    * @returns the path total length
    */
   getTotalLength() {
-    return getTotalLength(this.segments);
+    return this.length;
   }
 
   /**
@@ -184,7 +188,7 @@ class SVGPathCommander {
    * @param length the length
    * @returns the requested point
    */
-  getPointAtLength(length: number): { x: number; y: number } {
+  getPointAtLength(length: number) {
     return getPointAtLength(this.segments, length);
   }
 
@@ -236,23 +240,22 @@ class SVGPathCommander {
     const subPath = split.length > 1 ? split : false;
 
     const absoluteMultiPath = subPath
-      ? [...subPath].map((x, i) => {
+      ? subPath.map((x, i) => {
           if (onlySubpath) {
-            // return i ? reversePath(x) : parsePathString(x);
-            return i ? reversePath(x) : [...x];
+            return i ? reversePath(x) : x.slice(0);
           }
           return reversePath(x);
         })
-      : [...segments];
+      : segments.slice(0);
 
-    let path = [];
+    let path = [] as unknown as PathArray;
     if (subPath) {
-      path = absoluteMultiPath.flat(1);
+      path = absoluteMultiPath.flat(1) as PathArray;
     } else {
       path = onlySubpath ? segments : reversePath(segments);
     }
 
-    this.segments = [...path] as PathArray;
+    this.segments = path.slice(0) as PathArray;
     return this;
   }
 
@@ -306,6 +309,7 @@ class SVGPathCommander {
     } = this;
     const transform = {} as TransformObjectValues;
     for (const [k, v] of Object.entries(source) as TransformEntries) {
+      // istanbul ignore else @preserve
       if (k === 'skew' && Array.isArray(v)) {
         transform[k] = v.map(Number) as [number, number];
       } else if ((k === 'rotate' || k === 'translate' || k === 'origin' || k === 'scale') && Array.isArray(v)) {

package/src/interface.ts

@@ -1,51 +1,51 @@
 import type { PathSegment } from './types';
 
-export interface SegmentProperties {
+export type SegmentProperties = {
   segment: PathSegment;
   index: number;
   length: number;
   lengthAtSegment: number;
   [key: string]: any;
-}
+};
 
-export interface PointProperties {
+export type PointProperties = {
   closest: {
     x: number;
     y: number;
   };
   distance: number;
   segment?: SegmentProperties;
-}
+};
 
-export interface LineAttr {
+export type LineAttr = {
   type: 'line';
   x1: number;
   y1: number;
   x2: number;
   y2: number;
   [key: string]: string | number;
-}
-export interface PolyAttr {
+};
+export type PolyAttr = {
   type: 'polygon' | 'polyline';
   points: string;
   [key: string]: string | number;
-}
-export interface CircleAttr {
+};
+export type CircleAttr = {
   type: 'circle';
   cx: number;
   cy: number;
   r: number;
   [key: string]: string | number;
-}
-export interface EllipseAttr {
+};
+export type EllipseAttr = {
   type: 'ellipse';
   cx: number;
   cy: number;
   rx: number;
   ry?: number;
   [key: string]: string | number | undefined;
-}
-export interface RectAttr {
+};
+export type RectAttr = {
   type: 'rect';
   width: number;
   height: number;
@@ -54,14 +54,14 @@ export interface RectAttr {
   rx?: number;
   ry?: number;
   [key: string]: string | number | undefined;
-}
-export interface GlyphAttr {
+};
+export type GlyphAttr = {
   type: 'glyph';
   d: string;
   [key: string]: string | number;
-}
+};
 
-export interface ShapeParams {
+export type ShapeParams = {
   line: ['x1', 'y1', 'x2', 'y2'];
   circle: ['cx', 'cy', 'r'];
   ellipse: ['cx', 'cy', 'rx', 'ry'];
@@ -69,9 +69,9 @@ export interface ShapeParams {
   polygon: ['points'];
   polyline: ['points'];
   glyph: ['d'];
-}
+};
 
-export interface PathBBox {
+export type PathBBox = {
   width: number;
   height: number;
   x: number;
@@ -81,13 +81,13 @@ export interface PathBBox {
   cx: number;
   cy: number;
   cz: number;
-}
-export interface SegmentLimits {
+};
+export type SegmentLimits = {
   min: { x: number; y: number };
   max: { x: number; y: number };
-}
+};
 
-export interface ParserParams {
+export type ParserParams = {
   x1: number;
   y1: number;
   x2: number;
@@ -96,34 +96,34 @@ export interface ParserParams {
   y: number;
   qx: number | null;
   qy: number | null;
-}
+};
 
-export interface LengthFactory {
+export type LengthFactory = {
   length: number;
   point: { x: number; y: number };
   min: { x: number; y: number };
   max: { x: number; y: number };
-}
+};
 
-export interface Options {
+export type Options = {
   round: 'auto' | 'off' | number;
   origin: number[];
-}
+};
 
-export interface PathTransform {
+export type PathTransform = {
   s: PathSegment;
   c: string;
   x: number;
   y: number;
-}
+};
 
-export interface TransformObject {
+export type TransformObject = {
   translate: number | number[];
   rotate: number | number[];
   scale: number | number[];
   skew: number | number[];
   origin: number[];
-}
+};
 
 export type TransformProps = keyof TransformObject;
 export type TransformEntries = [TransformProps, TransformObject[TransformProps]][];

package/src/math/arcTools.ts

@@ -0,0 +1,217 @@
+import { default as getLineSegmentProperties } from './lineTools';
+import type { Point } from '../types';
+
+/**
+ * Returns the Arc segment length.
+ * @param rx radius along X axis
+ * @param ry radius along Y axis
+ * @param theta the angle in radians
+ * @returns the arc length
+ */
+const ellipticalArcLength = (rx: number, ry: number, theta: number) => {
+  const halfTheta = theta / 2;
+  const sinHalfTheta = Math.sin(halfTheta);
+  const cosHalfTheta = Math.cos(halfTheta);
+  const term1 = rx ** 2 * sinHalfTheta ** 2;
+  const term2 = ry ** 2 * cosHalfTheta ** 2;
+  const arcLength = Math.sqrt(term1 + term2) * theta;
+  return Math.abs(arcLength);
+};
+
+/**
+ * Returns the most extreme points in an Arc segment.
+ * @param x Center X coordinate of the ellipse arc
+ * @param y Center Y coordinate of the ellipse arc
+ * @param rx Radius on the X axis of the ellipse
+ * @param ry Radius on the Y axis of the ellipse
+ * @param rotation The ellipse rotation angle in radians
+ * @param startAngle The ellipse start angle in radians
+ * @param endAngle The ellipse end angle in radians
+ * @see https://stackoverflow.com/questions/87734/how-do-you-calculate-the-axis-aligned-bounding-box-of-an-ellipse
+ */
+const minmax = (
+  x: number,
+  y: number,
+  rx: number,
+  ry: number,
+  rotation: number,
+  startAngle: number,
+  endAngle: number,
+) => {
+  const { cos, sin, min, max } = Math;
+  const cosRotation = cos(rotation);
+  const sinRotation = sin(rotation);
+
+  // Rotate parametric equations
+  const xRotated = (t: number) => {
+    return x + rx * cos(t) * cosRotation - ry * sin(t) * sinRotation;
+  };
+  const yRotated = (t: number) => {
+    return y + ry * sin(t) * cosRotation + rx * cos(t) * sinRotation;
+  };
+
+  // Evaluate at start and end angles
+  const startX = xRotated(startAngle);
+  const startY = yRotated(startAngle);
+  const endX = xRotated(endAngle);
+  const endY = yRotated(endAngle);
+
+  // Find minimum and maximum x and y values
+  // Return AABB
+  return {
+    min: { x: min(startX, endX), y: min(startY, endY) },
+    max: { x: max(startX, endX), y: max(startY, endY) },
+  };
+};
+
+/**
+ * Returns the angle between two points.
+ * @param v0 starting point
+ * @param v1 ending point
+ * @returns the angle
+ */
+const angleBetween = (v0: Point, v1: Point) => {
+  const { x: v0x, y: v0y } = v0;
+  const { x: v1x, y: v1y } = v1;
+  const p = v0x * v1x + v0y * v1y;
+  const n = Math.sqrt((v0x ** 2 + v0y ** 2) * (v1x ** 2 + v1y ** 2));
+  const sign = v0x * v1y - v0y * v1x < 0 ? -1 : 1;
+  const angle = sign * Math.acos(p / n);
+
+  return angle;
+};
+
+/**
+ * Returns properties for an Arc segment.
+ *
+ * @param x1 the starting point X
+ * @param y1 the starting point Y
+ * @param c1x the first control point X
+ * @param c1y the first control point Y
+ * @param c2x the second control point X
+ * @param c2y the second control point Y
+ * @param x2 the ending point X
+ * @param y2 the ending point Y
+ * @param distance a [0-1] ratio
+ * @returns properties specific to Arc segmentas well as the segment length, point at length and the bounding box
+ */
+const getSegmentProperties = (
+  x1: number,
+  y1: number,
+  RX: number,
+  RY: number,
+  angle: number,
+  LAF: number,
+  SF: number,
+  x: number,
+  y: number,
+  distance?: number,
+) => {
+  const { abs, sin, cos, sqrt, PI } = Math;
+  let rx = abs(RX);
+  let ry = abs(RY);
+  const xRot = ((angle % 360) + 360) % 360;
+  const xRotRad = xRot * (PI / 180);
+
+  if (x1 === x && y1 === y) {
+    return {
+      point: { x, y },
+      length: 0,
+      bbox: { min: { x, y }, max: { x, y } },
+    };
+  }
+
+  if (rx === 0 || ry === 0) {
+    return getLineSegmentProperties(x1, y1, x, y, distance);
+  }
+
+  const dx = (x1 - x) / 2;
+  const dy = (y1 - y) / 2;
+
+  const transformedPoint = {
+    x: cos(xRotRad) * dx + sin(xRotRad) * dy,
+    y: -sin(xRotRad) * dx + cos(xRotRad) * dy,
+  };
+
+  const radiiCheck = transformedPoint.x ** 2 / rx ** 2 + transformedPoint.y ** 2 / ry ** 2;
+
+  if (radiiCheck > 1) {
+    rx *= sqrt(radiiCheck);
+    ry *= sqrt(radiiCheck);
+  }
+
+  const cSquareNumerator = rx ** 2 * ry ** 2 - rx ** 2 * transformedPoint.y ** 2 - ry ** 2 * transformedPoint.x ** 2;
+  const cSquareRootDenom = rx ** 2 * transformedPoint.y ** 2 + ry ** 2 * transformedPoint.x ** 2;
+
+  let cRadicand = cSquareNumerator / cSquareRootDenom;
+  cRadicand = cRadicand < 0 ? 0 : cRadicand;
+  const cCoef = (LAF !== SF ? 1 : -1) * sqrt(cRadicand);
+  const transformedCenter = {
+    x: cCoef * ((rx * transformedPoint.y) / ry),
+    y: cCoef * (-(ry * transformedPoint.x) / rx),
+  };
+
+  const center = {
+    x: cos(xRotRad) * transformedCenter.x - sin(xRotRad) * transformedCenter.y + (x1 + x) / 2,
+    y: sin(xRotRad) * transformedCenter.x + cos(xRotRad) * transformedCenter.y + (y1 + y) / 2,
+  };
+
+  const startVector = {
+    x: (transformedPoint.x - transformedCenter.x) / rx,
+    y: (transformedPoint.y - transformedCenter.y) / ry,
+  };
+
+  const startAngle = angleBetween({ x: 1, y: 0 }, startVector);
+
+  const endVector = {
+    x: (-transformedPoint.x - transformedCenter.x) / rx,
+    y: (-transformedPoint.y - transformedCenter.y) / ry,
+  };
+
+  let sweepAngle = angleBetween(startVector, endVector);
+  if (!SF && sweepAngle > 0) {
+    sweepAngle -= 2 * PI;
+  } else if (SF && sweepAngle < 0) {
+    sweepAngle += 2 * PI;
+  }
+  sweepAngle %= 2 * PI;
+
+  const alpha = startAngle + sweepAngle * (distance || 0);
+  const endAngle = startAngle + sweepAngle;
+  const ellipseComponentX = rx * cos(alpha);
+  const ellipseComponentY = ry * sin(alpha);
+
+  const point = {
+    x: cos(xRotRad) * ellipseComponentX - sin(xRotRad) * ellipseComponentY + center.x,
+    y: sin(xRotRad) * ellipseComponentX + cos(xRotRad) * ellipseComponentY + center.y,
+  };
+
+  // to be used later
+  // point.ellipticalArcStartAngle = startAngle;
+  // point.ellipticalArcEndAngle = startAngle + sweepAngle;
+  // point.ellipticalArcAngle = alpha;
+
+  // point.ellipticalArcCenter = center;
+  // point.resultantRx = rx;
+  // point.resultantRy = ry;
+  // point.length = ellipticalArcLength(rx, ry, sweepAngle);
+  // point.box = minmax(center.x, center.y, rx, ry, xRotRad, startAngle, startAngle + sweepAngle);
+
+  return {
+    point,
+    center,
+    angle: alpha,
+    startAngle,
+    endAngle,
+    radiusX: rx,
+    radiusY: ry,
+    get length() {
+      return ellipticalArcLength(rx, ry, sweepAngle);
+    },
+    get bbox() {
+      return minmax(center.x, center.y, rx, ry, xRotRad, startAngle, startAngle + sweepAngle);
+    },
+  };
+};
+
+export default getSegmentProperties;