annotate-image 2.0.0-beta.1

package/dist/types/annotate-edit.d.ts

@@ -0,0 +1,29 @@
+import type { AnnotationNote } from './types';
+import type { AnnotateImage } from './annotate-image';
+import { AnnotateView } from './annotate-view';
+/**
+ * Edit mode controller for a single annotation.
+ *
+ * Creates a draggable/resizable area with a text form, and handles
+ * save, delete, and cancel actions through the parent AnnotateImage.
+ */
+export declare class AnnotateEdit {
+    readonly image: AnnotateImage;
+    readonly area: HTMLElement;
+    readonly form: HTMLDivElement;
+    readonly textarea: HTMLTextAreaElement;
+    note: AnnotationNote;
+    private handlers;
+    private busy;
+    /**
+     * @param image - The parent AnnotateImage controller.
+     * @param note - Existing note to edit, or omit to create a new annotation.
+     * @param existingView - The view being edited (for updates); omit for new annotations.
+     */
+    constructor(image: AnnotateImage, note?: AnnotationNote, existingView?: AnnotateView);
+    /** Tear down the edit form and interaction handlers. */
+    destroy(): void;
+    private addSaveButton;
+    private addDeleteButton;
+    private addCancelButton;
+}

package/dist/types/annotate-image.d.ts

@@ -0,0 +1,70 @@
+import type { AnnotationNote, AnnotateImageOptions, AnnotateApi, NormalizedApi, NoteData, InteractionHandlers, AnnotateErrorContext } from './types';
+import { AnnotateEdit } from './annotate-edit';
+/** Strip internal fields (view, editable) before passing to callbacks. */
+export declare function stripInternals(note: AnnotationNote): NoteData;
+/** Normalize api config: convert string URLs to default fetch functions. */
+export declare function normalizeApi(api: AnnotateApi): NormalizedApi;
+/**
+ * Core annotation controller for a single image.
+ *
+ * Wraps the target image in a canvas overlay, manages annotation views
+ * and edit mode, and coordinates persistence through the configured API.
+ */
+export declare class AnnotateImage {
+    readonly img: HTMLImageElement;
+    readonly canvas: HTMLDivElement;
+    readonly viewOverlay: HTMLDivElement;
+    readonly editOverlay: HTMLDivElement;
+    button: HTMLButtonElement | undefined;
+    notes: AnnotationNote[];
+    private _mode;
+    options: AnnotateImageOptions;
+    /** Normalized transport API — all functions, no strings. */
+    api: NormalizedApi;
+    handlers: InteractionHandlers;
+    activeEdit: AnnotateEdit | null;
+    private destroyed;
+    /**
+     * @param img - Image element to annotate. Must be in the DOM with non-zero dimensions.
+     * @param options - Plugin configuration.
+     */
+    constructor(img: HTMLImageElement, options: AnnotateImageOptions);
+    /** Current interaction mode — 'view' for browsing, 'edit' when an annotation is being created or modified. */
+    get mode(): 'view' | 'edit';
+    /** Switch between view and edit mode, toggling overlay visibility. */
+    setMode(newMode: 'view' | 'edit'): void;
+    /** Return current notes with internal fields stripped. */
+    getNotes(): NoteData[];
+    /** @internal Notify that the notes collection changed. */
+    notifyChange(): void;
+    /** @internal Notify that a note was saved, then fire onChange. */
+    notifySave(note: NoteData): void;
+    /** @internal Notify that a note was deleted, then fire onChange. */
+    notifyDelete(note: NoteData): void;
+    /** @internal Notify that notes were loaded, then fire onChange. */
+    notifyLoad(): void;
+    private destroyViews;
+    private createViews;
+    /** Rebuild annotation views from the current notes array. */
+    load(): void;
+    /** Remove all annotations and their views. */
+    clear(): void;
+    /** Tear down the plugin: remove canvas, restore the original image. Idempotent. */
+    destroy(): void;
+    /** Cancel the active edit (if any) and return to view mode. */
+    cancelEdit(): void;
+    /** Replace all annotations with new data. Does not fire lifecycle callbacks. */
+    setNotes(notes: AnnotationNote[]): void;
+    /** Toggle editing mode. Creates or removes Add Note button and rebuilds views. Does not fire lifecycle callbacks. */
+    setEditable(editable: boolean): void;
+    private createButton;
+    /** Report an API error via the onError callback, or log to console if none configured. */
+    reportError(context: AnnotateErrorContext): void;
+    /** Load annotations from the server via api.load. */
+    private loadFromApi;
+    /**
+     * Enter edit mode to create a new annotation.
+     * @returns true if edit mode was entered, false if already editing.
+     */
+    add(): boolean;
+}

