@michaelyagi/kiri 0.1.0-alpha.2 → 0.1.0-alpha.3

package/dist/batch.d.ts

@@ -23,6 +23,8 @@ export declare class KiriBatch {
     get length(): number;
     /** Loads the next queued image into `cropper`. Returns false once the queue is exhausted. */
     next(): Promise<boolean>;
+    /** Loads the previous queued image into `cropper`. Returns false when already at the first item (or nothing loaded yet). */
+    previous(): Promise<boolean>;
     /** Metadata for the currently loaded item, or null before the first next() / after exhaustion. */
     current(): KiriBatchItem | null;
     /** Exports the current crop and stores it, indexed by item order. */

package/dist/export.d.ts

@@ -1,4 +1,4 @@
-import { ExportOptions, ExportResult, FrameShape, KiriState, Offset } from './types';
+import { CropRegion, ExportOptions, ExportResult, FrameShape, KiriState, Offset } from './types';
 import { Size } from './gestures';
 /**
  * Top-left corner of the frame, in the local pixel space of the rendered
@@ -12,5 +12,16 @@ export declare function computeFrameSourceRect(rendered: Size, offset: Offset, f
     left: number;
     top: number;
 };
+/**
+ * Maps the current crop selection back into the *original, unrotated,
+ * unflipped* source image's own pixel coordinates. Corner-based: takes the
+ * frame rect's four corners in rendered (rotated + scaled) space, undoes the
+ * scale, then inverse-rotates each corner (rotation is always a multiple of
+ * 90°, so this stays an axis-aligned rectangle — no interpolation needed)
+ * back into the natural image's coordinate space, then takes the bounding
+ * box. Flip doesn't move the rectangle (mirroring is content-only), so it's
+ * carried through untouched in the result for the caller to apply.
+ */
+export declare function computeCropRegion(natural: Size, frame: Size, state: KiriState): CropRegion;
 export declare function renderCropToCanvas(img: HTMLImageElement, state: KiriState, frame: Size, outputWidth: number, outputHeight: number, frameShape: FrameShape): HTMLCanvasElement;
 export declare function exportCrop(img: HTMLImageElement, state: KiriState, frame: Size, frameShape: FrameShape, options: ExportOptions): Promise<ExportResult>;

package/dist/gestures.d.ts

@@ -25,6 +25,8 @@ interface GestureCallbacks {
         max: number;
     };
     setState: (next: KiriState) => void;
+    /** Called on the "0" key — reverts to the post-`load()` state. */
+    reset: () => void;
 }
 export interface GestureOptions {
     mouseWheelZoom?: boolean | "ctrl";

package/dist/index.d.ts

@@ -1,4 +1,4 @@
 export { Kiri } from './kiri';
 export { KiriBatch } from './batch';
 export type { KiriBatchItem } from './batch';
-export type { ExportFormat, ExportOptions, ExportResult, ExportType, Filters, Flip, FrameShape, FrameSize, KiriEventCallback, KiriEventName, KiriOptions, KiriState, LoadOptions, Offset, UploadOptions, Uploader, ZoomerPosition, } from './types';
+export type { CropRegion, ExportFormat, ExportOptions, ExportResult, ExportType, Filters, Flip, FrameShape, FrameSize, KiriEventCallback, KiriEventName, KiriOptions, KiriState, LoadOptions, Offset, UploadOptions, Uploader, ZoomerPosition, } from './types';

package/dist/kiri.css

@@ -42,8 +42,15 @@
   border: 1px solid #333;
   border-radius: 50%;
   pointer-events: auto;
+}
+.kiri-frame-handle--top-left,
+.kiri-frame-handle--bottom-right {
   cursor: nwse-resize;
 }
