@bensitu/image-editor 1.5.0 → 1.5.2

package/README.md

@@ -19,9 +19,10 @@ ImageEditor offers:
 - Merge, download, base64 export, and `File` export helpers
 - Optional DOM/UI binding for common editor controls
 - Large-image downsampling to reduce browser memory pressure
+- Configurable history bounds for large image sessions
 - Centralized error and warning callbacks
 
-**Note:** This library requires **fabric.js v5.x** to be loaded before creating or initializing the editor.
+**Note:** This library uses **fabric.js v5.x**. Bundler and CommonJS entries load Fabric through the peer dependency. Browser global usage needs `window.fabric` available by the time `init()` runs; constructing the editor before Fabric is available is tolerated as long as Fabric is registered before initialization.
 
 ## Demo
 
@@ -61,6 +62,14 @@ import ImageEditor, {
 } from "@bensitu/image-editor";
 ```
 
+### CommonJS usage
+
+```javascript
+const ImageEditor = require("@bensitu/image-editor");
+
+const editor = new ImageEditor();
+```
+
 ### Browser global usage
 
 Include fabric.js first, then ImageEditor:
@@ -115,50 +124,89 @@ Use `dist/image-editor.js` or `dist/image-editor.min.js` for browser global scri
 
 ### JavaScript Implementation
 
+The constructor options are optional. For the smallest setup, create an editor instance and bind it to a canvas element.
+
+```javascript
+const editor = new ImageEditor();
+
+editor.init({
+  canvas: "fabricCanvas"
+});
+```
+
+`canvas` is the only required DOM binding when your canvas element does not use the default ID `fabricCanvas`. All other DOM bindings are optional.
+
+#### Optional Configuration
+
+You can pass options to override the built-in defaults.
+
 ```javascript
-// Create instance
 const editor = new ImageEditor({
   canvasWidth: 800,
   canvasHeight: 600,
   backgroundColor: "#ffffff",
+  initialImageBase64: null
+});
+```
+
+These are common optional overrides, not required settings.
+
+#### Demo-style Configuration
+
+The docs demo uses an explicit configuration so the demo behavior is predictable. These options are not required for normal usage.
+
+```javascript
+const editor = new ImageEditor({
+  // Layout mode. Enable only one layout mode at a time.
+  expandCanvasToImage: false,
+  fitImageToCanvas: true,
+  coverImageToCanvas: false,
+
+  // Image loading / performance.
+  downsampleOnLoad: true,
   initialImageBase64: null,
 
-  onError: (error, message) => {
-    console.error("[ImageEditor]", message, error);
-  },
+  // Mask behavior.
+  maskRotatable: true,
+  maskLabelOnSelect: true,
+  maskLabelOffset: 5,
 
-  onWarning: (error, message) => {
-    console.warn("[ImageEditor]", message, error);
-  },
+  // UI behavior.
+  backgroundColor: "transparent",
+  showPlaceholder: true,
+  animationDuration: 100,
+
+  // Export behavior.
+  exportImageAreaByDefault: true
 });
 
-try {
-  editor.init({
-    canvas: "fabricCanvas",
-    zoomInButton: "zoomInButton",
-    zoomOutButton: "zoomOutButton",
-    rotateLeftButton: "rotateLeftButton",
-    rotateLeftDegreesInput: "rotateLeftDegreesInput",
-    rotateRightButton: "rotateRightButton",
-    rotateRightDegreesInput: "rotateRightDegreesInput",
-    createMaskButton: "createMaskButton",
-    removeSelectedMaskButton: "removeSelectedMaskButton",
-    removeAllMasksButton: "removeAllMasksButton",
-    enterCropModeButton: "enterCropModeButton",
-    applyCropButton: "applyCropButton",
-    cancelCropButton: "cancelCropButton",
-    undoButton: "undoButton",
-    redoButton: "redoButton",
-    mergeMasksButton: "mergeMasksButton",
-    resetImageTransformButton: "resetImageTransformButton",
-    downloadImageButton: "downloadImageButton",
-    imageInput: "imageInput",
-  });
-} catch (error) {
-  console.error("Failed to initialize ImageEditor:", error);
-}
+editor.init({
+  canvas: "fabricCanvas",
+  canvasContainer: null,
+  imagePlaceholder: "imagePlaceholder",
+  scalePercentageInput: "scalePercentageInput",
+  rotateLeftButton: "rotateLeftButton",
+  rotateRightButton: "rotateRightButton",
+  rotateLeftDegreesInput: "rotateLeftDegreesInput",
+  rotateRightDegreesInput: "rotateRightDegreesInput",
+  createMaskButton: null,
+  removeSelectedMaskButton: "removeSelectedMaskButton",
+  removeAllMasksButton: "removeAllMasksButton",
+  mergeMasksButton: "mergeMasksButton",
+  downloadImageButton: "downloadImageButton",
+  maskList: "maskList",
+  enterCropModeButton: "enterCropModeButton",
+  applyCropButton: "applyCropButton",
+  cancelCropButton: "cancelCropButton",
+  resetImageTransformButton: "resetImageTransformButton",
+  imageInput: null,
+  uploadArea: null
+});
 ```
 
+The demo binds `createMaskButton`, `imageInput`, and `uploadArea` itself, so it passes `null` for those built-in bindings. Regular integrations can omit those keys to use the default IDs, or pass `null` to disable any optional binding.
+
+
 ### Loading an Image Manually
 
 ```javascript
