@yorab/react-paint 0.14.0 → 0.15.1

package/README.md

@@ -1,25 +1,46 @@
 # React Paint
 
-An open-source canvas-based library for React used for image annotation or as a digital whiteboard
+An open-source canvas-based library for React used for image annotation or as a digital whiteboard.
 
 ## Features
 
+- **Rich Drawing Tools** - Brush, shapes (rectangles, circles, ellipses, polygons, curves), lines, text, and picture support
+- **Interactive Canvas** - Full support for zoom, pan, pinch gestures, and infinite or fixed-size canvases
+- **Shape Manipulation** - Select, move, resize, rotate, and transform shapes with intuitive controls
+- **Customizable Styling** - Control colors, line widths, opacity, line styles, arrows, and fonts
+- **Layer Management** - Built-in layer manipulation panel for organizing your drawings
+- **Export & Import** - Export to PNG images or save/load your work as JSON data
+- **Event System** - Listen to data changes and integrate with your application state
+- **Flexible Configuration** - Extensive options to customize behavior and appearance
+- **TypeScript Support** - Fully typed for better developer experience
 
-## Quick start
+## Quick Start
+
+### Installation
 
 ```bash
-npm i @yorab/react-paint
+npm install @yorab/react-paint
+```
+
+**Note:** React Paint requires `react` and `react-dom` (version 18.x) as peer dependencies.
+
+### Import Styles
+
+Don't forget to import the CSS file in your application:
+
+```tsx
+import '@yorab/react-paint/react-paint.css'
 ```
-Note : react-paint needs <a href="https://www.npmjs.com/package/react">react</a> and <a href="https://www.npmjs.com/package/react-dom">react-dom</a> packages to work properly
 
 ## Usage
 
-### Basic usage
+### Basic Usage
 
 ```tsx
 import { Canvas, Editor, useReactPaint } from '@yorab/react-paint'
+import '@yorab/react-paint/react-paint.css'
 
-const BasicUsage = () => {
+function MyPaintApp() {
   const { editorProps, canvasProps } = useReactPaint()
 
   return (
@@ -30,13 +51,14 @@ const BasicUsage = () => {
 }
 ```
 
-### Advanced usage
+### Advanced Usage
 
 ```tsx
 import { useEffect, useState } from 'react'
 import { Canvas, Editor, useReactPaint, type DrawableShape, type StateData } from '@yorab/react-paint'
+import '@yorab/react-paint/react-paint.css'
 
-const SHAPES_INIT = [
+const SHAPES_INIT: DrawableShape[] = [
   {
     type: 'rect',
     x: 300,
@@ -51,14 +73,14 @@ const SHAPES_INIT = [
       lineWidth: 1,
       lineDash: 0,
       lineArrow: 0,
-     closedPoints: 1,
+      closedPoints: 1,
       fontFamily: 'serif'
     }
   }
 ]
 
-const AdvancedUsage = () => {
-  const [shapes, setShapes] = useState<DrawableShape[] | undefined>(SHAPES_INIT) // keep shapes state for internal use
+function AdvancedPaintApp() {
+  const [shapes, setShapes] = useState<DrawableShape[] | undefined>(SHAPES_INIT)
 
   const { editorProps, canvasProps, registerEvent, unregisterEvent } = useReactPaint({
     width: 1920,
@@ -100,282 +122,23 @@ const AdvancedUsage = () => {
 }
 ```
 
