@nextcloud/image-editor 1.0.0-beta.1

package/dist/index.d.ts

@@ -0,0 +1,233 @@
+import { ComponentOptionsMixin } from 'vue';
+import { ComponentProvideOptions } from 'vue';
+import { ComputedRef } from 'vue';
+import { DefineComponent } from 'vue';
+import { PublicProps } from 'vue';
+
+declare type __VLS_Props = {
+    /** Image to edit: Blob, File or URL */
+    src: Blob | string;
+    /** Accessible label of the canvas area */
+    label?: string;
+    /**
+     * Format, quality and size bound for the save button. Defaults to
+     * PNG at natural resolution, which is lossless but large: a host
+     * saving over a photo will want its source format instead.
+     */
+    exportOptions?: ExportOptions;
+    /**
+     * State to open with, as emitted by the change event, for resuming
+     * an edit that was not finished. Read when the source loads, so
+     * changing it later has no effect until the source changes too.
+     */
+    initialState?: EditorState;
+};
+
+/** All values range from -100 to 100, 0 meaning unchanged */
+export declare interface Adjustments {
+    brightness: number;
+    contrast: number;
+    saturation: number;
+}
+
+export declare type Annotation = DrawAnnotation | ArrowAnnotation | BoxAnnotation | TextAnnotation | RedactAnnotation;
+
+export declare interface ArrowAnnotation {
+    id: string;
+    type: 'arrow';
+    /** [fromX, fromY, toX, toY] in oriented image coordinates */
+    points: [number, number, number, number];
+    color: string;
+    strokeWidth: number;
+}
+
+export declare interface BoxAnnotation {
+    id: string;
+    type: 'rectangle' | 'ellipse';
+    /** The shape's local frame: rotation pivots on the rect's top-left */
+    rect: Rect;
+    /** Clockwise degrees around the rect's top-left corner */
+    rotation: number;
+    color: string;
+    strokeWidth: number;
+}
+
+/**
+ * A pristine edit state: nothing rotated, cropped, adjusted or annotated.
+ */
+export declare function createInitialState(): EditorState;
+
+export declare interface DrawAnnotation {
+    id: string;
+    type: 'draw';
+    /** Flat [x1, y1, x2, y2, …] polyline in oriented image coordinates */
+    points: number[];
+    color: string;
+    strokeWidth: number;
+}
+
+export declare interface EditorState {
+    rotation: Rotation;
+    /** Additional free rotation in degrees, -45 to 45 */
+    fineRotation: number;
+    /** Center zoom factor, 1 or greater */
+    zoom: number;
+    flipX: boolean;
+    flipY: boolean;
+    /** Crop rectangle in oriented image coordinates, null meaning uncropped */
+    crop: Rect | null;
+    adjustments: Adjustments;
+    preset: FilterPreset;
+    annotations: Annotation[];
+}
+
+/**
+ * SPDX-FileCopyrightText: 2026 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+export declare interface ExportOptions {
+    /** Target MIME type, defaults to 'image/png' */
+    format?: 'image/png' | 'image/jpeg' | 'image/webp';
+    /** Encoder quality between 0 and 1, only for lossy formats */
+    quality?: number;
+    /** Bound the longest output edge, never upscaling */
+    maxSize?: number;
+}
+
+export declare interface ExportResult {
+    blob: Blob;
+    width: number;
+    height: number;
+    mimeType: string;
+}
+
+export declare type FilterPreset = 'none' | 'grayscale' | 'noir' | 'luna' | 'sepia' | 'fade' | 'warm' | 'cool' | 'golden' | 'coast' | 'mist' | 'berry' | 'cinema' | 'invert' | 'solarize' | 'posterize' | 'pop';
+
+declare interface HistoryEntry<T> {
+    /** The recorded state */
+    snapshot: T;
+    /**
+     * What the user did to get here, already translated. Undefined for
+     * a step whose call site did not name it.
+     */
+    label?: string;
+}
+
+export declare const ImageEditor: DefineComponent<__VLS_Props, {
+exportImage: (options?: ExportOptions) => Promise<ExportResult>;
+/**
+* Start over, optionally from a given state.
+*
+* @param state state to reset to, defaulting to a pristine one
+*/
+reset: (state?: EditorState) => void;
+}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {
+cancel: () => any;
+change: (state: EditorState) => any;
+error: (error: Error) => any;
+save: (result: ExportResult) => any;
+}, string, PublicProps, Readonly<__VLS_Props> & Readonly<{
+onCancel?: (() => any) | undefined;
+onChange?: ((state: EditorState) => any) | undefined;
+onError?: ((error: Error) => any) | undefined;
+onSave?: ((result: ExportResult) => any) | undefined;
+}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {
+container: HTMLDivElement;
+}, HTMLDivElement>;
+
+/**
+ * Whether a state carries no edit at all, matching a fresh one from
+ * createInitialState. Consumers can use it for a dirty check, and the
+ * editor uses it to hand an untouched image back as it came in.
+ *
+ * @param state the state to inspect
+ */
+export declare function isPristine(state: EditorState): boolean;
+
+export declare interface Rect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+
+export declare interface RedactAnnotation {
+    id: string;
+    type: 'redact';
+    /** Region to obfuscate, in oriented image coordinates */
+    rect: Rect;
+    /** How the region is destroyed */
+    style: 'pixelate' | 'blur';
+}
+
+/**
+ * SPDX-FileCopyrightText: 2026 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+export declare type Rotation = 0 | 90 | 180 | 270;
+
+export declare interface Size {
+    width: number;
+    height: number;
+}
+
+export declare interface TextAnnotation {
+    id: string;
+    type: 'text' | 'sticker';
+    x: number;
+    y: number;
+    /** Text content, or the emoji character for stickers */
+    text: string;
+    color: string;
+    fontSize: number;
+    /** Clockwise degrees around the anchor */
+    rotation: number;
+}
+
+export declare interface UseHistory<T> {
+    /** Whether an older snapshot is available */
+    canUndo: ComputedRef<boolean>;
+    /** Whether a newer snapshot is available */
+    canRedo: ComputedRef<boolean>;
+    /** The active snapshot, undefined while the history is empty */
+    current: ComputedRef<T | undefined>;
+    /** Every recorded step, oldest first */
+    entries: ComputedRef<readonly HistoryEntry<T>[]>;
+    /** Position of the active step in entries, -1 while empty */
+    index: ComputedRef<number>;
+    /**
+     * Append a snapshot after the active one, discarding any redoable
+     * entries.
+     *
+     * @param snapshot the state to record
+     * @param label what the user did, for a history list
+     */
+    push(snapshot: T, label?: string): void;
+    /** Move back one snapshot and return it, or undefined at the oldest entry */
+    undo(): T | undefined;
+    /** Move forward one snapshot and return it, or undefined at the newest entry */
+    redo(): T | undefined;
+    /**
+     * Move to an arbitrary step and return its snapshot, or undefined
+     * where there is no such step or it is the active one already.
+     *
+     * @param target position in entries
+     */
+    jumpTo(target: number): T | undefined;
+    /** Drop all snapshots */
+    clear(): void;
+}
+
+/**
+ * Linear undo/redo history of immutable state snapshots.
+ *
+ * Snapshots are treated as opaque immutable values. Whatever is pushed
+ * must not be mutated afterwards, or the history it sits in changes
+ * under the caller; pushing a reference to a value the caller keeps
+ * building new versions of is fine, and cheaper than copying.
+ *
+ * @param capacity maximum number of snapshots kept, oldest dropped first
+ */
+export declare function useHistory<T>(capacity?: number): UseHistory<T>;
+
+export { }