@emasoft/svg-matrix 1.0.8 → 1.0.10

package/README.md

@@ -54,12 +54,164 @@ node test/benchmark-precision.js
 
 ## Installation
 
+### Node.js (Local Installation)
+
+**What does "local installation" mean?** It means downloading the library to your computer so you can use it in your Node.js projects. This is what most developers do.
+
+#### Step 1: Install the package
+
+Open your terminal and run:
+
 ```bash
 npm install @emasoft/svg-matrix
 ```
 
+This downloads the library into a folder called `node_modules` in your project.
+
+#### Step 2: Create a JavaScript file
+
+Create a new file called `example.js` in your project folder.
+
+#### Step 3: Import what you need
+
+There are two ways to import the library:
+
+**Way 1: Pick only what you need (recommended)**
+
+This is like ordering specific items from a menu:
+
+```js
+// example.js
+
+// Import only the modules you need
+import { Matrix, Vector, Transforms2D } from '@emasoft/svg-matrix';
+
+// Now you can use them directly
+const v = Vector.from([1, 2, 3]);
+const rotation = Transforms2D.rotate(Math.PI / 4);  // 45 degrees
+
+console.log('Vector:', v.toNumberArray());
+console.log('Rotation matrix created!');
+```
+
+**Way 2: Import everything at once**
+
+This is like getting the entire toolbox:
+
 ```js
-import { Matrix, Vector, Transforms2D, Transforms3D, SVGFlatten } from '@emasoft/svg-matrix';
+// example.js
+
+// Import EVERYTHING as one big object called "SVGMatrix"
+import * as SVGMatrix from '@emasoft/svg-matrix';
+
+// Now use SVGMatrix.ModuleName to access each tool
+const v = SVGMatrix.Vector.from([1, 2, 3]);
+const m = SVGMatrix.Matrix.identity(3);
+const rotation = SVGMatrix.Transforms2D.rotate(Math.PI / 4);
+const pathData = SVGMatrix.GeometryToPath.circleToPathData(100, 100, 50);
+
+// See everything that's available:
+console.log('Available modules:', Object.keys(SVGMatrix));
+```
+
+**What's inside the toolbox?** When you import everything, you get:
+- `SVGMatrix.Matrix` - For matrix math
+- `SVGMatrix.Vector` - For vector math
+- `SVGMatrix.Transforms2D` - For 2D rotations, translations, scaling
+- `SVGMatrix.Transforms3D` - For 3D transformations
+- `SVGMatrix.SVGFlatten` - For flattening SVG transforms
+- `SVGMatrix.GeometryToPath` - For converting shapes to paths
+- `SVGMatrix.PolygonClip` - For polygon boolean operations
+- ...and many more!
+
+#### Step 4: Run your code
+
+```bash
+node example.js
+```
+
+#### Complete Working Example
+
+Save this as `my-first-example.js`:
+
+```js
+// my-first-example.js
+// A complete example showing the main features
+
+import {
+  Matrix,
+  Vector,
+  Transforms2D,
+  GeometryToPath,
+  SVGFlatten
+} from '@emasoft/svg-matrix';
+
+console.log('=== Vector Example ===');
+const v = Vector.from([1, 2, 3]);
+const w = Vector.from([4, 5, 6]);
+console.log('Vector v:', v.toNumberArray());
+console.log('Vector w:', w.toNumberArray());
+console.log('Dot product (v · w):', v.dot(w).toString());
+
+console.log('\n=== Matrix Example ===');
+const A = Matrix.from([[1, 2], [3, 4]]);
+console.log('Matrix A:', A.toNumberArray());
+console.log('Determinant:', A.determinant().toString());
+
+console.log('\n=== Transform Example ===');
+// Create a transform: move 100 right, rotate 45°, scale 2x
+const transform = Transforms2D.translation(100, 0)
+  .mul(Transforms2D.rotate(Math.PI / 4))
+  .mul(Transforms2D.scale(2));
+
+// Apply to a point
+const [x, y] = Transforms2D.applyTransform(transform, 10, 0);
+console.log(`Point (10, 0) after transform: (${x.toFixed(2)}, ${y.toFixed(2)})`);
+
+console.log('\n=== SVG Path Example ===');
+// Convert a circle to a path
+const circlePath = GeometryToPath.circleToPathData(0, 0, 50);
+console.log('Circle as path:', circlePath.substring(0, 50) + '...');
+
+console.log('\nDone! Everything works!');
+```
+
+Run it:
+```bash
+node my-first-example.js
+```
+
+#### Troubleshooting
+
+**"Cannot use import statement outside a module"**
+
+Add `"type": "module"` to your `package.json`:
+
+```json
+{
+  "name": "my-project",
+  "type": "module"
+}
+```
+
+Or rename your file from `.js` to `.mjs`.
+
+**Using older Node.js syntax (require)?**
+
+This library uses modern ES modules. If you have old code using `require()`:
+
+```js
+// OLD WAY (doesn't work directly)
+// const { Matrix } = require('@emasoft/svg-matrix');  // ❌ Error!
+
+// NEW WAY (use dynamic import)
+async function main() {
+  const { Matrix, Vector } = await import('@emasoft/svg-matrix');
+
+  const v = Vector.from([1, 2, 3]);
+  console.log(v.norm().toString());
+}
+main();
 ```
 
 ### Browser Usage (CDN)
