plotboilerplate 1.20.2 → 1.22.0

package/src/ts/drawutilssvg.ts

@@ -37,7 +37,15 @@
  * @modified 2022-11-10 Tweaking some type issues.
  * @modified 2023-02-04 Fixed a typo in the CSS classname for cubic Bézier paths: cubicBezier (was cubierBezier).
  * @modified 2023-02-10 The methods `setCurrentClassName` and `setCurrentId` also accept `null` now.
- * @version  1.6.4
+ * @modified 2023-09-29 Added initialization checks for null parameters.
+ * @modified 2023-09-29 Added a missing implementation to the `drawurilssvg.do(XYCoords,string)` function. Didn't draw anything.
+ * @modified 2023-09-29 Downgrading all `Vertex` param type to the more generic `XYCoords` type in these render functions: line, arrow, texturedPoly, cubicBezier, cubicBezierPath, handle, handleLine, dot, point, circle, circleArc, ellipse, grid, raster.
+ * @modified 2023-09-29 Added the `headLength` parameter to the 'DrawLib.arrow()` function.
+ * @modified 2023-09-29 Added the `arrowHead(...)` function to the 'DrawLib.arrow()` interface.
+ * @modified 2023-09-29 Added the `cubicBezierArrow(...)` function to the 'DrawLib.arrow()` interface.
+ * @modified 2023-10-04 Adding `strokeOptions` param to these draw function: line, arrow, cubicBezierArrow, cubicBezier, cubicBezierPath, circle, circleArc, ellipse, square, rect, polygon, polyline.
+ *
+ * @version  1.6.7
  **/
 
 import { CircleSector } from "./CircleSector";
@@ -54,10 +62,12 @@ import {
   UID,
   DrawLibConfiguration,
   FontStyle,
-  FontWeight
+  FontWeight,
+  StrokeOptions
 } from "./interfaces";
 import { Bounds } from "./Bounds";
 import { UIDGenerator } from "./UIDGenerator";
+import { Vector } from "./Vector";
 
 const RAD_TO_DEG = 180 / Math.PI;
 
