@olenbetong/synergi-react 2.3.8 → 2.4.0

package/src/components/ImageEditor/plugins/zoomPlugin/ZoomCanvas.tsx

@@ -0,0 +1,123 @@
+import { type ReactNode, useEffect, useRef } from "react";
+import { ZOOM_STEP } from "./useZoomPan.js";
+import { useZoom } from "./ZoomContext.js";
+
+interface Props {
+	children: ReactNode;
+	/**
+	 * Whether single-pointer drag pans the canvas. Pass false in tool mode so
+	 * 1-finger events are owned by the tool; 2-finger pinch/drag still works.
+	 * Defaults to true.
+	 */
+	panEnabled?: boolean;
+}
+
+/**
+ * Fills the canvas area, applies zoom/pan transform to its children, and
+ * captures pointer events for gestures.
+ *
+ * • Ctrl/Cmd + scroll: zoom anchored at cursor (desktop)
+ * • 2-finger pinch + translate: simultaneous zoom + pan anchored at midpoint
+ * • 1-finger drag (when panEnabled): pan
+ */
+export function ZoomCanvas({ children, panEnabled = true }: Props) {
+	let { zoom, panX, panY, pan, panAndZoomAtPoint, zoomByDeltaAtPoint } = useZoom();
+
+	let containerRef = useRef<HTMLDivElement>(null);
+	let pointers = useRef(new Map<number, { x: number; y: number }>());
+	let lastPinchDist = useRef<number | null>(null);
+	let lastPinchMid = useRef<{ x: number; y: number } | null>(null);
+
+	// Stable refs so the DOM wheel listener never needs re-registration.
+	let panRef = useRef(pan);
+	let panAndZoomAtPointRef = useRef(panAndZoomAtPoint);
+	let zoomByDeltaAtPointRef = useRef(zoomByDeltaAtPoint);
+	panRef.current = pan;
+	panAndZoomAtPointRef.current = panAndZoomAtPoint;
+	zoomByDeltaAtPointRef.current = zoomByDeltaAtPoint;
+
+	function focalFromClient(clientX: number, clientY: number) {
+		let rect = containerRef.current?.getBoundingClientRect();
+		if (!rect) return { fx: 0, fy: 0 };
+		return { fx: clientX - rect.left - rect.width / 2, fy: clientY - rect.top - rect.height / 2 };
+	}
+
+	useEffect(() => {
+		let el = containerRef.current;
+		if (!el) return;
+
+		function onWheel(e: WheelEvent) {
+			if (!e.ctrlKey && !e.metaKey) return;
+			e.preventDefault();
+			let { fx, fy } = focalFromClient(e.clientX, e.clientY);
+			zoomByDeltaAtPointRef.current(e.deltaY < 0 ? ZOOM_STEP : -ZOOM_STEP, fx, fy);
+		}
+
+		el.addEventListener("wheel", onWheel, { passive: false });
+		return () => el.removeEventListener("wheel", onWheel);
+	}, []);
+
+	function onPointerDown(e: React.PointerEvent) {
+		// Only capture the pointer for panning. In tool mode (panEnabled=false) the inner
+		// tool elements (DragHandle, redact SVG) call setPointerCapture themselves after
+		// this event bubbles up — don't override their capture.
+		if (panEnabled) {
+			e.currentTarget.setPointerCapture(e.pointerId);
+		}
+		pointers.current.set(e.pointerId, { x: e.clientX, y: e.clientY });
+		lastPinchDist.current = null;
+		lastPinchMid.current = null;
+	}
+
+	function onPointerMove(e: React.PointerEvent) {
+		// Ignore hover — only process pointers that went through onPointerDown.
+		if (!pointers.current.has(e.pointerId)) return;
+
+		let prev = pointers.current.get(e.pointerId);
+		pointers.current.set(e.pointerId, { x: e.clientX, y: e.clientY });
+
+		if (pointers.current.size === 2) {
+			let [a, b] = [...pointers.current.values()];
+			let dist = Math.hypot(a.x - b.x, a.y - b.y);
+			let midX = (a.x + b.x) / 2;
+			let midY = (a.y + b.y) / 2;
+
+			if (lastPinchDist.current !== null && lastPinchDist.current > 0) {
+				let { fx, fy } = focalFromClient(midX, midY);
+				let scaleFactor = dist / lastPinchDist.current;
+				// Translate from midpoint movement + zoom from pinch — both in one state update.
+				let dx = lastPinchMid.current ? midX - lastPinchMid.current.x : 0;
+				let dy = lastPinchMid.current ? midY - lastPinchMid.current.y : 0;
+				panAndZoomAtPointRef.current(dx, dy, scaleFactor, fx, fy);
+			}
+
+			lastPinchDist.current = dist;
+			lastPinchMid.current = { x: midX, y: midY };
+		} else if (pointers.current.size === 1 && prev && panEnabled) {
+			panRef.current(e.clientX - prev.x, e.clientY - prev.y);
+		}
+	}
+
+	function onPointerUp(e: React.PointerEvent) {
+		pointers.current.delete(e.pointerId);
+		if (pointers.current.size < 2) {
+			lastPinchDist.current = null;
+			lastPinchMid.current = null;
+		}
+	}
+
+	return (
+		<div
+			ref={containerRef}
+			className="zoom-canvas-root"
+			onPointerDown={onPointerDown}
+			onPointerMove={onPointerMove}
+			onPointerUp={onPointerUp}
+			onPointerCancel={onPointerUp}
+		>
+			<div className="zoom-canvas-inner" style={{ transform: `translate(${panX}px, ${panY}px) scale(${zoom})` }}>
+				{children}
+			</div>
+		</div>
+	);
+}

