svg-path-commander 2.1.10 → 2.2.0

package/AGENTS.md

@@ -0,0 +1,106 @@
+# AGENTS.md — SVGPathCommander
+
+## Project Overview
+
+SVGPathCommander v2.2.0 — TypeScript library for manipulating SVG `<path>` `d` attributes. Works in browser and Node.js.
+
+## Commands
+
+```bash
+pnpm install          # Install dependencies
+pnpm dev              # Serve docs on localhost:3000
+pnpm test             # Run all tests (vitest + happy-dom)
+pnpm test-ui          # Run tests with UI
+pnpm test -- -t "Test name"    # Run a single test by name
+pnpm test -- class.test.ts     # Run a single test file
+pnpm lint             # Deno lint + tsc type check
+pnpm lint:ts          # Deno lint only
+pnpm fix:ts           # Deno lint --fix
+pnpm format           # Deno format
+pnpm build            # Build with tsdown
+pnpm check:ts         # tsc --noEmit (type check only)
+```
+
+## Tech Stack
+
+- **Language:** TypeScript (strict, ES2020 target, `allowImportingTsExtensions`)
+- **Package manager:** pnpm (v10.33.0)
+- **Build:** tsdown (ESM + UMD outputs)
+- **Test:** Vitest + happy-dom (Istanbul coverage)
+- **Lint/Format:** Deno (`deno lint`, `deno fmt`)
+- **Dependency:** `@thednp/dommatrix` (DOMMatrix shim)
+
+## Source Structure (`src/`)
+
+| Directory | Purpose |
+|---|---|
+| `index.ts` | Main entry — exports SVGPathCommander class + all types |
+| `main.ts` | SVGPathCommander class (core, chainable instance methods) |
+| `types.ts` | TypeScript type definitions (PathCommand, PathSegment, PathArray, etc.) |
+| `interface.ts` | Interfaces (Options, TransformObject, PathBBox, shape attrs) |
+| `util.ts` | Re-export of all static methods (tree-shakeable entry) |
+| `convert/` | Path format conversion (absolute, relative, curve, string) |
+| `parser/` | SVG path string tokenizer/scanner |
+| `process/` | Manipulation algorithms (normalize, optimize, reverse, transform, etc.) |
+| `math/` | Low-level math (bezier, cubic, quad, line, arc, polygon tools) |
+| `morph/` | Path morphing (equalize, split, sample, classify, match) |
+| `util/` | Query helpers (bbox, length, point-at-length, intersection, etc.) |
+| `options/` | Default configuration |
+
+## Code Conventions
+
+### Imports
+- Use `.ts` extension on all imports: `import { foo } from "./bar.ts"`
+- Path alias `~/*` maps to `src/` (e.g., `import SVGPathCommander from '~/index'`)
+- Group imports: external libs → internal modules → types
+- Use `import type` for type-only imports
+
+### Formatting & Linting
+- **No comments** unless explicitly asked
+- Run `pnpm format` then `pnpm lint:ts` before committing
+- Deno formatter and linter enforced (`deno fmt`, `deno lint`)
+
+### TypeScript
+- Strict mode enabled — no `any`, no implicit `any`
+- `noUnusedLocals` and `noUnusedParameters` enforced
+- `noImplicitReturns` enforced
+- `allowImportingTsExtensions` — always include `.ts` in imports
+- Use `type` aliases for unions, `interface` for object shapes
+
+### Naming Conventions
+- **Classes:** PascalCase (`SVGPathCommander`, `PathParser`)
+- **Functions/Methods:** camelCase (`parsePathString`, `normalizePath`)
+- **Types:** PascalCase ending in semantic suffix (`PathArray`, `NormalSegment`, `IteratorCallback`)
+- **Command types:** Suffix with `Command`/`Segment` (`AbsoluteCommand`, `MSegment`)
+- **Constants:** camelCase for module-level constants (`defaultOptions`, `distanceEpsilon`)
+- **Test descriptions:** Start with `Test` (`Test init with no parameter`)
+
+### Error Handling
+- Throw `TypeError` with descriptive message for invalid inputs
+- Use the shared `error` prefix from `~/util/error.ts`
+- Validate inputs early, fail fast with clear messages
+- Static methods return safe defaults for empty/invalid input (e.g., `getPathBBox('')`)
+
+### Class Design
+- Instance methods are chainable — always `return this`
+- Expose functionality as both instance methods and static methods
+- Use getters for computed properties (`get bbox()`, `get length()`)
+- Instance options validated in constructor with fallback to `defaultOptions`
+
+### Testing
+- Tests run with happy-dom (headless browser simulation)
+- Fixtures in `test/fixtures/`
+- Two test files: `test/class.test.ts` (instance API), `test/static.test.ts` (static methods)
+- Tests render actual SVG and verify `d` attribute output
+- Use `vi.waitFor()` for async DOM queries (timeout: 200ms)
+- Use `expect().to.deep.equal()` for object comparison, `expect().to.equal()` for primitives
+- Coverage provider: Istanbul
+
+## Build Outputs
+
+| File | Description |
+|---|---|
+| `dist/index.min.js` | UMD bundle (minified, browser-ready, includes dommatrix) |
+| `dist/index.js` | ESM bundle (tree-shakeable, neutral platform) |
+| `dist/util.js` | Static methods only (tree-shakeable) |
+| `dist/index.d.ts` | Type declarations |

