plotboilerplate 1.27.0 → 1.28.0

package/src/_esm/src/ts/utils/dom/guiSizeToggler.js

@@ -0,0 +1,40 @@
+/**
+ * @requires lil-gui
+ *
+ * @author   Ikaros Kappler
+ * @date     2021-12-13
+ * @modified 2022-01-10
+ * @modified 2024-06-25 Ported to typescript and moved to utils/dom (was located inside demos before).
+ * @modified 2024-10-02 Added a transition time.
+ * @version  1.1.1
+ */
+/**
+ * @param {GUI} gui - The GUI (compatible with dat.gui and lil-gui).
+ * @param {boolean} guiDoubleSize - True or false.
+ * @param {Record<string,string>} cssProps - The CSS props to use.
+ */
+const applyGuiSize = (gui, guiDoubleSize, cssProps) => {
+    if (cssProps && cssProps.hasOwnProperty("transformOrigin")) {
+        gui.domElement.style["transform-origin"] = cssProps["transformOrigin"];
+    }
+    else {
+        gui.domElement.style["transform-origin"] = "100% 0%";
+    }
+    const transform = cssProps && cssProps.hasOwnProperty("transform") ? cssProps["transform"] + " " : "";
+    // console.log("transform", transform);
+    if (guiDoubleSize) {
+        gui.domElement.style["transform"] = transform + "scale(2.0)";
+    }
+    else {
+        gui.domElement.style["transform"] = transform + "scale(1.0)";
+    }
+};
+export const guiSizeToggler = (gui, config, cssProps) => {
+    gui.domElement.style["transition"] = "transform 0.5s";
+    return {
+        update: function () {
+            applyGuiSize(gui, Boolean(config.guiDoubleSize), cssProps);
+        }
+    };
+};
+//# sourceMappingURL=guiSizeToggler.js.map

package/src/_esm/src/ts/utils/dom/guiSizeToggler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"guiSizeToggler.js","sourceRoot":"","sources":["../../../../../ts/utils/dom/guiSizeToggler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAQH;;;;GAIG;AACH,MAAM,YAAY,GAAG,CAAC,GAAQ,EAAE,aAAsB,EAAE,QAAgC,EAAE,EAAE;IAC1F,IAAI,QAAQ,IAAI,QAAQ,CAAC,cAAc,CAAC,iBAAiB,CAAC,EAAE,CAAC;QAC3D,GAAG,CAAC,UAAU,CAAC,KAAK,CAAC,kBAAkB,CAAC,GAAG,QAAQ,CAAC,iBAAiB,CAAC,CAAC;IACzE,CAAC;SAAM,CAAC;QACN,GAAG,CAAC,UAAU,CAAC,KAAK,CAAC,kBAAkB,CAAC,GAAG,SAAS,CAAC;IACvD,CAAC;IAED,MAAM,SAAS,GAAG,QAAQ,IAAI,QAAQ,CAAC,cAAc,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;IAEtG,uCAAuC;IACvC,IAAI,aAAa,EAAE,CAAC;QAClB,GAAG,CAAC,UAAU,CAAC,KAAK,CAAC,WAAW,CAAC,GAAG,SAAS,GAAG,YAAY,CAAC;IAC/D,CAAC;SAAM,CAAC;QACN,GAAG,CAAC,UAAU,CAAC,KAAK,CAAC,WAAW,CAAC,GAAG,SAAS,GAAG,YAAY,CAAC;IAC/D,CAAC;AACH,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,GAAQ,EAAE,MAAsB,EAAE,QAAgC,EAAE,EAAE;IACnG,GAAG,CAAC,UAAU,CAAC,KAAK,CAAC,YAAY,CAAC,GAAG,gBAAgB,CAAC;IACtD,OAAO;QACL,MAAM,EAAE;YACN,YAAY,CAAC,GAAG,EAAE,OAAO,CAAC,MAAM,CAAC,aAAa,CAAC,EAAE,QAAQ,CAAC,CAAC;QAC7D,CAAC;KACF,CAAC;AACJ,CAAC,CAAC"}

