@emasoft/svg-matrix 1.0.6 → 1.0.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (8) hide show
  1. package/README.md +231 -2
  2. package/bin/svg-matrix.js +1000 -0
  3. package/package.json +12 -2
  4. package/scripts/bootstrap_repo.sh +99 -0
  5. package/scripts/postinstall.js +252 -0
  6. package/src/clip-path-resolver.js +2 -1
  7. package/src/index.js +15 -1
  8. package/src/logger.js +302 -0
package/README.md CHANGED
@@ -31,6 +31,11 @@ High-precision matrix, vector, and SVG transformation library for JavaScript. Bu
31
31
  - Text-to-path conversion with font support
32
32
  - Browser verification against Chrome's native W3C SVG2 implementation
33
33
 
34
+ ## Requirements
35
+
36
+ - **Node.js 24.0.0** or higher (ES modules, modern JavaScript features)
37
+ - **Playwright** (optional) - for browser verification features
38
+
34
39
  ## Precision
35
40
 
36
41
  | Scenario | Float Error | This Library | Improvement |
@@ -57,14 +62,210 @@ npm install @emasoft/svg-matrix
57
62
  import { Matrix, Vector, Transforms2D, Transforms3D, SVGFlatten } from '@emasoft/svg-matrix';
58
63
  ```
59
64
 
60
- ### CDN
65
+ ### Browser Usage (CDN)
66
+
67
+ You can use this library directly in a web browser without installing anything. Just add a `<script>` tag to your HTML file.
68
+
69
+ **What is a CDN?** A CDN (Content Delivery Network) hosts the library files so you can load them directly in your browser. No `npm install` needed!
70
+
71
+ #### Option 1: esm.sh (Recommended)
72
+
73
+ Best for modern browsers. Automatically handles dependencies.
74
+
75
+ ```html
76
+ <!DOCTYPE html>
77
+ <html>
78
+ <head>
79
+ <title>SVG Matrix Example</title>
80
+ </head>
81
+ <body>
82
+ <script type="module">
83
+ // Import the modules you need
84
+ import { Matrix, Vector, Transforms2D } from 'https://esm.sh/@emasoft/svg-matrix';
85
+
86
+ // Now you can use them!
87
+ const rotation = Transforms2D.rotate(Math.PI / 4); // 45 degrees
88
+ const [x, y] = Transforms2D.applyTransform(rotation, 10, 0);
89
+
90
+ console.log(`Point (10, 0) rotated 45 degrees = (${x}, ${y})`);
91
+ </script>
92
+ </body>
93
+ </html>
94
+ ```
95
+
96
+ #### Option 2: unpkg
97
+
98
+ Another reliable CDN option.
61
99
 
62
100
  ```html
63
101
  <script type="module">
64
- import { Matrix, Vector, Transforms2D } from 'https://esm.sh/@emasoft/svg-matrix';
102
+ import { SVGFlatten, GeometryToPath } from 'https://unpkg.com/@emasoft/svg-matrix/src/index.js';
103
+
104
+ // Convert a circle to a path
105
+ const pathData = GeometryToPath.circleToPathData(100, 100, 50);
106
+ console.log(pathData);
65
107
  </script>
