@markerjs/markerjs3 3.0.0-alpha.1

package/LICENSE

@@ -0,0 +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
+SOFTWARE.

package/README.md

@@ -0,0 +1,36 @@
+# 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.
+>
+> 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.
+
+## Installation
+
+```
+npm install @markerjs/markerjs3
+```
+
+or 
+
+```
+yarn add @markerjs/markerjs3
+```
+
+## Usage
+
+*coming soon...*
+
+## Demos
+
+*coming soon...*
+
+## More docs and tutorials
+
+*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).

package/markerjs3.d.ts

@@ -0,0 +1,620 @@
+/**
+ * Describes point objects used internally
+ */
+interface IPoint {
+    /**
+     * Horizontal (X) coordinate.
+     */
+    x: number;
+    /**
+     * Vertical (Y) coordinate.
+     */
+    y: number;
+}
+
+/**
+ * Utility class to simplify SVG operations.
+ */
+declare class SvgHelper {
+    /**
+     * Creates SVG "defs".
+     */
+    static createDefs(): SVGDefsElement;
+    /**
+     * Sets attributes on an arbitrary SVG element
+     * @param el - target SVG element.
+     * @param attributes - set of name-value attribute pairs.
+     */
+    static setAttributes(el: SVGElement, attributes: Array<[string, string]>): void;
+    /**
+     * Creates an SVG rectangle with the specified width and height.
+     * @param width
+     * @param height
+     * @param attributes - additional attributes.
+     */
+    static createRect(width: number | string, height: number | string, attributes?: Array<[string, string]>): SVGRectElement;
+    /**
+     * Creates an SVG line with specified end-point coordinates.
+     * @param x1
+     * @param y1
+     * @param x2
+     * @param y2
+     * @param attributes - additional attributes.
+     */
+    static createLine(x1: number | string, y1: number | string, x2: number | string, y2: number | string, attributes?: Array<[string, string]>): SVGLineElement;
+    /**
+     * Creates an SVG polygon with specified points.
+     * @param points - points as string.
+     * @param attributes - additional attributes.
+     */
+    static createPolygon(points: string, attributes?: Array<[string, string]>): SVGPolygonElement;
+    /**
+     * Creates an SVG circle with the specified radius.
+     * @param radius
+     * @param attributes - additional attributes.
+     */
+    static createCircle(radius: number, attributes?: Array<[string, string]>): SVGCircleElement;
+    /**
+     * Creates an SVG ellipse with the specified horizontal and vertical radii.
+     * @param rx
+     * @param ry
+     * @param attributes - additional attributes.
+     */
+    static createEllipse(rx: number, ry: number, attributes?: Array<[string, string]>): SVGEllipseElement;
+    /**
+     * Creates an SVG group.
+     * @param attributes - additional attributes.
+     */
+    static createGroup(attributes?: Array<[string, string]>): SVGGElement;
+    /**
+     * Creates an SVG transform.
+     */
+    static createTransform(): SVGTransform;
+    /**
+     * Creates an SVG marker.
+     * @param id
+     * @param orient
+     * @param markerWidth
+     * @param markerHeight
+     * @param refX
+     * @param refY
+     * @param markerElement
+     */
+    static createMarker(id: string, orient: string, markerWidth: number | string, markerHeight: number | string, refX: number | string, refY: number | string, markerElement: SVGGraphicsElement): SVGMarkerElement;
+    /**
+     * Creates an SVG text element.
+     * @param attributes - additional attributes.
+     */
+    static createText(attributes?: Array<[string, string]>): SVGTextElement;
+    /**
+     * Creates an SVG TSpan.
+     * @param text - inner text.
+     * @param attributes - additional attributes.
+     */
+    static createTSpan(text: string, attributes?: Array<[string, string]>): SVGTSpanElement;
+    /**
+     * Creates an SVG image element.
+     * @param attributes - additional attributes.
+     */
+    static createImage(attributes?: Array<[string, string]>): SVGImageElement;
+    /**
+     * Creates an SVG point with the specified coordinates.
+     * @param x
+     * @param y
+     */
+    static createPoint(x: number, y: number): SVGPoint;
+    /**
+     * Creates an SVG path with the specified shape (d).
+     * @param d - path shape
+     * @param attributes - additional attributes.
+     */
+    static createPath(d: string, attributes?: Array<[string, string]>): SVGPathElement;
+    /**
+     * Creates an SVG text element.
+     * @param attributes - additional attributes.
+     */
+    static createForeignObject(attributes?: Array<[string, string]>): SVGForeignObjectElement;
+    /**
+     * Returns local coordinates relative to the provided `localRoot` of a client (screen) point.
+     * @param localRoot relative coordinate root
+     * @param x horizontal client coordinate
+     * @param y vertical client coordinate
+     * @param zoomLevel zoom level
+     * @returns local coordinates relative to `localRoot`
+     */
+    static clientToLocalCoordinates(localRoot: SVGElement | undefined, x: number, y: number, zoomLevel?: number): IPoint;
+    /**
+     * Creates an SVG image element from a supplied inner SVG markup string.
+     * @param stringSvg SVG markup (without the root svg tags)
+     * @returns SVG image element
+     */
+    static createSvgFromString(stringSvg: string): SVGSVGElement;
+}
+
+/**
+ * Represents marker's state used to save and restore state continue annotation in the future.
+ */
+interface MarkerBaseState {
+    /**
+     * Marker's type name.
+     */
+    typeName: string;
+    /**
+     * Additional information about the marker.
+     */
+    notes?: string;
+    strokeColor?: string;
+    strokeWidth?: number;
+    strokeDasharray?: string;
+    opacity?: number;
+}
+
+/**
+ * Describes a size
+ */
+interface ISize {
+    width: number;
+    height: number;
+}
+
+type MarkerStage = 'creating' | 'normal';
+declare class MarkerBase {
+    static typeName: string;
+    get typeName(): string;
+    protected _container: SVGGElement;
+    /**
+     * SVG container object holding the marker's visual.
+     */
+    get container(): SVGGElement;
+    /**
+     * Additional information about the marker
+     */
+    notes?: string;
+    /**
+     * The default marker size when the marker is created with a click (without dragging).
+     */
+    defaultSize: ISize;
+    /**
+     * Marker type title (display name) used for accessibility and other attributes.
+     */
+    static title: string;
+    stage: MarkerStage;
+    protected _strokeColor: string;
+    get strokeColor(): string;
+    set strokeColor(color: string);
+    protected applyStrokeColor(): void;
+    protected _fillColor: string;
+    get fillColor(): string;
+    set fillColor(color: string);
+    protected applyFillColor(): void;
+    protected _strokeWidth: number;
+    get strokeWidth(): number;
+    set strokeWidth(value: number);
+    protected applyStrokeWidth(): void;
+    protected _strokeDasharray: string;
+    get strokeDasharray(): string;
+    set strokeDasharray(value: string);
+    protected applyStrokeDasharray(): void;
+    protected _opacity: number;
+    get opacity(): number;
+    set opacity(value: number);
+    protected applyOpacity(): void;
+    constructor(container: SVGGElement);
+    /**
+     * Returns true if passed SVG element belongs to the marker. False otherwise.
+     *
+     * @param el - target element.
+     */
+    ownsTarget(el: EventTarget): boolean;
+    /**
+     * Disposes the marker and clean's up.
+     */
+    dispose(): void;
+    protected addMarkerVisualToContainer(element: SVGElement): void;
+    getOutline(): string;
+    /**
+     * Returns current marker state that can be restored in the future.
+     */
+    getState(): MarkerBaseState;
+    /**
+     * Restores previously saved marker state.
+     *
+     * @param state - previously saved state.
+     */
+    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 AnnotationState {
+    version?: number;
+    width: number;
+    height: number;
+    markers: MarkerBaseState[];
+}
+
+interface MarkerEditorProperties<TMarkerType extends MarkerBase = MarkerBase> {
+    /**
+     * SVG container for the marker and editor elements.
+     */
+    container: SVGGElement;
+    /**
+     * HTML overlay container for editor's HTML elements (such as label text editor).
+     */
+    overlayContainer: HTMLDivElement;
+    /**
+     * Type of marker to create.
+     */
+    markerType: new (container: SVGGElement) => TMarkerType;
+    /**
+     * Previously created marker to edit.
+     */
+    marker?: TMarkerType;
+}
+
+/**
+ * Represents marker's state (status) in time.
+ */
+type MarkerEditorState = 'new' | 'creating' | 'select' | 'move' | 'resize' | 'rotate' | 'edit';
+type MarkerCreationStyle = 'draw' | 'drop';
+declare class MarkerBaseEditor<TMarkerType extends MarkerBase = MarkerBase> {
+    protected _markerType: new (container: SVGGElement) => TMarkerType;
+    protected _creationStyle: MarkerCreationStyle;
+    get creationStyle(): MarkerCreationStyle;
+    /**
+     * Type guard for specific marker editor types.
+     * @param cls
+     * @returns
+     */
+    is<T>(cls: new (...args: any[]) => T): this is T;
+    protected _marker: TMarkerType;
+    get marker(): TMarkerType;
+    protected _container: SVGGElement;
+    /**
+     * Returns the SVG container for the marker's and editor's visual elements.
+     */
+    get container(): SVGGElement;
+    /**
+     * Overlay container for HTML elements like text editors, etc.
+     */
+    protected _overlayContainer: HTMLDivElement;
+    /**
+     * Overlay container for HTML elements like text editors, etc.
+     */
+    get overlayContainer(): HTMLDivElement;
+    /**
+     * Editor's state.
+     */
+    protected _state: MarkerEditorState;
+    /**
+     * Gets editor's state.
+     */
+    get state(): MarkerEditorState;
+    /**
+     * Sets editor's state.
+     */
+    set state(value: MarkerEditorState);
+    /**
+     * SVG group holding editor's control box.
+     */
+    protected _controlBox: SVGGElement;
+    /**
+     * Method called when marker creation is finished.
+     */
+    onMarkerCreated?: <T extends MarkerBaseEditor<MarkerBase>>(editor: T) => void;
+    /**
+     * Method to call when marker state changes.
+     */
+    onStateChanged?: <T extends MarkerBaseEditor<MarkerBase>>(editor: T) => void;
+    /**
+     * Marker's state when it is selected
+     */
+    protected manipulationStartState?: string;
+    /**
+     * Is this marker selected?
+     */
+    protected _isSelected: boolean;
+    /**
+     * Returns true if the marker is currently selected
+     */
+    get isSelected(): boolean;
+    protected _continuousCreation: boolean;
+    get continuousCreation(): boolean;
+    /**
+     * Sets rectangle's border stroke color.
+     * @param color - color as string
+     */
+    set strokeColor(color: string);
+    get strokeColor(): string;
+    /**
+     * Sets rectangle's border stroke (line) width.
+     * @param color - color as string
+     */
+    set strokeWidth(width: number);
+    get strokeWidth(): number;
+    /**
+     * Sets rectangle's border stroke dash array.
+     * @param color - color as string
+     */
+    set strokeDasharray(dashes: string);
+    get strokeDasharray(): string;
+    set fillColor(color: string);
+    get fillColor(): string;
+    set opacity(value: number);
+    get opacity(): number;
+    constructor(properties: MarkerEditorProperties<TMarkerType>);
+    ownsTarget(el: EventTarget | null): boolean;
+    /**
+     * Selects this marker and displays appropriate selected marker UI.
+     */
+    select(): void;
+    /**
+     * Deselects this marker and hides selected marker UI.
+     */
+    deselect(): void;
+    /**
+     * 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.) double click event.
+     *
+     * @param point - event coordinates.
+     * @param target - direct event target element.
+     */
+    dblClick(point: IPoint, target?: EventTarget): void;
+    /**
+     * Handles marker manipulation (move, resize, rotate, etc.).
+     *
+     * @param point - event coordinates.
+     */
+    manipulate(point: IPoint): void;
+    /**
+     * Handles pointer (mouse, touch, stylus, etc.) up event.
+     *
+     * @param point - event coordinates.
+     */
+    pointerUp(point: IPoint): void;
+    /**
+     * Disposes the marker and clean's up.
+     */
+    dispose(): void;
+    protected adjustControlBox(): void;
+    scale(scaleX: number, scaleY: number): void;
+    /**
+     * Called by a marker when its state could have changed.
+     * Does a check if the state has indeed changed before firing the handler.
+     */
+    protected stateChanged(): void;
+    getState(): MarkerBaseState;
+    /**
+     * Restores previously saved marker state.
+     *
+     * @param state - previously saved state.
+     */
+    restoreState(state: MarkerBaseState): void;
+}
+
+interface MarkerAreaEventMap {
+    /**
+     * Marker area initialized.
+     */
+    areainit: CustomEvent<MarkerAreaEventData>;
+    areashow: CustomEvent<MarkerAreaEventData>;
+    arearestorestate: CustomEvent<MarkerAreaEventData>;
+    areafocus: CustomEvent<MarkerAreaEventData>;
+    areablur: CustomEvent<MarkerAreaEventData>;
+    areastatechange: CustomEvent<MarkerAreaEventData>;
+    markerselect: CustomEvent<MarkerEditorEventData>;
+    markerdeselect: CustomEvent<MarkerEditorEventData>;
+    markercreating: CustomEvent<MarkerEditorEventData>;
+    markercreate: CustomEvent<MarkerEditorEventData>;
+    markerbeforedelete: CustomEvent<MarkerEditorEventData>;
+    markerdelete: CustomEvent<MarkerEditorEventData>;
+    markerchange: CustomEvent<MarkerEditorEventData>;
+}
+interface MarkerAreaEventData {
+    /**
+     * {@link MarkerArea} instance.
+     */
+    markerArea: MarkerArea;
+}
+interface MarkerEditorEventData extends MarkerAreaEventData {
+    markerEditor: MarkerBaseEditor;
+}
+declare class MarkerArea extends HTMLElement {
+    private _contentContainer?;
+    private _canvasContainer?;
+    private _overlayContainer;
+    private _overlayContentContainer;
+    private _mainCanvas?;
+    private _groupLayer?;
+    private _editingTarget?;
+    private width;
+    private height;
+    private _targetWidth;
+    get targetWidth(): number;
+    set targetWidth(value: number);
+    private _targetHeight;
+    get targetHeight(): number;
+    set targetHeight(value: number);
+    private mode;
+    private _logoUI?;
+    private _isInitialized;
+    private _currentMarkerEditor?;
+    get currentMarkerEditor(): MarkerBaseEditor | undefined;
+    private _newMarkerOutline;
+    private _targetImage;
+    get targetImage(): HTMLImageElement | undefined;
+    set targetImage(value: HTMLImageElement | undefined);
+    markerEditors: Map<typeof MarkerBase, typeof MarkerBaseEditor<MarkerBase>>;
+    editors: MarkerBaseEditor[];
+    private _zoomLevel;
+    /**
+     * Returns the current zoom level.
+     */
+    get zoomLevel(): number;
+    /**
+     * Sets the current zoom level.
+     */
+    set zoomLevel(value: number);
+    private prevPanPoint;
+    private panTo;
+    private undoRedoManager;
+    constructor();
+    private connectedCallback;
+    private disconnectedCallback;
+    private createLayout;
+    private addMainCanvas;
+    private setMainCanvasSize;
+    private setEditingTargetSize;
+    private initOverlay;
+    private addTargetImage;
+    createMarker(markerType: typeof MarkerBase | string): MarkerBaseEditor<MarkerBase> | undefined;
+    private addNewMarker;
+    private markerCreated;
+    private markerStateChanged;
+    setCurrentEditor(editor?: MarkerBaseEditor): void;
+    private touchPoints;
+    private isDragging;
+    private onCanvasPointerDown;
+    private onCanvasDblClick;
+    private onPointerMove;
+    private showOutline;
+    private hideOutline;
+    private onPointerUp;
+    private onPointerOut;
+    private onKeyUp;
+    private attachEvents;
+    private attachWindowEvents;
+    private detachEvents;
+    private detachWindowEvents;
+    private getMarkerTypeByName;
+    switchToSelectMode(): void;
+    getState(): AnnotationState;
+    restoreState(state: AnnotationState): void;
+    private scaleMarkers;
+    /**
+     * NOTE:
+     *
+     * before removing or modifying this method please consider supporting marker.js
+     * by visiting https://markerjs.com/buy for details
+     *
+     * thank you!
+     */
+    private toggleLogo;
+    private addLogo;
+    private removeLogo;
+    private positionLogo;
+    /**
+     * Returns true if undo operation can be performed (undo stack is not empty).
+     */
+    get isUndoPossible(): boolean;
+    /**
+     * Returns true if redo operation can be performed (redo stack is not empty).
+     */
+    get isRedoPossible(): boolean;
+    private addUndoStep;
+    /**
+     * Undo last action.
+     */
+    undo(): void;
+    private undoStep;
+    /**
+     * Redo previously undone action.
+     */
+    redo(): void;
+    private redoStep;
+    addEventListener<T extends keyof MarkerAreaEventMap>(type: T, listener: (this: MarkerArea, ev: MarkerAreaEventMap[T]) => void, options?: boolean | AddEventListenerOptions): void;
+    addEventListener<K extends keyof HTMLElementEventMap>(type: K, listener: (this: HTMLElement, ev: HTMLElementEventMap[K]) => void, options?: boolean | AddEventListenerOptions | undefined): void;
+    removeEventListener<T extends keyof MarkerAreaEventMap>(type: T, listener: (this: MarkerArea, ev: MarkerAreaEventMap[T]) => void, options?: boolean | EventListenerOptions): void;
+    removeEventListener<K extends keyof HTMLElementEventMap>(type: K, listener: (this: HTMLElement, ev: HTMLElementEventMap[K]) => void, options?: boolean | EventListenerOptions | undefined): void;
+}
+
+interface MarkerViewEventMap {
+    /**
+     * Viewer initialized.
+     */
+    viewinit: CustomEvent<MarkerViewEventData>;
+    viewshow: CustomEvent<MarkerViewEventData>;
+    viewrestorestate: CustomEvent<MarkerViewEventData>;
+}
+interface MarkerViewEventData {
+    /**
+     * {@link MarkerView} instance.
+     */
+    markerView: MarkerView;
+}
+declare class MarkerView extends HTMLElement {
+    private _contentContainer?;
+    private _canvasContainer?;
+    private _mainCanvas?;
+    private _groupLayer?;
+    private _editingTarget?;
+    private width;
+    private height;
+    private _targetWidth;
+    get targetWidth(): number;
+    set targetWidth(value: number);
+    private _targetHeight;
+    get targetHeight(): number;
+    set targetHeight(value: number);
+    private _targetImage;
+    get targetImage(): HTMLImageElement | undefined;
+    set targetImage(value: HTMLImageElement | undefined);
+    markerTypes: Array<typeof MarkerBase>;
+    markers: MarkerBase[];
+    private _logoUI?;
+    private _zoomLevel;
+    /**
+     * Returns the current zoom level.
+     */
+    get zoomLevel(): number;
+    /**
+     * Sets the current zoom level.
+     */
+    set zoomLevel(value: number);
+    private _isInitialized;
+    constructor();
+    private connectedCallback;
+    private disconnectedCallback;
+    private createLayout;
+    private addMainCanvas;
+    private setMainCanvasSize;
+    private setEditingTargetSize;
+    private addTargetImage;
+    private addNewMarker;
+    private attachEvents;
+    private attachWindowEvents;
+    private detachEvents;
+    private detachWindowEvents;
+    private getMarkerTypeByName;
+    show(state: AnnotationState): void;
+    private scaleMarkers;
+    /**
+     * NOTE:
+     *
+     * before removing or modifying this method please consider supporting marker.js
+     * by visiting https://markerjs.com/buy for details
+     *
+     * thank you!
+     */
+    private toggleLogo;
+    private addLogo;
+    private removeLogo;
+    private positionLogo;
+    addEventListener<T extends keyof MarkerViewEventMap>(type: T, listener: (this: MarkerView, ev: MarkerViewEventMap[T]) => void, options?: boolean | AddEventListenerOptions): void;
+    addEventListener<K extends keyof HTMLElementEventMap>(type: K, listener: (this: HTMLElement, ev: HTMLElementEventMap[K]) => void, options?: boolean | AddEventListenerOptions | undefined): void;
+    removeEventListener<T extends keyof MarkerViewEventMap>(type: T, listener: (this: MarkerView, ev: MarkerViewEventMap[T]) => void, options?: boolean | EventListenerOptions): void;
+    removeEventListener<K extends keyof HTMLElementEventMap>(type: K, listener: (this: HTMLElement, ev: HTMLElementEventMap[K]) => void, options?: boolean | EventListenerOptions | undefined): void;
+}
+
+export { type IPoint, MarkerArea, type MarkerAreaEventData, type MarkerAreaEventMap, MarkerView, type MarkerViewEventData, type MarkerViewEventMap, SvgHelper };