@markerjs/markerjs3 3.6.2 → 3.6.4

package/LICENSE

@@ -1,25 +1,25 @@
-marker.js 3 Linkware License
-
-Copyright (c) 2024 Alan Mendelevich
-
-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:
-
-1. The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-2. Link back to the Software website displayed during operation of the Software
-or an equivalent prominent public attribution must be retained. Alternative 
-commercial licenses can be obtained to remove this clause.
-
-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
+marker.js 3 Linkware License
+
+Copyright (c) 2024 Alan Mendelevich
+
+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:
+
+1. The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+2. Link back to the Software website displayed during operation of the Software
+or an equivalent prominent public attribution must be retained. Alternative 
+commercial licenses can be obtained to remove this clause.
+
+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/README.md

@@ -1,106 +1,106 @@
-# marker.js 3 — Add image annotation to your web apps
-
-marker.js 3 is a JavaScript browser library to enable image annotation in your web applications. Add marker.js 3 to your web app and enable users to annotate and mark up images. You can save, share or otherwise process the results.
-
-## Installation
-
-```bash
-npm install @markerjs/markerjs3
-```
-
-The library includes TypeScript type definitions out of the box.
-
-## Usage
-
-marker.js 3 is a "headless" library. In this case "headless" means that it doesn't come with any toolbars, property editors, and placement preconceptions. This way the library focuses on the core features you need, and you can make it feel totally native in the application you are building without resorting to any tricks or hacks.
-
-With that out of the way, here are the simplest usage scenarios...
-
-### MarkerArea (The Editor)
-
-Import `MarkerArea` from `@markerjs/markerjs3`:
-
-```js
-import { MarkerArea } from '@markerjs/markerjs3';
-```
-
-In the code below we assume that you have an `HTMLImageElement` as `targetImage`. It can be a reference to an image you already have on the page or you can simply create it with something like this:
-
-```js
-const targetImg = document.createElement('img');
-targetImg.src = './sample.jpg';
-```
-
-Now you just need to create an instance of `MarkerArea`, set its `targetImage` property and add it to the page:
-
-```js
-const markerArea = new MarkerArea();
-markerArea.targetImage = targetImg;
-editorContainerDiv.appendChild(markerArea);
-```
-
-To initiate creation of a marker you just call `createMarker()` and pass it the name (or type) of the marker you want to create. So, if you have a button with id `addFrameButton` you can make it create a new `FrameMarker` with something like this:
-
-```js
-document.querySelector('#addButton')?.addEventListener('click', () => {
-  markerArea.createMarker('FrameMarker');
-});
-```
-
-And whenever you want to save state (current annotation) you just call `getState()`:
-
-```js
-document.querySelector('#saveStateButton')?.addEventListener('click', () => {
-  const state = markerArea.getState();
-  console.log(state);
-});
-```
-
-### Rendering static images
-
-To render the annotation as a static image you use `Renderer`.
-
-```js
-import { MarkerArea, Renderer } from '@markerjs/markerjs3';
-```
-
-Just create an instance of it and pass the annotation state to the `rasterize()` method:
-
-```js
-const renderer = new Renderer();
-renderer.targetImage = targetImg;
-const dataUrl = await renderer.rasterize(markerArea.getState());
-
-const img = document.createElement('img');
-img.src = dataUrl;
-
-someDiv.appendChild(img);
-```
-
-### MarkerView (The Viewer)
-
-To show dynamic annotation overlays on top of the original image you use `MarkerView`.
-
-```js
-import { MarkerView } from '@markerjs/markerjs3';
-
-const markerView = new MarkerView();
-markerView.targetImage = targetImg;
-viewerContainer.appendChild(markerView);
-
-markerView.show(savedState);
-```
-
-## Demos
-
-Check out the [demos on markerjs.com](https://markerjs.com/demos).
-
-## More docs and tutorials
-
-You can find marker.js 3 reference and tutorials [here](https://markerjs.com/docs-v3/).
-
-## License
-
-Linkware (see [LICENSE](https://github.com/ailon/markerjs3/blob/master/LICENSE) for details) - the UI displays a small link back to the marker.js 3 website which should be retained.
-
-Alternative licenses are available through the [marker.js website](https://markerjs.com).
+# marker.js 3 — Add image annotation to your web apps
+
+marker.js 3 is a JavaScript browser library to enable image annotation in your web applications. Add marker.js 3 to your web app and enable users to annotate and mark up images. You can save, share or otherwise process the results.
+
+## Installation
+
+```bash
+npm install @markerjs/markerjs3
+```
+
+The library includes TypeScript type definitions out of the box.
+
+## Usage
+
+marker.js 3 is a "headless" library. In this case "headless" means that it doesn't come with any toolbars, property editors, and placement preconceptions. This way the library focuses on the core features you need, and you can make it feel totally native in the application you are building without resorting to any tricks or hacks.
+
+With that out of the way, here are the simplest usage scenarios...
+
+### MarkerArea (The Editor)
+
+Import `MarkerArea` from `@markerjs/markerjs3`:
+
+```js
+import { MarkerArea } from '@markerjs/markerjs3';
+```
+
+In the code below we assume that you have an `HTMLImageElement` as `targetImage`. It can be a reference to an image you already have on the page or you can simply create it with something like this:
+
+```js
+const targetImg = document.createElement('img');
+targetImg.src = './sample.jpg';
+```
+
+Now you just need to create an instance of `MarkerArea`, set its `targetImage` property and add it to the page:
+
+```js
+const markerArea = new MarkerArea();
+markerArea.targetImage = targetImg;
+editorContainerDiv.appendChild(markerArea);
+```
+
+To initiate creation of a marker you just call `createMarker()` and pass it the name (or type) of the marker you want to create. So, if you have a button with id `addFrameButton` you can make it create a new `FrameMarker` with something like this:
+
+```js
+document.querySelector('#addButton')?.addEventListener('click', () => {
+  markerArea.createMarker('FrameMarker');
+});
+```
+
+And whenever you want to save state (current annotation) you just call `getState()`:
+
+```js
+document.querySelector('#saveStateButton')?.addEventListener('click', () => {
+  const state = markerArea.getState();
+  console.log(state);
+});
+```
+
+### Rendering static images
+
+To render the annotation as a static image you use `Renderer`.
+
+```js
+import { MarkerArea, Renderer } from '@markerjs/markerjs3';
+```
+
+Just create an instance of it and pass the annotation state to the `rasterize()` method:
+
+```js
+const renderer = new Renderer();
+renderer.targetImage = targetImg;
+const dataUrl = await renderer.rasterize(markerArea.getState());
+
+const img = document.createElement('img');
+img.src = dataUrl;
+
+someDiv.appendChild(img);
+```
+
+### MarkerView (The Viewer)
+
+To show dynamic annotation overlays on top of the original image you use `MarkerView`.
+
+```js
+import { MarkerView } from '@markerjs/markerjs3';
+
+const markerView = new MarkerView();
+markerView.targetImage = targetImg;
+viewerContainer.appendChild(markerView);
+
+markerView.show(savedState);
+```
+
+## Demos
+
+Check out the [demos on markerjs.com](https://markerjs.com/demos).
+
+## More docs and tutorials
+
+You can find marker.js 3 reference and tutorials [here](https://markerjs.com/docs-v3/).
+
+## License
+
+Linkware (see [LICENSE](https://github.com/ailon/markerjs3/blob/master/LICENSE) for details) - the UI displays a small link back to the marker.js 3 website which should be retained.
+
+Alternative licenses are available through the [marker.js website](https://markerjs.com).

package/markerjs3.d.ts

@@ -1948,58 +1948,139 @@ declare class MarkerBaseEditor<TMarkerType extends MarkerBase = MarkerBase> {
 
 /**
  * Marker area custom event types.
+ *
+ * @summary
+ * Defines the custom events that can be dispatched by the {@link MarkerArea} component.
+ *
+ * @remarks
+ * The `MarkerAreaEventMap` interface defines the events that can be dispatched by the {@link MarkerArea} component.
+ *
+ * You can listen to these events using the {@link MarkerArea.addEventListener | addEventListener} method on the {@link MarkerArea} instance.
+ *
+ * The events can be logically grouped into two categories:
+ * 1. Marker area events (start with `area`)
+ * 2. Marker editor events (start with `marker`).
+ *
+ * The marker area events are related to the overall state of the {@link MarkerArea} component,
+ * while the marker editor events are related to the individual marker editors within the area.
+ *
+ * Marker area events receive {@link MarkerAreaEventData} as their `event.detail`,
+ * while marker editor events receive {@link MarkerEditorEventData} as their `event.detail`.
+ * Both event data types contain a reference to the {@link MarkerArea} instance
+ * and, for marker editor events, a reference to the specific marker editor that triggered the event.
  */
 interface MarkerAreaEventMap {
     /**
      * Marker area initialized.
+     *
+     * @remarks
+     * This event is dispatched early in the lifecycle when the {@link MarkerArea} component is initialized
+     * but none of its internal elements have been created yet.
+     *
+     * Use {@link areashow} to know when the component is fully initialized and ready to be used.
      */
     areainit: CustomEvent<MarkerAreaEventData>;
     /**
      * Marker area shown.
+     *
+     * @remarks
+     * This event is dispatched when the {@link MarkerArea} component is fully initialized and ready to be used.
      */
     areashow: CustomEvent<MarkerAreaEventData>;
     /**
      * Marker area state restored.
+     *
+     * @remarks
+     * This event is dispatched when the {@link MarkerArea} component restores its state from
+     * a previously saved state.
      */
     arearestorestate: CustomEvent<MarkerAreaEventData>;
     /**
      * Marker area focused.
+     *
+     * @remarks
+     * This event is dispatched when the {@link MarkerArea} component receives focus.
      */
     areafocus: CustomEvent<MarkerAreaEventData>;
     /**
      * Marker area lost focus.
+     *
+     * @remarks
+     * This event is dispatched when the {@link MarkerArea} component loses focus.
      */
     areablur: CustomEvent<MarkerAreaEventData>;
     /**
      * Marker area state changed.
+     *
+     * @remarks
+     * This event is dispatched when the {@link MarkerArea} component's state changes.
+     *
+     * This is a good place to implement auto-saving or update the UI based on the current state.
      */
     areastatechange: CustomEvent<MarkerAreaEventData>;
     /**
      * Marker selected.
+     *
+     * @remarks
+     * This event is dispatched when a marker editor is selected.
+     * You can use this event to update the UI or perform actions based on the selected marker editor.
      */
     markerselect: CustomEvent<MarkerEditorEventData>;
     /**
      * Marker deselected.
+     *
+     * @remarks
+     * This event is dispatched when a marker editor is deselected.
+     * You can use this event to update the UI or perform actions based on the deselected marker editor.
      */
     markerdeselect: CustomEvent<MarkerEditorEventData>;
     /**
      * Marker creating.
+     *
+     * @remarks
+     * This event is dispatched when a marker creation has been initiated.
+     * You can use this event to update the UI or perform actions based on the marker creation process.
      */
     markercreating: CustomEvent<MarkerEditorEventData>;
     /**
      * Marker created.
+     *
+     * @remarks
+     * This event is dispatched when a marker has been created.
+     * You can use this event to update the UI or perform actions based on the created marker editor.
+     *
+     * One common use case is implementing continuous marker creation,
+     * where you create a new marker editor immediately after the previous one has been created.
+     *
+     * @example
+     * ```js
+     * // create another marker of the same type
+     * markerArea.addEventListener("markercreate", (ev) => {
+     *   markerArea.createMarker(ev.detail.markerEditor.marker.typeName);
+     * });
+     * ```
      */
     markercreate: CustomEvent<MarkerEditorEventData>;
     /**
      * Marker about to be deleted.
+     *
+     * @remarks
+     * This event is dispatched before a marker editor is deleted.
      */
     markerbeforedelete: CustomEvent<MarkerEditorEventData>;
     /**
      * Marker deleted.
+     *
+     * @remarks
+     * This event is dispatched after a marker editor is deleted.
+     * You can use this event to update the UI or perform actions based on the deleted marker editor.
      */
     markerdelete: CustomEvent<MarkerEditorEventData>;
     /**
      * Marker changed.
+     *
+     * @remarks
+     * This event is dispatched when a marker editor's state has changed.
      */
     markerchange: CustomEvent<MarkerEditorEventData>;
 }
@@ -2827,7 +2908,7 @@ declare class TextBlockEditor {
      * Returns editor's UI,
      * @returns UI in a div element.
      */
-    getEditorUi(): HTMLDivElement;
+    getEditorUi(): HTMLTextAreaElement;
     /**
      * Focuses text editing in the editor.
      */
@@ -2969,47 +3050,102 @@ declare class CurveMarkerEditor<TMarkerType extends CurveMarker = CurveMarker> e
 }
 
 /**
- * Event map for {@link MarkerView}.
+ * Marker view custom event types.
+ *
+ * @summary
+ * Defines the custom events that can be dispatched by the {@link MarkerView} component.
+ *
+ * @remarks
+ * The `MarkerViewEventMap` interface defines the events that can be dispatched by the {@link MarkerView} component.
+ *
+ * You can listen to these events using the {@link MarkerView.addEventListener | addEventListener} method on the {@link MarkerView} instance.
+ *
+ * The events can be logically grouped into two categories:
+ * 1. Marker view events (start with `view`)
+ * 2. Marker events (start with `marker`).
+ *
+ * The marker view events are related to the overall state of the {@link MarkerView} component,
+ * while the marker events are related to the individual markers within the view.
+ *
+ * Marker view events receive {@link MarkerViewEventData} as their `event.detail`,
+ * while marker events receive {@link MarkerEventData} as their `event.detail`.
+ * Both event data types contain a reference to the {@link MarkerView} instance
+ * and, for marker events, a reference to the specific marker that triggered the event.
  */
 interface MarkerViewEventMap {
     /**
      * Viewer initialized.
+     *
+     * @remarks
+     * This event is dispatched when the {@link MarkerView} instance is created and initialized
+     * but none of its internal elements have been created yet.
      */
     viewinit: CustomEvent<MarkerViewEventData>;
     /**
      * Viewer shown.
+     *
+     * @remarks
+     * This event is dispatched when the {@link MarkerView} instance is fully initialized,
+     * its internal elements are created, and the target image is loaded.
+     * It indicates that the viewer is ready to display markers and annotations.
      */
     viewshow: CustomEvent<MarkerViewEventData>;
     /**
      * Viewer state restored.
+     *
+     * @remarks
+     * This event is dispatched when the {@link MarkerView} instance has restored a previously saved state.
+     * It indicates that the viewer has loaded markers and annotations from a saved state.
      */
     viewrestorestate: CustomEvent<MarkerViewEventData>;
     /**
      * Marker clicked.
+     *
+     * @remarks
+     * This event is dispatched when a marker within the {@link MarkerView} is clicked.
+     * It provides access to the clicked marker and the {@link MarkerView} instance.
      */
     markerclick: CustomEvent<MarkerEventData>;
     /**
      * Marker mouse over.
+     *
+     * @remarks
+     * This event is dispatched when the mouse pointer hovers over a marker within the {@link MarkerView}.
      */
     markerover: CustomEvent<MarkerEventData>;
     /**
      * Marker pointer down.
+     *
+     * @remarks
+     * This event is dispatched when a pointer (mouse, touch, etc.) is pressed down on a marker within the {@link MarkerView}.
      */
     markerpointerdown: CustomEvent<MarkerEventData>;
     /**
      * Marker pointer move.
+     *
+     * @remarks
+     * This event is dispatched when a pointer (mouse, touch, etc.) moves while over a marker within the {@link MarkerView}.
      */
     markerpointermove: CustomEvent<MarkerEventData>;
     /**
      * Marker pointer up.
+     *
+     * @remarks
+     * This event is dispatched when a pointer (mouse, touch, etc.) is released after being pressed down on a marker within the {@link MarkerView}.
      */
     markerpointerup: CustomEvent<MarkerEventData>;
     /**
      * Marker pointer enter.
+     *
+     * @remarks
+     * This event is dispatched when a pointer (mouse, touch, etc.) enters the area of a marker within the {@link MarkerView}.
      */
     markerpointerenter: CustomEvent<MarkerEventData>;
     /**
      * Marker pointer leave.
+     *
+     * @remarks
+     * This event is dispatched when a pointer (mouse, touch, etc.) leaves the area of a marker within the {@link MarkerView}.
      */
     markerpointerleave: CustomEvent<MarkerEventData>;
 }