annotate-image 2.0.0-beta.1

package/package.json

@@ -0,0 +1,117 @@
+{
+  "name": "annotate-image",
+  "version": "2.0.0-beta.1",
+  "description": "Create Flickr-like comment annotations on images — draw rectangles, add notes, save via AJAX or static data",
+  "license": "GPL-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/flipbit/jquery-image-annotate.git"
+  },
+  "files": [
+    "dist/",
+    "LICENSE",
+    "README.md"
+  ],
+  "main": "dist/core.js",
+  "types": "dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/core.js",
+      "default": "./dist/core.min.js"
+    },
+    "./jquery": {
+      "types": "./dist/types/jquery.annotate.d.ts",
+      "import": "./dist/jquery.js",
+      "default": "./dist/jquery.min.js"
+    },
+    "./react": {
+      "types": "./dist/types/react.d.ts",
+      "import": "./dist/react.js"
+    },
+    "./vue": {
+      "types": "./dist/types/vue.d.ts",
+      "import": "./dist/vue.js"
+    },
+    "./css": "./dist/css/annotate.min.css"
+  },
+  "scripts": {
+    "clean": "rm -rf dist",
+    "build:dirs": "mkdir -p dist/css dist/types",
+    "build:check": "tsc --noEmit",
+    "build:types": "tsc --emitDeclarationOnly --noEmit false --declaration --declarationDir dist/types --outDir dist/types",
+    "build:core": "esbuild src/index.ts --bundle --format=esm --outfile=dist/core.js",
+    "build:core:iife": "esbuild src/index.ts --bundle --minify --format=iife --global-name=AnnotateImage --outfile=dist/core.min.js",
+    "build:jquery": "esbuild src/jquery.annotate.ts --bundle --format=esm --external:jquery --outfile=dist/jquery.js",
+    "build:jquery:iife": "esbuild src/jquery.annotate.ts --bundle --minify --external:jquery --outfile=dist/jquery.min.js",
+    "build:react": "esbuild src/react.tsx --bundle --format=esm --external:react --external:react-dom --outfile=dist/react.js",
+    "build:vue": "esbuild src/vue.ts --bundle --format=esm --external:vue --outfile=dist/vue.js",
+    "build:css": "esbuild src/annotation.css --minify --outfile=dist/css/annotate.min.css",
+    "build": "npm run clean && npm run build:dirs && npm run build:check && npm run build:types && npm run build:core && npm run build:core:iife && npm run build:jquery && npm run build:jquery:iife && npm run build:react && npm run build:vue && npm run build:css",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:jquery4": "npm install jquery@4 --no-save && vitest run; STATUS=$?; npm install --no-save; exit $STATUS",
+    "test:e2e": "npx playwright test --config e2e/playwright.config.ts",
+    "lint": "eslint src/ test/",
+    "lint:fix": "eslint --fix src/ test/",
+    "format": "prettier --write 'src/**/*.{ts,css}' 'test/**/*.ts' '*.{js,ts,json}'",
+    "format:check": "prettier --check 'src/**/*.{ts,css}' 'test/**/*.ts' '*.{js,ts,json}'",
+    "demo": "npm run build && concurrently -k \"npm:demo:watch:*\" \"npm:demo:serve\"",
+    "demo:watch:core": "esbuild src/index.ts --bundle --format=esm --outfile=dist/core.js --watch",
+    "demo:watch:core-min": "esbuild src/index.ts --bundle --minify --format=iife --global-name=AnnotateImage --outfile=dist/core.min.js --watch",
+    "demo:watch:jquery": "esbuild src/jquery.annotate.ts --bundle --format=esm --external:jquery --outfile=dist/jquery.js --watch",
+    "demo:watch:jquery-min": "esbuild src/jquery.annotate.ts --bundle --minify --external:jquery --outfile=dist/jquery.min.js --watch",
+    "demo:watch:react": "esbuild src/react.tsx --bundle --format=esm --external:react --external:react-dom --outfile=dist/react.js --watch",
+    "demo:watch:vue": "esbuild src/vue.ts --bundle --format=esm --external:vue --outfile=dist/vue.js --watch",
+    "demo:watch:css": "esbuild src/annotation.css --minify --outfile=dist/css/annotate.min.css --watch",
+    "demo:serve": "live-server --port=8080 --open=demo/index.html --watch=dist,demo",
+    "demo:ci": "npm run build && concurrently -k \"npm:demo:watch:*\" \"npm:demo:serve:ci\"",
+    "demo:serve:ci": "live-server --port=8080 --no-browser --watch=dist,demo"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.2",
+    "@playwright/test": "^1.58.2",
+    "@testing-library/dom": "^10.4.1",
+    "@testing-library/react": "^16.3.2",
+    "@types/jquery": "^3.5.33",
+    "@types/react": "^18.3.28",
+    "@types/react-dom": "^18.3.7",
+    "@vue/test-utils": "^2.4.6",
+    "concurrently": "^9.2.1",
+    "esbuild": "^0.27.3",
+    "eslint": "^9.39.2",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-react-hooks": "^7.0.1",
+    "eslint-plugin-vue": "^10.8.0",
+    "jquery": "^3.7.1",
+    "jsdom": "^28.0.0",
+    "live-server": "^1.2.2",
+    "prettier": "^3.8.1",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.55.0",
+    "vitest": "^4.0.18",
+    "vue": "^3.5.28"
+  },
+  "peerDependencies": {
+    "jquery": ">=3.7.0",
+    "react": ">=18.0.0",
+    "react-dom": ">=18.0.0",
+    "vue": ">=3.3.0"
+  },
+  "peerDependenciesMeta": {
+    "jquery": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    },
+    "vue": {
+      "optional": true
+    }
+  }
+}

