107 lines
4.5 KiB
Markdown
107 lines
4.5 KiB
Markdown
|
# 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 |
|