react-img-cutout 1.2.0 → 1.4.0

package/README.md

@@ -1,4 +1,5 @@
 # react-img-cutout
+[![npm version](https://img.shields.io/npm/v/react-img-cutout.svg)](https://www.npmjs.com/package/react-img-cutout)
 
 `react-img-cutout` provides a simple, composable component for creating interactive image regions. 
 It enables pixel-perfect interaction using transparent PNG cutouts, while also supporting standard bounding boxes and polygons for geometric shapes. 

package/dist/components/cutout-viewer/cutout-viewer.d.ts

@@ -3,8 +3,11 @@ import { type HoverEffectPreset, type HoverEffect } from "./hover-effects";
 import { Cutout } from "./cutouts/image/cutout";
 import { BBoxCutout } from "./cutouts/bbox/bbox-cutout";
 import { PolygonCutout } from "./cutouts/polygon/polygon-cutout";
+import { CircleCutout } from "./cutouts/circle/circle-cutout";
 import { CutoutOverlay } from "./cutouts/cutout-overlay";
 import { DrawPolygon } from "./drawing/draw-polygon";
+import { DrawRectangle } from "./drawing/draw-rectangle";
+import { DrawCircle } from "./drawing/draw-circle";
 export interface CutoutViewerProps {
     /** URL of the main background image */
     mainImage: string;
@@ -16,6 +19,8 @@ export interface CutoutViewerProps {
     enabled?: boolean;
     /** When true, all cutouts show their active/hovered state simultaneously */
     showAll?: boolean;
+    /** When true, forces all overlays to be visible regardless of hover or selected state (default: false) */
+    showOverlays?: boolean;
     /** Minimum alpha value 0-255 for pixel hit-testing (default: 30) */
     alphaThreshold?: number;
     /** Delay in ms before the hover state clears after leaving a cutout (default: 150) */
@@ -40,8 +45,11 @@ type CutoutViewerComponent = ((props: CutoutViewerProps) => ReactElement) & {
     Cutout: typeof Cutout;
     BBoxCutout: typeof BBoxCutout;
     PolygonCutout: typeof PolygonCutout;
+    CircleCutout: typeof CircleCutout;
     Overlay: typeof CutoutOverlay;
     DrawPolygon: typeof DrawPolygon;
+    DrawRectangle: typeof DrawRectangle;
+    DrawCircle: typeof DrawCircle;
 };
 export declare const CutoutViewer: CutoutViewerComponent;
 export {};

package/dist/components/cutout-viewer/cutouts/circle/circle-cutout.d.ts

@@ -0,0 +1,23 @@
+import { type ReactNode } from "react";
+import { type HoverEffect, type HoverEffectPreset } from "../../hover-effects";
+import type { RenderLayerProps } from "../image/cutout";
+export interface CircleCutoutProps {
+    /** Unique identifier for this cutout */
+    id: string;
+    /** Normalized 0-1 center coordinate */
+    center: {
+        x: number;
+        y: number;
+    };
+    /** Normalized 0-1 radius as a fraction of min(viewerWidth, viewerHeight) */
+    radius: number;
+    /** Human-readable label */
+    label?: string;
+    /** Override the viewer-level hover effect for this specific cutout */
+    effect?: HoverEffectPreset | HoverEffect;
+    /** Children rendered inside this cutout's context (e.g. `<Overlay>`) */
+    children?: ReactNode;
+    /** Custom renderer for the cutout layer. When provided, replaces the default rendering. */
+    renderLayer?: (props: RenderLayerProps) => ReactNode;
+}
+export declare function CircleCutout({ id, center: defCenter, radius: defRadius, label, effect: effectOverride, children, renderLayer, }: CircleCutoutProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/cutout-viewer/cutouts/circle/circle-hit-test-strategy.d.ts

@@ -0,0 +1,11 @@
+import type { CutoutBounds, HitTestStrategy, CircleCutoutDefinition } from "../../hit-test-strategy";
+export declare class CircleHitTestStrategy implements HitTestStrategy {
+    id: string;
+    bounds: CutoutBounds;
+    private cx;
+    private cy;
+    private rx;
+    private ry;
+    constructor(def: CircleCutoutDefinition, viewportWidth?: number, viewportHeight?: number);
+    hitTest(nx: number, ny: number): boolean;
+}

package/dist/components/cutout-viewer/cutouts/cutout-overlay.d.ts

@@ -12,6 +12,8 @@ export interface CutoutOverlayProps {
     className?: string;
     /** Additional inline styles (merged after placement styles) */
     style?: CSSProperties;
+    /** When true, forces the overlay to be visible regardless of hover or selected state. This overrides the CutoutViewer's `showOverlays` setting if set. */
+    showOverlay?: boolean;
 }
 /**
  * Renders custom UI positioned relative to the parent `<CutoutViewer.Cutout>`'s
@@ -25,4 +27,4 @@ export interface CutoutOverlayProps {
  *   </CutoutViewer.Overlay>
  * </CutoutViewer.Cutout>
  */
-export declare function CutoutOverlay({ placement, children, className, style, }: CutoutOverlayProps): import("react/jsx-runtime").JSX.Element;
+export declare function CutoutOverlay({ placement, children, className, style, showOverlay, }: CutoutOverlayProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/cutout-viewer/cutouts/image/alpha-contour.d.ts

@@ -1,27 +1,29 @@
 /**
- * Contour-tracing utilities for extracting polygon outlines from alpha data.
+ * Contour-tracing utilities for extracting smooth polygon outlines
+ * from alpha data.
  *
- * Used by the trace effect to render image cutouts with the same SVG
- * stroke-dasharray animation that geometric shapes use.
+ * Used by the trace effect to render image cutouts with SVG stroke
+ * animations that closely follow the subject silhouette.
  *
  * Pipeline:
  * 1. Downscale alpha buffer to a working resolution for performance
- * 2. Build binary grid from alpha threshold
- * 3. Trace the outer boundary using Moore-Neighbor contour tracing
- * 4. Simplify with Ramer–Douglas–Peucker
+ * 2. Marching Squares with linear interpolation for sub-pixel contours
+ * 3. Stitch edge segments into closed loops
+ * 4. Simplify with Ramer-Douglas-Peucker
  * 5. Return normalized [0-1] coordinate pairs
  */
+type Point = [number, number];
 /**
- * Extract a simplified polygon contour from a pre-computed alpha buffer.
- *
- * Accepts the alpha data already extracted by the hit-test strategy,
- * avoiding a redundant image load.
+ * Extract a smooth polygon contour from a pre-computed alpha buffer
+ * using Marching Squares with linear interpolation for sub-pixel accuracy.
+ */
+export declare function traceContour(alpha: Uint8Array, srcW: number, srcH: number, alphaThreshold?: number, epsilon?: number): Point[];
+/**
+ * Convert a closed contour to a smooth SVG path using
+ * Catmull-Rom to Cubic Bezier conversion.
  *
- * @param alpha          Compact alpha buffer (one byte per pixel)
- * @param srcW           Source image width in pixels
- * @param srcH           Source image height in pixels
- * @param alphaThreshold Minimum alpha value (0-255) to consider opaque
- * @param epsilon        RDP simplification tolerance in normalized coords
- *                       (default: 0.003 — roughly 0.3 % of image size)
+ * Produces curves that pass through every control point with smooth
+ * tangent continuity, eliminating the angular straight-line look.
  */
-export declare function traceContour(alpha: Uint8Array, srcW: number, srcH: number, alphaThreshold?: number, epsilon?: number): [number, number][];
+export declare function contourToSmoothPath(points: Point[]): string;
+export {};

package/dist/components/cutout-viewer/drawing/draw-circle.d.ts

@@ -0,0 +1,35 @@
+import { type CSSProperties } from "react";
+import { type UseDrawCircleOptions } from "./use-draw-circle";
+export interface DrawCircleProps extends UseDrawCircleOptions {
+    /**
+     * Stroke / accent color used for the in-progress circle visualization.
+     * Accepts any CSS color string.
+     * @default "#3b82f6"
+     */
+    strokeColor?: string;
+    /**
+     * When `false`, the drawing overlay becomes fully transparent to pointer
+     * events and any in-progress drawing is cleared. Useful for toggling draw
+     * mode on/off without unmounting the component.
+     * @default true
+     */
+    enabled?: boolean;
+    /** Additional inline styles applied to the drawing overlay container */
+    style?: CSSProperties;
+    /** Additional class name applied to the drawing overlay container */
+    className?: string;
+}
+/**
+ * Composable sub-component of `<CutoutViewer>` that lets users draw circle
+ * regions directly on the main image via click-and-drag.
+ *
+ * ### Interactions
+ * - **Pointer down** — set the center point
+ * - **Drag** — preview the circle in real time (radius = distance from center)
+ * - **Pointer up** — complete the circle and call `onComplete`
+ * - **Escape** — cancel and reset the in-progress drawing
+ *
+ * All coordinates passed to `onComplete` are normalized (0–1), matching the
+ * convention used by `<CutoutViewer.CircleCutout>`.
+ */
+export declare function DrawCircle({ onComplete, minRadius, strokeColor, enabled, style, className, }: DrawCircleProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/cutout-viewer/drawing/draw-rectangle.d.ts

@@ -0,0 +1,35 @@
+import { type CSSProperties } from "react";
+import { type UseDrawRectangleOptions } from "./use-draw-rectangle";
+export interface DrawRectangleProps extends UseDrawRectangleOptions {
+    /**
+     * Stroke / accent color used for the in-progress rectangle visualization.
+     * Accepts any CSS color string.
+     * @default "#3b82f6"
+     */
+    strokeColor?: string;
+    /**
+     * When `false`, the drawing overlay becomes fully transparent to pointer
+     * events and any in-progress drawing is cleared. Useful for toggling draw
+     * mode on/off without unmounting the component.
+     * @default true
+     */
+    enabled?: boolean;
+    /** Additional inline styles applied to the drawing overlay container */
+    style?: CSSProperties;
+    /** Additional class name applied to the drawing overlay container */
+    className?: string;
+}
+/**
+ * Composable sub-component of `<CutoutViewer>` that lets users draw rectangle
+ * regions directly on the main image via click-and-drag.
+ *
+ * ### Interactions
+ * - **Pointer down** — anchor the first corner
+ * - **Drag** — preview the rectangle in real time
+ * - **Pointer up** — complete the rectangle and call `onComplete`
+ * - **Escape** — cancel and reset the in-progress drawing
+ *
+ * All coordinates passed to `onComplete` are normalized (0–1), matching the
+ * convention used by `<CutoutViewer.BBoxCutout>`.
+ */
+export declare function DrawRectangle({ onComplete, minSize, strokeColor, enabled, style, className, }: DrawRectangleProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/cutout-viewer/drawing/use-draw-circle.d.ts

@@ -0,0 +1,41 @@
+export interface UseDrawCircleOptions {
+    /** Called when the user finishes drawing a circle */
+    onComplete: (circle: {
+        center: {
+            x: number;
+            y: number;
+        };
+        radius: number;
+    }) => void;
+    /** Minimum radius required to complete a circle (default: 0.01) */
+    minRadius?: number;
+}
+export interface UseDrawCircleReturn {
+    /** The in-progress circle, or null when not dragging */
+    circle: {
+        center: {
+            x: number;
+            y: number;
+        };
+        radius: number;
+    } | null;
+    /** Current drawing viewport size in pixels */
+    viewportSize: {
+        width: number;
+        height: number;
+    };
+    /** True while the user is dragging */
+    isDragging: boolean;
+    /** Reset (cancel) the current in-progress drawing */
+    reset: () => void;
+    /** Ref to attach to the drawing container element */
+    containerRef: React.RefObject<HTMLDivElement | null>;
+    /** Event handlers to spread onto the drawing container element */
+    containerProps: {
+        onPointerDown: (e: React.PointerEvent<HTMLDivElement>) => void;
+        onPointerMove: (e: React.PointerEvent<HTMLDivElement>) => void;
+        onPointerUp: (e: React.PointerEvent<HTMLDivElement>) => void;
+        onPointerLeave: () => void;
+    };
+}
+export declare function useDrawCircle({ onComplete, minRadius, }: UseDrawCircleOptions): UseDrawCircleReturn;

package/dist/components/cutout-viewer/drawing/use-draw-rectangle.d.ts

@@ -0,0 +1,34 @@
+export interface UseDrawRectangleOptions {
+    /** Called when the user finishes drawing a rectangle */
+    onComplete: (bounds: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    }) => void;
+    /** Minimum size (width or height) required to complete a rectangle (default: 0.01) */
+    minSize?: number;
+}
+export interface UseDrawRectangleReturn {
+    /** The in-progress rectangle, or null when not dragging */
+    rect: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    } | null;
+    /** True while the user is dragging */
+    isDragging: boolean;
+    /** Reset (cancel) the current in-progress drawing */
+    reset: () => void;
+    /** Ref to attach to the drawing container element */
+    containerRef: React.RefObject<HTMLDivElement | null>;
+    /** Event handlers to spread onto the drawing container element */
+    containerProps: {
+        onPointerDown: (e: React.PointerEvent<HTMLDivElement>) => void;
+        onPointerMove: (e: React.PointerEvent<HTMLDivElement>) => void;
+        onPointerUp: (e: React.PointerEvent<HTMLDivElement>) => void;
+        onPointerLeave: () => void;
+    };
+}
+export declare function useDrawRectangle({ onComplete, minSize, }: UseDrawRectangleOptions): UseDrawRectangleReturn;

package/dist/components/cutout-viewer/hit-test-strategy.d.ts

@@ -36,7 +36,17 @@ export interface PolygonCutoutDefinition extends BaseCutoutDefinition {
     /** Array of [x, y] normalized points forming a closed path */
     points: [number, number][];
 }
-export type CutoutDefinition = ImageCutoutDefinition | BoundingBoxCutoutDefinition | PolygonCutoutDefinition;
+export interface CircleCutoutDefinition extends BaseCutoutDefinition {
+    type: "circle";
+    /** Normalized 0-1 center coordinate */
+    center: {
+        x: number;
+        y: number;
+    };
+    /** Normalized 0-1 radius as a fraction of min(viewerWidth, viewerHeight) */
+    radius: number;
+}
+export type CutoutDefinition = ImageCutoutDefinition | BoundingBoxCutoutDefinition | PolygonCutoutDefinition | CircleCutoutDefinition;
 export interface HitTestStrategy {
     /** Cutout identifier */
     id: string;
@@ -54,4 +64,9 @@ export interface HitTestStrategy {
 export { ImageHitTestStrategy } from "./cutouts/image/image-hit-test-strategy";
 export { RectHitTestStrategy } from "./cutouts/bbox/bbox-hit-test-strategy";
 export { PolygonHitTestStrategy } from "./cutouts/polygon/polygon-hit-test-strategy";
-export declare function createHitTestStrategy(def: CutoutDefinition, alphaThreshold: number): HitTestStrategy;
+export { CircleHitTestStrategy } from "./cutouts/circle/circle-hit-test-strategy";
+export interface HitTestViewportOptions {
+    viewportWidth?: number;
+    viewportHeight?: number;
+}
+export declare function createHitTestStrategy(def: CutoutDefinition, alphaThreshold: number, options?: HitTestViewportOptions): HitTestStrategy;

package/dist/components/cutout-viewer/index.d.ts

@@ -5,14 +5,23 @@ export type { CutoutOverlayProps, Placement } from "./cutouts/cutout-overlay";
 export type { CutoutProps, RenderLayerProps } from "./cutouts/image/cutout";
 export type { BBoxCutoutProps } from "./cutouts/bbox/bbox-cutout";
 export type { PolygonCutoutProps } from "./cutouts/polygon/polygon-cutout";
+export type { CircleCutoutProps } from "./cutouts/circle/circle-cutout";
 export { DrawPolygon } from "./drawing/draw-polygon";
 export type { DrawPolygonProps } from "./drawing/draw-polygon";
+export { DrawRectangle } from "./drawing/draw-rectangle";
+export type { DrawRectangleProps } from "./drawing/draw-rectangle";
+export { DrawCircle } from "./drawing/draw-circle";
+export type { DrawCircleProps } from "./drawing/draw-circle";
 export { useDrawPolygon } from "./drawing/use-draw-polygon";
 export type { UseDrawPolygonOptions, UseDrawPolygonReturn, } from "./drawing/use-draw-polygon";
+export { useDrawRectangle } from "./drawing/use-draw-rectangle";
+export type { UseDrawRectangleOptions, UseDrawRectangleReturn, } from "./drawing/use-draw-rectangle";
+export { useDrawCircle } from "./drawing/use-draw-circle";
+export type { UseDrawCircleOptions, UseDrawCircleReturn, } from "./drawing/use-draw-circle";
 export { useCutout } from "./cutouts/cutout-context";
 export { useCutoutHitTest } from "./use-cutout-hit-test";
 export type { CutoutImage, CutoutBounds } from "./use-cutout-hit-test";
-export type { CutoutDefinition, ImageCutoutDefinition, BoundingBoxCutoutDefinition, PolygonCutoutDefinition, HitTestStrategy, } from "./hit-test-strategy";
-export { ImageHitTestStrategy, RectHitTestStrategy, PolygonHitTestStrategy, createHitTestStrategy, } from "./hit-test-strategy";
+export type { CutoutDefinition, ImageCutoutDefinition, BoundingBoxCutoutDefinition, PolygonCutoutDefinition, CircleCutoutDefinition, HitTestStrategy, } from "./hit-test-strategy";
+export { ImageHitTestStrategy, RectHitTestStrategy, PolygonHitTestStrategy, CircleHitTestStrategy, createHitTestStrategy, } from "./hit-test-strategy";
 export { hoverEffects, elevateEffect, glowEffect, liftEffect, subtleEffect, traceEffect, shimmerEffect, defineKeyframes, } from "./hover-effects";
 export type { HoverEffect, HoverEffectPreset, GeometryStyle, KeyframeAnimation, } from "./hover-effects";

package/dist/components/cutout-viewer/use-cutout-hit-test.d.ts

@@ -1,6 +1,6 @@
 import { type CutoutDefinition, type CutoutBounds } from "./hit-test-strategy";
 export type { CutoutBounds } from "./hit-test-strategy";
-export type { CutoutDefinition, ImageCutoutDefinition, BoundingBoxCutoutDefinition, PolygonCutoutDefinition, HitTestStrategy, } from "./hit-test-strategy";
+export type { CutoutDefinition, ImageCutoutDefinition, BoundingBoxCutoutDefinition, PolygonCutoutDefinition, CircleCutoutDefinition, HitTestStrategy, } from "./hit-test-strategy";
 /** @deprecated Use `ImageCutoutDefinition` instead */
 export interface CutoutImage {
     id: string;
@@ -19,6 +19,10 @@ export declare function useCutoutHitTest(definitions: CutoutDefinition[], enable
     hoveredId: string | null;
     selectedId: string | null;
     activeId: string | null;
+    viewportSize: {
+        width: number;
+        height: number;
+    };
     boundsMap: Record<string, CutoutBounds>;
     contourMap: Record<string, [number, number][]>;
     containerRef: import("react").RefObject<HTMLDivElement | null>;

package/dist/components/cutout-viewer/viewer-context.d.ts

@@ -9,9 +9,14 @@ export interface CutoutViewerContextValue {
     activeId: string | null;
     selectedId: string | null;
     hoveredId: string | null;
+    viewportSize: {
+        width: number;
+        height: number;
+    };
     effect: HoverEffect;
     enabled: boolean;
     showAll: boolean;
+    showOverlays: boolean;
     boundsMap: Record<string, CutoutBounds>;
     contourMap: Record<string, [number, number][]>;
     isAnyActive: boolean;