@cropvue/core 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,424 @@
+import * as vue from 'vue';
+import { Ref } from 'vue';
+
+interface TransformState {
+    x: number;
+    y: number;
+    scale: number;
+    rotation: number;
+    flipX: boolean;
+    flipY: boolean;
+}
+interface CropState {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    stencil: StencilType;
+    points?: Point[];
+    aspectRatio?: number | null;
+    minWidth?: number;
+    minHeight?: number;
+    maxWidth?: number;
+    maxHeight?: number;
+}
+type StencilType = 'rectangle' | 'circle' | 'freeform';
+interface Point {
+    x: number;
+    y: number;
+}
+interface ImageData {
+    element: HTMLImageElement;
+    naturalWidth: number;
+    naturalHeight: number;
+    originalFile?: File;
+    originalSize?: number;
+}
+interface CropResult {
+    blob: Blob;
+    file: File;
+    url: string;
+    coords: CropCoordinates;
+    width: number;
+    height: number;
+    originalWidth: number;
+    originalHeight: number;
+}
+interface CropCoordinates {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    rotation: number;
+    flipX: boolean;
+    flipY: boolean;
+    scale: number;
+}
+interface UploadResult {
+    url?: string;
+    [key: string]: unknown;
+}
+type UploadFn = (file: File, options: {
+    onProgress: (percent: number) => void;
+    signal: AbortSignal;
+}) => Promise<UploadResult>;
+interface QueueItem {
+    id: string;
+    file: File;
+    thumbnail: string;
+    result?: CropResult;
+    status: 'pending' | 'cropping' | 'done';
+}
+type CropVueError = {
+    type: 'file-too-large';
+    maxSize: number;
+    actualSize: number;
+} | {
+    type: 'invalid-type';
+    accepted: string[];
+    actual: string;
+} | {
+    type: 'load-failed';
+    message: string;
+} | {
+    type: 'canvas-limit';
+    maxDimension: number;
+} | {
+    type: 'upload-failed';
+    message: string;
+} | {
+    type: 'compress-failed';
+    message: string;
+};
+type OutputFormat = 'auto' | 'webp' | 'jpeg' | 'png';
+interface CropperOptions {
+    stencil?: StencilType;
+    aspectRatio?: number | null;
+    minWidth?: number;
+    minHeight?: number;
+    maxWidth?: number;
+    maxHeight?: number;
+    outputFormat?: OutputFormat;
+    outputQuality?: number;
+    outputMaxWidth?: number;
+    outputMaxHeight?: number;
+}
+interface DropzoneOptions {
+    accept?: string[];
+    maxSize?: number;
+    multiple?: boolean;
+    onFiles?: (files: File[]) => void;
+    onError?: (error: CropVueError) => void;
+}
+interface UploaderOptions {
+    url?: string;
+    fieldName?: string;
+    headers?: Record<string, string>;
+    handler?: UploadFn;
+}
+interface CompressorOptions {
+    format?: OutputFormat;
+    quality?: number;
+    maxWidth?: number;
+    maxHeight?: number;
+}
+
+declare function useCropper(options?: CropperOptions): {
+    image: Ref<ImageData | null, ImageData | null>;
+    transform: Ref<TransformState, TransformState>;
+    crop: Ref<CropState, CropState>;
+    isReady: Ref<boolean, boolean>;
+    loadFile: (file: File) => Promise<void>;
+    loadUrl: (url: string) => Promise<void>;
+    rotateLeft: () => void;
+    rotateRight: () => void;
+    rotateTo: (degrees: number) => void;
+    flipX: () => void;
+    flipY: () => void;
+    zoomTo: (scale: number) => void;
+    zoomBy: (delta: number) => void;
+    panTo: (x: number, y: number) => void;
+    reset: () => void;
+    setCropArea: (area: Partial<CropState>) => void;
+    setStencil: (stencil: StencilType) => void;
+    setAspectRatio: (ratio: number | null) => void;
+    getResult: (opts?: {
+        format?: "auto" | "webp" | "jpeg" | "png";
+        quality?: number;
+        maxWidth?: number;
+        maxHeight?: number;
+    }) => Promise<CropResult>;
+    getPreviewUrl: () => string;
+    canvasRef: Ref<HTMLCanvasElement | null, HTMLCanvasElement | null>;
+    renderToCanvas: () => void;
+};
+
+declare function validateFile(file: File, options: {
+    accept: string[];
+    maxSize: number;
+}): CropVueError | null;
+declare function useDropzone(options?: DropzoneOptions): {
+    isDragging: Ref<boolean, boolean>;
+    files: Ref<File[], File[]>;
+    dropzoneRef: Ref<HTMLElement | null, HTMLElement | null>;
+    open: () => void;
+};
+
+interface Queue {
+    items: QueueItem[];
+    currentIndex: number;
+    add: (files: File[]) => void;
+    remove: (index: number) => void;
+    select: (index: number) => void;
+    next: () => void;
+    previous: () => void;
+    clear: () => void;
+    setResult: (index: number, result: CropResult) => void;
+}
+declare function createQueue(): Queue;
+declare function useImageQueue(): {
+    images: vue.Ref<{
+        id: string;
+        file: {
+            readonly lastModified: number;
+            readonly name: string;
+            readonly webkitRelativePath: string;
+            readonly size: number;
+            readonly type: string;
+            arrayBuffer: () => Promise<ArrayBuffer>;
+            bytes: () => Promise<Uint8Array<ArrayBuffer>>;
+            slice: (start?: number, end?: number, contentType?: string) => Blob;
+            stream: () => ReadableStream<Uint8Array<ArrayBuffer>>;
+            text: () => Promise<string>;
+        };
+        thumbnail: string;
+        result?: {
+            blob: {
+                readonly size: number;
+                readonly type: string;
+                arrayBuffer: () => Promise<ArrayBuffer>;
+                bytes: () => Promise<Uint8Array<ArrayBuffer>>;
+                slice: (start?: number, end?: number, contentType?: string) => Blob;
+                stream: () => ReadableStream<Uint8Array<ArrayBuffer>>;
+                text: () => Promise<string>;
+            };
+            file: {
+                readonly lastModified: number;
+                readonly name: string;
+                readonly webkitRelativePath: string;
+                readonly size: number;
+                readonly type: string;
+                arrayBuffer: () => Promise<ArrayBuffer>;
+                bytes: () => Promise<Uint8Array<ArrayBuffer>>;
+                slice: (start?: number, end?: number, contentType?: string) => Blob;
+                stream: () => ReadableStream<Uint8Array<ArrayBuffer>>;
+                text: () => Promise<string>;
+            };
+            url: string;
+            coords: {
+                x: number;
+                y: number;
+                width: number;
+                height: number;
+                rotation: number;
+                flipX: boolean;
+                flipY: boolean;
+                scale: number;
+            };
+            width: number;
+            height: number;
+            originalWidth: number;
+            originalHeight: number;
+        } | undefined;
+        status: "pending" | "cropping" | "done";
+    }[], QueueItem[] | {
+        id: string;
+        file: {
+            readonly lastModified: number;
+            readonly name: string;
+            readonly webkitRelativePath: string;
+            readonly size: number;
+            readonly type: string;
+            arrayBuffer: () => Promise<ArrayBuffer>;
+            bytes: () => Promise<Uint8Array<ArrayBuffer>>;
+            slice: (start?: number, end?: number, contentType?: string) => Blob;
+            stream: () => ReadableStream<Uint8Array<ArrayBuffer>>;
+            text: () => Promise<string>;
+        };
+        thumbnail: string;
+        result?: {
+            blob: {
+                readonly size: number;
+                readonly type: string;
+                arrayBuffer: () => Promise<ArrayBuffer>;
+                bytes: () => Promise<Uint8Array<ArrayBuffer>>;
+                slice: (start?: number, end?: number, contentType?: string) => Blob;
+                stream: () => ReadableStream<Uint8Array<ArrayBuffer>>;
+                text: () => Promise<string>;
+            };
+            file: {
+                readonly lastModified: number;
+                readonly name: string;
+                readonly webkitRelativePath: string;
+                readonly size: number;
+                readonly type: string;
+                arrayBuffer: () => Promise<ArrayBuffer>;
+                bytes: () => Promise<Uint8Array<ArrayBuffer>>;
+                slice: (start?: number, end?: number, contentType?: string) => Blob;
+                stream: () => ReadableStream<Uint8Array<ArrayBuffer>>;
+                text: () => Promise<string>;
+            };
+            url: string;
+            coords: {
+                x: number;
+                y: number;
+                width: number;
+                height: number;
+                rotation: number;
+                flipX: boolean;
+                flipY: boolean;
+                scale: number;
+            };
+            width: number;
+            height: number;
+            originalWidth: number;
+            originalHeight: number;
+        } | undefined;
+        status: "pending" | "cropping" | "done";
+    }[]>;
+    current: vue.Ref<number, number>;
+    add: (files: File[]) => void;
+    remove: (index: number) => void;
+    select: (index: number) => void;
+    next: () => void;
+    previous: () => void;
+    clear: () => void;
+    results: vue.ComputedRef<CropResult[]>;
+};
+
+declare function createUploadHandler(options: UploaderOptions): UploadFn;
+declare function useUploader(options?: UploaderOptions): {
+    upload: (file: File | Blob) => Promise<UploadResult>;
+    isUploading: vue.Ref<boolean, boolean>;
+    progress: vue.Ref<number, number>;
+    error: vue.Ref<string | null, string | null>;
+    abort: () => void;
+};
+
+declare function chooseOutputFormat(format: OutputFormat, inputMime: string): string;
+declare function compressBlob(canvas: HTMLCanvasElement, options: {
+    format: OutputFormat;
+    quality: number;
+    inputMime: string;
+    maxInputSize?: number;
+}): Promise<Blob>;
+declare function useCompressor(options?: CompressorOptions): {
+    compress: (canvas: HTMLCanvasElement, inputFile?: File) => Promise<Blob>;
+    isCompressing: vue.Ref<boolean, boolean>;
+};
+
+declare function handlePan(state: TransformState, dx: number, dy: number): TransformState;
+declare function handleZoom(state: TransformState, delta: number, centerX: number, centerY: number): TransformState;
+type HandlePosition = 'nw' | 'ne' | 'sw' | 'se' | 'n' | 's' | 'e' | 'w';
+declare function handleCropResize(crop: CropState, handle: HandlePosition, dx: number, dy: number, bounds: {
+    width: number;
+    height: number;
+}): CropState;
+declare function handleCropMove(crop: CropState, dx: number, dy: number, bounds: {
+    width: number;
+    height: number;
+}): CropState;
+declare function handleKeyboard(state: TransformState, key: string, shiftKey: boolean): TransformState;
+
+interface PointerHandlerOptions {
+    onPan: (dx: number, dy: number) => void;
+    onZoom: (delta: number, centerX: number, centerY: number) => void;
+    onCropResize: (handle: HandlePosition, dx: number, dy: number) => void;
+    onCropMove: (dx: number, dy: number) => void;
+    onKeyboard: (key: string, shiftKey: boolean) => void;
+    getHandleAtPoint: (e: PointerEvent) => HandlePosition | null;
+    isInsideCropArea: (e: PointerEvent) => boolean;
+    displayScale: () => number;
+}
+interface PointerHandlerCleanup {
+    destroy: () => void;
+}
+declare function usePointerHandler(element: HTMLElement, options: PointerHandlerOptions): PointerHandlerCleanup;
+
+declare function createTransformState(overrides?: Partial<TransformState>): TransformState;
+declare function createCropState(dimensions: {
+    width: number;
+    height: number;
+}, overrides?: Partial<CropState>): CropState;
+declare function snapRotation(degrees: number): number;
+declare function applyRotation(state: TransformState, degrees: number): TransformState;
+declare function applyFlip(state: TransformState, axis: 'x' | 'y'): TransformState;
+declare function applyZoom(state: TransformState, delta: number): TransformState;
+declare function applyPan(state: TransformState, dx: number, dy: number): TransformState;
+declare function clampTransform(state: TransformState, bounds: {
+    minX: number;
+    maxX: number;
+    minY: number;
+    maxY: number;
+}): TransformState;
+declare function resetTransform(_state: TransformState): TransformState;
+
+interface RenderOptions {
+    maxWidth?: number;
+    maxHeight?: number;
+}
+interface ExportOptions {
+    format: string;
+    quality: number;
+}
+declare function renderCrop(canvas: HTMLCanvasElement, image: HTMLImageElement, crop: CropState, transform: TransformState, options?: RenderOptions): void;
+declare function exportCrop(canvas: HTMLCanvasElement, options: ExportOptions): Promise<Blob>;
+
+interface ContainerBounds {
+    containerWidth: number;
+    containerHeight: number;
+}
+declare function constrainCropSize(crop: CropState, bounds: ContainerBounds): CropState;
+declare function constrainAspectRatio(crop: CropState): CropState;
+declare function constrainCropPosition(crop: CropState, bounds: ContainerBounds): CropState;
+
+interface ContainerDimensions {
+    containerWidth: number;
+    containerHeight: number;
+}
+declare function getRectangleClipPath(rect: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}, container: ContainerDimensions): string;
+declare function getCircleClipPath(rect: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}, _container: ContainerDimensions): string;
+declare function getFreeformClipPath(points: Point[]): string;
+declare function isPointInsideStencil(px: number, py: number, crop: Pick<CropState, 'stencil' | 'x' | 'y' | 'width' | 'height' | 'points'>): boolean;
+
+declare function getMaxCanvasSize(): number;
+declare function downsampleDimensions(width: number, height: number, maxDimension: number): {
+    width: number;
+    height: number;
+};
+
+declare function detectMimeType(file: File): string;
+declare function supportsWebP(): boolean;
+declare function getMimeForFormat(format: OutputFormat): string;
+declare function hasTransparency(mime: string): boolean;
+
+declare function loadImageFromFile(file: File): Promise<ImageData>;
+declare function loadImageFromUrl(url: string): Promise<ImageData>;
+declare function needsDownsample(width: number, height: number): boolean;
+declare function getSafeDimensions(width: number, height: number): {
+    width: number;
+    height: number;
+};
+
+export { applyFlip, applyPan, applyRotation, applyZoom, chooseOutputFormat, clampTransform, compressBlob, constrainAspectRatio, constrainCropPosition, constrainCropSize, createCropState, createQueue, createTransformState, createUploadHandler, detectMimeType, downsampleDimensions, exportCrop, getCircleClipPath, getFreeformClipPath, getMaxCanvasSize, getMimeForFormat, getRectangleClipPath, getSafeDimensions, handleCropMove, handleCropResize, handleKeyboard, handlePan, handleZoom, hasTransparency, isPointInsideStencil, loadImageFromFile, loadImageFromUrl, needsDownsample, renderCrop, resetTransform, snapRotation, supportsWebP, useCompressor, useCropper, useDropzone, useImageQueue, usePointerHandler, useUploader, validateFile };
+export type { CompressorOptions, CropCoordinates, CropResult, CropState, CropVueError, CropperOptions, DropzoneOptions, HandlePosition, ImageData, OutputFormat, Point, PointerHandlerCleanup, PointerHandlerOptions, QueueItem, StencilType, TransformState, UploadFn, UploadResult, UploaderOptions };