plotboilerplate 1.23.3 → 1.25.0

package/src/ts/utils/helpers/VEllipseSectorHelper.ts

@@ -1,60 +1,178 @@
 /**
  * A helper for VEllipseSectors.
  *
- * @author  Ikaros Kappler
- * @date    2021-03-24
- * @version 1.0.0
+ * @author   Ikaros Kappler
+ * @date     2021-03-24
+ * @modified 2025-04-02 Adding `VEllipseSectorHelper.drawHandleLines`.
+ * @modified 2025-04-07 Modifying the calculation of `startAngle` and `endAngle` from the rotation control point: wrapping result into [0,TWO_PI).
+ * @modified 2025-04-09 Adding the `VEllipseSectorHelper.destroy` method.
+ * @modified 2025-05-05 `VEllipseSectorHelper` is now implementing `IShapeInteractionHelper`.
+ * @version  1.1.0
  */
 
 import { Line } from "../../Line";
 import { VEllipseSector } from "../../VEllipseSector";
 import { Vertex } from "../../Vertex";
-import { VertEvent } from "../../VertexListeners";
+import { VertEvent, VertListener } from "../../VertexListeners";
+import { geomutils } from "../../geomutils";
+import { DrawLib, IShapeInteractionHelper } from "../../interfaces";
+
+export class VEllipseSectorHelper implements IShapeInteractionHelper {
+  private sector: VEllipseSector;
+  private startAngleControlPoint: Vertex;
+  private endAngleControlPoint: Vertex;
+  private rotationControlPoint: Vertex;
+
+  private _rotationControlLine: Line;
+  private _startAngleControlLine: Line;
+  private _endAngleControlLine: Line;
+
+  private _centerHandler: VertListener;
+  private _rotationHandler: VertListener;
+  private _startAngleHandler: VertListener;
+  private _endAngleHandler: VertListener;
 
-export class VEllipseSectorHelper {
   constructor(
     sector: VEllipseSector,
     startAngleControlPoint: Vertex,
     endAngleControlPoint: Vertex,
     rotationControlPoint: Vertex
   ) {
-    const rotationControlLine: Line = new Line(sector.ellipse.center, rotationControlPoint);
-    const startAngleControlLine: Line = new Line(sector.ellipse.center, startAngleControlPoint);
-    const endAngleControlLine: Line = new Line(sector.ellipse.center, endAngleControlPoint);
+    this.sector = sector;
+    this.startAngleControlPoint = startAngleControlPoint;
+    this.endAngleControlPoint = endAngleControlPoint;
+    this.rotationControlPoint = rotationControlPoint;
+
+    // const rotationControlLine: Line = new Line(sector.ellipse.center, rotationControlPoint);
+    this._rotationControlLine = new Line(sector.ellipse.center, rotationControlPoint);
+    // const startAngleControlLine: Line = new Line(sector.ellipse.center, startAngleControlPoint);
+    this._startAngleControlLine = new Line(sector.ellipse.center, startAngleControlPoint);
+    // const endAngleControlLine: Line = new Line(sector.ellipse.center, endAngleControlPoint);
+    this._endAngleControlLine = new Line(sector.ellipse.center, endAngleControlPoint);
 
     // +---------------------------------------------------------------------
     // | Listen for the center to be moved.
     // +-------------------------------------------
-    sector.ellipse.center.listeners.addDragListener((event: VertEvent) => {
-      startAngleControlPoint.add(event.params.dragAmount);
-      endAngleControlPoint.add(event.params.dragAmount);
-      rotationControlPoint.add(event.params.dragAmount);
-    });
+    sector.ellipse.center.listeners.addDragListener((this._centerHandler = this._handleDragCenterPoint()));
 
     // +---------------------------------------------------------------------
     // | Listen for rotation changes.
     // +-------------------------------------------
-    rotationControlPoint.listeners.addDragListener((event: VertEvent) => {
-      var newRotation = rotationControlLine.angle();
-      var rDiff = newRotation - sector.ellipse.rotation;
-      sector.ellipse.rotation = newRotation;
-      sector.ellipse.axis.rotate(rDiff, sector.ellipse.center);
-      startAngleControlPoint.rotate(rDiff, sector.ellipse.center);
-      endAngleControlPoint.rotate(rDiff, sector.ellipse.center);
-    });
+    rotationControlPoint.listeners.addDragListener((this._rotationHandler = this._handleDragRotationControlPoint()));
 
     // +---------------------------------------------------------------------
     // | Listen for start angle changes.
     // +-------------------------------------------
-    startAngleControlPoint.listeners.addDragListener((event: VertEvent) => {
-      sector.startAngle = startAngleControlLine.angle() - sector.ellipse.rotation;
-    });
+    startAngleControlPoint.listeners.addDragListener((this._startAngleHandler = this._handleDragStartAngleControlPoint()));
 
     // +---------------------------------------------------------------------
     // | Listen for end angle changes.
     // +-------------------------------------------
-    endAngleControlPoint.listeners.addDragListener((event: VertEvent) => {
-      sector.endAngle = endAngleControlLine.angle() - sector.ellipse.rotation;
+    endAngleControlPoint.listeners.addDragListener((this._endAngleHandler = this._handleDragEndAngleControlPoint()));
+  }
+
+  /**
+   * Creates a new drag handler for the circle sector's start control point.
+   *
+   * @private
+   * @method _handleDragStartControlPoint
+   * @instance
+   * @memberof CircleSectorHelper
+   * @returns A new event handler.
+   */
+  private _handleDragCenterPoint(): VertListener {
+    const _self = this;
+    return (event: VertEvent) => {
+      _self.startAngleControlPoint.add(event.params.dragAmount);
+      _self.endAngleControlPoint.add(event.params.dragAmount);
+      _self.rotationControlPoint.add(event.params.dragAmount);
+    };
+  }
+
+  private _handleDragRotationControlPoint(): VertListener {
+    const _self = this;
+    return (event: VertEvent) => {
+      const newRotation: number = _self._rotationControlLine.angle();
+      const rDiff: number = newRotation - _self.sector.ellipse.rotation;
+      _self.sector.ellipse.rotation = newRotation;
+      _self.sector.ellipse.axis.rotate(rDiff, _self.sector.ellipse.center);
+      _self.startAngleControlPoint.rotate(rDiff, _self.sector.ellipse.center);
+      _self.endAngleControlPoint.rotate(rDiff, _self.sector.ellipse.center);
+    };
+  }
+
+  private _handleDragStartAngleControlPoint(): VertListener {
+    const _self = this;
+    return (_event: VertEvent) => {
+      // sector.startAngle = startAngleControlLine.angle() - sector.ellipse.rotation;
+      _self.sector.startAngle = geomutils.mapAngleTo2PI(_self._startAngleControlLine.angle() - _self.sector.ellipse.rotation);
+    };
+  }
+
+  private _handleDragEndAngleControlPoint(): VertListener {
+    const _self = this;
+
+    return (event: VertEvent) => {
+      _self.sector.endAngle = geomutils.mapAngleTo2PI(_self._endAngleControlLine.angle() - _self.sector.ellipse.rotation);
+    };
+  }
+
+  /**
+   * Draw grey handle lines.
+   *
+   * @param {DrawLib<any>} draw - The draw library instance to use.
+   * @param {DrawLib<any>} fill - The fill library instance to use.
+   */
+  drawHandleLines(draw: DrawLib<any>, fill: DrawLib<any>) {
+    draw.line(this.sector.ellipse.center, this.startAngleControlPoint, "rgba(64,192,128,0.333)", 1.0, {
+      dashOffset: 0.0,
+      dashArray: [4, 2]
+    });
+    draw.line(this.sector.ellipse.center, this.endAngleControlPoint, "rgba(64,192,128,0.333)", 1.0, {
+      dashOffset: 0.0,
+      dashArray: [4, 2]
     });
+    // Draw rotation handle line
+    draw.line(this.sector.ellipse.center, this.rotationControlPoint, "rgba(192,64,128,0.333)", 1.0, {
+      dashOffset: 0.0,
+      dashArray: [4, 2]
+    });
+    // Draw helper box
+    draw.line(
+      this.sector.ellipse.center
+        .clone()
+        .add(0, this.sector.ellipse.signedRadiusV())
+        .rotate(this.sector.ellipse.rotation, this.sector.ellipse.center),
+      this.sector.ellipse.axis,
+      "rgba(64,128,192,0.333)",
+      1.0,
+      {
+        dashOffset: 0.0,
+        dashArray: [4, 2]
+      }
+    );
+    draw.line(
+      this.sector.ellipse.center
+        .clone()
+        .add(this.sector.ellipse.signedRadiusH(), 0)
+        .rotate(this.sector.ellipse.rotation, this.sector.ellipse.center),
+      this.sector.ellipse.axis,
+      "rgba(64,128,192,0.333)",
+      1.0,
+      {
+        dashOffset: 0.0,
+        dashArray: [4, 2]
+      }
+    );
+  } // END drawHandleLines
+
+  /**
+   * Destroy this VEllipseHandler which means: all listeners are being removed.
+   */
+  destroy(): void {
+    this.sector.ellipse.center.listeners.removeDragListener(this._centerHandler);
+    this.rotationControlPoint.listeners.removeDragListener(this._rotationHandler);
+    this.startAngleControlPoint.listeners.removeDragListener(this._startAngleHandler);
+    this.endAngleControlPoint.listeners.removeDragListener(this._endAngleHandler);
   }
 }

package/src/ts/utils/parsers/LinearColorGradientParser.ts

@@ -0,0 +1,297 @@
+/**
+ * A CSS gradient string parser.
+ *
+ * Source:
+ *  https://stackoverflow.com/questions/20215440/parse-css-gradient-rule-with-javascript-regex
+ * Thanks to Dean Taylor
+ *
+ * @date           2025-09-04
+ * @OriginalAuthor Dean Taylor
+ * @RefactoredBy   Ikaros Kappler, ported to Typescript.
+ * @version        1.0.0
+ */
+
+import { Color } from "../datastructures/Color";
+import { ColorGradient, ColorGradientItem, ColorGradientRotation } from "../datastructures/ColorGradient";
+
+/**
+ * A wrapper type for the regular expressions used to parsed gradient strings.
+ */
+export type ColorGradientParserRegExpLib = {
+  gradientSearch: RegExp;
+  colorStopSearch: RegExp;
+};
+
+/**
+ * The raw parse result.
+ */
+export type ColorGradientParseResult = {
+  original: string;
+  line: string;
+  angle: string;
+  colorStopList: ColorGradientStopResult[];
+  sideCorner: string;
+  gradientType?: string;
+  parseWarning?: boolean;
+};
+
+/**
+ * The position string can have two formats: as percent or as pixels.
+ * For conversion to LinearColorGradient only relative (percent) is supported.
+ */
+type PositionString = `${number}px` | `${number}%`;
+
+/**
+ * A sub type of the result representing pairs of (color,position) elements.
+ */
+type ColorGradientStopResult = {
+  color: string;
+  position: PositionString; // '56.5%' or '20px'
+};
+
+/**
+ * This must convert positioning strings to ratio numbers (in [0..1]).
+ * Must throw error if not parsable.
+ */
+export type PositionToRatioConverter = (positionString: PositionString) => number;
+
+/**
+ * The default implementation of `PositionToRatioConverter`.
+ * @param positionString
+ * @returns
+ */
+export const DefaultPositionConverter: PositionToRatioConverter = (positionString: PositionString): number => {
+  if (typeof positionString === "undefined") {
+    throw new Error("Cannot parse positioning string `null`.");
+  }
+  const tmp: string = positionString.trim();
+  if (tmp.length === 0) {
+    throw new Error('Cannot parse empty positioning string "".');
+  }
+  if (!tmp.endsWith("%")) {
+    throw new Error(`Cannot parse positioning string, must end with '%': '${tmp}'`);
+  }
+  return Number.parseFloat(tmp) / 100.0;
+};
+
+/**
+ * Utility combine multiple regular expressions.
+ *
+ * Source:
+ *  https://stackoverflow.com/questions/20215440/parse-css-gradient-rule-with-javascript-regex
+ * Thanks to Dean Taylor
+ *
+ * @param {Array<RegExp | string>} regexpList List of regular expressions or strings.
+ * @param {string} flags Normal RegExp flags.
+ */
+const __combineRegExp = (regexpList: Array<RegExp | string>, flags: string): RegExp => {
+  var source: string = "";
+  for (var i = 0; i < regexpList.length; i++) {
+    const regex = regexpList[i];
+    if (typeof regex === "string") {
+      source += regex;
+    } else {
+      source += regex.source;
+    }
+  }
+  return new RegExp(source, flags);
+};
+
+/**
+ * Generate the required regular expressions once.
+ *
+ * Regular Expressions are easier to manage this way and can be well described.
+ *
+ * @result {object} Object containing regular expressions.
+ */
+const __generateDefaultRegExpLib = (): ColorGradientParserRegExpLib => {
+  // Note any variables with "Capture" in name include capturing bracket set(s).
+  const searchFlags = "gi", // ignore case for angles, "rgb" etc
+    rAngle = /(?:[+-]?\d*\.?\d+)(?:deg|grad|rad|turn)/, // Angle +ive, -ive and angle types
+    rSideCornerCapture = /to\s+((?:(?:left|right)(?:\s+(?:top|bottom))?))/, // optional 2nd part
+    rComma = /\s*,\s*/, // Allow space around comma.
+    rColorHex = /\#(?:[a-f0-9]{6}|[a-f0-9]{3})/, // 3 or 6 character form
+    rDigits3 = /\(\s*(?:\d{1,3}\s*,\s*){2}\d{1,3}\s*\)/, // "(1, 2, 3)"
+    rDigits4 = /\(\s*(?:\d{1,3}\s*,\s*){2}\d{1,3}\s*,\s*\d*\.?\d+\)/, // "(1, 2, 3, 4)"
+    rValue = /(?:[+-]?\d*\.?\d+)(?:%|[a-z]+)?/, // ".9", "-5px", "100%".
+    rKeyword = /[_a-z-][_a-z0-9-]*/, // "red", "transparent", "border-collapse".
+    rColor = __combineRegExp(
+      ["(?:", rColorHex, "|", "(?:rgb|hsl)", rDigits3, "|", "(?:rgba|hsla)", rDigits4, "|", rKeyword, ")"],
+      ""
+    ),
+    rColorStop = __combineRegExp([rColor, "(?:\\s+", rValue, "(?:\\s+", rValue, ")?)?"], ""), // Single Color Stop, optional %, optional length.
+    rColorStopList = __combineRegExp(["(?:", rColorStop, rComma, ")*", rColorStop], ""), // List of color stops min 1.
+    rLineCapture = __combineRegExp(["(?:(", rAngle, ")|", rSideCornerCapture, ")"], ""), // Angle or SideCorner
+    rGradientSearch = __combineRegExp(["(?:(", rLineCapture, ")", rComma, ")?(", rColorStopList, ")"], searchFlags), // Capture 1:"line", 2:"angle" (optional), 3:"side corner" (optional) and 4:"stop list".
+    rColorStopSearch = __combineRegExp(
+      ["\\s*(", rColor, ")", "(?:\\s+", "(", rValue, "))?", "(?:", rComma, "\\s*)?"],
+      searchFlags
+    ); // Capture 1:"color" and 2:"position" (optional).
+
+  return {
+    gradientSearch: rGradientSearch,
+    colorStopSearch: rColorStopSearch
+  };
+};
+
+/**
+ * Actually parse the input gradient parameters string into an object for reusability.
+ *
+ *
+ * @note Really this only supports the standard syntax not historical versions, see MDN for details
+ *       https://developer.mozilla.org/en-US/docs/Web/CSS/linear-gradient
+ *
+ * @param {ColorGradientParserRegExpLib} regExpLib
+ * @param {string} input Input string in the form "to right bottom, #FF0 0%, red 20px, rgb(0, 0, 255) 100%"
+ * @returns {object|undefined} Object containing break down of input string including array of stop points.
+ */
+export var __parseGradient = (regExpLib: ColorGradientParserRegExpLib, input: string): ColorGradientParseResult => {
+  var result: ColorGradientParseResult;
+  var matchGradient: RegExpExecArray, matchColorStop: string[], stopResult: ColorGradientStopResult;
+
+  // reset search position, because we reuse regex.
+  regExpLib.gradientSearch.lastIndex = 0;
+
+  matchGradient = regExpLib.gradientSearch.exec(input);
+  if (matchGradient !== null) {
+    result = {
+      original: matchGradient[0],
+      colorStopList: [],
+      line: null,
+      angle: null,
+      sideCorner: null
+    };
+
+    // Line (Angle or Side-Corner).
+    if (!!matchGradient[1]) {
+      result.line = matchGradient[1];
+    }
+    // Angle or undefined if side-corner.
+    if (!!matchGradient[2]) {
+      result.angle = matchGradient[2];
+    }
+    // Side-corner or undefined if angle.
+    if (!!matchGradient[3]) {
+      result.sideCorner = matchGradient[3];
+    }
+
+    // reset search position, because we reuse regex.
+    regExpLib.colorStopSearch.lastIndex = 0;
+
+    // Loop though all the color-stops.
+    matchColorStop = regExpLib.colorStopSearch.exec(matchGradient[4]);
+    while (matchColorStop !== null) {
+      stopResult = {
+        color: matchColorStop[1],
+        position: null
+      };
+
+      // Position (optional).
+      if (!!matchColorStop[2]) {
+        stopResult.position = matchColorStop[2] as PositionString;
+      }
+      result.colorStopList.push(stopResult);
+
+      // Continue searching from previous position.
+      matchColorStop = regExpLib.colorStopSearch.exec(matchGradient[4]);
+    }
+  }
+
+  // Can be undefined if match not found.
+  return result;
+};
+
+/**
+ * The actual parser class.
+ */
+export class LinearColorGradientParser {
+  private readonly regExpLib: ColorGradientParserRegExpLib;
+
+  constructor(regExpLib?: ColorGradientParserRegExpLib) {
+    this.regExpLib = regExpLib || __generateDefaultRegExpLib();
+  }
+
+  public parse(input: string, positionConverter?: PositionToRatioConverter): ColorGradient {
+    const result: ColorGradientParseResult = this.parseRaw(input);
+
+    return LinearColorGradientParser.parseResultToColorGradient(result, positionConverter);
+  }
+
+  public parseRaw(input: string): ColorGradientParseResult {
+    var result: ColorGradientParseResult;
+    const rGradientEnclosedInBrackets: RegExp = /.*gradient\s*\(((?:\([^\)]*\)|[^\)\(]*)*)\)/; // Captures inside brackets - max one additional inner set.
+    const match: RegExpExecArray = rGradientEnclosedInBrackets.exec(input);
+
+    const bracketPos = input.indexOf("(");
+    const gradientType = bracketPos === -1 ? null : input.substring(0, bracketPos).toLowerCase();
+
+    if (match !== null) {
+      // Get the parameters for the gradient
+      result = __parseGradient(this.regExpLib, match[1]);
+      result.gradientType = gradientType;
+      if (result.original.trim() !== match[1].trim()) {
+        // Did not match the input exactly - possible parsing error.
+        result.parseWarning = true;
+      }
+    } else {
+      //   result = new Error("Failed to find gradient");
+      throw new Error("Failed to find gradient");
+    }
+
+    return result;
+  }
+
+  public static parseResultToColorGradient(
+    result: ColorGradientParseResult,
+    positionConverter?: PositionToRatioConverter
+  ): ColorGradient {
+    if (!result.gradientType || result.gradientType.toLowerCase() != "linear-gradient") {
+      throw new Error(`Cannot create linear gradient from type '${result.gradientType}'.`);
+    }
+
+    if (!result.colorStopList || result.colorStopList.length <= 1) {
+      throw new Error(
+        `Cannot create linear gradient from color stop list of length '${result.colorStopList.length}'. Too few elements.`
+      );
+    }
+
+    const colorStops: Array<ColorGradientItem> = [];
+    const converter: PositionToRatioConverter = positionConverter ?? DefaultPositionConverter;
+    for (var i = 0; i < result.colorStopList.length; i++) {
+      const stopListItem: ColorGradientStopResult = result.colorStopList[i];
+      console.log(stopListItem);
+      const color = Color.parse(stopListItem.color);
+
+      // var position: number = LinearColorGradientParser.parsePosition(stopListItem.position);
+      var ratio: number;
+      if (typeof stopListItem.position === "undefined") {
+        // Try to auto-fill undefined positions by their index in the list.
+        ratio = i / (result.colorStopList.length - 1);
+      } else {
+        ratio = converter(stopListItem.position);
+      }
+      colorStops.push({ color: color, ratio: ratio });
+    }
+
+    return new ColorGradient(colorStops, result.line as ColorGradientRotation);
+  }
+} // END class
+
+// var test_this_one = function (regExpLib, input) {
+//   var result,
+//     rGradientEnclosedInBrackets = /.*gradient\s*\(((?:\([^\)]*\)|[^\)\(]*)*)\)/, // Captures inside brackets - max one additional inner set.
+//     match = rGradientEnclosedInBrackets.exec(input);
+
+//   if (match !== null) {
+//     // Get the parameters for the gradient
+//     result = parseGradient(regExpLib, match[1]);
+//     if (result.original.trim() !== match[1].trim()) {
+//       // Did not match the input exactly - possible parsing error.
+//       result.parseWarning = true;
+//     }
+//   } else {
+//     result = "Failed to find gradient";
+//   }
+
+//   return result;
+// };