@molecule/app-image-crop-cropperjs 1.0.0

package/LICENSE

@@ -0,0 +1,115 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work.
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship.
+
+      "Contribution" shall mean any work of authorship, including the
+      original version of the Work and any modifications or additions
+      to that Work, that is intentionally submitted to the Licensor for
+      inclusion in the Work by the copyright owner or by an individual or
+      Legal Entity authorized to submit on behalf of the copyright owner.
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by the Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      patent license to make, have made, use, offer to sell, sell, import,
+      and otherwise transfer the Work.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file.
+
+   5. Submission of Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND.
+
+   8. Limitation of Liability. In no event and under no legal theory shall
+      any Contributor be liable to You for damages.
+
+   9. Accepting Warranty or Additional Liability.
+
+   Copyright 2026 Molecule Dev, Inc.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/dist/index.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Cropper.js image-crop provider for `@molecule/app-image-crop` — a REAL
+ * implementation backed by cropperjs v1. `createCropper({ src })` mounts a live
+ * `Cropper` on an image element and every instance method delegates to the
+ * corresponding cropperjs call, so `getCroppedCanvas()` returns the actual
+ * cropped `<canvas>` (call `.toBlob()` / `.toDataURL()` on it to export) — not a
+ * placeholder object.
+ *
+ * @example
+ * ```typescript
+ * import { provider } from '@molecule/app-image-crop-cropperjs'
+ * import { setProvider, requireProvider } from '@molecule/app-image-crop'
+ *
+ * setProvider(provider)   // once, at app startup (bonds.ts)
+ *
+ * const cropper = requireProvider().createCropper({ src: '/avatar.jpg', aspectRatio: 1 })
+ * const canvas = cropper.getCroppedCanvas({ width: 200, height: 200 })
+ * canvas.toBlob((blob) => uploadAvatar(blob), 'image/png')
+ * ```
+ *
+ * @remarks
+ * - **Import cropperjs's stylesheet yourself** — this package does NOT:
+ *   `import 'cropperjs/dist/cropper.css'`. Without it the crop box, handles, and
+ *   drag guides render unstyled (an invisible/broken cropper), the same way Quill
+ *   needs its theme CSS.
+ * - **Browser-only.** `createCropper()` calls `document.createElement('img')` and
+ *   `new Cropper(...)`; construct it in a client-only effect under SSR.
+ * - **cropperjs initializes on the image's `load` event.** Reading `getCropData()`
+ *   or `getCroppedCanvas()` before the source has loaded returns empty/degenerate
+ *   data — drive them after load, or set the region explicitly with `setCropData()`
+ *   in natural-image coordinates first.
+ * - **`circular` is a UI concern, not a pixel op.** cropperjs has no circular
+ *   pixel output; for a round avatar, style the crop box round in CSS
+ *   (`.cropper-view-box, .cropper-face { border-radius: 50% }`) and draw the
+ *   returned canvas into a rounded canvas before upload.
+ * - **`OutputOptions.quality` applies at encode time**, not to canvas generation —
+ *   pass it to `canvas.toBlob(cb, 'image/jpeg', quality)` / `toDataURL(type, quality)`.
+ * - Provider defaults (`guides`, `background`, `viewMode`) come from
+ *   `createProvider(config)`; per-cropper `CropperOptions.guides` wins over the
+ *   config default. `maxWidth`/`maxHeight` are enforced on output (cropperjs has no
+ *   max-crop-box constructor option).
+ * - **Wire it** with `setProvider()` from `@molecule/app-image-crop` or
+ *   `bond('image-crop', provider)` from `@molecule/app-bond` — both route through
+ *   the shared registry; `requireProvider()` throws until one has run.
+ *
+ * @module
+ */
+export * from './provider.js';
+export * from './types.js';
+export { default as Cropper } from 'cropperjs';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AAEH,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA;AAG1B,OAAO,EAAE,OAAO,IAAI,OAAO,EAAE,MAAM,WAAW,CAAA"}

package/dist/index.js

