js-draw 0.1.12 → 0.2.0

package/src/components/Stroke.ts

@@ -111,19 +111,23 @@ export default class Stroke extends AbstractComponent {
 		return new Stroke(this.parts);
 	}
 
-	protected serializeToString(): string | null {
-		return JSON.stringify(this.parts.map(part => {
+	protected serializeToJSON() {
+		return this.parts.map(part => {
 			return {
 				style: styleToJSON(part.style),
 				path: part.path.serialize(),
 			};
-		}));
+		});
 	}
 
-	public static deserializeFromString(data: string): Stroke {
-		const json = JSON.parse(data);
+	/** @internal */
+	public static deserializeFromJSON(json: any): Stroke {
+		if (typeof json === 'string') {
+			json = JSON.parse(json);
+		}
+
 		if (typeof json !== 'object' || typeof json.length !== 'number') {
-			throw new Error(`${data} is missing required field, parts, or parts is of the wrong type.`);
+			throw new Error(`${json} is missing required field, parts, or parts is of the wrong type.`);
 		}
 
 		const pathSpec: RenderablePathSpec[] = json.map((part: any) => {
@@ -134,4 +138,4 @@ export default class Stroke extends AbstractComponent {
 	}
 }
 
-AbstractComponent.registerComponent('stroke', Stroke.deserializeFromString);
+AbstractComponent.registerComponent('stroke', Stroke.deserializeFromJSON);

package/src/components/Text.ts

@@ -26,6 +26,7 @@ export default class Text extends AbstractComponent {
 		private readonly style: TextStyle,
 
 		// If not given, an HtmlCanvasElement is used to determine text boundaries.
+		// @internal
 		private readonly getTextDimens: GetTextDimensCallback = Text.getTextDimens,
 	) {
 		super(componentTypeId);
@@ -152,7 +153,7 @@ export default class Text extends AbstractComponent {
 		return localizationTable.text(this.getText());
 	}
 
-	protected serializeToString(): string {
+	protected serializeToJSON(): Record<string, any> {
 		const serializableStyle = {
 			...this.style,
 			renderingStyle: styleToJSON(this.style.renderingStyle),
@@ -165,21 +166,19 @@ export default class Text extends AbstractComponent {
 				};
 			} else {
 				return {
-					json: text.serializeToString(),
+					json: text.serializeToJSON(),
 				};
 			}
 		});
 
-		return JSON.stringify({
+		return {
 			textObjects,
 			transform: this.transform.toArray(),
 			style: serializableStyle,
-		});
+		};
 	}
 
-	public static deserializeFromString(data: string, getTextDimens: GetTextDimensCallback = Text.getTextDimens): Text {
-		const json = JSON.parse(data);
-
+	public static deserializeFromString(json: any, getTextDimens: GetTextDimensCallback = Text.getTextDimens): Text {
 		const style: TextStyle = {
 			renderingStyle: styleFromJSON(json.style.renderingStyle),
 			size: json.style.size,

package/src/components/UnknownSVGObject.ts

@@ -1,3 +1,9 @@
+//
+// Stores objects loaded from an SVG that aren't recognised by the editor.
+// @internal
+// @packageDocumentation
+//
+
 import LineSegment2 from '../math/LineSegment2';
 import Mat33 from '../math/Mat33';
 import Rect2 from '../math/Rect2';
@@ -39,7 +45,7 @@ export default class UnknownSVGObject extends AbstractComponent {
 		return localization.svgObject;
 	}
 
-	protected serializeToString(): string | null {
+	protected serializeToJSON(): string | null {
 		return JSON.stringify({
 			html: this.svgObject.outerHTML,
 		});

package/src/components/lib.ts

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

package/src/lib.ts

@@ -0,0 +1,28 @@
+/**
+ * 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/src/math/Mat33.ts

@@ -1,15 +1,22 @@
 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).
+/**
+ * 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 {
 	private readonly rows: Vec3[];
 
-	// ⎡ 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 ⎦
+	 * ```
+	 */
 	public constructor(
 		public readonly a1: number,
 		public readonly a2: number,
@@ -30,6 +37,14 @@ export default class Mat33 {
 		];
 	}
 
+	/**
+	 * 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 ⎦
+	 * ```
+	 */
 	public static ofRows(r1: Vec3, r2: Vec3, r3: Vec3): Mat33 {
 		return new Mat33(
 			r1.x, r1.y, r1.z,
@@ -44,8 +59,13 @@ export default class Mat33 {
 		0, 0, 1
 	);
 
-	// 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.
+	 */
 	public inverse(): Mat33 {
 		return this.computeInverse() ?? Mat33.identity;
 	}
@@ -162,9 +182,11 @@ export default class Mat33 {
 		);
 	}
 
-	// Applies this as an affine transformation to the given vector.
-	// Returns a transformed version of [other].
-	public transformVec2(other: Vec3): Vec2 {
+	/**
+	 * Applies this as an affine transformation to the given vector.
+	 * Returns a transformed version of `other`.
+	 */
+	public transformVec2(other: Vec2): Vec2 {
 		// When transforming a Vec2, we want to use the z transformation
 		// components of this for translation:
 		//  ⎡ . . tX ⎤
@@ -179,8 +201,10 @@ export default class Mat33 {
 		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 ℝ³.
+	 */
 	public transformVec3(other: Vec3): Vec3 {
 		return Vec3.of(
 			this.rows[0].dot(other),
@@ -189,7 +213,7 @@ export default class Mat33 {
 		);
 	}
 
-	// Returns true iff this = other ± fuzz
+	/** Returns true iff this = other ± fuzz */
 	public eq(other: Mat33, fuzz: number = 0): boolean {
 		for (let i = 0; i < 3; i++) {
 			if (!this.rows[i].eq(other.rows[i], fuzz)) {
@@ -205,12 +229,16 @@ 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();
+		`.trimEnd().trimStart();
 	}
 
-	// result[0] = top left element
-	// result[1] = element at row zero, column 1
-	// ...
+	/**
+	 * ```
+	 * result[0] = top left element
+	 * result[1] = element at row zero, column 1
+	 * ...
+	 * ```
+	 */
 	public toArray(): number[] {
 		return [
 			this.a1, this.a2, this.a3,
@@ -219,7 +247,7 @@ export default class Mat33 {
 		];
 	}
 
-	// Constructs a 3x3 translation matrix (for translating Vec2s)
+	/** Constructs a 3x3 translation matrix (for translating `Vec2`s) */
 	public static translation(amount: Vec2): Mat33 {
 		// When transforming Vec2s by a 3x3 matrix, we give the input
 		// Vec2s z = 1. As such,
@@ -269,7 +297,7 @@ export default class Mat33 {
 		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. */
 	public static fromCSSMatrix(cssString: string): Mat33 {
 		if (cssString === '' || cssString === 'none') {
 			return Mat33.identity;

package/src/math/Path.ts

@@ -299,8 +299,8 @@ export default class Path {
 		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.
 	public static toString(startPoint: Point2, parts: PathCommand[], onlyAbsCommands: boolean = true): string {
 		const result: string[] = [];
 
@@ -377,7 +377,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.
 	public static fromString(pathString: string): Path {
 		// See the MDN reference:
 		// https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/d

package/src/math/Rect2.ts

@@ -2,8 +2,8 @@ import LineSegment2 from './LineSegment2';
 import Mat33 from './Mat33';
 import { Point2, Vec2 } from './Vec2';
 
-// An object that can be converted to a Rect2.
-interface RectTemplate {
+/** An object that can be converted to a Rect2. */
+export interface RectTemplate {
 	x: number;
 	y: number;
 	w?: number;

package/src/math/Vec3.ts

@@ -1,6 +1,10 @@
 
 
-// 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 {
 	private constructor(
 		public readonly x: number,
@@ -9,7 +13,7 @@ export default class Vec3 {
 	) {
 	}
 
-	// Returns the x, y components of this
+	/** Returns the x, y components of this. */
 	public get xy(): { x: number; y: number } {
 		// Useful for APIs that behave differently if .z is present.
 		return {
@@ -22,7 +26,7 @@ export default class Vec3 {
 		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`. */
 	public at(idx: number): number {
 		if (idx === 0) return this.x;
 		if (idx === 1) return this.y;
@@ -31,7 +35,7 @@ export default class Vec3 {
 		throw new Error(`${idx} out of bounds!`);
 	}
 
-	// Alias for this.magnitude
+	/** Alias for this.magnitude. */
 	public length(): number {
 		return this.magnitude();
 	}
@@ -44,16 +48,26 @@ export default class Vec3 {
 		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)`.
+	 */
 	public angle(): number {
 		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.
+	 */
 	public normalized(): Vec3 {
 		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. */
 	public times(c: number): Vec3 {
 		return Vec3.of(this.x * c, this.y * c, this.z * c);
 	}
@@ -81,8 +95,10 @@ export default class Vec3 {
 		);
 	}
 
-	// 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.
+	 */
 	public orthog(): Vec3 {
 		// If parallel to the z-axis
 		if (this.dot(Vec3.unitX) === 0 && this.dot(Vec3.unitY) === 0) {
@@ -92,18 +108,32 @@ 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`. */
 	public extend(distance: number, direction: Vec3): Vec3 {
 		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. */
 	public lerp(target: Vec3, fractionTo: number): Vec3 {
 		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)
+	 * ```
+	 */
 	public zip(
 		other: Vec3, zip: (componentInThis: number, componentInOther: number)=> number
 	): Vec3 {
@@ -114,7 +144,14 @@ export default class Vec3 {
 		);
 	}
 
-	// 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)
+	 * ```
+	 */
 	public map(fn: (component: number, index: number)=> number): Vec3 {
 		return Vec3.of(
 			fn(this.x, 0), fn(this.y, 1), fn(this.z, 2)
@@ -125,8 +162,19 @@ export default class Vec3 {
 		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
+	 * ```
+	 */
 	public eq(other: Vec3, fuzz: number): boolean {
 		for (let i = 0; i < 3; i++) {
 			if (Math.abs(other.at(i) - this.at(i)) > fuzz) {

package/src/math/lib.ts

@@ -0,0 +1,15 @@
+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/src/math/rounding.ts

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

package/src/rendering/Display.ts

@@ -1,3 +1,18 @@
+/**
+ * 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 CanvasRenderer from './renderers/CanvasRenderer';
 import { Editor } from '../Editor';
@@ -23,6 +38,7 @@ export default class Display {
 	private resizeSurfacesCallback?: ()=> void;
 	private flattenCallback?: ()=> void;
 
+	/** @internal */
 	public constructor(
 		private editor: Editor, mode: RenderingMode, private parent: HTMLElement|null
 	) {
@@ -60,7 +76,7 @@ export default class Display {
 				return this.dryInkRenderer.canRenderFromWithoutDataLoss(renderer);
 			},
 			blockResolution: cacheBlockResolution,
-			cacheSize: 500 * 500 * 4 * 220,
+			cacheSize: 500 * 500 * 4 * 150,
 			maxScale: 1.5,
 			minComponentsPerCache: 45,
 			minComponentsToUseCache: 105,
@@ -75,9 +91,11 @@ export default class Display {
 		});
 	}
 
-	// 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).
+	/**
+	 * @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).
+	 */
 	public get width(): number {
 		return this.dryInkRenderer.displaySize().x;
 	}
@@ -86,10 +104,15 @@ export default class Display {
 		return this.dryInkRenderer.displaySize().y;
 	}
 
+	/** @internal */
 	public getCache() {
 		return this.cache;
 	}
 
+	/**
+	 * @returns the color at the given point on the dry ink renderer, or `null` if `screenPos`
+	 * 	is not on the display.
+	 */
 	public getColorAt = (_screenPos: Point2): Color4|null => {
 		return null;
 	};
@@ -170,6 +193,10 @@ export default class Display {
 		this.editor.createHTMLOverlay(textRendererOutputContainer);
 	}
 
+	/**
+	 * Rerenders the text-based display.
+	 * The text-based display is intended for screen readers and can be navigated to by pressing `tab`.
+	 */
 	public rerenderAsText() {
 		this.textRenderer.clear();
 		this.editor.image.render(this.textRenderer, this.editor.viewport);
@@ -179,7 +206,11 @@ export default class Display {
 		}
 	}
 
-	// Clears the drawing surfaces and otherwise prepares for a rerender.
+	/**
+	 * Clears the drawing surfaces and otherwise prepares for a rerender.
+	 * 
+	 * @returns the dry ink renderer.
+	 */
 	public startRerender(): AbstractRenderer {
 		this.resizeSurfacesCallback?.();
 		this.wetInkRenderer.clear();
@@ -188,19 +219,28 @@ export default class Display {
 		return this.dryInkRenderer;
 	}
 
+	/**
+	 * If `draftMode`, the dry ink renderer is configured to render
+	 * low-quality output.
+	 */
 	public setDraftMode(draftMode: boolean) {
 		this.dryInkRenderer.setDraftMode(draftMode);
 	}
 
+	/** @internal */
 	public getDryInkRenderer(): AbstractRenderer {
 		return this.dryInkRenderer;
 	}
 
+	/**
+	 * @returns The renderer used for showing action previews (e.g. an unfinished stroke).
+	 * The `wetInkRenderer`'s surface is stacked above the `dryInkRenderer`'s.
+	 */
 	public getWetInkRenderer(): AbstractRenderer {
 		return this.wetInkRenderer;
 	}
 
-	// Re-renders the contents of the wetInkRenderer onto the dryInkRenderer
+	/** Re-renders the contents of the wetInkRenderer onto the dryInkRenderer. */
 	public flatten() {
 		this.flattenCallback?.();
 	}

package/src/rendering/caching/CacheRecord.test.ts

@@ -11,7 +11,7 @@ describe('CacheRecord', () => {
 		const { cache } = createCache(undefined, {
 			blockResolution,
 		});
-		const state = cache.getSharedState();
+		const state = cache['sharedState'];
 
 		const record = new CacheRecord(() => {}, state);
 

package/src/rendering/caching/CacheRecord.ts

@@ -11,6 +11,9 @@ export default class CacheRecord {
 	private lastUsedCycle: number;
 	private allocd: boolean = false;
 
+	// For debugging
+	public allocCount: number = 0;
+
 	public constructor(
 		private onBeforeDeallocCallback: BeforeDeallocCallback|null,
 		private cacheState: CacheState,
@@ -46,6 +49,7 @@ export default class CacheRecord {
 		this.allocd = true;
 		this.onBeforeDeallocCallback = newDeallocCallback;
 		this.lastUsedCycle = this.cacheState.currentRenderingCycle;
+		this.allocCount ++;
 	}
 
 	public getLastUsedCycle(): number {