@olenbetong/synergi-react 2.3.8 → 2.4.0

package/src/components/ImageEditor/ImageEditor.tsx

@@ -0,0 +1,310 @@
+import ArrowBackIcon from "@mui/icons-material/ArrowBack";
+import CheckIcon from "@mui/icons-material/Check";
+import RedoIcon from "@mui/icons-material/Redo";
+import RestartAltIcon from "@mui/icons-material/RestartAlt";
+import UndoIcon from "@mui/icons-material/Undo";
+import { Button, CircularProgress, Fab, IconButton, Tooltip, useMediaQuery } from "@mui/material";
+import { getLocalizedString } from "@olenbetong/appframe-core";
+import { forwardRef, useImperativeHandle, useMemo, useState } from "react";
+
+import "./ImageEditor.css";
+import { ResponsiveButton } from "./ResponsiveButton.js";
+import type { ActionPlugin, ActionRegistry, EditAction, Plugin, ToolPlugin, ViewPlugin } from "./types.js";
+import { useActiveTool } from "./useActiveTool.js";
+import { useImageHistory } from "./useImageHistory.js";
+
+export type ImageEditorRef = {
+	/** Returns the current edited blob, or null if no edits have been applied since the last source image. */
+	getCurrentBlob: () => Blob | null;
+};
+
+interface Props {
+	imageUrl: string;
+	/** Called when the user clicks the Done button. When omitted, the Done button is not shown. */
+	onConfirm?: (blob: Blob) => void;
+	/** Called when the user wants to exit without saving. Shows a back button in the top bar. */
+	onCancel?: () => void;
+	plugins: Plugin[];
+	/** Optional view plugin (e.g. zoom/pan) that wraps the canvas and contributes top-bar controls. */
+	viewPlugin?: ViewPlugin;
+}
+
+/**
+ * Full-screen image editor shell.
+ * Does not know about specific tools — behaviour is entirely driven by the `plugins` prop.
+ * Tool plugins contribute an overlay and toolbar; action plugins execute immediately.
+ * Supports undo/redo: each applied transformation is recorded with its EditAction list.
+ */
+export const ImageEditor = forwardRef<ImageEditorRef, Props>(function ImageEditor(
+	{ imageUrl, onConfirm, onCancel, plugins, viewPlugin }: Props,
+	ref,
+) {
+	let registry = useMemo(() => buildActionRegistry(plugins), [plugins]);
+	let history = useImageHistory(imageUrl, registry);
+	let { activePlugin, activateTool, deactivateTool } = useActiveTool(plugins);
+	let [busy, setBusy] = useState(false);
+	let disabled = busy || history.replaying;
+	let isSmall = useMediaQuery("(max-width: 600px)");
+
+	useImperativeHandle(ref, () => ({
+		getCurrentBlob: () => history.currentBlob,
+	}));
+
+	async function executeAction(plugin: ActionPlugin) {
+		setBusy(true);
+		try {
+			let blob = await plugin.execute(history.currentImageUrl);
+			let actions: EditAction[] = [{ type: plugin.id, params: {} }];
+			history.applyActions(blob, actions);
+		} finally {
+			setBusy(false);
+		}
+	}
+
+	function handleToolApply(blob: Blob, actions: EditAction[]) {
+		history.applyActions(blob, actions);
+		deactivateTool();
+	}
+
+	function confirm() {
+		if (!onConfirm) return;
+		if (history.currentBlob) {
+			onConfirm(history.currentBlob);
+			return;
+		}
+		fetch(history.currentImageUrl)
+			.then((r) => r.blob())
+			.then(onConfirm);
+	}
+
+	let CanvasWrapper = viewPlugin?.CanvasWrapper;
+	let TopBarControls = viewPlugin?.TopBarControls;
+
+	let inner = (
+		<div className="image-editor">
+			{/* Top toolbar — always visible; undo/redo/reset disabled while a tool is active */}
+			<div className="image-editor__topbar">
+				<div className="image-editor__toolbar-group">
+					{onCancel && (
+						<>
+							<ResponsiveButton
+								icon={<ArrowBackIcon />}
+								label={getLocalizedString("Back")}
+								onClick={onCancel}
+								isSmall={isSmall}
+							/>
+							<span className="image-editor__topbar-divider" aria-hidden />
+						</>
+					)}
+					<ResponsiveButton
+						icon={<UndoIcon />}
+						label={getLocalizedString("Undo")}
+						onClick={history.undo}
+						disabled={disabled || !history.canUndo || !!activePlugin}
+						isSmall={isSmall}
+					/>
+					<ResponsiveButton
+						icon={<RedoIcon />}
+						label={getLocalizedString("Redo")}
+						onClick={history.redo}
+						disabled={disabled || !history.canRedo || !!activePlugin}
+						isSmall={isSmall}
+					/>
+					<ResponsiveButton
+						icon={<RestartAltIcon />}
+						label={getLocalizedString("Reset")}
+						onClick={history.reset}
+						disabled={disabled || !history.canUndo || !!activePlugin}
+						isSmall={isSmall}
+					/>
+				</div>
+
+				{TopBarControls && (
+					<div className="image-editor__toolbar-group">
+						<TopBarControls disabled={disabled} isSmall={isSmall} />
+					</div>
+				)}
+			</div>
+
+			{/* Canvas area */}
+			<div className="image-editor__canvas">
+				{CanvasWrapper ? (
+					<CanvasWrapper panEnabled={!activePlugin}>
+						{activePlugin ? (
+							<ActiveOverlay plugin={activePlugin} />
+						) : (
+							<img
+								src={history.currentImageUrl}
+								alt={getLocalizedString("Image to edit")}
+								className="image-editor__img"
+							/>
+						)}
+					</CanvasWrapper>
+				) : activePlugin ? (
+					<ActiveOverlay plugin={activePlugin} />
+				) : (
+					<img src={history.currentImageUrl} alt={getLocalizedString("Image to edit")} className="image-editor__img" />
+				)}
+
+				{/* Done button floats over the canvas, bottom-right — hidden when a tool is active or no onConfirm */}
+				{!activePlugin && onConfirm && (
+					<Fab
+						color="primary"
+						variant={isSmall ? "circular" : "extended"}
+						onClick={confirm}
+						disabled={disabled}
+						sx={{ position: "absolute", bottom: "1rem", right: "1rem", zIndex: 5 }}
+					>
+						<CheckIcon sx={isSmall ? undefined : { mr: 1 }} />
+						{!isSmall && getLocalizedString("Done")}
+					</Fab>
+				)}
+
+				{/* Replay overlay covers the canvas and sits above the Done button */}
+				{history.replaying && (
+					<div className="image-editor__replay-overlay">
+						<CircularProgress color="inherit" />
+					</div>
+				)}
+			</div>
+
+			{/* Bottom toolbar — tool/action plugin buttons */}
+			<div className="image-editor__toolbar">
+				{activePlugin ? (
+					<ActiveToolbar plugin={activePlugin} />
+				) : (
+					<div className="image-editor__toolbar-group">
+						{plugins.map((p) =>
+							p.type === "tool" ? (
+								<ToolButton
+									key={p.id}
+									plugin={p}
+									busy={disabled}
+									onActivate={() => activateTool(p.id)}
+									isSmall={isSmall}
+								/>
+							) : (
+								<ActionButton
+									key={p.id}
+									plugin={p}
+									busy={disabled}
+									onExecute={() => executeAction(p)}
+									isSmall={isSmall}
+								/>
+							),
+						)}
+					</div>
+				)}
+			</div>
+		</div>
+	);
+
+	// Wrap with the active tool's provider so Overlay and Toolbar share context.
+	if (activePlugin) {
+		let ActiveProvider = activePlugin.Provider;
+		inner = (
+			<ActiveProvider imageUrl={history.currentImageUrl} onApply={handleToolApply} onCancel={deactivateTool}>
+				{inner}
+			</ActiveProvider>
+		);
+	}
+
+	// Wrap with the view plugin's provider (outermost) so both CanvasWrapper and TopBarControls share state.
+	if (viewPlugin) {
+		let ViewProvider = viewPlugin.Provider;
+		return <ViewProvider>{inner}</ViewProvider>;
+	}
+
+	return inner;
+});
+
+function ToolButton({
+	plugin,
+	busy,
+	onActivate,
+	isSmall,
+}: {
+	plugin: ToolPlugin;
+	busy: boolean;
+	onActivate: () => void;
+	isSmall: boolean;
+}) {
+	let Icon = plugin.Icon;
+	if (isSmall) {
+		return (
+			<Tooltip title={getLocalizedString(plugin.label)}>
+				<span>
+					<IconButton onClick={onActivate} disabled={busy} color="inherit">
+						<Icon />
+					</IconButton>
+				</span>
+			</Tooltip>
+		);
+	}
+	return (
+		<Button startIcon={<Icon />} onClick={onActivate} disabled={busy} variant="outlined" color="inherit">
+			{getLocalizedString(plugin.label)}
+		</Button>
+	);
+}
+
+function ActionButton({
+	plugin,
+	busy,
+	onExecute,
+	isSmall,
+}: {
+	plugin: ActionPlugin;
+	busy: boolean;
+	onExecute: () => void;
+	isSmall: boolean;
+}) {
+	let Icon = plugin.Icon;
+	if (isSmall) {
+		return (
+			<Tooltip title={getLocalizedString(plugin.label)}>
+				<span>
+					<IconButton onClick={onExecute} disabled={busy} color="inherit">
+						{busy ? <CircularProgress size={18} color="inherit" /> : <Icon />}
+					</IconButton>
+				</span>
+			</Tooltip>
+		);
+	}
+	return (
+		<Button
+			startIcon={busy ? <CircularProgress size={18} color="inherit" /> : <Icon />}
+			onClick={onExecute}
+			disabled={busy}
+			color="inherit"
+		>
+			{getLocalizedString(plugin.label)}
+		</Button>
+	);
+}
+
+function ActiveOverlay({ plugin }: { plugin: ToolPlugin }) {
+	let Overlay = plugin.Overlay;
+	return <Overlay />;
+}
+
+function ActiveToolbar({ plugin }: { plugin: ToolPlugin }) {
+	let Toolbar = plugin.Toolbar;
+	return <Toolbar />;
+}
+
+/** Builds the action registry from all registered plugins. */
+function buildActionRegistry(plugins: Plugin[]): ActionRegistry {
+	let registry: ActionRegistry = new Map();
+	for (let plugin of plugins) {
+		if (plugin.type === "action") {
+			// Action plugins have no params — their execute function IS the replay handler.
+			registry.set(plugin.id, (imageUrl, _params) => plugin.execute(imageUrl));
+		} else {
+			for (let action of plugin.actions) {
+				registry.set(action.type, action.apply);
+			}
+		}
+	}
+	return registry;
+}

