@vivekjha659/react-image-editor 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vivek
+
+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.

package/Readme.md

@@ -0,0 +1,138 @@
+# @vivekjha659/react-image-editor
+
+A portable, WhatsApp-style image editor modal for React and Next.js apps —
+crop, freehand drawing, shapes (rectangle / circle / arrow / double-arrow /
+curve), and text overlays. Ships with a dedicated mobile UI and a separate
+desktop sidebar UI.
+
+## Install
+
+```bash
+npm install @vivekjha659/react-image-editor
+```
+
+You'll also need these peer dependencies if your project doesn't already
+have them:
+
+```bash
+npm install react react-dom react-konva konva lucide-react react-icons react-toastify
+```
+
+Import the stylesheet once, anywhere in your app (it's plain compiled CSS —
+no Tailwind setup required on your end, even if you don't use Tailwind):
+
+```js
+import "@vivekjha659/react-image-editor/style.css";
+```
+
+## Quick start
+
+```jsx
+import { useState } from "react";
+import { ImageEditorModal } from "@vivekjha659/react-image-editor";
+
+function Example() {
+  const [isOpen, setIsOpen] = useState(true);
+
+  return (
+    <ImageEditorModal
+      isOpen={isOpen}
+      onClose={() => setIsOpen(false)}
+      image={{ kind: "url", url: "https://example.com/photo.jpg", name: "photo.jpg" }}
+      onSave={(result) => {
+        // result = { blob, file, dataUrl, width, height }
+        console.log(result.file); // a File, ready to upload
+      }}
+    />
+  );
+}
+```
+
+### Image input
+
+`image` accepts any of these shapes:
+
+```ts
+type EditableImageSource =
+  | { kind: "url"; url: string; name?: string }
+  | { kind: "file"; file: File; name?: string }
+  | { kind: "blob"; blob: Blob; name?: string }
+  | { kind: "dataUrl"; dataUrl: string; name?: string };
+```
+
+Use whichever matches what you already have — a remote URL, a `File` from
+an `<input type="file">`, a `Blob`, or a base64 data URL. No manual
+conversion needed.
+
+### Save result
+
+`onSave` receives an `ImageEditResult`:
+
+```ts
+interface ImageEditResult {
+  blob: Blob;
+  file: File;
+  dataUrl: string;
+  width: number;
+  height: number;
+}
+```
+
+All four are derived from the same flattened canvas — pick whichever your
+upload pipeline needs (`file`/`blob` for `FormData` uploads, `dataUrl` for
+inline previews, `width`/`height` for validation or layout).
+
+## Next.js usage
+
+This component reads `window`/`document` on mount (canvas, Konva, object
+URLs) and **cannot be server-rendered**. In the Next.js App Router, every
+component is a Server Component by default, so you must both:
+
+1. Import it with `next/dynamic` and `ssr: false`, and
+2. Only render it from inside a Client Component (a file with its own
+   `"use client"` at the top) — `ssr: false` is not itself valid inside a
+   Server Component.
+
+```jsx
+// components/Editor.jsx
+"use client";
+
+import dynamic from "next/dynamic";
+
+const ImageEditorModal = dynamic(
+  () =>
+    import("@vivekjha659/react-image-editor").then((m) => m.ImageEditorModal),
+  { ssr: false },
+);
+
+export default function Editor({ isOpen, onClose, image, onSave }) {
+  return (
+    <ImageEditorModal
+      isOpen={isOpen}
+      onClose={onClose}
+      image={image}
+      onSave={onSave}
+    />
+  );
+}
+```
+
+Then import `components/Editor.jsx` from wherever you need it — Server or
+Client Components alike, since dynamic-loading is already handled inside
+that wrapper.
+
+## API
+
+| Export | Description |
+|---|---|
+| `ImageEditorModal` | The editor modal component. |
+| `resolveImageSource(source)` | Normalizes an `EditableImageSource` into an `<img>`-usable `src`. Used internally; exported for advanced/custom flows. |
+| `getImageSourceKey(source)` | Stable dependency-array key for an `EditableImageSource`. |
+| `buildImageEditResult(canvas, options?)` | Builds an `ImageEditResult` from a canvas. Used internally by the save flow; exported for advanced/custom flows. |
+
+Full type definitions ship in `dist/index.d.ts` — TypeScript/Next.js
+consumers get autocomplete and inline docs out of the box.
+
+## License
+
+MIT © Vivek

package/dist/index.d.ts

@@ -0,0 +1,99 @@
+import * as React from "react";
+
+/**
+ * The image to load into the editor. Accepts a remote/static URL, a File
+ * (e.g. from an <input type="file">), a Blob, or an already-encoded data
+ * URL. Object URLs created internally for "file"/"blob" sources are
+ * automatically revoked when the source changes or the modal unmounts.
+ */
+export type EditableImageSource =
+  | { kind: "url"; url: string; name?: string }
+  | { kind: "file"; file: File; name?: string }
+  | { kind: "blob"; blob: Blob; name?: string }
+  | { kind: "dataUrl"; dataUrl: string; name?: string };
+
+/**
+ * The result handed to `onSave` once the user confirms their edit. All four
+ * representations are derived from the same flattened canvas in a single
+ * pass — use whichever your upload pipeline needs.
+ */
+export interface ImageEditResult {
+  blob: Blob;
+  file: File;
+  dataUrl: string;
+  width: number;
+  height: number;
+}
+
+export interface ImageEditorModalProps {
+  /** Controls whether the modal is rendered/visible. */
+  isOpen: boolean;
+  /** Called when the user cancels/dismisses the editor without saving. */
+  onClose: () => void;
+  /** The image to edit. See {@link EditableImageSource}. */
+  image: EditableImageSource;
+  /** Called with the edited image once the user confirms save/send. */
+  onSave: (result: ImageEditResult) => void;
+}
+
+/**
+ * A portable, WhatsApp-style image editor modal — crop, freehand drawing,
+ * shapes (rectangle / circle / arrow / double-arrow / curve), and text
+ * overlays, with a dedicated mobile UI and a desktop sidebar UI.
+ *
+ * This component reads `window`/`document` on mount and must not be
+ * server-rendered. In Next.js, import it with:
+ *
+ * ```ts
+ * const ImageEditorModal = dynamic(
+ *   () => import("@yourscope/react-image-editor").then((m) => m.ImageEditorModal),
+ *   { ssr: false },
+ * );
+ * ```
+ */
+export declare function ImageEditorModal(
+  props: ImageEditorModalProps,
+): React.JSX.Element | null;
+
+/**
+ * Normalizes any {@link EditableImageSource} into a usable <img>/canvas src.
+ * Returns a `cleanup()` you must call (e.g. from a `useEffect` return) to
+ * revoke any object URL created for "file"/"blob" sources. Called
+ * internally by `ImageEditorModal`; exported for advanced/custom usage.
+ */
+export declare function resolveImageSource(
+  source: EditableImageSource | null | undefined,
+): {
+  src: string | null;
+  name: string | undefined;
+  isObjectUrl: boolean;
+  cleanup: () => void;
+};
+
+/**
+ * Produces a stable string key for an {@link EditableImageSource}, suitable
+ * for use as a `useEffect`/`useMemo` dependency array entry — avoids
+ * re-resolving (and re-revoking) object URLs just because a caller passed a
+ * fresh object literal with the same underlying value.
+ */
+export declare function getImageSourceKey(
+  source: EditableImageSource | null | undefined,
+): string | null;
+
+/**
+ * Builds an {@link ImageEditResult} from a canvas — blob, File, dataUrl, and
+ * dimensions, all derived from a single `canvas.toBlob()` call. Called
+ * internally by `ImageEditorModal`'s save flow; exported for advanced/
+ * custom usage.
+ */
+export declare function buildImageEditResult(
+  canvas: HTMLCanvasElement,
+  options?: {
+    /** Defaults to "edited-image.png" */
+    fileName?: string;
+    /** Defaults to "image/png" */
+    mimeType?: string;
+    /** Only used for lossy mime types (e.g. "image/jpeg") */
+    quality?: number;
+  },
+): Promise<ImageEditResult>;