@michaelyagi/kiri 0.1.0-alpha.2

package/dist/batch.d.ts

@@ -0,0 +1,34 @@
+import { Kiri } from './kiri';
+import { ExportOptions, ExportResult, KiriOptions, LoadOptions } from './types';
+export interface KiriBatchItem {
+    source: File | Blob | string;
+    loadOptions?: LoadOptions;
+}
+/**
+ * Steps a single shared `Kiri` instance through a queue of images, so the
+ * whole drag/zoom/rotate/flip/filters interaction surface is reused as-is —
+ * no per-image instance, no duplicated cropping logic.
+ */
+export declare class KiriBatch {
+    /** The shared `Kiri` instance. Use its normal methods (drag/zoom/rotate/filters/etc.) to adjust the currently-loaded item. */
+    readonly cropper: Kiri;
+    private readonly items;
+    private index;
+    private captures;
+    /** @param items An initial queue; more can be added later via `add()`. */
+    constructor(container: HTMLElement, options?: KiriOptions, items?: KiriBatchItem[]);
+    /** Appends an item to the queue. */
+    add(item: KiriBatchItem): void;
+    /** Total number of queued items. */
+    get length(): number;
+    /** Loads the next queued image into `cropper`. Returns false once the queue is exhausted. */
+    next(): 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. */
+    capture(options?: ExportOptions): Promise<ExportResult>;
+    /** All captures made so far, in item order (sparse where an item hasn't been captured yet). */
+    results(): ExportResult[];
+    /** Tears down the shared `Kiri` instance. */
+    destroy(): void;
+}

package/dist/exif.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Reads the EXIF orientation tag (1-8) from a JPEG ArrayBuffer, defaulting to 1
+ * (no adjustment) for images with no EXIF data or non-JPEG input.
+ */
+export declare function readExifOrientation(buffer: ArrayBuffer): number;
+export interface OrientationTransform {
+    rotation: number;
+    flipHorizontal: boolean;
+}
+/**
+ * Maps an EXIF orientation value to the rotation + horizontal-flip pair that
+ * normalizes it. A vertical flip is never needed on its own: orientation 4
+ * (mirror vertical) is expressed as rotate(180) + flip horizontal, which is
+ * mathematically equivalent and matches Kiri's transform order (flip is
+ * applied before rotation, so this composes correctly).
+ */
+export declare function orientationToTransform(orientation: number): OrientationTransform;

package/dist/export.d.ts

