js-draw 0.12.0 → 0.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "js-draw",
-	"version": "0.12.0",
+	"version": "0.13.0",
 	"description": "Draw pictures using a pen, touchscreen, or mouse! JS-draw is a drawing library for JavaScript and TypeScript. ",
 	"main": "./dist/src/lib.d.ts",
 	"types": "./dist/src/lib.js",
@@ -101,7 +101,7 @@
 		"ts-jest": "^29.0.3",
 		"ts-loader": "^9.4.2",
 		"ts-node": "^10.9.1",
-		"typedoc": "^0.23.23",
+		"typedoc": "^0.23.24",
 		"typescript": "^4.9.4",
 		"webpack": "^5.75.0"
 	},

package/src/Color4.test.ts

@@ -16,4 +16,15 @@ describe('Color4', () => {
 		expect(Color4.fromString('rgba ( 255, 0,\t 0, 0.5)')).objEq(Color4.ofRGBA(1, 0, 0, 0.5));
 		expect(Color4.fromString('rgba( 0, 0, 128, 0)')).objEq(Color4.ofRGBA(0, 0, 128/255, 0));
 	});
+
+	it('should mix blue and red to get dark purple', () => {
+		expect(Color4.ofRGB(1, 0, 0).mix(Color4.ofRGB(0, 0, 1), 0.5)).objEq(Color4.ofRGB(0.5, 0, 0.5));
+		expect(Color4.ofRGB(1, 0, 0).mix(Color4.ofRGB(0, 0, 1), 0.1)).objEq(Color4.ofRGB(0.9, 0, 0.1));
+	});
+
+	it('should mix red and green to get yellow', () => {
+		expect(Color4.ofRGB(1, 0, 0).mix(Color4.ofRGB(0, 1, 0), 0.3)).objEq(
+			Color4.ofRGB(0.7, 0.3, 0)
+		);
+	});
 });

package/src/Color4.ts

@@ -129,6 +129,28 @@ export default class Color4 {
 		return this.toHexString() === other.toHexString();
 	}
 
+	/**
+	 * If `fractionTo` is not in the range [0, 1], it will be clamped to the nearest number
+	 * in that range. For example, `a.mix(b, -1)` is equivalent to `a.mix(b, 0)`.
+	 * 
+	 * @returns a color `fractionTo` of the way from this color to `other`.
+	 * 
+	 * @example
+	 * ```ts
+	 * Color4.ofRGB(1, 0, 0).mix(Color4.ofRGB(0, 1, 0), 0.1) // -> Color4(0.9, 0.1, 0)
+	 * ```
+	 */
+	public mix(other: Color4, fractionTo: number): Color4 {
+		fractionTo = Math.min(Math.max(fractionTo, 0), 1);
+		const fractionOfThis = 1 - fractionTo;
+		return new Color4(
+			this.r * fractionOfThis + other.r * fractionTo,
+			this.g * fractionOfThis + other.g * fractionTo,
+			this.b * fractionOfThis + other.b * fractionTo,
+			this.a * fractionOfThis + other.a * fractionTo,
+		);
+	}
+
 	private hexString: string|null = null;
 
 	/**

package/src/Editor.ts

@@ -1,22 +1,3 @@
-/**
- * The main entrypoint for the full editor.
- *
- * @example
- * To create an editor with a toolbar,
- * ```
- * const editor = new Editor(document.body);
- *
- * const toolbar = editor.addToolbar();
- * toolbar.addActionButton('Save', () => {
- *   const saveData = editor.toSVG().outerHTML;
- *   // Do something with saveData...
- * });
- * ```
- *
- * @packageDocumentation
- */
-
-
 import EditorImage from './EditorImage';
 import ToolController from './tools/ToolController';
 import { InputEvtType, PointerEvt, EditorNotifier, EditorEventType, ImageLoader } from './types';
@@ -70,12 +51,27 @@ export interface EditorSettings {
 	iconProvider: IconProvider,
 }
 
