@bensitu/image-editor 2.0.0 → 2.1.0

package/README.md

@@ -6,15 +6,10 @@
 
 A lightweight, TypeScript-first canvas image editor built on top of
 [Fabric.js](https://fabricjs.com/) v7. `ImageEditor` wraps a Fabric canvas
-with image loading, scale and rotation, mask creation, crop, history
+with image loading, scale and rotation, mask creation, crop, Mosaic mode, history
 (undo/redo), and base64/file export — exposed as a single canonical class
 with a stable public surface.
 
-> **v2.0.0 is a behavior-preserving migration.** The v1 deprecated method
-> and property aliases have been removed in favor of the canonical names
-> documented below. See [`CHANGELOG.md`](./CHANGELOG.md) for the complete
-> rename map.
-
 ## Demo
 
 [https://bensitu.github.io/image-editor/](https://bensitu.github.io/image-editor/)
@@ -33,6 +28,8 @@ with a stable public surface.
   interleave
 - Bounded history stack with idempotent dispose
 - Crop session with mask preservation toggle and atomic apply/cancel
+- Mosaic mode with circular brush preview, runtime brush/block controls, and
+  one undo step per successful pixelation click
 - Base64 and `File` exports with PNG/JPEG/WebP support, configurable
   multiplier, and mask compositing
 
@@ -135,6 +132,17 @@ resolve to `undefined`.
 <button id="applyCropButton">Apply Crop</button>
 <button id="cancelCropButton">Cancel Crop</button>
 
+<button id="enterMosaicModeButton">Mosaic</button>
+<button id="exitMosaicModeButton">Exit Mosaic</button>
+<label>
+    Brush size
+    <input id="mosaicBrushSizeInput" type="range" min="8" max="160" step="1" value="48" />
+</label>
+<label>
+    Block size
+    <input id="mosaicBlockSizeInput" type="range" min="2" max="40" step="1" value="8" />
+</label>
+
 <button id="mergeMasksButton">Merge</button>
 <button id="downloadImageButton">Download</button>
 <button id="undoButton">Undo</button>
@@ -156,6 +164,10 @@ const editor = new ImageEditor(fabric, {
     canvasWidth: 800,
     canvasHeight: 600,
     backgroundColor: '#ffffff',
+    defaultMosaicConfig: {
+        brushSize: 48,
+        blockSize: 8,
+    },
 } satisfies ImageEditorOptions);
 
 editor.init({
@@ -172,6 +184,10 @@ editor.init({
     enterCropModeButton: 'enterCropModeButton',
     applyCropButton: 'applyCropButton',
     cancelCropButton: 'cancelCropButton',
+    enterMosaicModeButton: 'enterMosaicModeButton',
+    exitMosaicModeButton: 'exitMosaicModeButton',
+    mosaicBrushSizeInput: 'mosaicBrushSizeInput',
+    mosaicBlockSizeInput: 'mosaicBlockSizeInput',
     mergeMasksButton: 'mergeMasksButton',
     downloadImageButton: 'downloadImageButton',
     undoButton: 'undoButton',
@@ -232,22 +248,31 @@ new ImageEditor(options?: ImageEditorOptions)  // UMD: reads globalThis.fabric
 | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `loadImage(base64, options?)` | Load an image from a `data:image/...` URL. Returns `Promise<void>`. Transactional: any failure restores the prior canvas, scroll, overflow, and snapshot state. |
 | `isImageLoaded()`             | Returns `true` if a valid image is currently loaded on the canvas.                                                                                              |
-| `isBusy()`                    | Returns `true` while the editor is loading, animating, or in crop mode.                                                                                         |
+| `isBusy()`                    | Returns `true` while the editor is loading, animating, in crop mode, or in Mosaic mode.                                                                         |
 | `setLayoutMode(mode)`         | Select the layout strategy for future image loads. `mode` is `'fit'`, `'cover'`, or `'expand'`.                                                                 |
 
 `LoadImageOptions` currently includes `preserveScroll?: boolean` for
 preserving the container's scroll position across both successful loads and
 rollback paths.
 
-Use `setLayoutMode()` instead of mutating internal options when a UI lets users
-choose how the next image should be placed:
+Use `defaultLayoutMode` to choose the initial image-load strategy, then call
+`setLayoutMode()` when a UI should change how future images are placed:
 
 ```ts
-editor.setLayoutMode('fit');
+const editor = new ImageEditor(fabric, {
+    defaultLayoutMode: 'fit',
+});
+
+await editor.loadImage(imageA);
+
+// Future loads use cover. The current image is not re-laid out immediately.
 editor.setLayoutMode('cover');
-editor.setLayoutMode('expand');
+await editor.loadImage(imageB);
 ```
 
+Invalid JavaScript `defaultLayoutMode` values fall back to `'expand'`.
+Invalid `setLayoutMode()` calls are ignored and preserve the current mode.
+
 File-input helpers accept JPG, PNG, WebP, GIF, and BMP files. GIF and BMP are
 decoded as static raster input for canvas editing; GIF animation and BMP/GIF
 source-format preservation are not retained. Export output remains controlled by
@@ -273,6 +298,27 @@ the JPEG, PNG, or WebP export options.
 `fabricGenerator`. Falsy values in `styles` (`0`, `false`, `null`, `''`,
 `NaN`) are applied verbatim.
 
+Use `defaultMaskConfig` to define constructor-level defaults for masks created
+through either `createMask()` or the built-in `createMaskButton`. Per-call
+`createMask(config)` values override `defaultMaskConfig`.
+
+```ts
+const editor = new ImageEditor(fabric, {
+    defaultMaskConfig: {
+        color: 'rgba(255, 0, 0, 0.35)',
+        alpha: 0.35,
+        styles: {
+            stroke: '#ff0000',
+            strokeWidth: 2,
+            strokeDashArray: [6, 4],
+        },
+    },
+});
+
+editor.createMask(); // Uses defaultMaskConfig.
+editor.createMask({ color: 'rgba(0, 128, 255, 0.35)' }); // Per-call override.
+```
+
 ### Crop
 
 | Method            | Description                                                                          |
@@ -281,6 +327,53 @@ the JPEG, PNG, or WebP export options.
 | `applyCrop()`     | Apply the current crop region. Atomic: failure rolls back to the pre-crop snapshot.  |
 | `cancelCrop()`    | Cancel crop mode and restore the prior canvas state without pushing a history entry. |
 
+### Mosaic mode
+
+| Method                     | Description                                                            |
+| -------------------------- | ---------------------------------------------------------------------- |
+| `enterMosaicMode()`        | Enter circular-brush Mosaic mode and show the hover preview on canvas. |
+| `exitMosaicMode()`         | Leave Mosaic mode and remove preview/session handlers.                 |
+| `isMosaicMode()`           | Returns `true` while a Mosaic session is active.                       |
+| `getMosaicConfig()`        | Returns a defensive copy of the current runtime Mosaic config.         |
+| `setMosaicConfig(config)`  | Patch current Mosaic config without creating a history entry.          |
+| `resetMosaicConfig()`      | Restore current Mosaic config from constructor defaults.               |
+| `setMosaicBrushSize(size)` | Set brush diameter in canvas pixels.                                   |
+| `setMosaicBlockSize(size)` | Set source-pixel block size; values are floored to integers.           |
+
+`defaultMosaicConfig` initializes the current runtime Mosaic config. Runtime
+setters update only the current config and never mutate constructor defaults.
+`resetMosaicConfig()` clones the constructor defaults back into the current
+config.
+
+```ts
+const editor = new ImageEditor(fabric, {
+    defaultMosaicConfig: {
+        brushSize: 48,
+        blockSize: 8,
+    },
+});
+
+editor.init({
+    canvas: 'canvas',
+    enterMosaicModeButton: 'enterMosaicModeButton',
+    exitMosaicModeButton: 'exitMosaicModeButton',
+    mosaicBrushSizeInput: 'mosaicBrushSizeInput',
+    mosaicBlockSizeInput: 'mosaicBlockSizeInput',
+});
+
+editor.enterMosaicMode();
+editor.setMosaicConfig({ brushSize: 64, blockSize: 12 });
+editor.resetMosaicConfig();
+```
+
+`brushSize` is the circular brush diameter in canvas pixels. `blockSize` is
+the source-image pixel block size; larger values produce chunkier pixelation.
+Clicking outside the image is a no-op. Each successful Mosaic click bakes the
+pixelated region into the base image and creates exactly one undo step. Because
+Mosaic edits replace base image pixels rather than adding Fabric overlay
+objects, exported images include the Mosaic naturally while the preview circle
+is never exported or saved in history.
+
 ### Merge and export
 
 | Method                        | Description                                                                                    |
@@ -335,9 +428,7 @@ ignored; nested `label` and `crop` objects are deep-merged with the defaults.
 | `maxScale`                | `5.0`                | Maximum scale factor.                                                                                                                                                                                                                                                          |
 | `scaleStep`               | `0.05`               | Scale delta per zoom step.                                                                                                                                                                                                                                                     |
 | `rotationStep`            | `90`                 | Rotation step in degrees.                                                                                                                                                                                                                                                      |
-| `expandCanvasToImage`     | `true`               | Grow the canvas to fit the loaded image (lowest layout precedence).                                                                                                                                                                                                            |
-| `fitImageToCanvas`        | `false`              | Fit the image inside the visible workspace viewport (highest layout precedence).                                                                                                                                                                                               |
-| `coverImageToCanvas`      | `false`              | Scale large images down to cover the visible workspace, cap at native size, and expand overflowing canvas axes so the container can scroll.                                                                                                                                    |
+| `defaultLayoutMode`       | `'expand'`           | Initial layout mode for image loads until changed by `setLayoutMode()`. Use `'fit'`, `'cover'`, or `'expand'`. Invalid runtime values fall back to `'expand'`.                                                                                                                 |
 | `downsampleOnLoad`        | `true`               | Downsample large images on load.                                                                                                                                                                                                                                               |
 | `downsampleMaxWidth`      | `4000`               | Max width before downsampling kicks in.                                                                                                                                                                                                                                        |
 | `downsampleMaxHeight`     | `3000`               | Max height before downsampling kicks in.                                                                                                                                                                                                                                       |
@@ -352,6 +443,8 @@ ignored; nested `label` and `crop` objects are deep-merged with the defaults.
 | `mergeMaskByDefault`      | `true`               | Default mask compositing behavior for `exportImageBase64`, `exportImageFile`, and `downloadImage`.                                                                                                                                                                             |
 | `defaultMaskWidth`        | `50`                 | Default mask width.                                                                                                                                                                                                                                                            |
 | `defaultMaskHeight`       | `80`                 | Default mask height.                                                                                                                                                                                                                                                           |
+| `defaultMaskConfig`       | `{}`                 | Defaults applied by `createMask()` after `defaultMaskWidth` / `defaultMaskHeight` and before per-call config. Supports `MaskConfig` fields except `onCreate` and `fabricGenerator`.                                                                                            |
+| `defaultMosaicConfig`     | see source           | Defaults used to initialize the current Mosaic tool config. Supports `brushSize`, `blockSize`, preview circle styling, `outputFileType`, and `outputQuality`. Runtime Mosaic setters update the current config only.                                                           |
 | `maskRotatable`           | `false`              | Allow masks to be rotated by the user.                                                                                                                                                                                                                                         |
 | `maskLabelOnSelect`       | `true`               | Show a label above a selected mask.                                                                                                                                                                                                                                            |
 | `maskLabelOffset`         | `3`                  | Pixel offset of the label from the mask's top-left corner.                                                                                                                                                                                                                     |
@@ -379,12 +472,17 @@ lossless and ignores `crop.exportQuality`; JPEG/WebP use `crop.exportQuality`
 when finite, otherwise `downsampleQuality`, otherwise `0.92`. Choose JPEG/WebP
 only when smaller intermediate crop output is preferred.
 
+`defaultMosaicConfig.outputFileType` also defaults to `'source'`. Mosaic commits
+preserve the current image MIME type when known and fall back to PNG when the
+source format cannot be determined. JPEG/WebP commits use
+`defaultMosaicConfig.outputQuality` when finite, otherwise `downsampleQuality`.
+
 ## Example workflow
 
 1. Construct `ImageEditor` with options and call `init(idMap)` to wire it up.
 2. Load an image via `loadImage(base64)` or the bound file input.
-3. Adjust with `scaleImage`, `rotateImage`, `resetImageTransform`, and the
-   crop session.
+3. Adjust with `scaleImage`, `rotateImage`, `resetImageTransform`, the crop
+   session, or Mosaic mode.
 4. Add `createMask` calls and inspect via the `maskList` element.
 5. Use `mergeMasks` to bake masks into the image, then
    `exportImageBase64`, `exportImageFile`, or `downloadImage` to produce
@@ -447,8 +545,11 @@ import type {
     ResolvedOptions,
     LabelConfig,
     CropConfig,
+    MosaicConfig,
+    ResolvedMosaicConfig,
     LoadImageOptions,
     RemoveAllMasksOptions,
+    DefaultMaskConfig,
     MaskConfig,
     MaskObject,
     MaskNumericProp,
@@ -458,6 +559,7 @@ import type {
     NormalizedImageFormat,
     ExportArea,
     CropExportFileType,
+    MosaicOutputFileType,
     Base64ExportOptions,
     ImageFileExportOptions,
     ImageInfo,