-### Other usages
-
-you will find other usages in <a href="https://github.com/YoRab/react-paint-editor/tree/main/stories">stories</a>
-
-### API
-
-#### `useReactPaint`
-
-##### Parameters
-
-| Parameter | Type | Description | Default value |
-| :--- | :--- | :--- | :--- |
-| `width` | `number` | *Optional*. Canvas width in px | `1000` |
-| `height` | `number` | *Optional*. Canvas height in px | `600` |
-| `shapes` | [`DrawableShape[]`](####drawableshape) | *Optional*. Array of shapes used to init the canvas | `undefined` |
-| `mode` | `editor\|viewer` | *Optional*. `editor` lets you interact with the canvas and editor. `viewer` hides the editor and makes the canvas read-only| `editor` |
-| `disabled` | `boolean` | *Optional*. Global parameter used to prevent interaction with every element in the editor or canvas | `false` |
-| `options` | [`OptionalOptions`](####optionaloptions) | *Optional*. Set of options to customize available features  | See [`OptionalOptions`]((####optionaloptions)) |
-
-
-##### Returns
-
-| Parameter | Type | Description |
-| :--- | :--- | :--- |
-| `canvasProps` | `object` | Set of properties to forward to Canvas component |
-| `editorProps` | `object` | Set of properties to forward to Editor component |
-| `registerEvent` | `(event: "dataChanged", listener: (data: StateData,  source: 'user' \| 'remote') => void) => void` |  registerEvent is used to register a listener for special events triggered by react-paint. The only currently available event is `dataChanged`. `source` indicates the origin of the state update  |
-| `unregisterEvent` | `(event: "dataChanged", listener?: ((data: StateData,  source: 'user' \| 'remote') => void) \| undefined) => void` | unregisterEvent is used to unregister a listener previously registered. Omitting listener will result in unregistering every listeners for the the given event | 
-| `resetCanvas` | `(shapes: DrawableShape[], clearHistory?: boolean) => Promise<void>` | reset canvas with the given shapes. use `[]` or `undefined` to clear the canvas. Set `false` to `clearHistory` to prevent history stack to be cleared | 
-| `getCurrentImage` | `(view: 'defaultView' \|  'currentZoom' \| 'fitToShapes') => string` | Returns a data URL containing the content of the current canvas as a PNG image. `defaultView` will export a picture with dimensions based on canvas and no zoom. `currentZoom` will export a picture with dimensions based on canvas and current zoom and offset. `fitToShapes` will export a picture containing all drawn shapes. |
-| `getCurrentData` | `() => StateData` | Returns the current state of the canvas  |
-
-#### `OptionalOptions`
-
-| Parameter | Type | Description | Default value |
-| :--- | :--- | :--- | :--- |
-| `layersManipulation` | `boolean` | *Optional*. Show panel to manipulate layers | `true` |
-| `grid` | `number` | *Optional*. Size in px for grid cells. Set to 0 to hide grid | `0` |
-| `canGrow` | `boolean` | *Optional*. Allow canvas to upscale and grow to fit container | `false` |
-| `canShrink` | `boolean` | *Optional*. Allow canvas to downscale and shrink to fit container | `true` |
-| `withExport` | `boolean` | *Optional*. Show button to manually export to PNG | `true` |
-| `withLoadAndSave` | `boolean` | *Optional*.Show button to manually save or load data  | `true` |
-| `withUploadPicture` | `boolean` | *Optional*. Show button to add picture shape stored in base64 | `true` |
-| `withUrlPicture` | `boolean` | *Optional*.Show button to add picture shape with only the url stored. Need connectivity to be displayed | `false` |
-| `withFrameSelection` | `boolean` | *Optional*.Enable frame selection | `true` |
-| `withSkeleton` | `boolean` | *Optional*. Display skeleton when hovering shape | `false` |
-| `clearCallback` | `'empty' \| 'defaultShapes' \| (() => DrawableShape[])` | *Optional*. Set clear button behavior. `empty` clear all shapes, `defaultShapes` uses shapes given in props. It is also possible to set a function returning an array of shapes | `empty` |
-| `brushAlgo` | `'simple' \| 'quadratic'` | *Optional*. Choose which algorithm to display brush shape. `simple` displays path as is, `quadratic` uses quadratic bézier curves  | `simple` |
-| `isBrushShapeDoneOnMouseUp` | `boolean` | *Optional*. Choose whether drawing brush shape after releasing mouse should create a new shape or not | `true` |
-| `canvasSelectionPadding` | `boolean` | *Optional*. Padding between shape and selection frame | `0` |
-| `availableTools` | `CustomToolInput[]` | *Optional*. List of available tools. See CustomTool for more details | `` |
-| `size` | `'fixed' \| 'infinite'` | *Optional*. Choose canvas size mode. `fixed` canvas is bound within its width and height, `infinite` canvas has no bound  | `fixed` |
-| `canZoom` | `'never' \| 'always'` | *Optional*. Choose wether zoom is available `never` zoom is not available, `always` zoom is available  | `never` |
-
-
-
-
-#### Canvas
-
-##### Parameters
-
-| Parameter | Type | Description | Default value |
-| :--- | :--- | :--- | :--- |
-| `canvasProps` | `object` | **Required**. Set of properties coming from useReactPaint |  |
-| `className` | `string` | *Optional*. Classname for canvas parent node | `undefined` |
-| `style` | `CSSProperties` | *Optional*. css properties to inject to canvas parent node | `undefined` |
-| `options` | `{canvasBackgroundColor?: string; canvasSelectionColor?: string; canvasSelectionWidth?: number}` | *Optional*. Set of properties to use to customize canvas style | `{canvasBackgroundColor: 'white'; canvasSelectionColor: 'blue'; canvasSelectionWidth: 2}` |
-
-
-#### Editor
-
-##### Parameters
-
-| Parameter | Type | Description | Default value |
-| :--- | :--- | :--- | :--- |
-| `editorProps` | `object` | **Required**. Set of properties coming from useReactPaint |  |
-| `children` | `ReactNode` | **Required**. Need Canvas component to work properly |  |
-| `className` | `string` | *Optional*. Classname for canvas parent node | `undefined` |
-| `style` | `CSSProperties` | *Optional*. css properties to inject to canvas parent node | `undefined` |
-| `options` | `{    toolbarBackgroundColor?: string;    dividerColor?: string;    fontRadius?: number;    fontDisabledColor?: string;    fontDisabledBackgroundColor?: string;    fontColor?: string;    fontBackgroundColor?: string;    fontSelectedColor?: string;    fontSelectedBackgroundColor?: string;    fontHoverColor?: string;    fontHoverBackgroundColor?: string;  }` | *Optional*. Set of properties to use to customize editor style | ` {  toolbarBackgroundColor: 'white',  dividerColor: '#36418129',  fontRadius: 8,  fontDisabledColor: '#3641812b',  fontDisabledBackgroundColor: 'transparent',  fontColor: '#364181',  fontBackgroundColor: 'transparent',  fontSelectedColor: 'white',  fontSelectedBackgroundColor: '#364181',  fontHoverColor: '#364181',  fontHoverBackgroundColor: '#afd8d8'}` |
-
-### Types
-
-#### `DrawableShape`
-#### `StateData`
-
-#### `CustomTool`
-
-```
- type CustomTool = {
-  id: string
-  icon: string
-  label: string
-} & (
-  | {
-      type: 'brush'
-      settings: ToolsSettingsType<'brush'>
-    }
-  | {
-      type: 'circle'
-      settings: ToolsSettingsType<'circle'>
-    }
-  | {
-      type: 'ellipse'
-      settings: ToolsSettingsType<'ellipse'>
-    }
-  | {
-      type: 'rect'
-      settings: ToolsSettingsType<'rect'>
-    }
-  | {
-      type: 'square'
-      settings: ToolsSettingsType<'square'>
-    }
-  | {
-      type: 'line'
-      settings: ToolsSettingsType<'line'>
-    }
-  | {
-      type: 'polygon'
-      settings: ToolsSettingsType<'polygon'>
-    }
-  | {
-      type: 'curve'
-      settings: ToolsSettingsType<'curve'>
-    }
-  | {
-      type: 'text'
-      settings: ToolsSettingsType<'text'>
-    }
-  | {
-      type: 'picture'
-      settings: ToolsSettingsType<'picture'>
-    }
-)
-
-type SettingsOpacity = {
-  opacity: {
-    min: number
-    max: number
-    step: number
-    default: number
-    hidden?: boolean
-  }
-}
-
-type SettingsStrokeColor = {
-  strokeColor: {
-    values: string[]
-    default: string
-    hidden?: boolean
-  }
-}
-
-type SettingsFillColor = {
-  fillColor: {
-    values: string[]
-    default: string
-    hidden?: boolean
-  }
-}
-
-type SettingsLineWidth = {
-  lineWidth: {
-    min: number
-    max: number
-    step: number
-    default: number
-    hidden?: boolean
-  }
-}
-
-type SettingsLineDash = {
-  lineDash: {
-    values: number[]
-    default: number
-    hidden?: boolean
-  }
-}
-
-type SettingsLineArrow = {
-  lineArrow: {
-    values: number[]
-    default: number
-    hidden?: boolean
-  }
-}
-
-type SettingsFont = {
-  fontFamily: {
-    values: string[]
-    default: string
-    hidden?: boolean
-  }
-  fontBold: {
-    values: boolean[]
-    default: boolean
-    hidden?: boolean
-  }
-  fontItalic: {
-    values: boolean[]
-    default: boolean
-    hidden?: boolean
-  }
-}
-
-type SettingsClosedPoints = {
-  closedPoints: {
-    default: number
-    hidden?: boolean
-  }
-}
-
-type ToolsRectSettings = SettingsStrokeColor & SettingsFillColor & SettingsOpacity & SettingsLineWidth & SettingsLineDash
-
-type ToolsSquareSettings = SettingsStrokeColor & SettingsFillColor & SettingsOpacity & SettingsLineWidth & SettingsLineDash
+## Documentation
 
-type ToolsCircleSettings = SettingsStrokeColor & SettingsFillColor & SettingsOpacity & SettingsLineWidth & SettingsLineDash
+For complete documentation, API reference, examples, and interactive demos, visit our **Storybook**:
 
-type ToolsEllipseSettings = SettingsStrokeColor & SettingsFillColor & SettingsOpacity & SettingsLineWidth & SettingsLineDash
-
-type ToolsTextSettings = SettingsOpacity & SettingsStrokeColor & SettingsFont
-
-type ToolsLineSettings = SettingsOpacity & SettingsStrokeColor & SettingsLineWidth & SettingsLineDash & SettingsLineArrow
-
-type ToolsBrushSettings = SettingsOpacity & SettingsStrokeColor & SettingsLineWidth & SettingsLineDash
-
-type ToolsPolygonSettings = SettingsOpacity &
-  SettingsStrokeColor &
-  SettingsFillColor &
-  SettingsLineWidth &
-  SettingsLineDash &
-  SettingsClosedPoints
-
-type ToolsCurveSettings = SettingsOpacity &
-  SettingsStrokeColor &
-  SettingsFillColor &
-  SettingsLineWidth &
-  SettingsLineDash &
-  SettingsClosedPoints
-
-type ToolsTriangleSettings = SettingsStrokeColor & SettingsFillColor & SettingsOpacity & SettingsLineWidth & SettingsLineDash
-
-type ToolsPictureSettings = SettingsOpacity
-
-type ToolsSettingsType<T extends ShapeType> = T extends 'rect'
-  ? ToolsRectSettings
-  : T extends 'square'
-    ? ToolsSquareSettings
-    : T extends 'circle'
-      ? ToolsCircleSettings
-      : T extends 'ellipse'
-        ? ToolsEllipseSettings
-        : T extends 'text'
-          ? ToolsTextSettings
-          : T extends 'line'
-            ? ToolsLineSettings
-            : T extends 'brush'
-              ? ToolsBrushSettings
-              : T extends 'polygon'
-                ? ToolsPolygonSettings
-                : T extends 'curve'
-                  ? ToolsCurveSettings
-                  : T extends 'triangle'
-                    ? ToolsTriangleSettings
-                    : T extends 'picture'
-                      ? ToolsPictureSettings
-                      : never
-
-```
+**[📚 View Storybook Documentation](https://yorab.github.io/react-paint-editor/)**
 
-## Changelog
-https://github.com/YoRab/react-paint-editor/blob/main/Changelog.md
+The Storybook includes:
+- Getting started guide
+- Complete API reference
+- Interactive playground
+- Usage examples
+- Configuration options
 
-## License
-<a href="https://github.com/YoRab/react-paint-editor/blob/main/LICENSE.txt">MIT</a>
+## Resources
 
+- [Changelog](https://github.com/YoRab/react-paint-editor/blob/main/Changelog.md)
+- [License](https://github.com/YoRab/react-paint-editor/blob/main/LICENSE.txt) (MIT)
+- [GitHub Repository](https://github.com/YoRab/react-paint-editor)
 
 ## Contributing

package/dist/canvas/components/Canvas.d.ts

@@ -11,6 +11,7 @@ type DrawerType = {
     settings: UtilsSettings;
     isEditMode: boolean;
     shapes: ShapeEntity[];
+    duplicateShapes: (shapesToDuplicate: ShapeEntity[]) => void;
     saveShapes: () => void;
     addShapes: (newShape: ShapeEntity[]) => void;
     updateSingleShape: (updatedShape: ShapeEntity[], withSave?: boolean) => void;
@@ -43,6 +44,7 @@ type DrawerType = {
     setSelectionMode: React.Dispatch<React.SetStateAction<SelectionModeData<number | Point>>>;
     isShiftPressed: boolean;
     isAltPressed: boolean;
+    isSpacePressed: boolean;
     withFrameSelection: boolean;
     withSkeleton: boolean;
     setCanvasMoveAcceleration: React.Dispatch<React.SetStateAction<Point>>;

package/dist/canvas/components/EditTextBox.d.ts

@@ -1,9 +1,9 @@
 import type { UtilsSettings } from './../../canvas/constants/app';
-import type { DrawableShape } from './../../common/types/Shapes';
+import type { ShapeEntity } from './../../common/types/Shapes';
 import './EditTextBox.css';
 type EditTextBoxType = {
     disabled?: boolean;
-    shape: DrawableShape<'text'>;
+    shape: ShapeEntity<'text'>;
     defaultValue: string[];
     settings: UtilsSettings;
     updateValue: (newValue: string[]) => void;

package/dist/canvas/constants/app.d.ts

@@ -26,6 +26,7 @@ export type UtilsSettings = {
         zoom: boolean;
         edition: boolean;
     };
+    debug: boolean;
 };
 type AppOptionsType = {
     layersManipulation: boolean;
@@ -45,6 +46,7 @@ type AppOptionsType = {
     canvasSelectionPadding: number;
     size: Size;
     canZoom: 'never' | 'always';
+    debug: boolean;
 };
 export type OptionalOptions = RecursivePartial<AppOptionsType>;
 export declare const DEFAULT_OPTIONS: AppOptionsType;

package/dist/canvas/constants/keyboard.d.ts

@@ -0,0 +1,24 @@
+export declare const KeyboardCode: {
+    readonly ArrowUp: "ArrowUp";
+    readonly ArrowDown: "ArrowDown";
+    readonly ArrowLeft: "ArrowLeft";
+    readonly ArrowRight: "ArrowRight";
+    readonly Delete: "Delete";
+    readonly Backspace: "Backspace";
+    readonly Escape: "Escape";
+    readonly Shift: "Shift";
+    readonly Alt: "Alt";
+    readonly Option: "Option";
+    readonly Space: " ";
+    readonly z: "z";
+    readonly Z: "Z";
+    readonly y: "y";
+    readonly Y: "Y";
+    readonly Plus: "+";
+    readonly Minus: "-";
+    readonly Zero: "0";
+};
+export declare const KeyboardCommand: {
+    readonly Copy: "copy";
+    readonly Paste: "paste";
+};

package/dist/canvas/hooks/useComponent.d.ts

@@ -3,8 +3,10 @@ import { type RefObject } from 'react';
 type UseComponentType = {
     settings: UtilsSettings;
     componentRef: RefObject<HTMLElement | null>;
+    canvasRef: RefObject<HTMLCanvasElement | null>;
 };
-declare const useComponent: ({ settings, componentRef }: UseComponentType) => {
+declare const useComponent: ({ settings, componentRef, canvasRef }: UseComponentType) => {
     isInsideComponent: boolean;
+    isInsideCanvas: boolean;
 };
 export default useComponent;

package/dist/canvas/hooks/useDebounce.d.ts

@@ -0,0 +1,2 @@
+declare const useDebounce: <T extends (...args: any[]) => void>(callback: T, delay?: number) => (...args: Parameters<T>) => void;
+export default useDebounce;

package/dist/canvas/hooks/useDrawableCanvas.d.ts

@@ -14,6 +14,7 @@ type UseCanvasType = {
     setActiveTool: React.Dispatch<React.SetStateAction<ToolsType>>;
     refreshHoveredShape: (e: MouseEvent | TouchEvent, ctx: CanvasRenderingContext2D, cursorPosition: Point, isInsideMask: boolean) => void;
     refreshSelectedShapes: (ctx: CanvasRenderingContext2D, cursorPosition: Point, settings: UtilsSettings) => void;
+    duplicateShapes: (shapesToDuplicate: ShapeEntity[]) => void;
     canvasOffsetStartData: {
         start: Point;
         originalOffset: Point;
@@ -36,8 +37,9 @@ type UseCanvasType = {
     isAltPressed: boolean;
     withFrameSelection: boolean;
     settings: UtilsSettings;
+    isSpacePressed: boolean;
 };
-declare const useDrawableCanvas: ({ addShapes, drawCanvasRef, setActiveTool, refreshHoveredShape, shapes, selectionMode, activeTool, isInsideComponent, setCanvasOffset, selectedShape, canvasOffsetStartData, refreshSelectedShapes, setSelectedShape, setSelectionFrame, setCanvasOffsetStartData, updateSingleShape, saveShapes, setSelectionMode, setCanvasMoveAcceleration, settings, isShiftPressed, isAltPressed, withFrameSelection }: UseCanvasType) => {
+declare const useDrawableCanvas: ({ addShapes, drawCanvasRef, setActiveTool, refreshHoveredShape, shapes, selectionMode, activeTool, isInsideComponent, setCanvasOffset, selectedShape, canvasOffsetStartData, refreshSelectedShapes, setSelectedShape, setSelectionFrame, setCanvasOffsetStartData, updateSingleShape, duplicateShapes, saveShapes, setSelectionMode, setCanvasMoveAcceleration, settings, isShiftPressed, isAltPressed, withFrameSelection, isSpacePressed }: UseCanvasType) => {
     hoverMode: HoverModeData;
 };
 export default useDrawableCanvas;

package/dist/canvas/hooks/useKeyboard.d.ts

@@ -4,6 +4,7 @@ import type { Point, SelectionType, ShapeEntity } from './../../common/types/Sha
 import type { ToolsType } from './../../common/types/tools';
 type UseKeyboardType = {
     isInsideComponent: boolean;
+    isInsideCanvas: boolean;
     selectedShape: SelectionType | undefined;
     pasteShapes: (shape: ShapeEntity[]) => void;
     updateShapes: (shapes: ShapeEntity[]) => void;
@@ -13,6 +14,7 @@ type UseKeyboardType = {
     forwardShape: () => void;
     setShiftPressed: (value: React.SetStateAction<boolean>) => void;
     setAltPressed: (value: React.SetStateAction<boolean>) => void;
+    setIsSpacePressed: (value: React.SetStateAction<boolean>) => void;
     isEditingText: boolean;
     setActiveTool: (tool: ToolsType) => void;
     setSelectionMode: (mode: SelectionModeData<number | Point>) => void;
@@ -21,6 +23,8 @@ type UseKeyboardType = {
         frame: [Point, Point];
     } | undefined) => void;
     settings: UtilsSettings;
+    setCanvasZoom: (action: 'unzoom' | 'zoom' | 'default') => void;
+    resetZoom: () => void;
 };
-declare const useKeyboard: ({ isInsideComponent, selectedShape, isEditingText, settings, setSelectedShape, setActiveTool, setSelectionMode, setSelectionFrame, removeShape, pasteShapes, updateShapes, backwardShape, forwardShape, setShiftPressed, setAltPressed }: UseKeyboardType) => {};
+declare const useKeyboard: ({ isInsideComponent, isInsideCanvas, selectedShape, isEditingText, settings, setSelectedShape, setActiveTool, setCanvasZoom, resetZoom, setSelectionMode, setSelectionFrame, removeShape, pasteShapes, updateShapes, backwardShape, forwardShape, setShiftPressed, setAltPressed, setIsSpacePressed }: UseKeyboardType) => {};
 export default useKeyboard;