package/src/components/ImageEditor/ResponsiveButton.tsx

@@ -0,0 +1,32 @@
+import { Button, IconButton, Tooltip } from "@mui/material";
+import type { ReactNode } from "react";
+
+interface Props {
+	icon: ReactNode;
+	label: string;
+	onClick: () => void;
+	disabled?: boolean;
+	isSmall: boolean;
+}
+
+/** Renders a labelled Button on large screens and a Tooltip-wrapped IconButton on small ones. */
+export function ResponsiveButton({ icon, label, onClick, disabled, isSmall }: Props) {
+	if (isSmall) {
+		return (
+			<Tooltip title={label}>
+				{/* span needed so Tooltip can attach to a disabled button */}
+				<span>
+					<IconButton onClick={onClick} disabled={disabled} color="inherit" size="small">
+						{icon}
+					</IconButton>
+				</span>
+			</Tooltip>
+		);
+	}
+
+	return (
+		<Button startIcon={icon} onClick={onClick} color="inherit" disabled={disabled}>
+			{label}
+		</Button>
+	);
+}

package/src/components/ImageEditor/defaultPlugins.ts

@@ -0,0 +1,10 @@
+import { cropPlugin } from "./plugins/cropPlugin/index.js";
+import { redactPlugin } from "./plugins/redactPlugin/index.js";
+import { rotateCcwPlugin, rotateCwPlugin } from "./plugins/rotatePlugin.js";
+import { zoomPlugin } from "./plugins/zoomPlugin/index.js";
+
+/** Default set of image editing plugins in display order. */
+export const defaultPlugins = [rotateCcwPlugin, rotateCwPlugin, cropPlugin, redactPlugin];
+
+/** Default view plugin providing zoom and pan. */
+export const defaultViewPlugin = zoomPlugin;