package/readme.md

@@ -0,0 +1,389 @@
+# Annotate Image
+
+A JavaScript image annotation plugin that creates Flickr-like comment annotations on images. Users can draw rectangular regions on images, add text notes, and persist annotations via callbacks or AJAX.
+
+Works standalone (vanilla JS), or with jQuery, React, or Vue. Framework adapters are tree-shakeable — only the one you import gets bundled.
+
+## Installation
+
+```sh
+npm install annotate-image
+```
+
+jQuery, React, and Vue are optional peer dependencies. Install only what you use:
+
+```sh
+# For jQuery projects
+npm install jquery
+
+# For React projects
+npm install react react-dom
+
+# For Vue projects
+npm install vue
+```
+
+## Usage
+
+### Vanilla JS
+
+```html
+<link rel="stylesheet" href="dist/css/annotate.min.css">
+<script src="dist/core.min.js"></script>
+```
+
+```js
+const instance = AnnotateImage.annotate(document.getElementById('myImage'), {
+  editable: true,
+  notes: [
+    { top: 286, left: 161, width: 52, height: 37,
+      text: 'Small people on the steps',
+      id: 'note-1', editable: false },
+    { top: 134, left: 179, width: 68, height: 74,
+      text: 'National Gallery Dome',
+      id: 'note-2', editable: true },
+  ],
+  onChange(notes) { console.log('Notes changed:', notes); },
+});
+
+// Programmatic control
+instance.add();              // Enter add-note mode
+instance.getNotes();         // Get current annotations
+instance.clear();            // Remove all annotations
+instance.destroy();          // Tear down completely
+```
+
+### ES Modules
+
+```js
+import { annotate } from 'annotate-image';
+import 'annotate-image/css';
+
+const instance = annotate(document.getElementById('myImage'), {
+  editable: true,
+  notes: [],
+});
+```
+
+### jQuery
+
+```html
+<link rel="stylesheet" href="dist/css/annotate.min.css">
+<script src="https://code.jquery.com/jquery-3.7.1.min.js"></script>
+<script src="dist/jquery.min.js"></script>
+```
+
+```js
+$(function() {
+  $('#myImage').annotateImage({
+    editable: true,
+    notes: [/* ... */],
+  });
+});
+
+// Destroy
+$('#myImage').annotateImage('destroy');
+```
+
+Or as an ES module:
+
+```js
+import 'annotate-image/jquery';
+import 'annotate-image/css';
+```
+
+### React
+
+```tsx
+import { useRef } from 'react';
+import { AnnotateImage } from 'annotate-image/react';
+import type { AnnotateImageRef } from 'annotate-image/react';
+import 'annotate-image/css';
+
+function App() {
+  const ref = useRef<AnnotateImageRef>(null);
+
+  return (
+    <>
+      <AnnotateImage
+        ref={ref}
+        src="/photo.jpg"
+        width={800}
+        height={600}
+        editable
+        notes={[]}
+        onChange={(notes) => console.log(notes)}
+        onSave={(note) => console.log('Saved:', note)}
+        onDelete={(note) => console.log('Deleted:', note)}
+      />
+      <button onClick={() => ref.current?.add()}>Add Note</button>
+      <button onClick={() => console.log(ref.current?.getNotes())}>
+        Get Notes
+      </button>
+    </>
+  );
+}
+```
+
+### Vue
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { AnnotateImage } from 'annotate-image/vue';
+import 'annotate-image/css';
+
+const annotator = ref();
+</script>
+
+<template>
+  <AnnotateImage
+    ref="annotator"
+    src="/photo.jpg"
+    :width="800"
+    :height="600"
+    editable
+    :notes="[]"
+    @change="(notes) => console.log(notes)"
+    @save="(note) => console.log('Saved:', note)"
+    @delete="(note) => console.log('Deleted:', note)"
+  />
+  <button @click="annotator?.add()">Add Note</button>
+  <button @click="console.log(annotator?.getNotes())">Get Notes</button>
+</template>
+```
+
+## API Reference
+
+### Core: `annotate(img, options?)`
+
+Creates an annotation layer on an image element. Returns an `AnnotateImage` instance.
+
+#### Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `editable` | `boolean` | `true` | Enable annotation editing |
+| `notes` | `AnnotationNote[]` | `[]` | Initial annotations |
+| `api` | `AnnotateApi` | — | Server persistence (see below) |
+| `onChange` | `(notes: NoteData[]) => void` | — | Called after any notes mutation |
+| `onSave` | `(note: NoteData) => void` | — | Called after a note is saved |
+| `onDelete` | `(note: NoteData) => void` | — | Called after a note is deleted |
+| `onLoad` | `(notes: NoteData[]) => void` | — | Called after notes are loaded |
+| `onError` | `(ctx: AnnotateErrorContext) => void` | — | Called on API errors (defaults to `console.error`) |
+
+#### `AnnotateApi`
+
+Each field accepts a URL string (default fetch behavior) or a function for full control. Omit `api` entirely for static-only mode.
+
+```typescript
+{
+  load?: string | (() => Promise<AnnotationNote[]>),
+  save?: string | ((note: NoteData) => Promise<SaveResult>),
+  delete?: string | ((note: NoteData) => Promise<void>),
+}
+```
+
+#### Instance Methods
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `add()` | `boolean` | Enter add-note mode. Returns false if already editing. |
+| `clear()` | `void` | Remove all annotations. |
+| `destroy()` | `void` | Tear down completely. Idempotent. |
+| `getNotes()` | `NoteData[]` | Current annotations (internal fields stripped). |
+| `load()` | `void` | Rebuild views from the current notes array. |
+
+#### Data Types
+
+```typescript
+// Full annotation (includes internal fields)
+interface AnnotationNote {
+  id: string;
+  top: number;
+  left: number;
+  width: number;
+  height: number;
+  text: string;
+  editable: boolean;
+}
+
+// Annotation data passed to callbacks (no internal fields)
+type NoteData = Omit<AnnotationNote, 'view' | 'editable'>;
+```
+
+### React: `<AnnotateImage>`
+
+#### Props (`AnnotateImageProps`)
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `src` | `string` | — | Image URL (required) |
+| `width` | `number` | — | Image width in pixels |
+| `height` | `number` | — | Image height in pixels |
+| `notes` | `AnnotationNote[]` | `[]` | Initial annotations |
+| `editable` | `boolean` | `true` | Enable editing |
+| `onChange` | `(notes: NoteData[]) => void` | — | Notes changed |
+| `onSave` | `(note: NoteData) => void` | — | Note saved |
+| `onDelete` | `(note: NoteData) => void` | — | Note deleted |
+| `onLoad` | `(notes: NoteData[]) => void` | — | Notes loaded |
+| `onError` | `(ctx: AnnotateErrorContext) => void` | — | Error occurred |
+
+#### Ref Methods (`AnnotateImageRef`)
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `add()` | `void` | Enter add-note mode |
+| `clear()` | `void` | Remove all annotations |
+| `destroy()` | `void` | Tear down the instance |
+| `getNotes()` | `NoteData[]` | Get current annotations |
+
+### Vue: `<AnnotateImage>`
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `src` | `String` | — | Image URL (required) |
+| `width` | `Number` | — | Image width in pixels |
+| `height` | `Number` | — | Image height in pixels |
+| `notes` | `AnnotationNote[]` | — | Initial annotations |
+| `editable` | `Boolean` | `true` | Enable editing |
+
+#### Emits
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `change` | `NoteData[]` | Notes changed |
+| `save` | `NoteData` | Note saved |
+| `delete` | `NoteData` | Note deleted |
+| `load` | `NoteData[]` | Notes loaded |
+| `error` | `AnnotateErrorContext` | Error occurred |
+
+#### Exposed Methods (via template ref)
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `add()` | `void` | Enter add-note mode |
+| `clear()` | `void` | Remove all annotations |
+| `destroy()` | `void` | Tear down the instance |
+| `getNotes()` | `NoteData[]` | Get current annotations |
+| `notes` | `Ref<NoteData[]>` | Reactive current notes |
+
+## Tree Shaking
+
+Each entry point (`annotate-image`, `annotate-image/jquery`, `annotate-image/react`, `annotate-image/vue`) is a separate bundle. Importing one does not pull in the others. Unused framework adapters are excluded automatically by bundlers that support package `exports`.
+
+## Error Handling
+
+The `onError` callback receives a context object:
+
+```typescript
+interface AnnotateErrorContext {
+  type: 'load' | 'save' | 'delete';
+  error: Error;
+  note?: AnnotationNote;
+}
+```
+
+If no `onError` callback is provided, errors are logged to the console.
+
+## Accessibility
+
+The plugin supports keyboard navigation:
+
+- **Tab** to navigate between annotation areas and controls
+- **Enter/Space** to activate buttons and open editable annotations
+- **Escape** to cancel editing
+- Annotation areas and buttons have `role="button"` and `tabindex` attributes
+- Focus is managed automatically when entering/exiting edit mode
+- Visible focus styles on all interactive elements
+
+## Demos
+
+Run the demo server locally:
+
+```sh
+npm run demo
+```
+
+This opens a browser at `http://localhost:8080/demo/index.html` with links to demos including static annotations, AJAX loading, vanilla JS, React, Vue, and multiple instances.
+
+## Build
+
+```sh
+npm install
+npm run build        # Type-check, bundle, minify
+npm run build:check  # Type-check only
+npm test             # Run tests
+npm run test:jquery4 # Run tests against jQuery 4
+```
+
+### Build Output
+
+`dist/` contains the built artifacts:
+
+- `dist/core.js` — Core library (ESM, no dependencies)
+- `dist/core.min.js` — Core library (IIFE, minified, `AnnotateImage` global)
+- `dist/jquery.js` — jQuery adapter (ESM, jQuery external)
+- `dist/jquery.min.js` — jQuery adapter (IIFE, minified, jQuery external)
+- `dist/react.js` — React component (ESM, React external)
+- `dist/vue.js` — Vue component (ESM, Vue external)
+- `dist/css/annotate.min.css` — Minified styles
+- `dist/types/` — TypeScript declaration files
+
+## Browser Compatibility
+
+All modern browsers (Chrome, Firefox, Safari, Edge). The plugin uses pointer events and `fetch`, so IE is not supported.
+
+## History
+
+### Version 2.0
+
+* Package renamed from `jquery-image-annotate` to `annotate-image`
+* Rewritten in TypeScript with vanilla DOM internals
+* Removed jQuery UI dependency — drag/resize uses vanilla pointer events
+* Added core vanilla JS API (`annotate()` factory) that works without jQuery
+* jQuery adapter is now a thin wrapper registering `$.fn.annotateImage`
+* Added React 18+ and Vue 3+ framework components
+* Lifecycle callbacks: `onChange`, `onSave`, `onDelete`, `onLoad`
+* `getNotes()` method for reading current annotations
+* Replaced `$.ajax`/`$.getJSON` with `fetch`
+* Build system replaced: Bower/Grunt removed in favor of npm/esbuild
+* Added ESM and IIFE bundle outputs with TypeScript declarations
+* Supports jQuery 3.x and 4.x
+* Keyboard accessibility for all interactive elements
+* Full test suite using Vitest
+
+### Version 1.4 — 19th January, 2011
+* Upgraded jQuery to version 1.7.1
+
+### Version 1.3 — 22nd June, 2009
+* Fixed a bug when creating a new annotation via AJAX.
+* The Id of the annotation is expected to be returned as a JSON object from the response of the save call, e.g.
+
+    `{ "annotation_id": "000001" }`
+
+### Version 1.2 — 24th April, 2009
+* Fixed jQuery UI 1.3.2 compatibility.
+* Forked source for jQuery 1.2.x and 1.3.x
+* Notes now fade in/out.
+* Tidied up CSS/positioning.
+
+### Version 1.1 — 2nd April, 2009
+* Fixed bug when annotating an image with no previous annotations.
+
+### Version 1.0 — 11th March, 2009
+* Initial release
+
+## Credits
+
+Based on the Drupal extension:
+
+Image Annotations by Ronan Berder
+hunvreus@gmail.com
+http://drupal.org/project/image_annotate
+
+## Licence
+
+Released under the [GNU GPL v2](LICENSE) license.