Cropper

Options

minSize also caps the angle once its diagonal is longer than a side of the photo. Only its size next to the photo counts, not the photo's pixel count. While disabled, setValue(), setImage() and setOptions() still work. Both callbacks are on events.

Read the crop

Change the crop

Every write keeps the crop valid, see value. Before the cropper has a photo, only setValue(), reset(), setImage() and setOptions() do anything.

Tell listeners why

Every write except setImage() and setOptions() takes action options last. Outside a gesture, setValue(), setRotation(), setZoom() and setCropState() report imperative unless you pass a reason. Here the write straightens the photo 5°, and on the next frame the commit logs 5 history:

import { createCropper } from "@zriz/core";

const cropper = createCropper({
  image: { width: 4032, height: 3024 },
  onValueCommit: (value, details) => {
    console.log(value.rotation, details.reason);
  },
});

cropper.setRotation(5, { reason: "history" });

Drive the crop from your own input

Call begin() when your input takes hold and end() when it lets go. Every write between them is one gesture with one commit. Pass the same owner object to both, so no other input can end your gesture:

import { createCropper } from "@zriz/core";

const cropper = createCropper({
  image: { width: 4032, height: 3024 },
});
const owner = {};

export const bind = (input: HTMLInputElement) => {
  input.addEventListener("pointerdown", (event) => {
    cropper.begin("dial", event, owner);
  });

  input.addEventListener("input", () => {
    cropper.setRotation(input.valueAsNumber);
  });

  const end = (event: PointerEvent) => {
    cropper.end(event, owner);
  };

  input.addEventListener("pointerup", end);
  input.addEventListener("pointercancel", end);
};

Test without a browser

In Node, the default clock waits about 16 ms per frame on setTimeout. Pass a clock of your own and step the frames yourself, so every event fires when your test says:

import { createCropper } from "@zriz/core";
import type { Clock } from "@zriz/core";

const queue = new Map<number, (time: number) => void>();
let id = 0;
let now = 0;

const clock: Clock = {
  request: (step) => {
    id += 1;
    queue.set(id, step);

    return id;
  },
  cancel: (handle) => {
    queue.delete(handle);
  },
};

const advance = (ms: number) => {
  now += ms;
  const steps = [...queue.values()];

  queue.clear();
  for (const step of steps) step(now);
};

const commits: number[] = [];
const cropper = createCropper({
  clock,
  image: { width: 4032, height: 3024 },
  onValueCommit: (value) => commits.push(value.rotation),
});

cropper.setRotation(7);
advance(16);
console.log(commits);

setRotation() changes getValue() at once, and advance(16) runs the frame that sends the commit. The log reads [7].

Add a plugin and clean it up

A plugin is an object with a name, an init and an optional destroy. init runs right after createCropper makes the cropper. Root and useCropper take plugins too, read them once and run init once on the client, after mount, never during a render.

import { createCropper } from "@zriz/core";
import type { CropperPlugin } from "@zriz/core";

let off = () => {};

const logger: CropperPlugin = {
  name: "logger",
  init: (cropper) => {
    off = cropper.on("commit", (value) => console.log(value));
  },
  destroy: () => off(),
};

const cropper = createCropper({ plugins: [logger] });

cropper.destroy();

destroy runs only when you call destroy(). Root never calls it. When the component that made the cropper unmounts, Root or the one that called useCropper, it calls stop() instead, on purpose: StrictMode and <Activity> unmount a component and mount the same cropper again, and a destroyed cropper cannot come back.

If a plugin holds a timer or a socket, call destroy() yourself when you are done with the cropper, for example through actionsRef.

Read the crop in image pixels

getCropState() and useCropperFrame give a CropState, and setCropState() takes one. crop.x and crop.y are not a corner. They are the crop's centre measured from the photo's centre, so they can be negative, with x to the right and y down, after the quarter turns.