js-draw 0.1.12 → 0.2.0

package/package.json

@@ -1,103 +1,120 @@
 {
-  "name": "js-draw",
-  "version": "0.1.12",
-  "description": "Draw pictures using a pen, touchscreen, or mouse! JS-draw is a drawing library for JavaScript and TypeScript. ",
-  "main": "dist/src/Editor.js",
-  "types": "dist/src/Editor.d.ts",
-  "exports": {
-    ".": {
-      "types": "./dist/src/Editor.d.ts",
-      "default": "./dist/src/Editor.js"
-    },
-    "./localizations/getLocalizationTable": {
-      "types": "./dist/src/localizations/getLocalizationTable.d.ts",
-      "default": "./dist/src/localizations/getLocalizationTable.js"
-    },
-    "./getLocalizationTable": {
-      "types": "./dist/src/localizations/getLocalizationTable.d.ts",
-      "default": "./dist/src/localizations/getLocalizationTable.js"
-    },
-    "./styles": {
-      "default": "./src/styles.js"
-    },
-    "./Editor": {
-      "types": "./dist/src/Editor.d.ts",
-      "default": "./dist/src/Editor.js"
-    },
-    "./localization": {
-      "types": "./dist/src/localization.d.ts",
-      "default": "./dist/src/localization.js"
-    },
-    "./toolbar/HTMLToolbar": {
-      "types": "./dist/src/toolbar/HTMLToolbar.d.ts",
-      "default": "./dist/src/toolbar/HTMLToolbar.js"
-    },
-    "./Editor.css": {
-      "default": "./src/Editor.css"
-    },
-    "./toolbar/toolbar.css": {
-      "default": "./src/toolbar/toolbar.css"
-    },
-    "./bundle": {
-      "default": "./dist/bundle.js"
-    }
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/personalizedrefrigerator/js-draw.git"
-  },
-  "author": "Henry Heino",
-  "license": "MIT",
-  "private": false,
-  "scripts": {
-    "test": "jest",
-    "build": "rm -rf ./dist; mkdir dist && yarn tsc && ts-node ./build_tools/bundle.ts",
-    "lint": "eslint .",
-    "linter-precommit": "eslint --fix --ext .js --ext .ts",
-    "lint-staged": "lint-staged",
-    "_postinstall": "husky install",
-    "prepack": "yarn build && pinst --disable",
-    "postpack": "pinst --enable"
-  },
-  "dependencies": {
-    "@melloware/coloris": "^0.16.0",
-    "bezier-js": "^6.1.0"
-  },
-  "devDependencies": {
-    "@types/bezier-js": "^4.1.0",
-    "@types/jest": "^28.1.7",
-    "@types/jsdom": "^20.0.0",
-    "@types/node": "^18.7.15",
-    "@typescript-eslint/eslint-plugin": "^5.36.2",
-    "@typescript-eslint/parser": "^5.36.2",
-    "css-loader": "^6.7.1",
-    "eslint": "^8.23.0",
-    "husky": "^8.0.1",
-    "jest": "^28.1.3",
-    "jest-environment-jsdom": "^29.0.2",
-    "jsdom": "^20.0.0",
-    "lint-staged": "^13.0.3",
-    "pinst": "^3.0.0",
-    "style-loader": "^3.3.1",
-    "terser-webpack-plugin": "^5.3.5",
-    "ts-jest": "^28.0.8",
-    "ts-loader": "^9.3.1",
-    "ts-node": "^10.9.1",
-    "typescript": "^4.8.2",
-    "webpack": "^5.74.0"
-  },
-  "bugs": {
-    "url": "https://github.com/personalizedrefrigerator/js-draw/issues"
-  },
-  "homepage": "https://github.com/personalizedrefrigerator/js-draw#readme",
-  "directories": {
-    "doc": "docs"
-  },
-  "keywords": [
-    "ink",
-    "drawing",
-    "pen",
-    "freehand",
-    "svg"
-  ]
+	"name": "js-draw",
+	"version": "0.2.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",
+	"exports": {
+		".": {
+			"types": "./dist/src/lib.d.ts",
+			"default": "./dist/src/lib.js"
+		},
+		"./getLocalizationTable": {
+			"types": "./dist/src/localizations/getLocalizationTable.d.ts",
+			"default": "./dist/src/localizations/getLocalizationTable.js"
+		},
+		"./styles": {
+			"default": "./src/styles.js"
+		},
+		"./Editor": {
+			"types": "./dist/src/Editor.d.ts",
+			"default": "./dist/src/Editor.js"
+		},
+		"./types": {
+			"types": "./dist/src/types.d.ts",
+			"default": "./dist/src/types.js"
+		},
+		"./localization": {
+			"types": "./dist/src/localization.d.ts",
+			"default": "./dist/src/localization.js"
+		},
+		"./toolbar/HTMLToolbar": {
+			"types": "./dist/src/toolbar/HTMLToolbar.d.ts",
+			"default": "./dist/src/toolbar/HTMLToolbar.js"
+		},
+		"./Editor.css": {
+			"default": "./src/Editor.css"
+		},
+		"./math": {
+			"types": "./dist/src/math/lib.d.ts",
+			"default": "./dist/src/math/lib.js"
+		},
+		"./Color4": {
+			"types": "./dist/src/Color4.d.ts",
+			"default": "./dist/src/Color4.js"
+		},
+		"./components": {
+			"types": "./dist/src/components/lib.d.ts",
+			"default": "./dist/src/components/lib.js"
+		},
+		"./commands": {
+			"types": "./dist/src/commands/lib.d.ts",
+			"default": "./dist/src/commands/lib.js"
+		},
+		"./bundle": {
+			"types": "./dist/src/bundle/bundled.d.ts",
+			"default": "./dist/bundle.js"
+		}
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/personalizedrefrigerator/js-draw.git"
+	},
+	"author": "Henry Heino",
+	"license": "MIT",
+	"private": false,
+	"scripts": {
+		"test": "jest",
+		"build": "rm -rf ./dist; mkdir dist && yarn tsc && ts-node ./build_tools/bundle.ts",
+		"doc": "typedoc --options typedoc.json",
+		"watch-docs": "typedoc --watch --options typedoc.json",
+		"lint": "eslint .",
+		"linter-precommit": "eslint --fix --ext .js --ext .ts",
+		"lint-staged": "lint-staged",
+		"prepare": "husky install && yarn build",
+		"prepack": "yarn build && pinst --disable",
+		"postpack": "pinst --enable"
+	},
+	"dependencies": {
+		"@melloware/coloris": "^0.16.0",
+		"bezier-js": "^6.1.0"
+	},
+	"devDependencies": {
+		"@types/bezier-js": "^4.1.0",
+		"@types/jest": "^28.1.7",
+		"@types/jsdom": "^20.0.0",
+		"@types/node": "^18.7.15",
+		"@typescript-eslint/eslint-plugin": "^5.36.2",
+		"@typescript-eslint/parser": "^5.36.2",
+		"css-loader": "^6.7.1",
+		"eslint": "^8.23.0",
+		"husky": "^8.0.1",
+		"jest": "^28.1.3",
+		"jest-environment-jsdom": "^29.0.2",
+		"jsdom": "^20.0.0",
+		"lint-staged": "^13.0.3",
+		"pinst": "^3.0.0",
+		"style-loader": "^3.3.1",
+		"terser-webpack-plugin": "^5.3.5",
+		"ts-jest": "^28.0.8",
+		"ts-loader": "^9.3.1",
+		"ts-node": "^10.9.1",
+		"typedoc": "^0.23.14",
+		"typescript": "^4.8.2",
+		"webpack": "^5.74.0"
+	},
+	"bugs": {
+		"url": "https://github.com/personalizedrefrigerator/js-draw/issues"
+	},
+	"homepage": "https://github.com/personalizedrefrigerator/js-draw#readme",
+	"directories": {
+		"doc": "docs"
+	},
+	"keywords": [
+		"ink",
+		"drawing",
+		"pen",
+		"freehand",
+		"svg"
+	]
 }