package/src/components/ImageEditor/index.ts

@@ -0,0 +1,6 @@
+export { defaultPlugins, defaultViewPlugin } from "./defaultPlugins.js";
+export type { ImageEditorRef } from "./ImageEditor.js";
+export { ImageEditor } from "./ImageEditor.js";
+export { cropPlugin } from "./plugins/cropPlugin/index.js";
+export { rotateCcwPlugin, rotateCwPlugin } from "./plugins/rotatePlugin.js";
+export type { ActionPlugin, EditAction, Plugin, ToolPlugin, ViewPlugin } from "./types.js";

package/src/components/ImageEditor/plugins/cropPlugin/CropContext.tsx

@@ -0,0 +1,24 @@
+import { createContext, useContext } from "react";
+
+import type { EditAction, ToolProviderProps } from "../../types.js";
+import type { CropToolState } from "./useCropTool.js";
+import { useCropTool } from "./useCropTool.js";
+
+interface CropContextValue extends CropToolState {
+	imageUrl: string;
+	onApply: (blob: Blob, actions: EditAction[]) => void;
+	onCancel: () => void;
+}
+
+let CropContext = createContext<CropContextValue | null>(null);
+
+export function CropProvider({ imageUrl, onApply, onCancel, children }: ToolProviderProps) {
+	let state = useCropTool(imageUrl, true);
+	return <CropContext.Provider value={{ ...state, imageUrl, onApply, onCancel }}>{children}</CropContext.Provider>;
+}
+
+export function useCropContext(): CropContextValue {
+	let ctx = useContext(CropContext);
+	if (!ctx) throw new Error("useCropContext must be used within CropProvider");
+	return ctx;
+}

