@markerjs/markerjs3 3.0.0-alpha.4 → 3.0.0-beta.1

package/README.md

@@ -1,10 +1,10 @@
 # marker.js 3 — Add image annotation to your web apps
 
-> **Note**: marker.js 3 is in the early pre-release stage of its lifecycle and will have many additions and breaking changes before the official 3.0 release.
+> **Note**: marker.js 3 is in the pre-release stage of its lifecycle and will have many additions and, potentially, breaking changes before the official 3.0 release.
 >
 > If you need a stable image annotation library, consider using [marker.js 2](https://markerjs.com) for now.
 
-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 instantly enable users to annotate and mark up images. You can save, share or otherwise process the results.
+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
 
@@ -12,7 +12,7 @@ marker.js 3 is a JavaScript browser library to enable image annotation in your w
 npm install @markerjs/markerjs3
 ```
 
-or 
+or
 
 ```
 yarn add @markerjs/markerjs3
@@ -20,17 +20,99 @@ yarn add @markerjs/markerjs3
 
 ## Usage
 
-*coming soon...*
+Unlike the previous version, marker.js 3 is a "headless" (sort of) 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
 
-*coming soon...*
+Check out the "work-in-progress" demo [here](https://github.com/ailon/markerjs3-wip-demo). It covers most of the available features with no extra bells or whistles.
+
+While it's made with React it is purposefully light on React-specific stuff and "best practices" to just focus on marker.js 3 related things.
+
+_more demos coming soon..._
 
 ## More docs and tutorials
 
-*coming soon...*
+_coming soon..._
 
 ## 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).
+Alternative licenses are available through the [marker.js website](https://markerjs.com).

package/markerjs3.d.ts

@@ -236,6 +236,14 @@ declare class MarkerBase {
      * @param scaleY - vertical scale
      */
     scale(scaleX: number, scaleY: number): void;
+    /**
+     * Returns markers bounding box.
+     *
+     * Override to return a custom bounding box.
+     *
+     * @returns rectangle fitting the marker.
+     */
+    getBBox(): DOMRect;
 }
 
 /**
@@ -357,6 +365,7 @@ declare class RectangularBoxMarkerBase extends MarkerBase {
      * @param scaleY - vertical scale
      */
     scale(scaleX: number, scaleY: number): void;
+    getBBox(): DOMRect;
 }
 
 declare class ShapeOutlineMarkerBase extends RectangularBoxMarkerBase {
@@ -403,8 +412,7 @@ interface ShapeMarkerBaseState extends ShapeOutlineMarkerBaseState {
 declare abstract class ShapeMarkerBase extends ShapeOutlineMarkerBase {
     static title: string;
     protected _fillColor: string;
-    get fillColor(): string;
-    set fillColor(value: string);
+    protected applyFillColor(): void;
     constructor(container: SVGGElement);
     createVisual(): void;
     /**
@@ -861,7 +869,7 @@ declare class TextMarker extends RectangularBoxMarkerBase {
     /**
      * Text padding from the bounding box.
      */
-    protected padding: number;
+    padding: number;
     /**
      * Text's bounding box where text should fit and/or be anchored to.
      */
@@ -879,6 +887,7 @@ declare class TextMarker extends RectangularBoxMarkerBase {
      * Sets (adjusts) the stencil's size.
      */
     setSize(): void;
+    protected setSizeFromTextSize(): void;
     private textSizeChanged;
     /**
      * Sets the text color.
@@ -949,6 +958,11 @@ declare class CalloutMarker extends TextMarker {
     private tipBase2Position;
     private _calloutVisual;
     constructor(container: SVGGElement);
+    protected applyStrokeColor(): void;
+    protected applyStrokeWidth(): void;
+    protected applyStrokeDasharray(): void;
+    protected applyOpacity(): void;
+    protected applyFillColor(): void;
     protected getPath(): string;
     private setTipPoints;
     createVisual(): void;
@@ -987,6 +1001,139 @@ declare class EllipseMarker extends ShapeMarkerBase {
     getState(): ShapeMarkerBaseState;
 }
 
+type ImageType = 'svg' | 'bitmap';
+/**
+ * Represents image marker's state.
+ */
+interface ImageMarkerBaseState extends RectangularBoxMarkerBaseState {
+    imageType?: ImageType;
+    svgString?: string;
+    imageSrc?: string;
+}
+
+declare class ImageMarkerBase extends RectangularBoxMarkerBase {
+    static title: string;
+    /**
+     * Main SVG or image element of the stencil.
+     */
+    protected SVGImage?: SVGSVGElement | SVGImageElement;
+    protected imageType: ImageType;
+    protected _svgString?: string;
+    get svgString(): string | undefined;
+    set svgString(value: string | undefined);
+    protected _imageSrc?: string;
+    get imageSrc(): string | undefined;
+    set imageSrc(value: string | undefined);
+    /**
+     * Natural (real) width of the image.
+     */
+    protected naturalWidth: number;
+    /**
+     * Natural (real) height of the image.
+     */
+    protected naturalHeight: number;
+    constructor(container: SVGGElement);
+    protected createImage(): void;
+    createVisual(): void;
+    adjustImage(): void;
+    private isDescendant;
+    ownsTarget(el: EventTarget): boolean;
+    setSize(): void;
+    getState(): ImageMarkerBaseState;
+    protected applyStrokeColor(): void;
+    restoreState(state: ImageMarkerBaseState): void;
+    /**
+     * Scales marker. Used after the image resize.
+     *
+     * @param scaleX - horizontal scale
+     * @param scaleY - vertical scale
+     */
+    scale(scaleX: number, scaleY: number): void;
+}
+
+/**
+ * Used to represent user-set images.
+ */
+declare class CustomImageMarker extends ImageMarkerBase {
+    /**
+     * String type name of the marker type.
+     */
+    static typeName: string;
+    /**
+     * Marker type title (display name) used for accessibility and other attributes.
+     */
+    static title: string;
+}
+
+/**
+ * Check mark marker.
+ */
+declare class CheckImageMarker extends ImageMarkerBase {
+    /**
+     * String type name of the marker type.
+     */
+    static typeName: string;
+    /**
+     * Marker type title (display name) used for accessibility and other attributes.
+     */
+    static title: string;
+    constructor(container: SVGGElement);
+}
+
+/**
+ * X mark marker.
+ */
+declare class XImageMarker extends ImageMarkerBase {
+    /**
+     * String type name of the marker type.
+     */
+    static typeName: string;
+    /**
+     * Marker type title (display name) used for accessibility and other attributes.
+     */
+    static title: string;
+    constructor(container: SVGGElement);
+}
+
+interface CaptionFrameMarkerState extends TextMarkerState, ShapeMarkerBaseState {
+}
+
+declare class CaptionFrameMarker extends TextMarker {
+    static typeName: string;
+    static title: string;
+    private _outerFrameVisual;
+    private _captionFrameVisual;
+    private _frameVisual;
+    constructor(container: SVGGElement);
+    protected applyStrokeColor(): void;
+    protected applyStrokeWidth(): void;
+    protected applyStrokeDasharray(): void;
+    protected applyOpacity(): void;
+    protected applyFillColor(): void;
+    protected getPaths(width?: number, height?: number): {
+        frame: string;
+        caption: string;
+    };
+    createVisual(): void;
+    adjustVisual(): void;
+    protected adjustTextPosition(): void;
+    protected adjustFrameVisual(): void;
+    ownsTarget(el: EventTarget): boolean;
+    setSize(): void;
+    protected setSizeFromTextSize(): void;
+    hideVisual(): void;
+    showVisual(): void;
+    getState(): CaptionFrameMarkerState;
+    restoreState(state: MarkerBaseState): void;
+    /**
+     * Scales marker. Used after the image resize.
+     *
+     * @param scaleX - horizontal scale
+     * @param scaleY - vertical scale
+     */
+    scale(scaleX: number, scaleY: number): void;
+}
+
 interface MarkerEditorProperties<TMarkerType extends MarkerBase = MarkerBase> {
     /**
      * SVG container for the marker and editor elements.
@@ -1252,6 +1399,8 @@ declare class MarkerArea extends HTMLElement {
     private hideOutline;
     private onPointerUp;
     private finishMarqueeSelection;
+    private adjustMarqueeSelectOutline;
+    private hideMarqueeSelectOutline;
     private onPointerOut;
     private onKeyUp;
     private attachEvents;
@@ -1727,9 +1876,127 @@ declare class FreehandMarkerEditor<TMarkerType extends FreehandMarker = Freehand
     deselect(): void;
 }
 
+/**
+ * Text changed event handler type.
+ */
+type TextChangedHandler = (text: string) => void;
+type BlurHandler = () => void;
+/**
+ * Represents a text block editor element.
+ */
+declare class TextBlockEditor {
+    private textEditor;
+    private isInFocus;
+    private _width;
+    /**
+     * Returns editor width in pixels.
+     */
+    get width(): number;
+    /**
+     * Sets editor width in pixels.
+     */
+    set width(value: number);
+    private _height;
+    /**
+     * Returns editor height in pixels.
+     */
+    get height(): number;
+    /**
+     * Sets editor height in pixels.
+     */
+    set height(value: number);
+    private _left;
+    /**
+     * Returns the horizontal (X) location of the editor's left corner (in pixels).
+     */
+    get left(): number;
+    /**
+     * Sets the horizontal (X) location of the editor's left corner (in pixels).
+     */
+    set left(value: number);
+    private _top;
+    /**
+     * Returns the vertical (Y) location of the editor's top left corner (in pixels).
+     */
+    get top(): number;
+    /**
+     * Sets the vertical (Y) location of the editor's top left corner (in pixels).
+     */
+    set top(value: number);
+    private _text;
+    /**
+     * Returns the text block text.
+     */
+    get text(): string;
+    /**
+     * Sets the text block text.
+     */
+    set text(value: string);
+    private _fontFamily;
+    /**
+     * Returns text block's font family.
+     */
+    get fontFamily(): string;
+    /**
+     * Sets the text block's font family.
+     */
+    set fontFamily(value: string);
+    private _fontSize;
+    /**
+     * Returns text block's font size.
+     */
+    get fontSize(): string;
+    /**
+     * Sets text block's font size.
+     */
+    set fontSize(value: string);
+    private _textColor;
+    /**
+     * Returns text block's font color.
+     */
+    get textColor(): string;
+    /**
+     * Returns text block's font color.
+     */
+    set textColor(value: string);
+    private _bgColor;
+    get bgColor(): string;
+    set bgColor(value: string);
+    /**
+     * Text changed event handler.
+     */
+    onTextChanged?: TextChangedHandler;
+    onBlur?: BlurHandler;
+    /**
+     * Creates a new text block editor instance.
+     */
+    constructor();
+    private isSetupCompleted;
+    private setup;
+    /**
+     * Returns editor's UI,
+     * @returns UI in a div element.
+     */
+    getEditorUi(): HTMLDivElement;
+    /**
+     * Focuses text editing in the editor.
+     */
+    focus(): void;
+    /**
+     * Unfocuses the editor.
+     */
+    blur(): void;
+}
+
 declare class TextMarkerEditor<TMarkerType extends TextMarker = TextMarker> extends RectangularBoxMarkerBaseEditor<TMarkerType> {
-    private textBlockEditorContainer;
-    private textBlockEditor;
+    protected textBlockEditorContainer: SVGForeignObjectElement;
+    protected textBlockEditor: TextBlockEditor;
+    set color(color: string);
+    get color(): string;
+    set fontFamily(font: string);
+    get fontFamily(): string;
+    set fontSize(size: FontSize);
+    get fontSize(): FontSize;
     constructor(properties: MarkerEditorProperties<TMarkerType>);
     private _pointerDownTime;
     private _pointerDownPoint;
@@ -1777,6 +2044,29 @@ declare class CalloutMarkerEditor<TMarkerType extends CalloutMarker = CalloutMar
     protected resize(point: IPoint): void;
 }
 
+declare class ImageMarkerEditor<TMarkerType extends ImageMarkerBase = ImageMarkerBase> extends RectangularBoxMarkerBaseEditor<TMarkerType> {
+    constructor(properties: MarkerEditorProperties<TMarkerType>);
+    /**
+     * Handles pointer (mouse, touch, stylus, etc.) down event.
+     *
+     * @param point - event coordinates.
+     * @param target - direct event target element.
+     */
+    pointerDown(point: IPoint, target?: EventTarget): void;
+    /**
+     * Handles pointer (mouse, touch, stylus, etc.) up event.
+     *
+     * @param point - event coordinates.
+     * @param target - direct event target element.
+     */
+    pointerUp(point: IPoint): void;
+}
+
+declare class CaptionFrameMarkerEditor<TMarkerType extends CaptionFrameMarker = CaptionFrameMarker> extends TextMarkerEditor<TMarkerType> {
+    constructor(properties: MarkerEditorProperties<TMarkerType>);
+    protected setSize(): void;
+}
+
 interface MarkerViewEventMap {
     /**
      * Viewer initialized.
@@ -1858,6 +2148,7 @@ declare class MarkerView extends HTMLElement {
 declare class Renderer {
     private _mainCanvas?;
     private _editingTarget?;
+    private _renderHelperContainer?;
     private _targetWidth;
     get targetWidth(): number;
     set targetWidth(value: number);
@@ -1916,4 +2207,4 @@ declare class Renderer {
     rasterize(state: AnnotationState, targetCanvas?: HTMLCanvasElement): Promise<string>;
 }
 
-export { type AnnotationState, ArrowMarker, ArrowMarkerEditor, type ArrowMarkerState, type ArrowType, CalloutMarker, CalloutMarkerEditor, type CalloutMarkerState, type ColorType, CoverMarker, EllipseFrameMarker, EllipseMarker, FrameMarker, FreehandMarker, FreehandMarkerEditor, type FreehandMarkerState, Grip, HighlightMarker, type IPoint, LineMarker, LinearMarkerBase, type LinearMarkerBaseState, LinearMarkerEditor, MarkerArea, type MarkerAreaEventData, type MarkerAreaEventMap, MarkerBase, MarkerBaseEditor, type MarkerBaseState, type MarkerEditorProperties, type MarkerEditorState, MarkerView, type MarkerViewEventData, type MarkerViewEventMap, MeasurementMarker, PolygonMarker, PolygonMarkerEditor, type PolygonMarkerState, RectangularBoxMarkerBase, type RectangularBoxMarkerBaseState, Renderer, ResizeGrip, RotateGrip, ShapeMarkerBase, type ShapeMarkerBaseState, ShapeMarkerEditor, ShapeOutlineMarkerBase, type ShapeOutlineMarkerBaseState, ShapeOutlineMarkerEditor, SvgHelper, TextMarker, TextMarkerEditor, type TextMarkerState };
+export { type AnnotationState, ArrowMarker, ArrowMarkerEditor, type ArrowMarkerState, type ArrowType, CalloutMarker, CalloutMarkerEditor, type CalloutMarkerState, CaptionFrameMarker, CaptionFrameMarkerEditor, type CaptionFrameMarkerState, CheckImageMarker, type ColorType, CoverMarker, CustomImageMarker, EllipseFrameMarker, EllipseMarker, type FontSize, FrameMarker, FreehandMarker, FreehandMarkerEditor, type FreehandMarkerState, Grip, HighlightMarker, type IPoint, ImageMarkerBase, type ImageMarkerBaseState, ImageMarkerEditor, type ImageType, LineMarker, LinearMarkerBase, type LinearMarkerBaseState, LinearMarkerEditor, MarkerArea, type MarkerAreaEventData, type MarkerAreaEventMap, MarkerBase, MarkerBaseEditor, type MarkerBaseState, type MarkerEditorProperties, type MarkerEditorState, MarkerView, type MarkerViewEventData, type MarkerViewEventMap, MeasurementMarker, PolygonMarker, PolygonMarkerEditor, type PolygonMarkerState, RectangularBoxMarkerBase, type RectangularBoxMarkerBaseState, Renderer, ResizeGrip, RotateGrip, ShapeMarkerBase, type ShapeMarkerBaseState, ShapeMarkerEditor, ShapeOutlineMarkerBase, type ShapeOutlineMarkerBaseState, ShapeOutlineMarkerEditor, SvgHelper, TextMarker, TextMarkerEditor, type TextMarkerState, XImageMarker };