@@ -223,6 +233,9 @@ export class drawutilssvg implements DrawLib<void | SVGElement> {
     this.cache = new Map<UID, SVGElement>();
     this.setSize(canvasSize);
     if (isSecondary) {
+      if (!gNode || !bufferGNode || !nodeDefs || !bufferNodeDefs) {
+        throw "Cannot create secondary svg draw lib with undefinde gNode|bufferGNode|nodeDefs|bufferNodeDefs.";
+      }
       this.gNode = gNode;
       this.bufferGNode = bufferGNode;
       this.nodeDefs = nodeDefs;
@@ -369,6 +382,9 @@ export class drawutilssvg implements DrawLib<void | SVGElement> {
     if (this.drawlibConfiguration.blendMode) {
       node.style["mix-blend-mode"] = this.drawlibConfiguration.blendMode;
     }
+    // if (this.lineDashEnabled && this.lineDash && this.lineDash.length > 0 && drawutilssvg.nodeSupportsLineDash(nodeName)) {
+    //   node.setAttribute("stroke-dasharray", this.lineDash.join(" "));
+    // }
     return node;
   }
 
@@ -392,22 +408,73 @@ export class drawutilssvg implements DrawLib<void | SVGElement> {
    * @param {number=1} lineWidth - (optional) A line width to use for drawing (default is 1).
    * @return {SVGElement} The node itself (for chaining).
    */
-  private _bindFillDraw(node: SVGElement, className: string, color?: string | null, lineWidth?: number | null): SVGElement {
+  private _bindFillDraw(
+    node: SVGElement,
+    className: string,
+    color?: string | null,
+    lineWidth?: number | null,
+    strokeOptions?: StrokeOptions
+  ): SVGElement {
+    this._configureNode(node, className, this.fillShapes, color, lineWidth, strokeOptions);
+    return this._bindNode(node, undefined);
+  }
+
+  /**
+   * Bind this given node to a parent. If no parent is passed then the global
+   * node buffer will be used.
+   *
+   * @method _bindNode
+   * @private
+   * @instance
+   * @memberof drawutilssvg
+   * @param {SVGElement} node - The SVG node to bind.
+   * @param {SVGElement=} bindingParent - (optional) You may pass node other than the glober buffer node.
+   * @returns {SVGElement} The passed node itself.
+   */
+  private _bindNode(node: SVGElement, bindingParent?: SVGElement): SVGElement {
+    if (!node.parentNode) {
+      // Attach to DOM only if not already attached
+      (bindingParent ?? this.bufferGNode).appendChild(node);
+    }
+    return node;
+  }
+
+  /**
+   * Add custom CSS class names and the globally defined CSS classname to the
+   * given node.
+   *
+   * @method addCSSClasses
+   * @private
+   * @instance
+   * @memberof drawutilssvg
+   * @param {SVGElement} node - The SVG node to bind.
+   * @param {string} className - The additional custom classname to add.
+   * @returns {void}
+   */
+  private _addCSSClasses(node: SVGElement, className: string) {
     if (this.curClassName) {
       node.setAttribute("class", `${className} ${this.curClassName}`);
     } else {
       node.setAttribute("class", className);
     }
-    node.setAttribute("fill", this.fillShapes && color ? color : "none");
-    node.setAttribute("stroke", this.fillShapes ? "none" : color || "none");
+  }
+
+  private _configureNode(
+    node: SVGElement,
+    className: string,
+    fillMode: boolean,
+    color?: string | null,
+    lineWidth?: number | null,
+    strokeOptions?: StrokeOptions
+  ): SVGElement {
+    this._addCSSClasses(node, className);
+    node.setAttribute("fill", fillMode && color ? color : "none");
+    node.setAttribute("stroke", fillMode ? "none" : color || "none");
     node.setAttribute("stroke-width", `${lineWidth || 1}`);
     if (this.curId) {
       node.setAttribute("id", `${this.curId}`); // Maybe React-style 'key' would be better?
     }
-    if (!node.parentNode) {
-      // Attach to DOM only if not already attached
-      this.bufferGNode.appendChild(node);
-    }
+    this.applyStrokeOpts(node, strokeOptions);
     return node;
   }
 
@@ -437,7 +504,7 @@ export class drawutilssvg implements DrawLib<void | SVGElement> {
       this.scale,
       this.canvasSize,
       fillShapes,
-      null, // no DrawConfig
+      null as any as DrawConfig, // no DrawConfig – this will work as long as `isSecondary===true`
       true, // isSecondary
       this.gNode,
       this.bufferGNode,
@@ -458,6 +525,21 @@ export class drawutilssvg implements DrawLib<void | SVGElement> {
     this.drawlibConfiguration = configuration;
   }
 
+  // /**
+  //  * Set or clear the line-dash configuration. Pass `null` for un-dashed lines.
+  //  *
+  //  * See https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/stroke-dasharray
+  //  * and https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/setLineDash
+  //  * for how line dashes work.
+  //  *
+  //  * @method
+  //  * @param {Array<number> lineDashes - The line-dash array configuration.
+  //  * @returns {void}
+  //  */
+  // setLineDash(lineDashes: Array<number>) {
+  //   this.lineDash = lineDashes;
+  // }
+
   /**
    * This method shouled be called each time the currently drawn `Drawable` changes.
    * It is used by some libraries for identifying elemente on re-renders.
@@ -538,6 +620,32 @@ export class drawutilssvg implements DrawLib<void | SVGElement> {
     this.bufferedNodeDefs = tmpDefsNode;
   }
 
+  /**
+   * A private helper method to apply stroke options to the current
+   * context.
+   * @param {StrokeOptions=} strokeOptions -
+   */
+  private applyStrokeOpts(node: SVGElement, strokeOptions?: StrokeOptions) {
+    if (
+      strokeOptions &&
+      strokeOptions.dashArray &&
+      strokeOptions.dashArray.length > 0 &&
+      drawutilssvg.nodeSupportsLineDash(node.tagName)
+    ) {
+      node.setAttribute(
+        "stroke-dasharray",
+        strokeOptions.dashArray
+          .map((dashArayElem: number) => {
+            return dashArayElem * this.scale.x;
+          })
+          .join(" ")
+      );
+      if (strokeOptions.dashOffset) {
+        node.setAttribute("stroke-dashoffset", `${strokeOptions.dashOffset * this.scale.x}`);
+      }
+    }
+  }
+
   private _x(x: number): number {
     return this.offset.x + this.scale.x * x;
   }
@@ -549,49 +657,143 @@ export class drawutilssvg implements DrawLib<void | SVGElement> {
    * Draw the line between the given two points with the specified (CSS-) color.
    *
    * @method line
-   * @param {Vertex} zA - The start point of the line.
-   * @param {Vertex} zB - The end point of the line.
+   * @param {XYCoords} zA - The start point of the line.
+   * @param {XYCoords} zB - The end point of the line.
    * @param {string} color - Any valid CSS color string.
    * @param {number=1} lineWidth? - [optional] The line's width.
+   * @param {StrokeOptions=} strokeOptions - (optional) Stroke settings to use.
+   *
    * @return {void}
    * @instance
    * @memberof drawutilssvg
    **/
-  line(zA: Vertex, zB: Vertex, color: string, lineWidth?: number): SVGElement {
-    const line: SVGElement = this.makeNode("line");
-    line.setAttribute("x1", `${this._x(zA.x)}`);
-    line.setAttribute("y1", `${this._y(zA.y)}`);
-    line.setAttribute("x2", `${this._x(zB.x)}`);
-    line.setAttribute("y2", `${this._y(zB.y)}`);
-
-    return this._bindFillDraw(line, "line", color, lineWidth || 1);
+  line(zA: XYCoords, zB: XYCoords, color: string, lineWidth?: number, strokeOptions?: StrokeOptions): SVGElement {
+    // const line: SVGElement = this.makeNode("line");
+    // this.applyStrokeOpts(line, strokeOptions);
+    // line.setAttribute("x1", `${this._x(zA.x)}`);
+    // line.setAttribute("y1", `${this._y(zA.y)}`);
+    // line.setAttribute("x2", `${this._x(zB.x)}`);
+    // line.setAttribute("y2", `${this._y(zB.y)}`);
+    const line = this.makeLineNode(zA, zB, color, lineWidth, strokeOptions);
+    return this._bindFillDraw(line, "line", color, lineWidth || 1, strokeOptions);
   }
 
   /**
    * Draw a line and an arrow at the end (zB) of the given line with the specified (CSS-) color.
    *
    * @method arrow
-   * @param {Vertex} zA - The start point of the arrow-line.
-   * @param {Vertex} zB - The end point of the arrow-line.
+   * @param {XYCoords} zA - The start point of the arrow-line.
+   * @param {XYCoords} zB - The end point of the arrow-line.
    * @param {string} color - Any valid CSS color string.
    * @param {number=} lineWidth - (optional) The line width to use; default is 1.
+   * @param {headLength=8} headLength - (optional) The length of the arrow head (default is 8 units).
+   * @param {StrokeOptions=} strokeOptions - (optional) Stroke settings to use.
+   *
    * @return {void}
    * @instance
    * @memberof drawutilssvg
    **/
-  arrow(zA: Vertex, zB: Vertex, color: string, lineWidth?: number): SVGElement {
-    const node: SVGElement = this.makeNode("path");
-    var headlen: number = 8; // length of head in pixels
-    var vertices: Array<Vertex> = Vertex.utils.buildArrowHead(zA, zB, headlen, this.scale.x, this.scale.y);
-    const d: Array<string | number> = ["M", this._x(zA.x), this._y(zA.y)];
-    for (var i = 0; i <= vertices.length; i++) {
-      d.push("L");
-      // Note: only use offset here (the vertices are already scaled)
-      d.push(this.offset.x + vertices[i % vertices.length].x);
-      d.push(this.offset.y + vertices[i % vertices.length].y);
-    }
-    node.setAttribute("d", d.join(" "));
-    return this._bindFillDraw(node, "arrow", color, lineWidth || 1);
+  arrow(
+    zA: XYCoords,
+    zB: XYCoords,
+    color: string,
+    lineWidth?: number,
+    headLength: number = 8,
+    strokeOptions?: StrokeOptions
+  ): SVGElement {
+    const group: SVGElement = this.makeNode("g");
+    const arrowHeadBasePosition: XYCoords = { x: 0, y: 0 };
+    // Just create the child nodes, don't bind them to the root node.
+    const arrowHead: SVGElement = this.makeArrowHeadNode(zA, zB, color, lineWidth, headLength, undefined, arrowHeadBasePosition);
+    const line: SVGElement = this.makeLineNode(zA, arrowHeadBasePosition, color, lineWidth, strokeOptions);
+    group.appendChild(line);
+    group.appendChild(arrowHead);
+    this._addCSSClasses(group, "linear-arrow");
+    this._bindNode(group, undefined);
+    return group;
+  }
+
+  /**
+   * Draw a cubic Bézier curve and and an arrow at the end (endControlPoint) of the given line width the specified (CSS-) color and arrow size.
+   *
+   * @method cubicBezierArrow
+   * @param {XYCoords} startPoint - The start point of the cubic Bézier curve
+   * @param {XYCoords} endPoint   - The end point the cubic Bézier curve.
+   * @param {XYCoords} startControlPoint - The start control point the cubic Bézier curve.
+   * @param {XYCoords} endControlPoint   - The end control point the cubic Bézier curve.
+   * @param {string} color - The CSS color to draw the curve with.
+   * @param {number} lineWidth - (optional) The line width to use.
+   * @param {headLength=8} headLength - (optional) The length of the arrow head (default is 8 units).
+   * @param {StrokeOptions=} strokeOptions - (optional) Stroke settings to use.
+   *
+   * @return {void}
+   * @instance
+   * @memberof DrawLib
+   */
+  cubicBezierArrow(
+    startPoint: XYCoords,
+    endPoint: XYCoords,
+    startControlPoint: XYCoords,
+    endControlPoint: XYCoords,
+    color: string,
+    lineWidth?: number,
+    headLength: number = 8,
+    strokeOptions?: StrokeOptions
+  ): SVGElement {
+    const group: SVGElement = this.makeNode("g");
+    // Just create the child nodes, don't bind them to the root node.
+    const arrowHeadBasePosition = new Vertex(0, 0);
+    const arrowHead: SVGElement = this.makeArrowHeadNode(
+      endControlPoint,
+      endPoint,
+      color,
+      lineWidth,
+      headLength,
+      undefined,
+      arrowHeadBasePosition
+    );
+    const diff = arrowHeadBasePosition.difference(endPoint);
+    const bezier: SVGElement = this.makeCubicBezierNode(
+      startPoint,
+      { x: endPoint.x - diff.x, y: endPoint.y - diff.y },
+      startControlPoint,
+      { x: endControlPoint.x - diff.x, y: endControlPoint.y - diff.y },
+      color,
+      lineWidth,
+      strokeOptions
+    );
+    group.appendChild(bezier);
+    group.appendChild(arrowHead);
+    this._addCSSClasses(group, "cubicbezier-arrow");
+    this._bindNode(group, undefined);
+    return group;
+  }
+
+  /**
+   * Draw just an arrow head a the end of an imaginary line (zB) of the given line width the specified (CSS-) color and size.
+   *
+   * @method arrow
+   * @param {XYCoords} zA - The start point of the arrow-line.
+   * @param {XYCoords} zB - The end point of the arrow-line.
+   * @param {string} color - Any valid CSS color string.
+   * @param {number=1} lineWidth - (optional) The line width to use; default is 1.
+   * @param {number=8} headLength - (optional) The length of the arrow head (default is 8 pixels).
+   * @param {StrokeOptions=} strokeOptions - (optional) Stroke settings to use.
+   *
+   * @return {void}
+   * @instance
+   * @memberof DrawLib
+   **/
+  arrowHead(
+    zA: XYCoords,
+    zB: XYCoords,
+    color: string,
+    lineWidth?: number,
+    headLength: number = 8,
+    strokeOptions?: StrokeOptions
+  ): SVGElement {
+    const node: SVGElement = this.makeArrowHeadNode(zA, zB, color, lineWidth, headLength, strokeOptions);
+    return this._bindFillDraw(node, "arrowhead", color, lineWidth || 1, strokeOptions);
   }
 
   /**
@@ -601,14 +803,14 @@ export class drawutilssvg implements DrawLib<void | SVGElement> {
    *
    * @method image
    * @param {Image} image - The image object to draw.
-   * @param {Vertex} position - The position to draw the the upper left corner at.
-   * @param {Vertex} size - The x/y-size to draw the image with.
+   * @param {XYCoords} position - The position to draw the the upper left corner at.
+   * @param {XYCoords} size - The x/y-size to draw the image with.
    * @param {number=0.0} alpha - (optional, default=0.0) The transparency (1.0=opaque, 0.0=transparent).
    * @return {void}
    * @instance
    * @memberof drawutilssvg
    **/
-  image(image: HTMLImageElement, position: Vertex, size: Vertex, alpha: number = 1.0) {
+  image(image: HTMLImageElement, position: XYCoords, size: XYCoords, alpha: number = 1.0) {
     const node: SVGElement = this.makeNode("image");
 
     // We need to re-adjust the image if it was not yet fully loaded before.
@@ -618,7 +820,7 @@ export class drawutilssvg implements DrawLib<void | SVGElement> {
         const ratioY = size.y / image.naturalHeight;
         node.setAttribute("width", `${image.naturalWidth * this.scale.x}`);
         node.setAttribute("height", `${image.naturalHeight * this.scale.y}`);
-        node.setAttribute("display", null); // Dislay when loaded
+        node.setAttribute("display", null as any as string); // Dislay when loaded
         // if (alpha) {
         node.setAttribute("opacity", `${alpha}`);
         // }
@@ -648,7 +850,7 @@ export class drawutilssvg implements DrawLib<void | SVGElement> {
    * @param {Image} textureImage - The image object to draw.
    * @param {Bounds} textureSize - The texture size to use; these are the original bounds to map the polygon vertices to.
    * @param {Polygon} polygon - The polygon to use as clip path.
-   * @param {Vertex} polygonPosition - The polygon's position (relative), measured at the bounding box's center.
+   * @param {XYCoords} polygonPosition - The polygon's position (relative), measured at the bounding box's center.
    * @param {number} rotation - The rotation to use for the polygon (and for the texture).
    * @return {void}
    * @instance
@@ -658,12 +860,12 @@ export class drawutilssvg implements DrawLib<void | SVGElement> {
     textureImage: HTMLImageElement,
     textureSize: Bounds,
     polygon: Polygon,
-    polygonPosition: Vertex,
+    polygonPosition: XYCoords,
     rotation: number
   ): SVGElement {
-    const basePolygonBounds: Bounds = polygon.getBounds();
+    // const basePolygonBounds: Bounds = polygon.getBounds();
     const rotatedScalingOrigin = new Vertex(textureSize.min).clone().rotate(rotation, polygonPosition);
-    const rotationCenter = polygonPosition.clone().add(rotatedScalingOrigin.difference(textureSize.min).inv());
+    // const rotationCenter = polygonPosition.clone().add(rotatedScalingOrigin.difference(textureSize.min).inv());
     // Create something like this
     // ...
     //    <defs>
@@ -727,50 +929,37 @@ export class drawutilssvg implements DrawLib<void | SVGElement> {
    * Draw the given (cubic) bézier curve.
    *
    * @method cubicBezier
-   * @param {Vertex} startPoint - The start point of the cubic Bézier curve
-   * @param {Vertex} endPoint   - The end point the cubic Bézier curve.
-   * @param {Vertex} startControlPoint - The start control point the cubic Bézier curve.
-   * @param {Vertex} endControlPoint   - The end control point the cubic Bézier curve.
+   * @param {XYCoords} startPoint - The start point of the cubic Bézier curve
+   * @param {XYCoords} endPoint   - The end point the cubic Bézier curve.
+   * @param {XYCoords} startControlPoint - The start control point the cubic Bézier curve.
+   * @param {XYCoords} endControlPoint   - The end control point the cubic Bézier curve.
    * @param {string} color - The CSS color to draw the curve with.
    * @param {number} lineWidth - (optional) The line width to use.
+   * @param {StrokeOptions=} strokeOptions - (optional) Stroke settings to use.
+   *
    * @return {void}
    * @instance
    * @memberof drawutilssvg
    */
   cubicBezier(
-    startPoint: Vertex,
-    endPoint: Vertex,
-    startControlPoint: Vertex,
-    endControlPoint: Vertex,
+    startPoint: XYCoords,
+    endPoint: XYCoords,
+    startControlPoint: XYCoords,
+    endControlPoint: XYCoords,
     color: string,
-    lineWidth?: number
+    lineWidth?: number,
+    strokeOptions?: StrokeOptions
   ): SVGElement {
-    if (startPoint instanceof CubicBezierCurve) {
-      return this.cubicBezier(
-        startPoint.startPoint,
-        startPoint.endPoint,
-        startPoint.startControlPoint,
-        startPoint.endControlPoint,
-        color,
-        lineWidth
-      );
-    }
-    const node: SVGElement = this.makeNode("path");
-    // Draw curve
-    const d: Array<string | number> = [
-      "M",
-      this._x(startPoint.x),
-      this._y(startPoint.y),
-      "C",
-      this._x(startControlPoint.x),
-      this._y(startControlPoint.y),
-      this._x(endControlPoint.x),
-      this._y(endControlPoint.y),
-      this._x(endPoint.x),
-      this._y(endPoint.y)
-    ];
-    node.setAttribute("d", d.join(" "));
-    return this._bindFillDraw(node, "cubicBezier", color, lineWidth);
+    const node: SVGElement = this.makeCubicBezierNode(
+      startPoint,
+      endPoint,
+      startControlPoint,
+      endControlPoint,
+      color,
+      lineWidth,
+      strokeOptions
+    );
+    return this._bindNode(node, undefined);
   }
 
   /**
@@ -781,24 +970,29 @@ export class drawutilssvg implements DrawLib<void | SVGElement> {
    * <pre> [ point1, point1_startControl, point2_endControl, point2, point2_startControl, point3_endControl, point3, ... pointN_endControl, pointN ]</pre>
    *
    * @method cubicBezierPath
-   * @param {Vertex[]} path - The cubic bezier path as described above.
+   * @param {XYCoords[]} path - The cubic bezier path as described above.
    * @param {string} color - The CSS colot to draw the path with.
    * @param {number=1} lineWidth - (optional) The line width to use.
+   * @param {StrokeOptions=} strokeOptions - (optional) Stroke settings to use.
+   *
    * @return {void}
    * @instance
    * @memberof drawutilssvg
    */
-  cubicBezierPath(path: Array<Vertex>, color: string, lineWidth?: number): SVGElement {
+  cubicBezierPath(path: Array<XYCoords>, color: string, lineWidth?: number, strokeOptions?: StrokeOptions): SVGElement {
     const node: SVGElement = this.makeNode("path");
-    if (!path || path.length == 0) return node;
+    this.applyStrokeOpts(node, strokeOptions);
+    if (!path || path.length == 0) {
+      return node;
+    }
 
     // Draw curve
     const d: Array<string | number> = ["M", this._x(path[0].x), this._y(path[0].y)];
 
     // Draw curve path
-    var endPoint: Vertex;
-    var startControlPoint: Vertex;
-    var endControlPoint: Vertex;
+    var endPoint: XYCoords;
+    var startControlPoint: XYCoords;
+    var endControlPoint: XYCoords;
     for (var i = 1; i < path.length; i += 3) {
       startControlPoint = path[i];
       endControlPoint = path[i + 1];
@@ -829,7 +1023,7 @@ export class drawutilssvg implements DrawLib<void | SVGElement> {
    * @instance
    * @memberof drawutilssvg
    */
-  handle(startPoint: Vertex, endPoint: Vertex): void {
+  handle(startPoint: XYCoords, endPoint: XYCoords): void {
     // TODO: redefine methods like these into an abstract class?
     this.point(startPoint, "rgb(0,32,192)");
     this.square(endPoint, 5, "rgba(0,128,192,0.5)");
@@ -839,28 +1033,32 @@ export class drawutilssvg implements DrawLib<void | SVGElement> {
    * Draw a handle line (with a light grey).
    *
    * @method handleLine
-   * @param {Vertex} startPoint - The start point to draw the handle at.
-   * @param {Vertex} endPoint - The end point to draw the handle at.
+   * @param {XYCoords} startPoint - The start point to draw the handle at.
+   * @param {XYCoords} endPoint - The end point to draw the handle at.
    * @return {void}
    * @instance
    * @memberof drawutilssvg
    */
-  handleLine(startPoint: Vertex, endPoint: Vertex): void {
-    this.line(startPoint, endPoint, "rgb(192,192,192)");
+  handleLine(startPoint: XYCoords, endPoint: XYCoords): void {
+    this.line(startPoint, endPoint, "rgb(128,128,128,0.5)");
   }
 
   /**
    * Draw a 1x1 dot with the specified (CSS-) color.
    *
    * @method dot
-   * @param {Vertex} p - The position to draw the dot at.
+   * @param {XYCoords} p - The position to draw the dot at.
    * @param {string} color - The CSS color to draw the dot with.
    * @return {void}
    * @instance
    * @memberof drawutilssvg
    */
-  dot(p: Vertex, color: string) {
+  dot(p: XYCoords, color: string) {
     const node: SVGElement = this.makeNode("line");
+    node.setAttribute("x1", `${this._x(p.x)}`);
+    node.setAttribute("y1", `${this._y(p.y)}`);
+    node.setAttribute("x2", `${this._x(p.x)}`);
+    node.setAttribute("y2", `${this._y(p.y)}`);
     return this._bindFillDraw(node, "dot", color, 1);
   }
 
@@ -868,13 +1066,13 @@ export class drawutilssvg implements DrawLib<void | SVGElement> {
    * Draw the given point with the specified (CSS-) color and radius 3.
    *
    * @method point
-   * @param {Vertex} p - The position to draw the point at.
+   * @param {XYCoords} p - The position to draw the point at.
    * @param {string} color - The CSS color to draw the point with.
    * @return {void}
    * @instance
    * @memberof drawutilssvg
    */
-  point(p: Vertex, color: string) {
+  point(p: XYCoords, color: string) {
     var radius: number = 3;
     const node: SVGElement = this.makeNode("circle");
     node.setAttribute("cx", `${this._x(p.x)}`);
@@ -889,17 +1087,21 @@ export class drawutilssvg implements DrawLib<void | SVGElement> {
    * Note that if the x- and y- scales are different the result will be an ellipse rather than a circle.
    *
    * @method circle
-   * @param {Vertex} center - The center of the circle.
+   * @param {XYCoords} center - The center of the circle.
    * @param {number} radius - The radius of the circle.
    * @param {string} color - The CSS color to draw the circle with.
    * @param {number=} lineWidth - (optional) The line width to use; default is 1.
+   * @param {StrokeOptions=} strokeOptions - (optional) Stroke settings to use.
+   *
    * @return {void}
    * @instance
    * @memberof drawutilssvg
    */
-  circle(center: Vertex, radius: number, color: string, lineWidth?: number) {
+  circle(center: XYCoords, radius: number, color: string, lineWidth?: number, strokeOptions?: StrokeOptions) {
     // Todo: draw ellipse when scalex!=scaley
     const node: SVGElement = this.makeNode("circle");
+    this.applyStrokeOpts(node, strokeOptions);
+
     node.setAttribute("cx", `${this._x(center.x)}`);
     node.setAttribute("cy", `${this._y(center.y)}`);
     node.setAttribute("r", `${radius * this.scale.x}`); // y?
@@ -911,17 +1113,29 @@ export class drawutilssvg implements DrawLib<void | SVGElement> {
    * Draw a circular arc (section of a circle) with the given CSS color.
    *
    * @method circleArc
-   * @param {Vertex} center - The center of the circle.
+   * @param {XYCoords} center - The center of the circle.
    * @param {number} radius - The radius of the circle.
    * @param {number} startAngle - The angle to start at.
    * @param {number} endAngle - The angle to end at.
    * @param {string} color - The CSS color to draw the circle with.
+   * @param {StrokeOptions=} strokeOptions - (optional) Stroke settings to use.
+   *
    * @return {void}
    * @instance
    * @memberof drawutilssvg
    */
-  circleArc(center: Vertex, radius: number, startAngle: number, endAngle: number, color: string, lineWidth?: number) {
+  circleArc(
+    center: XYCoords,
+    radius: number,
+    startAngle: number,
+    endAngle: number,
+    color: string,
+    lineWidth?: number,
+    strokeOptions?: StrokeOptions
+  ) {
     const node: SVGElement = this.makeNode("path");
+    this.applyStrokeOpts(node, strokeOptions);
+
     const arcData: SVGPathParams = CircleSector.circleSectorUtils.describeSVGArc(
       this._x(center.x),
       this._y(center.y),
@@ -937,21 +1151,33 @@ export class drawutilssvg implements DrawLib<void | SVGElement> {
    * Draw an ellipse with the specified (CSS-) color and thw two radii.
    *
    * @method ellipse
-   * @param {Vertex} center - The center of the ellipse.
+   * @param {XYCoords} center - The center of the ellipse.
    * @param {number} radiusX - The radius of the ellipse.
    * @param {number} radiusY - The radius of the ellipse.
    * @param {string} color - The CSS color to draw the ellipse with.
    * @param {number=} lineWidth - (optional) The line width to use; default is 1.
    * @param {number=} rotation - (optional, default=0) The rotation of the ellipse.
+   * @param {StrokeOptions=} strokeOptions - (optional) Stroke settings to use.
+   *
    * @return {void}
    * @instance
    * @memberof drawutilssvg
    */
-  ellipse(center: Vertex, radiusX: number, radiusY: number, color: string, lineWidth?: number, rotation?: number) {
+  ellipse(
+    center: XYCoords,
+    radiusX: number,
+    radiusY: number,
+    color: string,
+    lineWidth?: number,
+    rotation?: number,
+    strokeOptions?: StrokeOptions
+  ) {
     if (typeof rotation === "undefined") {
       rotation = 0.0;
     }
     const node: SVGElement = this.makeNode("ellipse");
+    this.applyStrokeOpts(node, strokeOptions);
+
     node.setAttribute("cx", `${this._x(center.x)}`);
     node.setAttribute("cy", `${this._y(center.y)}`);
     node.setAttribute("rx", `${radiusX * this.scale.x}`);
@@ -969,15 +1195,19 @@ export class drawutilssvg implements DrawLib<void | SVGElement> {
    *
    * @method square
    * @param {XYCoords} center - The center of the square.
-   * @param {Vertex} size - The size of the square.
+   * @param {number} size - The size of the square.
    * @param {string} color - The CSS color to draw the square with.
    * @param {number=} lineWidth - (optional) The line width to use; default is 1.
-   * @return {void}
+   * @param {StrokeOptions=} strokeOptions - (optional) Stroke settings to use.
+   *
+   * @return {SVGElement}
    * @instance
    * @memberof drawutilssvg
    */
-  square(center: XYCoords, size: number, color: string, lineWidth?: number) {
+  square(center: XYCoords, size: number, color: string, lineWidth?: number, strokeOptions?: StrokeOptions): SVGElement {
     const node: SVGElement = this.makeNode("rectangle");
+    this.applyStrokeOpts(node, strokeOptions);
+
     node.setAttribute("x", `${this._x(center.x - size / 2.0)}`);
     node.setAttribute("y", `${this._y(center.y - size / 2.0)}`);
     node.setAttribute("width", `${size * this.scale.x}`);
@@ -994,9 +1224,23 @@ export class drawutilssvg implements DrawLib<void | SVGElement> {
    * @param {number} height - The height of the rectangle.
    * @param {string} color - The color to use.
    * @param {number=1} lineWidth - (optional) The line with to use (default is 1).
+   * @param {StrokeOptions=} strokeOptions - (optional) Stroke settings to use.
+   *
+   * @return {SVGElement}
+   * @instance
+   * @memberof drawutilssvg
    **/
-  rect(position: XYCoords, width: number, height: number, color: string, lineWidth?: number) {
+  rect(
+    position: XYCoords,
+    width: number,
+    height: number,
+    color: string,
+    lineWidth?: number,
+    strokeOptions?: StrokeOptions
+  ): SVGElement {
     const node: SVGElement = this.makeNode("rect");
+    this.applyStrokeOpts(node, strokeOptions);
+
     node.setAttribute("x", `${this._x(position.x)}`);
     node.setAttribute("y", `${this._y(position.y)}`);
     node.setAttribute("width", `${width * this.scale.x}`);
@@ -1009,7 +1253,7 @@ export class drawutilssvg implements DrawLib<void | SVGElement> {
    * Draw a grid of horizontal and vertical lines with the given (CSS-) color.
    *
    * @method grid
-   * @param {Vertex} center - The center of the grid.
+   * @param {XYCoords} center - The center of the grid.
    * @param {number} width - The total width of the grid (width/2 each to the left and to the right).
    * @param {number} height - The total height of the grid (height/2 each to the top and to the bottom).
    * @param {number} sizeX - The horizontal grid size.
@@ -1019,7 +1263,7 @@ export class drawutilssvg implements DrawLib<void | SVGElement> {
    * @instance
    * @memberof drawutilssvg
    */
-  grid(center: Vertex, width: number, height: number, sizeX: number, sizeY: number, color: string) {
+  grid(center: XYCoords, width: number, height: number, sizeX: number, sizeY: number, color: string) {
     const node: SVGElement = this.makeNode("path");
     const d: SVGPathParams = [];
 
@@ -1046,7 +1290,7 @@ export class drawutilssvg implements DrawLib<void | SVGElement> {
    * This works analogue to the grid() function
    *
    * @method raster
-   * @param {Vertex} center - The center of the raster.
+   * @param {XYCoords} center - The center of the raster.
    * @param {number} width - The total width of the raster (width/2 each to the left and to the right).
    * @param {number} height - The total height of the raster (height/2 each to the top and to the bottom).
    * @param {number} sizeX - The horizontal raster size.
@@ -1056,7 +1300,7 @@ export class drawutilssvg implements DrawLib<void | SVGElement> {
    * @instance
    * @memberof drawutilssvg
    */
-  raster(center: Vertex, width: number, height: number, sizeX: number, sizeY: number, color: string) {
+  raster(center: XYCoords, width: number, height: number, sizeX: number, sizeY: number, color: string) {
     const node: SVGElement = this.makeNode("path");
     const d: SVGPathParams = [];
 
@@ -1083,14 +1327,14 @@ export class drawutilssvg implements DrawLib<void | SVGElement> {
    * as even shaped diamonds.
    *
    * @method diamondHandle
-   * @param {Vertex} center - The center of the diamond.
-   * @param {Vertex} size - The x/y-size of the diamond.
+   * @param {XYCoords} center - The center of the diamond.
+   * @param {number} size - The x/y-size of the diamond.
    * @param {string} color - The CSS color to draw the diamond with.
    * @return {void}
    * @instance
    * @memberof drawutilssvg
    */
-  diamondHandle(center: Vertex, size: number, color: string) {
+  diamondHandle(center: XYCoords, size: number, color: string) {
     const node: SVGElement = this.makeNode("path");
     const d: SVGPathParams = [
       "M",
@@ -1119,14 +1363,14 @@ export class drawutilssvg implements DrawLib<void | SVGElement> {
    * as even shaped squares.
    *
    * @method squareHandle
-   * @param {Vertex} center - The center of the square.
-   * @param {Vertex} size - The x/y-size of the square.
+   * @param {XYCoords} center - The center of the square.
+   * @param {XYCoords} size - The x/y-size of the square.
    * @param {string} color - The CSS color to draw the square with.
    * @return {void}
    * @instance
    * @memberof drawutilssvg
    */
-  squareHandle(center: Vertex, size: number, color: string) {
+  squareHandle(center: XYCoords, size: number, color: string) {
     const node: SVGElement = this.makeNode("rect");
     node.setAttribute("x", `${this._x(center.x) - size / 2.0}`);
     node.setAttribute("y", `${this._y(center.y) - size / 2.0}`);
@@ -1143,14 +1387,14 @@ export class drawutilssvg implements DrawLib<void | SVGElement> {
    * as even shaped circles.
    *
    * @method circleHandle
-   * @param {Vertex} center - The center of the circle.
+   * @param {XYCoords} center - The center of the circle.
    * @param {number} radius - The radius of the circle.
    * @param {string} color - The CSS color to draw the circle with.
    * @return {void}
    * @instance
    * @memberof drawutilssvg
    */
-  circleHandle(center: Vertex, radius: number, color: string) {
+  circleHandle(center: XYCoords, radius: number, color: string) {
     radius = radius || 3;
 
     const node: SVGElement = this.makeNode("circle");
@@ -1247,17 +1491,29 @@ export class drawutilssvg implements DrawLib<void | SVGElement> {
    * Draw a polygon line (alternative function to the polygon).
    *
    * @method polyline
-   * @param {Vertex[]} vertices - The polygon vertices to draw.
+   * @param {XYCoords[]} vertices - The polygon vertices to draw.
    * @param {boolan}   isOpen   - If true the polyline will not be closed at its end.
    * @param {string}   color    - The CSS color to draw the polygon with.
    * @param {number=} lineWidth - (optional) The line width to use; default is 1.
+   * @param {StrokeOptions=} strokeOptions - (optional) Stroke settings to use.
+   *
    * @return {void}
    * @instance
    * @memberof drawutilssvg
    */
-  polyline(vertices: Array<Vertex>, isOpen: boolean, color: string, lineWidth?: number): SVGElement {
+  polyline(
+    vertices: Array<XYCoords>,
+    isOpen: boolean,
+    color: string,
+    lineWidth?: number,
+    strokeOptions?: StrokeOptions
+  ): SVGElement {
     const node: SVGElement = this.makeNode("path");
-    if (vertices.length == 0) return node;
+    this.applyStrokeOpts(node, strokeOptions);
+
+    if (vertices.length == 0) {
+      return node;
+    }
     // Draw curve
     const d: Array<string | number> = ["M", this._x(vertices[0].x), this._y(vertices[0].y)];
     var n = vertices.length;
@@ -1380,12 +1636,17 @@ export class drawutilssvg implements DrawLib<void | SVGElement> {
    * @param {string=null} color - (optional) The color to draw this path with (default is null).
    * @param {number=1} lineWidth - (optional) the line width to use (default is 1).
    * @param {boolean=false} options.inplace - (optional) If set to true then path transforamtions (scale and translate) will be done in-place in the array. This can boost the performance.
+   * @param {number=} options.dashOffset - (optional) `See StrokeOptions`.
+   * @param {number=[]} options.dashArray - (optional) `See StrokeOptions`.
+   *
    * @instance
    * @memberof drawutils
    * @return {R} An instance representing the drawn path.
    */
-  path(pathData: SVGPathParams, color?: string, lineWidth?: number, options?: { inplace?: boolean }): SVGElement {
+  path(pathData: SVGPathParams, color?: string, lineWidth?: number, options?: { inplace?: boolean } & StrokeOptions): SVGElement {
     const node: SVGElement = this.makeNode("path");
+    this.applyStrokeOpts(node, options);
+
     // Transform the path: in-place (fast) or copy (slower)
     const d: SVGPathParams = options && options.inplace ? pathData : drawutilssvg.copyPathData(pathData);
     drawutilssvg.transformPathData(d, this.offset, this.scale);
@@ -1413,7 +1674,7 @@ export class drawutilssvg implements DrawLib<void | SVGElement> {
 
     // Add a covering rect with the given background color
     this.curId = "background";
-    this.curClassName = undefined;
+    this.curClassName = null; // undefined;
     const node: SVGElement = this.makeNode("rect");
     // For some strange reason SVG rotation transforms use degrees instead of radians
     // Note that the background does not scale with the zoom level (always covers full element)
@@ -1426,7 +1687,7 @@ export class drawutilssvg implements DrawLib<void | SVGElement> {
     this._bindFillDraw(node, this.curId, null, null);
     node.setAttribute("fill", typeof color === "undefined" ? "none" : color);
     // Clear the current ID again
-    this.curId = undefined;
+    this.curId = null; // undefined;
   }
 
   /**
@@ -1637,4 +1898,165 @@ export class drawutilssvg implements DrawLib<void | SVGElement> {
       }
     } // END while
   } // END transformPathData
+
+  private static nodeSupportsLineDash(nodeName: string) {
+    return ["line", "path", "circle", "ellipse", "rectangle", "rect"].includes(nodeName);
+  }
+
+  /**
+   * Creates a basic <line> node with start and end coordinates. The created node will not
+   * be bound to any root node.
+   *
+   * @private
+   * @method makeLineNode
+   * @param {XYCoords} zA - The line's start position.
+   * @param {XYCoords} zB - The line's start position.
+   * @param {string} color - The CSS color to draw the point with.
+   * @param {number=1} lineWidth - (optional) The line width to use.
+   * @param {StrokeOptions=} strokeOptions - (optional) Additional stroke options to use.
+   * @param {string=} classNameOverride - (optional) If nothing is passed the default classname 'path' will be used.
+   * @return {SVGLineElement}
+   * @instance
+   * @memberof drawutilssvg
+   */
+  private makeLineNode(
+    zA: XYCoords,
+    zB: XYCoords,
+    color: string,
+    lineWidth?: number,
+    strokeOptions?: StrokeOptions,
+    classNameOverride?: string
+  ): SVGLineElement {
+    const line: SVGLineElement = this.makeNode("line") as SVGLineElement;
+    line.setAttribute("x1", `${this._x(zA.x)}`);
+    line.setAttribute("y1", `${this._y(zA.y)}`);
+    line.setAttribute("x2", `${this._x(zB.x)}`);
+    line.setAttribute("y2", `${this._y(zB.y)}`);
+    this._configureNode(line, classNameOverride ?? "line", this.fillShapes, color, lineWidth || 1, strokeOptions);
+    return line;
+  }
+
+  /**
+   * Creates a basic <path> node with given path string data. The created node will not
+   * be bound to any root node.
+   *
+   * @private
+   * @method makePathNode
+   * @param {string} pathString - The path data (must be a valid path data string).
+   * @param {string} color - The CSS color to draw the point with.
+   * @param {number=1} lineWidth - (optional) The line width to use.
+   * @param {StrokeOptions=} strokeOptions - (optional) Additional stroke options to use.
+   * @param {string=} classNameOverride - (optional) If nothing is passed the default classname 'path' will be used.
+   * @return {SVGPathElement}
+   * @instance
+   * @memberof drawutilssvg
+   */
+  private makePathNode(
+    pathString: string,
+    color: string,
+    lineWidth?: number,
+    strokeOptions?: StrokeOptions,
+    classNameOverride?: string
+  ): SVGPathElement {
+    const path: SVGPathElement = this.makeNode("path") as SVGPathElement;
+    path.setAttribute("d", pathString);
+    this._configureNode(path, classNameOverride ?? "path", this.fillShapes, color, lineWidth || 1, strokeOptions);
+    return path;
+  }
+
+  /**
+   * Creates a basic arrow head node (<path> node) at the end of the given line coordinates. The created node will not
+   * be bound to any root node.
+   *
+   * @private
+   * @method makeArrowHeadNode
+   * @param {string} pathString - The path data (must be a valid path data string).
+   * @param {string} color - The CSS color to draw the point with.
+   * @param {number=1} lineWidth - (optional) The line width to use.
+   * @param {number=8} headLength - (optional) The length of the arrow head; if none is specified then the head will be 8 absolute units long.
+   * @param {StrokeOptions=} strokeOptions - (optional) Additional stroke options to use.
+   * @param {XYCoords=} arrowHeadBasePositionBuffer - (optional) If not null, then this position will contain the arrow head's start point (after execution). Some sort of OUT variable.
+   * @return {SVGPathElement}
+   * @instance
+   * @memberof drawutilssvg
+   */
+  private makeArrowHeadNode(
+    zA: XYCoords,
+    zB: XYCoords,
+    color: string,
+    lineWidth?: number,
+    headLength: number = 8,
+    strokeOptions?: StrokeOptions,
+    arrowHeadBasePositionBuffer?: XYCoords
+  ): SVGPathElement {
+    var vertices: Array<Vertex> = Vector.utils.buildArrowHead(zA, zB, headLength, this.scale.x, this.scale.y);
+    const d: Array<string | number> = ["M", this.offset.x + vertices[0].x, this.offset.y + vertices[0].y];
+    if (arrowHeadBasePositionBuffer) {
+      arrowHeadBasePositionBuffer.x = vertices[0].x / this.scale.x;
+      arrowHeadBasePositionBuffer.y = vertices[0].y / this.scale.y;
+    }
+    for (var i = 1; i <= vertices.length; i++) {
+      d.push("L");
+      // Note: only use offset here (the vertices are already scaled)
+      d.push(this.offset.x + vertices[i % vertices.length].x);
+      d.push(this.offset.y + vertices[i % vertices.length].y);
+    }
+    const node: SVGPathElement = this.makePathNode(d.join(" "), color, lineWidth, strokeOptions, "arrowhead");
+    return node;
+  }
+
+  /**
+   * Creates a basic cubic Bézier path node (<path> node) with the given cubic Bézier data. The created node will not
+   * be bound to any root node.
+   *
+   * @private
+   * @method makeCubicBezierNode
+   * @param {XYCoords} startPoint - The start point of the cubic Bézier curve
+   * @param {XYCoords} endPoint   - The end point the cubic Bézier curve.
+   * @param {XYCoords} startControlPoint - The start control point the cubic Bézier curve.
+   * @param {XYCoords} endControlPoint   - The end control point the cubic Bézier curve.
+   * @param {string} color - The CSS color to draw the point with.
+   * @param {number=1} lineWidth - (optional) The line width to use.
+   * @param {StrokeOptions=} strokeOptions - (optional) Additional stroke options to use.
+   * @param {string=} classNameOverride - (optional) If nothing is passed the default classname 'path' will be used.
+   * @param {XYCoords=} arrowHeadBasePositionBuffer - (optional) If not null, then this position will contain the arrow head's start point (after execution). Some sort of OUT variable.
+   * @return {SVGPathElement}
+   * @instance
+   * @memberof drawutilssvg
+   */
+  private makeCubicBezierNode(
+    startPoint: XYCoords,
+    endPoint: XYCoords,
+    startControlPoint: XYCoords,
+    endControlPoint: XYCoords,
+    color: string,
+    lineWidth?: number,
+    strokeOptions?: StrokeOptions
+  ): SVGElement {
+    if (startPoint instanceof CubicBezierCurve) {
+      return this.cubicBezier(
+        startPoint.startPoint,
+        startPoint.endPoint,
+        startPoint.startControlPoint,
+        startPoint.endControlPoint,
+        color,
+        lineWidth
+      );
+    }
+    // Draw curve
+    const d: Array<string | number> = [
+      "M",
+      this._x(startPoint.x),
+      this._y(startPoint.y),
+      "C",
+      this._x(startControlPoint.x),
+      this._y(startControlPoint.y),
+      this._x(endControlPoint.x),
+      this._y(endControlPoint.y),
+      this._x(endPoint.x),
+      this._y(endPoint.y)
+    ];
+    const node: SVGElement = this.makePathNode(d.join(" "), color, lineWidth, strokeOptions, "cubicBezier");
+    return node;
+  }
 }