@tspro/ts-utils-lib 3.3.1 → 3.4.0

package/CHANGELOG.md

@@ -1,4 +1,11 @@
 # Changelog
+## [3.4.0]- 2026-02-01
+### Added
+- More functions to Rect and AnchoredRect.
+
+### Fixed
+- AnchoredRect.toRect() returned wrong Rect.
+
 ## [3.3.1] - 2026-01-24
 ### Fixed
 - README.md.

package/README.md

@@ -37,12 +37,12 @@ const { UniMap, Utils } = require("@tspro/ts-utils-lib");
 
 ```html
 <!-- Unpkg CDM: Load non-polyfilled or polyfilled bundles. -->
-<script src="https://unpkg.com/@tspro/ts-utils-lib@3.3.1/dist/index.es5.iife.js"></script>
-<script src="https://unpkg.com/@tspro/ts-utils-lib@3.3.1/dist/index.es5.polyfilled.iife.js"></script>
+<script src="https://unpkg.com/@tspro/ts-utils-lib@3.4.0/dist/index.es5.iife.js"></script>
+<script src="https://unpkg.com/@tspro/ts-utils-lib@3.4.0/dist/index.es5.polyfilled.iife.js"></script>
 
 <!-- jsDelivr CDN: Load non-polyfilled or polyfilled bundles. -->
-<script src="https://cdn.jsdelivr.net/npm/@tspro/ts-utils-lib@3.3.1/dist/index.es5.iife.js"></script>
-<script src="https://cdn.jsdelivr.net/npm/@tspro/ts-utils-lib@3.3.1/dist/index.es5.polyfilled.iife.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/@tspro/ts-utils-lib@3.4.0/dist/index.es5.iife.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/@tspro/ts-utils-lib@3.4.0/dist/index.es5.polyfilled.iife.js"></script>
 
 <script>
     const { UniMap, Utils } = window.TsUtilsLib;

package/dist/index.d.ts

@@ -775,20 +775,79 @@ declare class Vec extends BaseContainer {
 }
 
 /**
- * An immutable 2D rectangle defined by its top-left corner (x, y) and size (width, height).
- * Provides geometric utilities like intersection, containment, scaling, etc.
+ * Mutable axis-aligned 2D rectangle defined by a top-left corner (`x`, `y`)
+ * and non-negative size (`width`, `height`).
+ *
+ * This class represents a basic geometric rectangle without an anchor.
+ * All operations assume a coordinate system where:
+ * - `left = x`
+ * - `top = y`
+ * - `right = x + width`
+ * - `bottom = y + height`
+ *
+ * Width and height are always non-negative. An error is thrown if violated.
  */
 declare class Rect {
     x: number;
     y: number;
     width: number;
     height: number;
+    /**
+     * Create an empty rectangle at the origin.
+     */
     constructor();
+    /**
+     * Create a copy of another Rect.
+     */
+    constructor(other: Rect);
+    /**
+     * Create a rectangle from a rect-like object.
+     *
+     * Accepts `{ left, top, width, height }`.
+     */
+    constructor(other: {
+        left: number;
+        top: number;
+        width: number;
+        height: number;
+    });
+    /**
+     * Create a rectangle with size only.
+     * The rectangle is positioned at the origin.
+     */
     constructor(width: number, height: number);
+    /**
+     * Create a rectangle from position and size.
+     *
+     * @param x - Left coordinate
+     * @param y - Top coordinate
+     * @param width - Rectangle width (must be non-negative)
+     * @param height - Rectangle height (must be non-negative)
+     */
     constructor(x: number, y: number, width: number, height: number);
+    /**
+     * Reset this rectangle to the origin with zero size.
+     */
     set(): Rect;
+    /**
+     * Set rectangle size and reset position to the origin.
+     *
+     * @param width - Rectangle width (must be non-negative)
+     * @param height - Rectangle height (must be non-negative)
+     */
     set(width: number, height: number): Rect;
+    /**
+     * Set rectangle position and size.
+     *
+     * @param x - Left coordinate
+     * @param y - Top coordinate
+     * @param width - Rectangle width (must be non-negative)
+     * @param height - Rectangle height (must be non-negative)
+     */
     set(x: number, y: number, width: number, height: number): Rect;
+    /**
+     * Create the smallest rectangle enclosing two points.
+     */
     static fromPoints(p1: {
         x: number;
         y: number;
@@ -796,42 +855,173 @@ declare class Rect {
         x: number;
         y: number;
     }): Rect;
+    /**
+     * 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: number, cy: number, width: number, height: number): Rect;
+    /** Left edge coordinate. */
     get left(): number;
+    /** Top edge coordinate. */
     get top(): number;
+    /** Right edge coordinate. */
     get right(): number;
+    /** Bottom edge coordinate. */
     get bottom(): number;
+    /** Geometric center x-coordinate. */
     get centerX(): number;
+    /** Geometric center y-coordinate. */
     get centerY(): number;
+    /** Geometric center point. */
     get center(): {
         x: number;
         y: number;
     };
+    /** Rectangle area (`width * height`). */
     get area(): number;
+    /**
+     * Whether this rectangle has zero or negative area.
+     * Note: width and height are guaranteed non-negative.
+     */
     get isEmpty(): boolean;
+    /**
+     * Test whether a point lies inside or on the edges of this rectangle.
+     */
     containsPoint(px: number, py: number): boolean;
+    /**
+     * Test whether another rectangle is fully contained within this rectangle.
+     */
     containsRect(other: Rect): boolean;
+    /**
+     * Test whether this rectangle intersects another rectangle.
+     *
+     * Edge-touching is considered an intersection.
+     */
     intersects(other: Rect): boolean;
+    /**
+     * Test whether this rectangle intersects another rectangle.
+     *
+     * Edge-touching is considered an intersection.
+     */
+    intersects(other: {
+        left: number;
+        top: number;
+        width: number;
+        height: number;
+    }): boolean;
+    /**
+     * Compute the intersection of this rectangle with another rectangle.
+     *
+     * Returns an empty rectangle if there is no overlap.
+     */
     intersectionCopy(other: Rect): Rect;
+    /**
+     * Compute the intersection of this rectangle with another rectangle.
+     *
+     * Returns an empty rectangle if there is no overlap.
+     */
+    intersectionCopy(other: {
+        left: number;
+        top: number;
+        width: number;
+        height: number;
+    }): Rect;
+    /**
+     * Compute the union of this rectangle with another rectangle.
+     */
     unionCopy(other: Rect): Rect;
+    /**
+     * Compute the union of this rectangle with another rectangle.
+     */
+    unionCopy(other: {
+        left: number;
+        top: number;
+        width: number;
+        height: number;
+    }): Rect;
+    /**
+     * Create an inset (shrunken) copy of this rectangle.
+     *
+     * @param dx - Horizontal inset
+     * @param dy - Vertical inset
+     */
     insetCopy(dx: number, dy: number): Rect;
+    /**
+     * Create an inflated (expanded) copy of this rectangle.
+     *
+     * @param dx - Horizontal expansion
+     * @param dy - Vertical expansion
+     */
     inflateCopy(dx: number, dy: number): Rect;
+    /**
+     * Move this rectangle by the given offset.
+     * Modifies this instance.
+     */
     offsetInPlace(dx: number, dy: number): Rect;
+    /**
+     * Create a translated copy of this rectangle.
+     */
     offsetCopy(dx: number, dy: number): Rect;
+    /**
+     * 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: number, scaleY?: number): Rect;
+    /**
+     * Create a scaled copy of this rectangle.
+     * Scaling is performed around the geometric center.
+     */
     scaleCopy(scaleX: number, scaleY?: number): Rect;
+    /**
+     * Create a copy with all edges rounded to the nearest integer.
+     */
     roundCopy(): Rect;
+    /**
+     * Create a copy with all edges rounded down.
+     */
     floorCopy(): Rect;
+    /**
+     * Create a copy with all edges rounded up.
+     */
     ceilCopy(): Rect;
+    /**
+     * Expand this rectangle to include a point.
+     */
     expandCopy(px: number, py: number): Rect;
+    /**
+     * Test for exact equality with another rectangle.
+     */
     equals(other: Rect): boolean;
+    /**
+     * Create a deep copy of this rectangle.
+     */
     clone(): Rect;
-    toString(): string;
+    /**
+     * Convert this rectangle to an AnchoredRect.
+     * The anchor is placed at the geometric center.
+     */
     toAnchoredRect(): AnchoredRect;
+    toString(): string;
 }
 
 /**
- * A mutable AnchoredRect class is a rectangle (left, top, right, bottom) with an anchor point (anchorX, anchorY).
+ * Mutable axis-aligned rectangle with an explicit anchor point.
+ *
+ * The rectangle is defined by its edges (`left`, `top`, `right`, `bottom`)
+ * and an independent anchor (`anchorX`, `anchorY`) that acts as a logical
+ * pivot for scaling, sectioning, and layout operations.
+ *
+ * The anchor does not need to lie at the geometric center of the rectangle.
+ *
+ * All coordinates use the same coordinate space and orientation
+ * (top ≤ bottom, left ≤ right).
  */
 declare class AnchoredRect {
     left: number;
@@ -841,53 +1031,57 @@ declare class AnchoredRect {
     anchorY: number;
     bottom: number;
     /**
-     * Create rectangle with all zero values.
+     * Create an empty rectangle at the origin.
+     * All edges and anchor coordinates are set to zero.
      */
     constructor();
     /**
-     * Create rectangle with left, right, top, bottom.
-     * Properties anchorX and anchorY will be centered in the middle.
+     * Create a rectangle from `{ left, top, width, height }`.
+     * The anchor is placed at the geometric center.
+     */
+    constructor(other: {
+        left: number;
+        top: number;
+        width: number;
+        height: number;
+    });
+    /**
+     * Create a deep copy of another AnchoredRect.
+     */
+    constructor(other: AnchoredRect);
+    /**
+     * Create a rectangle from edge coordinates.
+     * The anchor is placed at the geometric center.
      *
-     * @param left - Left coordinate.
-     * @param right - Right coordinate.
-     * @param top - Top coordinate.
-     * @param bottom - Bottom coordinate.
+     * @param left - Left edge
+     * @param right - Right edge
+     * @param top - Top edge
+     * @param bottom - Bottom edge
      */
     constructor(left: number, right: number, top: number, bottom: number);
     /**
-     * Create rectangle with full arguments.
+     * Create a rectangle with explicit edge and anchor coordinates.
      *
-     * @param left - Left coordinate.
-     * @param anchorX - Center x-coordinate.
-     * @param right - Right coordinate.
-     * @param top - Top coordinate.
-     * @param anchorY - Center y-coordinate.
-     * @param bottom - Bottom coordinate.
+     * @param left - Left edge
+     * @param anchorX - Anchor x-coordinate
+     * @param right - Right edge
+     * @param top - Top edge
+     * @param anchorY - Anchor y-coordinate
+     * @param bottom - Bottom edge
      */
     constructor(left: number, anchorX: number, right: number, top: number, anchorY: number, bottom: number);
     /**
-     * Set rectangle with all zero values.
+     * Reset this rectangle to the origin.
+     * All edges and anchor coordinates are set to zero.
      */
     set(): AnchoredRect;
     /**
-     * Set rectangle with left, right, top, bottom.
-     * Properties anchorX and anchorY will be centered in the middle.
-     *
-     * @param left - Left coordinate.
-     * @param right - Right coordinate.
-     * @param top - Top coordinate.
-     * @param bottom - Bottom coordinate.
+     * Set rectangle edges.
+     * The anchor is repositioned to the geometric center.
      */
     set(left: number, right: number, top: number, bottom: number): AnchoredRect;
     /**
-     * Set rectangle with full arguments.
-     *
-     * @param left - Left coordinate.
-     * @param anchorX - Center x-coordinate.
-     * @param right - Right coordinate.
-     * @param top - Top coordinate.
-     * @param anchorY - Center y-coordinate.
-     * @param bottom - Bottom coordinate.
+     * Set rectangle edges and anchor explicitly.
      */
     set(left: number, anchorX: number, right: number, top: number, anchorY: number, bottom: number): AnchoredRect;
     /**
@@ -920,130 +1114,126 @@ declare class AnchoredRect {
      * @returns - AnchoredRect.
      */
     static createSections(leftw: number, rightw: number, toph: number, bottomh: number): AnchoredRect;
-    /**
-     * Get center x-coordinate.
-     */
+    /** Geometric center x-coordinate (ignores anchor). */
     get centerX(): number;
-    /**
-     * Get center ycoordinate.
-     */
+    /** Geometric center y-coordinate (ignores anchor). */
     get centerY(): number;
-    /**
-     * Width getter.
-     */
+    /** Rectangle width (`right - left`). */
     get width(): number;
-    /**
-     * Height getter.
-     */
+    /** Rectangle height (`bottom - top`). */
     get height(): number;
-    /**
-     * Left section width getter.
-     */
+    /** Distance from left edge to anchor. */
     get leftw(): number;
-    /**
-     * Right section width getter.
-     */
+    /** Distance from anchor to right edge. */
     get rightw(): number;
+    /** Distance from top edge to anchor. */
+    get toph(): number;
+    /** Distance from anchor to bottom edge. */
+    get bottomh(): number;
     /**
-     * Top section height getter.
+     * Test whether a point lies inside or on the edges of this rectangle.
      */
-    get toph(): number;
+    contains(x: number, y: number): boolean;
     /**
-     * Bottom section height getter.
+     * 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.
      */
-    get bottomh(): number;
+    insetCopy(dx: number, dy?: number): AnchoredRect;
     /**
-     * Does this Rect contain given (x, y)-point?
+     * Create an inflated (expanded) copy of this rectangle.
+     *
+     * The rectangle edges are moved outward by the given amounts.
+     * The anchor position is preserved.
      *
-     * @param x - X-coordinate.
-     * @param y - Y-coordinate.
-     * @returns - True/false.
+     * @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.
      */
-    contains(x: number, y: number): boolean;
+    inflateCopy(dx: number, dy?: number): AnchoredRect;
     /**
-     * Do a and b rects overlap?
+     * Test whether this rectangle intersects another rectangle.
      *
-     * @param a - AnchoredRect a.
-     * @param b - AnchoredRect b.
-     * @returns - True/false.
+     * Edge-touching is considered an intersection.
+     * Accepts either an AnchoredRect or a rect-like object
+     * with `{ left, top, width, height }`.
+     */
+    intersects(other: AnchoredRect): boolean;
+    intersects(other: {
+        left: number;
+        top: number;
+        width: number;
+        height: number;
+    }): boolean;
+    /**
+     * This method requires strict overlap (edge-touching does NOT count).
      */
     static overlap(a: AnchoredRect, b: AnchoredRect): boolean;
     /**
-     * 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: AnchoredRect, b: AnchoredRect): boolean;
     /**
-     * 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: AnchoredRect | null | undefined, b: AnchoredRect | null | undefined): boolean;
     /**
-     * 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: AnchoredRect): boolean;
     /**
-     * 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: AnchoredRect | null | undefined, b: AnchoredRect | null | undefined): boolean;
     /**
-     * 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: AnchoredRect): boolean;
     /**
-     * Created duplicate of this Rect.
-     * @returns - Duplicate.
+     * Create copy.
      */
     clone(): AnchoredRect;
     /**
-     * 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: number, dy: number): AnchoredRect;
     /**
-     * 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: number, dy: number): AnchoredRect;
     /**
-     * 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: AnchoredRect): AnchoredRect;
+    unionInPlace(other: AnchoredRect): AnchoredRect;
+    /** @deprecated - Use unionInPlace(). */
+    expandInPlace(other: AnchoredRect): AnchoredRect;
     /**
-     * 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: AnchoredRect): AnchoredRect;
+    unionCopy(other: AnchoredRect): AnchoredRect;
+    /** @deprecated - Use unionCopy(). */
+    expandCopy(other: AnchoredRect): AnchoredRect;
     /**
-     * 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: AnchoredRect): AnchoredRect;
     /**
@@ -1054,11 +1244,8 @@ declare class AnchoredRect {
      */
     clipCopy(clipRect: AnchoredRect): AnchoredRect;
     /**
-     * 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: number, scaleY?: number): AnchoredRect;
     /**
@@ -1070,11 +1257,15 @@ declare class AnchoredRect {
      */
     scaleCopy(scaleX: number, scaleY?: number): AnchoredRect;
     /**
-     * Get this AnchoredRect instance.
-     * @returns - This AnchoredRect instance.
+     * Return this rect.
      */
     getRect(): AnchoredRect;
+    /**
+     * Convert to a basic Rect using geometric edges.
+     * Anchor information is discarded.
+     */
     toRect(): Rect;
+    /** String of this rect. */
     toString(): string;
 }