js-draw 0.1.12 → 0.2.1

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 {

package/src/rendering/caching/CacheRecordManager.ts

@@ -1,38 +1,64 @@
-import { BeforeDeallocCallback, PartialCacheState } from './types';
+import { BeforeDeallocCallback, CacheProps, CacheState } from './types';
 import CacheRecord from './CacheRecord';
 import Rect2 from '../../math/Rect2';
 
+const debugMode = false;
 
 export class CacheRecordManager {
 	// Fixed-size array: Cache blocks are assigned indicies into [cachedCanvases].
 	private cacheRecords: CacheRecord[] = [];
 	private maxCanvases: number;
+	private cacheState: CacheState;
 
-	public constructor(private readonly cacheState: PartialCacheState) {
-		const cacheProps = cacheState.props;
+	public constructor(cacheProps: CacheProps) {
 		this.maxCanvases = Math.ceil(
 			// Assuming four components per pixel:
 			cacheProps.cacheSize / 4 / cacheProps.blockResolution.x / cacheProps.blockResolution.y
 		);
 	}
 
+	public setSharedState(state: CacheState) {
+		this.cacheState = state;
+	}
+
 	public allocCanvas(drawTo: Rect2, onDealloc: BeforeDeallocCallback): CacheRecord {
 		if (this.cacheRecords.length < this.maxCanvases) {
 			const record: CacheRecord = new CacheRecord(
 				onDealloc,
-				{
-					...this.cacheState,
-					recordManager: this,
-				},
+				this.cacheState,
 			);
 			record.setRenderingRegion(drawTo);
 			this.cacheRecords.push(record);
 
+			if (debugMode) {
+				console.log('[Cache] Cache spaces used: ', this.cacheRecords.length, ' of ', this.maxCanvases);
+			}
+
 			return record;
 		} else {
 			const lru = this.getLeastRecentlyUsedRecord()!;
+
+			if (debugMode) {
+				console.log(
+					'[Cache] Re-alloc. Times allocated: ', lru.allocCount,
+					'\nLast used cycle: ', lru.getLastUsedCycle(),
+					'\nCurrent cycle: ', this.cacheState.currentRenderingCycle
+				);
+			}
+
 			lru.realloc(onDealloc);
 			lru.setRenderingRegion(drawTo);
+
+			if (debugMode) {
+				console.log(
+					'[Cache] Now re-alloc\'d. Last used cycle: ', lru.getLastUsedCycle()
+				);
+				console.assert(
+					lru['cacheState'] === this.cacheState,
+					'[Cache] Unequal cache states! cacheState should be a shared object!'
+				);
+			}
+
 			return lru;
 		}
 	}

package/src/rendering/caching/RenderingCache.ts

@@ -4,46 +4,41 @@ import Viewport from '../../Viewport';
 import AbstractRenderer from '../renderers/AbstractRenderer';
 import RenderingCacheNode from './RenderingCacheNode';
 import { CacheRecordManager } from './CacheRecordManager';
-import { CacheProps, CacheState, PartialCacheState } from './types';
+import { CacheProps, CacheState } from './types';
 
 export default class RenderingCache {
-	private partialSharedState: PartialCacheState;
+	private sharedState: CacheState;
 	private recordManager: CacheRecordManager;
 	private rootNode: RenderingCacheNode|null;
 
 	public constructor(cacheProps: CacheProps) {
-		this.partialSharedState = {
+		this.recordManager = new CacheRecordManager(cacheProps);
+		this.sharedState = {
 			props: cacheProps,
 			currentRenderingCycle: 0,
-		};
-		this.recordManager = new CacheRecordManager(this.partialSharedState);
-	}
-
-	public getSharedState(): CacheState {
-		return {
-			...this.partialSharedState,
 			recordManager: this.recordManager,
 		};
+		this.recordManager.setSharedState(this.sharedState);
 	}
 
 	public render(screenRenderer: AbstractRenderer, image: ImageNode, viewport: Viewport) {
 		const visibleRect = viewport.visibleRect;
-		this.partialSharedState.currentRenderingCycle ++;
+		this.sharedState.currentRenderingCycle ++;
 
 		// If we can't use the cache,
-		if (!this.partialSharedState.props.isOfCorrectType(screenRenderer)) {
+		if (!this.sharedState.props.isOfCorrectType(screenRenderer)) {
 			image.render(screenRenderer, visibleRect);
 			return;
 		}
 
 		if (!this.rootNode) {
 			// Adjust the node so that it has the correct aspect ratio
-			const res = this.partialSharedState.props.blockResolution;
+			const res = this.sharedState.props.blockResolution;
 
 			const topLeft = visibleRect.topLeft;
 			this.rootNode = new RenderingCacheNode(
 				new Rect2(topLeft.x, topLeft.y, res.x, res.y),
-				this.getSharedState()
+				this.sharedState
 			);
 		}
 
@@ -54,7 +49,7 @@ export default class RenderingCache {
 		this.rootNode = this.rootNode!.smallestChildContaining(visibleRect) ?? this.rootNode;
 
 		const visibleLeaves = image.getLeavesIntersectingRegion(viewport.visibleRect, rect => screenRenderer.isTooSmallToRender(rect));
-		if (visibleLeaves.length > this.partialSharedState.props.minComponentsToUseCache) {
+		if (visibleLeaves.length > this.sharedState.props.minComponentsToUseCache) {
 			this.rootNode!.renderItems(screenRenderer, [ image ], viewport);
 		} else {
 			image.render(screenRenderer, visibleRect);

package/src/rendering/caching/types.ts

@@ -27,13 +27,8 @@ export interface CacheProps {
     minComponentsToUseCache: number;
 }
 
-// CacheRecordManager relies on a partial copy of the shared state. Thus,
-// we need to separate partial/non-partial state.
-export interface PartialCacheState {
+export interface CacheState {
     currentRenderingCycle: number;
     props: CacheProps;
-}
-
-export interface CacheState extends PartialCacheState {
     recordManager: CacheRecordManager;
 }

package/src/rendering/renderers/CanvasRenderer.ts

@@ -64,7 +64,7 @@ export default class CanvasRenderer extends AbstractRenderer {
 			this.minRenderSizeAnyDimen = 2;
 		} else {
 			this.minSquareCurveApproxDist = 1;
-			this.minRenderSizeBothDimens = 1;
+			this.minRenderSizeBothDimens = 0.5;
 			this.minRenderSizeAnyDimen = 0;
 		}
 	}

package/src/styles.js

@@ -1,3 +1,7 @@
+/**
+ * Applies the editor's styles to the document.
+ * @packageDocumentation
+ */
 
 import './Editor.css';
 import '@melloware/coloris/dist/coloris.css';

package/src/toolbar/HTMLToolbar.ts

@@ -43,6 +43,7 @@ export default class HTMLToolbar {
 		this.setupColorPickers();
 	}
 
+	// @internal
 	public setupColorPickers() {
 		const closePickerOverlay = document.createElement('div');
 		closePickerOverlay.className = `${toolbarCSSPrefix}closeColorPickerOverlay`;

package/src/toolbar/makeColorInput.ts

@@ -8,7 +8,7 @@ import { makePipetteIcon } from './icons';
 type OnColorChangeListener = (color: Color4)=>void;
 
 
-// Returns [ input, container ].
+// Returns [ color input, input container ].
 export const makeColorInput = (editor: Editor, onColorChange: OnColorChangeListener): [ HTMLInputElement, HTMLElement ] => {
 	const colorInputContainer = document.createElement('span');
 	const colorInput = document.createElement('input');

package/src/toolbar/toolbar.css

@@ -24,6 +24,7 @@
 .toolbar-root > .toolbar-toolContainer > * > button,
 .toolbar-root > .toolbar-buttonGroup > button {
 	width: min-content;
+	white-space: pre;
 	height: min(20vh, 60px);
 }
 
@@ -64,8 +65,13 @@
 	margin-right: 3px;
 
 	min-width: 40px;
-	max-width: 70px;
-	font-size: 11pt;
+	width: min-content;
+	font-size: 1em;
+}
+
+.toolbar-dropdown > .toolbar-toolContainer > button,
+.toolbar-dropdown > .toolbar-toolContainer > .toolbar-button {
+	width: 6em;
 }
 
 .toolbar-button:hover, .toolbar-root button:not(:disabled):hover {

package/src/toolbar/widgets/PenWidget.ts

@@ -1,3 +1,5 @@
+// @internal @packageDocumentation
+
 import { makeArrowBuilder } from '../../components/builders/ArrowBuilder';
 import { makeFreehandLineBuilder } from '../../components/builders/FreehandLineBuilder';
 import { makeLineBuilder } from '../../components/builders/LineBuilder';

package/src/tools/PanZoom.ts

@@ -16,7 +16,6 @@ interface PinchData {
 	dist: number;
 }
 
-
 export enum PanZoomMode {
 	OneFingerTouchGestures = 0x1,
 	TwoFingerTouchGestures = 0x1 << 1,

package/src/tools/Pen.ts

@@ -8,7 +8,7 @@ import BaseTool from './BaseTool';
 import { ToolType } from './ToolController';
 import { ComponentBuilder, ComponentBuilderFactory } from '../components/builders/types';
 
-interface PenStyle {
+export interface PenStyle {
     color: Color4;
     thickness: number;
 }
@@ -34,7 +34,16 @@ export default class Pen extends BaseTool {
 
 	private getStrokePoint(pointer: Pointer): StrokeDataPoint {
 		const minPressure = 0.3;
-		const pressure = Math.max(pointer.pressure ?? 1.0, minPressure);
+		let pressure = Math.max(pointer.pressure ?? 1.0, minPressure);
+
+		if (!isFinite(pressure)) {
+			console.warn('Non-finite pressure!', pointer);
+			pressure = minPressure;
+		}
+		console.assert(isFinite(pointer.canvasPos.length()), 'Non-finite canvas position!');
+		console.assert(isFinite(pointer.screenPos.length()), 'Non-finite screen position!');
+		console.assert(isFinite(pointer.timeStamp), 'Non-finite timeStamp on pointer!');
+
 		return {
 			pos: pointer.canvasPos,
 			width: pressure * this.getPressureMultiplier(),

package/src/tools/PipetteTool.ts

@@ -1,3 +1,5 @@
+// @internal @packageDocumentation
+
 import Color4 from '../Color4';
 import Editor from '../Editor';
 import { PointerEvt } from '../types';

package/src/tools/SelectionTool.ts

@@ -12,6 +12,7 @@ import { EditorEventType, KeyPressEvent, KeyUpEvent, PointerEvt } from '../types
 import Viewport from '../Viewport';
 import BaseTool from './BaseTool';
 import { ToolType } from './ToolController';
+import SerializableCommand from '../commands/SerializableCommand';
 
 const handleScreenSize = 30;
 const styles = `
@@ -124,6 +125,7 @@ const makeDraggable = (element: HTMLElement, onDrag: DragCallback, onDragEnd: Dr
 // Maximum number of strokes to transform without a re-render.
 const updateChunkSize = 100;
 
+// @internal
 class Selection {
 	public region: Rect2;
 	private boxRotation: number;
@@ -131,7 +133,7 @@ class Selection {
 	private rotateCircle: HTMLElement;
 	private selectedElems: AbstractComponent[];
 	private transform: Mat33;
-	private transformationCommands: Command[];
+	private transformationCommands: SerializableCommand[];
 
 	public constructor(
 		public startPoint: Point2, private editor: Editor
@@ -230,7 +232,7 @@ class Selection {
 		this.transformPreview(Mat33.zRotation(deltaRotation, this.region.center));
 	}
 
-	private computeTransformCommands() {
+	private computeTransformCommands(): SerializableCommand[] {
 		return this.selectedElems.map(elem => {
 			return elem.transformBy(this.transform);
 		});
@@ -275,39 +277,65 @@ class Selection {
 
 		// Make the commands undo-able
 		this.editor.dispatch(new Selection.ApplyTransformationCommand(
-			this, currentTransfmCommands, fullTransform, inverseTransform, deltaBoxRotation
+			this, currentTransfmCommands, fullTransform, deltaBoxRotation
 		));
 	}
 
-	private static ApplyTransformationCommand = class extends Command {
+	static {
+		SerializableCommand.register('selection-tool-transform', (json: any, editor) => {
+			// The selection box is lost when serializing/deserializing. No need to store box rotation
+			const guiBoxRotation = 0;
+			const fullTransform: Mat33 = new Mat33(...(json.transform as [
+				number, number, number,
+				number, number, number,
+				number, number, number,
+			]));
+			const commands = (json.commands as any[]).map(data => SerializableCommand.deserialize(data, editor));
+
+			return new this.ApplyTransformationCommand(null, commands, fullTransform, guiBoxRotation);
+		});
+	}
+
+	private static ApplyTransformationCommand = class extends SerializableCommand {
 		public constructor(
-			private selection: Selection,
-			private currentTransfmCommands: Command[],
-			private fullTransform: Mat33, private inverseTransform: Mat33,
+			private selection: Selection|null,
+			private currentTransfmCommands: SerializableCommand[],
+			private fullTransform: Mat33,
 			private deltaBoxRotation: number,
 		) {
-			super();
+			super('selection-tool-transform');
 		}
 
 		public async apply(editor: Editor) {
 			// Approximate the new selection
-			this.selection.region = this.selection.region.transformedBoundingBox(this.fullTransform);
-			this.selection.boxRotation += this.deltaBoxRotation;
-			this.selection.updateUI();
+			if (this.selection) {
+				this.selection.region = this.selection.region.transformedBoundingBox(this.fullTransform);
+				this.selection.boxRotation += this.deltaBoxRotation;
+				this.selection.updateUI();
+			}
 
 			await editor.asyncApplyCommands(this.currentTransfmCommands, updateChunkSize);
-			this.selection.recomputeRegion();
-			this.selection.updateUI();
+			this.selection?.recomputeRegion();
+			this.selection?.updateUI();
 		}
 
 		public async unapply(editor: Editor) {
-			this.selection.region = this.selection.region.transformedBoundingBox(this.inverseTransform);
-			this.selection.boxRotation -= this.deltaBoxRotation;
-			this.selection.updateUI();
+			if (this.selection) {
+				this.selection.region = this.selection.region.transformedBoundingBox(this.fullTransform.inverse());
+				this.selection.boxRotation -= this.deltaBoxRotation;
+				this.selection.updateUI();
+			}
 
 			await editor.asyncUnapplyCommands(this.currentTransfmCommands, updateChunkSize);
-			this.selection.recomputeRegion();
-			this.selection.updateUI();
+			this.selection?.recomputeRegion();
+			this.selection?.updateUI();
+		}
+
+		protected serializeToJSON() {
+			return {
+				commands: this.currentTransfmCommands.map(command => command.serialize()),
+				transform: this.fullTransform.toArray(),
+			};
 		}
 
 		public description(_editor: Editor, localizationTable: EditorLocalization) {

package/src/types.ts

@@ -9,6 +9,7 @@ import AbstractComponent from './components/AbstractComponent';
 import Rect2 from './math/Rect2';
 import Pointer from './Pointer';
 import Color4 from './Color4';
+import Command from './commands/Command';
 
 
 export interface PointerEvtListener {
@@ -91,12 +92,17 @@ export enum EditorEventType {
 	ToolEnabled,
 	ToolDisabled,
 	ToolUpdated,
+
 	UndoRedoStackUpdated,
+	CommandDone,
+	CommandUndone,
 	ObjectAdded,
+
 	ViewportChanged,
 	DisplayResized,
+
 	ColorPickerToggled,
-	ColorPickerColorSelected
+	ColorPickerColorSelected,
 }
 
 type EditorToolEventType = EditorEventType.ToolEnabled
@@ -131,6 +137,16 @@ export interface EditorUndoStackUpdated {
 	readonly redoStackSize: number;
 }
 
+export interface CommandDoneEvent {
+	readonly kind: EditorEventType.CommandDone;
+	readonly command: Command;
+}
+
+export interface CommandUndoneEvent {
+	readonly kind: EditorEventType.CommandUndone;
+	readonly command: Command;
+}
+
 export interface ColorPickerToggled {
 	readonly kind: EditorEventType.ColorPickerToggled;
 	readonly open: boolean;
@@ -143,8 +159,8 @@ export interface ColorPickerColorSelected {
 
 export type EditorEventDataType = EditorToolEvent | EditorObjectEvent
 	| EditorViewportChangedEvent | DisplayResizedEvent
-	| EditorUndoStackUpdated
-	| ColorPickerToggled| ColorPickerColorSelected;
+	| EditorUndoStackUpdated | CommandDoneEvent | CommandUndoneEvent
+	| ColorPickerToggled | ColorPickerColorSelected;
 
 
 // Returns a Promise to indicate that the event source should pause until the Promise resolves.

package/tsconfig.json

@@ -24,6 +24,9 @@
 
 		// Files that don't need transpilation
 		"**/*.test.ts",
-		"__mocks__/*"
+		"__mocks__/*",
+
+		// Output files
+		"./dist/**"
 	],
 }

package/typedoc.json

@@ -0,0 +1,20 @@
+{
+	"entryPoints": [
+		"./src/"
+	],
+	"exclude": [
+		"**/*.test.ts"
+	],
+	"excludePrivate": true,
+	"excludeInternal": true,
+	"commentStyle": "all",
+	"readme": "README.md",
+	"entryPointStrategy": "expand",
+	"out": "docs/typedoc/",
+
+	"validation": {
+		"notExported": false,
+		"invalidLink": true,
+		"notDocumented": false
+	}
+}