js-draw 0.1.12 → 0.2.0

package/dist/src/components/lib.js

@@ -0,0 +1,4 @@
+import AbstractComponent from './AbstractComponent';
+import Stroke from './Stroke';
+import Text from './Text';
+export { AbstractComponent, Stroke, Text, };

package/dist/src/lib.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The main entrypoint for the NPM package. Everything exported by this file
+ * is available through the `js-draw` package.
+ *
+ * @example
+ * ```
+ * import { Editor, Vec3, Mat33 } from 'js-draw';
+ * ```
+ *
+ * @see
+ * {@link Editor!}
+ *
+ * @packageDocumentation
+ */
+import Editor from './Editor';
+export { EditorEventType } from './types';
+export { default as getLocalizationTable } from './localizations/getLocalizationTable';
+export * from './localization';
+export { default as Color4 } from './Color4';
+export * from './math/lib';
+export * from './components/lib';
+export * from './commands/lib';
+export { default as HTMLToolbar } from './toolbar/HTMLToolbar';
+export { Editor };
+export default Editor;

package/dist/src/lib.js

@@ -0,0 +1,25 @@
+/**
+ * The main entrypoint for the NPM package. Everything exported by this file
+ * is available through the `js-draw` package.
+ *
+ * @example
+ * ```
+ * import { Editor, Vec3, Mat33 } from 'js-draw';
+ * ```
+ *
+ * @see
+ * {@link Editor!}
+ *
+ * @packageDocumentation
+ */
+import Editor from './Editor';
+export { EditorEventType } from './types';
+export { default as getLocalizationTable } from './localizations/getLocalizationTable';
+export * from './localization';
+export { default as Color4 } from './Color4';
+export * from './math/lib';
+export * from './components/lib';
+export * from './commands/lib';
+export { default as HTMLToolbar } from './toolbar/HTMLToolbar';
+export { Editor };
+export default Editor;

package/dist/src/math/Mat33.d.ts

@@ -1,5 +1,10 @@
 import { Point2, Vec2 } from './Vec2';
 import Vec3 from './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).