package/dist/types/annotate-view.d.ts

@@ -0,0 +1,43 @@
+import type { AnnotationNote } from './types';
+import type { AnnotateImage } from './annotate-image';
+/** Read position from inline styles (jsdom has no layout engine). */
+export declare function readInlinePosition(el: HTMLElement): {
+    left: number;
+    top: number;
+};
+/** Read dimensions from inline styles, falling back to offsetWidth/offsetHeight. */
+export declare function readInlineSize(el: HTMLElement): {
+    width: number;
+    height: number;
+};
+/**
+ * Renders a single annotation as a positioned area with a hover tooltip.
+ * Editable annotations support click-to-edit to open the edit form.
+ */
+export declare class AnnotateView {
+    readonly image: AnnotateImage;
+    readonly area: HTMLDivElement;
+    readonly tooltip: HTMLDivElement;
+    note: AnnotationNote;
+    editable: boolean;
+    /**
+     * @param image - The parent AnnotateImage controller.
+     * @param note - Annotation data to display.
+     */
+    constructor(image: AnnotateImage, note: AnnotationNote);
+    /** Apply the note's position and dimensions to the area element. */
+    setPosition(): void;
+    /** Update the view's position, size, and text from the edit area after a save. */
+    resetPosition(editable: {
+        area: HTMLElement;
+        note: AnnotationNote;
+    }, text: string): void;
+    /** Show the tooltip and apply hover styling. */
+    show(): void;
+    /** Hide the tooltip and remove hover styling. */
+    hide(): void;
+    /** Remove the annotation's DOM elements. */
+    destroy(): void;
+    /** Open the edit form for this annotation (only if in view mode). */
+    edit(): void;
+}

package/dist/types/index.d.ts

@@ -0,0 +1,16 @@
+import { AnnotateImage } from './annotate-image';
+import { DEFAULT_LABELS } from './types';
+import type { AnnotationNote, AnnotateImageOptions, AnnotateApi, AnnotateErrorContext, SaveResult, NoteData, Labels } from './types';
+export { AnnotateImage, DEFAULT_LABELS };
+export type { AnnotationNote, AnnotateImageOptions, AnnotateApi, AnnotateErrorContext, SaveResult, NoteData, Labels };
+/**
+ * Create an annotation layer on an image element.
+ *
+ * The image must already be loaded and have non-zero dimensions.
+ * Returns the AnnotateImage instance that manages the annotation lifecycle.
+ *
+ * @param img - The image element to annotate. Must be in the DOM with non-zero dimensions.
+ * @param options - Plugin configuration (editable, notes, api callbacks, etc.).
+ * @returns The AnnotateImage instance.
+ */
+export declare function annotate(img: HTMLImageElement, options?: Partial<AnnotateImageOptions>): AnnotateImage;

package/dist/types/interactions.d.ts

@@ -0,0 +1,7 @@
+import type { DragCallbacks, ResizeCallbacks, InteractionHandlers } from './types';
+export declare function makeDraggable(el: HTMLElement, opts: DragCallbacks): void;
+export declare function destroyDraggable(el: HTMLElement): void;
+export declare function makeResizable(el: HTMLElement, opts: ResizeCallbacks): void;
+export declare function destroyResizable(el: HTMLElement): void;
+/** Returns an InteractionHandlers object using vanilla pointer events. */
+export declare function createDefaultHandlers(): InteractionHandlers;

package/dist/types/jquery.annotate.d.ts

@@ -0,0 +1,6 @@
+import type { AnnotateImageOptions } from './types';
+declare global {
+    interface JQuery {
+        annotateImage(optionsOrMethod?: Partial<AnnotateImageOptions> | string): this;
+    }
+}

package/dist/types/react.d.ts