@@ -0,0 +1,16 @@
+import { 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
+ * (rotated + scaled) image. Pure so the crop-region math is testable without
+ * a real canvas: the frame is centered on the stage, the image's own center
+ * sits at `offset` from that same point, so the frame's top-left in the
+ * rendered image's local space is the rendered center, shifted back by the
+ * offset.
+ */
+export declare function computeFrameSourceRect(rendered: Size, offset: Offset, frame: Size): {
+    left: number;
+    top: number;
+};
+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/filters.d.ts

@@ -0,0 +1,11 @@
+import { Filters } from './types';
+export declare const DEFAULT_FILTERS: Filters;
+/** Merges a partial filter update into the current filters, clamping numeric values to >= 0. */
+export declare function mergeFilters(current: Filters, partial: Partial<Filters>): Filters;
+/**
+ * Builds a CSS `filter` value from the current filter state. Used verbatim as
+ * both the live-preview `img.style.filter` and a canvas 2D context's
+ * `ctx.filter` before drawing, so preview and export always match exactly —
+ * no separately hand-rolled brightness/contrast/saturation pixel math.
+ */
+export declare function buildFilterString(filters: Filters): string;

package/dist/gestures.d.ts

@@ -0,0 +1,35 @@
+import { KiriState, Offset } from './types';
+export interface Size {
+    width: number;
+    height: number;
+}
+/** Rotation-aware natural size: 90/270 degrees swap width and height. */
+export declare function effectiveNaturalSize(natural: Size, rotationDeg: number): Size;
+/** The smallest scale at which the (rotation-adjusted) image still fully covers the frame. */
+export declare function computeCoverScale(natural: Size, frame: Size, rotationDeg: number): number;
+/** Rendered size of the image layer given a user zoom multiplier (relative to cover scale). */
+export declare function effectiveRenderedSize(natural: Size, frame: Size, rotationDeg: number, zoom: number): Size;
+export declare function clampZoom(zoom: number, minZoom: number, maxZoom: number): number;
+/**
+ * Clamp the image-center offset (from stage/frame center) so the frame stays
+ * fully covered by the rendered image on every axis.
+ */
+export declare function clampOffset(offset: Offset, rendered: Size, frame: Size): Offset;
+export declare function normalizeRotation(deg: number): number;
+interface GestureCallbacks {
+    getNaturalSize: () => Size;
+    getFrameSize: () => Size;
+    getState: () => KiriState;
+    getMinMaxZoom: () => {
+        min: number;
+        max: number;
+    };
+    setState: (next: KiriState) => void;
+}
+export interface GestureOptions {
+    mouseWheelZoom?: boolean | "ctrl";
+}
+export declare function attachGestures(stageEl: HTMLElement, callbacks: GestureCallbacks, options: GestureOptions): {
+    destroy: () => void;
+};
+export {};

package/dist/index.d.ts

@@ -0,0 +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';

package/dist/kiri.css

@@ -0,0 +1,72 @@
+.kiri-stage {
+  position: relative;
+  overflow: hidden;
+  width: 100%;
+  height: 100%;
+  min-height: 200px;
+  background: #333;
+  touch-action: none;
+  cursor: grab;
+  user-select: none;
+}
+.kiri-stage.kiri-dragging {
+  cursor: grabbing;
+}
+.kiri-image-layer {
+  position: absolute;
+  top: 50%;
+  left: 50%;
+  pointer-events: none;
+}
+.kiri-image-layer img {
+  display: block;
+  max-width: none;
+}
+.kiri-frame {
+  position: absolute;
+  top: 50%;
+  left: 50%;
+  transform: translate(-50%, -50%);
+  border: 1px solid rgba(255, 255, 255, 0.85);
+  box-shadow: 0 0 0 9999px rgba(0, 0, 0, 0.5);
+  pointer-events: none;
+}
+.kiri-frame--circle {
+  border-radius: 50%;
+}
+.kiri-frame-handle {
+  position: absolute;
+  width: 10px;
+  height: 10px;
+  background: #fff;
+  border: 1px solid #333;
+  border-radius: 50%;
+  pointer-events: auto;
+  cursor: nwse-resize;
+}
+.kiri-root {
+  display: inline-flex;
+  gap: 10px;
+  align-items: stretch;
+}
+.kiri-root--bottom,
+.kiri-root--top {
+  flex-direction: column;
+}
+.kiri-root--left,
+.kiri-root--right {
+  flex-direction: row;
+}
+.kiri-root--top .kiri-zoomer,
+.kiri-root--left .kiri-zoomer {
+  order: -1;
+}
+.kiri-zoomer {
+  cursor: pointer;
+}
+.kiri-root--left .kiri-zoomer,
+.kiri-root--right .kiri-zoomer {
+  writing-mode: vertical-lr;
+  direction: rtl;
+  width: 24px;
+}

package/dist/kiri.d.ts

@@ -0,0 +1,88 @@
+import { ExportOptions, ExportResult, Filters, KiriEventCallback, KiriEventName, KiriOptions, KiriState, LoadOptions, 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,
+ * flip, apply filters, then export or upload the crop.
+ */
+export declare class Kiri {
+    private readonly container;
+    private readonly opts;
+    private readonly stage;
+    private readonly gestureHandle;
+    private resizeHandle;
+    private zoomerHandle;
+    private naturalSize;
+    private state;
+    private listeners;
+    /**
+     * @param container An element already present in the DOM. Passing
+     * `null`/`undefined`, or an element that isn't in the DOM yet, throws.
+     * @param options See the {@link KiriOptions} fields for defaults.
+     */
+    constructor(container: HTMLElement, options?: KiriOptions);
+    /**
+     * Loads an image, replacing whatever was loaded before. EXIF orientation
+     * (rotation + horizontal flip) is corrected automatically unless
+     * `useExifOrientation: false` was passed to the constructor — only for
+     * `File`/`Blob` sources, since a plain URL string can't be read for EXIF
+     * data without an extra fetch.
+     * @param source A `File` (e.g. from a file input), a `Blob`, or a URL string.
+     * @param loadOptions Initial `zoom`/`offset`/`rotation`/`flip`.
+     */
+    load(source: File | Blob | string, loadOptions?: LoadOptions): Promise<void>;
+    /** A snapshot of the current state — mutating the returned object has no effect. */
+    getState(): KiriState;
+    /** Sets the zoom to an absolute value, clamped to `[minZoom, maxZoom]`. */
+    setZoom(zoom: number): void;
+    /**
+     * Rotates relative to the current rotation, snapped to the nearest 90°.
+     * No-op if `rotatable: false` was passed to the constructor.
+     */
+    rotate(deltaDeg: number): void;
+    /** Toggles horizontal flip, independent of rotation. No-op if `flippable: false`. */
+    flipHorizontal(): void;
+    /** Toggles vertical flip, independent of rotation. No-op if `flippable: false`. */
+    flipVertical(): void;
+    /**
+     * Resizes the frame. Also resizes the stage to match, if
+     * `autoSizeStage: true` (the default). Each axis is clamped to a 20px
+     * minimum.
+     */
+    setFrameSize(width: number, height: number): void;
+    /**
+     * Merges a partial update into the current filters (omitted fields are
+     * left as they are). Numeric values are clamped to `>= 0`.
+     */
+    setFilters(filters: Partial<Filters>): void;
+    /**
+     * Renders the current crop. A circle frame is a real clip in the output
+     * (transparent corners on PNG/WebP); a circle exported as JPEG warns and
+     * renders solid black corners instead, since JPEG has no alpha channel.
+     * @returns A data URL string (`type: "base64"`, the default), a `Blob`, or an `HTMLCanvasElement`.
+     */
+    export(options?: ExportOptions): Promise<ExportResult>;
+    /**
+     * Exports the current crop as a blob, then uploads it — a default
+     * FormData/`fetch` POST, or a custom `uploader` (per-call `options.uploader`
+     * wins over the constructor's, which wins over the built-in default).
+     */
+    upload(url: string, options?: UploadOptions): Promise<unknown>;
+    /** Subscribes to `"change"` — fires on every state update (drag/zoom/rotate/flip/filters), and once after `load()` resolves. */
+    on(event: KiriEventName, callback: KiriEventCallback): void;
+    /** Unsubscribes a callback previously passed to {@link on}. */
+    off(event: KiriEventName, callback: KiriEventCallback): void;
+    /**
+     * Tears the instance down: removes all pointer/wheel event listeners
+     * (drag/zoom gestures), the resize-handle listener (if `resizableFrame`),
+     * and the zoom-slider listener (if `showZoomer`); clears the container's
+     * `innerHTML`, leaving an empty container element; and clears all
+     * `"change"` listeners. Call this when you're done with an instance (e.g.
+     * unmounting) to avoid leaking listeners.
+     */
+    destroy(): void;
+    private getFrameSize;
+    private syncStageSize;
+    private commitState;
+    private enableZoomer;
+    private enableFrameResize;
+}