@@ -0,0 +1,51 @@
+/**
+ * Cropper.js image-crop provider for `@molecule/app-image-crop` — a REAL
+ * implementation backed by cropperjs v1. `createCropper({ src })` mounts a live
+ * `Cropper` on an image element and every instance method delegates to the
+ * corresponding cropperjs call, so `getCroppedCanvas()` returns the actual
+ * cropped `<canvas>` (call `.toBlob()` / `.toDataURL()` on it to export) — not a
+ * placeholder object.
+ *
+ * @example
+ * ```typescript
+ * import { provider } from '@molecule/app-image-crop-cropperjs'
+ * import { setProvider, requireProvider } from '@molecule/app-image-crop'
+ *
+ * setProvider(provider)   // once, at app startup (bonds.ts)
+ *
+ * const cropper = requireProvider().createCropper({ src: '/avatar.jpg', aspectRatio: 1 })
+ * const canvas = cropper.getCroppedCanvas({ width: 200, height: 200 })
+ * canvas.toBlob((blob) => uploadAvatar(blob), 'image/png')
+ * ```
+ *
+ * @remarks
+ * - **Import cropperjs's stylesheet yourself** — this package does NOT:
+ *   `import 'cropperjs/dist/cropper.css'`. Without it the crop box, handles, and
+ *   drag guides render unstyled (an invisible/broken cropper), the same way Quill
+ *   needs its theme CSS.
+ * - **Browser-only.** `createCropper()` calls `document.createElement('img')` and
+ *   `new Cropper(...)`; construct it in a client-only effect under SSR.
+ * - **cropperjs initializes on the image's `load` event.** Reading `getCropData()`
+ *   or `getCroppedCanvas()` before the source has loaded returns empty/degenerate
+ *   data — drive them after load, or set the region explicitly with `setCropData()`
+ *   in natural-image coordinates first.
+ * - **`circular` is a UI concern, not a pixel op.** cropperjs has no circular
+ *   pixel output; for a round avatar, style the crop box round in CSS
+ *   (`.cropper-view-box, .cropper-face { border-radius: 50% }`) and draw the
+ *   returned canvas into a rounded canvas before upload.
+ * - **`OutputOptions.quality` applies at encode time**, not to canvas generation —
+ *   pass it to `canvas.toBlob(cb, 'image/jpeg', quality)` / `toDataURL(type, quality)`.
+ * - Provider defaults (`guides`, `background`, `viewMode`) come from
+ *   `createProvider(config)`; per-cropper `CropperOptions.guides` wins over the
+ *   config default. `maxWidth`/`maxHeight` are enforced on output (cropperjs has no
+ *   max-crop-box constructor option).
+ * - **Wire it** with `setProvider()` from `@molecule/app-image-crop` or
+ *   `bond('image-crop', provider)` from `@molecule/app-bond` — both route through
+ *   the shared registry; `requireProvider()` throws until one has run.
+ *
+ * @module
+ */
+export * from './provider.js';
+export * from './types.js';
+// Re-export Cropper for advanced usage (custom cropperjs options / events).
+export { default as Cropper } from 'cropperjs';

package/dist/provider.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Cropper.js image crop provider implementation.
+ *
+ * Wraps cropperjs v1 (`new Cropper(imageElement, options)`) behind the molecule
+ * `ImageCropProvider` / `CropperInstance` contract. Every instance method
+ * delegates to the corresponding real cropperjs call, so `getCroppedCanvas()`
+ * returns the actual cropped `<canvas>` — not a placeholder.
+ *
+ * @module
+ */
+import type { ImageCropProvider } from '@molecule/app-image-crop';
+import type { CropperjsConfig } from './types.js';
+/**
+ * Creates a Cropper.js-based image crop provider.
+ *
+ * @param config - Optional provider-level defaults (`guides`, `background`, `viewMode`).
+ * @returns A configured `ImageCropProvider` backed by real cropperjs instances.
+ */
+export declare function createProvider(config?: CropperjsConfig): ImageCropProvider;
+/** Default Cropper.js provider instance. */
+export declare const provider: ImageCropProvider;
+//# sourceMappingURL=provider.d.ts.map

package/dist/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,KAAK,EAIV,iBAAiB,EAElB,MAAM,0BAA0B,CAAA;AAEjC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AA2EjD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,MAAM,GAAE,eAAoB,GAAG,iBAAiB,CA8C9E;AAED,4CAA4C;AAC5C,eAAO,MAAM,QAAQ,EAAE,iBAAoC,CAAA"}

package/dist/provider.js