package/src/components/ImageEditor/plugins/zoomPlugin/ZoomContext.tsx

@@ -0,0 +1,15 @@
+import { createContext, type ReactNode, use } from "react";
+import { useZoomPan, type ZoomPanResult } from "./useZoomPan.js";
+
+let ZoomContext = createContext<ZoomPanResult | null>(null);
+
+export function useZoom(): ZoomPanResult {
+	let ctx = use(ZoomContext);
+	if (!ctx) throw new Error("useZoom must be used within ZoomProvider");
+	return ctx;
+}
+
+export function ZoomProvider({ children }: { children: ReactNode }) {
+	let state = useZoomPan();
+	return <ZoomContext value={state}>{children}</ZoomContext>;
+}

package/src/components/ImageEditor/plugins/zoomPlugin/ZoomControls.tsx

@@ -0,0 +1,43 @@
+import ZoomInIcon from "@mui/icons-material/ZoomIn";
+import ZoomInMapIcon from "@mui/icons-material/ZoomInMap";
+import ZoomOutIcon from "@mui/icons-material/ZoomOut";
+import { getLocalizedString } from "@olenbetong/appframe-core";
+import { ResponsiveButton } from "../../ResponsiveButton.js";
+import { useZoom } from "./ZoomContext.js";
+
+interface Props {
+	disabled?: boolean;
+	isSmall?: boolean;
+}
+
+export function ZoomControls({ disabled, isSmall = false }: Props) {
+	let { zoom, zoomIn, zoomOut, resetZoom, canZoomIn, canZoomOut, isZoomed } = useZoom();
+
+	return (
+		<>
+			<ResponsiveButton
+				icon={<ZoomOutIcon />}
+				label={getLocalizedString("Zoom out")}
+				onClick={zoomOut}
+				disabled={disabled || !canZoomOut}
+				isSmall={isSmall}
+			/>
+			<span className="image-editor__zoom-level">{Math.round(zoom * 100)}%</span>
+			<ResponsiveButton
+				icon={<ZoomInIcon />}
+				label={getLocalizedString("Zoom in")}
+				onClick={zoomIn}
+				disabled={disabled || !canZoomIn}
+				isSmall={isSmall}
+			/>
+			{isZoomed && (
+				<ResponsiveButton
+					icon={<ZoomInMapIcon />}
+					label={getLocalizedString("Reset zoom")}
+					onClick={resetZoom}
+					isSmall={isSmall}
+				/>
+			)}
+		</>
+	);
+}

package/src/components/ImageEditor/plugins/zoomPlugin/index.ts