@@ -0,0 +1,43 @@
+import type { AnnotationNote, NoteData, AnnotateErrorContext } from './types';
+/** Props for the AnnotateImage React component. */
+export interface AnnotateImageProps {
+    /** Image source URL. */
+    src: string;
+    /** Image width in pixels. Required if image may not be loaded yet. */
+    width?: number;
+    /** Image height in pixels. Required if image may not be loaded yet. */
+    height?: number;
+    /** Image alt text for accessibility. */
+    alt?: string;
+    /** Annotations to render. */
+    notes?: AnnotationNote[];
+    /** Enable annotation editing. Default: true. */
+    editable?: boolean;
+    /** Called after any notes mutation. */
+    onChange?: (notes: NoteData[]) => void;
+    /** Called after a note is saved (new or edited). */
+    onSave?: (note: NoteData) => void;
+    /** Called after a note is deleted. */
+    onDelete?: (note: NoteData) => void;
+    /** Called after notes are loaded. */
+    onLoad?: (notes: NoteData[]) => void;
+    /** Called when an operation fails. */
+    onError?: (context: AnnotateErrorContext) => void;
+}
+/** Imperative methods exposed via ref. */
+export interface AnnotateImageRef {
+    /** Enter add-note mode. */
+    add(): void;
+    /** Remove all annotations. */
+    clear(): void;
+    /** Return current annotations (internal fields stripped). */
+    getNotes(): NoteData[];
+}
+/**
+ * React component for image annotation.
+ * Wraps the vanilla AnnotateImage core with reactive state and event callbacks.
+ *
+ * @remarks SSR-safe — renders a plain `<img>` on the server. DOM manipulation
+ * only runs in useEffect (client-side).
+ */
+export declare const AnnotateImage: import("react").ForwardRefExoticComponent<AnnotateImageProps & import("react").RefAttributes<AnnotateImageRef>>;

package/dist/types/types.d.ts

@@ -0,0 +1,119 @@
+import type { AnnotateView } from './annotate-view';
+export interface AnnotationNote {
+    id: string;
+    top: number;
+    left: number;
+    width: number;
+    height: number;
+    text: string;
+    editable: boolean;
+    view?: AnnotateView;
+}
+/** Response from a save operation. */
+export interface SaveResult {
+    annotation_id?: string;
+}
+/**
+ * Per-note data passed to save/delete callbacks.
+ * AnnotationNote without internal fields (view, editable).
+ */
+export type NoteData = Omit<AnnotationNote, 'view' | 'editable'>;
+export interface AnnotateErrorContext {
+    type: 'load' | 'save' | 'delete';
+    error: Error;
+    note?: AnnotationNote;
+}
+/** Transport configuration for server persistence. */
+export interface AnnotateApi {
+    /**
+     * Load annotations from the server.
+     * - String: GET request to this URL, expects AnnotationNote[] JSON response.
+     * - Function: called on init, must resolve with the annotations array.
+     */
+    load?: string | (() => Promise<AnnotationNote[]>);
+    /**
+     * Persist an annotation to the server.
+     * - String: POST request to this URL with JSON body, expects SaveResult response.
+     * - Function: called with note data, must resolve with SaveResult on success.
+     */
+    save?: string | ((note: NoteData) => Promise<SaveResult>);
+    /**
+     * Delete an annotation from the server.
+     * - String: POST request to this URL with JSON body.
+     * - Function: called with note data, must resolve on success.
+     */
+    delete?: string | ((note: NoteData) => Promise<void>);
+}
+/** Normalized transport — all functions, no strings. Used internally. */
+export interface NormalizedApi {
+    load?: () => Promise<AnnotationNote[]>;
+    save?: (note: NoteData) => Promise<SaveResult>;
+    delete?: (note: NoteData) => Promise<void>;
+}
+/** Configurable UI labels. All fields optional; missing fields use defaults. */
+export interface Labels {
+    /** "Add Note" button text and tooltip. Default: "Add Note". */
+    addNote?: string;
+    /** Save button text. Default: "OK". */
+    save?: string;
+    /** Delete button text. Default: "Delete". */
+    delete?: string;
+    /** Cancel button text. Default: "Cancel". */
+    cancel?: string;
+    /** Textarea placeholder text. Default: "" (no placeholder). */
+    placeholder?: string;
+}
+/** Built-in defaults for all UI labels. */
+export declare const DEFAULT_LABELS: Required<Labels>;
+export interface AnnotateImageOptions {
+    /** Enable annotation editing. Default: true. */
+    editable: boolean;
+    /** Static annotation data to render on init. Default: []. */
+    notes: AnnotationNote[];
+    /** Server persistence configuration. Omit for static-only mode. */
+    api?: AnnotateApi;
+    /** Called when a load/save/delete operation fails. */
+    onError?: (context: AnnotateErrorContext) => void;
+    /** Called after any notes mutation (load, save, delete, clear). */
+    onChange?: (notes: NoteData[]) => void;
+    /** Called after a note is saved (new or edited). */
+    onSave?: (note: NoteData) => void;
+    /** Called after a note is deleted. */
+    onDelete?: (note: NoteData) => void;
+    /** Called after notes are loaded (initial or via api.load). */
+    onLoad?: (notes: NoteData[]) => void;
+    /** UI label overrides. Missing fields use built-in defaults. */
+    labels?: Labels;
+}
+export interface DragCallbacks {
+    containment?: HTMLElement;
+    onDrag?: (pos: {
+        left: number;
+        top: number;
+    }) => void;
+    onStop?: (pos: {
+        left: number;
+        top: number;
+    }) => void;
+}
+export interface ResizeCallbacks {
+    containment?: HTMLElement;
+    onResize?: (rect: {
+        left: number;
+        top: number;
+        width: number;
+        height: number;
+    }) => void;
+    onStop?: (rect: {
+        left: number;
+        top: number;
+        width: number;
+        height: number;
+    }) => void;
+}
+export interface InteractionHandlers {
+    makeDraggable: (el: HTMLElement, opts: DragCallbacks) => void;
+    makeResizable: (el: HTMLElement, opts: ResizeCallbacks) => void;
+    destroyDraggable: (el: HTMLElement) => void;
+    destroyResizable: (el: HTMLElement) => void;
+}