+.kiri-frame-handle--top-right,
+.kiri-frame-handle--bottom-left {
+  cursor: nesw-resize;
+}
 .kiri-root {
   display: inline-flex;
   gap: 10px;

package/dist/kiri.d.ts

@@ -1,4 +1,4 @@
-import { ExportOptions, ExportResult, Filters, KiriEventCallback, KiriEventName, KiriOptions, KiriState, LoadOptions, UploadOptions } from './types';
+import { CropRegion, ExportOptions, ExportResult, Filters, KiriEventCallback, KiriEventName, KiriOptions, KiriState, LoadOptions, Offset, UploadOptions } from './types';
 /**
  * An interactive image cropper attached to a plain DOM element. Drag to pan,
  * zoom via wheel/pinch/an optional built-in slider, rotate in 90° steps,
@@ -13,6 +13,8 @@ export declare class Kiri {
     private zoomerHandle;
     private naturalSize;
     private state;
+    /** Snapshot taken right after `load()` resolves, so `reset()` has something to revert to. */
+    private initialState;
     private listeners;
     /**
      * @param container An element already present in the DOM. Passing
@@ -34,6 +36,18 @@ export declare class Kiri {
     getState(): KiriState;
     /** Sets the zoom to an absolute value, clamped to `[minZoom, maxZoom]`. */
     setZoom(zoom: number): void;
+    /**
+     * Sets the pan offset to an absolute value (image-center offset from the
+     * frame center, in stage pixels), clamped so the frame stays fully covered
+     * by the rendered image.
+     */
+    setOffset(offset: Offset): void;
+    /**
+     * Reverts zoom/offset/rotation/flip/filters to what they were right after
+     * `load()` resolved (including any `loadOptions` passed to it). No-op if
+     * nothing has been loaded yet.
+     */
+    reset(): void;
     /**
      * Rotates relative to the current rotation, snapped to the nearest 90°.
      * No-op if `rotatable: false` was passed to the constructor.
@@ -61,6 +75,13 @@ export declare class Kiri {
      * @returns A data URL string (`type: "base64"`, the default), a `Blob`, or an `HTMLCanvasElement`.
      */
     export(options?: ExportOptions): Promise<ExportResult>;
+    /**
+     * The current crop selection as a rectangle in the original, unrotated,
+     * unflipped source image's own pixel coordinates — for sending to a server
+     * that will crop the full-resolution original itself instead of uploading
+     * a client-re-encoded image. See {@link CropRegion}.
+     */
+    getCropRegion(): CropRegion;
     /**
      * Exports the current crop as a blob, then uploads it — a default
      * FormData/`fetch` POST, or a custom `uploader` (per-call `options.uploader`

package/dist/kiri.js

@@ -35,6 +35,12 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
     container.innerHTML = "";
     const stageEl = document.createElement("div");
     stageEl.className = "kiri-stage";
+    stageEl.tabIndex = 0;
+    stageEl.setAttribute("role", "application");
+    stageEl.setAttribute(
+      "aria-label",
+      "Image cropper. Drag to pan. Arrow keys to pan, plus/minus to zoom, 0 to reset."
+    );
     const imageLayerEl = document.createElement("div");
     imageLayerEl.className = "kiri-image-layer";
     const imgEl = document.createElement("img");
@@ -109,6 +115,8 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
   function normalizeRotation(deg) {
     return (deg % 360 + 360) % 360;
   }
+  const KEYBOARD_PAN_STEP = 15;
+  const KEYBOARD_ZOOM_STEP = 0.1;
   function pointerDistance(a, b) {
     return Math.hypot(a.clientX - b.clientX, a.clientY - b.clientY);
   }
@@ -188,11 +196,47 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
       const delta = -e.deltaY * 15e-4;
       applyClampedState({ ...state, zoom: state.zoom * (1 + delta) });
     }
+    function onKeyDown(e) {
+      const state = callbacks.getState();
+      switch (e.key) {
+        case "ArrowLeft":
+          e.preventDefault();
+          applyClampedState({ ...state, offset: { ...state.offset, x: state.offset.x - KEYBOARD_PAN_STEP } });
+          break;
+        case "ArrowRight":
+          e.preventDefault();
+          applyClampedState({ ...state, offset: { ...state.offset, x: state.offset.x + KEYBOARD_PAN_STEP } });
+          break;
+        case "ArrowUp":
+          e.preventDefault();
+          applyClampedState({ ...state, offset: { ...state.offset, y: state.offset.y - KEYBOARD_PAN_STEP } });
+          break;
+        case "ArrowDown":
+          e.preventDefault();
+          applyClampedState({ ...state, offset: { ...state.offset, y: state.offset.y + KEYBOARD_PAN_STEP } });
+          break;
+        case "+":
+        case "=":
+          e.preventDefault();
+          applyClampedState({ ...state, zoom: state.zoom + KEYBOARD_ZOOM_STEP });
+          break;
+        case "-":
+        case "_":
+          e.preventDefault();
+          applyClampedState({ ...state, zoom: state.zoom - KEYBOARD_ZOOM_STEP });
+          break;
+        case "0":
+          e.preventDefault();
+          callbacks.reset();
+          break;
+      }
+    }
     stageEl.addEventListener("pointerdown", onPointerDown);
     stageEl.addEventListener("pointermove", onPointerMove);
     stageEl.addEventListener("pointerup", onPointerUp);
     stageEl.addEventListener("pointercancel", onPointerUp);
     stageEl.addEventListener("wheel", onWheel, { passive: false });
+    stageEl.addEventListener("keydown", onKeyDown);
     return {
       destroy() {
         stageEl.removeEventListener("pointerdown", onPointerDown);
@@ -200,6 +244,7 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
         stageEl.removeEventListener("pointerup", onPointerUp);
         stageEl.removeEventListener("pointercancel", onPointerUp);
         stageEl.removeEventListener("wheel", onWheel);
+        stageEl.removeEventListener("keydown", onKeyDown);
       }
     };
   }
@@ -265,6 +310,9 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
     );
     return fallback;
   }
+  function clampNum(value, min, max) {
+    return Math.min(Math.max(value, min), max);
+  }
   const VALID_EXPORT_TYPES = ["base64", "blob", "canvas"];
   const VALID_EXPORT_FORMATS = ["image/jpeg", "image/png", "image/webp"];
   function computeFrameSourceRect(rendered, offset, frame) {
@@ -273,6 +321,53 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
       top: rendered.height / 2 - offset.y - frame.height / 2
     };
   }
+  function computeCropRegion(natural, frame, state) {
+    const scale = computeCoverScale(natural, frame, state.rotation) * state.zoom;
+    const rendered = effectiveRenderedSize(natural, frame, state.rotation, state.zoom);
+    const { left: frameLeft, top: frameTop } = computeFrameSourceRect(rendered, state.offset, frame);
+    const renderedCenter = { x: rendered.width / 2, y: rendered.height / 2 };
+    const naturalCenter = { x: natural.width / 2, y: natural.height / 2 };
+    const rotation = normalizeRotation(state.rotation);
+    const corners = [
+      { x: frameLeft, y: frameTop },
+      { x: frameLeft + frame.width, y: frameTop },
+      { x: frameLeft, y: frameTop + frame.height },
+      { x: frameLeft + frame.width, y: frameTop + frame.height }
+    ].map(({ x, y }) => {
+      const cx = (x - renderedCenter.x) / scale;
+      const cy = (y - renderedCenter.y) / scale;
+      let u;
+      let v;
+      if (rotation === 90) {
+        u = cy;
+        v = -cx;
+      } else if (rotation === 180) {
+        u = -cx;
+        v = -cy;
+      } else if (rotation === 270) {
+        u = -cy;
+        v = cx;
+      } else {
+        u = cx;
+        v = cy;
+      }
+      return { x: u + naturalCenter.x, y: v + naturalCenter.y };
+    });
+    const xs = corners.map((c) => c.x);
+    const ys = corners.map((c) => c.y);
+    const left = clampNum(Math.min(...xs), 0, natural.width);
+    const top = clampNum(Math.min(...ys), 0, natural.height);
+    const right = clampNum(Math.max(...xs), 0, natural.width);
+    const bottom = clampNum(Math.max(...ys), 0, natural.height);
+    return {
+      x: Math.round(left),
+      y: Math.round(top),
+      width: Math.round(right - left),
+      height: Math.round(bottom - top),
+      rotation,
+      flip: { ...state.flip }
+    };
+  }
   function renderCropToCanvas(img, state, frame, outputWidth, outputHeight, frameShape) {
     const natural = { width: img.naturalWidth, height: img.naturalHeight };
     const scale = computeCoverScale(natural, frame, state.rotation) * state.zoom;
@@ -404,6 +499,8 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
         flip: { horizontal: false, vertical: false },
         filters: DEFAULT_FILTERS
       });
+      /** Snapshot taken right after `load()` resolves, so `reset()` has something to revert to. */
+      __publicField(this, "initialState", null);
       __publicField(this, "listeners", { change: [] });
       var _a, _b, _c;
       if (!container || typeof container.appendChild !== "function") {
@@ -428,6 +525,7 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
         rotatable: options.rotatable ?? true,
         flippable: options.flippable ?? true,
         resizableFrame: options.resizableFrame ?? false,
+        lockAspectRatio: options.lockAspectRatio ?? false,
         mouseWheelZoom: resolveMouseWheelZoom(options.mouseWheelZoom),
         useExifOrientation: options.useExifOrientation ?? true,
         uploader: options.uploader,
@@ -464,7 +562,8 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
           getFrameSize: () => this.getFrameSize(),
           getState: () => this.state,
           getMinMaxZoom: () => ({ min: this.opts.minZoom, max: this.opts.maxZoom }),
-          setState: (next) => this.commitState(next)
+          setState: (next) => this.commitState(next),
+          reset: () => this.reset()
         },
         { mouseWheelZoom: this.opts.mouseWheelZoom }
       );