@@ -0,0 +1,12 @@
+import type { ViewPlugin } from "../../types.js";
+import { ZoomCanvas } from "./ZoomCanvas.js";
+import { ZoomProvider } from "./ZoomContext.js";
+import { ZoomControls } from "./ZoomControls.js";
+
+export const zoomPlugin: ViewPlugin = {
+	type: "view",
+	id: "zoom",
+	Provider: ZoomProvider,
+	CanvasWrapper: ZoomCanvas,
+	TopBarControls: ZoomControls,
+};

package/src/components/ImageEditor/plugins/zoomPlugin/useZoomPan.ts

@@ -0,0 +1,126 @@
+import { useCallback, useState } from "react";
+
+export const MIN_ZOOM = 0.5;
+export const MAX_ZOOM = 5;
+export const ZOOM_STEP = 0.25;
+
+interface State {
+	zoom: number;
+	panX: number;
+	panY: number;
+}
+
+export interface ZoomPanResult {
+	zoom: number;
+	panX: number;
+	panY: number;
+	canZoomIn: boolean;
+	canZoomOut: boolean;
+	isZoomed: boolean;
+	zoomIn: () => void;
+	zoomOut: () => void;
+	resetZoom: () => void;
+	/** Translate by (dx, dy) screen pixels. */
+	pan: (dx: number, dy: number) => void;
+	/**
+	 * Zoom by a multiplicative scale factor, anchored at a focal point.
+	 * focalX/focalY are in px relative to the container centre.
+	 */
+	zoomByScaleAtPoint: (scaleFactor: number, focalX: number, focalY: number) => void;
+	/**
+	 * Zoom by an additive step delta, anchored at a focal point.
+	 * focalX/focalY are in px relative to the container centre.
+	 */
+	zoomByDeltaAtPoint: (delta: number, focalX: number, focalY: number) => void;
+	/**
+	 * Simultaneously pan by (dx, dy) and zoom by a multiplicative scale factor,
+	 * anchored at a focal point. Used for 2-finger gestures where the midpoint
+	 * may translate while the fingers pinch.
+	 */
+	panAndZoomAtPoint: (dx: number, dy: number, scaleFactor: number, focalX: number, focalY: number) => void;
+}
+
+export function useZoomPan(): ZoomPanResult {
+	let [{ zoom, panX, panY }, setState] = useState<State>({ zoom: 1, panX: 0, panY: 0 });
+
+	let zoomIn = useCallback(() => {
+		// Zoom from centre (focalX = 0, focalY = 0)
+		setState((s) => {
+			let newZoom = +Math.min(MAX_ZOOM, s.zoom + ZOOM_STEP).toFixed(2);
+			let scale = newZoom / s.zoom;
+			return { zoom: newZoom, panX: s.panX * scale, panY: s.panY * scale };
+		});
+	}, []);
+
+	let zoomOut = useCallback(() => {
+		setState((s) => {
+			let newZoom = +Math.max(MIN_ZOOM, s.zoom - ZOOM_STEP).toFixed(2);
+			let scale = newZoom / s.zoom;
+			return { zoom: newZoom, panX: s.panX * scale, panY: s.panY * scale };
+		});
+	}, []);
+
+	let resetZoom = useCallback(() => {
+		setState({ zoom: 1, panX: 0, panY: 0 });
+	}, []);
+
+	let pan = useCallback((dx: number, dy: number) => {
+		setState((s) => ({ ...s, panX: s.panX + dx, panY: s.panY + dy }));
+	}, []);
+
+	let zoomByScaleAtPoint = useCallback((scaleFactor: number, focalX: number, focalY: number) => {
+		setState((s) => {
+			let newZoom = +Math.min(MAX_ZOOM, Math.max(MIN_ZOOM, s.zoom * scaleFactor)).toFixed(3);
+			let realScale = newZoom / s.zoom;
+			return {
+				zoom: newZoom,
+				// Keep the focal point fixed on screen: pan adjusts to compensate for the zoom shift.
+				panX: focalX * (1 - realScale) + s.panX * realScale,
+				panY: focalY * (1 - realScale) + s.panY * realScale,
+			};
+		});
+	}, []);
+
+	let zoomByDeltaAtPoint = useCallback((delta: number, focalX: number, focalY: number) => {
+		setState((s) => {
+			let newZoom = +Math.min(MAX_ZOOM, Math.max(MIN_ZOOM, s.zoom + delta)).toFixed(2);
+			let scale = newZoom / s.zoom;
+			return {
+				zoom: newZoom,
+				panX: focalX * (1 - scale) + s.panX * scale,
+				panY: focalY * (1 - scale) + s.panY * scale,
+			};
+		});
+	}, []);
+
+	let panAndZoomAtPoint = useCallback((dx: number, dy: number, scaleFactor: number, focalX: number, focalY: number) => {
+		setState((s) => {
+			let newZoom = +Math.min(MAX_ZOOM, Math.max(MIN_ZOOM, s.zoom * scaleFactor)).toFixed(3);
+			let realScale = newZoom / s.zoom;
+			// Apply pan first, then zoom around the focal point.
+			let panXAfterPan = s.panX + dx;
+			let panYAfterPan = s.panY + dy;
+			return {
+				zoom: newZoom,
+				panX: focalX * (1 - realScale) + panXAfterPan * realScale,
+				panY: focalY * (1 - realScale) + panYAfterPan * realScale,
+			};
+		});
+	}, []);
+
+	return {
+		zoom,
+		panX,
+		panY,
+		canZoomIn: zoom < MAX_ZOOM,
+		canZoomOut: zoom > MIN_ZOOM,
+		isZoomed: zoom !== 1 || panX !== 0 || panY !== 0,
+		zoomIn,
+		zoomOut,
+		resetZoom,
+		pan,
+		zoomByScaleAtPoint,
+		zoomByDeltaAtPoint,
+		panAndZoomAtPoint,
+	};
+}