package/src/Color4.ts

@@ -1,14 +1,25 @@
 
 export default class Color4 {
 	private constructor(
+		/** Red component. Should be in the range [0, 1]. */
 		public readonly r: number,
+
+		/** Green component. `g` ∈ [0, 1] */
 		public readonly g: number,
+
+		/** Blue component. `b` ∈ [0, 1] */
 		public readonly b: number,
+
+		/** Alpha/transparent component. `a` ∈ [0, 1] */
 		public readonly a: number
 	) {
 	}
 
-	// Each component should be in the range [0, 1]
+	/**
+	 * Create a color from red, green, blue components. The color is fully opaque (`a = 1.0`).
+	 * 
+	 * Each component should be in the range [0, 1].
+	 */
 	public static ofRGB(red: number, green: number, blue: number): Color4 {
 		return Color4.ofRGBA(red, green, blue, 1.0);
 	}
@@ -58,7 +69,7 @@ export default class Color4 {
 		return Color4.ofRGBA(components[0], components[1], components[2], components[3]);
 	}
 
-	// Like fromHex, but can handle additional colors if an HTML5Canvas is available.
+	/** Like fromHex, but can handle additional colors if an `HTMLCanvasElement` is available. */
 	public static fromString(text: string): Color4 {
 		if (text.startsWith('#')) {
 			return Color4.fromHex(text);
@@ -82,6 +93,7 @@ export default class Color4 {
 		}
 	}
 
+	/** @returns true if `this` and `other` are approximately equal. */
 	public eq(other: Color4|null|undefined): boolean {
 		if (other == null) {
 			return false;
@@ -91,6 +103,15 @@ export default class Color4 {
 	}
 
 	private hexString: string|null = null;
+
+	/**
+	 * @returns a hexadecimal color string representation of `this`, in the form `#rrggbbaa`.
+	 * 
+	 * @example
+	 * ```
+	 * Color4.red.toHexString(); // -> #ff0000ff
+	 * ```
+	 */
 	public toHexString(): string {
 		if (this.hexString) {
 			return this.hexString;

package/src/Editor.ts

@@ -1,3 +1,21 @@
+/**
+ * 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';
@@ -21,36 +39,80 @@ import { EditorLocalization } from './localization';
 import getLocalizationTable from './localizations/getLocalizationTable';
 
 export interface EditorSettings {
-	// Defaults to RenderingMode.CanvasRenderer
+	/** Defaults to `RenderingMode.CanvasRenderer` */
 	renderingMode: RenderingMode,
 
-	// Uses a default English localization if a translation is not given.
+	/** Uses a default English localization if a translation is not given. */
 	localization: Partial<EditorLocalization>,
 
-	// True if touchpad/mousewheel scrolling should scroll the editor instead of the document.
-	// This does not include pinch-zoom events.
-	// Defaults to true.
+	/**
+	 * `true` if touchpad/mousewheel scrolling should scroll the editor instead of the document.
+	 * This does not include pinch-zoom events.
+	 * Defaults to true.
+	 */
 	wheelEventsEnabled: boolean|'only-if-focused';
 
+	/** Minimum zoom fraction (e.g. 0.5 → 50% zoom). */
 	minZoom: number,
 	maxZoom: number,
 }
 
+// { @inheritDoc Editor! }
 export class Editor {
 	// Wrapper around the viewport and toolbar
 	private container: HTMLElement;
 	private renderingRegion: HTMLElement;
 
-	public history: UndoRedoHistory;
 	public display: Display;
+
+	/**
+	 * Handles undo/redo.
+	 * 
+	 * @example
+	 * ```
+	 * const editor = new Editor(document.body);
+	 * 
+	 * // Do something undoable.
+	 * // ...
+	 * 
+	 * // Undo the last action
+	 * editor.history.undo();
+	 * ```
+	 */
+	public history: UndoRedoHistory;
+
+	/**
+	 * Data structure for adding/removing/querying objects in the image.
+	 * 
+	 * @example
+	 * ```
+	 * const editor = new Editor(document.body);
+	 * 
+	 * // Create a path.
+	 * const stroke = new Stroke([
+	 *   Path.fromString('M0,0 L30,30 z').toRenderable({ fill: Color4.black }),
+	 * ]);
+	 * const addElementCommand = editor.image.addElement(stroke);
+	 * 
+	 * // Add the stroke to the editor
+	 * editor.dispatch(addElementCommand);
+	 * ```
+	 */
 	public image: EditorImage;
 
-	// Viewport for the exported/imported image
+	/** Viewport for the exported/imported image. */
 	private importExportViewport: Viewport;
+
+	/** @internal */
 	public localization: EditorLocalization;
 
 	public viewport: Viewport;
 	public toolController: ToolController;
+
+	/**
+	 * Global event dispatcher/subscriber.
+	 * @see {@link types.EditorEventType}
+	 */
 	public notifier: EditorNotifier;
 
 	private loadingWarning: HTMLElement;
@@ -59,6 +121,29 @@ export class Editor {
 
 	private settings: EditorSettings;
 
+	/**
+	 * @example
+	 * ```
+	 * const container = document.body;
+	 * 
+	 * // Create an editor
+	 * const editor = new Editor(container, {
+	 *   // 2e-10 and 1e12 are the default values for minimum/maximum zoom.
+	 *   minZoom: 2e-10,
+	 *   maxZoom: 1e12,
+	 * });
+	 * 
+	 * // Add the default toolbar
+	 * const toolbar = editor.addToolbar();
+	 * toolbar.addActionButton({
+	 *   label: 'Save'
+	 *   icon: createSaveIcon(),
+	 * }, () => {
+	 *   const saveData = editor.toSVG().outerHTML;
+	 *   // Do something with saveData
+	 * });
+	 * ```
+	 */
 	public constructor(
 		parent: HTMLElement,
 		settings: Partial<EditorSettings> = {},
@@ -145,14 +230,19 @@ export class Editor {
 		});
 	}
 
-	// Returns a reference to this' container.
-	// Example usage:
-	//   editor.getRootElement().style.height = '500px';
+	/**
+	 * @returns a reference to the editor's container.
+	 * 
+	 * @example
+	 * ```
+	 *   editor.getRootElement().style.height = '500px';
+	 * ```
+	 */
 	public getRootElement(): HTMLElement {
 		return this.container;
 	}
 
-	// [fractionLoaded] should be a number from 0 to 1, where 1 represents completely loaded.
+	/** @param fractionLoaded - should be a number from 0 to 1, where 1 represents completely loaded. */
 	public showLoadingWarning(fractionLoaded: number) {
 		const loadingPercent = Math.round(fractionLoaded * 100);
 		this.loadingWarning.innerText = this.localization.loading(loadingPercent);
@@ -166,6 +256,9 @@ export class Editor {
 	}
 
 	private previousAccessibilityAnnouncement: string = '';
+
+	// Announce `message` for screen readers. If `message` is the same as the previous
+	// message, it is re-announced.
 	public announceForAccessibility(message: string) {
 		// Force re-announcing an announcement if announced again.
 		if (message === this.previousAccessibilityAnnouncement) {
@@ -175,6 +268,10 @@ export class Editor {
 		this.previousAccessibilityAnnouncement = message;
 	}
 
+	/**
+	 * Creates a toolbar. If `defaultLayout` is true, default buttons are used.
+	 * @returns a reference to the toolbar.
+	 */
 	public addToolbar(defaultLayout: boolean = true): HTMLToolbar {
 		const toolbar = new HTMLToolbar(this, this.container, this.localization);
 
@@ -340,8 +437,7 @@ export class Editor {
 		});
 	}
 
-	// Adds event listners for keypresses to [elem] and forwards those events to the
-	// editor.
+	/** Adds event listners for keypresses to `elem` and forwards those events to the editor. */
 	public handleKeyEventsFrom(elem: HTMLElement) {
 		elem.addEventListener('keydown', evt => {
 			if (evt.key === 't' || evt.key === 'T') {
@@ -369,7 +465,7 @@ export class Editor {
 		});
 	}
 
-	// Adds to history by default
+	/** `apply` a command. `command` will be announced for accessibility. */
 	public dispatch(command: Command, addToHistory: boolean = true) {
 		if (addToHistory) {
 			// .push applies [command] to this
@@ -381,7 +477,21 @@ export class Editor {
 		this.announceForAccessibility(command.description(this, this.localization));
 	}
 
-	// Dispatches a command without announcing it. By default, does not add to history.
+	/**
+	 * Dispatches a command without announcing it. By default, does not add to history.
+	 * Use this to show finalized commands that don't need to have `announceForAccessibility`
+	 * called.
+	 * 
+	 * Prefer `command.apply(editor)` for incomplete commands. `dispatchNoAnnounce` may allow
+	 * clients to listen for the application of commands (e.g. `SerializableCommand`s so they can
+	 * be sent across the network), while `apply` does not.
+	 * 
+	 * @example
+	 * ```
+	 * const addToHistory = false;
+	 * editor.dispatchNoAnnounce(editor.viewport.zoomTo(someRectangle), addToHistory);
+	 * ```
+	 */
 	public dispatchNoAnnounce(command: Command, addToHistory: boolean = false) {
 		if (addToHistory) {
 			this.history.push(command);
@@ -390,11 +500,13 @@ export class Editor {
 		}
 	}
 
-	// Apply a large transformation in chunks.
-	// If [apply] is false, the commands are unapplied.
-	// Triggers a re-render after each [updateChunkSize]-sized group of commands
-	// has been applied.
-	private async asyncApplyOrUnapplyCommands(
+	/**
+	 * Apply a large transformation in chunks.
+	 * If `apply` is `false`, the commands are unapplied.
+	 * Triggers a re-render after each `updateChunkSize`-sized group of commands
+	 * has been applied.
+	 */
+	public async asyncApplyOrUnapplyCommands(
 		commands: Command[], apply: boolean, updateChunkSize: number
 	) {
 		this.display.setDraftMode(true);
@@ -423,10 +535,12 @@ export class Editor {
 		this.hideLoadingWarning();
 	}
 
+	// @see {@link #asyncApplyOrUnapplyCommands }
 	public asyncApplyCommands(commands: Command[], chunkSize: number) {
 		return this.asyncApplyOrUnapplyCommands(commands, true, chunkSize);
 	}
 
+	// @see {@link #asyncApplyOrUnapplyCommands }
 	public asyncUnapplyCommands(commands: Command[], chunkSize: number) {
 		return this.asyncApplyOrUnapplyCommands(commands, false, chunkSize);
 	}
@@ -440,6 +554,8 @@ export class Editor {
 	};
 
 	private rerenderQueued: boolean = false;
+	// Schedule a re-render for some time in the near future. Does not schedule an additional
+	// re-render if a re-render is already queued.
 	public queueRerender() {
 		if (!this.rerenderQueued) {
 			this.rerenderQueued = true;
@@ -486,11 +602,13 @@ export class Editor {
 		this.display.getWetInkRenderer().clear();
 	}
 
-	// Focuses the region used for text input
+	// Focuses the region used for text input/key commands.
 	public focus() {
 		this.renderingRegion.focus();
 	}
 
+	// Creates an element that will be positioned on top of the dry/wet ink
+	// renderers.
 	public createHTMLOverlay(overlay: HTMLElement) {
 		overlay.classList.add('overlay');
 		this.container.appendChild(overlay);
@@ -509,7 +627,7 @@ export class Editor {
 	}
 
 	// Dispatch a pen event to the currently selected tool.
-	// Intented for unit tests.
+	// Intended primarially for unit tests.
 	public sendPenEvent(
 		eventType: InputEvtType.PointerDownEvt|InputEvtType.PointerMoveEvt|InputEvtType.PointerUpEvt,
 		point: Point2,
@@ -589,7 +707,7 @@ export class Editor {
 		return this.importExportViewport.visibleRect;
 	}
 
-	// Resize the output SVG
+	// Resize the output SVG to match `imageRect`.
 	public setImportExportRect(imageRect: Rect2): Command {
 		const origSize = this.importExportViewport.visibleRect.size;
 		const origTransform = this.importExportViewport.canvasToScreenTransform;
@@ -615,8 +733,12 @@ export class Editor {
 		};
 	}
 
-	// Alias for loadFrom(SVGLoader.fromString).
-	// This is particularly useful when accessing a bundled version of the editor.
+	/**
+	 * Alias for loadFrom(SVGLoader.fromString).
+	 * 
+	 * This is particularly useful when accessing a bundled version of the editor,
+	 * where `SVGLoader.fromString` is unavailable.
+	 */
 	public async loadFromSVG(svgData: string) {
 		const loader = SVGLoader.fromString(svgData);
 		await this.loadFrom(loader);