jigsawpuzzlegame 1.0.11 → 1.0.13

package/README.md

@@ -1,287 +1,299 @@
-# JigsawPuzzle
-
-A lightweight, reusable JavaScript class for creating interactive jigsaw puzzle games in web applications. Features customizable piece shapes, rotation support, save/load functionality, and touch/mouse controls.
-
-## Demo
-
-Try it out live: [https://jigsawpuzzleclass.raketten.net/game.html](https://jigsawpuzzleclass.raketten.net/game.html)
-
-## Installation
-
-```bash
-npm i jigsawpuzzlegame
-```
-
-## Quick Start
-
-```javascript
-import { JigsawPuzzle } from 'jigsaw-puzzle';
-
-const puzzle = new JigsawPuzzle('puzzle-container', {
-    image: 'https://example.com/image.jpg',
-    numPieces: 20,
-    shapeType: 0,
-    allowRotation: false,
-    onReady: () => {
-        puzzle.start();
-    },
-    onWin: () => {
-        console.log('Puzzle solved!');
-    }
-});
-```
-
-## HTML Setup
-
-```html
-<div id="puzzle-container"></div>
-<script type="module" src="your-script.js"></script>
-```
-
-Make sure your container has a defined size:
-
-```css
-#puzzle-container {
-    width: 100vw;
-    height: 100vh;
-    position: relative;
-}
-```
-
-## Configuration Options
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `image` | string | `null` | URL or data URL of the image to use for the puzzle (ignored if `savedData` is provided) |
-| `savedData` | string\|null | `null` | JSON string of saved game state:<br>• Non-empty string: use this saved data<br>• Empty string (`""`): load from localStorage<br>• Not provided or `null`: use normal initialization with `image` and other parameters |
-| `numPieces` | number | `20` | Number of puzzle pieces (approximate - actual count depends on optimal grid layout, ignored if `savedData` is provided) |
-| `shapeType` | number | `0` | Shape type for puzzle pieces (0-3, ignored if `savedData` is provided):<br>• `0` - Classic jigsaw shape (curved tabs)<br>• `1` - Alternative shape 1<br>• `2` - Alternative shape 2<br>• `3` - Straight edges (rectangular pieces) |
-| `allowRotation` | boolean | `false` | Whether pieces can be rotated by clicking/tapping (90° increments, ignored if `savedData` is provided) |
-| `onReady` | function | `null` | Callback function called when the puzzle is ready (image loaded and displayed) |
-| `onWin` | function | `null` | Callback function called when the puzzle is completed |
-| `onStart` | function | `null` | Callback function called when a game starts |
-| `onStop` | function | `null` | Callback function called when a game is stopped |
-
-## API Methods
-
-### `start()`
-
-Starts a new game with the current settings. Creates the puzzle pieces and distributes them.
-
-```javascript
-puzzle.start();
-```
-
-**Important:** Call this only after the puzzle is ready (use the `onReady` callback).
-
-### `stop()`
-
-Stops the current game and returns to the image preview state.
-
-```javascript
-puzzle.stop();
-```
-
-### `reset()`
-
-Resets the puzzle to initial state. Reloads the current image and prepares for a new game.
-
-```javascript
-puzzle.reset();
-// Then wait for onReady callback and call puzzle.start()
-```
-
-### `setImage(imageUrl)`
-
-Sets a new image for the puzzle.
-
-**Parameters:**
-- `imageUrl` (string) - URL or data URL of the image
-
-```javascript
-puzzle.setImage('https://example.com/new-image.jpg');
-// Image will reload, wait for onReady callback
-```
-
-### `setOptions(newOptions)`
-
-Updates puzzle options without creating a new instance.
-
-**Parameters:**
-- `newOptions` (object) - Object with options to update (partial updates allowed)
-
-```javascript
-puzzle.setOptions({
-    numPieces: 50,
-    allowRotation: true,
-    shapeType: 1
-});
-```
-
-### `save([callback])`
-
-Saves the current game state. Gets the state data, converts it to a JSON string, then either calls the callback with the string or saves to localStorage.
-
-**Parameters:**
-- `callback` (function, optional) - Function that receives the saved data as JSON string. If not provided, saves to localStorage automatically.
-
-```javascript
-// Save to localStorage (default)
-puzzle.save();
-
-// Save with custom callback
-puzzle.save((savedData) => {
-    localStorage.setItem('myPuzzleSave', savedData);
-    // Or send to server, download as file, etc.
-});
-```
-
-### Loading Saved Games
-
-To load a saved game, create a new puzzle instance with the `savedData` option:
-
-```javascript
-// Load from explicit string
-const savedString = localStorage.getItem('myPuzzleSave');
-const puzzle = new JigsawPuzzle('puzzle-container', {
-    savedData: savedString,
-    onReady: () => puzzle.start()
-});
-
-// Load from localStorage automatically (pass empty string)
-const puzzle = new JigsawPuzzle('puzzle-container', {
-    savedData: "",  // Empty string triggers localStorage lookup
-    onReady: () => puzzle.start()
-});
-
-// Create new puzzle (no saved data)
-const puzzle = new JigsawPuzzle('puzzle-container', {
-    image: 'image.jpg',
-    numPieces: 25,
-    onReady: () => puzzle.start()
-});
-```
-
-### `destroy()`
-
-Completely destroys the puzzle instance, cleaning up all resources. Use this when you want to remove the puzzle and create a new one in the same container.
-
-```javascript
-puzzle.destroy();
-puzzle = new JigsawPuzzle('puzzle-container', {
-    image: 'new-image.jpg',
-    numPieces: 30
-});
-```
-
-## Complete Example
-
-```javascript
-import { JigsawPuzzle } from 'jigsaw-puzzle';
-
-const puzzle = new JigsawPuzzle('puzzle-container', {
-    image: 'https://example.com/image.jpg',
-    numPieces: 20,
-    shapeType: 0,
-    allowRotation: false,
-    onReady: () => {
-        // Puzzle is ready, start the game
-        puzzle.start();
-    },
-    onWin: () => {
-        alert('Congratulations! You solved the puzzle!');
-    },
-    onStart: () => {
-        console.log('Game started');
-    },
-    onStop: () => {
-        console.log('Game stopped');
-    }
-});
-
-// Save game
-function saveGame() {
-    puzzle.save((data) => {
-        localStorage.setItem('puzzleSave', data);
-        console.log('Game saved!');
-    });
-}
-
-// Load game - create new instance with saved data
-function loadGame() {
-    const saved = localStorage.getItem('puzzleSave');
-    if (saved) {
-        if (puzzle) puzzle.destroy();
-        puzzle = new JigsawPuzzle('puzzle-container', {
-            savedData: saved,
-            onReady: () => puzzle.start(),
-            onWin: () => {
-                alert('You won!');
-            }
-        });
-    }
-}
-```
-
-## User Interactions
-
-- **Mouse/Touch:** Click and drag pieces to move them
-- **Rotation:** If `allowRotation` is enabled, quick click/tap rotates pieces 90°
-- **Piece Merging:** When pieces are close and correctly aligned, they automatically merge
-- **Pan:** Click and drag on empty space to pan all pieces
-- **Zoom:** Mouse wheel to zoom in/out, or pinch gesture on touch devices
-
-## Browser Compatibility
-
-Requires modern browser features:
-- ES6 Modules support
-- Canvas API
-- Path2D API
-- Touch events (for mobile support)
-
-Works in all modern browsers (Chrome, Firefox, Safari, Edge).
-
-## Styling
-
-The library automatically injects its required CSS styles when loaded, so **no external CSS file is needed**. The styles are injected once per page load, even if multiple puzzle instances are created.
-
-The puzzle uses these CSS classes (automatically styled by the library):
-
-- `.polypiece` - Individual puzzle pieces
-- `.polypiece.moving` - Pieces during animation
-- `.gameCanvas` - Reference image canvas (hidden during play)
-
-You can override these styles in your own CSS if needed. The library injects a `<style>` element with id `jigsaw-puzzle-styles` that you can target or override.
-
-## Troubleshooting
-
-### Puzzle doesn't start
-- Make sure you're calling `start()` in the `onReady` callback
-- Check that the image URL is valid and accessible (CORS issues if loading from different domain)
-- Verify the container element exists and has a size
-
-### Image doesn't load
-- Check browser console for CORS errors
-- Use data URLs or images from the same domain
-- Ensure the image URL is correct
-
-### Pieces don't merge
-- Make sure pieces are close enough (the puzzle calculates optimal distance)
-- Check that pieces are in the same rotation if rotation is enabled
-- Verify pieces are correctly aligned
-
-## License
-
-Copyright (c) 2026 by Dillon (https://codepen.io/Dillo/pen/QWKLYab) & Henrik Rasmussen (https://www.raketten.net)
-
-Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
-
-## Authors
-
-- Dillon - https://codepen.io/Dillo/pen/QWKLYab
-- Henrik Rasmussen - https://www.raketten.net
-
+# JigsawPuzzle
+
+A lightweight, reusable JavaScript class for creating interactive jigsaw puzzle games in web applications. Features customizable piece shapes, rotation support, save/load functionality, and touch/mouse controls.
+
+## Demo
+
+Try it out live: [https://jigsawpuzzleclass.raketten.net/game.html](https://jigsawpuzzleclass.raketten.net/game.html)
+
+## Installation
+
+```bash
+npm i jigsawpuzzlegame
+```
+
+## Quick Start
+
+```javascript
+import { JigsawPuzzle } from 'jigsaw-puzzle';
+
+const puzzle = new JigsawPuzzle('puzzle-container', {
+    image: 'https://example.com/image.jpg',
+    numPieces: 20,
+    shapeType: 0,
+    allowRotation: false,
+    onReady: () => {
+        puzzle.start();
+    },
+    onWin: () => {
+        console.log('Puzzle solved!');
+    }
+});
+```
+
+## HTML Setup
+
+```html
+<div id="puzzle-container"></div>
+<script type="module" src="your-script.js"></script>
+```
+
+Make sure your container has a defined size:
+
+```css
+#puzzle-container {
+    width: 100vw;
+    height: 100vh;
+    position: relative;
+}
+```
+
+## Configuration Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `image` | string | `null` | URL or data URL of the image to use for the puzzle (ignored if `savedData` is provided) |
+| `savedData` | string\|null | `null` | JSON string of saved game state:<br>• Non-empty string: use this saved data<br>• Empty string (`""`): load from localStorage<br>• Not provided or `null`: use normal initialization with `image` and other parameters |
+| `numPieces` | number | `20` | Number of puzzle pieces (approximate - actual count depends on optimal grid layout, ignored if `savedData` is provided) |
+| `shapeType` | number | `0` | Shape type for puzzle pieces (0-3, ignored if `savedData` is provided):<br>• `0` - Classic jigsaw shape (curved tabs)<br>• `1` - Alternative shape 1<br>• `2` - Alternative shape 2<br>• `3` - Straight edges (rectangular pieces) |
+| `allowRotation` | boolean | `false` | Whether pieces can be rotated by clicking/tapping (90° increments, ignored if `savedData` is provided) |
+| `onReady` | function | `null` | Callback function called when the puzzle is ready (image loaded and displayed) |
+| `onWin` | function | `null` | Callback function called when the puzzle is completed |
+| `onStart` | function | `null` | Callback function called when a game starts |
+| `onStop` | function | `null` | Callback function called when a game is stopped |
+| `onMerged` | function | `null` | Callback function called when puzzle pieces are merged together (receives the merged piece as parameter) |
+| `onChanged` | function | `null` | Callback function called when a piece is moved or changed (receives the piece as parameter) |
+| `onDeleted` | function | `null` | Callback function called when a piece is deleted/merged into another piece (receives the deleted piece as parameter) |
+
+## API Methods
+
+### `start()`
+
+Starts a new game with the current settings. Creates the puzzle pieces and distributes them.
+
+```javascript
+puzzle.start();
+```
+
+**Important:** Call this only after the puzzle is ready (use the `onReady` callback).
+
+### `stop()`
+
+Stops the current game and returns to the image preview state.
+
+```javascript
+puzzle.stop();
+```
+
+### `reset()`
+
+Resets the puzzle to initial state. Reloads the current image and prepares for a new game.
+
+```javascript
+puzzle.reset();
+// Then wait for onReady callback and call puzzle.start()
+```
+
+### `setImage(imageUrl)`
+
+Sets a new image for the puzzle.
+
+**Parameters:**
+- `imageUrl` (string) - URL or data URL of the image
+
+```javascript
+puzzle.setImage('https://example.com/new-image.jpg');
+// Image will reload, wait for onReady callback
+```
+
+### `setOptions(newOptions)`
+
+Updates puzzle options without creating a new instance.
+
+**Parameters:**
+- `newOptions` (object) - Object with options to update (partial updates allowed)
+
+```javascript
+puzzle.setOptions({
+    numPieces: 50,
+    allowRotation: true,
+    shapeType: 1
+});
+```
+
+### `save([callback])`
+
+Saves the current game state. Gets the state data, converts it to a JSON string, then either calls the callback with the string or saves to localStorage.
+
+**Parameters:**
+- `callback` (function, optional) - Function that receives the saved data as JSON string. If not provided, saves to localStorage automatically.
+
+```javascript
+// Save to localStorage (default)
+puzzle.save();
+
+// Save with custom callback
+puzzle.save((savedData) => {
+    localStorage.setItem('myPuzzleSave', savedData);
+    // Or send to server, download as file, etc.
+});
+```
+
+### Loading Saved Games
+
+To load a saved game, create a new puzzle instance with the `savedData` option:
+
+```javascript
+// Load from explicit string
+const savedString = localStorage.getItem('myPuzzleSave');
+const puzzle = new JigsawPuzzle('puzzle-container', {
+    savedData: savedString,
+    onReady: () => puzzle.start()
+});
+
+// Load from localStorage automatically (pass empty string)
+const puzzle = new JigsawPuzzle('puzzle-container', {
+    savedData: "",  // Empty string triggers localStorage lookup
+    onReady: () => puzzle.start()
+});
+
+// Create new puzzle (no saved data)
+const puzzle = new JigsawPuzzle('puzzle-container', {
+    image: 'image.jpg',
+    numPieces: 25,
+    onReady: () => puzzle.start()
+});
+```
+
+### `destroy()`
+
+Completely destroys the puzzle instance, cleaning up all resources. Use this when you want to remove the puzzle and create a new one in the same container.
+
+```javascript
+puzzle.destroy();
+puzzle = new JigsawPuzzle('puzzle-container', {
+    image: 'new-image.jpg',
+    numPieces: 30
+});
+```
+
+## Complete Example
+
+```javascript
+import { JigsawPuzzle } from 'jigsaw-puzzle';
+
+const puzzle = new JigsawPuzzle('puzzle-container', {
+    image: 'https://example.com/image.jpg',
+    numPieces: 20,
+    shapeType: 0,
+    allowRotation: false,
+    onReady: () => {
+        // Puzzle is ready, start the game
+        puzzle.start();
+    },
+    onWin: () => {
+        alert('Congratulations! You solved the puzzle!');
+    },
+    onStart: () => {
+        console.log('Game started');
+    },
+    onStop: () => {
+        console.log('Game stopped');
+    },
+    onMerged: (piece) => {
+        console.log('Pieces merged!', piece);
+    },
+    onChanged: (piece) => {
+        console.log('Piece moved', piece);
+    },
+    onDeleted: (piece) => {
+        console.log('Piece deleted', piece);
+    }
+});
+
+// Save game
+function saveGame() {
+    puzzle.save((data) => {
+        localStorage.setItem('puzzleSave', data);
+        console.log('Game saved!');
+    });
+}
+
+// Load game - create new instance with saved data
+function loadGame() {
+    const saved = localStorage.getItem('puzzleSave');
+    if (saved) {
+        if (puzzle) puzzle.destroy();
+        puzzle = new JigsawPuzzle('puzzle-container', {
+            savedData: saved,
+            onReady: () => puzzle.start(),
+            onWin: () => {
+                alert('You won!');
+            }
+        });
+    }
+}
+```
+
+## User Interactions
+
+- **Mouse/Touch:** Click and drag pieces to move them
+- **Rotation:** If `allowRotation` is enabled, quick click/tap rotates pieces 90°
+- **Piece Merging:** When pieces are close and correctly aligned, they automatically merge
+- **Pan:** Click and drag on empty space to pan all pieces
+- **Zoom:** Mouse wheel to zoom in/out, or pinch gesture on touch devices
+
+## Browser Compatibility
+
+Requires modern browser features:
+- ES6 Modules support
+- Canvas API
+- Path2D API
+- Touch events (for mobile support)
+
+Works in all modern browsers (Chrome, Firefox, Safari, Edge).
+
+## Styling
+
+The library automatically injects its required CSS styles when loaded, so **no external CSS file is needed**. The styles are injected once per page load, even if multiple puzzle instances are created.
+
+The puzzle uses these CSS classes (automatically styled by the library):
+
+- `.polypiece` - Individual puzzle pieces
+- `.polypiece.moving` - Pieces during animation
+- `.gameCanvas` - Reference image canvas (hidden during play)
+
+You can override these styles in your own CSS if needed. The library injects a `<style>` element with id `jigsaw-puzzle-styles` that you can target or override.
+
+## Troubleshooting
+
+### Puzzle doesn't start
+- Make sure you're calling `start()` in the `onReady` callback
+- Check that the image URL is valid and accessible (CORS issues if loading from different domain)
+- Verify the container element exists and has a size
+
+### Image doesn't load
+- Check browser console for CORS errors
+- Use data URLs or images from the same domain
+- Ensure the image URL is correct
+
+### Pieces don't merge
+- Make sure pieces are close enough (the puzzle calculates optimal distance)
+- Check that pieces are in the same rotation if rotation is enabled
+- Verify pieces are correctly aligned
+
+## License
+
+Copyright (c) 2026 by Dillon (https://codepen.io/Dillo/pen/QWKLYab) & Henrik Rasmussen (https://www.raketten.net)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+## Authors
+
+- Dillon - https://codepen.io/Dillo/pen/QWKLYab
+- Henrik Rasmussen - https://www.raketten.net
+