package/src/_esm/src/ts/utils/findInVertexArray.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @author  Ikaros Kappler
+ * @date    2022-01-10
+ * @version 1.0.0
+ */
+import { Vertex } from "../Vertex";
+import { XYCoords } from "../interfaces";
+/**
+ * In an array of vertices find the first occurence of a specific vertex, using
+ * and epsilon tolerance.
+ *
+ * @param {Array<Vertex>} vertexList - The vertex array to search in.
+ * @param {XYCoords} vertex - A vertex/position to search for. This can be any x-y-tuple and does not
+ *                              necessarily need to be an instance of Vertex.
+ * @param {number} epsilon - The epsilon tolerance to use (should be >= 0). This is a required param to avoid excessive
+ *                              is-undef checking if this function runs in a loop.
+ * @returns {boolean} - The first index of a vertex that matched or -1 if no such vertex could be found.
+ */
+export declare const findInVertexArray: (vertexList: Array<Vertex>, vertex: XYCoords, epsilon: number) => number;

package/src/_esm/src/ts/utils/findInVertexArray.js

@@ -0,0 +1,25 @@
+/**
+ * @author  Ikaros Kappler
+ * @date    2022-01-10
+ * @version 1.0.0
+ */
+/**
+ * In an array of vertices find the first occurence of a specific vertex, using
+ * and epsilon tolerance.
+ *
+ * @param {Array<Vertex>} vertexList - The vertex array to search in.
+ * @param {XYCoords} vertex - A vertex/position to search for. This can be any x-y-tuple and does not
+ *                              necessarily need to be an instance of Vertex.
+ * @param {number} epsilon - The epsilon tolerance to use (should be >= 0). This is a required param to avoid excessive
+ *                              is-undef checking if this function runs in a loop.
+ * @returns {boolean} - The first index of a vertex that matched or -1 if no such vertex could be found.
+ */
+export const findInVertexArray = (vertexList, vertex, epsilon) => {
+    for (var i = 0; i < vertexList.length; i++) {
+        if (vertexList[i].distance(vertex) < epsilon) {
+            return i;
+        }
+    }
+    return -1;
+};
+//# sourceMappingURL=findInVertexArray.js.map

package/src/_esm/src/ts/utils/findInVertexArray.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"findInVertexArray.js","sourceRoot":"","sources":["../../../../ts/utils/findInVertexArray.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,UAAyB,EAAE,MAAgB,EAAE,OAAe,EAAU,EAAE;IACxG,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,UAAU,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAC3C,IAAI,UAAU,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,GAAG,OAAO,EAAE,CAAC;YAC7C,OAAO,CAAC,CAAC;QACX,CAAC;IACH,CAAC;IACD,OAAO,CAAC,CAAC,CAAC;AACZ,CAAC,CAAC"}

package/src/_esm/src/ts/utils/gup.d.ts

@@ -0,0 +1,14 @@
+/**
+ * `gup` = "Get URL/URI Params".
+ *
+ * This function simply taktes the location string from the broser bar and retrieves all GET params
+ * as a record of string mappings.
+ *
+ * You can pass that result into the `Params` class to get proper type conversion for numbers and booleans.
+ *
+ * Ported to typescript.
+ * @date 2021-05-21
+ * @modified 2024-03-10 Fixed some type for Typescript 5 compatibility.
+ * @modified 2024-08-26 Decoding URI components in GET params.
+ */
+export declare const gup: () => Record<string, string>;

package/src/_esm/src/ts/utils/gup.js

@@ -0,0 +1,27 @@
+/**
+ * `gup` = "Get URL/URI Params".
+ *
+ * This function simply taktes the location string from the broser bar and retrieves all GET params
+ * as a record of string mappings.
+ *
+ * You can pass that result into the `Params` class to get proper type conversion for numbers and booleans.
+ *
+ * Ported to typescript.
+ * @date 2021-05-21
+ * @modified 2024-03-10 Fixed some type for Typescript 5 compatibility.
+ * @modified 2024-08-26 Decoding URI components in GET params.
+ */
+// Get the URI GET params as an assoc.
+//
+// A nicer version with regex
+// Found at
+//    https://stackoverflow.com/questions/979975/how-to-get-the-value-from-the-get-parameters?utm_medium=organic&utm_source=google_rich_qa&utm_campaign=google_rich_qa
+export const gup = () => {
+    const vars = {};
+    globalThis.location.href.replace(/[?&]+([^=&]+)=([^&]*)/gi, (_m, key, value) => {
+        const keyName = key;
+        return (vars[decodeURIComponent(keyName)] = value);
+    });
+    return vars;
+};
+//# sourceMappingURL=gup.js.map

