@js-draw/math 1.22.0 → 1.24.1

package/src/shapes/BezierJSWrapper.ts

@@ -4,6 +4,11 @@ import LineSegment2 from './LineSegment2';
 import Rect2 from './Rect2';
 import Parameterized2DShape from './Parameterized2DShape';
 
+// The typings for Bezier are incorrect in some cases:
+interface CorrectedBezierType extends Bezier {
+	dderivative(t: number): { x: number; y: number };
+}
+
 /**
  * A lazy-initializing wrapper around Bezier-js.
  *
@@ -14,13 +19,13 @@ import Parameterized2DShape from './Parameterized2DShape';
  * @internal
  */
 export abstract class BezierJSWrapper extends Parameterized2DShape {
-	#bezierJs: Bezier | null = null;
+	#bezierJs: CorrectedBezierType | null = null;
 
 	protected constructor(bezierJsBezier?: Bezier) {
 		super();
 
 		if (bezierJsBezier) {
-			this.#bezierJs = bezierJsBezier;
+			this.#bezierJs = bezierJsBezier as CorrectedBezierType;
 		}
 	}
 
@@ -29,7 +34,7 @@ export abstract class BezierJSWrapper extends Parameterized2DShape {
 
 	protected getBezier() {
 		if (!this.#bezierJs) {
-			this.#bezierJs = new Bezier(this.getPoints().map((p) => p.xy));
+			this.#bezierJs = new Bezier(this.getPoints().map((p) => p.xy)) as CorrectedBezierType;
 		}
 		return this.#bezierJs;
 	}
@@ -56,14 +61,16 @@ export abstract class BezierJSWrapper extends Parameterized2DShape {
 		return Vec2.ofXY(this.getBezier().get(t));
 	}
 
+	/** @returns the curve's directional derivative at `t`. */
 	public derivativeAt(t: number): Point2 {
 		return Vec2.ofXY(this.getBezier().derivative(t));
 	}
 
 	public secondDerivativeAt(t: number): Point2 {
-		return Vec2.ofXY((this.getBezier() as any).dderivative(t));
+		return Vec2.ofXY(this.getBezier().dderivative(t));
 	}
 
+	/** @returns the [normal vector](https://en.wikipedia.org/wiki/Normal_(geometry)) to this curve at `t`. */
 	public normal(t: number): Vec2 {
 		return Vec2.ofXY(this.getBezier().normal(t));
 	}

package/src/shapes/Path.ts

@@ -11,6 +11,7 @@ import Parameterized2DShape from './Parameterized2DShape';
 import BezierJSWrapper from './BezierJSWrapper';
 import convexHull2Of from '../utils/convexHull2Of';
 
+/** Identifiers for different path commands. These commands can make up a {@link Path}. */
 export enum PathCommandType {
 	LineTo,
 	MoveTo,

package/src/shapes/QuadraticBezier.ts

@@ -4,14 +4,34 @@ import BezierJSWrapper from './BezierJSWrapper';
 import Rect2 from './Rect2';
 
 /**
- * Represents a 2D Bézier curve.
+ * Represents a 2D [Bézier curve](https://en.wikipedia.org/wiki/B%C3%A9zier_curve).
  *
- * **Note**: Many Bézier operations use `bezier-js`'s.
+ * Example:
+ * ```ts,runnable,console
+ * import { QuadraticBezier, Vec2 } from '@js-draw/math';
+ *
+ * const startPoint = Vec2.of(4, 3);
+ * const controlPoint = Vec2.of(1, 1);
+ * const endPoint = Vec2.of(1, 3);
+ *
+ * const curve = new QuadraticBezier(
+ *   startPoint,
+ *   controlPoint,
+ *   endPoint,
+ * );
+ *
+ * console.log('Curve:', curve);
+ * ```
+ *
+ * **Note**: Some Bézier operations internally use the `bezier-js` library.
  */
 export class QuadraticBezier extends BezierJSWrapper {
 	public constructor(
+		// Start point
 		public readonly p0: Point2,
+		// Control point
 		public readonly p1: Point2,
+		// End point
 		public readonly p2: Point2,
 	) {
 		super();

package/src/shapes/Rect2.ts

@@ -17,6 +17,18 @@ export interface RectTemplate {
 /**
  * Represents a rectangle in 2D space, parallel to the XY axes.
  *
+ * **Example**:
+ * ```ts,runnable,console
+ * import { Rect2, Vec2 } from '@js-draw/math';
+ *
+ * const rect = Rect2.fromCorners(
+ *   Vec2.of(0, 0),
+ *   Vec2.of(10, 10),
+ * );
+ * console.log('area', rect.area);
+ * console.log('topLeft', rect.topLeft);
+ * ```
+ *
  * `invariant: w ≥ 0, h ≥ 0, immutable`
  */
 export class Rect2 extends Abstract2DShape {
@@ -28,9 +40,13 @@ export class Rect2 extends Abstract2DShape {
 	public readonly area: number;
 
 	public constructor(
+		// Top left x coordinate
 		public readonly x: number,
+		// Top left y coordinate
 		public readonly y: number,
+		// Width
 		public readonly w: number,
+		// Height
 		public readonly h: number,
 	) {
 		super();
@@ -69,6 +85,7 @@ export class Rect2 extends Abstract2DShape {
 		);
 	}
 
+	/** @returns true iff `other` is completely within this `Rect2`. */
 	public containsRect(other: Rect2): boolean {
 		return (
 			this.x <= other.x &&