Initial Commit

packages/devtools/docs/compress-svg/src/plugins/cleanup-attrs/cleanup-attrs.md

@@ -0,0 +1,67 @@
+# cleanup-attrs — Remove Redundant SVG Attributes
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## Purpose
+
+`cleanupAttrs` strips attributes whose values match the SVG specification defaults and trims whitespace from all remaining attribute values. Many SVG authoring tools emit default attribute values explicitly (e.g. `fill="black"`, `opacity="1"`) that carry no information. Removing them reduces file size without changing the rendered output.
+
+## Features
+
+- Removes attributes whose trimmed value matches the SVG default (sourced from `DEFAULT_ATTRS` in constants)
+- Removes attributes with empty string values after trimming
+- Trims leading/trailing whitespace from all attribute values
+- Passes non-element nodes through unchanged
+- Included in `PRESET_DEFAULT`, `PRESET_SAFE`, and `PRESET_AGGRESSIVE`
+
+## Usage: Basic Example
+
+```typescript
+import { compressSvg } from '@suaveplan/compress-svg';
+import { cleanupAttrs } from '@suaveplan/compress-svg/plugins/cleanup-attrs';
+
+const svg = '<svg><rect fill="black" opacity="1" x="10" fill-opacity="1"/></svg>';
+const result = compressSvg(svg, { plugins: [cleanupAttrs] });
+// result.data === '<svg><rect x="10"/></svg>'
+```
+
+## Usage: Advanced Example
+
+```typescript
+import { cleanupAttrs } from '@suaveplan/compress-svg/plugins/cleanup-attrs';
+
+const node = {
+  type: 'element' as const,
+  name: 'rect',
+  attributes: { fill: 'red', opacity: '1', style: '', x: '  10  ' },
+  children: [],
+};
+const result = cleanupAttrs.apply(node, { floatPrecision: 3, transformPrecision: 5 });
+// result.attributes === { fill: 'red', x: '10' }
+// opacity removed (default), style removed (empty), x trimmed
+```
+
+## API Reference
+
+### `cleanupAttrs: SvgPlugin`
+
+| Property | Value |
+|----------|-------|
+| `name`   | `"cleanupAttrs"` |
+| `apply`  | `(node, options) => SvgNode \| null` |
+
+Iterates over each attribute:
+
+1. Trims the value.
+2. Drops the attribute if the trimmed value is empty.
+3. Drops the attribute if `DEFAULT_ATTRS[key] === trimmedValue`.
+4. Otherwise keeps the attribute with the trimmed value.
+
+**Returns the node unchanged** for non-element nodes.
+
+**Default attributes removed** (partial list): `fill="black"`, `fill-opacity="1"`, `stroke-opacity="1"`, `opacity="1"`, `display="inline"`, `visibility="visible"`, `overflow="visible"`.
+
+## Implementation Notes
+
+The `DEFAULT_ATTRS` constant is defined centrally in `src/constants/index.ts` so all plugins share the same definition. The plugin always returns a new node object with a fresh `attributes` record, even if no attributes were removed — callers should not rely on reference equality after the plugin runs. Only exact-string matches against the default values are checked; no numeric normalisation is performed (e.g. `opacity="1.0"` is not recognised as a default).