react-image-mask
Version:
A React component for creating image masks with drawing tools
369 lines (362 loc) • 13.5 kB
TypeScript
/// <reference types="react" />
import * as react from 'react';
import * as react_jsx_runtime from 'react/jsx-runtime';
/**
* Available tool modes for the image mask component
* @typedef {string} ToolMode
*/
type ToolMode =
/** Move/pan tool for navigating around the canvas */ 'move' |
/** Freehand drawing tool for creating mask areas */ 'mask-freehand' |
/** Box selection tool for creating rectangular mask areas */ 'mask-box' |
/** Polygon selection tool for creating custom shaped mask areas */ 'mask-polygon' |
/** Freehand eraser tool for removing mask areas */ 'eraser-freehand' |
/** Box eraser tool for removing rectangular mask areas */ 'eraser-box' |
/** Clear tool for removing all mask areas */ 'clear';
/**
* Represents a 2D point with x and y coordinates
* @interface Point
*/
interface Point {
/** X coordinate in pixels */
x: number;
/** Y coordinate in pixels */
y: number;
}
/**
* Represents a rectangular selection area
* @interface BoxSelection
*/
interface BoxSelection {
/** X coordinate of the top-left corner */
x: number;
/** Y coordinate of the top-left corner */
y: number;
/** Width of the selection in pixels */
width: number;
/** Height of the selection in pixels */
height: number;
}
/**
* Represents a state in the undo/redo history
* @interface HistoryState
*/
interface HistoryState {
/** Base64 encoded canvas data representing the mask state */
canvasData: string;
/** The tool mode that was active when this state was created */
toolMode: ToolMode;
}
/**
* Configuration object for controlling which UI controls are displayed
* @interface ControlsConfig
*/
interface ControlsConfig {
/** Whether to show the download mask button */
showDownloadButton?: boolean;
/** Whether to show the clear mask button */
showClearButton?: boolean;
/** Whether to show the undo/redo buttons */
showUndoRedo?: boolean;
/** Whether to show the tool selection buttons */
showToolButtons?: boolean;
/** Whether to show brush size controls */
showBrushControls?: boolean;
/** Whether to show color picker controls */
showColorControls?: boolean;
/** Whether to show opacity slider controls */
showOpacityControls?: boolean;
/** Whether to show zoom controls */
showZoomControls?: boolean;
}
/**
* Props for the main ImageMask component
* @interface ImageMaskProps
*/
interface ImageMaskProps {
/** Source URL of the image to mask. Defaults to a placeholder image */
src?: string;
/** Color of the mask in RGBA format. Defaults to 'rgba(0, 0, 0, 1)' */
maskColor?: string;
/** Width of the canvas in pixels. If not provided, uses container width */
width?: number;
/** Height of the canvas in pixels. If not provided, uses container height */
height?: number;
/** Opacity of the mask overlay (0-1). Defaults to 0.5 */
opacity?: number;
/** Size of the brush in pixels. Defaults to 10 */
brushSize?: number;
/** Configuration for which controls to display */
controlsConfig?: ControlsConfig;
/** Callback fired when the mask data changes */
onMaskChange?: (maskData: string | null) => void;
/** Callback fired when the zoom level changes */
onZoomChange?: (zoom: number) => void;
/** Callback fired when the history state changes (undo/redo availability) */
onHistoryChange?: (canUndo: boolean, canRedo: boolean) => void;
/** CSS class name for the container element */
className?: string;
}
/**
* Props for the ImageMaskCanvas component (lower-level canvas component)
* @interface ImageMaskCanvasProps
*/
interface ImageMaskCanvasProps {
/** Source URL of the image to mask (required) */
src: string;
/** Color of the mask in RGBA format */
maskColor?: string;
/** Width of the canvas in pixels */
width?: number;
/** Height of the canvas in pixels */
height?: number;
/** Opacity of the mask overlay (0-1) */
opacity?: number;
/** Current active tool mode */
toolMode: ToolMode;
/** React ref for the canvas component */
ref?: React.RefObject<React.FC<ImageMaskCanvasProps>>;
/** Callback fired when the zoom level changes */
onZoomChange?: (zoom: number) => void;
/** Callback fired when the history state changes */
onHistoryChange?: (canUndo: boolean, canRedo: boolean) => void;
}
/**
* Represents a color option for the color picker
* @interface ColorOption
*/
interface ColorOption {
/** Display name of the color */
name: string;
/** RGBA color value */
value: string;
}
/**
* Ref interface for the ImageMaskCanvas component
* Provides imperative API for controlling the canvas programmatically
* @interface ImageMaskCanvasRef
*/
interface ImageMaskCanvasRef {
/** Returns the current mask as a base64 encoded PNG image */
getMaskData: () => string | null;
/** Clears all mask data from the canvas */
clearMask: () => void;
/** Undoes the last action */
undo: () => void;
/** Redoes the last undone action */
redo: () => void;
/** Sets the active tool mode */
setToolMode: (mode: ToolMode) => void;
/** Sets the mask color */
setMaskColor: (color: string) => void;
/** Sets the mask opacity (0-1) */
setOpacity: (opacity: number) => void;
/** Sets the brush size in pixels */
setBrushSize: (size: number) => void;
/** Whether undo is currently available */
canUndo: boolean;
/** Whether redo is currently available */
canRedo: boolean;
/** Sets the zoom level as a percentage (100 = 100%) */
setZoom: (zoomPercentage: number) => void;
}
/**
* Ref interface for the main ImageMask component
* Provides basic imperative API for controlling the component
* @interface ImageMaskRef
*/
interface ImageMaskRef {
/** Returns the current mask as a base64 encoded PNG image */
getMaskData: () => string | null;
/** Clears all mask data from the canvas */
clearMask: () => void;
/** Undoes the last action */
undo: () => void;
/** Redoes the last undone action */
redo: () => void;
}
/**
* ImageMask - A comprehensive React component for creating image masks with drawing tools
*
* This is the main component that combines the drawing canvas with intuitive controls.
* It provides multiple drawing tools (freehand, box, polygon), eraser tools, zoom/pan
* functionality, and full touch gesture support for mobile devices.
*
* Features:
* - Multiple drawing tools (freehand, box selection, polygon selection)
* - Eraser tools for precise mask editing
* - Zoom and pan functionality with mouse wheel and touch gestures
* - Undo/redo history with configurable depth
* - Customizable brush size, opacity, and colors
* - Touch gestures for iPad/mobile (pinch-to-zoom, two-finger pan)
* - Apple Pencil support
* - Export functionality (PNG download)
* - Configurable UI controls
*
* @component
* @example
* ```tsx
* // Basic usage
* <ImageMask
* src="https://example.com/image.jpg"
* onMaskChange={(maskData) => console.log('Mask updated:', maskData)}
* />
*
* // Advanced usage with custom configuration
* const controlsConfig = {
* showDownloadButton: false,
* showBrushControls: true,
* showColorControls: true
* };
*
* <ImageMask
* src="https://example.com/image.jpg"
* maskColor="rgba(255, 0, 0, 1)"
* opacity={0.7}
* brushSize={20}
* controlsConfig={controlsConfig}
* onMaskChange={handleMaskChange}
* onZoomChange={handleZoomChange}
* onHistoryChange={handleHistoryChange}
* />
* ```
*/
declare const ImageMask: react.ForwardRefExoticComponent<ImageMaskProps & react.RefAttributes<ImageMaskRef>>;
//# sourceMappingURL=ImageMask.d.ts.map
/**
* ImageMaskCanvas - The core canvas component for image masking with drawing tools
*
* This is the low-level canvas component that handles all drawing operations, touch gestures,
* zoom/pan functionality, and mask data management. It uses Konva.js for high-performance
* canvas rendering and supports multiple drawing tools with full touch gesture support.
*
* Key Features:
* - Multiple drawing tools (freehand, box, polygon selection)
* - Eraser tools for precise editing
* - Zoom/pan with mouse wheel and touch gestures
* - Full iPad/mobile support with pinch-to-zoom and two-finger pan
* - Apple Pencil compatibility
* - Undo/redo history management
* - Real-time mask preview with customizable opacity and colors
* - Responsive container sizing
* - High-performance rendering with Konva.js
*
* @component
* @example
* ```tsx
* const canvasRef = useRef<ImageMaskCanvasRef>(null);
*
* <ImageMaskCanvas
* ref={canvasRef}
* src="https://example.com/image.jpg"
* toolMode="mask-freehand"
* onZoomChange={(zoom) => console.log('Zoom:', zoom)}
* onHistoryChange={(canUndo, canRedo) => console.log('History:', { canUndo, canRedo })}
* />
* ```
*/
declare const ImageMaskCanvas: react.ForwardRefExoticComponent<Omit<ImageMaskCanvasProps, "ref"> & react.RefAttributes<ImageMaskCanvasRef>>;
//# sourceMappingURL=ImageMaskCanvas.d.ts.map
/**
* ImageMaskControls - UI controls component for the image mask editor
*
* This component provides a comprehensive control panel with tool selection,
* settings adjustments, and action buttons. It includes dropdown menus for
* color selection, brush sizes, zoom levels, and tool-specific options.
* All controls are configurable and can be shown/hidden based on requirements.
*
* Features:
* - Tool selection (move, freehand, box, polygon, eraser tools)
* - Color picker with predefined colors and custom color input
* - Brush size selection with visual preview
* - Opacity slider for mask transparency
* - Zoom controls with preset levels
* - Undo/redo functionality
* - Clear and download actions
* - Fully configurable UI (show/hide sections)
* - Responsive dropdown menus with click-outside-to-close
*
* @component
* @example
* ```tsx
* <ImageMaskControls
* setToolMode={setToolMode}
* toolMode={toolMode}
* clearCanvas={clearCanvas}
* currentZoom={zoom}
* undo={undo}
* redo={redo}
* canUndo={canUndo}
* canRedo={canRedo}
* onDownloadMask={handleDownload}
* setMaskColor={setMaskColor}
* currentMaskColor={maskColor}
* setOpacity={setOpacity}
* currentOpacity={opacity}
* setBrushSize={setBrushSize}
* currentBrushSize={brushSize}
* setZoom={setZoom}
* controlsConfig={controlsConfig}
* />
* ```
*/
declare const ImageMaskControls: ({ setToolMode, toolMode, clearCanvas, currentZoom, undo, redo, canUndo, canRedo, onDownloadMask, setMaskColor, currentMaskColor, setOpacity, currentOpacity, setBrushSize, currentBrushSize, setZoom, controlsConfig }: {
/** Function to set the active tool mode */
setToolMode: (toolMode: ToolMode) => void;
/** Currently active tool mode */
toolMode: ToolMode;
/** Function to clear all mask data */
clearCanvas?: (() => void) | undefined;
/** Current zoom level as percentage */
currentZoom?: number | undefined;
/** Function to undo the last action */
undo?: (() => void) | undefined;
/** Function to redo the last undone action */
redo?: (() => void) | undefined;
/** Whether undo is currently available */
canUndo?: boolean | undefined;
/** Whether redo is currently available */
canRedo?: boolean | undefined;
/** Function to download the current mask */
onDownloadMask?: (() => void) | undefined;
/** Function to set the mask color */
setMaskColor?: ((color: string) => void) | undefined;
/** Current mask color in RGBA format */
currentMaskColor?: string | undefined;
/** Function to set the mask opacity */
setOpacity?: ((opacity: number) => void) | undefined;
/** Current mask opacity (0-1) */
currentOpacity?: number | undefined;
/** Function to set the brush size */
setBrushSize?: ((size: number) => void) | undefined;
/** Current brush size in pixels */
currentBrushSize?: number | undefined;
/** Function to set the zoom level */
setZoom?: ((zoom: number) => void) | undefined;
/** Configuration for which controls to display */
controlsConfig?: ControlsConfig | undefined;
}) => react_jsx_runtime.JSX.Element;
/**
* Downloads the current mask as a PNG image file
*
* This utility function processes the mask canvas data and converts it to a
* standard mask format where white pixels represent masked areas and black
* pixels represent background areas. The resulting image is downloaded as
* 'mask.png' to the user's default download location.
*
* @param {HTMLCanvasElement | null} maskCanvas - The canvas element containing the mask data
* @param {number} width - The desired width of the output mask image in pixels
* @param {number} height - The desired height of the output mask image in pixels
*
* @example
* ```typescript
* // Download a mask from a canvas
* const canvas = document.getElementById('maskCanvas') as HTMLCanvasElement;
* downloadMask(canvas, 1024, 768);
* ```
*
* @returns {void} This function doesn't return a value, it triggers a download
*/
declare const downloadMask: (maskCanvas: HTMLCanvasElement | null, width: number, height: number) => void;
export { ImageMask, ImageMaskCanvas, ImageMaskControls, downloadMask };
export type { BoxSelection, ColorOption, HistoryState, ImageMaskCanvasProps, ImageMaskCanvasRef, ImageMaskProps, ImageMaskRef, Point, ToolMode };