package/src/components/ImageEditor/types.ts

@@ -0,0 +1,69 @@
+import type { ComponentType, ReactNode } from "react";
+
+/** A single atomic edit operation, recorded for undo/redo replay. */
+export interface EditAction {
+	type: string;
+	params: Record<string, unknown>;
+}
+
+/**
+ * Registers a replay handler for a specific action type.
+ * Must be a pure async function — no React hooks, no side-effect state.
+ */
+export interface ActionHandler {
+	type: string;
+	apply: (imageUrl: string, params: Record<string, unknown>) => Promise<Blob>;
+}
+
+/** Maps action type → replay function. Built by ImageEditor from the plugins array. */
+export type ActionRegistry = Map<string, ActionHandler["apply"]>;
+
+export interface ToolProviderProps {
+	imageUrl: string;
+	/** Called when the tool has produced a transformed image. */
+	onApply: (blob: Blob, actions: EditAction[]) => void;
+	onCancel: () => void;
+	children: ReactNode;
+}
+
+/**
+ * A mode tool: activates a persistent editing state with its own canvas overlay and toolbar.
+ * The Provider shares state between Overlay and Toolbar via React context.
+ * `actions` registers replay handlers so the history can reconstruct any past state.
+ */
+export interface ToolPlugin {
+	type: "tool";
+	id: string;
+	label: string;
+	Icon: ComponentType;
+	Provider: ComponentType<ToolProviderProps>;
+	Overlay: ComponentType;
+	Toolbar: ComponentType;
+	/** Replay handlers for every action type this tool can produce. */
+	actions: ActionHandler[];
+}
+
+/** An action tool: executes a transform immediately without entering a persistent mode. */
+export interface ActionPlugin {
+	type: "action";
+	id: string;
+	label: string;
+	Icon: ComponentType;
+	execute: (imageUrl: string) => Promise<Blob>;
+}
+
+export type Plugin = ToolPlugin | ActionPlugin;
+
+/**
+ * A view plugin: provides zoom/pan or other viewport transforms without modifying the image.
+ * Wraps the main image area with gesture handling and contributes controls to the top toolbar.
+ */
+export interface ViewPlugin {
+	type: "view";
+	id: string;
+	Provider: ComponentType<{ children: ReactNode }>;
+	/** Wraps the main image; applies transforms and captures pinch/pan gestures. */
+	CanvasWrapper: ComponentType<{ children: ReactNode; panEnabled?: boolean }>;
+	/** Controls rendered in the top toolbar (e.g. zoom in/out/reset). */
+	TopBarControls: ComponentType<{ disabled?: boolean; isSmall?: boolean }>;
+}

package/src/components/ImageEditor/useActiveTool.ts

