@tspro/ts-utils-lib 3.3.0 → 3.4.0

package/dist/index.js

@@ -1,7 +1,7 @@
 'use strict';
 
 /*!
- * TsUtilsLib v3.3.0 (cjs)
+ * TsUtilsLib v3.4.0 (cjs)
  * (c) 2023-2025 PahkaSoft
  * Licensed under the MIT License
  */
@@ -2028,6 +2028,24 @@ var Vec = class _Vec extends BaseContainer {
 };
 
 // src/core/rect.ts
+function getRectProps(arg) {
+  let left = NaN;
+  let right = NaN;
+  let top = NaN;
+  let bottom = NaN;
+  if (hasProperties(arg, ["left", "top"])) {
+    left = Number(arg.left);
+    top = Number(arg.top);
+  } else if (hasProperties(arg, ["x", "y"])) {
+    left = Number(arg.x);
+    top = Number(arg.y);
+  }
+  if (hasProperties(arg, ["width", "height"])) {
+    right = left + Number(arg.width);
+    bottom = top + Number(arg.height);
+  }
+  return { left, top, right, bottom };
+}
 var Rect = class _Rect {
   constructor(...args) {
     __publicField(this, "x");
@@ -2036,15 +2054,21 @@ var Rect = class _Rect {
     __publicField(this, "height");
     if (args.length === 0) {
       this.x = this.y = this.width = this.height = 0;
+    } else if (args.length === 1) {
+      const _args = getRectProps(args[0]);
+      this.x = _args.left;
+      this.y = _args.top;
+      this.width = _args.right - _args.left;
+      this.height = _args.bottom - _args.top;
     } else if (args.length === 2) {
       this.x = this.y = 0;
-      this.width = args[0];
-      this.height = args[1];
+      this.width = Number(args[0]);
+      this.height = Number(args[1]);
     } else {
-      this.x = args[0];
-      this.y = args[1];
-      this.width = args[2];
-      this.height = args[3];
+      this.x = Number(args[0]);
+      this.y = Number(args[1]);
+      this.width = Number(args[2]);
+      this.height = Number(args[3]);
     }
     if (this.width < 0 || this.height < 0)
       throw new Error("Rect width and height must be non-negative.");
@@ -2066,7 +2090,9 @@ var Rect = class _Rect {
       throw new Error("Rect width and height must be non-negative.");
     return this;
   }
-  // --- Static Constructors ---
+  /**
+   * Create the smallest rectangle enclosing two points.
+   */
   static fromPoints(p1, p2) {
     const x = Math.min(p1.x, p2.x);
     const y = Math.min(p1.y, p2.y);
@@ -2074,77 +2100,129 @@ var Rect = class _Rect {
     const h = Math.abs(p1.y - p2.y);
     return new _Rect(x, y, w, h);
   }
+  /**
+   * Create a rectangle centered at the given point.
+   *
+   * @param cx - Center x-coordinate
+   * @param cy - Center y-coordinate
+   * @param width - Rectangle width
+   * @param height - Rectangle height
+   */
   static fromCenter(cx, cy, width, height) {
     return new _Rect(cx - width / 2, cy - height / 2, width, height);
   }
-  // --- Derived Properties ---
+  /** Left edge coordinate. */
   get left() {
     return this.x;
   }
+  /** Top edge coordinate. */
   get top() {
     return this.y;
   }
+  /** Right edge coordinate. */
   get right() {
     return this.x + this.width;
   }
+  /** Bottom edge coordinate. */
   get bottom() {
     return this.y + this.height;
   }
+  /** Geometric center x-coordinate. */
   get centerX() {
     return this.x + this.width / 2;
   }
+  /** Geometric center y-coordinate. */
   get centerY() {
     return this.y + this.height / 2;
   }
+  /** Geometric center point. */
   get center() {
     return { x: this.centerX, y: this.centerY };
   }
+  /** Rectangle area (`width * height`). */
   get area() {
     return this.width * this.height;
   }
+  /**
+   * Whether this rectangle has zero or negative area.
+   * Note: width and height are guaranteed non-negative.
+   */
   get isEmpty() {
     return this.width <= 0 || this.height <= 0;
   }
-  // --- Geometric Tests ---
+  /**
+   * Test whether a point lies inside or on the edges of this rectangle.
+   */
   containsPoint(px, py) {
     return px >= this.left && px <= this.right && py >= this.top && py <= this.bottom;
   }
+  /**
+   * Test whether another rectangle is fully contained within this rectangle.
+   */
   containsRect(other) {
     return other.left >= this.left && other.right <= this.right && other.top >= this.top && other.bottom <= this.bottom;
   }
   intersects(other) {
-    return !(other.right < this.left || other.left > this.right || other.bottom < this.top || other.top > this.bottom);
+    const _args = getRectProps(other);
+    return !(_args.right < this.left || _args.left > this.right || _args.bottom < this.top || _args.top > this.bottom);
   }
-  // --- Operations ---
   intersectionCopy(other) {
-    const x1 = Math.max(this.left, other.left);
-    const y1 = Math.max(this.top, other.top);
-    const x2 = Math.min(this.right, other.right);
-    const y2 = Math.min(this.bottom, other.bottom);
+    const _args = getRectProps(other);
+    const x1 = Math.max(this.left, _args.left);
+    const y1 = Math.max(this.top, _args.top);
+    const x2 = Math.min(this.right, _args.right);
+    const y2 = Math.min(this.bottom, _args.bottom);
     if (x2 <= x1 || y2 <= y1) return new _Rect();
     return new _Rect(x1, y1, x2 - x1, y2 - y1);
   }
   unionCopy(other) {
-    const x1 = Math.min(this.left, other.left);
-    const y1 = Math.min(this.top, other.top);
-    const x2 = Math.max(this.right, other.right);
-    const y2 = Math.max(this.bottom, other.bottom);
+    const _args = getRectProps(other);
+    const x1 = Math.min(this.left, _args.left);
+    const y1 = Math.min(this.top, _args.top);
+    const x2 = Math.max(this.right, _args.right);
+    const y2 = Math.max(this.bottom, _args.bottom);
     return new _Rect(x1, y1, x2 - x1, y2 - y1);
   }
+  /**
+   * Create an inset (shrunken) copy of this rectangle.
+   *
+   * @param dx - Horizontal inset
+   * @param dy - Vertical inset
+   */
   insetCopy(dx, dy) {
     return new _Rect(this.x + dx, this.y + dy, this.width - 2 * dx, this.height - 2 * dy);
   }
+  /**
+   * Create an inflated (expanded) copy of this rectangle.
+   *
+   * @param dx - Horizontal expansion
+   * @param dy - Vertical expansion
+   */
   inflateCopy(dx, dy) {
     return new _Rect(this.x - dx, this.y - dy, this.width + 2 * dx, this.height + 2 * dy);
   }
+  /**
+   * Move this rectangle by the given offset.
+   * Modifies this instance.
+   */
   offsetInPlace(dx, dy) {
     this.x += dx;
     this.y += dy;
     return this;
   }
+  /**
+   * Create a translated copy of this rectangle.
+   */
   offsetCopy(dx, dy) {
     return new _Rect(this.x + dx, this.y + dy, this.width, this.height);
   }
+  /**
+   * Scale this rectangle around its geometric center.
+   * Modifies this instance.
+   *
+   * @param scaleX - Horizontal scale factor
+   * @param scaleY - Vertical scale factor (defaults to scaleX)
+   */
   scaleInPlace(scaleX, scaleY = scaleX) {
     this.x = this.centerX - this.width * scaleX / 2;
     this.width *= scaleX;
@@ -2152,9 +2230,16 @@ var Rect = class _Rect {
     this.height *= scaleY;
     return this;
   }
+  /**
+   * Create a scaled copy of this rectangle.
+   * Scaling is performed around the geometric center.
+   */
   scaleCopy(scaleX, scaleY = scaleX) {
     return this.clone().scaleInPlace(scaleX, scaleY);
   }
+  /**
+   * Create a copy with all edges rounded to the nearest integer.
+   */
   roundCopy() {
     const left = Math.round(this.left);
     const top = Math.round(this.top);
@@ -2162,6 +2247,9 @@ var Rect = class _Rect {
     const bottom = Math.round(this.bottom);
     return new _Rect(left, top, right - left, bottom - top);
   }
+  /**
+   * Create a copy with all edges rounded down.
+   */
   floorCopy() {
     const left = Math.floor(this.left);
     const top = Math.floor(this.top);
@@ -2169,6 +2257,9 @@ var Rect = class _Rect {
     const bottom = Math.floor(this.bottom);
     return new _Rect(left, top, right - left, bottom - top);
   }
+  /**
+   * Create a copy with all edges rounded up.
+   */
   ceilCopy() {
     const left = Math.ceil(this.left);
     const top = Math.ceil(this.top);
@@ -2176,6 +2267,9 @@ var Rect = class _Rect {
     const bottom = Math.ceil(this.bottom);
     return new _Rect(left, top, right - left, bottom - top);
   }
+  /**
+   * Expand this rectangle to include a point.
+   */
   expandCopy(px, py) {
     const left = Math.min(this.left, px);
     const top = Math.min(this.top, py);
@@ -2183,22 +2277,55 @@ var Rect = class _Rect {
     const bottom = Math.max(this.bottom, py);
     return new _Rect(left, top, right - left, bottom - top);
   }
-  // --- Utilities ---
+  /**
+   * Test for exact equality with another rectangle.
+   */
   equals(other) {
     return this.x === other.x && this.y === other.y && this.width === other.width && this.height === other.height;
   }
+  /**
+   * Create a deep copy of this rectangle.
+   */
   clone() {
     return new _Rect(this.x, this.y, this.width, this.height);
   }
-  toString() {
-    return `Rect(x=${this.x}, y=${this.y}, w=${this.width}, h=${this.height})`;
-  }
+  /**
+   * Convert this rectangle to an AnchoredRect.
+   * The anchor is placed at the geometric center.
+   */
   toAnchoredRect() {
     return new AnchoredRect(this.left, this.right, this.top, this.bottom);
   }
+  toString() {
+    return `Rect(x=${this.x}, y=${this.y}, w=${this.width}, h=${this.height})`;
+  }
 };
 
 // src/core/anchor-rect.ts
+function getRectProps2(arg) {
+  let left = NaN;
+  let anchorX;
+  let right = NaN;
+  let top = NaN;
+  let anchorY;
+  let bottom = NaN;
+  if (hasProperties(arg, ["left", "top"])) {
+    left = Number(arg.left);
+    top = Number(arg.top);
+  } else if (hasProperties(arg, ["x", "y"])) {
+    left = Number(arg.x);
+    top = Number(arg.y);
+  }
+  if (hasProperties(arg, ["width", "height"])) {
+    right = left + Number(arg.width);
+    bottom = top + Number(arg.height);
+  }
+  if (hasProperties(arg, ["anchorX", "anchorY"])) {
+    anchorX = Number(arg.anchorX);
+    anchorY = Number(arg.anchorY);
+  }
+  return { left, anchorX, right, top, anchorY, bottom };
+}
 var AnchoredRect = class _AnchoredRect {
   constructor(...args) {
     __publicField(this, "left");
@@ -2221,6 +2348,14 @@ var AnchoredRect = class _AnchoredRect {
       this.top = args[2];
       this.bottom = args[3];
       this.anchorY = (this.top + this.bottom) / 2;
+    } else if (args.length === 1) {
+      const _args = getRectProps2(args[0]);
+      this.left = _args.left;
+      this.right = _args.right;
+      this.anchorX = _args.anchorX ?? (this.left + this.right) / 2;
+      this.top = _args.top;
+      this.bottom = _args.bottom;
+      this.anchorY = _args.anchorY ?? (this.top + this.bottom) / 2;
     } else if (args.length === 0) {
       this.left = this.anchorX = this.right = 0;
       this.top = this.anchorY = this.bottom = 0;
@@ -2294,89 +2429,90 @@ var AnchoredRect = class _AnchoredRect {
   static createSections(leftw, rightw, toph, bottomh) {
     return new _AnchoredRect(-leftw, 0, rightw, -toph, 0, bottomh);
   }
-  /**
-   * Get center x-coordinate.
-   */
+  /** Geometric center x-coordinate (ignores anchor). */
   get centerX() {
     return this.left + this.width / 2;
   }
-  /**
-   * Get center ycoordinate.
-   */
+  /** Geometric center y-coordinate (ignores anchor). */
   get centerY() {
     return this.top + this.height / 2;
   }
-  /**
-   * Width getter.
-   */
+  /** Rectangle width (`right - left`). */
   get width() {
     return this.right - this.left;
   }
-  /**
-   * Height getter.
-   */
+  /** Rectangle height (`bottom - top`). */
   get height() {
     return this.bottom - this.top;
   }
-  /**
-   * Left section width getter.
-   */
+  /** Distance from left edge to anchor. */
   get leftw() {
     return this.anchorX - this.left;
   }
-  /**
-   * Right section width getter.
-   */
+  /** Distance from anchor to right edge. */
   get rightw() {
     return this.right - this.anchorX;
   }
-  /**
-   * Top section height getter.
-   */
+  /** Distance from top edge to anchor. */
   get toph() {
     return this.anchorY - this.top;
   }
-  /**
-   * Bottom section height getter.
-   */
+  /** Distance from anchor to bottom edge. */
   get bottomh() {
     return this.bottom - this.anchorY;
   }
   /**
-   * Does this Rect contain given (x, y)-point?
-   * 
-   * @param x - X-coordinate.
-   * @param y - Y-coordinate.
-   * @returns - True/false.
+   * Test whether a point lies inside or on the edges of this rectangle.
    */
   contains(x, y) {
     return x >= this.left && x <= this.right && y >= this.top && y <= this.bottom;
   }
   /**
-   * Do a and b rects overlap?
-   * 
-   * @param a - AnchoredRect a.
-   * @param b - AnchoredRect b.
-   * @returns - True/false.
+   * Create an inset (shrunken) copy of this rectangle.
+   *
+   * The rectangle edges are moved inward by the given amounts.
+   * The anchor position is preserved.
+   *
+   * @param dx - Horizontal inset applied to left and right edges.
+   * @param dy - Vertical inset applied to top and bottom edges.
+   *             Defaults to `dx`.
+   * @returns A new AnchoredRect inset from all sides.
+   */
+  insetCopy(dx, dy = dx) {
+    return new _AnchoredRect(this.left + dx, this.anchorX, this.right - dx, this.top + dy, this.anchorY, this.bottom - dy);
+  }
+  /**
+   * Create an inflated (expanded) copy of this rectangle.
+   *
+   * The rectangle edges are moved outward by the given amounts.
+   * The anchor position is preserved.
+   *
+   * @param dx - Horizontal expansion applied to left and right edges.
+   * @param dy - Vertical expansion applied to top and bottom edges.
+   *             Defaults to `dx`.
+   * @returns A new AnchoredRect expanded on all sides.
+   */
+  inflateCopy(dx, dy = dx) {
+    return new _AnchoredRect(this.left - dx, this.anchorX, this.right + dx, this.top - dy, this.anchorY, this.bottom + dy);
+  }
+  intersects(other) {
+    const _args = getRectProps2(other);
+    return !(_args.right < this.left || _args.left > this.right || _args.bottom < this.top || _args.top > this.bottom);
+  }
+  /**
+   * This method requires strict overlap (edge-touching does NOT count).
    */
   static overlap(a, b) {
     return a.right > b.left && a.left < b.right && a.bottom > b.top && a.top < b.bottom;
   }
   /**
-   * Do horizontal measures of a and b rects overlap?
-   * 
-   * @param a - AnchoredRect a.
-   * @param b - AnchoredRect b.
-   * @returns - True/false.
+   * This method requires strict (horizontal) overlap (edge-touching does NOT count).
    */
   static overlapX(a, b) {
     return a.right > b.left && a.left < b.right;
   }
   /**
-   * Check if given rects are equal.
-   * @param a - AnchoredRect a.
-   * @param b - AnchoredRect b.
-   * @returns - True/false.
+   * Test if rects are equal.
    */
   static equals(a, b) {
     if (a == null && b == null) {
@@ -2388,19 +2524,13 @@ var AnchoredRect = class _AnchoredRect {
     }
   }
   /**
-   * Check if this rect equals with another rect.
-   * @param other - The other rect.
-   * @returns - True/false.
+   * Test if this rect equals with given rect.
    */
   equals(other) {
     return _AnchoredRect.equals(this, other);
   }
   /**
-   * Check if edges of given rects are equal, ignoring anchorX and anchorY.
-   * 
-   * @param a - AnchoredRect a.
-   * @param b - AnchoredRect b.
-   * @returns - True/false.
+   * Test if edges of given rects are equal, ignoring anchorX and anchorY.
    */
   static equalsEdges(a, b) {
     if (a == null && b == null) {
@@ -2412,27 +2542,23 @@ var AnchoredRect = class _AnchoredRect {
     }
   }
   /**
-   * Check if edges of this Rect equals with given Rect, ignoring anchorX and anchorY.
-   * 
-   * @param other - The other AnchoredRect.
-   * @returns - True/false.
+   * Test if edges of this equal with given Rect, ignoring anchorX and anchorY.
    */
   equalsEdges(other) {
     return _AnchoredRect.equalsEdges(this, other);
   }
   /**
-   * Created duplicate of this Rect.
-   * @returns - Duplicate.
+   * Create copy.
    */
   clone() {
     return new _AnchoredRect(this.left, this.anchorX, this.right, this.top, this.anchorY, this.bottom);
   }
   /**
-   * Move this rect by (dx, dy). Modifies this Rect.
+   * Move this rect by (dx, dy).
    * 
    * @param dx - Offset amount in x-direction.
    * @param dy - Offset amount in y-direction.
-   * @returns - This AnchoredRect instance.
+   * @returns - Modified this.
    */
   offsetInPlace(dx, dy) {
     this.left += dx;
@@ -2444,42 +2570,52 @@ var AnchoredRect = class _AnchoredRect {
     return this;
   }
   /**
-   * Move this rect by (dx, dy). Immutable, returns modified copy.
+   * Move this rect by (dx, dy).
    * 
    * @param dx - Offset amount in x-direction.
    * @param dy - Offset amount in y-direction.
-   * @returns - AnchoredRect copy with applied offset.
+   * @returns - Copy with applied offset.
    */
   offsetCopy(dx, dy) {
     return this.clone().offsetInPlace(dx, dy);
   }
   /**
-   * Expand this Rect by given Rect. Modifies this Rect.
-   * 
-   * @param rect - AnchoredRect to expand this instance with.
-   * @returns - This AnchoredRect instance.
+   * Expand this rectangle to include another rectangle.
+   * The anchor is preserved.
    */
-  expandInPlace(rect) {
-    this.left = Math.min(this.left, rect.left);
-    this.right = Math.max(this.right, rect.right);
-    this.top = Math.min(this.top, rect.top);
-    this.bottom = Math.max(this.bottom, rect.bottom);
+  unionInPlace(other) {
+    this.left = Math.min(this.left, other.left);
+    this.right = Math.max(this.right, other.right);
+    this.top = Math.min(this.top, other.top);
+    this.bottom = Math.max(this.bottom, other.bottom);
     return this;
   }
+  /** @deprecated - Use unionInPlace(). */
+  expandInPlace(other) {
+    return this.unionInPlace(other);
+  }
   /**
-   * Expand this Rect by given Rect. Immutable, returns modified copy.
-   * 
-   * @param rect - AnchoredRect to expand this instance with.
-   * @returns - Expanded copy of this AnchoredRect.
+   * Union this rect with given Rect. 
+   * @param other - Union with.
+   * @returns - Modified copy.
    */
-  expandCopy(rect) {
-    return this.clone().expandInPlace(rect);
+  unionCopy(other) {
+    return new _AnchoredRect(
+      Math.min(this.left, other.left),
+      this.anchorX,
+      Math.max(this.right, other.right),
+      Math.min(this.top, other.top),
+      this.anchorY,
+      Math.max(this.bottom, other.bottom)
+    );
+  }
+  /** @deprecated - Use unionCopy(). */
+  expandCopy(other) {
+    return this.unionCopy(other);
   }
   /**
-   * Clip this Rect by given Rect. Mmodifies this Rect.
-   * 
-   * @param clipRect - AnchoredRect to clip this instance with.
-   * @returns - This AnchoredRect instance.
+   * Clip this rectangle to the bounds of another rectangle.
+   * The anchor is clamped to remain inside the clipped region.
    */
   clipInPlace(clipRect) {
     this.left = Math.max(this.left, clipRect.left);
@@ -2500,11 +2636,8 @@ var AnchoredRect = class _AnchoredRect {
     return this.clone().clipInPlace(clipRect);
   }
   /**
-   * Scale Rect. Anchor pos is (anchorX, anchorY). Modifies this Rect.
-   * 
-   * @param scaleX - Scale x-amount.
-   * @param scaleY - Scale y-amount. If undefined then scale x-amount is used.
-   * @returns This AnchoredRect instance.
+   * Scale this rectangle around its anchor point.
+   * Edges are moved relative to the anchor.
    */
   scaleInPlace(scaleX, scaleY = scaleX) {
     this.left = this.anchorX - this.leftw * scaleX;
@@ -2524,15 +2657,19 @@ var AnchoredRect = class _AnchoredRect {
     return this.clone().scaleInPlace(scaleX, scaleY);
   }
   /**
-   * Get this AnchoredRect instance.
-   * @returns - This AnchoredRect instance.
+   * Return this rect.
    */
   getRect() {
     return this;
   }
+  /**
+   * Convert to a basic Rect using geometric edges.
+   * Anchor information is discarded.
+   */
   toRect() {
-    return new Rect(this.left, this.right, this.width, this.height);
+    return new Rect(this.left, this.top, this.width, this.height);
   }
+  /** String of this rect. */
   toString() {
     return `Rect(left=${this.left}, anchorX=${this.anchorX}, right=${this.right}, top=${this.top}, anchorY=${this.anchorY}, bottom=${this.bottom})`;
   }
@@ -4466,7 +4603,7 @@ var CallTracker = _CallTracker;
 
 // src/index.ts
 function getLibInfo() {
-  return "TsUtilsLib v3.3.0 (cjs)";
+  return "TsUtilsLib v3.4.0 (cjs)";
 }
 
 exports.AnchoredRect = AnchoredRect;