@@ -175,6 +223,8 @@ loadImageDataUrl("data:image/jpeg;base64,...");
 
 ## Configuration Options
 
+All options are optional. If an option is not provided, the editor uses the default value listed below.
+
 When creating the editor instance, pass an options object to override defaults.
 
 | Option                        | Default                   | Description                                                                                                                                           |
@@ -198,6 +248,8 @@ When creating the editor instance, pass an options object to override defaults.
 | `downsampleMimeType`          | `null`                    | Optional output MIME type for downsampled images. Supported values include `jpeg`, `jpg`, `png`, `webp`, `image/jpeg`, `image/png`, and `image/webp`. |
 | `imageLoadTimeoutMs`          | `30000`                   | Timeout for image decode/load operations.                                                                                                             |
 | `exportMultiplier`            | `1`                       | Default scale multiplier for export.                                                                                                                  |
+| `maxExportPixels`             | `50000000`                | Maximum output pixel count allowed per export after applying the multiplier.                                                                           |
+| `maxHistorySize`              | `50`                      | Maximum undo/redo history entries to retain. Large base64 source images can make each history snapshot expensive.                                     |
 | `exportImageAreaByDefault`    | `true`                    | Export only the image area by default instead of the full canvas.                                                                                     |
 | `defaultMaskWidth`            | `50`                      | Default mask width in pixels.                                                                                                                         |
 | `defaultMaskHeight`           | `80`                      | Default mask height in pixels.                                                                                                                        |
@@ -207,19 +259,28 @@ When creating the editor instance, pass an options object to override defaults.
 | `maskName`                    | `mask`                    | Prefix for mask names and labels.                                                                                                                     |
 | `groupSelection`              | `false`                   | Whether Fabric can select multiple masks as an active selection.                                                                                      |
 | `label.getText`               | `(mask) => mask.maskName` | Callback for custom label text. The second argument is the mask's stable zero-based creation index (`mask.maskId - 1`).                               |
-| `showPlaceholder`             | `true`                    | Show a placeholder when no image is loaded.                                                                                                           |
+| `label.create`                | `undefined`               | Optional callback that returns a custom Fabric label object for the selected mask. Invalid or throwing callbacks fall back to the default label.       |
+| `label.textOptions`           | see defaults              | Fabric text options merged into the default label when `label.create` is not used or falls back.                                                       |
+| `showPlaceholder`             | `true`                    | Show a placeholder when no image is loaded. When `false`, internal load, rollback, and status paths keep the placeholder hidden.                       |
 | `initialImageBase64`          | `null`                    | Base64 data URL to auto-load during initialization.                                                                                                   |
 | `defaultDownloadFileName`     | `edited_image.jpg`        | Default file name for downloads.                                                                                                                      |
+| `crop.minWidth`               | `100`                     | Minimum crop rectangle width, clamped to the current image bounds.                                                                                    |
+| `crop.minHeight`              | `100`                     | Minimum crop rectangle height, clamped to the current image bounds.                                                                                   |
+| `crop.padding`                | `10`                      | Initial inset from the image bounds when entering crop mode.                                                                                          |
+| `crop.hideMasksDuringCrop`    | `true`                    | Hide editable masks while crop mode is active.                                                                                                        |
 | `crop.preserveMasksAfterCrop` | `false`                   | Keep masks that intersect the crop area, shifted into the cropped canvas. Merge masks first if they should be baked into the image pixels.            |
-| `onImageLoaded`               | `null`                    | Callback invoked after an image finishes loading.                                                                                                     |
+| `crop.allowRotationOfCropRect` | `false`                  | Reserved for future rotated crop support. In v1.x, crop rectangles stay axis-aligned; setting this to `true` reports a warning and rotation remains disabled. |
+| `onImageLoaded`               | `null`                    | Callback invoked after an image load is committed. Callback errors are reported as warnings and do not roll back the loaded image.                    |
 | `onError`                     | `null`                    | Callback invoked for recoverable internal errors.                                                                                                     |
 | `onWarning`                   | `null`                    | Callback invoked for recoverable internal warnings.                                                                                                   |
 