+ */
 export default class Mat33 {
     readonly a1: number;
     readonly a2: number;
@@ -11,22 +16,63 @@ export default class Mat33 {
     readonly c2: number;
     readonly c3: number;
     private readonly rows;
+    /**
+     * Creates a matrix from inputs in the form,
+     * ```
+     * ⎡ a1 a2 a3 ⎤
+     * ⎢ b1 b2 b3 ⎥
+     * ⎣ c1 c2 c3 ⎦
+     * ```
+     */
     constructor(a1: number, a2: number, a3: number, b1: number, b2: number, b3: number, c1: number, c2: number, c3: number);
+    /**
+     * Creates a matrix from the given rows:
+     * ```
+     *  ⎡ r1.x r1.y r1.z ⎤
+     *  ⎢ r2.x r2.y r2.z ⎥
+     *  ⎣ r3.x r3.y r3.z ⎦
+     * ```
+     */
     static ofRows(r1: Vec3, r2: Vec3, r3: Vec3): Mat33;
     static identity: Mat33;
+    /**
+     * Either returns the inverse of this, or, if this matrix is singular/uninvertable,
+     * returns Mat33.identity.
+     *
+     * This may cache the computed inverse and return the cached version instead of recomputing
+     * it.
+     */
     inverse(): Mat33;
     invertable(): boolean;
     private cachedInverse;
     private computeInverse;
     transposed(): Mat33;
     rightMul(other: Mat33): Mat33;
-    transformVec2(other: Vec3): Vec2;
+    /**
+     * Applies this as an affine transformation to the given vector.
+     * Returns a transformed version of `other`.
+     */
+    transformVec2(other: Vec2): Vec2;
+    /**
+     * Applies this as a linear transformation to the given vector (doesn't translate).
+     * This is the standard way of transforming vectors in ℝ³.
+     */
     transformVec3(other: Vec3): Vec3;
+    /** Returns true iff this = other ± fuzz */
     eq(other: Mat33, fuzz?: number): boolean;
     toString(): string;
+    /**
+     * ```
+     * result[0] = top left element
+     * result[1] = element at row zero, column 1
+     * ...
+     * ```
+     */
     toArray(): number[];
+    /** Constructs a 3x3 translation matrix (for translating `Vec2`s) */
     static translation(amount: Vec2): Mat33;
     static zRotation(radians: number, center?: Point2): Mat33;
     static scaling2D(amount: number | Vec2, center?: Point2): Mat33;
+    /** Converts a CSS-form `matrix(a, b, c, d, e, f)` to a Mat33. */
     static fromCSSMatrix(cssString: string): Mat33;
 }

package/dist/src/math/Mat33.js

@@ -1,12 +1,19 @@
 import { Vec2 } from './Vec2';
 import Vec3 from './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).
+/**
+ * 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).
+ */
 export default class Mat33 {
-    // ⎡ a1 a2 a3 ⎤
-    // ⎢ b1 b2 b3 ⎥
-    // ⎣ c1 c2 c3 ⎦
+    /**
+     * Creates a matrix from inputs in the form,
+     * ```
+     * ⎡ a1 a2 a3 ⎤
+     * ⎢ b1 b2 b3 ⎥
+     * ⎣ c1 c2 c3 ⎦
+     * ```
+     */
     constructor(a1, a2, a3, b1, b2, b3, c1, c2, c3) {
         this.a1 = a1;
         this.a2 = a2;
@@ -24,11 +31,24 @@ export default class Mat33 {
             Vec3.of(c1, c2, c3),
         ];
     }
+    /**
+     * Creates a matrix from the given rows:
+     * ```
+     *  ⎡ r1.x r1.y r1.z ⎤
+     *  ⎢ r2.x r2.y r2.z ⎥
+     *  ⎣ r3.x r3.y r3.z ⎦
+     * ```
+     */
     static ofRows(r1, r2, r3) {
         return new Mat33(r1.x, r1.y, r1.z, r2.x, r2.y, r2.z, r3.x, r3.y, r3.z);
     }
-    // Either returns the inverse of this, or, if this matrix is singular/uninvertable,
-    // returns Mat33.identity.
+    /**
+     * Either returns the inverse of this, or, if this matrix is singular/uninvertable,
+     * returns Mat33.identity.
+     *
+     * This may cache the computed inverse and return the cached version instead of recomputing
+     * it.
+     */
     inverse() {
         var _a;
         return (_a = this.computeInverse()) !== null && _a !== void 0 ? _a : Mat33.identity;
@@ -109,8 +129,10 @@ export default class Mat33 {
         };
         return new Mat33(at(0, 0), at(0, 1), at(0, 2), at(1, 0), at(1, 1), at(1, 2), at(2, 0), at(2, 1), at(2, 2));
     }
-    // Applies this as an affine transformation to the given vector.
-    // Returns a transformed version of [other].
+    /**
+     * Applies this as an affine transformation to the given vector.
+     * Returns a transformed version of `other`.
+     */
     transformVec2(other) {
         // When transforming a Vec2, we want to use the z transformation
         // components of this for translation:
@@ -124,12 +146,14 @@ export default class Mat33 {
         // Drop the z=1 to allow magnitude to work as expected
         return Vec2.of(intermediate.x, intermediate.y);
     }
-    // Applies this as a linear transformation to the given vector (doesn't translate).
-    // This is the standard way of transforming vectors in ℝ³.
+    /**
+     * Applies this as a linear transformation to the given vector (doesn't translate).
+     * This is the standard way of transforming vectors in ℝ³.
+     */
     transformVec3(other) {
         return Vec3.of(this.rows[0].dot(other), this.rows[1].dot(other), this.rows[2].dot(other));
     }
-    // Returns true iff this = other ± fuzz
+    /** Returns true iff this = other ± fuzz */
     eq(other, fuzz = 0) {
         for (let i = 0; i < 3; i++) {
             if (!this.rows[i].eq(other.rows[i], fuzz)) {
@@ -143,11 +167,15 @@ export default class Mat33 {
 ⎡ ${this.a1},\t ${this.a2},\t ${this.a3}\t ⎤
 ⎢ ${this.b1},\t ${this.b2},\t ${this.b3}\t ⎥
 ⎣ ${this.c1},\t ${this.c2},\t ${this.c3}\t ⎦
-		`.trimRight();
-    }
-    // result[0] = top left element
-    // result[1] = element at row zero, column 1
-    // ...
+		`.trimEnd().trimStart();
+    }
+    /**
+     * ```
+     * result[0] = top left element
+     * result[1] = element at row zero, column 1
+     * ...
+     * ```
+     */
     toArray() {
         return [
             this.a1, this.a2, this.a3,
@@ -155,7 +183,7 @@ export default class Mat33 {
             this.c1, this.c2, this.c3,
         ];
     }
-    // Constructs a 3x3 translation matrix (for translating Vec2s)
+    /** Constructs a 3x3 translation matrix (for translating `Vec2`s) */
     static translation(amount) {
         // When transforming Vec2s by a 3x3 matrix, we give the input
         // Vec2s z = 1. As such,
@@ -186,7 +214,7 @@ export default class Mat33 {
         // Translate such that [center] goes to (0, 0)
         return result.rightMul(Mat33.translation(center.times(-1)));
     }
-    // Converts a CSS-form matrix(a, b, c, d, e, f) to a Mat33.
+    /** Converts a CSS-form `matrix(a, b, c, d, e, f)` to a Mat33. */
     static fromCSSMatrix(cssString) {
         if (cssString === '' || cssString === 'none') {
             return Mat33.identity;

package/dist/src/math/Path.js

@@ -215,8 +215,8 @@ export default class Path {
     serialize() {
         return this.toString();
     }
-    // [onlyAbsCommands]: True if we should avoid converting absolute coordinates to relative offsets -- such
-    //                    conversions can lead to smaller output strings, but also take time.
+    // @param onlyAbsCommands - True if we should avoid converting absolute coordinates to relative offsets -- such
+    //   conversions can lead to smaller output strings, but also take time.
     static toString(startPoint, parts, onlyAbsCommands = true) {
         const result = [];
         let prevPoint;
@@ -286,7 +286,7 @@ export default class Path {
     }
     // Create a Path from a SVG path specification.
     // TODO: Support a larger subset of SVG paths.
-    // TODO: Support s,t shorthands.
+    // TODO: Support `s`,`t` commands shorthands.
     static fromString(pathString) {
         // See the MDN reference:
         // https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/d

package/dist/src/math/Rect2.d.ts

@@ -1,7 +1,8 @@
 import LineSegment2 from './LineSegment2';
 import Mat33 from './Mat33';
 import { Point2, Vec2 } from './Vec2';
-interface RectTemplate {
+/** An object that can be converted to a Rect2. */
+export interface RectTemplate {
     x: number;
     y: number;
     w?: number;
@@ -48,4 +49,3 @@ export default class Rect2 {
     static empty: Rect2;
     static unitSquare: Rect2;
 }
-export {};

package/dist/src/math/Vec3.d.ts

@@ -1,30 +1,92 @@
+/**
+ * A vector with three components. Can also be used to represent a two-component vector.
+ *
+ * A `Vec3` is immutable.
+ */
 export default class Vec3 {
     readonly x: number;
     readonly y: number;
     readonly z: number;
     private constructor();
+    /** Returns the x, y components of this. */
     get xy(): {
         x: number;
         y: number;
     };
     static of(x: number, y: number, z: number): Vec3;
+    /** Returns this' `idx`th component. For example, `Vec3.of(1, 2, 3).at(1) → 2`. */
     at(idx: number): number;
+    /** Alias for this.magnitude. */
     length(): number;
     magnitude(): number;
     magnitudeSquared(): number;
+    /**
+     * Return this' angle in the XY plane (treats this as a Vec2).
+     *
+     * This is equivalent to `Math.atan2(vec.y, vec.x)`.
+     */
     angle(): number;
+    /**
+     * Returns a unit vector in the same direction as this.
+     *
+     * If `this` has zero length, the resultant vector has `NaN` components.
+     */
     normalized(): Vec3;
+    /** @returns A copy of `this` multiplied by a scalar. */
     times(c: number): Vec3;
     plus(v: Vec3): Vec3;
     minus(v: Vec3): Vec3;
     dot(other: Vec3): number;
     cross(other: Vec3): Vec3;
+    /**
+     * Returns a vector orthogonal to this. If this is a Vec2, returns `this` rotated
+     * 90 degrees counter-clockwise.
+     */
     orthog(): Vec3;
+    /** Returns this plus a vector of length `distance` in `direction`. */
     extend(distance: number, direction: Vec3): Vec3;
+    /** Returns a vector `fractionTo` of the way to target from this. */
     lerp(target: Vec3, fractionTo: number): Vec3;
+    /**
+     * `zip` Maps a component of this and a corresponding component of
+     * `other` to a component of the output vector.
+     *
+     * @example
+     * ```
+     * const a = Vec3.of(1, 2, 3);
+     * const b = Vec3.of(0.5, 2.1, 2.9);
+     *
+     * const zipped = a.zip(b, (aComponent, bComponent) => {
+     *   return Math.min(aComponent, bComponent);
+     * });
+     *
+     * console.log(zipped.toString()); // → Vec(0.5, 2, 2.9)
+     * ```
+     */
     zip(other: Vec3, zip: (componentInThis: number, componentInOther: number) => number): Vec3;
+    /**
+     * Returns a vector with each component acted on by `fn`.
+     *
+     * @example
+     * ```
+     * console.log(Vec3.of(1, 2, 3).map(val => val + 1)); // → Vec(2, 3, 4)
+     * ```
+     */
     map(fn: (component: number, index: number) => number): Vec3;
     asArray(): number[];
+    /**
+     * [fuzz] The maximum difference between two components for this and [other]
+     * to be considered equal.
+     *
+     * @example
+     * ```
+     * Vec3.of(1, 2, 3).eq(Vec3.of(4, 5, 6), 100);  // → true
+     * Vec3.of(1, 2, 3).eq(Vec3.of(4, 5, 6), 0.1);  // → false
+     * Vec3.of(1, 2, 3).eq(Vec3.of(4, 5, 6), 3);    // → true
+     * Vec3.of(1, 2, 3).eq(Vec3.of(4, 5, 6), 3.01); // → true
+     * Vec3.of(1, 2, 3).eq(Vec3.of(4, 5, 6), 2.99); // → false
+     * ```
+     */
     eq(other: Vec3, fuzz: number): boolean;
     toString(): string;
     static unitX: Vec3;

package/dist/src/math/Vec3.js

@@ -1,11 +1,15 @@
-// A vector with three components. Can also be used to represent a two-component vector
+/**
+ * A vector with three components. Can also be used to represent a two-component vector.
+ *
+ * A `Vec3` is immutable.
+ */
 export default class Vec3 {
     constructor(x, y, z) {
         this.x = x;
         this.y = y;
         this.z = z;
     }
-    // Returns the x, y components of this
+    /** Returns the x, y components of this. */
     get xy() {
         // Useful for APIs that behave differently if .z is present.
         return {
@@ -16,7 +20,7 @@ export default class Vec3 {
     static of(x, y, z) {
         return new Vec3(x, y, z);
     }
-    // Returns this' [idx]th component
+    /** Returns this' `idx`th component. For example, `Vec3.of(1, 2, 3).at(1) → 2`. */
     at(idx) {
         if (idx === 0)
             return this.x;
@@ -26,7 +30,7 @@ export default class Vec3 {
             return this.z;
         throw new Error(`${idx} out of bounds!`);
     }
-    // Alias for this.magnitude
+    /** Alias for this.magnitude. */
     length() {
         return this.magnitude();
     }
@@ -36,14 +40,24 @@ export default class Vec3 {
     magnitudeSquared() {
         return this.dot(this);
     }
-    // Return this' angle in the XY plane (treats this as a Vec2)
+    /**
+     * Return this' angle in the XY plane (treats this as a Vec2).
+     *
+     * This is equivalent to `Math.atan2(vec.y, vec.x)`.
+     */
     angle() {
         return Math.atan2(this.y, this.x);
     }
+    /**
+     * Returns a unit vector in the same direction as this.
+     *
+     * If `this` has zero length, the resultant vector has `NaN` components.
+     */
     normalized() {
         const norm = this.magnitude();
         return Vec3.of(this.x / norm, this.y / norm, this.z / norm);
     }
+    /** @returns A copy of `this` multiplied by a scalar. */
     times(c) {
         return Vec3.of(this.x * c, this.y * c, this.z * c);
     }
@@ -62,8 +76,10 @@ export default class Vec3 {
         // | x2 y2 z2|
         return Vec3.of(this.y * other.z - other.y * this.z, other.x * this.z - this.x * other.z, this.x * other.y - other.x * this.y);
     }
-    // Returns a vector orthogonal to this. If this is a Vec2, returns [this] rotated
-    // 90 degrees counter-clockwise.
+    /**
+     * Returns a vector orthogonal to this. If this is a Vec2, returns `this` rotated
+     * 90 degrees counter-clockwise.
+     */
     orthog() {
         // If parallel to the z-axis
         if (this.dot(Vec3.unitX) === 0 && this.dot(Vec3.unitY) === 0) {
@@ -71,28 +87,60 @@ export default class Vec3 {
         }
         return this.cross(Vec3.unitZ.times(-1)).normalized();
     }
-    // Returns this plus a vector of length [distance] in [direction]
+    /** Returns this plus a vector of length `distance` in `direction`. */
     extend(distance, direction) {
         return this.plus(direction.normalized().times(distance));
     }
-    // Returns a vector [fractionTo] of the way to target from this.
+    /** Returns a vector `fractionTo` of the way to target from this. */
     lerp(target, fractionTo) {
         return this.times(1 - fractionTo).plus(target.times(fractionTo));
     }
-    // [zip] Maps a component of this and a corresponding component of
-    // [other] to a component of the output vector.
+    /**
+     * `zip` Maps a component of this and a corresponding component of
+     * `other` to a component of the output vector.
+     *
+     * @example
+     * ```
+     * const a = Vec3.of(1, 2, 3);
+     * const b = Vec3.of(0.5, 2.1, 2.9);
+     *
+     * const zipped = a.zip(b, (aComponent, bComponent) => {
+     *   return Math.min(aComponent, bComponent);
+     * });
+     *
+     * console.log(zipped.toString()); // → Vec(0.5, 2, 2.9)
+     * ```
+     */
     zip(other, zip) {
         return Vec3.of(zip(other.x, this.x), zip(other.y, this.y), zip(other.z, this.z));
     }
-    // Returns a vector with each component acted on by [fn]
+    /**
+     * Returns a vector with each component acted on by `fn`.
+     *
+     * @example
+     * ```
+     * console.log(Vec3.of(1, 2, 3).map(val => val + 1)); // → Vec(2, 3, 4)
+     * ```
+     */
     map(fn) {
         return Vec3.of(fn(this.x, 0), fn(this.y, 1), fn(this.z, 2));
     }
     asArray() {
         return [this.x, this.y, this.z];
     }
-    // [fuzz] The maximum difference between two components for this and [other]
-    // to be considered equal.
+    /**
+     * [fuzz] The maximum difference between two components for this and [other]
+     * to be considered equal.
+     *
+     * @example
+     * ```
+     * Vec3.of(1, 2, 3).eq(Vec3.of(4, 5, 6), 100);  // → true
+     * Vec3.of(1, 2, 3).eq(Vec3.of(4, 5, 6), 0.1);  // → false
+     * Vec3.of(1, 2, 3).eq(Vec3.of(4, 5, 6), 3);    // → true
+     * Vec3.of(1, 2, 3).eq(Vec3.of(4, 5, 6), 3.01); // → true
+     * Vec3.of(1, 2, 3).eq(Vec3.of(4, 5, 6), 2.99); // → false
+     * ```
+     */
     eq(other, fuzz) {
         for (let i = 0; i < 3; i++) {
             if (Math.abs(other.at(i) - this.at(i)) > fuzz) {

package/dist/src/math/lib.d.ts

@@ -0,0 +1,7 @@
+import LineSegment2 from './LineSegment2';
+import Mat33 from './Mat33';
+import Path from './Path';
+import Rect2 from './Rect2';
+import { Vec2 } from './Vec2';
+import Vec3 from './Vec3';
+export { LineSegment2, Mat33, Path, Rect2, Vec3, Vec2, };

package/dist/src/math/lib.js

@@ -0,0 +1,7 @@
+import LineSegment2 from './LineSegment2';
+import Mat33 from './Mat33';
+import Path from './Path';
+import Rect2 from './Rect2';
+import { Vec2 } from './Vec2';
+import Vec3 from './Vec3';
+export { LineSegment2, Mat33, Path, Rect2, Vec3, Vec2, };

package/dist/src/math/rounding.js

@@ -1,3 +1,4 @@
+// @packageDocumentation @internal
 // Clean up stringified numbers
 const cleanUpNumber = (text) => {
     // Regular expression substitions can be somewhat expensive. Only do them

package/dist/src/rendering/Display.d.ts

@@ -1,3 +1,17 @@
+/**
+ * Handles `HTMLCanvasElement`s (or other drawing surfaces if being used) used to display the editor's contents.
+ *
+ * @example
+ * ```
+ * const editor = new Editor(document.body);
+ * const w = editor.display.width;
+ * const h = editor.display.height;
+ * const center = Vec2.of(w / 2, h / 2);
+ * const colorAtCenter = editor.display.getColorAt(center);
+ * ```
+ *
+ * @packageDocumentation
+ */
 import AbstractRenderer from './renderers/AbstractRenderer';
 import { Editor } from '../Editor';
 import { Point2 } from '../math/Vec2';
@@ -17,17 +31,47 @@ export default class Display {
     private cache;
     private resizeSurfacesCallback?;
     private flattenCallback?;
+    /** @internal */
     constructor(editor: Editor, mode: RenderingMode, parent: HTMLElement | null);
+    /**
+     * @returns the visible width of the display (e.g. how much
+     * space the display's element takes up in the x direction
+     * in the DOM).
+     */
     get width(): number;
     get height(): number;
+    /** @internal */
     getCache(): RenderingCache;
+    /**
+     * @returns the color at the given point on the dry ink renderer, or `null` if `screenPos`
+     * 	is not on the display.
+     */
     getColorAt: (_screenPos: Point2) => Color4 | null;
     private initializeCanvasRendering;
     private initializeTextRendering;
+    /**
+     * Rerenders the text-based display.
+     * The text-based display is intended for screen readers and can be navigated to by pressing `tab`.
+     */
     rerenderAsText(): void;
+    /**
+     * Clears the drawing surfaces and otherwise prepares for a rerender.
+     *
+     * @returns the dry ink renderer.
+     */
     startRerender(): AbstractRenderer;
+    /**
+     * If `draftMode`, the dry ink renderer is configured to render
+     * low-quality output.
+     */
     setDraftMode(draftMode: boolean): void;
+    /** @internal */
     getDryInkRenderer(): AbstractRenderer;
+    /**
+     * @returns The renderer used for showing action previews (e.g. an unfinished stroke).
+     * The `wetInkRenderer`'s surface is stacked above the `dryInkRenderer`'s.
+     */
     getWetInkRenderer(): AbstractRenderer;
+    /** Re-renders the contents of the wetInkRenderer onto the dryInkRenderer. */
     flatten(): void;
 }