package/src/components/ImageEditor/plugins/cropPlugin/CropOverlay.tsx

@@ -0,0 +1,119 @@
+import { Alert, CircularProgress, Typography } from "@mui/material";
+import { getLocalizedString } from "@olenbetong/appframe-core";
+
+import { CropCanvas } from "../../CropCanvas.js";
+import { DragHandle } from "../../DragHandle.js";
+import { EdgeHandle } from "../../EdgeHandle.js";
+import { useCropContext } from "./CropContext.js";
+
+/** Canvas-area overlay for the crop tool. Reads all state from CropContext. */
+export function CropOverlay() {
+	let {
+		imageUrl,
+		activeCorners,
+		scale,
+		displaySize,
+		canvasRef,
+		cvReady,
+		cvError,
+		cropping,
+		error,
+		handleCanvasReady,
+		updateCorner,
+	} = useCropContext();
+
+	return (
+		<div className="crop-root">
+			<div className="crop-inner">
+				<CropCanvas ref={canvasRef} imageUrl={imageUrl} corners={activeCorners} onReady={handleCanvasReady} />
+
+				{displaySize.width > 0 &&
+					activeCorners.map((corner, i) => (
+						<DragHandle
+							key={i}
+							x={corner.x * scale}
+							y={corner.y * scale}
+							onChange={(x, y) => updateCorner(i, x, y)}
+							containerWidth={displaySize.width}
+							containerHeight={displaySize.height}
+						/>
+					))}
+
+				{displaySize.width > 0 &&
+					(() => {
+						let [tl, tr, br, bl] = activeCorners;
+						let s = scale;
+						return (
+							<>
+								{/* Top edge — moves TL (0) and TR (1) */}
+								<EdgeHandle
+									x={((tl.x + tr.x) / 2) * s}
+									y={((tl.y + tr.y) / 2) * s}
+									axis="y"
+									onChange={(dx, dy) => {
+										updateCorner(0, tl.x * s + dx, tl.y * s + dy);
+										updateCorner(1, tr.x * s + dx, tr.y * s + dy);
+									}}
+								/>
+								{/* Right edge — moves TR (1) and BR (2) */}
+								<EdgeHandle
+									x={((tr.x + br.x) / 2) * s}
+									y={((tr.y + br.y) / 2) * s}
+									axis="x"
+									onChange={(dx, dy) => {
+										updateCorner(1, tr.x * s + dx, tr.y * s + dy);
+										updateCorner(2, br.x * s + dx, br.y * s + dy);
+									}}
+								/>
+								{/* Bottom edge — moves BR (2) and BL (3) */}
+								<EdgeHandle
+									x={((br.x + bl.x) / 2) * s}
+									y={((br.y + bl.y) / 2) * s}
+									axis="y"
+									onChange={(dx, dy) => {
+										updateCorner(2, br.x * s + dx, br.y * s + dy);
+										updateCorner(3, bl.x * s + dx, bl.y * s + dy);
+									}}
+								/>
+								{/* Left edge — moves BL (3) and TL (0) */}
+								<EdgeHandle
+									x={((bl.x + tl.x) / 2) * s}
+									y={((bl.y + tl.y) / 2) * s}
+									axis="x"
+									onChange={(dx, dy) => {
+										updateCorner(3, bl.x * s + dx, bl.y * s + dy);
+										updateCorner(0, tl.x * s + dx, tl.y * s + dy);
+									}}
+								/>
+							</>
+						);
+					})()}
+			</div>
+
+			{!cvReady && !cvError && (
+				<div className="crop-loading">
+					<CircularProgress size={18} color="inherit" />
+					<Typography variant="body2">{getLocalizedString("Loading OpenCV…")}</Typography>
+				</div>
+			)}
+			{cvError && (
+				<div className="crop-loading">
+					<Alert severity="error" sx={{ fontSize: "0.8rem" }}>
+						{getLocalizedString("Crop tool failed to load")}
+					</Alert>
+				</div>
+			)}
+			{(error || cropping) && (
+				<div className="crop-loading">
+					{cropping ? (
+						<CircularProgress size={18} color="inherit" />
+					) : (
+						<Alert severity="error" sx={{ fontSize: "0.8rem" }}>
+							{error}
+						</Alert>
+					)}
+				</div>
+			)}
+		</div>
+	);
+}