66
108
  ```
67
109
 
110
+ #### Option 3: jsDelivr
111
+
112
+ Popular CDN with good caching.
113
+
114
+ ```html
115
+ <script type="module">
116
+ import { Matrix, Vector } from 'https://cdn.jsdelivr.net/npm/@emasoft/svg-matrix/src/index.js';
117
+
118
+ const v = Vector.from([1, 2, 3]);
119
+ const w = Vector.from([4, 5, 6]);
120
+ console.log('Dot product:', v.dot(w).toString());
121
+ </script>
122
+ ```
123
+
124
+ #### Pin to a Specific Version
125
+
126
+ To avoid breaking changes, pin to a specific version:
127
+
128
+ ```html
129
+ <!-- esm.sh with version -->
130
+ <script type="module">
131
+ import { Transforms2D } from 'https://esm.sh/@emasoft/svg-matrix@1.0.7';
132
+ </script>
133
+
134
+ <!-- unpkg with version -->
135
+ <script type="module">
136
+ import { Matrix } from 'https://unpkg.com/@emasoft/svg-matrix@1.0.7/src/index.js';
137
+ </script>
138
+
139
+ <!-- jsDelivr with version -->
140
+ <script type="module">
141
+ import { Vector } from 'https://cdn.jsdelivr.net/npm/@emasoft/svg-matrix@1.0.7/src/index.js';
142
+ </script>
143
+ ```
144
+
145
+ #### Complete Working Example
146
+
147
+ Save this as `example.html` and open it in your browser:
148
+
149
+ ```html
150
+ <!DOCTYPE html>
151
+ <html>
152
+ <head>
153
+ <title>SVG Matrix - Complete Example</title>
154
+ <style>
155
+ body { font-family: sans-serif; padding: 20px; }
156
+ svg { border: 1px solid #ccc; }
157
+ pre { background: #f5f5f5; padding: 10px; }
158
+ </style>
159
+ </head>
160
+ <body>
161
+ <h1>SVG Matrix Demo</h1>
162
+
163
+ <h2>Original Circle</h2>
164
+ <svg width="200" height="200">
165
+ <circle id="original" cx="100" cy="100" r="40" fill="blue" opacity="0.5"/>
166
+ </svg>
167
+
168
+ <h2>Transformed (rotate 45 + scale 1.5)</h2>
169
+ <svg width="200" height="200">
170
+ <path id="transformed" fill="red" opacity="0.5"/>
171
+ </svg>
172
+
173
+ <h2>Generated Path Data</h2>
174
+ <pre id="output"></pre>
175
+
176
+ <script type="module">
177
+ import {
178
+ Transforms2D,
179
+ GeometryToPath,
180
+ SVGFlatten
181
+ } from 'https://esm.sh/@emasoft/svg-matrix';
182
+
183
+ // Step 1: Convert circle to path
184
+ const circlePath = GeometryToPath.circleToPathData(100, 100, 40);
185
+
186
+ // Step 2: Create a combined transform (rotate 45 degrees, then scale 1.5x)
187
+ const transform = Transforms2D.scale(1.5)
188
+ .mul(Transforms2D.rotate(Math.PI / 4));
189
+
190
+ // Step 3: Apply transform to the path
191
+ const transformedPath = SVGFlatten.transformPathData(circlePath, transform);
192
+
193
+ // Step 4: Display the result
194
+ document.getElementById('transformed').setAttribute('d', transformedPath);
195
+ document.getElementById('output').textContent = transformedPath;
196
+ </script>
197
+ </body>
198
+ </html>
199
+ ```
200
+
201
+ #### Troubleshooting
202
+
203
+ **"Cannot use import statement outside a module"**
204
+ Make sure you have `type="module"` in your script tag:
205
+ ```html
206
+ <script type="module"> <!-- This is required! -->
207
+ ```
208
+
209
+ **CORS errors when opening HTML file directly**
210
+ Some browsers block CDN imports when opening files with `file://`. Solutions:
211
+ 1. Use a local server: `npx serve .` or `python -m http.server`
212
+ 2. Or use a code playground like CodePen, JSFiddle, or StackBlitz
213
+
214
+ **Want to use with older browsers?**
215
+ This library requires ES modules (modern browsers). For IE11 or very old browsers, you'll need a bundler like Webpack or Rollup.
216
+
217
+ ## CLI
218
+
219
+ The library includes a command-line interface for batch processing SVG files.
220
+
221
+ ```bash
222
+ # Process single file
223
+ svg-matrix flatten input.svg -o output.svg
224
+
225
+ # Batch process folder
226
+ svg-matrix flatten ./svgs/ -o ./output/
227
+
228
+ # Process files from list
229
+ svg-matrix flatten --list files.txt -o ./output/
230
+
231
+ # Convert shapes to paths
232
+ svg-matrix convert input.svg -o output.svg
233
+
234
+ # Normalize paths to cubic Beziers
235
+ svg-matrix normalize input.svg -o output.svg
236
+
237
+ # Show SVG file info
238
+ svg-matrix info input.svg
239
+
240
+ # Show help
241
+ svg-matrix help
242
+ ```
243
+
244
+ ### CLI Options
245
+
246
+ | Option | Description |
247
+ |--------|-------------|
248
+ | `-o, --output <path>` | Output file or directory |
249
+ | `-l, --list <file>` | Read input files from text file |
250
+ | `-r, --recursive` | Process directories recursively |
251
+ | `-p, --precision <n>` | Decimal precision (default: 6) |
252
+ | `-f, --force` | Overwrite existing files |
253
+ | `-n, --dry-run` | Show what would be done |
254
+ | `-q, --quiet` | Suppress all output except errors |
255
+ | `-v, --verbose` | Enable verbose/debug output |
256
+ | `--log-file <path>` | Write log to file |
257
+
258
+ ### File List Format
259
+
260
+ Create a text file with one path per line:
261
+
262
+ ```
263
+ # This is a comment
264
+ ./folder1/file1.svg
265
+ ./folder2/file2.svg
266
+ ./entire-folder/
267
+ ```
268
+
68
269
  ## Quick Start
69
270
 
70
271
  ```js
@@ -447,6 +648,34 @@ import {
447
648
  } from '@emasoft/svg-matrix';
448
649
  ```
449
650
 
651
+ ### Logging
652
+
653
+ Control library logging output:
654
+
655
+ ```js
656
+ import { Logger, LogLevel, setLogLevel, enableFileLogging } from '@emasoft/svg-matrix';
657
+
658
+ // Suppress all logging
659
+ setLogLevel(LogLevel.SILENT);
660
+
661
+ // Enable only errors
662
+ setLogLevel(LogLevel.ERROR);
663
+
664
+ // Enable warnings and errors (default)
665
+ setLogLevel(LogLevel.WARN);
666
+
667
+ // Enable all logging including debug
668
+ setLogLevel(LogLevel.DEBUG);
669
+
670
+ // Write logs to file
671
+ enableFileLogging('/path/to/log.txt');
672
+
673
+ // Direct Logger access
674
+ Logger.level = LogLevel.INFO;
675
+ Logger.warn('Custom warning');
676
+ Logger.debug('Debug info');
677
+ ```
678
+
450
679
  ## License
451
680
 
452
681
  MIT