-// { @inheritDoc Editor! }
+/**
+ * The main entrypoint for the full editor.
+ *
+ * @example
+ * To create an editor with a toolbar,
+ * ```
+ * const editor = new Editor(document.body);
+ *
+ * const toolbar = editor.addToolbar();
+ * toolbar.addActionButton('Save', () => {
+ *   const saveData = editor.toSVG().outerHTML;
+ *   // Do something with saveData...
+ * });
+ * ```
+ */
 export class Editor {
 	// Wrapper around the viewport and toolbar
 	private container: HTMLElement;
 	private renderingRegion: HTMLElement;
 
+	/** Manages drawing surfaces/{@link lib!AbstractRenderer}s. */
 	public display: Display;
 
 	/**
@@ -116,11 +112,23 @@ export class Editor {
 	/** Viewport for the exported/imported image. */
 	private importExportViewport: Viewport;
 
+	/**
+	 * Allows transforming the view and querying information about
+	 * what is currently visible.
+	 */
+	public readonly viewport: Viewport;
+
 	/** @internal */
 	public readonly localization: EditorLocalization;
 
+	/** {@link lib!EditorSettings.iconProvider} */
 	public readonly icons: IconProvider;
-	public readonly viewport: Viewport;
+
+	/**
+	 * Controls the list of tools. See
+	 * [the custom tool example](https://github.com/personalizedrefrigerator/js-draw/tree/main/docs/example-custom-tools)
+	 * for more.
+	 */
 	public readonly toolController: ToolController;
 
 	/**
@@ -765,12 +773,18 @@ export class Editor {
 		this.nextRerenderListeners = [];
 	}
 
+	/**
+	 * @see {@link Display.getWetInkRenderer} {@link Display.flatten}
+	 */
 	public drawWetInk(...path: RenderablePathSpec[]) {
 		for (const part of path) {
 			this.display.getWetInkRenderer().drawPath(part);
 		}
 	}
 
+	/**
+	 * @see {@link Display.getWetInkRenderer}
+	 */
 	public clearWetInk() {
 		this.display.getWetInkRenderer().clear();
 	}
@@ -895,7 +909,7 @@ export class Editor {
 	public toDataURL(format: 'image/png'|'image/jpeg'|'image/webp' = 'image/png'): string {
 		const canvas = document.createElement('canvas');
 
-		const resolution = this.importExportViewport.getResolution();
+		const resolution = this.importExportViewport.getScreenRectSize();
 
 		canvas.width = resolution.x;
 		canvas.height = resolution.y;

package/src/EditorImage.ts

@@ -75,6 +75,11 @@ export default class EditorImage {
 		delete this.componentsById[elem.getId()];
 	}
 
+	/**
+	 * @returns the AbstractComponent with `id`, if it exists.
+	 * 
+	 * @see {@link AbstractComponent.getId}
+	 */
 	public lookupElement(id: string): AbstractComponent|null {
 		return this.componentsById[id] ?? null;
 	}
@@ -84,6 +89,13 @@ export default class EditorImage {
 		return this.root.addLeaf(elem);
 	}
 
+	/**
+	 * Returns a command that adds the given element to the `EditorImage`.
+	 * If `applyByFlattening` is true, the content of the wet ink renderer is
+	 * rendered onto the main rendering canvas instead of doing a full re-render.
+	 * 
+	 * @see {@link Display.flatten}
+	 */
 	public static addElement(elem: AbstractComponent, applyByFlattening: boolean = false): SerializableCommand {
 		return new EditorImage.AddElementCommand(elem, applyByFlattening);
 	}

package/src/Pointer.ts

@@ -36,6 +36,25 @@ export default class Pointer {
 	) {
 	}
 
+	// Snaps this pointer to the nearest grid point (rounds the coordinates of this
+	// pointer based on the current zoom). Returns a new Pointer and does not modify
+	// this.
+	public snappedToGrid(viewport: Viewport): Pointer {
+		const snappedCanvasPos = viewport.snapToGrid(this.canvasPos);
+		const snappedScreenPos = viewport.canvasToScreen(snappedCanvasPos);
+
+		return new Pointer(
+			snappedScreenPos,
+			snappedCanvasPos,
+			this.pressure,
+			this.isPrimary,
+			this.down,
+			this.device,
+			this.id,
+			this.timeStamp,
+		);
+	}
+
 	// Creates a Pointer from a DOM event. If `relativeTo` is given, (0, 0) in screen coordinates is
 	// considered the top left of `relativeTo`.
 	public static ofEvent(evt: PointerEvent, isDown: boolean, viewport: Viewport, relativeTo?: HTMLElement): Pointer {

package/src/SVGLoader.ts

@@ -31,6 +31,7 @@ export type SVGLoaderUnknownStyleAttribute = { key: string, value: string, prior
 
 const supportedStrokeFillStyleAttrs = [ 'stroke', 'fill', 'stroke-width' ];
 
+// Handles loading images from SVG.
 export default class SVGLoader implements ImageLoader {
 	private onAddComponent: ComponentAddedListener|null = null;
 	private onProgress: OnProgressListener|null = null;
@@ -422,7 +423,11 @@ export default class SVGLoader implements ImageLoader {
 		this.onFinish?.();
 	}
 
-	// @param sanitize - if `true`, don't store unknown attributes.
+	/**
+	 * @see {@link Editor.loadFrom}
+	 * @param text - Textual representation of the SVG (e.g. `<svg viewbox='...'>...</svg>`).
+	 * @param sanitize - if `true`, don't store unknown attributes.
+	 */
 	public static fromString(text: string, sanitize: boolean = false): SVGLoader {
 		const sandbox = document.createElement('iframe');
 		sandbox.src = 'about:blank';

package/src/Viewport.ts

@@ -92,26 +92,30 @@ export class Viewport {
 		this.screenRect = this.screenRect.resizedTo(screenSize);
 	}
 
-	// Get the screen's visible region transformed into canvas space.
+	/** Get the screen's visible region transformed into canvas space. */
 	public get visibleRect(): Rect2 {
 		return this.screenRect.transformedBoundingBox(this.inverseTransform);
 	}
 
-	// the given point, but in canvas coordinates
+	/** @returns the given point, but in canvas coordinates */
 	public screenToCanvas(screenPoint: Point2): Point2 {
 		return this.inverseTransform.transformVec2(screenPoint);
 	}
 
+	/** @returns the given point transformed into screen coordinates. */
 	public canvasToScreen(canvasPoint: Point2): Point2 {
 		return this.transform.transformVec2(canvasPoint);
 	}
 
+	/** @returns a command that transforms the canvas by `transform`. */
 	public static transformBy(transform: Mat33): ViewportTransform {
 		return new Viewport.ViewportTransform(transform);
 	}
 
-	// Updates the transformation directly. Using `transformBy` is preferred.
-	// [newTransform] should map from canvas coordinates to screen coordinates.
+	/**
+	 * Updates the transformation directly. Using `transformBy` is preferred.
+	 * @param newTransform - should map from canvas coordinates to screen coordinates.
+	 */
 	public resetTransform(newTransform: Mat33 = Mat33.identity) {
 		const oldTransform = this.transform;
 		this.transform = newTransform;
@@ -131,29 +135,64 @@ export class Viewport {
 		return this.transform;
 	}
 
-	public getResolution(): Vec2 {
+	/** @returns the size of the visible region in pixels. */
+	public getScreenRectSize(): Vec2 {
 		return this.screenRect.size;
 	}
 
-	// Returns the amount a vector on the canvas is scaled to become a vector on the screen.
+	/** Alias for `getScreenRectSize`. @deprecated */
+	public getResolution() {
+		return this.getScreenRectSize();
+	}
+
+	/** @returns the amount a vector on the canvas is scaled to become a vector on the screen. */
 	public getScaleFactor(): number {
 		// Use transformVec3 to avoid translating the vector
 		return this.transform.transformVec3(Vec3.unitX).magnitude();
 	}
 
-	// Returns the size of one screen pixel in canvas units.
+	/**
+	 * @returns `getScaleFactor()` rounded to the nearest power of 10.
+	 * For example, if `getScaleFactor()` returns 101, `getScaleFactorToNearestPowerOfTen()`
+	 * should return `100` because `100` is the nearest power of 10 to 101.
+	 */
+	public getScaleFactorToNearestPowerOfTen() {
+		const scaleFactor = this.getScaleFactor();
+		return Math.pow(10, Math.round(Math.log10(scaleFactor)));
+	}
+
+	public snapToGrid(canvasPos: Point2) {
+		const snapCoordinate = (coordinate: number) => {
+			const scaleFactor = this.getScaleFactorToNearestPowerOfTen();
+			const roundFactor = scaleFactor / 100;
+			const snapped = Math.round(coordinate * roundFactor) / roundFactor;
+
+			return snapped;
+		};
+
+		const snappedCanvasPos = Vec2.of(
+			snapCoordinate(canvasPos.x), snapCoordinate(canvasPos.y)
+		);
+		return snappedCanvasPos;
+	}
+
+	/** Returns the size of one screen pixel in canvas units. */
 	public getSizeOfPixelOnCanvas(): number {
 		return 1/this.getScaleFactor();
 	}
 
-	// Returns the angle of the canvas in radians.
-	// This is the angle by which the canvas is rotated relative to the screen.
+	/**
+	 * @returns the angle of the canvas in radians.
+	 * This is the angle by which the canvas is rotated relative to the screen.
+	 */
 	public getRotationAngle(): number {
 		return this.transform.transformVec3(Vec3.unitX).angle();
 	}
 
-	// Rounds the given `point` to a multiple of 10 such that it is within `tolerance` of
-	// its original location. This is useful for preparing data for base-10 conversion.
+	/**
+	 * Rounds the given `point` to a multiple of 10 such that it is within `tolerance` of
+	 * its original location. This is useful for preparing data for base-10 conversion.
+	 */
 	public static roundPoint<T extends Point2|number>(
 		point: T, tolerance: number,
 	): PointDataType<T>;

package/src/commands/invertCommand.ts

@@ -3,7 +3,7 @@ import { EditorLocalization } from '../localization';
 import Command from './Command';
 import SerializableCommand from './SerializableCommand';
 
-// Returns a command taht does the opposite of the given command --- `result.apply()` calls
+// Returns a command that does the opposite of the given command --- `result.apply()` calls
 // `command.unapply()` and `result.unapply()` calls `command.apply()`.
 const invertCommand = <T extends Command> (command: T): T extends SerializableCommand ? SerializableCommand : Command => {
 	if (command instanceof SerializableCommand) {

package/src/components/AbstractComponent.ts

@@ -13,9 +13,20 @@ export type LoadSaveDataTable = Record<string, Array<LoadSaveData>>;
 export type DeserializeCallback = (data: string)=>AbstractComponent;
 type ComponentId = string;
 
+/**
+ * A base class for everything that can be added to an {@link EditorImage}.
+ */
 export default abstract class AbstractComponent {
+	// The timestamp (milliseconds) at which the component was
+	// last changed (i.e. created/translated).
+	// @deprecated
 	protected lastChangedTime: number;
+
+	// The bounding box of this component.
+	// {@link getBBox}, by default, returns `contentBBox`.
+	// This must be set by components.
 	protected abstract contentBBox: Rect2;
+
 	private zIndex: number;
 	private id: string;
 
@@ -38,7 +49,7 @@ export default abstract class AbstractComponent {
 	}
 
 	// Returns a unique ID for this element.
-	// @see { @link EditorImage!default.lookupElement }
+	// @see { @link lib!EditorImage.lookupElement }
 	public getId() {
 		return this.id;
 	}
@@ -55,14 +66,22 @@ export default abstract class AbstractComponent {
 		this.deserializationCallbacks[componentKind] = deserialize ?? null;
 	}
 
-	// Get and manage data attached by a loader.
+	// Stores data attached by a loader.
 	private loadSaveData: LoadSaveDataTable = {};
+
+	/**
+	 * Attach data that can be used while exporting the component (e.g. to SVG).
+	 * 
+	 * This is intended for use by a {@link ImageLoader}.
+	 */
 	public attachLoadSaveData(key: string, data: LoadSaveData) {
 		if (!this.loadSaveData[key]) {
 			this.loadSaveData[key] = [];
 		}
 		this.loadSaveData[key].push(data);
 	}
+
+	/** See {@link attachLoadSaveData} */
 	public getLoadSaveData(): LoadSaveDataTable {
 		return this.loadSaveData;
 	}
@@ -71,13 +90,20 @@ export default abstract class AbstractComponent {
 		return this.zIndex;
 	}
 
+	/** @returns the bounding box of  */
 	public getBBox(): Rect2 {
 		return this.contentBBox;
 	}
 
 	public abstract render(canvas: AbstractRenderer, visibleRect?: Rect2): void;
+
+	/** @return true if `lineSegment` intersects this component. */
 	public abstract intersects(lineSegment: LineSegment2): boolean;
 
+	/**
+	 * @returns true if this component intersects `rect` -- it is entirely contained
+	 *  within the rectangle or one of the rectangle's edges intersects this component.
+	 */
 	public intersectsRect(rect: Rect2): boolean {
 		// If this component intersects rect,
 		// it is either contained entirely within rect or intersects one of rect's edges.
@@ -200,6 +226,7 @@ export default abstract class AbstractComponent {
 			}
 
 			this.component.applyTransformation(newTransfm);
+			this.component.lastChangedTime = (new Date()).getTime();
 
 			// Add the element back to the document.
 			if (hadParent) {
@@ -250,6 +277,10 @@ export default abstract class AbstractComponent {
 		}
 	};
 
+	/**
+	 * @return a description that could be read by a screen reader
+	 *     (e.g. when adding/erasing the component)
+	 */
 	public abstract description(localizationTable: ImageComponentLocalization): string;
 
 	// Component-specific implementation of {@link clone}.

package/src/lib.ts

@@ -8,25 +8,28 @@
  * ```
  * 
  * @see
- * {@link Editor!}
+ * {@link Editor}
  * 
  * @packageDocumentation
  */
 
-import Editor from './Editor';
+import Editor, { EditorSettings } from './Editor';
 export { default as EditorImage } from './EditorImage';
 export * from './types';
 export { default as getLocalizationTable } from './localizations/getLocalizationTable';
 export * from './localization';
 
 export { default as Color4 } from './Color4';
+export { default as SVGLoader } from './SVGLoader';
+export { default as Viewport } from './Viewport';
 export * from './math/lib';
 export * from './components/lib';
 export * from './commands/lib';
 export * from './tools/lib';
 export * from './toolbar/lib';
+export * from './rendering/lib';
 export { default as Pointer, PointerDevice } from './Pointer';
 export { default as HTMLToolbar } from './toolbar/HTMLToolbar';
 
-export { Editor };
+export { Editor, EditorSettings };
 export default Editor;

package/src/math/Mat33.ts

@@ -338,7 +338,7 @@ export default class Mat33 {
 		return result.rightMul(Mat33.translation(center.times(-1)));
 	}
 
-	/** @see {@link !fromCSSMatrix} */
+	/** @see {@link fromCSSMatrix} */
 	public toCSSMatrix(): string {
 		return `matrix(${this.a1},${this.b1},${this.a2},${this.b2},${this.a3},${this.b3})`;
 	}

package/src/rendering/Display.ts

@@ -1,18 +1,3 @@
-/**
- * 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';
@@ -29,6 +14,18 @@ export enum RenderingMode {
 	// SVGRenderer is not supported by the main display
 }
 
+/**
+ * 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);
+ * ```
+ */
 export default class Display {
 	private dryInkRenderer: AbstractRenderer;
 	private wetInkRenderer: AbstractRenderer;

package/src/rendering/RenderingStyle.ts

@@ -13,7 +13,7 @@ export default RenderingStyle;
 export const stylesEqual = (a: RenderingStyle, b: RenderingStyle): boolean => {
 	const result = a === b || (a.fill.eq(b.fill)
 		&& (a.stroke == undefined) === (b.stroke == undefined)
-        && (a.stroke?.color?.eq(b.stroke?.color) ?? true)
+		&& (a.stroke?.color?.eq(b.stroke?.color) ?? true)
 		&& a.stroke?.width === b.stroke?.width);
     
 	// Map undefined/null -> false

package/src/rendering/lib.ts

@@ -0,0 +1,4 @@
+
+export { default as AbstractRenderer } from './renderers/AbstractRenderer';
+export { default as DummyRenderer } from './renderers/DummyRenderer';
+export { default as Display } from './Display';

package/src/rendering/renderers/DummyRenderer.ts

@@ -1,5 +1,3 @@
-// Renderer that outputs nothing. Useful for automated tests.
-
 import { TextStyle } from '../../components/TextComponent';
 import Mat33 from '../../math/Mat33';
 import Rect2 from '../../math/Rect2';
@@ -9,6 +7,7 @@ import Viewport from '../../Viewport';
 import RenderingStyle from '../RenderingStyle';
 import AbstractRenderer, { RenderableImage } from './AbstractRenderer';
 
+// Renderer that outputs almost nothing. Useful for automated tests.
 export default class DummyRenderer extends AbstractRenderer {
 	// Variables that track the state of what's been rendered
 	public clearedCount: number = 0;
@@ -28,7 +27,7 @@ export default class DummyRenderer extends AbstractRenderer {
 
 	public displaySize(): Vec2 {
 		// Do we have a stored viewport size?
-		const viewportSize = this.getViewport().getResolution();
+		const viewportSize = this.getViewport().getScreenRectSize();
 
 		// Don't use a 0x0 viewport — DummyRenderer is often used
 		// for tests that run without a display, so pretend we have a

package/src/rendering/renderers/SVGRenderer.ts

@@ -38,6 +38,10 @@ export default class SVGRenderer extends AbstractRenderer {
 					stroke-linecap: round;
 					stroke-linejoin: round;
 				}
+
+				text {
+					white-space: pre;
+				}
 			`.replace(/\s+/g, '');
 			styleSheet.setAttribute('id', renderedStylesheetId);
 			this.elem.appendChild(styleSheet);

package/src/rendering/renderers/TextOnlyRenderer.ts

@@ -9,7 +9,6 @@ import RenderingStyle from '../RenderingStyle';
 import AbstractRenderer, { RenderableImage } from './AbstractRenderer';
 
 // Outputs a description of what was rendered.
-
 export default class TextOnlyRenderer extends AbstractRenderer {
 	private descriptionBuilder: string[] = [];
 	private pathCount: number = 0;

package/src/toolbar/HTMLToolbar.ts

@@ -169,7 +169,7 @@ export default class HTMLToolbar {
 	 * toolbar.addSpacer({ grow: 1 });
 	 * toolbar.addDefaults();
 	 * toolbar.addSpacer({ grow: 1 });
- 	 * 
+	 *
 	 * toolbar.addActionButton({
 	 * 	label: 'Save',
 	 * 	icon: editor.icons.makeSaveIcon(),