package/dist/types/vue.d.ts

@@ -0,0 +1,79 @@
+import type { AnnotationNote, NoteData, AnnotateErrorContext } from './types';
+/**
+ * Vue component for image annotation.
+ * Wraps the vanilla AnnotateImage core with reactive state and Vue events.
+ *
+ * @remarks SSR-safe — renders a plain `<img>` on the server. DOM manipulation
+ * only runs in onMounted (client-side).
+ */
+export declare const AnnotateImage: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
+    /** Image source URL. */
+    src: {
+        type: StringConstructor;
+        required: true;
+    };
+    /** Image width in pixels. Required if image may not be loaded yet. */
+    width: {
+        type: NumberConstructor;
+    };
+    /** Image height in pixels. Required if image may not be loaded yet. */
+    height: {
+        type: NumberConstructor;
+    };
+    /** Image alt text for accessibility. */
+    alt: {
+        type: StringConstructor;
+    };
+    /** Annotations to render. */
+    notes: {
+        type: () => AnnotationNote[];
+    };
+    /** Enable annotation editing. Default: true. */
+    editable: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+}>, () => import("vue").VNode<import("vue").RendererNode, import("vue").RendererElement, {
+    [key: string]: any;
+}>, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    save: (_note: NoteData) => true;
+    delete: (_note: NoteData) => true;
+    load: (_notes: NoteData[]) => true;
+    change: (_notes: NoteData[]) => true;
+    error: (_context: AnnotateErrorContext) => true;
+}, string, import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<{
+    /** Image source URL. */
+    src: {
+        type: StringConstructor;
+        required: true;
+    };
+    /** Image width in pixels. Required if image may not be loaded yet. */
+    width: {
+        type: NumberConstructor;
+    };
+    /** Image height in pixels. Required if image may not be loaded yet. */
+    height: {
+        type: NumberConstructor;
+    };
+    /** Image alt text for accessibility. */
+    alt: {
+        type: StringConstructor;
+    };
+    /** Annotations to render. */
+    notes: {
+        type: () => AnnotationNote[];
+    };
+    /** Enable annotation editing. Default: true. */
+    editable: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+}>> & Readonly<{
+    onChange?: ((_notes: NoteData[]) => any) | undefined;
+    onError?: ((_context: AnnotateErrorContext) => any) | undefined;
+    onLoad?: ((_notes: NoteData[]) => any) | undefined;
+    onSave?: ((_note: NoteData) => any) | undefined;
+    onDelete?: ((_note: NoteData) => any) | undefined;
+}>, {
+    editable: boolean;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;