@@ -0,0 +1,21 @@
+import { useState } from "react";
+
+import type { Plugin, ToolPlugin } from "./types.js";
+
+interface UseActiveToolResult {
+	activePlugin: ToolPlugin | null;
+	activateTool: (id: string) => void;
+	deactivateTool: () => void;
+}
+
+/** Manages which tool plugin is currently active. */
+export function useActiveTool(plugins: Plugin[]): UseActiveToolResult {
+	let [activeId, setActiveId] = useState<string | null>(null);
+	let activePlugin = (plugins.find((p) => p.type === "tool" && p.id === activeId) ?? null) as ToolPlugin | null;
+
+	return {
+		activePlugin,
+		activateTool: setActiveId,
+		deactivateTool: () => setActiveId(null),
+	};
+}

package/src/components/ImageEditor/useEdgeDetection.ts

@@ -0,0 +1,167 @@
+import { useEffect, useState } from "react";
+
+export interface Point {
+	x: number;
+	y: number;
+}
+
+/** TL, TR, BR, BL */
+export type Quad = [Point, Point, Point, Point];
+
+export function fullImageQuad(width: number, height: number): Quad {
+	return [
+		{ x: 0, y: 0 },
+		{ x: width, y: 0 },
+		{ x: width, y: height },
+		{ x: 0, y: height },
+	];
+}
+
+interface FindQuadResult {
+	quad: Quad | null;
+	/** Canvas containing the Canny edge image (with detected quad overlay) for debugging */
+	debugCanvas: HTMLCanvasElement;
+}
+
+function findLargestQuad(cv: any, src: any, minAreaFraction = 0.1): FindQuadResult {
+	let gray = new cv.Mat();
+	let blurred = new cv.Mat();
+	let edges = new cv.Mat();
+	let dilated = new cv.Mat();
+	let contours = new cv.MatVector();
+	let hierarchy = new cv.Mat();
+
+	try {
+		cv.cvtColor(src, gray, cv.COLOR_RGBA2GRAY);
+		cv.GaussianBlur(gray, blurred, new cv.Size(5, 5), 0);
+		// Lower thresholds catch document-background boundaries even in low-contrast images
+		cv.Canny(blurred, edges, 40, 120);
+
+		// Dilate to close small gaps along document edges
+		let kernel = cv.getStructuringElement(cv.MORPH_RECT, new cv.Size(3, 3));
+		cv.dilate(edges, dilated, kernel);
+		kernel.delete();
+
+		// Build RGBA debug canvas so we can draw a coloured quad overlay
+		let debugRgba = new cv.Mat();
+		cv.cvtColor(dilated, debugRgba, cv.COLOR_GRAY2RGBA);
+
+		cv.findContours(dilated, contours, hierarchy, cv.RETR_LIST, cv.CHAIN_APPROX_SIMPLE);
+
+		let best: unknown = null;
+		let bestArea = 0;
+		let minArea = src.cols * src.rows * minAreaFraction;
+
+		for (let i = 0; i < contours.size(); i++) {
+			let contour = contours.get(i);
+			let peri = cv.arcLength(contour, true);
+			let approx = new cv.Mat();
+			// Larger epsilon is more aggressive — helps when the outline isn't perfectly straight
+			cv.approxPolyDP(contour, approx, 0.04 * peri, true);
+
+			if (approx.rows === 4) {
+				let area = cv.contourArea(approx);
+				if (area > bestArea && area > minArea) {
+					bestArea = area;
+					(best as any)?.delete();
+					best = approx;
+				} else {
+					approx.delete();
+				}
+			} else {
+				approx.delete();
+			}
+			contour.delete();
+		}
+
+		let quad: Quad | null = null;
+		if (best) {
+			let mat = best as any;
+			let pts: Point[] = [];
+			for (let i = 0; i < 4; i++) {
+				pts.push({ x: mat.data32S[i * 2], y: mat.data32S[i * 2 + 1] });
+			}
+			mat.delete();
+
+			// Sort into TL, TR, BR, BL
+			pts.sort((a, b) => a.x + a.y - (b.x + b.y));
+			let tl = pts[0];
+			let br = pts[3];
+			let remaining = [pts[1], pts[2]];
+			let tr = remaining[0].x > remaining[1].x ? remaining[0] : remaining[1];
+			let bl = remaining[0].x < remaining[1].x ? remaining[0] : remaining[1];
+			quad = [tl, tr, br, bl];
+
+			// Draw the detected quad on the debug canvas in green
+			let green = new cv.Scalar(0, 255, 0, 255);
+			let ordered = [tl, tr, br, bl];
+			for (let i = 0; i < 4; i++) {
+				let a = ordered[i];
+				let b = ordered[(i + 1) % 4];
+				cv.line(debugRgba, new cv.Point(a.x, a.y), new cv.Point(b.x, b.y), green, 3);
+			}
+			for (let pt of ordered) {
+				cv.circle(debugRgba, new cv.Point(pt.x, pt.y), 8, green, -1);
+			}
+		}
+
+		let debugCanvas = document.createElement("canvas");
+		cv.imshow(debugCanvas, debugRgba);
+		debugRgba.delete();
+
+		return { quad, debugCanvas };
+	} finally {
+		gray.delete();
+		blurred.delete();
+		edges.delete();
+		dilated.delete();
+		contours.delete();
+		hierarchy.delete();
+	}
+}
+
+interface UseEdgeDetectionResult {
+	corners: Quad | null;
+	/** Data URL of the Canny edge image, for debug visualisation */
+	debugImageUrl: string | null;
+}
+
+/**
+ * Runs Canny edge detection on the image to suggest document corners.
+ * Falls back to full-image corners if no quadrilateral is found.
+ */
+export function useEdgeDetection(cv: any, canvas: HTMLCanvasElement | null, enabled: boolean): UseEdgeDetectionResult {
+	let [corners, setCorners] = useState<Quad | null>(null);
+	let [debugImageUrl, setDebugImageUrl] = useState<string | null>(null);
+
+	useEffect(() => {
+		console.log(
+			"[useEdgeDetection] effect: enabled=",
+			enabled,
+			"cv=",
+			typeof cv,
+			"canvas=",
+			canvas?.width,
+			"x",
+			canvas?.height,
+		);
+		if (!enabled || !cv || !canvas) return;
+
+		try {
+			console.log("[useEdgeDetection] running findLargestQuad...");
+			let src = cv.imread(canvas);
+			let { quad, debugCanvas } = findLargestQuad(cv, src);
+			src.delete();
+			console.log("[useEdgeDetection] quad=", quad);
+			setDebugImageUrl(debugCanvas.toDataURL());
+			setCorners(quad ?? fullImageQuad(canvas.width, canvas.height));
+		} catch (err) {
+			console.error("[useEdgeDetection] error:", err);
+			if (canvas) {
+				setCorners(fullImageQuad(canvas.width, canvas.height));
+			}
+		}
+	}, [cv, canvas, enabled]);
+
+	return { corners, debugImageUrl };
+}

