@markerjs/markerjs3 3.0.0-alpha.3 → 3.0.0-beta.0

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

@@ -403,8 +403,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;
     /**
@@ -949,6 +948,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;
@@ -959,6 +963,34 @@ declare class CalloutMarker extends TextMarker {
     scale(scaleX: number, scaleY: number): void;
 }
 
+declare class EllipseFrameMarker extends ShapeOutlineMarkerBase {
+    /**
+     * 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);
+    protected getPath(width?: number, height?: number): string;
+    getState(): ShapeOutlineMarkerBaseState;
+}
+
+declare class EllipseMarker extends ShapeMarkerBase {
+    /**
+     * 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);
+    protected getPath(width?: number, height?: number): string;
+    getState(): ShapeMarkerBaseState;
+}
+
 interface MarkerEditorProperties<TMarkerType extends MarkerBase = MarkerBase> {
     /**
      * SVG container for the marker and editor elements.
@@ -1702,6 +1734,12 @@ declare class FreehandMarkerEditor<TMarkerType extends FreehandMarker = Freehand
 declare class TextMarkerEditor<TMarkerType extends TextMarker = TextMarker> extends RectangularBoxMarkerBaseEditor<TMarkerType> {
     private textBlockEditorContainer;
     private 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;
@@ -1830,6 +1868,7 @@ declare class MarkerView extends HTMLElement {
 declare class Renderer {
     private _mainCanvas?;
     private _editingTarget?;
+    private _renderHelperContainer?;
     private _targetWidth;
     get targetWidth(): number;
     set targetWidth(value: number);
@@ -1888,4 +1927,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, 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, type ColorType, CoverMarker, EllipseFrameMarker, EllipseMarker, type FontSize, 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 };