@js-draw/math 1.19.0 → 1.21.1

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2023 Henry Heino
+Copyright (c) 2023-2024 Henry Heino
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/dist/cjs/Mat33.d.ts

@@ -1,5 +1,8 @@
 import { Point2, Vec2 } from './Vec2';
 import Vec3 from './Vec3';
+/**
+ * See {@link Mat33.toArray}.
+ */
 export type Mat33Array = [
     number,
     number,
@@ -15,6 +18,46 @@ export type Mat33Array = [
  * Represents a three dimensional linear transformation or
  * a two-dimensional affine transformation. (An affine transformation scales/rotates/shears
  * **and** translates while a linear transformation just scales/rotates/shears).
+ *
+ * In addition to other matrices, {@link Mat33}s can be used to transform {@link Vec3}s and {@link Vec2}s.
+ *
+ * For example, to move the point $(1, 1)$ by 5 units to the left and 6 units up,
+ * ```ts,runnable,console
+ * import {Mat33, Vec2} from '@js-draw/math';
+ *
+ * const moveLeftAndUp = Mat33.translation(Vec2.of(5, 6));
+ * console.log(moveLeftAndUp);
+ * ```
+ *
+ * This `moveLeftAndUp` matrix could then translate (move) a {@link Vec2} using
+ * {@link Mat33.transformVec2}:
+ *
+ * ```ts,runnable,console
+ * ---use-previous---
+ * ---visible---
+ * console.log(moveLeftAndUp.transformVec2(Vec2.of(1, 1)));
+ * console.log(moveLeftAndUp.transformVec2(Vec2.of(-1, 2)));
+ * ```
+ *
+ * It's also possible to create transformation matrices that scale and rotate.
+ * A single transform matrix can be created from multiple using matrix multiplication
+ * (see {@link Mat33.rightMul}):
+ *
+ * ```ts,runnable,console
+ * ---use-previous---
+ * ---visible---
+ * // Create a matrix by right multiplying.
+ * const scaleThenRotate =
+ *   // The resultant matrix first scales by a factor of two
+ *   Mat33.scaling2D(2).rightMul(
+ *     // ...then rotates by pi/2 radians = 90 degrees.
+ *     Mat33.zRotation(Math.PI / 2)
+ *   );
+ * console.log(scaleThenRotate);
+ *
+ * // Use scaleThenRotate to scale then rotate a vector.
+ * console.log(scaleThenRotate.transformVec2(Vec2.unitX));
+ * ```
  */
 export declare class Mat33 {
     readonly a1: number;
@@ -36,6 +79,9 @@ export declare class Mat33 {
      *   c1 & c2 & c3
      * \end{bmatrix}
      * $$
+     *
+     * Static constructor methods are also available.
+     * See {@link Mat33.scaling2D}, {@link Mat33.zRotation}, {@link Mat33.translation}, and {@link Mat33.fromCSSMatrix}.
      */
     constructor(a1: number, a2: number, a3: number, b1: number, b2: number, b3: number, c1: number, c2: number, c3: number);
     /**
@@ -49,6 +95,7 @@ export declare class Mat33 {
      * $$
      */
     static ofRows(r1: Vec3, r2: Vec3, r3: Vec3): Mat33;
+    /** The 3x3 [identity matrix](https://en.wikipedia.org/wiki/Identity_matrix). */
     static identity: Mat33;
     /**
      * Either returns the inverse of this, or, if this matrix is singular/uninvertable,
@@ -62,6 +109,29 @@ export declare class Mat33 {
     private cachedInverse;
     private computeInverse;
     transposed(): Mat33;
+    /**
+     * [Right-multiplies](https://en.wikipedia.org/wiki/Matrix_multiplication) this by `other`.
+     *
+     * See also {@link transformVec3} and {@link transformVec2}.
+     *
+     * Example:
+     * ```ts,runnable,console
+     * import {Mat33, Vec2} from '@js-draw/math';
+     * console.log(Mat33.identity.rightMul(Mat33.identity));
+     *
+     * // Create a matrix by right multiplying.
+     * const scaleThenRotate =
+     *   // The resultant matrix first scales by a factor of two
+     *   Mat33.scaling2D(2).rightMul(
+     *     // ...then rotates by pi/4 radians = 45 degrees.
+     *     Mat33.zRotation(Math.PI / 4)
+     *   );
+     * console.log(scaleThenRotate);
+     *
+     * // Use scaleThenRotate to scale then rotate a vector.
+     * console.log(scaleThenRotate.transformVec2(Vec2.unitX));
+     * ```
+     */
     rightMul(other: Mat33): Mat33;
     /**
      * Applies this as an **affine** transformation to the given vector.
@@ -79,6 +149,15 @@ export declare class Mat33 {
     isIdentity(): boolean;
     /** Returns true iff this = other ± fuzz */
     eq(other: Mat33, fuzz?: number): boolean;
+    /**
+     * Creates a human-readable representation of the matrix.
+     *
+     * Example:
+     * ```ts,runnable,console
+     * import { Mat33 } from '@js-draw/math';
+     * console.log(Mat33.identity.toString());
+     * ```
+     */
     toString(): string;
     /**
      * ```
@@ -86,6 +165,18 @@ export declare class Mat33 {
      * result[1] = element at row zero, column 1
      * ...
      * ```
+     *
+     * Example:
+     * ```ts,runnable,console
+     * import { Mat33 } from '@js-draw/math';
+     * console.log(
+     *   new Mat33(
+     *     1, 2, 3,
+     *     4, 5, 6,
+     *     7, 8, 9,
+     *   )
+     * );
+     * ```
      */
     toArray(): Mat33Array;
     /**

package/dist/cjs/Mat33.js

@@ -10,6 +10,46 @@ const Vec3_1 = __importDefault(require("./Vec3"));
  * Represents a three dimensional linear transformation or
  * a two-dimensional affine transformation. (An affine transformation scales/rotates/shears
  * **and** translates while a linear transformation just scales/rotates/shears).
+ *
+ * In addition to other matrices, {@link Mat33}s can be used to transform {@link Vec3}s and {@link Vec2}s.
+ *
+ * For example, to move the point $(1, 1)$ by 5 units to the left and 6 units up,
+ * ```ts,runnable,console
+ * import {Mat33, Vec2} from '@js-draw/math';
+ *
+ * const moveLeftAndUp = Mat33.translation(Vec2.of(5, 6));
+ * console.log(moveLeftAndUp);
+ * ```
+ *
+ * This `moveLeftAndUp` matrix could then translate (move) a {@link Vec2} using
+ * {@link Mat33.transformVec2}:
+ *
+ * ```ts,runnable,console
+ * ---use-previous---
+ * ---visible---
+ * console.log(moveLeftAndUp.transformVec2(Vec2.of(1, 1)));
+ * console.log(moveLeftAndUp.transformVec2(Vec2.of(-1, 2)));
+ * ```
+ *
+ * It's also possible to create transformation matrices that scale and rotate.
+ * A single transform matrix can be created from multiple using matrix multiplication
+ * (see {@link Mat33.rightMul}):
+ *
+ * ```ts,runnable,console
+ * ---use-previous---
+ * ---visible---
+ * // Create a matrix by right multiplying.
+ * const scaleThenRotate =
+ *   // The resultant matrix first scales by a factor of two
+ *   Mat33.scaling2D(2).rightMul(
+ *     // ...then rotates by pi/2 radians = 90 degrees.
+ *     Mat33.zRotation(Math.PI / 2)
+ *   );
+ * console.log(scaleThenRotate);
+ *
+ * // Use scaleThenRotate to scale then rotate a vector.
+ * console.log(scaleThenRotate.transformVec2(Vec2.unitX));
+ * ```
  */
 class Mat33 {
     /**
@@ -21,6 +61,9 @@ class Mat33 {
      *   c1 & c2 & c3
      * \end{bmatrix}
      * $$
+     *
+     * Static constructor methods are also available.
+     * See {@link Mat33.scaling2D}, {@link Mat33.zRotation}, {@link Mat33.translation}, and {@link Mat33.fromCSSMatrix}.
      */
     constructor(a1, a2, a3, b1, b2, b3, c1, c2, c3) {
         this.a1 = a1;
@@ -131,6 +174,29 @@ class Mat33 {
     transposed() {
         return new Mat33(this.a1, this.b1, this.c1, this.a2, this.b2, this.c2, this.a3, this.b3, this.c3);
     }
+    /**
+     * [Right-multiplies](https://en.wikipedia.org/wiki/Matrix_multiplication) this by `other`.
+     *
+     * See also {@link transformVec3} and {@link transformVec2}.
+     *
+     * Example:
+     * ```ts,runnable,console
+     * import {Mat33, Vec2} from '@js-draw/math';
+     * console.log(Mat33.identity.rightMul(Mat33.identity));
+     *
+     * // Create a matrix by right multiplying.
+     * const scaleThenRotate =
+     *   // The resultant matrix first scales by a factor of two
+     *   Mat33.scaling2D(2).rightMul(
+     *     // ...then rotates by pi/4 radians = 45 degrees.
+     *     Mat33.zRotation(Math.PI / 4)
+     *   );
+     * console.log(scaleThenRotate);
+     *
+     * // Use scaleThenRotate to scale then rotate a vector.
+     * console.log(scaleThenRotate.transformVec2(Vec2.unitX));
+     * ```
+     */
     rightMul(other) {
         other = other.transposed();
         const at = (row, col) => {
@@ -180,6 +246,15 @@ class Mat33 {
         }
         return true;
     }
+    /**
+     * Creates a human-readable representation of the matrix.
+     *
+     * Example:
+     * ```ts,runnable,console
+     * import { Mat33 } from '@js-draw/math';
+     * console.log(Mat33.identity.toString());
+     * ```
+     */
     toString() {
         let result = '';
         const maxColumnLens = [0, 0, 0];
@@ -228,6 +303,18 @@ class Mat33 {
      * result[1] = element at row zero, column 1
      * ...
      * ```
+     *
+     * Example:
+     * ```ts,runnable,console
+     * import { Mat33 } from '@js-draw/math';
+     * console.log(
+     *   new Mat33(
+     *     1, 2, 3,
+     *     4, 5, 6,
+     *     7, 8, 9,
+     *   )
+     * );
+     * ```
      */
     toArray() {
         return [
@@ -436,5 +523,6 @@ class Mat33 {
     }
 }
 exports.Mat33 = Mat33;
+/** The 3x3 [identity matrix](https://en.wikipedia.org/wiki/Identity_matrix). */
 Mat33.identity = new Mat33(1, 0, 0, 0, 1, 0, 0, 0, 1);
 exports.default = Mat33;

package/dist/cjs/shapes/LineSegment2.d.ts

@@ -7,7 +7,18 @@ interface IntersectionResult {
     point: Point2;
     t: number;
 }
-/** Represents a line segment. A `LineSegment2` is immutable. */
+/**
+ * Represents a line segment. A `LineSegment2` is immutable.
+ *
+ * @example
+ * ```ts,runnable,console
+ * import {LineSegment2, Vec2} from '@js-draw/math';
+ * const l = new LineSegment2(Vec2.of(1, 1), Vec2.of(2, 2));
+ * console.log('length: ', l.length);
+ * console.log('direction: ', l.direction);
+ * console.log('bounding box: ', l.bbox);
+ * ```
+ */
 export declare class LineSegment2 extends Parameterized2DShape {
     private readonly point1;
     private readonly point2;
@@ -30,7 +41,7 @@ export declare class LineSegment2 extends Parameterized2DShape {
      * if no such line segment exists.
      *
      * @example
-     * ```ts,runnable
+     * ```ts,runnable,console
      * import {LineSegment2, Vec2} from '@js-draw/math';
      * console.log(LineSegment2.ofSmallestContainingPoints([Vec2.of(1, 0), Vec2.of(0, 1)]));
      * ```

package/dist/cjs/shapes/LineSegment2.js

@@ -7,7 +7,18 @@ exports.LineSegment2 = void 0;
 const Rect2_1 = __importDefault(require("./Rect2"));
 const Vec2_1 = require("../Vec2");
 const Parameterized2DShape_1 = __importDefault(require("./Parameterized2DShape"));
-/** Represents a line segment. A `LineSegment2` is immutable. */
+/**
+ * Represents a line segment. A `LineSegment2` is immutable.
+ *
+ * @example
+ * ```ts,runnable,console
+ * import {LineSegment2, Vec2} from '@js-draw/math';
+ * const l = new LineSegment2(Vec2.of(1, 1), Vec2.of(2, 2));
+ * console.log('length: ', l.length);
+ * console.log('direction: ', l.direction);
+ * console.log('bounding box: ', l.bbox);
+ * ```
+ */
 class LineSegment2 extends Parameterized2DShape_1.default {
     /** Creates a new `LineSegment2` from its endpoints. */
     constructor(point1, point2) {
@@ -27,7 +38,7 @@ class LineSegment2 extends Parameterized2DShape_1.default {
      * if no such line segment exists.
      *
      * @example
-     * ```ts,runnable
+     * ```ts,runnable,console
      * import {LineSegment2, Vec2} from '@js-draw/math';
      * console.log(LineSegment2.ofSmallestContainingPoints([Vec2.of(1, 0), Vec2.of(0, 1)]));
      * ```

package/dist/cjs/shapes/PointShape2D.d.ts

@@ -41,7 +41,7 @@ declare class PointShape2D extends Parameterized2DShape {
         minus(v: Vec3): Vec3;
         dot(other: Vec3): number;
         cross(other: Vec3): Vec3;
-        scale(other: number | Vec3): Vec3;
+        scale(other: Vec3 | number): Vec3;
         orthog(): Vec3;
         extend(distance: number, direction: Vec3): Vec3;
         lerp(target: Vec3, fractionTo: number): Vec3;

package/dist/cjs/shapes/Rect2.d.ts

@@ -80,7 +80,7 @@ export declare class Rect2 extends Abstract2DShape {
         minus(v: Vec3): Vec3;
         dot(other: Vec3): number;
         cross(other: Vec3): Vec3;
-        scale(other: number | Vec3): Vec3;
+        scale(other: Vec3 | number): Vec3;
         orthog(): Vec3;
         extend(distance: number, direction: Vec3): Vec3;
         lerp(target: Vec3, fractionTo: number): Vec3;

package/dist/mjs/Mat33.d.ts

@@ -1,5 +1,8 @@
 import { Point2, Vec2 } from './Vec2';
 import Vec3 from './Vec3';
+/**
+ * See {@link Mat33.toArray}.
+ */
 export type Mat33Array = [
     number,
     number,
@@ -15,6 +18,46 @@ export type Mat33Array = [
  * Represents a three dimensional linear transformation or
  * a two-dimensional affine transformation. (An affine transformation scales/rotates/shears
  * **and** translates while a linear transformation just scales/rotates/shears).
+ *
+ * In addition to other matrices, {@link Mat33}s can be used to transform {@link Vec3}s and {@link Vec2}s.
+ *
+ * For example, to move the point $(1, 1)$ by 5 units to the left and 6 units up,
+ * ```ts,runnable,console
+ * import {Mat33, Vec2} from '@js-draw/math';
+ *
+ * const moveLeftAndUp = Mat33.translation(Vec2.of(5, 6));
+ * console.log(moveLeftAndUp);
+ * ```
+ *
+ * This `moveLeftAndUp` matrix could then translate (move) a {@link Vec2} using
+ * {@link Mat33.transformVec2}:
+ *
+ * ```ts,runnable,console
+ * ---use-previous---
+ * ---visible---
+ * console.log(moveLeftAndUp.transformVec2(Vec2.of(1, 1)));
+ * console.log(moveLeftAndUp.transformVec2(Vec2.of(-1, 2)));
+ * ```
+ *
+ * It's also possible to create transformation matrices that scale and rotate.
+ * A single transform matrix can be created from multiple using matrix multiplication
+ * (see {@link Mat33.rightMul}):
+ *
+ * ```ts,runnable,console
+ * ---use-previous---
+ * ---visible---
+ * // Create a matrix by right multiplying.
+ * const scaleThenRotate =
+ *   // The resultant matrix first scales by a factor of two
+ *   Mat33.scaling2D(2).rightMul(
+ *     // ...then rotates by pi/2 radians = 90 degrees.
+ *     Mat33.zRotation(Math.PI / 2)
+ *   );
+ * console.log(scaleThenRotate);
+ *
+ * // Use scaleThenRotate to scale then rotate a vector.
+ * console.log(scaleThenRotate.transformVec2(Vec2.unitX));
+ * ```
  */
 export declare class Mat33 {
     readonly a1: number;
@@ -36,6 +79,9 @@ export declare class Mat33 {
      *   c1 & c2 & c3
      * \end{bmatrix}
      * $$
+     *
+     * Static constructor methods are also available.
+     * See {@link Mat33.scaling2D}, {@link Mat33.zRotation}, {@link Mat33.translation}, and {@link Mat33.fromCSSMatrix}.
      */
     constructor(a1: number, a2: number, a3: number, b1: number, b2: number, b3: number, c1: number, c2: number, c3: number);
     /**
@@ -49,6 +95,7 @@ export declare class Mat33 {
      * $$
      */
     static ofRows(r1: Vec3, r2: Vec3, r3: Vec3): Mat33;
+    /** The 3x3 [identity matrix](https://en.wikipedia.org/wiki/Identity_matrix). */
     static identity: Mat33;
     /**
      * Either returns the inverse of this, or, if this matrix is singular/uninvertable,
@@ -62,6 +109,29 @@ export declare class Mat33 {
     private cachedInverse;
     private computeInverse;
     transposed(): Mat33;
+    /**
+     * [Right-multiplies](https://en.wikipedia.org/wiki/Matrix_multiplication) this by `other`.
+     *
+     * See also {@link transformVec3} and {@link transformVec2}.
+     *
+     * Example:
+     * ```ts,runnable,console
+     * import {Mat33, Vec2} from '@js-draw/math';
+     * console.log(Mat33.identity.rightMul(Mat33.identity));
+     *
+     * // Create a matrix by right multiplying.
+     * const scaleThenRotate =
+     *   // The resultant matrix first scales by a factor of two
+     *   Mat33.scaling2D(2).rightMul(
+     *     // ...then rotates by pi/4 radians = 45 degrees.
+     *     Mat33.zRotation(Math.PI / 4)
+     *   );
+     * console.log(scaleThenRotate);
+     *
+     * // Use scaleThenRotate to scale then rotate a vector.
+     * console.log(scaleThenRotate.transformVec2(Vec2.unitX));
+     * ```
+     */
     rightMul(other: Mat33): Mat33;
     /**
      * Applies this as an **affine** transformation to the given vector.
@@ -79,6 +149,15 @@ export declare class Mat33 {
     isIdentity(): boolean;
     /** Returns true iff this = other ± fuzz */
     eq(other: Mat33, fuzz?: number): boolean;
+    /**
+     * Creates a human-readable representation of the matrix.
+     *
+     * Example:
+     * ```ts,runnable,console
+     * import { Mat33 } from '@js-draw/math';
+     * console.log(Mat33.identity.toString());
+     * ```
+     */
     toString(): string;
     /**
      * ```
@@ -86,6 +165,18 @@ export declare class Mat33 {
      * result[1] = element at row zero, column 1
      * ...
      * ```
+     *
+     * Example:
+     * ```ts,runnable,console
+     * import { Mat33 } from '@js-draw/math';
+     * console.log(
+     *   new Mat33(
+     *     1, 2, 3,
+     *     4, 5, 6,
+     *     7, 8, 9,
+     *   )
+     * );
+     * ```
      */
     toArray(): Mat33Array;
     /**

package/dist/mjs/Mat33.mjs

@@ -4,6 +4,46 @@ import  Vec3  from './Vec3.mjs';
  * Represents a three dimensional linear transformation or
  * a two-dimensional affine transformation. (An affine transformation scales/rotates/shears
  * **and** translates while a linear transformation just scales/rotates/shears).
+ *
+ * In addition to other matrices, {@link Mat33}s can be used to transform {@link Vec3}s and {@link Vec2}s.
+ *
+ * For example, to move the point $(1, 1)$ by 5 units to the left and 6 units up,
+ * ```ts,runnable,console
+ * import {Mat33, Vec2} from '@js-draw/math';
+ *
+ * const moveLeftAndUp = Mat33.translation(Vec2.of(5, 6));
+ * console.log(moveLeftAndUp);
+ * ```
+ *
+ * This `moveLeftAndUp` matrix could then translate (move) a {@link Vec2} using
+ * {@link Mat33.transformVec2}:
+ *
+ * ```ts,runnable,console
+ * ---use-previous---
+ * ---visible---
+ * console.log(moveLeftAndUp.transformVec2(Vec2.of(1, 1)));
+ * console.log(moveLeftAndUp.transformVec2(Vec2.of(-1, 2)));
+ * ```
+ *
+ * It's also possible to create transformation matrices that scale and rotate.
+ * A single transform matrix can be created from multiple using matrix multiplication
+ * (see {@link Mat33.rightMul}):
+ *
+ * ```ts,runnable,console
+ * ---use-previous---
+ * ---visible---
+ * // Create a matrix by right multiplying.
+ * const scaleThenRotate =
+ *   // The resultant matrix first scales by a factor of two
+ *   Mat33.scaling2D(2).rightMul(
+ *     // ...then rotates by pi/2 radians = 90 degrees.
+ *     Mat33.zRotation(Math.PI / 2)
+ *   );
+ * console.log(scaleThenRotate);
+ *
+ * // Use scaleThenRotate to scale then rotate a vector.
+ * console.log(scaleThenRotate.transformVec2(Vec2.unitX));
+ * ```
  */
 export class Mat33 {
     /**
@@ -15,6 +55,9 @@ export class Mat33 {
      *   c1 & c2 & c3
      * \end{bmatrix}
      * $$
+     *
+     * Static constructor methods are also available.
+     * See {@link Mat33.scaling2D}, {@link Mat33.zRotation}, {@link Mat33.translation}, and {@link Mat33.fromCSSMatrix}.
      */
     constructor(a1, a2, a3, b1, b2, b3, c1, c2, c3) {
         this.a1 = a1;
@@ -125,6 +168,29 @@ export class Mat33 {
     transposed() {
         return new Mat33(this.a1, this.b1, this.c1, this.a2, this.b2, this.c2, this.a3, this.b3, this.c3);
     }
+    /**
+     * [Right-multiplies](https://en.wikipedia.org/wiki/Matrix_multiplication) this by `other`.
+     *
+     * See also {@link transformVec3} and {@link transformVec2}.
+     *
+     * Example:
+     * ```ts,runnable,console
+     * import {Mat33, Vec2} from '@js-draw/math';
+     * console.log(Mat33.identity.rightMul(Mat33.identity));
+     *
+     * // Create a matrix by right multiplying.
+     * const scaleThenRotate =
+     *   // The resultant matrix first scales by a factor of two
+     *   Mat33.scaling2D(2).rightMul(
+     *     // ...then rotates by pi/4 radians = 45 degrees.
+     *     Mat33.zRotation(Math.PI / 4)
+     *   );
+     * console.log(scaleThenRotate);
+     *
+     * // Use scaleThenRotate to scale then rotate a vector.
+     * console.log(scaleThenRotate.transformVec2(Vec2.unitX));
+     * ```
+     */
     rightMul(other) {
         other = other.transposed();
         const at = (row, col) => {
@@ -174,6 +240,15 @@ export class Mat33 {
         }
         return true;
     }
+    /**
+     * Creates a human-readable representation of the matrix.
+     *
+     * Example:
+     * ```ts,runnable,console
+     * import { Mat33 } from '@js-draw/math';
+     * console.log(Mat33.identity.toString());
+     * ```
+     */
     toString() {
         let result = '';
         const maxColumnLens = [0, 0, 0];
@@ -222,6 +297,18 @@ export class Mat33 {
      * result[1] = element at row zero, column 1
      * ...
      * ```
+     *
+     * Example:
+     * ```ts,runnable,console
+     * import { Mat33 } from '@js-draw/math';
+     * console.log(
+     *   new Mat33(
+     *     1, 2, 3,
+     *     4, 5, 6,
+     *     7, 8, 9,
+     *   )
+     * );
+     * ```
      */
     toArray() {
         return [
@@ -429,5 +516,6 @@ export class Mat33 {
         return matrix ?? Mat33.identity;
     }
 }
+/** The 3x3 [identity matrix](https://en.wikipedia.org/wiki/Identity_matrix). */
 Mat33.identity = new Mat33(1, 0, 0, 0, 1, 0, 0, 0, 1);
 export default Mat33;

package/dist/mjs/shapes/LineSegment2.d.ts

@@ -7,7 +7,18 @@ interface IntersectionResult {
     point: Point2;
     t: number;
 }
-/** Represents a line segment. A `LineSegment2` is immutable. */
+/**
+ * Represents a line segment. A `LineSegment2` is immutable.
+ *
+ * @example
+ * ```ts,runnable,console
+ * import {LineSegment2, Vec2} from '@js-draw/math';
+ * const l = new LineSegment2(Vec2.of(1, 1), Vec2.of(2, 2));
+ * console.log('length: ', l.length);
+ * console.log('direction: ', l.direction);
+ * console.log('bounding box: ', l.bbox);
+ * ```
+ */
 export declare class LineSegment2 extends Parameterized2DShape {
     private readonly point1;
     private readonly point2;
@@ -30,7 +41,7 @@ export declare class LineSegment2 extends Parameterized2DShape {
      * if no such line segment exists.
      *
      * @example
-     * ```ts,runnable
+     * ```ts,runnable,console
      * import {LineSegment2, Vec2} from '@js-draw/math';
      * console.log(LineSegment2.ofSmallestContainingPoints([Vec2.of(1, 0), Vec2.of(0, 1)]));
      * ```

package/dist/mjs/shapes/LineSegment2.mjs

@@ -1,7 +1,18 @@
 import  Rect2  from './Rect2.mjs';
 import  { Vec2 }  from '../Vec2.mjs';
 import  Parameterized2DShape  from './Parameterized2DShape.mjs';
-/** Represents a line segment. A `LineSegment2` is immutable. */
+/**
+ * Represents a line segment. A `LineSegment2` is immutable.
+ *
+ * @example
+ * ```ts,runnable,console
+ * import {LineSegment2, Vec2} from '@js-draw/math';
+ * const l = new LineSegment2(Vec2.of(1, 1), Vec2.of(2, 2));
+ * console.log('length: ', l.length);
+ * console.log('direction: ', l.direction);
+ * console.log('bounding box: ', l.bbox);
+ * ```
+ */
 export class LineSegment2 extends Parameterized2DShape {
     /** Creates a new `LineSegment2` from its endpoints. */
     constructor(point1, point2) {
@@ -21,7 +32,7 @@ export class LineSegment2 extends Parameterized2DShape {
      * if no such line segment exists.
      *
      * @example
-     * ```ts,runnable
+     * ```ts,runnable,console
      * import {LineSegment2, Vec2} from '@js-draw/math';
      * console.log(LineSegment2.ofSmallestContainingPoints([Vec2.of(1, 0), Vec2.of(0, 1)]));
      * ```

package/dist/mjs/shapes/PointShape2D.d.ts

@@ -41,7 +41,7 @@ declare class PointShape2D extends Parameterized2DShape {
         minus(v: Vec3): Vec3;
         dot(other: Vec3): number;
         cross(other: Vec3): Vec3;
-        scale(other: number | Vec3): Vec3;
+        scale(other: Vec3 | number): Vec3;
         orthog(): Vec3;
         extend(distance: number, direction: Vec3): Vec3;
         lerp(target: Vec3, fractionTo: number): Vec3;

package/dist/mjs/shapes/Rect2.d.ts

@@ -80,7 +80,7 @@ export declare class Rect2 extends Abstract2DShape {
         minus(v: Vec3): Vec3;
         dot(other: Vec3): number;
         cross(other: Vec3): Vec3;
-        scale(other: number | Vec3): Vec3;
+        scale(other: Vec3 | number): Vec3;
         orthog(): Vec3;
         extend(distance: number, direction: Vec3): Vec3;
         lerp(target: Vec3, fractionTo: number): Vec3;

package/dist-test/test_imports/yarn.lock

@@ -0,0 +1,12 @@
+# This file is generated by running "yarn install" inside your project.
+# Manual changes might be lost - proceed with caution!
+
+__metadata:
+  version: 8
+  cacheKey: 10c0
+
+"js-draw-math-test-imports@workspace:.":
+  version: 0.0.0-use.local
+  resolution: "js-draw-math-test-imports@workspace:."
+  languageName: unknown
+  linkType: soft

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@js-draw/math",
-	"version": "1.19.0",
+	"version": "1.21.1",
 	"description": "A math library for js-draw. ",
 	"types": "./dist/mjs/lib.d.ts",
 	"main": "./dist/cjs/lib.js",
@@ -17,18 +17,17 @@
 	},
 	"author": "Henry Heino",
 	"license": "MIT",
-	"private": false,
 	"scripts": {
-		"dist-test": "cd dist-test/test_imports && npm install && npm run test",
-		"dist": "npm run build && npm run dist-test",
-		"build": "rm -rf ./dist && build-tool build",
+		"dist-test": "cd dist-test/test_imports && yarn install && yarn run test",
+		"dist": "yarn run build && yarn run dist-test",
+		"build": "build-tool build",
 		"watch": "build-tool watch"
 	},
 	"dependencies": {
 		"bezier-js": "6.1.3"
 	},
 	"devDependencies": {
-		"@js-draw/build-tool": "^1.19.0",
+		"@js-draw/build-tool": "^1.21.1",
 		"@types/bezier-js": "4.1.0",
 		"@types/jest": "29.5.5",
 		"@types/jsdom": "21.1.3"
@@ -45,5 +44,5 @@
 		"svg",
 		"math"
 	],
-	"gitHead": "50fa44a2bb68b93d24efea433760a5e45c56293f"
+	"gitHead": "a46f0e1c3586e4b3019152eea87cd2784b00282f"
 }

package/src/Mat33.ts

@@ -1,6 +1,9 @@
 import { Point2, Vec2 } from './Vec2';
 import Vec3 from './Vec3';
 
+/**
+ * See {@link Mat33.toArray}.
+ */
 export type Mat33Array = [
 	number, number, number,
 	number, number, number,
@@ -11,6 +14,46 @@ export type Mat33Array = [
  * Represents a three dimensional linear transformation or
  * a two-dimensional affine transformation. (An affine transformation scales/rotates/shears
  * **and** translates while a linear transformation just scales/rotates/shears).
+ *
+ * In addition to other matrices, {@link Mat33}s can be used to transform {@link Vec3}s and {@link Vec2}s.
+ *
+ * For example, to move the point $(1, 1)$ by 5 units to the left and 6 units up,
+ * ```ts,runnable,console
+ * import {Mat33, Vec2} from '@js-draw/math';
+ *
+ * const moveLeftAndUp = Mat33.translation(Vec2.of(5, 6));
+ * console.log(moveLeftAndUp);
+ * ```
+ *
+ * This `moveLeftAndUp` matrix could then translate (move) a {@link Vec2} using
+ * {@link Mat33.transformVec2}:
+ *
+ * ```ts,runnable,console
+ * ---use-previous---
+ * ---visible---
+ * console.log(moveLeftAndUp.transformVec2(Vec2.of(1, 1)));
+ * console.log(moveLeftAndUp.transformVec2(Vec2.of(-1, 2)));
+ * ```
+ *
+ * It's also possible to create transformation matrices that scale and rotate.
+ * A single transform matrix can be created from multiple using matrix multiplication
+ * (see {@link Mat33.rightMul}):
+ *
+ * ```ts,runnable,console
+ * ---use-previous---
+ * ---visible---
+ * // Create a matrix by right multiplying.
+ * const scaleThenRotate =
+ *   // The resultant matrix first scales by a factor of two
+ *   Mat33.scaling2D(2).rightMul(
+ *     // ...then rotates by pi/2 radians = 90 degrees.
+ *     Mat33.zRotation(Math.PI / 2)
+ *   );
+ * console.log(scaleThenRotate);
+ *
+ * // Use scaleThenRotate to scale then rotate a vector.
+ * console.log(scaleThenRotate.transformVec2(Vec2.unitX));
+ * ```
  */
 export class Mat33 {
 	private readonly rows: Vec3[];
@@ -24,6 +67,9 @@ export class Mat33 {
 	 *   c1 & c2 & c3
 	 * \end{bmatrix}
 	 * $$
+	 *
+	 * Static constructor methods are also available.
+	 * See {@link Mat33.scaling2D}, {@link Mat33.zRotation}, {@link Mat33.translation}, and {@link Mat33.fromCSSMatrix}.
 	 */
 	public constructor(
 		public readonly a1: number,
@@ -63,6 +109,7 @@ export class Mat33 {
 		);
 	}
 
+	/** The 3x3 [identity matrix](https://en.wikipedia.org/wiki/Identity_matrix). */
 	public static identity = new Mat33(
 		1, 0, 0,
 		0, 1, 0,
@@ -178,6 +225,29 @@ export class Mat33 {
 		);
 	}
 
+	/**
+	 * [Right-multiplies](https://en.wikipedia.org/wiki/Matrix_multiplication) this by `other`.
+	 *
+	 * See also {@link transformVec3} and {@link transformVec2}.
+	 *
+	 * Example:
+	 * ```ts,runnable,console
+	 * import {Mat33, Vec2} from '@js-draw/math';
+	 * console.log(Mat33.identity.rightMul(Mat33.identity));
+	 *
+	 * // Create a matrix by right multiplying.
+	 * const scaleThenRotate =
+	 *   // The resultant matrix first scales by a factor of two
+	 *   Mat33.scaling2D(2).rightMul(
+	 *     // ...then rotates by pi/4 radians = 45 degrees.
+	 *     Mat33.zRotation(Math.PI / 4)
+	 *   );
+	 * console.log(scaleThenRotate);
+	 *
+	 * // Use scaleThenRotate to scale then rotate a vector.
+	 * console.log(scaleThenRotate.transformVec2(Vec2.unitX));
+	 * ```
+	 */
 	public rightMul(other: Mat33): Mat33 {
 		other = other.transposed();
 
@@ -245,6 +315,15 @@ export class Mat33 {
 		return true;
 	}
 
+	/**
+	 * Creates a human-readable representation of the matrix.
+	 *
+	 * Example:
+	 * ```ts,runnable,console
+	 * import { Mat33 } from '@js-draw/math';
+	 * console.log(Mat33.identity.toString());
+	 * ```
+	 */
 	public toString(): string {
 		let result = '';
 		const maxColumnLens = [ 0, 0, 0 ];
@@ -297,6 +376,18 @@ export class Mat33 {
 	 * result[1] = element at row zero, column 1
 	 * ...
 	 * ```
+	 *
+	 * Example:
+	 * ```ts,runnable,console
+	 * import { Mat33 } from '@js-draw/math';
+	 * console.log(
+	 *   new Mat33(
+	 *     1, 2, 3,
+	 *     4, 5, 6,
+	 *     7, 8, 9,
+	 *   )
+	 * );
+	 * ```
 	 */
 	public toArray(): Mat33Array {
 		return [
@@ -481,7 +572,7 @@ export class Mat33 {
 
 				return argNumber;
 			});
-			return parsed.filter(n => n !== null) as number[];
+			return parsed.filter(n => n !== null);
 		};
 
 

package/src/shapes/BezierJSWrapper.ts

@@ -118,7 +118,7 @@ export abstract class BezierJSWrapper extends Parameterized2DShape {
 			}
 
 			return t;
-		}).filter(entry => entry !== null) as number[];
+		}).filter(entry => entry !== null);
 	}
 
 	public override splitAt(t: number): [BezierJSWrapper] | [BezierJSWrapper, BezierJSWrapper] {

package/src/shapes/LineSegment2.ts

@@ -9,7 +9,18 @@ interface IntersectionResult {
 	t: number;
 }
 
-/** Represents a line segment. A `LineSegment2` is immutable. */
+/**
+ * Represents a line segment. A `LineSegment2` is immutable.
+ *
+ * @example
+ * ```ts,runnable,console
+ * import {LineSegment2, Vec2} from '@js-draw/math';
+ * const l = new LineSegment2(Vec2.of(1, 1), Vec2.of(2, 2));
+ * console.log('length: ', l.length);
+ * console.log('direction: ', l.direction);
+ * console.log('bounding box: ', l.bbox);
+ * ```
+ */
 export class LineSegment2 extends Parameterized2DShape {
 	// invariant: ||direction|| = 1
 
@@ -51,7 +62,7 @@ export class LineSegment2 extends Parameterized2DShape {
 	 * if no such line segment exists.
 	 *
 	 * @example
-	 * ```ts,runnable
+	 * ```ts,runnable,console
 	 * import {LineSegment2, Vec2} from '@js-draw/math';
 	 * console.log(LineSegment2.ofSmallestContainingPoints([Vec2.of(1, 0), Vec2.of(0, 1)]));
 	 * ```

package/dist-test/test_imports/package-lock.json

@@ -1,13 +0,0 @@
-{
-	"name": "js-draw-math-test-imports",
-	"version": "0.0.1",
-	"lockfileVersion": 3,
-	"requires": true,
-	"packages": {
-		"": {
-			"name": "js-draw-math-test-imports",
-			"version": "0.0.1",
-			"license": "MIT"
-		}
-	}
-}