-`expandCanvasToImage`, `fitImageToCanvas`, and `coverImageToCanvas` are mutually exclusive layout modes. If more than one is enabled, the editor reports a warning and uses the first active mode in its existing load order.
+`expandCanvasToImage`, `fitImageToCanvas`, and `coverImageToCanvas` are mutually exclusive layout modes. If more than one is enabled, the editor reports a warning and uses this precedence: `fitImageToCanvas`, then `coverImageToCanvas`, then `expandCanvasToImage`.
+
+Numeric runtime options are normalized during construction. Non-finite or invalid dimensions, scale limits, export limits, crop sizes, label offsets, and history sizes fall back to safe defaults. `animationDuration: 0` and `downsampleQuality: 0` remain valid.
 
 ## DOM Binding Keys
 
-`init(idMap)` binds editor behavior to DOM elements by ID. All keys are optional.
+`init(idMap)` binds editor behavior to DOM elements by ID. All keys are optional when the default IDs are present. Optional bindings can also be set to `null` to disable the built-in listener for that element.
 
 | Key                         | Description                                                    |
 | --------------------------- | -------------------------------------------------------------- |
@@ -279,11 +340,12 @@ The following DOM binding keys remain supported in `1.x` for compatibility, but
 | Method                            | Returns                 | Description                                                                                                           |
 | --------------------------------- | ----------------------- | --------------------------------------------------------------------------------------------------------------------- |
 | `init(idMap)`                     | `void`                  | Bind the editor to DOM elements. Pass IDs in an object.                                                               |
+| `dispose()`                       | `void`                  | Cleans up the canvas, listeners, crop state, animations, and captured DOM visibility/disabled/pointer-events state.   |
 | `loadImage(imageBase64, options)` | `Promise<void>`         | Load an image from a base64 data URL. Resolves after the Fabric image is on the canvas.                               |
 | `isImageLoaded()`                 | `boolean`               | Return whether a valid image is loaded on the canvas.                                                                 |
-| `isBusy()`                        | `boolean`               | Return whether the editor is loading, animating, cropping, or running another compound operation.                     |
-| `scaleImage(factor)`              | `Promise<void>`         | Scale the image to the given factor relative to the base scale.                                                       |
-| `rotateImage(degrees)`            | `Promise<void>`         | Rotate the image to the given angle in degrees.                                                                       |
+| `isBusy()`                        | `boolean`               | Return whether the editor is loading, animating, cropping, applying crop, or running another compound operation.      |
+| `scaleImage(factor)`              | `Promise<void>`         | Scale the image to the given finite factor relative to the base scale. Non-finite values are ignored.                 |
+| `rotateImage(degrees)`            | `Promise<void>`         | Rotate the image to the given finite angle in degrees. Non-finite values are ignored.                                 |
 | `resetImageTransform()`           | `Promise<void>`         | Reset scale to `1` and rotation to `0`.                                                                               |
 | `undo()`                          | `Promise<void>`         | Undo the last state change. Resolves after the canvas state is restored.                                              |
 | `redo()`                          | `Promise<void>`         | Redo the next state change. Resolves after the canvas state is restored.                                              |
@@ -291,8 +353,8 @@ The following DOM binding keys remain supported in `1.x` for compatibility, but
 | `removeSelectedMask()`            | `void`                  | Remove the currently selected mask or selected masks.                                                                 |
 | `removeAllMasks(options)`         | `void`                  | Remove all masks from the canvas.                                                                                     |
 | `enterCropMode()`                 | `void`                  | Create a resizable/movable selection rectangle on top of the image.                                                   |
-| `cancelCrop()`                    | `void`                  | Cancel crop mode and remove the temporary selection rectangle.                                                        |
-| `applyCrop()`                     | `Promise<void>`         | Apply the current crop rectangle to the canvas.                                                                       |
+| `cancelCrop()`                    | `void`                  | Cancel crop mode and remove the temporary selection rectangle. No-ops while `applyCrop()` is already running.         |
+| `applyCrop()`                     | `Promise<void>`         | Apply the current valid crop rectangle to the canvas. Invalid crop regions warn and keep crop mode active.            |
 | `mergeMasks()`                    | `Promise<void>`         | Merge masks into the base image on the canvas.                                                                        |
 | `downloadImage(fileName)`         | `void`                  | Download the edited image as a file.                                                                                  |
 | `exportImageBase64(options)`      | `Promise<string>`       | Export an image data URL. `fileType` can be `jpeg`, `jpg`, `png`, `webp`, or a supported image MIME type.             |