package/src/_esm/src/ts/utils/gup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gup.js","sourceRoot":"","sources":["../../../../ts/utils/gup.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,sCAAsC;AACtC,EAAE;AACF,6BAA6B;AAC7B,WAAW;AACX,sKAAsK;AACtK,MAAM,CAAC,MAAM,GAAG,GAAG,GAA2B,EAAE;IAC9C,MAAM,IAAI,GAA2B,EAAE,CAAC;IACxC,UAAU,CAAC,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,yBAAyB,EAAE,CAAC,EAAU,EAAE,GAAW,EAAE,KAAa,EAAU,EAAE;QAC7G,MAAM,OAAO,GAAW,GAAmB,CAAC;QAC5C,OAAO,CAAC,IAAI,CAAC,kBAAkB,CAAC,OAAO,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC;IACrD,CAAC,CAAC,CAAC;IACH,OAAO,IAAI,CAAC;AACd,CAAC,CAAC"}

package/src/_esm/src/ts/utils/helpers/BezierPathInteractionHelper.d.ts

@@ -0,0 +1,272 @@
+/**
+ * Interfaces and class for automatically handling Bézier curves.
+ *
+ * @requires AlloyFinger
+ * @requires BezierPath
+ * @requires CubicBezierPath
+ * @requires KeyHandler
+ * @requires MouseHandler
+ * @requires PlotBoilerplate
+ * @requires VertEvent
+ * @requires Vertex
+ * @requires XMouseEvent
+ * @requires XYCoords
+ *
+ *
+ * @author   Ikaros Kappler
+ * @date     2020-07-31
+ * @modified 2020-08-03 Ported this class from vanilla JS to Typescript.
+ * @modified 2020-08-12 Added a distance check before handling the click/tap event.
+ * @modified 2021-01-03 Changed property to `autoAdjustPaths` in the HandlerOptions interface (typo).
+ * @modified 2021-01-03 Added following new functions: `addPathVertexDragStartListeners`, `removePathVertexDragStartListeners`, `addPathVertexDragEndListeners` and `removePathVertexDragEndListeners`.
+ * @modified 2021-03-31 Fixed the issue with the new AlloyFinger (Typescript).
+ * @modified 2022-02-03 Changing the element to catch events (eventCatcher instead of canvas).
+ * @modified 2024-03-10 Fixing some types for Typescript 5 compatibility.
+ * @modified 2025-04-14 Added the `BezierPathInteractionHelper.drawHandleLines` method.
+ * @modified 2025-04-14 Fixing correct event types for touch events in `BezierPathInteractionHelper`.
+ * @modified 2025-04-14 BezierPathInteractionHelper: Changed default value of `HelperOptions.autoAdjustPaths` from `true` to `false`.
+ * @modified 2025-05-05 Added optional params `draw` and `fill` to BezierPathInteractionHelper.drawHandleLines` method.
+ * @modified 2025-05-05 Class `BezierPathInteractionHelper` now implementing `IShapeInteractionHelper`.
+ * @modified 2025-05-07 Tweaking performance of `BezierPathInteractionHelper`: only triggering redraw now when mouse move within given detect range.
+ * @version  1.2.1
+ *
+ * @file BezierPathInteractionHelper
+ * @public
+ **/
+import { BezierPath } from "../../BezierPath";
+import { PlotBoilerplate } from "../../PlotBoilerplate";
+import { VertListener } from "../../VertexListeners";
+import { Vertex } from "../../Vertex";
+import { DrawLib, IShapeInteractionHelper } from "../../interfaces";
+/**
+ * Handler type for mouse-pointer-moved listeners.
+ */
+type OnPointerMoved = (pathIndex: number, pathPoint: Vertex | null, pointerPos: Vertex | null, t: number) => void;
+/**
+ * Handler type for vertex-inserted listeners.
+ */
+type OnVertexInserted = (pathIndex: number, insertIndex: number, newPath: BezierPath, oldPath: BezierPath) => void;
+/**
+ * Handler type for vertex-removed listeners.
+ */
+type OnVerticesDeleted = (pathIndex: number, removedVertexIndices: Array<number>, newPath: BezierPath, oldPath: BezierPath) => void;
+/**
+ * Handler type for path-removed listeners.
+ */
+type OnPathRemoved = (pathIndex: number, oldPath: BezierPath) => void;
+/**
+ * Options passed to the constructor.
+ */
+interface HelperOptions {
+    autoAdjustPaths?: boolean;
+    allowPathRemoval?: boolean;
+    maxDetectDistance?: number;
+    onPointerMoved?: OnPointerMoved;
+    onVertexInserted?: OnVertexInserted;
+    onVerticesDeleted?: OnVerticesDeleted;
+    onPathRemoved?: OnPathRemoved;
+}
+/**
+ * @classdesc A helper for adding vertices to and remove vertices from Bézier paths.
+ * By default the 'delete' key is used to remove vertices or paths.
+ *
+ * For convenience this helper is capable of handling multiple paths which are kept
+ * in an array.
+ *
+ * [Demo](https://www.plotboilerplate.io/repo/demos/23-bezier-point-distance/ "Demo")
+ *
+ * @public
+ **/
+export declare class BezierPathInteractionHelper implements IShapeInteractionHelper {
+    /**
+     * @member {PlotBoilerplate} pb
+     * @memberof BezierPathInteractionHelper
+     * @type {PlotBoilerplate}
+     * @instance
+     */
+    private pb;
+    private paths;
+    private onPointerMoved;
+    private onVertexInserted;
+    private onVerticesDeleted;
+    private onPathRemoved;
+    private autoAdjustPaths;
+    private allowPathRemoval;
+    private maxDetectDistance;
+    private mouseIsOver;
+    private currentPathIndex;
+    private currentDistance;
+    private currentT;
+    private currentA;
+    private currentB;
+    private _mouseHandler;
+    private _touchHandler;
+    private _keyHandler;
+    private _mouseEnterListener;
+    private _mouseLeaveListener;
+    /**
+     * Pre: all paths must have been added to the PlotBoilerplate's drawable buffer (use the add(Drawable) function).
+     *
+     * The move callback accepts four params:
+     *   * The point on the closest curve (Vertex)
+     *   * The mouse or touch position (Vertex)
+     *   * The curve position (float t)
+     *   * The curve index on the array (integer)
+     *
+     *
+     * @constructor
+     * @name BezierPathInteractionHelper
+     * @param {PlotBoilerplate} pb
+     * @param {Array<BezierPath>} paths
+     * @param {boolean} options.autoAdjustPaths - If true then inner path points will be auto-adjusted to keep the curve smooth.
+     * @param {boolean} options.allowPathRemoval - If true then full paths can be removed (by removing selected vertices).
+     * @param {number} maxDetectDistance - The max detection distance. No events will be fired if the mouse/touch pointer is outside this range (default is Number.MAX_VALUE).
+     * @param {function(number,Vertex,Vertex,number)} options.onPointerMoved (pathIndex,pathPoint,pointer,t)
+     * @param {function(number,number,BezierPath,BezierPath)} options.onVertexInserted (pathIndex,insertIndex,newPath,oldPath)
+     * @param {function(number,number[],BezierPath,BezierPath)} options.onVerticesDeleted (pathIndex,removedVertexIndices,newPath,oldPath)
+     * @param {function(number,BezierPath)} options.onPathRemoved (pathIndex,oldPath)
+     **/
+    constructor(pb: PlotBoilerplate, paths: Array<BezierPath>, options: HelperOptions);
+    /**
+     * Manually add a path to this helper.
+     * Note that if `autoAdjustPaths==true` then listeners will be installed to the path's vertices to
+     * keep the path smooth at all times.
+     *
+     * @method addPath
+     * @instance
+     * @memberof BezierPathInteractionHelper
+     * @param {BezierPath} path - The path to add.
+     * @return {boolean} Duplicate path instances cannot be added; function will return false if path already exists.
+     **/
+    addPath(path: BezierPath): boolean;
+    /**
+     * Manually remove a path from this helper.
+     * Note that this method ignores the `allowPathRemoval` option.
+     *
+     * @method removePath
+     * @instance
+     * @memberof BezierPathInteractionHelper
+     * @param {BezierPath} path - The path to remove.
+     * @return {boolean} Returns false if the path could not be found.
+     **/
+    removePath(path: BezierPath): boolean;
+    /**
+     * Remove the path at the given index.
+     *
+     * @method removePathAt
+     * @instance
+     * @memberof BezierPathInteractionHelper
+     * @param {number} pathIndex - The index of the path (must be inside bounds, see `this.paths` array).
+     * @return {void}
+     **/
+    removePathAt(pathIndex: number): void;
+    /**
+     * Update the inner status by running the distance calculation again with the current settings.
+     *
+     * Call this if any of the properties changed (like maxDetecDistance).
+     *
+     * @method update
+     * @instance
+     * @memberof BezierPathInteractionHelper
+     * @return {void}
+     **/
+    update(): void;
+    /**
+     * Draw grey handle lines.
+     *
+     * @param {DrawLib<any>} draw - (optional) The draw library to use. If not provided then `pb.draw` will be used.
+     * @param {DrawLib<any>} fill - (optional) The fill library to use. If not provided then `pb.fill` will be used.
+     */
+    drawHandleLines(draw?: DrawLib<any>, fill?: DrawLib<any>): void;
+    /**
+     * This function should invalidate any installed listeners and invalidate this object.
+     * After calling this function the object might not hold valid data any more and
+     * should not be used any more.
+     *
+     * @method destroy
+     * @instance
+     * @memberof BezierPathInteractionHelper
+     * @return {void}
+     **/
+    destroy(): void;
+    private _locatePath;
+    private _handleDelete;
+    private _handleSingleVertexDelete;
+    private _handleDeleteOnPath;
+    private _replacePathAt;
+    private _handleMoveEvent;
+    private _clearMoveEvent;
+    private _installTouchListener;
+    private _installMouseListener;
+    private _installKeyListener;
+    private _removeDefaultPathListeners;
+    private _updateMinDistance;
+    static setPathAutoAdjust(path: BezierPath): void;
+    /**
+     * A helper function to add drag-start listeners to all vertices of the given path.
+     *
+     * @static
+     * @method addPathVertexDragStartListeners
+     * @memberof BezierPathInteractionHelper
+     * @param {BezierPath} path - The Bézier path to add vertex listeners to.
+     * @param {function} vertexDragStartListener - The drag listeners to add to each path vertex.
+     * @return void
+     **/
+    static addPathVertexDragStartListeners(path: BezierPath, vertexDragStartListener: VertListener): void;
+    /**
+     * A helper function to remove drag-start listeners to all vertices of the given path.
+     *
+     * @static
+     * @method removePathVertexDragStartListeners
+     * @memberof BezierPathInteractionHelper
+     * @param {BezierPath} path - The Bézier path to remove vertex listeners from.
+     * @param {function} vertexDragListener - The drag listeners to remove from each path vertex.
+     * @return void
+     **/
+    static removePathVertexDragStartListeners(path: BezierPath, vertexDragStartListener: VertListener): void;
+    /**
+     * A helper function to add drag listeners to all vertices of the given path.
+     *
+     * @static
+     * @method addPathVertexDragListeners
+     * @memberof BezierPathInteractionHelper
+     * @param {BezierPath} path - The Bézier path to add vertex listeners to.
+     * @param {function} vertexDragListener - The drag listeners to add to each path vertex.
+     * @return void
+     **/
+    static addPathVertexDragListeners(path: BezierPath, vertexDragListener: VertListener): void;
+    /**
+     * A helper function to remove drag listeners to all vertices of the given path.
+     *
+     * @static
+     * @method removePathVertexDragListeners
+     * @memberof BezierPathInteractionHelper
+     * @param {BezierPath} path - The Bézier path to remove vertex listeners from.
+     * @param {function} vertexDragListener - The drag listeners to remove from each path vertex.
+     * @return void
+     **/
+    static removePathVertexDragListeners(path: BezierPath, vertexDragListener: VertListener): void;
+    /**
+     * A helper function to add drag-end listeners to all vertices of the given path.
+     *
+     * @static
+     * @method addPathVertexDragEndListeners
+     * @memberof BezierPathInteractionHelper
+     * @param {BezierPath} path - The Bézier path to add vertex listeners to.
+     * @param {function} vertexDragEndListener - The drag listeners to add to each path vertex.
+     * @return void
+     **/
+    static addPathVertexDragEndListeners(path: BezierPath, vertexDragEndListener: VertListener): void;
+    /**
+     * A helper function to remove drag-end listeners to all vertices of the given path.
+     *
+     * @static
+     * @method removePathVertexDragEndListeners
+     * @memberof BezierPathInteractionHelper
+     * @param {BezierPath} path - The Bézier path to remove vertex listeners from.
+     * @param {function} vertexDragListener - The drag listeners to remove from each path vertex.
+     * @return void
+     **/
+    static removePathVertexDragEndListeners(path: BezierPath, vertexDragEndListener: VertListener): void;
+}
+export {};