@@ -0,0 +1,122 @@
+/**
+ * Cropper.js image crop provider implementation.
+ *
+ * Wraps cropperjs v1 (`new Cropper(imageElement, options)`) behind the molecule
+ * `ImageCropProvider` / `CropperInstance` contract. Every instance method
+ * delegates to the corresponding real cropperjs call, so `getCroppedCanvas()`
+ * returns the actual cropped `<canvas>` — not a placeholder.
+ *
+ * @module
+ */
+import Cropper from 'cropperjs';
+/**
+ * Maps the core `CropperOptions` (plus provider-level config defaults) onto the
+ * cropperjs constructor `Options`. `aspectRatio` / `minCropBoxWidth` /
+ * `minCropBoxHeight` are only set when provided so cropperjs keeps its own
+ * free-form / unconstrained defaults otherwise. (Max crop size has no
+ * constructor equivalent in cropperjs — it is enforced on output via
+ * `getCroppedCanvas`; see `toGetCroppedCanvasOptions`.)
+ *
+ * @param options - The core cropper options for this instance.
+ * @param config - Provider-level defaults from `createProvider`.
+ * @returns cropperjs constructor options.
+ */
+const toCropperOptions = (options, config) => {
+    const cropperOptions = {
+        viewMode: config.viewMode ?? 1,
+        guides: options.guides ?? config.guides ?? true,
+        background: config.background ?? true,
+        autoCrop: true,
+    };
+    if (options.aspectRatio !== undefined) {
+        cropperOptions.aspectRatio = options.aspectRatio;
+    }
+    if (options.minWidth !== undefined) {
+        cropperOptions.minCropBoxWidth = options.minWidth;
+    }
+    if (options.minHeight !== undefined) {
+        cropperOptions.minCropBoxHeight = options.minHeight;
+    }
+    return cropperOptions;
+};
+/**
+ * Maps the core `OutputOptions` and the cropper's min/max size constraints onto
+ * cropperjs `getCroppedCanvas` options. `quality` is intentionally NOT mapped:
+ * it is an encode-time setting for `canvas.toBlob`/`toDataURL`, not a
+ * canvas-generation parameter.
+ *
+ * @param options - The core cropper options (for min/max size constraints).
+ * @param output - Optional per-call output options.
+ * @returns cropperjs `getCroppedCanvas` options.
+ */
+const toGetCroppedCanvasOptions = (options, output) => {
+    const canvasOptions = {};
+    if (output?.width !== undefined) {
+        canvasOptions.width = output.width;
+    }
+    if (output?.height !== undefined) {
+        canvasOptions.height = output.height;
+    }
+    if (output?.fillColor !== undefined) {
+        canvasOptions.fillColor = output.fillColor;
+    }
+    if (options.minWidth !== undefined) {
+        canvasOptions.minWidth = options.minWidth;
+    }
+    if (options.minHeight !== undefined) {
+        canvasOptions.minHeight = options.minHeight;
+    }
+    if (options.maxWidth !== undefined) {
+        canvasOptions.maxWidth = options.maxWidth;
+    }
+    if (options.maxHeight !== undefined) {
+        canvasOptions.maxHeight = options.maxHeight;
+    }
+    return canvasOptions;
+};
+/**
+ * Creates a Cropper.js-based image crop provider.
+ *
+ * @param config - Optional provider-level defaults (`guides`, `background`, `viewMode`).
+ * @returns A configured `ImageCropProvider` backed by real cropperjs instances.
+ */
+export function createProvider(config = {}) {
+    return {
+        name: 'cropperjs',
+        createCropper(options) {
+            // cropperjs mounts on an <img>; the core contract only gives us `src`, so
+            // we create the image element here. cropperjs initializes on the image's
+            // `load` event — read crop data / export after load (or set the region
+            // explicitly via setCropData first).
+            const image = document.createElement('img');
+            image.src = options.src;
+            const cropper = new Cropper(image, toCropperOptions(options, config));
+            return {
+                getCroppedCanvas(outputOptions) {
+                    return cropper.getCroppedCanvas(toGetCroppedCanvasOptions(options, outputOptions));
+                },
+                getCropData() {
+                    return cropper.getData();
+                },
+                setCropData(data) {
+                    cropper.setData(data);
+                },
+                reset() {
+                    cropper.reset();
+                },
+                rotate(degrees) {
+                    cropper.rotate(degrees);
+                },
+                zoom(ratio) {
+                    cropper.zoom(ratio);
+                },
+                destroy() {
+                    cropper.destroy();
+                    image.remove();
+                },
+            };
+        },
+    };
+}
+/** Default Cropper.js provider instance. */
+export const provider = createProvider();

package/dist/types.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Configuration for the Cropper.js provider.
+ *
+ * @module
+ */
+/**
+ * Provider-level defaults applied to every cropper created by the provider.
+ *
+ * These map onto cropperjs constructor options. Per-cropper `CropperOptions`
+ * (e.g. `guides`) take precedence over the matching field here.
+ */
+export interface CropperjsConfig {
+    /**
+     * Whether to show the dashed crop guide lines by default. Overridden per-cropper
+     * by `CropperOptions.guides`. Defaults to `true`.
+     */
+    guides?: boolean;
+    /** Whether to render the checkerboard background behind the image. Defaults to `true`. */
+    background?: boolean;
+    /**
+     * cropperjs view mode (0-3) constraining the crop box relative to the canvas /
+     * container. `1` restricts the crop box within the canvas. Defaults to `1`.
+     */
+    viewMode?: 0 | 1 | 2 | 3;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,MAAM,CAAC,EAAE,OAAO,CAAA;IAEhB,0FAA0F;IAC1F,UAAU,CAAC,EAAE,OAAO,CAAA;IAEpB;;;OAGG;IACH,QAAQ,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;CACzB"}

package/dist/types.js

@@ -0,0 +1,6 @@
+/**
+ * Configuration for the Cropper.js provider.
+ *
+ * @module
+ */
+export {};

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@molecule/app-image-crop-cropperjs",
+  "version": "1.0.0",
+  "description": "Cropper.js provider for @molecule/app-image-crop",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "molecule",
+    "image",
+    "crop",
+    "cropperjs"
+  ],
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "directory": "packages/app/bonds/image-crop/cropperjs"
+  },
+  "peerDependencies": {
+    "@molecule/app-image-crop": "^1.0.0"
+  },
+  "devDependencies": {
+    "@molecule/app-image-crop": "1.0.0",
+    "@types/cropperjs": "1.3.3",
+    "@types/node": "26.1.2",
+    "typescript": "6.0.3",
+    "vitest": "4.1.10"
+  },
+  "dependencies": {
+    "cropperjs": "1.6.2"
+  }
+}