package/src/components/ImageEditor/plugins/cropPlugin/CropToolbar.tsx

@@ -0,0 +1,36 @@
+import CheckIcon from "@mui/icons-material/Check";
+import CloseIcon from "@mui/icons-material/Close";
+import { Button, CircularProgress } from "@mui/material";
+import { getLocalizedString } from "@olenbetong/appframe-core";
+
+import { useCropContext } from "./CropContext.js";
+
+/** Toolbar shown while the crop tool is active. Reads state from CropContext. */
+export function CropToolbar() {
+	let { applyCrop, cropping, cvReady, cvError, onApply, onCancel } = useCropContext();
+
+	async function handleApply() {
+		let result = await applyCrop();
+		if (result) onApply(result.blob, result.actions);
+	}
+
+	return (
+		<>
+			<div className="image-editor__toolbar-group">
+				<Button startIcon={<CloseIcon />} onClick={onCancel} color="inherit" disabled={cropping}>
+					{getLocalizedString("Cancel")}
+				</Button>
+			</div>
+			<div className="image-editor__toolbar-group">
+				<Button
+					variant="contained"
+					startIcon={cropping ? <CircularProgress size={18} color="inherit" /> : <CheckIcon />}
+					onClick={handleApply}
+					disabled={cropping || !cvReady || !!cvError}
+				>
+					{getLocalizedString("Apply crop")}
+				</Button>
+			</div>
+		</>
+	);
+}

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

@@ -0,0 +1,20 @@
+import CropIcon from "@mui/icons-material/Crop";
+
+import type { ToolPlugin } from "../../types.js";
+import { CropProvider } from "./CropContext.js";
+import { CropOverlay } from "./CropOverlay.js";
+import { CropToolbar } from "./CropToolbar.js";
+import { replayCrop } from "./useCropTool.js";
+
+export { CropOverlay, CropProvider, CropToolbar };
+
+export const cropPlugin: ToolPlugin = {
+	type: "tool",
+	id: "crop",
+	label: "Crop",
+	Icon: CropIcon,
+	Provider: CropProvider,
+	Overlay: CropOverlay,
+	Toolbar: CropToolbar,
+	actions: [{ type: "crop", apply: replayCrop }],
+};