js-draw 0.1.12 → 0.2.1

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/localizations/de.ts

@@ -0,0 +1,98 @@
+import { defaultEditorLocalization, EditorLocalization } from '../localization';
+
+// German localization
+const localization: EditorLocalization = {
+	...defaultEditorLocalization,
+
+	pen: 'Stift',
+	eraser: 'Radierer',
+	select: 'Auswahl',
+	handTool: 'Verschieben',
+
+	zoom: 'Vergrößerung',
+	resetView: 'Ansicht zurücksetzen',
+
+	thicknessLabel: 'Dicke: ',
+	colorLabel: 'Farbe: ',
+	fontLabel: 'Schriftart: ',
+
+	resizeImageToSelection: 'Bildgröße an Auswahl anpassen',
+	deleteSelection: 'Auswahl löschen',
+	duplicateSelection: 'Auswahl duplizieren',
+
+	undo: 'Rückgängig',
+	redo: 'Wiederholen',
+
+	pickColorFromScreen: 'Farbe von Bildschirm auswählen',
+	clickToPickColorAnnouncement: 'Klicke auf den Bildschirm, um eine Farbe auszuwählen',
+	selectionToolKeyboardShortcuts: 'Auswahl-Werkzeug: Verwende die Pfeiltasten, um ausgewählte Elemente zu verschieben und ‚i‘ und ‚o‘, um ihre Größe zu ändern.',
+	touchPanning: 'Ansicht mit Touchscreen verschieben',
+	anyDevicePanning: 'Ansicht mit jedem Eingabegerät verschieben',
+
+	selectObjectType: 'Objekt-Typ: ',
+	freehandPen: 'Freihand',
+	arrowPen: 'Pfeil',
+	linePen: 'Linie',
+	outlinedRectanglePen: 'Umrissenes Rechteck',
+	filledRectanglePen: 'Ausgefülltes Rechteck',
+
+	dropdownShown: t=>`Dropdown-Menü für ${t} angezeigt`,
+	dropdownHidden: t=>`Dropdown-Menü für ${t} versteckt`,
+	zoomLevel: t=>`Vergößerung: ${t}%`,
+	colorChangedAnnouncement: t=>`Farbe zu ${t} geändert`,
+	penTool: t=>`Stift ${t}`,
+
+	selectionTool: 'Auswahl',
+	eraserTool: 'Radiergummi',
+	touchPanTool: 'Ansicht mit Touchscreen verschieben',
+	twoFingerPanZoomTool: 'Ansicht verschieben und vergrößern',
+	undoRedoTool: 'Rückgängig/Wiederholen',
+	rightClickDragPanTool: 'Rechtsklick-Ziehen',
+	pipetteTool: 'Farbe von Bildschirm auswählen',
+	keyboardPanZoom: 'Tastaturkürzel zum Verschieben/Vergrößern der Ansicht',
+	textTool: 'Text',
+	enterTextToInsert: 'Einzufügender Text',
+
+	toolEnabledAnnouncement: t=>`${t} aktiviert`,
+	toolDisabledAnnouncement: t=>`${t} deaktiviert`,
+	updatedViewport: 'Transformierte Ansicht',
+	transformedElements: t=>`${t} Element${1===t?'':'e'} transformiert`,
+	resizeOutputCommand: t=>`Bildgröße auf ${t.w}x${t.h} geändert`,
+	addElementAction: t=>`${t} hinzugefügt`,
+	eraseAction: (t,e)=>`${e} ${t} gelöscht`,
+	duplicateAction: (t,e)=>`${e} ${t} dupliziert`,
+	inverseOf: t=>`Umkehrung von ${t}`,
+
+	elements: 'Elemente',
+	erasedNoElements: 'Nichts entfernt',
+	duplicatedNoElements: 'Nichts dupliziert',
+	rotatedBy: t=>`${Math.abs(t)} Grad ${t<0?'im Uhrzeigersinn':'gegen den Uhrzeigersinn'} gedreht`,
+
+	movedLeft: 'Nacht links bewegt',
+	movedUp: 'Nacht oben bewegt',
+	movedDown: 'Nacht unten bewegt',
+	movedRight: 'Nacht rechts bewegt',
+	zoomedOut: 'Ansicht verkleinert',
+	zoomedIn: 'Ansicht vergrößert',
+
+	selectedElements: t=>`${t} Element${ 1===t ? '' : 'e' } ausgewählt`,
+	stroke: 'Strich',
+	svgObject: 'SVG-Objekt',
+
+	text: t=>`Text-Objekt: ${t}`,
+	pathNodeCount: t=>`Es gibt ${t} sichtbare Pfad-Objekte.`,
+	textNodeCount: t=>`Es gibt ${t} sichtbare Text-Knotenpunkte.`,
+	textNode: t=>`Text: ${t}`,
+
+	rerenderAsText: 'Als Text darstellen',
+	accessibilityInputInstructions: 'Drücke ‚t‘, um den Inhalt des Ansichtsfensters als Text zu lesen. Verwende die Pfeiltasten, um die Ansicht zu verschieben, und klicke und ziehe, um Striche zu zeichnen. Drücke ‚w‘ zum Vergrößern und ‚s‘ zum Verkleinern der Ansicht.',
+
+	loading: t=>`Laden ${t}%...`,
+	doneLoading: 'Laden fertig',
+
+	imageEditor: 'Bild-Editor',
+	undoAnnouncement: t=>`Rückgangig gemacht ${t}`,
+	redoAnnouncement: t=>`Wiederholt ${t}`,
+};
+
+export default localization;

package/src/localizations/getLocalizationTable.ts

@@ -1,9 +1,11 @@
 
 import { defaultEditorLocalization, EditorLocalization } from '../localization';
+import de from './de';
 import en from './en';
 import es from './es';
 
 const allLocales: Record<string, EditorLocalization> = {
+	de,
 	en,
 	es,
 };

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