@@ -523,6 +622,7 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
         flip: { horizontal: flipHorizontal, vertical: flipVertical },
         filters: this.state.filters
       });
+      this.initialState = this.getState();
     }
     /** A snapshot of the current state — mutating the returned object has no effect. */
     getState() {
@@ -546,6 +646,36 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
       const offset = clampOffset(this.state.offset, rendered, this.getFrameSize());
       this.commitState({ ...this.state, zoom: clamped, offset });
     }
+    /**
+     * Sets the pan offset to an absolute value (image-center offset from the
+     * frame center, in stage pixels), clamped so the frame stays fully covered
+     * by the rendered image.
+     */
+    setOffset(offset) {
+      const rendered = effectiveRenderedSize(
+        this.naturalSize,
+        this.getFrameSize(),
+        this.state.rotation,
+        this.state.zoom
+      );
+      const clamped = clampOffset(offset, rendered, this.getFrameSize());
+      this.commitState({ ...this.state, offset: clamped });
+    }
+    /**
+     * Reverts zoom/offset/rotation/flip/filters to what they were right after
+     * `load()` resolved (including any `loadOptions` passed to it). No-op if
+     * nothing has been loaded yet.
+     */
+    reset() {
+      if (!this.initialState) return;
+      this.commitState({
+        zoom: this.initialState.zoom,
+        offset: { ...this.initialState.offset },
+        rotation: this.initialState.rotation,
+        flip: { ...this.initialState.flip },
+        filters: { ...this.initialState.filters }
+      });
+    }
     /**
      * Rotates relative to the current rotation, snapped to the nearest 90°.
      * No-op if `rotatable: false` was passed to the constructor.
@@ -616,6 +746,15 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
         options
       );
     }
+    /**
+     * The current crop selection as a rectangle in the original, unrotated,
+     * unflipped source image's own pixel coordinates — for sending to a server
+     * that will crop the full-resolution original itself instead of uploading
+     * a client-re-encoded image. See {@link CropRegion}.
+     */
+    getCropRegion() {
+      return computeCropRegion(this.naturalSize, this.getFrameSize(), this.state);
+    }
     /**
      * Exports the current crop as a blob, then uploads it — a default
      * FormData/`fetch` POST, or a custom `uploader` (per-call `options.uploader`
@@ -678,42 +817,64 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
       };
     }
     enableFrameResize() {
-      const handle = document.createElement("div");
-      handle.className = "kiri-frame-handle";
-      handle.style.right = "-5px";
-      handle.style.bottom = "-5px";
-      this.stage.frameEl.appendChild(handle);
-      let start = null;
-      const onDown = (e) => {
-        e.stopPropagation();
-        handle.setPointerCapture(e.pointerId);
-        start = {
-          x: e.clientX,
-          y: e.clientY,
-          width: this.opts.frame.width,
-          height: this.opts.frame.height
+      const corners = [
+        { name: "top-left", edge: { left: "-5px", top: "-5px" }, signX: -1, signY: -1 },
+        { name: "top-right", edge: { right: "-5px", top: "-5px" }, signX: 1, signY: -1 },
+        { name: "bottom-left", edge: { left: "-5px", bottom: "-5px" }, signX: -1, signY: 1 },
+        { name: "bottom-right", edge: { right: "-5px", bottom: "-5px" }, signX: 1, signY: 1 }
+      ];
+      const cleanups = [];
+      for (const corner of corners) {
+        const handle = document.createElement("div");
+        handle.className = `kiri-frame-handle kiri-frame-handle--${corner.name}`;
+        Object.assign(handle.style, corner.edge);
+        this.stage.frameEl.appendChild(handle);
+        let start = null;
+        const onDown = (e) => {
+          e.stopPropagation();
+          handle.setPointerCapture(e.pointerId);
+          start = {
+            x: e.clientX,
+            y: e.clientY,
+            width: this.opts.frame.width,
+            height: this.opts.frame.height
+          };
         };
-      };
-      const onMove = (e) => {
-        if (!start) return;
-        const dx = (e.clientX - start.x) * 2;
-        const dy = (e.clientY - start.y) * 2;
-        this.setFrameSize(start.width + dx, start.height + dy);
-      };
-      const onUp = () => {
-        start = null;
-      };
-      handle.addEventListener("pointerdown", onDown);
-      handle.addEventListener("pointermove", onMove);
-      handle.addEventListener("pointerup", onUp);
-      handle.addEventListener("pointercancel", onUp);
-      this.resizeHandle = {
-        destroy() {
+        const onMove = (e) => {
+          if (!start) return;
+          const dx = (e.clientX - start.x) * 2 * corner.signX;
+          const dy = (e.clientY - start.y) * 2 * corner.signY;
+          const rawWidth = start.width + dx;
+          const rawHeight = start.height + dy;
+          if (this.opts.lockAspectRatio) {
+            const aspect = start.width / start.height;
+            if (Math.abs(rawWidth - start.width) >= Math.abs(rawHeight - start.height) * aspect) {
+              this.setFrameSize(rawWidth, rawWidth / aspect);
+            } else {
+              this.setFrameSize(rawHeight * aspect, rawHeight);
+            }
+          } else {
+            this.setFrameSize(rawWidth, rawHeight);
+          }
+        };
+        const onUp = () => {
+          start = null;
+        };
+        handle.addEventListener("pointerdown", onDown);
+        handle.addEventListener("pointermove", onMove);
+        handle.addEventListener("pointerup", onUp);
+        handle.addEventListener("pointercancel", onUp);
+        cleanups.push(() => {
           handle.removeEventListener("pointerdown", onDown);
           handle.removeEventListener("pointermove", onMove);
           handle.removeEventListener("pointerup", onUp);
           handle.removeEventListener("pointercancel", onUp);
           handle.remove();
+        });
+      }
+      this.resizeHandle = {
+        destroy() {
+          for (const cleanup of cleanups) cleanup();
         }
       };
     }
@@ -745,6 +906,14 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
       await this.cropper.load(item.source, item.loadOptions);
       return true;
     }
+    /** Loads the previous queued image into `cropper`. Returns false when already at the first item (or nothing loaded yet). */
+    async previous() {
+      if (this.index <= 0) return false;
+      this.index -= 1;
+      const item = this.items[this.index];
+      await this.cropper.load(item.source, item.loadOptions);
+      return true;
+    }
     /** Metadata for the currently loaded item, or null before the first next() / after exhaustion. */
     current() {
       return this.items[this.index] ?? null;