package/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+## [2.2.0] - 2026-04-06
+
+### Added
+- **Path intersection** — `pathsIntersection()`, `boundingBoxIntersect()`, `isPointInsideBBox()`
+- **Path equalization** — `equalizePaths()`, `equalizeSegments()` for matching segment counts
+- Full JSDoc coverage with `@param`, `@returns`, `@example` tags
+- New demo page for path morphing
+- `polyonArea` utility
+- `isMultiPath()`, `isClosedPath()`, `isPolygonArray()` and `isPolylineArray` utilities
+- CHANGELOG.md and AGENTS.md
+
+### Removed
+- badge workflow and script in package.json
+
+### Fixed
+- **pathToCurve** inconsistencies
+- reworked all exports as named exports
+
+### Changed
+- Added a separate export for utilities in `svg-path-commander/util`
+- Migrated test runner from Playwright to happy-dom
+- updated tests
+- tsdown bundler

package/README.md

@@ -1,12 +1,11 @@
 # SVGPathCommander
+
 [![Coverage Status](https://coveralls.io/repos/github/thednp/svg-path-commander/badge.svg)](https://coveralls.io/github/thednp/svg-path-commander)
 [![ci](https://github.com/thednp/svg-path-commander/actions/workflows/ci.yml/badge.svg)](https://github.com/thednp/svg-path-commander/actions/workflows/ci.yml)
 [![NPM Version](https://img.shields.io/npm/v/svg-path-commander.svg)](https://www.npmjs.com/package/svg-path-commander)
 [![NPM Downloads](https://img.shields.io/npm/dm/svg-path-commander.svg)](http://npm-stat.com/charts.html?svg-path-commander)
 [![jsDeliver](https://img.shields.io/jsdelivr/npm/hw/svg-path-commander)](https://www.jsdelivr.com/package/npm/svg-path-commander)
-[![typescript version](https://img.shields.io/badge/typescript-5.7.3-brightgreen)](https://www.typescriptlang.org/)
-[![vitest version](https://img.shields.io/badge/vitest-3.0.5-brightgreen)](https://vitest.dev/)
-[![vite version](https://img.shields.io/badge/vite-6.1.0-brightgreen)](https://vitejs.dev/)
+
 
 ![image](./docs/assets/SVGPathCommander.svg)
 
@@ -40,10 +39,17 @@ This library is available on [CDN](https://www.jsdelivr.com/package/npm/svg-path
 
 ```
 npm install svg-path-commander
+# or pnpm/bun/deno add svg-path-commander
 ```
 
 
 # CDN
+Version 2.2.0+
+```html
+<script src="https://cdn.jsdelivr.net/npm/svg-path-commander/dist/index.min.js">
+```
+
+Versions before 2.2.0
 ```html
 <script src="https://cdn.jsdelivr.net/npm/svg-path-commander/dist/svg-path-commander.js">
 ```
@@ -230,6 +236,42 @@ const myPathBBox = SVGPathCommander.getPathBBox('M0 0L50 0L25 50z');
 // result => {width: 50, height: 50, x: 0, y: 0, x2: 50, y2: 50, cx: 25, cy: 25, cz: 75}
 ```
 
+Find intersection points between two paths:
+```js
+const count = SVGPathCommander.pathsIntersection(
+  'M0 50C0 0,100 0,100 50',
+  'M50 0C100 0,100 100,50 100',
+  true
+);
+// result => 1
+
+const points = SVGPathCommander.pathsIntersection(
+  'M0 50C0 0,100 0,100 50',
+  'M50 0C100 0,100 100,50 100',
+  false
+);
+// result => [{ x: 50, y: 25, t1: 0.5, t2: 0.5 }]
+```
+
+Equalize two paths for morphing (single subpath):
+```js
+const [eq1, eq2] = SVGPathCommander.equalizeSegments(
+  'M0 0L100 0L50 100Z',
+  'M0 0L100 0L100 100L0 100Z'
+);
+// eq1.length === eq2.length — ready for morphing
+```
+
+Equalize two paths for morphing (single or multi subpath):
+```js
+const [eq1, eq2] = SVGPathCommander.equalizePaths(
+  'M0 0L100 0L50 100Z',
+  'M0 0L100 0L100 100L0 100Z',
+  { close: true }
+);
+// Both paths now have the same number of segments
+```
+
 # WIKI
 For developer guidelines, and a complete list of static methods, head over to the [wiki pages](https://github.com/thednp/svg-path-commander/wiki).