package/src/components/ImageEditor/useImageEditor.ts

@@ -0,0 +1,39 @@
+import { useEffect, useRef, useState } from "react";
+
+interface UseImageEditorResult {
+	currentImageUrl: string;
+	currentBlob: Blob | null;
+	applyImage: (blob: Blob) => string;
+	reset: () => void;
+}
+
+/**
+ * Manages the image history for the editor.
+ * Tracks the current image URL/blob and cleans up generated object URLs on unmount.
+ */
+export function useImageEditor(initialImageUrl: string): UseImageEditorResult {
+	let [currentImageUrl, setCurrentImageUrl] = useState(initialImageUrl);
+	let [currentBlob, setCurrentBlob] = useState<Blob | null>(null);
+	let generatedUrls = useRef<string[]>([]);
+
+	useEffect(() => {
+		return () => {
+			for (let url of generatedUrls.current) URL.revokeObjectURL(url);
+		};
+	}, []);
+
+	function applyImage(blob: Blob): string {
+		let nextUrl = URL.createObjectURL(blob);
+		generatedUrls.current = [...generatedUrls.current, nextUrl];
+		setCurrentImageUrl(nextUrl);
+		setCurrentBlob(blob);
+		return nextUrl;
+	}
+
+	function reset() {
+		setCurrentImageUrl(initialImageUrl);
+		setCurrentBlob(null);
+	}
+
+	return { currentImageUrl, currentBlob, applyImage, reset };
+}