@inweb/markup 25.8.20 → 25.8.21

package/lib/markup/Konva/KonvaMarkup.d.ts

@@ -11,7 +11,7 @@ export declare class KonvaMarkup implements IMarkup {
     private _viewer;
     private _worldTransformer;
     private _container;
-    private _pointerEvents;
+    private _containerEvents;
     private _markupIsActive;
     private _markupMode;
     private _markupColor;
@@ -31,7 +31,7 @@ export declare class KonvaMarkup implements IMarkup {
     lineWidth: number;
     lineType: MarkupLineType;
     fontSize: number;
-    initialize(container: HTMLElement, pointerEvents?: string[], viewer?: IEventEmitter, worldTransformer?: IWorldTransform): void;
+    initialize(container: HTMLElement, containerEvents?: string[], viewer?: IEventEmitter, worldTransformer?: IWorldTransform): void;
     dispose(): void;
     changeActiveDragger: (event: ChangeActiveDraggerEvent) => void;
     resizeContainer: (entries: ResizeObserverEntry[]) => void;

package/lib/markup/Konva/MarkupColor.d.ts

@@ -1,37 +1,38 @@
 /**
- * Markup color.
+ * Defines the markup color helper object.
  */
 export declare class MarkupColor {
     R: number;
     G: number;
     B: number;
-    private _hex;
+    HEX: string;
     /**
-     * Color in #000000 format
+     * Creates an instance of the color.
+     *
+     * @param r - The `red` component of the color, as a number between 0 and 255.
+     * @param g - The `green` component of the color, as a number between 0 and 255.
+     * @param b - The `blue` component of the color, as a number between 0 and 255.
+     */
+    constructor(r: number, g: number, b: number);
+    /**
+     * Returns the color as a string in hexadecimal color syntax `#RGB` using its primary color
+     * components (red, green, blue) written as hexadecimal numbers.
      */
-    get HexColor(): string;
+    asHex(): string;
     /**
-     * Color as object with r,g,b properties
+     * Returns the color as an {r, g, b} object.
      */
-    get RGB(): {
+    asRGB(): {
         r: number;
         g: number;
         b: number;
     };
     /**
-     * Create an instance of Color
-     *
-     * @param r - Red color in [0,255] range
-     * @param g - Green color in [0,255] range
-     * @param b - Blue color in [0,255] range
-     */
-    constructor(r: number, g: number, b: number);
-    /**
-     * Set Color for current instance
+     * Sets the color.
      *
-     * @param r - Red color in [0,255] range
-     * @param g - Green color in [0,255] range
-     * @param b - Blue color in [0,255] range
+     * @param r - The `red` component of the color, as a number between 0 and 255.
+     * @param g - The `green` component of the color, as a number between 0 and 255.
+     * @param b - The `blue` component of the color, as a number between 0 and 255.
      */
     setColor(r: number, g: number, b: number): void;
     private rgbToHex;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inweb/markup",
-  "version": "25.8.20",
+  "version": "25.8.21",
   "description": "JavaScript 2D markups",
   "homepage": "https://cloud.opendesign.com/docs/index.html",
   "license": "SEE LICENSE IN LICENSE",
@@ -26,8 +26,8 @@
     "docs": "typedoc"
   },
   "dependencies": {
-    "@inweb/eventemitter2": "~25.8.20",
-    "@inweb/viewer-core": "~25.8.20"
+    "@inweb/eventemitter2": "~25.8.21",
+    "@inweb/viewer-core": "~25.8.21"
   },
   "devDependencies": {
     "konva": "^9.2.0"

package/src/index.ts

@@ -27,7 +27,7 @@ export { IMarkupCloud } from "./markup/IMarkupCloud";
 export { IMarkupColorable } from "./markup/IMarkupColorable";
 export { IMarkupEllipse } from "./markup/IMarkupEllipse";
 export { IMarkupImage } from "./markup/IMarkupImage";
-export { IMarkupLine, MarkupLineType } from "./markup/IMarkupLine";
+export { IMarkupLine, IMarkupLineParams, MarkupLineType } from "./markup/IMarkupLine";
 export { IMarkupObject } from "./markup/IMarkupObject";
 export { IMarkupRectangle } from "./markup/IMarkupRectangle";
 export { IMarkupText } from "./markup/IMarkupText";

package/src/markup/IMarkup.ts

@@ -25,6 +25,7 @@ import { IEventEmitter } from "@inweb/eventemitter2";
 import { IViewpoint } from "@inweb/viewer-core";
 import { IWorldTransform } from "./IWorldTransform";
 import { IMarkupObject } from "./IMarkupObject";
+import { IMarkupLineParams } from "./IMarkupLine";
 
 /**
  * Defines the markup edit mode. Matches the type of markup object being created.
@@ -50,7 +51,7 @@ export interface IMarkup {
   lineType: string;
 
   /**
-   * Font size of new markup text, in pixels.
+   * Font size of new markup text.
    *
    * @default 34
    */
@@ -62,8 +63,11 @@ export interface IMarkup {
    * @param container - Container element used to operate on. This is usually a `<canvas>` or
    *   `<div>` on top of which the markup is drawn. If the `container` is a `<canvas>` element,
    *   its content will be combined with the markup in the viewpoint snapshot.
-   * @param pointerEvents - List of pointing device events that the markup should redirect to
-   *   the `viewer`.
+   * @param containerEvents - List of container events, such as mouse events or
+   *   {@link https://developer.mozilla.org/docs/Web/API/Pointer_events#event_types_and_global_event_handlers | pointer events}
+   *   or
+   *   {@link https://developer.mozilla.org/docs/Web/API/TouchEvent#touch_event_types | touch events}
+   *   that the markup should redirect to the `viewer`.
    * @param viewer - `Viewer` instance that receives pointing device events.
    * @param worldTransformer - Transformer of screen space into the `viewer` world space and
    *   vice versa. If a transformer is defined, markup objects will be stored at the viewpoint
@@ -71,7 +75,7 @@ export interface IMarkup {
    */
   initialize(
     container: HTMLElement,
-    pointerEvents?: string[],
+    containerEvents?: string[],
     viewer?: IEventEmitter,
     worldTransformer?: IWorldTransform
   ): void;
@@ -94,9 +98,9 @@ export interface IMarkup {
   /**
    * Sets the color of new markup objects.
    *
-   * @param r - `Red` part of color.
-   * @param g - `Green` part of color.
-   * @param b - `Blue` part of color.
+   * @param r - The `red` component of the color, as a number between 0 and 255.
+   * @param g - The `green` component of the color, as a number between 0 and 255.
+   * @param b - The `blue` component of the color, as a number between 0 and 255.
    */
   setMarkupColor(r: number, g: number, b: number): void;
 
@@ -108,18 +112,18 @@ export interface IMarkup {
   /**
    * Colors all markup objects with the specified color.
    *
-   * @param r - `Red` part of color.
-   * @param g - `Green` part of color.
-   * @param b - `Blue` part of color.
+   * @param r - The `red` component of the color, as a number between 0 and 255.
+   * @param g - The `green` component of the color, as a number between 0 and 255.
+   * @param b - The `blue` component of the color, as a number between 0 and 255.
    */
   colorizeAllMarkup(r: number, g: number, b: number): void;
 
   /**
-   * Colors selected markup objects with the specified color.
+   * Colors the selected markup objects with the specified color.
    *
-   * @param r - `Red` part of color.
-   * @param g - `Green` part of color.
-   * @param b - `Blue` part of color.
+   * @param r - The `red` component of the color, as a number between 0 and 255.
+   * @param g - The `green` component of the color, as a number between 0 and 255.
+   * @param b - The `blue` component of the color, as a number between 0 and 255.
    */
   colorizeSelectedMarkups(r: number, g: number, b: number): void;
 
@@ -148,7 +152,15 @@ export interface IMarkup {
    *
    * @param type - Markup object type. Can be `Line`, `Text`, `Rectangle`, `Ellipse`, `Arrow`,
    *   `Image` or `Cloud`.
-   * @param params - Markup object parameters.
+   * @param params - Parameters for creating a markup object. Must match the object type:
+   *
+   *   - `Line` - {@link IMarkupLineParams}
+   *   - `Text` - {@link IMarkupTextParams}
+   *   - `Rectangle` - {@link IMarkupRectangleParams}
+   *   - `Ellipse` - {@link IMarkupEllipseParams}
+   *   - `Arrow` - {@link IMarkupArrowParams}
+   *   - `Image` - {@link IMarkupImageParams}
+   *   - `Cloud` - {@link IMarkupCloudParams}
    */
   createObject(type: string, params: any): IMarkupObject;
 
@@ -163,7 +175,7 @@ export interface IMarkup {
   getSelectedObjects(): IMarkupObject[];
 
   /**
-   * Selects specified markup objects.
+   * Selects the specified markup objects.
    *
    * @param objects - The list of markup objects.
    */

package/src/markup/IMarkupArrow.ts

@@ -25,46 +25,38 @@ import { IMarkupObject } from "./IMarkupObject";
 import { IMarkupColorable } from "./IMarkupColorable";
 
 /**
- * Arrow Markup object
+ * 2D markup Arrow object interface.
  */
 export interface IMarkupArrow extends IMarkupObject, IMarkupColorable {
   /**
-   * Get points of current Arrow
-   *
-   * @returns {{ x: number; y: number }} array of points
+   * Returns the coordinales of the start and end points of arrow.
    */
   getPoints(): { x: number; y: number }[];
 
   /**
-   * Set points of the Arrow
+   * Sets the coordinales of the start and end points of the arrow.
    *
-   * @param {{ x: number; y: number }} points - array of points
+   * @param {{ x: number; y: number }} points - Array of points.
    */
   setPoints(points: { x: number; y: number }[]);
 
   /**
-   * Get Start Point of the Arrow
+   * Returns the coordinales of the start point of arrow.
    */
   getStartPoint(): { x: number; y: number };
 
   /**
-   * Set Start point of the Arrow
-   *
-   * @param x - value of X coordinate
-   * @param y - value of Y coordinate
+   * Sets the coordinales of the start point of the arrow.
    */
   setStartPoint(x: number, y: number);
 
   /**
-   * Get End point of the Arrow
+   * Returns the coordinales of the end point of arrow.
    */
   getEndPoint(): { x: number; y: number };
 
   /**
-   * Set End point of the Arrow
-   *
-   * @param x - value of X coordinate
-   * @param y - value of Y coordinate
+   * Sets the coordinales of the end point of the arrow.
    */
   setEndPoint(x: number, y: number);
 }

package/src/markup/IMarkupCloud.ts

@@ -25,55 +25,46 @@ import { IMarkupObject } from "./IMarkupObject";
 import { IMarkupColorable } from "./IMarkupColorable";
 
 /**
- * Cloud Markup object
+ * 2D markup Cloud object interface.
  */
 export interface IMarkupCloud extends IMarkupObject, IMarkupColorable {
   /**
-   * Get position of the Cloud
+   * Returns the coordinates of the top-left point (position) of the cloud.
    */
   getPosition(): { x: number; y: number };
 
   /**
-   * Set position of the Cloud
-   *
-   * @param x - value of X coordinate
-   * @param y - value of Y coordinate
+   * Sets the coordinates of the top-left point (position) of the cloud.
    */
   setPosition(x: number, y: number);
 
   /**
-   * Get width of the Cloud. Default value is 200
+   * Returns the width of the cloud.
    */
   getWidth(): number;
 
   /**
-   * Set width of the Cloud
-   *
-   * @param w - value of width. Default value is 200
+   * Sets the width of the cloud.
    */
   setWidth(w: number);
 
   /**
-   * Get height of the Cloud. Default value is 200
+   * Returns the height of the cloud.
    */
   getHeigth(): number;
 
   /**
-   * Set height of the Cloud
-   *
-   * @param h - value of height. Default value is 200
+   * Sets the height of the cloud.
    */
   setHeight(h: number);
 
   /**
-   * Get line width of the Cloud. Defailt value is 4
+   * Returns the line width of the cloud.
    */
   getLineWidth(): number;
 
   /**
-   * Set line width of the Cloud
-   *
-   * @param size - value of width. Defailt value is 4
+   * Sets the line width of the cloud.
    */
   setLineWidth(size: number);
 }

package/src/markup/IMarkupColorable.ts

@@ -22,18 +22,19 @@
 ///////////////////////////////////////////////////////////////////////////////
 
 /**
- * Markup Colorable
+ * 2D markup colorable object interface.
  */
 export interface IMarkupColorable {
   /**
-   * Get color of the Markup instance
+   * Returns the foreground color of an object's line or text as a string in hexadecimal color
+   * syntax `#RGB` using its primary color components (red, green, blue) written as hexadecimal numbers.
    */
   getColor(): string;
 
   /**
-   * Set color of the Markup instance
+   * Sets the foreground color of an object's line or text.
    *
-   * @param hex - color in #hex format. Default: `#ff0000`
+   * @param hex - Color in hexadecimal color syntax `#RGB`.
    */
   setColor(hex: string): void;
 }

package/src/markup/IMarkupEllipse.ts

@@ -25,55 +25,46 @@ import { IMarkupObject } from "./IMarkupObject";
 import { IMarkupColorable } from "./IMarkupColorable";
 
 /**
- * Ellipse Markup object
+ * 2D markup Ellipse object interface.
  */
 export interface IMarkupEllipse extends IMarkupObject, IMarkupColorable {
   /**
-   * Get position of the Ellipse
+   * Returns the coordinates of the center point (position) of the ellipse.
    */
   getPosition(): { x: number; y: number };
 
   /**
-   * Set position of the Ellipse
-   *
-   * @param x - value of X coordinate
-   * @param y - value of Y coordinate
+   * Sets the coordinates of the top-left point (position) of the ellipse.
    */
   setPosition(x: number, y: number);
 
   /**
-   * Get X radius of the Ellipse
+   * Returns the X radius of the ellipse.
    */
   getRadiusX(): number;
 
   /**
-   * Set X radius of the Ellipse
-   *
-   * @param r - value of X radius of the Ellipse
+   * Sets the X radius of the ellipse.
    */
   setRadiusX(r: number);
 
   /**
-   * Get Y radius of the Ellipse
+   * Returns the Y radius of the ellipse.
    */
   getRadiusY(): number;
 
   /**
-   * Set Y radius of the Ellipse
-   *
-   * @param r - value of Y radius of the Ellipse
+   * Sets the X radius of the ellipse.
    */
   setRadiusY(r: number);
 
   /**
-   * Get line width of the Ellipse. Defailt is 4
+   * Returns the line width of the ellipse.
    */
   getLineWidth(): number;
 
   /**
-   * Set line width of the Ellipse. Default is 4
-   *
-   * @param size - value of width
+   * Sets the line width of the ellipse.
    */
   setLineWidth(size: number);
 }

package/src/markup/IMarkupImage.ts

@@ -24,55 +24,52 @@
 import { IMarkupObject } from "./IMarkupObject";
 
 /**
- * Image Markup object
+ * 2D markup Image object interface.
  */
 export interface IMarkupImage extends IMarkupObject {
   /**
-   * Get position of the Image
+   * Returns the coordinates of the top-left point (position) of the image.
    */
   getPosition(): { x: number; y: number };
 
   /**
-   * Set position of the Image
-   *
-   * @param x - value of X coordinate
-   * @param y - value of Y coordinate
+   * Sets the coordinates of the top-left point (position) of the image.
    */
   setPosition(x: number, y: number);
 
   /**
-   * Get source of the Image. Provides base64 string
+   * Returns the image source as a base64-encoded
+   * {@link https://developer.mozilla.org/docs/Web/HTTP/Basics_of_HTTP/Data_URIs | Data URL}.
    */
   getSrc(): string;
 
   /**
-   * Set source of the Image
+   * Sets the image source. External image URL is not supported, only base64-encoded
+   * {@link https://developer.mozilla.org/docs/Web/HTTP/Basics_of_HTTP/Data_URIs | Data URLs}.
    *
-   * @param src - string in base64 format
+   * @param src - Image source as base64-encoded string.
    */
   setSrc(src: string);
 
   /**
-   * Get width of the Image
+   * Returns the width of the image. The original image is scaled to this width.
    */
   getWidth(): number;
 
   /**
-   * Set width of the Image
-   *
-   * @param w - value of width. Height will be automatically updated according to ratio of the Image
+   * Sets the width of the image. The image height will be automatically updated to match its
+   * aspect ratio.
    */
   setWidth(w: number);
 
   /**
-   * Get height of the Image
+   * Returns the height of the image. The original image is scaled to this height.
    */
   getHeight(): number;
 
   /**
-   * Set height of the Image
-   *
-   * @param h - value of height. Width will be automatically updated according to ratio of the Image
+   * Sets the height of the image. The image width will be automatically updated to match its
+   * aspect ratio.
    */
   setHeight(h: number);
 }

package/src/markup/IMarkupLine.ts

@@ -30,42 +30,77 @@ import { IMarkupColorable } from "./IMarkupColorable";
 export type MarkupLineType = "solid" | "dot" | "dash";
 
 /**
- * Line Markup object
+ * 2D markup Line object interface.
  */
 export interface IMarkupLine extends IMarkupObject, IMarkupColorable {
   /**
-   * Get points of the Line
+   * Returns the coordinates of the line points as a flat array [x1, y1, x2, y2, ...].
    */
   getPoints(): number[];
 
   /**
-   * Get Line width. Default value is 4
+   * Returns the line width.
    */
   getLineWidth(): number;
 
   /**
-   * Set Line width. Default value is 4
-   *
-   * @param size - value of width
+   * Sets the line width.
    */
   setLineWidth(size: number);
 
   /**
-   * Get Type of the Line. Available values: `solid`, `dot`, `dash`. Default is `solid`
+   * Returns the line type. Can be `solid`, `dot` or `dash`.
    */
   getLineType(): string;
 
   /**
-   * Set Type of the Line. Available values: `solid`, `dot`, `dash`. Default is `solid`
+   * Sets the line type.
    *
-   * @param type
+   * @param type - Line type. Can be `solid`, `dot` or `dash`.
    */
   setLineType(type: string);
 
   /**
-   * Add points to the Line
+   * Adds the specified points to the end of the line.
    *
-   * @param {{ x: number; y: number }} points array of points
+   * @param points - Array of 2D points.
    */
   addPoints(points: [{ x: number; y: number }]);
 }
+
+/**
+ * Defines the parameters for creating a {@link IMarkupLine | markup line}.
+ */
+export interface IMarkupLineParams {
+  /**
+   * Array of line points.
+   */
+  points?: { x: number; y: number }[];
+
+  /**
+   * Line type. Can be `solid`, `dot` or `dash`.
+   *
+   * @default "solid"
+   */
+  type?: MarkupLineType;
+
+  /**
+   * Line width.
+   *
+   * @default 4
+   */
+  width?: number;
+
+  /**
+   * Line color as a string in hexadecimal color syntax `#RGB` color using its primary color
+   * components (red, green, blue) written as hexadecimal numbers.
+   *
+   * @default "#ff0000"
+   */
+  color?: string;
+
+  /**
+   * Internal markup object identifier.
+   */
+  id?: string;
+}

package/src/markup/IMarkupObject.ts

@@ -22,57 +22,67 @@
 ///////////////////////////////////////////////////////////////////////////////
 
 /**
- * Markup object
+ * 2D markup object interface.
  */
 export interface IMarkupObject {
   /**
-   * Link to Library object (Konva, VisualizeJS)
+   * Returns a reference to a core markup library object (Konva, VisualizeJS, etc.).
    */
   ref(): any;
 
   /**
-   * Get an internal identificator of the object. Not unique
+   * Returns the internal identifier of the object. Not unique.
    */
   id(): string;
 
   /**
-   * Set Mouse editing feature
-   *
-   * @param value true / false
+   * Enables or disables the ability to select and edit an object using the mouse.
    */
-  enableMouseEditing(value: boolean);
+  enableMouseEditing(value: boolean): void;
 
   /**
-   * Get type of the Markup object
+   * Returns the type of the object.
    */
   type(): string;
 
   /**
-   * Get rotation of the Markup object
+   * Returns the rotation angle of the object, in degress.
    */
   getRotation(): number;
 
   /**
-   * Set rotation of the Markup object
+   * Sets the rotation angle of the object.
    *
-   * @param degrees number of degress to rotate
+   * @param degrees - Number of degress to rotate.
    */
   setRotation(degrees: number): void;
 
   /**
-   * Get Z-Index of the Markup object
+   * Returns the Z-index of a object relative to sibling objects that are in the same group.
+   *
+   * Z-Index is not absolute (like in CSS). It is relative to parent object group only:
+   *
+   * - `images` - are olways at the bottom
+   * - `texts` - are olways on top
+   * - `others` - are always between images and texts
    */
   getZIndex(): number;
 
   /**
-   * Set Z-Index of the Markup object
+   * Sets the Z-index of a object relative to sibling objects that are in the same group.
+   *
+   * Z-Index is not absolute (like in CSS). It is relative to parent object group only:
+   *
+   * - `images` - are olways at the bottom
+   * - `texts` - are olways on top
+   * - `others` - are always between images and texts
    *
-   * @param zIndex integer value of Z-Index
+   * @param zIndex - An integer value of Z-Index.
    */
   setZIndex(zIndex: number): void;
 
   /**
-   * Delete current Markup object
+   * Deletes the current object.
    */
   delete(): void;
 }