@@ -121,6 +273,43 @@ Popular CDN with good caching.
 </script>
 ```
 
+#### Import Everything at Once
+
+**What if I don't know what I need yet?** You can import the entire library as one big object. This is like getting the whole toolbox instead of picking individual tools.
+
+```html
+<script type="module">
+  // Import EVERYTHING as one object called "SVGMatrix"
+  // The "* as" means "everything as"
+  import * as SVGMatrix from 'https://esm.sh/@emasoft/svg-matrix';
+
+  // Now use SVGMatrix.ModuleName to access each tool
+  const v = SVGMatrix.Vector.from([1, 2, 3]);
+  const m = SVGMatrix.Matrix.identity(3);
+  const rotation = SVGMatrix.Transforms2D.rotate(Math.PI / 4);
+  const [x, y] = SVGMatrix.Transforms2D.applyTransform(rotation, 10, 0);
+
+  // See everything that's available:
+  console.log('All modules:', Object.keys(SVGMatrix));
+  // Output: ['Matrix', 'Vector', 'Transforms2D', 'Transforms3D', 'SVGFlatten', ...]
+</script>
+```
+
+**What's inside?** Here's everything you get:
+
+| Module | What it does |
+|--------|--------------|
+| `SVGMatrix.Matrix` | Matrix math (multiply, inverse, determinant) |
+| `SVGMatrix.Vector` | Vector math (add, dot product, cross product) |
+| `SVGMatrix.Transforms2D` | 2D transforms (rotate, scale, translate) |
+| `SVGMatrix.Transforms3D` | 3D transforms (rotate around axes) |
+| `SVGMatrix.SVGFlatten` | Flatten SVG transforms into paths |
+| `SVGMatrix.GeometryToPath` | Convert shapes (circle, rect) to paths |
+| `SVGMatrix.PolygonClip` | Boolean operations on polygons |
+| `SVGMatrix.ClipPathResolver` | Resolve SVG clipPath elements |
+| `SVGMatrix.BrowserVerify` | Verify against browser's SVG engine |
+| `SVGMatrix.Logger` | Control library logging |
+
 #### Pin to a Specific Version
 
 To avoid breaking changes, pin to a specific version:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@emasoft/svg-matrix",
-  "version": "1.0.8",
+  "version": "1.0.10",
   "description": "Arbitrary-precision matrix, vector and affine transformation library for JavaScript using decimal.js",
   "type": "module",
   "main": "src/index.js",

package/src/index.js

@@ -49,7 +49,7 @@ import { Logger, LogLevel, setLogLevel, getLogLevel as getLoggerLevel, enableFil
  * Library version
  * @constant {string}
  */
-export const VERSION = '1.0.8';
+export const VERSION = '1.0.10';
 
 /**
  * Default precision for path output (decimal places)