-
-```
-
-### Step 2: Add controls
-
-`useCropperState` returns a single `controller` object bundling the state and a named setter for every supported transition:
-
-```tsx
-const controller = useCropperState();
-const {
- state,
- setZoom, setZoomAtPoint, setRotation, setFlip, snapRotate90, setCropRect,
- applyOperation, reset, isDirty, getCroppedImage,
-} = controller;
-
-// Zoom slider
- setZoom( parseFloat( e.target.value ) ) } />
-
-// Rotation buttons
-
-
-
-// Flip
-
-
-// Reset
-
-```
-
-### Step 3: Export the result
-
-```tsx
-// As a Blob (for upload or further processing):
-const blob = await getCroppedImage( 'image/jpeg', 0.9 );
-
-// As source-pixel coordinates (for server-side processing):
-import { getSourceRegion } from '../image-editor';
-const region = getSourceRegion( state, { width: naturalWidth, height: naturalHeight } );
-
-// As percentages (for WP REST API /edit endpoint):
-import { getSourceRegionPercent } from '../image-editor';
-const pct = getSourceRegionPercent( state, { width: naturalWidth, height: naturalHeight } );
-```
+import { Cropper, useCropperReducer } from '../image-editor';
-## Architecture overview
+function ImageCropper( { src }: { src: string } ) {
+ const controller = useCropperReducer();
-```
-Consumer (plugin/theme/AI agent)
- |
- v
-useCropperState() -- State management (reducer + convenience setters)
- |
- v
-...
;
-}
-
-function MyCropper() {
- const controller = useCropperState();
- return
+
+ );
}
```
-**StencilProps contract:**
-
-| Prop | Type | Description |
-|------|------|-------------|
-| `cropRect` | `NormalizedRect` | Current crop area in [0,1] normalized space |
-| `containerSize` | `Size` | Container pixel dimensions |
-| `imageSize` | `Size` | Visual (rotated) image pixel dimensions |
-| `onCropChange` | `(rect) => void` | Call during drag to update the crop |
-| `onResizeEnd` | `() => void` | Call on mouseup to trigger settle animation |
-| `aspectRatio` | `number?` | Locked aspect ratio (width/height) |
-| `freeformCrop` | `boolean?` | Whether handles are shown |
-| `stencilTransition` | `string?` | CSS transition for settle animation |
-| `cropBounds` | `{minX,minY,maxX,maxY}?` | Allowed crop handle limits |
-
-### 2. Transform pipeline (AI agent integration)
+The cropper fills its parent. Always render it inside a sized container.
-The pipeline is the primary interface for programmatic control. Operations are JSON-serializable, making them ideal for AI agents, undo/redo stacks, and remote control.
-
-```typescript
-import { useCropperState } from '../image-editor';
-import type { TransformOperation } from '../image-editor';
-
-// An AI agent generates a list of operations:
-const operations: TransformOperation[] = [
- { type: 'crop', rect: { x: 0.1, y: 0.1, width: 0.8, height: 0.8 } },
- { type: 'rotate', degrees: 15 },
- { type: 'zoom', factor: 1.5 },
- { type: 'flip', direction: 'horizontal' },
-];
-
-// Apply them:
-const { applyOperation } = useCropperState();
-for ( const op of operations ) {
- applyOperation( op );
-}
-```
-
-**Replay from scratch:**
-
-```typescript
-import { stateFromPipeline } from '../image-editor';
-
-// Replay a pipeline from initial state:
-const finalState = stateFromPipeline( operations );
-
-// Serialize for storage (operations are plain JSON):
-const json = JSON.stringify( operations );
-
-// Deserialize:
-const ops = JSON.parse( json );
-```
-
-**Adding new operation types:**
-
-1. Add the operation variant to `TransformOperation` in `core/types.ts`
-2. Handle it in `applyOperationToState()` in `core/transforms/pipeline.ts`
-
-### 3. Custom export pipelines
-
-The export system converts cropper state to canvas output. Use `applyToCanvas()` to chain custom processing with the cropper transforms.
-
-```typescript
-import { applyToCanvas } from '../image-editor';
-
-// 1. Apply your own processing first (brightness, filters, etc.):
-const processedCanvas = applyBrightness( sourceImage, { brightness: 1.2 } );
-
-// 2. Apply the cropper transforms on top:
-const finalCanvas = applyToCanvas(
- processedCanvas,
- { width: processedCanvas.width, height: processedCanvas.height },
- cropperState
-);
-
-// 3. Export however you need:
-const blob = await new Promise( ( resolve ) =>
- finalCanvas.toBlob( resolve, 'image/jpeg', 0.9 )
-);
-```
-
-`applyToCanvas()` accepts any `CanvasImageSource`: `HTMLImageElement`, `HTMLCanvasElement`, `OffscreenCanvas`, `ImageBitmap`, `HTMLVideoElement`.
-
-### 4. State management patterns
-
-The state is a plain object and the hook returns one `controller` bundle of state + named setters. There are two ways to wire it up depending on your component structure.
-
-**Direct hook (simple case):**
-
-When the cropper and controls are in the same component:
+## Add Controls
```tsx
-import { Cropper, useCropperState } from '../image-editor';
-
-function ImageEditor() {
- const controller = useCropperState();
- const { state, setZoom, snapRotate90, reset } = controller;
- return (
-
-
-
-
-
- );
-}
-```
-
-**Provider pattern (deep component trees):**
-
-When controls and the cropper are in different parts of the tree, use `CropperProvider` to avoid prop-drilling. Any descendant can call `useCropper()` to access the controller:
+function ImageCropperWithControls( { src }: { src: string } ) {
+ const controller = useCropperReducer();
+ const { state, setZoom, snapRotate90, toggleFlip, reset } = controller;
+
+ return (
+ <>
+
+
+
+
+
-
-
-
- );
+ const { snapRotate90 } = useCropper();
+ return ;
}
-function CropperPanel() {
- const controller = useCropper();
- return Zoom: { Math.round( state.zoom * 100 ) }%
; +function CropperPanel( { src }: { src: string } ) { + const controller = useCropper(); + return
-
- );
+for ( const operation of operations ) {
+ controller.applyOperation( operation );
}
-```
-
-**Key implementation details:**
-
-| Concern | Solution |
-|---------|----------|
-| Stale closures in gesture callbacks | Use `useRef` for state (`stateRef`) and snapshot (`snapshotRef`). The callbacks are stable (`[]` deps) and always read the latest value. |
-| Stale closures in keyboard handler | Use `undoRef` / `redoRef` updated on every render, with the listener registered once (`[]` deps). |
-| Wheel zoom boundaries | The `useInteraction` hook debounces wheel events — it fires `onGestureStart` on the first scroll tick and `onGestureEnd` after 300ms of inactivity, grouping a burst of scroll events into one undo step. |
-| Handle resize settle | `onGestureEnd` fires after the settle animation (crop re-centers). The undo snapshot captures the final settled state. |
-| Pipeline display | For toolbar ops, log the `TransformOperation`. For gestures, compare before/after state and generate a descriptive label (e.g., "gesture: pan, zoom 1.5x"). |
-
-## Accessibility
-The cropper is keyboard-accessible and screen-reader friendly:
-
-**Keyboard controls:**
-- **Arrow keys** on the container: pan the image (Shift for larger jumps)
-- **+/-** on the container: zoom in/out
-- **R** on the container: snap rotate 90°
-- **Tab** to crop handles, then **arrow keys** to resize (Shift for larger jumps)
-- Aspect ratio lock is respected during keyboard resize
-
-**Screen reader support:**
-- Container is a focusable `role="group"` with `aria-label="Image editor"`. We deliberately avoid `role="application"` because it disables the screen reader's default keybindings — too heavy for a single widget.
-- Resize handles are native `
-
-
-
-
-
-