vuedit-image-editor 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Mahjoz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,663 @@
+import { App } from 'vue';
+import { Component } from 'vue';
+import { ComponentOptionsMixin } from 'vue';
+import { ComponentProvideOptions } from 'vue';
+import { DeepReadonly } from 'vue';
+import { DefineComponent } from 'vue';
+import { ExtractPropTypes } from 'vue';
+import { InjectionKey } from 'vue';
+import { PropType } from 'vue';
+import { PublicProps } from 'vue';
+import { Ref } from 'vue';
+
+declare type __VLS_NonUndefinedable<T> = T extends undefined ? never : T;
+
+declare type __VLS_NonUndefinedable_2<T> = T extends undefined ? never : T;
+
+declare type __VLS_Prettify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+
+declare type __VLS_TypePropsToRuntimeProps<T> = {
+    [K in keyof T]-?: {} extends Pick<T, K> ? {
+        type: PropType<__VLS_NonUndefinedable<T[K]>>;
+    } : {
+        type: PropType<T[K]>;
+        required: true;
+    };
+};
+
+declare type __VLS_TypePropsToRuntimeProps_2<T> = {
+    [K in keyof T]-?: {} extends Pick<T, K> ? {
+        type: PropType<__VLS_NonUndefinedable_2<T[K]>>;
+    } : {
+        type: PropType<T[K]>;
+        required: true;
+    };
+};
+
+declare type __VLS_WithDefaults<P, D> = {
+    [K in keyof Pick<P, keyof P>]: K extends keyof D ? __VLS_Prettify<P[K] & {
+        default: D[K];
+    }> : P[K];
+};
+
+/**
+ * Apply clarity (local contrast / unsharp mask) to ImageData in-place.
+ * strength: -0.25 to 0.25, base 0. Positive sharpens, negative softens.
+ * Uses a 3x3 Laplacian kernel blended with the original.
+ */
+export declare function applyClarity(imageData: ImageData, strength: number): void;
+
+/**
+ * Apply a 5x4 color matrix to ImageData in-place.
+ * Offsets (m4, m9, m14, m19) are in 0-1 range and scaled to 0-255 internally.
+ */
+export declare function applyColorMatrix(imageData: ImageData, matrix: number[]): void;
+
+/**
+ * Apply gamma correction to ImageData in-place.
+ * gamma: 0.2 to 5.0, base 1.0 (1 = no change)
+ */
+export declare function applyGamma(imageData: ImageData, gamma: number): void;
+
+/**
+ * Apply vignette effect to ImageData in-place.
+ * strength: -1 to 1 (negative = lighten edges, positive = darken edges)
+ */
+export declare function applyVignette(imageData: ImageData, strength: number, width: number, height: number): void;
+
+export declare const ar: LocaleStrings;
+
+/** Brightness adjustment matrix. v: -0.25 to 0.25 */
+export declare function brightnessMatrix(v: number): number[];
+
+export declare class CanvasRenderer {
+    private canvas;
+    private ctx;
+    private sourceImage;
+    private animFrameId;
+    private needsRender;
+    /** Viewport transform */
+    viewport: ViewportTransform;
+    /** Active plugin ID — used to determine whether to show cropped preview */
+    activePluginId: string | null;
+    /**
+     * The full image display rect in CSS pixels.
+     * Used by the crop overlay to position handles on top of the image.
+     */
+    private fullImageRect;
+    /** Cached offscreen canvas for color-adjusted preview */
+    private previewCanvas;
+    private previewCtx;
+    private previewCacheKey;
+    /** Max preview dimension for color processing performance */
+    private readonly previewMaxSize;
+    /** Cache for image-based sticker elements */
+    private stickerImageCache;
+    constructor(canvas: HTMLCanvasElement);
+    setSource(image: HTMLImageElement | null): void;
+    /** Resize canvas to match container (handles DPR) */
+    resize(width: number, height: number): void;
+    /** Request a render on the next animation frame */
+    requestRender(): void;
+    /** Callback called after each render with context for plugin drawing */
+    afterRender: ((ctx: CanvasRenderingContext2D, state: ImageState, imageRect: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }) => void) | null;
+    /** Cached getState function for render loop */
+    private getState;
+    /** Start the render loop */
+    startRenderLoop(getState: () => ImageState): void;
+    /** Schedule a single render frame (only when needed) */
+    private scheduleRender;
+    /** Stop the render loop */
+    stopRenderLoop(): void;
+    /**
+     * Build a cache key from the finetune + filter state.
+     * Only regenerates the preview canvas when these values change.
+     */
+    private buildEffectsCacheKey;
+    /**
+     * Check if any color effects are active.
+     */
+    private hasColorEffects;
+    /**
+     * Get a color-adjusted preview image.
+     * Returns the source image if no effects are active,
+     * otherwise returns a cached offscreen canvas with effects applied.
+     */
+    private getPreviewSource;
+    /** Check if crop is not at full-image defaults */
+    private isCropActive;
+    /**
+     * Main render method.
+     * Draws the image with color adjustments fitted to the canvas.
+     * On crop tab: renders full image (CropOverlay handles crop visualization).
+     * On other tabs: renders only the cropped region fitted to canvas.
+     */
+    render(state: ImageState): void;
+    /**
+     * Render full image view (used on the crop tab).
+     */
+    private renderFullView;
+    /**
+     * Render cropped view (used on non-crop tabs).
+     * Shows only the crop region fitted to the canvas.
+     */
+    private renderCroppedView;
+    /**
+     * Render frame preview overlay on the canvas.
+     */
+    private renderFramePreview;
+    /**
+     * Get the full image display rect in CSS pixels.
+     * The CropOverlay uses this to position crop handles correctly.
+     */
+    getImageRect(): {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    /**
+     * Render stickers on the canvas viewport.
+     */
+    private renderStickers;
+    /**
+     * Render stickers with positions remapped relative to the crop region.
+     */
+    private renderStickersInCrop;
+    destroy(): void;
+}
+
+/** Compose multiple matrices into one (left to right application order) */
+export declare function composeMatrices(...matrices: number[][]): number[];
+
+/** Contrast adjustment matrix. v: -0.25 to 0.25 */
+export declare function contrastMatrix(v: number): number[];
+
+export declare function createDefaultImageState(): ImageState;
+
+export declare function createEditorEngine(options: EditorOptions): EditorEngine;
+
+export declare function CropPlugin(): EditorPlugin;
+
+export declare interface CropState {
+    /** Normalized 0-1 X position of crop region */
+    x: number;
+    /** Normalized 0-1 Y position of crop region */
+    y: number;
+    /** Normalized 0-1 width of crop region */
+    width: number;
+    /** Normalized 0-1 height of crop region */
+    height: number;
+    /** Locked aspect ratio (width/height), null = free */
+    aspectRatio: number | null;
+    /** Rotation in radians, -PI/4 to PI/4 for free rotation */
+    rotation: number;
+    /** Flip horizontally */
+    flipX: boolean;
+    /** Flip vertically */
+    flipY: boolean;
+}
+
+declare const _default: {
+    install: typeof install;
+};
+export default _default;
+
+export declare const defaultStickerCategories: StickerCategory[];
+
+/**
+ * Deserialize a JSON string back to an ImageState.
+ * Validates the basic structure before returning.
+ */
+export declare function deserializeState(json: string): Partial<ImageState>;
+
+export declare interface EditorEngine {
+    /** Reactive editor state */
+    state: ImageState;
+    /** Read-only reactive state for consumers */
+    readonlyState: DeepReadonly<ImageState>;
+    /** Source image element */
+    sourceImage: Ref<HTMLImageElement | null>;
+    /** Whether the source image is loading */
+    loading: Ref<boolean>;
+    /** Error message if loading fails */
+    error: Ref<string | null>;
+    /** Registered plugins */
+    plugins: Ref<EditorPlugin[]>;
+    /** Currently active plugin ID */
+    activePluginId: Ref<string | null>;
+    /** Currently active plugin */
+    activePlugin: Ref<EditorPlugin | null>;
+    /** Whether any edits have been made */
+    hasEdits: Ref<boolean>;
+    /** History */
+    canUndo: Ref<boolean>;
+    canRedo: Ref<boolean>;
+    /** Zoom level (1 = fit to container) */
+    zoom: Ref<number>;
+    /** Editor options */
+    options: EditorOptions;
+    /** Load the source image */
+    load: (src: string | File | Blob) => Promise<void>;
+    /** Register a plugin */
+    registerPlugin: (plugin: EditorPlugin) => void;
+    /** Unregister a plugin by ID */
+    unregisterPlugin: (id: string) => void;
+    /** Set active plugin by ID */
+    setActivePlugin: (id: string) => void;
+    /** Update state and push to history */
+    updateState: (updater: (state: ImageState) => void) => void;
+    /** Undo last change */
+    undo: () => void;
+    /** Redo last undone change */
+    redo: () => void;
+    /** Revert to initial state */
+    revert: () => void;
+    /** Set zoom level */
+    setZoom: (level: number) => void;
+    /** Request a re-render of the canvas */
+    requestRender: () => void;
+    /** Render callback — set by EditorCanvas */
+    onRender: Ref<(() => void) | null>;
+    /** Temporary viewport pan during crop drag (pixels) */
+    cropDragPan: Ref<{
+        x: number;
+        y: number;
+    }>;
+}
+
+export declare interface EditorOptions {
+    /** Image source: URL, File, or Blob */
+    src: string | File | Blob;
+    /** List of plugin IDs to enable (e.g., ['crop', 'filter', 'finetune']) */
+    plugins?: string[];
+    /** Locale code */
+    locale?: 'en' | 'ar';
+    /** Text direction */
+    dir?: 'ltr' | 'rtl';
+    /** Theme: 'light' (default) or 'dark' */
+    theme?: 'dark' | 'light';
+    /** Output format */
+    outputMimeType?: 'image/jpeg' | 'image/png' | 'image/webp';
+    /** Output quality (0-1), for JPEG/WebP */
+    outputQuality?: number;
+    /** Max canvas pixels for export (iOS limit ~16M) */
+    maxCanvasPixels?: number;
+    /** Initial image state (for re-editing) */
+    initialState?: Partial<ImageState>;
+    /** Custom plugins to register in addition to built-in plugins */
+    customPlugins?: EditorPlugin[];
+}
+
+export declare interface EditorPlugin {
+    /** Unique plugin ID (e.g., 'crop', 'filter') */
+    id: string;
+    /** SVG icon as HTML string or component */
+    icon: string | Component;
+    /** Display label key (used for locale lookup) */
+    labelKey: string;
+    /** Controls component rendered in the control panel */
+    controls: Component;
+    /** Overlay component rendered on top of the canvas viewport */
+    overlay?: Component;
+    /** Called when the plugin tab is activated */
+    onActivate?: () => void;
+    /** Called when the plugin tab is deactivated */
+    onDeactivate?: () => void;
+    /** Called after the base canvas render to draw plugin-specific preview content */
+    onRender?: (context: PluginRenderContext) => void;
+}
+
+export declare const en: {
+    undo: string;
+    redo: string;
+    revert: string;
+    zoomIn: string;
+    zoomOut: string;
+    zoomToFit: string;
+    done: string;
+    cancel: string;
+    export: string;
+    close: string;
+    crop: string;
+    filter: string;
+    finetune: string;
+    sticker: string;
+    frame: string;
+    resize: string;
+    aspectRatio: string;
+    custom: string;
+    square: string;
+    landscape: string;
+    portrait: string;
+    rotation: string;
+    rotateLeft: string;
+    rotateRight: string;
+    flipHorizontal: string;
+    flipVertical: string;
+    brightness: string;
+    contrast: string;
+    saturation: string;
+    exposure: string;
+    temperature: string;
+    gamma: string;
+    clarity: string;
+    vignette: string;
+    original: string;
+    intensity: string;
+    chrome: string;
+    fade: string;
+    pastel: string;
+    cold: string;
+    warm: string;
+    mono: string;
+    noir: string;
+    wash: string;
+    stark: string;
+    sepia: string;
+    rust: string;
+    blues: string;
+    color: string;
+    solidSharp: string;
+    solidRound: string;
+    lineSingle: string;
+    lineMultiple: string;
+    hook: string;
+    polaroid: string;
+    edgeSeparate: string;
+    edgeCross: string;
+    edgeOverlap: string;
+    fill: string;
+    transparent: string;
+    emoji: string;
+    shapes: string;
+    none: string;
+    frameSize: string;
+    frameColor: string;
+    width: string;
+    height: string;
+    lockAspectRatio: string;
+    loading: string;
+    loadError: string;
+    processing: string;
+    cropApply: string;
+    unsavedChanges: string;
+    confirm: string;
+};
+
+/** Exposure adjustment matrix. v: -0.25 to 0.25 */
+export declare function exposureMatrix(v: number): number[];
+
+export declare function FillPlugin(): EditorPlugin;
+
+export declare function FilterPlugin(): EditorPlugin;
+
+declare interface FilterPreset {
+    id: string;
+    labelKey: string;
+    matrix: number[];
+}
+
+export declare const filterPresets: FilterPreset[];
+
+export declare interface FilterState {
+    /** Filter preset ID, null = no filter */
+    id: string | null;
+    /** Filter intensity 0 to 1 */
+    intensity: number;
+    /** Optional 5x4 color matrix (20 elements) */
+    matrix?: number[];
+}
+
+declare interface FinetuneEffect {
+    key: keyof FinetuneState;
+    labelKey: keyof LocaleStrings;
+    min: number;
+    max: number;
+    base: number;
+    step: number;
+}
+
+export declare const finetuneEffects: FinetuneEffect[];
+
+export declare function FinetunePlugin(): EditorPlugin;
+
+export declare interface FinetuneState {
+    brightness: number;
+    contrast: number;
+    saturation: number;
+    exposure: number;
+    temperature: number;
+    gamma: number;
+    clarity: number;
+    vignette: number;
+}
+
+export declare function FramePlugin(): EditorPlugin;
+
+export declare interface FrameState {
+    /** Frame style ID, null = no frame */
+    style: string | null;
+    /** Frame thickness as percentage of image size */
+    size: number;
+    /** RGBA color, each 0-1 */
+    color: [number, number, number, number];
+    /** Corner radius */
+    radius: number;
+}
+
+declare interface FrameStyleDef {
+    id: string;
+    labelKey: keyof LocaleStrings;
+}
+
+export declare const frameStyles: FrameStyleDef[];
+
+declare class History_2 {
+    private states;
+    private pointer;
+    private maxSize;
+    constructor(maxSize?: number);
+    /** Push a new state snapshot. Truncates any future (redo) states. */
+    push(state: ImageState): void;
+    /** Undo: return the previous state, or null if at the beginning. */
+    undo(): ImageState | null;
+    /** Redo: return the next state, or null if at the end. */
+    redo(): ImageState | null;
+    /** Reset history with a single initial state. */
+    reset(state: ImageState): void;
+    get canUndo(): boolean;
+    get canRedo(): boolean;
+    get currentIndex(): number;
+    get length(): number;
+}
+export { History_2 as History }
+
+/** Identity matrix — no transformation */
+export declare const IDENTITY_MATRIX: number[];
+
+export declare const ImageEditorModal: DefineComponent<ExtractPropTypes<__VLS_WithDefaults<__VLS_TypePropsToRuntimeProps<{
+src: string | File | Blob;
+plugins?: string[];
+locale?: "en" | "ar";
+dir?: "ltr" | "rtl";
+theme?: "dark" | "light";
+outputMimeType?: "image/jpeg" | "image/png" | "image/webp";
+outputQuality?: number;
+maxCanvasPixels?: number;
+initialState?: Partial<ImageState>;
+}>, {
+plugins: () => string[];
+locale: string;
+dir: string;
+theme: string;
+outputQuality: number;
+}>>, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {
+close: () => void;
+process: (result: ProcessResult) => void;
+}, string, PublicProps, Readonly<ExtractPropTypes<__VLS_WithDefaults<__VLS_TypePropsToRuntimeProps<{
+src: string | File | Blob;
+plugins?: string[];
+locale?: "en" | "ar";
+dir?: "ltr" | "rtl";
+theme?: "dark" | "light";
+outputMimeType?: "image/jpeg" | "image/png" | "image/webp";
+outputQuality?: number;
+maxCanvasPixels?: number;
+initialState?: Partial<ImageState>;
+}>, {
+plugins: () => string[];
+locale: string;
+dir: string;
+theme: string;
+outputQuality: number;
+}>>> & Readonly<{
+onClose?: (() => any) | undefined;
+onProcess?: ((result: ProcessResult) => any) | undefined;
+}>, {
+dir: "ltr" | "rtl";
+plugins: string[];
+locale: "en" | "ar";
+theme: "dark" | "light";
+outputQuality: number;
+}, {}, {}, {}, string, ComponentProvideOptions, true, {}, any>;
+
+export declare const ImageEditorShell: DefineComponent<ExtractPropTypes<__VLS_TypePropsToRuntimeProps_2<{
+options: EditorOptions;
+}>>, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {
+close: () => void;
+process: (result: ProcessResult) => void;
+}, string, PublicProps, Readonly<ExtractPropTypes<__VLS_TypePropsToRuntimeProps_2<{
+options: EditorOptions;
+}>>> & Readonly<{
+onClose?: (() => any) | undefined;
+onProcess?: ((result: ProcessResult) => any) | undefined;
+}>, {}, {}, {}, {}, string, ComponentProvideOptions, true, {}, any>;
+
+export declare class ImageProcessor {
+    /**
+     * Process image at FULL RESOLUTION.
+     * Applies all transformations and exports as Blob.
+     */
+    process(source: HTMLImageElement, state: ImageState, options?: ProcessOptions): Promise<ProcessResult>;
+}
+
+export declare interface ImageState {
+    crop: CropState;
+    finetune: FinetuneState;
+    filter: FilterState;
+    stickers: StickerInstance[];
+    frame: FrameState;
+    resize: ResizeState;
+    backgroundColor: [number, number, number, number];
+}
+
+export declare function install(app: App): void;
+
+/**
+ * Load images from various sources into an HTMLImageElement.
+ * Handles URL strings, File objects, Blobs, and EXIF orientation.
+ */
+export declare function loadImage(src: string | File | Blob): Promise<HTMLImageElement>;
+
+export declare const LOCALE_KEY: InjectionKey<(key: string) => string>;
+
+export declare type LocaleStrings = typeof en;
+
+/**
+ * Create a full ImageState from a partial state, filling in defaults.
+ */
+export declare function mergeWithDefaults(partial: Partial<ImageState>): ImageState;
+
+/** Multiply two 5x4 matrices (treating them as 5x5 with implicit last row [0,0,0,0,1]) */
+export declare function multiplyMatrices(a: number[], b: number[]): number[];
+
+export declare interface PluginRenderContext {
+    /** Canvas 2D rendering context */
+    ctx: CanvasRenderingContext2D;
+    /** Current editor state */
+    state: ImageState;
+    /** Image display rect in canvas pixels */
+    imageRect: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+}
+
+declare interface ProcessOptions {
+    mimeType?: string;
+    quality?: number;
+    maxCanvasPixels?: number;
+}
+
+export declare interface ProcessResult {
+    /** The processed image as a Blob */
+    blob: Blob;
+    /** The final image state (serializable for persistence) */
+    imageState: ImageState;
+}
+
+export declare function ResizePlugin(): EditorPlugin;
+
+export declare interface ResizeState {
+    width?: number;
+    height?: number;
+    fit: 'contain' | 'cover' | 'force';
+    upscale: boolean;
+}
+
+/** Saturation adjustment matrix. v: -0.25 to 0.25 */
+export declare function saturationMatrix(v: number): number[];
+
+/**
+ * Serialize editor state to a JSON string.
+ * Safe to store in localStorage, a database, or send over network.
+ */
+export declare function serializeState(state: ImageState): string;
+
+declare interface StickerCategory {
+    id: string;
+    labelKey: string;
+    stickers: string[];
+}
+
+export declare interface StickerInstance {
+    id: string;
+    /** URL, data URI, or emoji character */
+    src: string;
+    /** Normalized 0-1 position */
+    x: number;
+    y: number;
+    /** Normalized 0-1 size */
+    width: number;
+    height: number;
+    /** Rotation in radians */
+    rotation: number;
+    flipX: boolean;
+    flipY: boolean;
+    opacity: number;
+}
+
+export declare function StickerPlugin(): EditorPlugin;
+
+/** Temperature adjustment matrix. v: -0.25 to 0.25 (positive = warmer, negative = cooler) */
+export declare function temperatureMatrix(v: number): number[];
+
+export declare function useEditor(): EditorEngine;
+
+declare interface ViewportTransform {
+    zoom: number;
+    panX: number;
+    panY: number;
+}
+
+export { }