Initial Commit

packages/devtools/docs/compress-svg/src/plugins/convert-path-data/convert-path-data.md

@@ -0,0 +1,59 @@
+# convert-path-data — Reduce Float Precision in SVG Path Data
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## Purpose
+
+`convertPathData` reduces the number of decimal places in the `d` attribute of `<path>` elements to the configured `floatPrecision`. Path coordinates output by design tools routinely carry many more decimal places than the display resolution requires — coordinates like `M 10.000000001 20.000000001` are visually indistinguishable from `M 10 20`. Rounding reduces the serialised size of path data proportionally to the number of coordinates and original precision.
+
+## Features
+
+- Rounds all numeric values in the `d` attribute to `floatPrecision` decimal places
+- Handles all path commands: `M`, `L`, `C`, `S`, `Q`, `T`, `A`, `Z` and their lowercase variants
+- Supports scientific notation in coordinates (`1.5e-4`)
+- Passes through non-`<path>` elements unchanged
+- Passes through `<path>` elements that have no `d` attribute
+- Passes through non-element nodes unchanged
+
+## Usage: Basic Example
+
+```typescript
+import { compressSvg } from '@suaveplan/compress-svg';
+import { convertPathData } from '@suaveplan/compress-svg/plugins/convert-path-data';
+
+const svg = '<svg><path d="M 10.12345678 20.98765432 L 30 40"/></svg>';
+const result = compressSvg(svg, { plugins: [convertPathData], floatPrecision: 3 });
+// result.data contains 'd="M 10.123 20.988 L 30 40"'
+```
+
+## Usage: Advanced Example
+
+```typescript
+import { convertPathData } from '@suaveplan/compress-svg/plugins/convert-path-data';
+
+const node = {
+  type: 'element' as const,
+  name: 'path',
+  attributes: { d: 'C 1.111111 2.222222 3.333333 4.444444 5.555555 6.666666' },
+  children: [],
+};
+
+const result = convertPathData.apply(node, { floatPrecision: 2, transformPrecision: 5 });
+// result.attributes.d === 'C 1.11 2.22 3.33 4.44 5.56 6.67'
+```
+
+## API Reference
+
+### `convertPathData: SvgPlugin`
+
+| Property | Value |
+|----------|-------|
+| `name`   | `"convertPathData"` |
+| `apply`  | `(node, options) => SvgNode \| null` |
+
+Reads `options.floatPrecision` (integer, 0–20). Applies `Number.toFixed(precision)` to every numeric token in the `d` attribute string, then converts back to the minimal string representation via `parseFloat(n.toFixed(p)).toString()` to strip trailing zeros.
+
+## Implementation Notes
+
+The rounding regex matches the full range of SVG numeric literals including optional sign, decimal point, and scientific-notation exponent. Each matched token is parsed as a 64-bit float, rounded, and re-stringified; no attempt is made to normalise the command letters or collapse redundant moves. The plugin operates purely on the string level, making it independent of any path-command parsing library and keeping the implementation small and auditable.