@@ -313,6 +375,8 @@ Deprecated method aliases are still available for compatibility and will be remo
 
 `createMask(config)` accepts an optional configuration object.
 
+Invalid mask configuration, such as non-finite numeric values, non-positive dimensions/radii, duplicate or zero-area polygon points, malformed polygon points, throwing custom generators, or custom generators that do not return a Fabric object, is rejected with a warning and returns `null` without mutating the canvas or history.
+
 | Option             | Description                                                                                |
 | ------------------ | ------------------------------------------------------------------------------------------ |
 | `shape`            | Mask shape. Built-in values include `rect`, `circle`, `ellipse`, and `polygon`.            |
@@ -330,6 +394,10 @@ Deprecated method aliases are still available for compatibility and will be remo
 | `fabricGenerator`  | Factory callback for creating a custom Fabric object.                                      |
 | `onCreate`         | Callback invoked after the mask is added to the canvas.                                    |
 
+`fabricGenerator` runs before the mask is committed. If it throws or returns an invalid object, `createMask()` reports a warning and returns `null`. `onCreate` runs after the mask and history entry are committed; if it throws, the mask remains on the canvas and the error is reported as a warning.
+
+Label callbacks are also isolated. If `label.create` throws or returns an invalid object, the editor uses the default Fabric text label. If `label.getText` throws, the editor uses `mask.maskName`.
+
 Example:
 
 ```javascript
@@ -350,6 +418,10 @@ By default, applying crop removes unmerged masks.
 
 This is intentional: an unmerged mask is still an editable overlay object, not part of the image pixels. When `crop.preserveMasksAfterCrop` is `false`, applying crop discards unmerged masks instead of trying to keep or partially crop those overlay objects.
 
+`applyCrop()` owns a short crop-apply lock while it exports the selected region and reloads the cropped image. Calls to `cancelCrop()` or `enterCropMode()` during that pending apply are ignored and reported as warnings so crop state cannot be mutated mid-apply. The crop region is validated before export; invalid or out-of-bounds regions do not silently produce a 1x1 image.
+
+While crop mode is active, the built-in DOM binding disables editor operation controls but keeps the canvas, canvas container, and placeholder interaction available so the crop rectangle and scrollable viewport remain usable. The apply/cancel crop buttons stay enabled.
+
 Choose the workflow based on the result you want:
 
 - **Crop first, then add masks** when masks should be placed only on the final cropped image.
@@ -414,6 +486,24 @@ try {
 }
 ```
 
+Exports are limited by `maxExportPixels`. Increase that option only when the host page can tolerate the memory cost of larger canvas exports.
+
+```javascript
+const editor = new ImageEditor({
+  maxExportPixels: 80000000,
+});
+```
+
+JPEG exports cannot preserve transparency. Transparent, zero-alpha, empty, or invalid `backgroundColor` values are flattened against white; valid opaque CSS colors are preserved.
+
+Undo/redo history is limited by `maxHistorySize`. The default is `50`; lower it for workflows that load large base64 images and perform many edits.
+
+```javascript
+const editor = new ImageEditor({
+  maxHistorySize: 20,
+});
+```
+
 ## Error Handling
 
 Some ImageEditor API methods may throw synchronously or reject their returned Promise when the operation cannot be completed.
@@ -464,13 +554,13 @@ function showEditorMessage(message) {
 
 Common failure cases include:
 
-- fabric.js is not loaded before creating or initializing the editor.
+- fabric.js is not available when `init()` or another canvas operation needs it.
 - The configured canvas element cannot be found.
-- The image data URL is invalid, unsupported, too large, or times out while loading.
+- The image data URL or selected file is invalid, unsupported, too large, or times out while loading.
 - Another operation is already running, such as image loading, animation, crop, undo, redo, merge, or export.
 - The editor has been disposed before the operation completes.
-- The browser cannot create a canvas export because of platform, memory, or security restrictions.
-- A custom `fabricGenerator`, label callback, or external event handler throws an error.
+- The requested export exceeds `maxExportPixels`, uses an invalid multiplier, or the browser cannot create a canvas export because of platform, memory, or security restrictions.
+- A custom callback such as `onImageLoaded`, `onCreate`, `fabricGenerator`, `label.create`, or `label.getText` throws. These are isolated where possible and reported through `onWarning` without rolling back already committed successful work.
 
 ## Example Workflow
 
@@ -529,7 +619,7 @@ IE11 and old mobile Safari are not supported by the distributed build. If you ne
 
 ## Dependencies
 
-- **fabric.js v5.x** — Must be loaded before ImageEditor.
+- **fabric.js v5.x** — Required peer dependency. Browser global usage needs `window.fabric` available before `init()`.
 
 ## License