js-draw 0.12.0 → 0.13.0

package/src/toolbar/IconProvider.ts

@@ -43,7 +43,7 @@ export default class IconProvider {
 		return this.makeRedoIcon(true);
 	}
 
-	// @param mirror - reflect across the x-axis @internal
+	// @param mirror - reflect across the x-axis. This parameter is internal.
 	// @returns a redo icon.
 	public makeRedoIcon(mirror: boolean = false): IconType {
 		const icon = document.createElementNS(svgNamespace, 'svg');
@@ -383,52 +383,119 @@ export default class IconProvider {
 		return icon;
 	}
 	
-	public makePenIcon(tipThickness: number, color: string|Color4, roundedTip?: boolean): IconType {
+	public makePenIcon(strokeSize: number, color: string|Color4, rounded?: boolean): IconType {
 		if (color instanceof Color4) {
 			color = color.toHexString();
 		}
 	
 		const icon = document.createElementNS(svgNamespace, 'svg');
 		icon.setAttribute('viewBox', '0 0 100 100');
-	
-		const halfThickness = tipThickness / 2;
-	
-		// Draw a pen-like shape
-		const penTipLeft = 50 - halfThickness;
-		const penTipRight = 50 + halfThickness;
+		const tipThickness = strokeSize / 2;
 
-		let tipCenterPrimaryPath = `L${penTipLeft},95 L${penTipRight},90`;
-		let tipCenterBackgroundPath = `L${penTipLeft},85 L${penTipRight},83`;
+		const inkTipPath = `
+			M ${15 - tipThickness},${80 - tipThickness}
+			  ${15 - tipThickness},${80 + tipThickness}
+			  30,83
+			  15,65
+			Z
+		`;
+		const trailStartEndY = 80 + tipThickness;
+		const inkTrailPath = `
+			m ${15 - tipThickness * 1.1},${trailStartEndY}
+			c 35,10 55,15 60,30
+			l ${35 + tipThickness * 1.2},${-10 - tipThickness}
+			C 80.47,98.32 50.5,${90 + tipThickness} 20,${trailStartEndY} Z
+		`;
 
-		if (roundedTip) {
-			tipCenterPrimaryPath = `L${penTipLeft},95 q${halfThickness},10 ${2 * halfThickness},-5`;
-			tipCenterBackgroundPath = `L${penTipLeft},87 q${halfThickness},10 ${2 * halfThickness},-3`;
+		const colorBubblePath = `
+			M 72.45,35.67
+			A 10,15 41.8 0 1 55,40.2 10,15 41.8 0 1 57.55,22.3 10,15 41.8 0 1 75,17.8 10,15 41.8 0 1 72.5,35.67
+			Z
+		`;
+
+		let gripMainPath = 'M 85,-25 25,35 h 10 v 10 h 10 v 10 h 10 v 10 h 10 l -5,10 60,-60 z';
+		let gripShadow1Path = 'M 25,35 H 35 L 90,-15 85,-25 Z';
+		let gripShadow2Path = 'M 60,75 65,65 H 55 l 55,-55 10,5 z';
+
+		if (rounded) {
+			gripMainPath = 'M 85,-25 25,35 c 15,0 40,30 35,40 l 60,-60 z';
+			gripShadow1Path = 'm 25,35 c 3.92361,0.384473 7.644275,0.980572 10,3 l 55,-53 -5,-10 z';
+			gripShadow2Path = 'M 60,75 C 61,66 59,65 56,59 l 54,-54 10,10 z';
 		}
 
-		const primaryStrokeTipPath = `M14,63 ${tipCenterPrimaryPath} L88,60 Z`;
-		const backgroundStrokeTipPath = `M14,63 ${tipCenterBackgroundPath} L88,60 Z`;
+		const penTipPath = `M 25,35 ${10 - tipThickness / 4},${70 - tipThickness / 2} 20,75 25,85 60,75 70,55 45,25 Z`;
 
-		icon.innerHTML = `
-		<defs>
-			${checkerboardPatternDef}
-		</defs>
-		<g>
-			<!-- Pen grip -->
+		const pencilTipColor = Color4.fromHex('#f4d7d7');
+		const tipColor = pencilTipColor.mix(
+			Color4.fromString(color), tipThickness / 40 - 0.1
+		).toHexString();
+
+		const ink = `
+			<path
+				fill="${checkerboardPatternRef}"
+				d="${inkTipPath}"
+			/>
+			<path
+				fill="${checkerboardPatternRef}"
+				d="${inkTrailPath}"
+			/>
+			<path
+				fill="${color}"
+				d="${inkTipPath}"
+			/>
+			<path
+				fill="${color}"
+				d="${inkTrailPath}"
+			/>
+		`;
+
+		const penTip = `
+			<path
+				fill="${checkerboardPatternRef}"
+				d="${penTipPath}"
+			/>
+			<path
+				fill="${tipColor}"
+				stroke="${color}"
+				d="${penTipPath}"
+			/>
+		`;
+
+		const grip = `
 			<path
-				d='M10,10 L90,10 L90,60 L${50 + halfThickness},80 L${50 - halfThickness},80 L10,60 Z'
 				${iconColorStrokeFill}
+				d="${gripMainPath}"
+			/>
+
+			<!-- shadows -->
+			<path
+				fill="rgba(150, 150, 150, 0.3)"
+				d="${gripShadow1Path}"
 			/>
-		</g>
-		<g>
-			<!-- Checkerboard background for slightly transparent pens -->
-			<path d='${backgroundStrokeTipPath}' fill='${checkerboardPatternRef}'/>
-	
-			<!-- Actual pen tip -->
 			<path
-				d='${primaryStrokeTipPath}'
-				fill='${color}'
-				stroke='${color}'
+				fill="rgba(100, 100, 100, 0.2)"
+				d="${gripShadow2Path}"
 			/>
+
+			<!-- color bubble -->
+			<path
+				fill="${checkerboardPatternRef}"
+				d="${colorBubblePath}"
+			/>
+			<path
+				fill="${color}"
+				d="${colorBubblePath}"
+			/>
+		`;
+
+		icon.innerHTML = `
+		<defs>
+			${checkerboardPatternDef}
+		</defs>
+		<g>
+			${ink}
+			${penTip}
+			${grip}
 		</g>
 		`;
 		return icon;

package/src/tools/PanZoom.ts

@@ -338,7 +338,7 @@ export default class PanZoom extends BaseTool {
 			toCanvas.transformVec3(
 				Vec3.of(-delta.x, -delta.y, 0)
 			);
-		const pinchZoomScaleFactor = 1.04;
+		const pinchZoomScaleFactor = 1.03;
 		const transformUpdate = Mat33.scaling2D(
 			Math.max(0.25, Math.min(Math.pow(pinchZoomScaleFactor, -delta.z), 4)), canvasPos
 		).rightMul(

package/src/tools/PasteHandler.ts

@@ -1,8 +1,3 @@
-/**
- * A tool that handles paste events.
- * @packageDocumentation
- */
-
 import Editor from '../Editor';
 import { AbstractComponent, TextComponent } from '../components/lib';
 import SVGLoader from '../SVGLoader';
@@ -14,12 +9,23 @@ import Color4 from '../Color4';
 import { TextStyle } from '../components/TextComponent';
 import ImageComponent from '../components/ImageComponent';
 
-// { @inheritDoc PasteHandler! }
+/**
+ * A tool that handles paste events (e.g. as triggered by ctrl+V).
+ * 
+ * @example
+ * While `ToolController` has a `PasteHandler` in its default list of tools,
+ * if a non-default set is being used, `PasteHandler` can be added as follows:
+ * ```ts
+ * const toolController = editor.toolController;
+ * toolController.addTool(new PasteHandler(editor));
+ * ```
+ */
 export default class PasteHandler extends BaseTool {
 	public constructor(private editor: Editor) {
 		super(editor.notifier, editor.localization.pasteHandler);
 	}
 
+	// @internal
 	public onPaste(event: PasteEvent): boolean {
 		const mime = event.mime.toLowerCase();
 

package/src/tools/Pen.test.ts

@@ -1,8 +1,12 @@
 
-import { Rect2 } from '../lib';
+import PenTool from './Pen';
 import { Vec2 } from '../math/Vec2';
 import createEditor from '../testing/createEditor';
 import { InputEvtType } from '../types';
+import Rect2 from '../math/Rect2';
+import StrokeComponent from '../components/Stroke';
+import Mat33 from '../math/Mat33';
+import { makeFreehandLineBuilder } from '../components/builders/FreehandLineBuilder';
 
 describe('Pen', () => {
 	it('should draw horizontal lines', () => {
@@ -147,4 +151,43 @@ describe('Pen', () => {
 		expect(elems[0].getBBox().topLeft).objEq(Vec2.of(420, 24), 32); // ± 32
 		expect(elems[0].getBBox().bottomRight).objEq(Vec2.of(420, 340), 25); // ± 25
 	});
+
+	it('ctrl+z should finalize then undo the current stroke', async () => {
+		const editor = createEditor();
+
+		expect(editor.history.undoStackSize).toBe(0);
+
+		editor.sendPenEvent(InputEvtType.PointerDownEvt, Vec2.of(10, 10)); 
+		jest.advanceTimersByTime(100);
+		editor.sendPenEvent(InputEvtType.PointerMoveEvt, Vec2.of(20, 10));
+
+		const ctrlKeyDown = true;
+		editor.sendKeyboardEvent(InputEvtType.KeyPressEvent, 'z', ctrlKeyDown);
+
+		// Stroke should have been undone
+		expect(editor.history.redoStackSize).toBe(1);
+
+		// Lifting the pointer up shouldn't clear the redo stack.
+		editor.sendPenEvent(InputEvtType.PointerUpEvt, Vec2.of(420, 340));
+		expect(editor.history.redoStackSize).toBe(1);
+	});
+
+	it('holding ctrl should snap the stroke to grid', () => {
+		const editor = createEditor();
+		editor.viewport.resetTransform(Mat33.identity);
+
+		const penTool = editor.toolController.getMatchingTools(PenTool)[0];
+		penTool.setStrokeFactory(makeFreehandLineBuilder);
+
+		editor.sendPenEvent(InputEvtType.PointerDownEvt, Vec2.of(0.1, 0.1)); 
+		jest.advanceTimersByTime(100);
+		editor.sendPenEvent(InputEvtType.PointerMoveEvt, Vec2.of(10.1, 10.1));
+		editor.sendPenEvent(InputEvtType.PointerUpEvt, Vec2.of(10.1, 10.1));
+
+		const allElems = editor.image.getAllElements();
+		expect(allElems).toHaveLength(1);
+
+		const firstStroke = allElems[0] as StrokeComponent;
+		expect(firstStroke.getPath().bbox).objEq(new Rect2(0, 0, 10, 10));
+	});
 });

package/src/tools/Pen.ts

@@ -3,7 +3,7 @@ import Editor from '../Editor';
 import EditorImage from '../EditorImage';
 import Pointer, { PointerDevice } from '../Pointer';
 import { makeFreehandLineBuilder } from '../components/builders/FreehandLineBuilder';
-import { EditorEventType, KeyPressEvent, PointerEvt, StrokeDataPoint } from '../types';
+import { EditorEventType, KeyPressEvent, KeyUpEvent, PointerEvt, StrokeDataPoint } from '../types';
 import BaseTool from './BaseTool';
 import { ComponentBuilder, ComponentBuilderFactory } from '../components/builders/types';
 
@@ -15,6 +15,7 @@ export interface PenStyle {
 export default class Pen extends BaseTool {
 	protected builder: ComponentBuilder|null = null;
 	private lastPoint: StrokeDataPoint|null = null;
+	private ctrlKeyPressed: boolean = false;
 
 	public constructor(
 		private editor: Editor,
@@ -31,6 +32,10 @@ export default class Pen extends BaseTool {
 
 	// Converts a `pointer` to a `StrokeDataPoint`.
 	protected toStrokePoint(pointer: Pointer): StrokeDataPoint {
+		if (this.isSnappingToGrid()) {
+			pointer = pointer.snappedToGrid(this.editor.viewport);
+		}
+
 		const minPressure = 0.3;
 		let pressure = Math.max(pointer.pressure ?? 1.0, minPressure);
 
@@ -42,8 +47,10 @@ export default class Pen extends BaseTool {
 		console.assert(isFinite(pointer.screenPos.length()), 'Non-finite screen position!');
 		console.assert(isFinite(pointer.timeStamp), 'Non-finite timeStamp on pointer!');
 
+		const pos = pointer.canvasPos;
+
 		return {
-			pos: pointer.canvasPos,
+			pos,
 			width: pressure * this.getPressureMultiplier(),
 			color: this.style.color,
 			time: pointer.timeStamp,
@@ -86,6 +93,8 @@ export default class Pen extends BaseTool {
 	}
 
 	public onPointerMove({ current }: PointerEvt): void {
+		if (!this.builder) return;
+
 		this.addPointToStroke(this.toStrokePoint(current));
 	}
 
@@ -102,7 +111,18 @@ export default class Pen extends BaseTool {
 		};
 
 		this.addPointToStroke(strokePoint);
-		if (this.builder && current.isPrimary) {
+
+		if (current.isPrimary) {
+			this.finalizeStroke();
+		}
+	}
+
+	public onGestureCancel() {
+		this.editor.clearWetInk();
+	}
+
+	private finalizeStroke() {
+		if (this.builder) {
 			const stroke = this.builder.build();
 			this.previewStroke();
 
@@ -118,10 +138,6 @@ export default class Pen extends BaseTool {
 		this.editor.clearWetInk();
 	}
 
-	public onGestureCancel() {
-		this.editor.clearWetInk();
-	}
-
 	private noteUpdated() {
 		this.editor.notifier.dispatch(EditorEventType.ToolUpdated, {
 			kind: EditorEventType.ToolUpdated,
@@ -160,7 +176,15 @@ export default class Pen extends BaseTool {
 	public getColor() { return this.style.color; }
 	public getStrokeFactory() { return this.builderFactory; }
 
-	public onKeyPress({ key }: KeyPressEvent): boolean {
+	public setEnabled(enabled: boolean): void {
+		super.setEnabled(enabled);
+
+		this.ctrlKeyPressed = false;
+	}
+
+	private isSnappingToGrid() { return this.ctrlKeyPressed; }
+
+	public onKeyPress({ key, ctrlKey }: KeyPressEvent): boolean {
 		key = key.toLowerCase();
 
 		let newThickness: number|undefined;
@@ -176,6 +200,27 @@ export default class Pen extends BaseTool {
 			return true;
 		}
 
+		if (key === 'control') {
+			this.ctrlKeyPressed = true;
+			return true;
+		}
+
+		// Ctrl+Z: End the stroke so that it can be undone/redone.
+		if (key === 'z' && ctrlKey && this.builder) {
+			this.finalizeStroke();
+		}
+
+		return false;
+	}
+
+	public onKeyUp({ key }: KeyUpEvent): boolean {
+		key = key.toLowerCase();
+
+		if (key === 'control') {
+			this.ctrlKeyPressed = false;
+			return true;
+		}
+
 		return false;
 	}
 }

package/src/tools/SelectionTool/SelectionHandle.ts

@@ -18,6 +18,7 @@ export type DragEndCallback = ()=> void;
 
 export default class SelectionHandle {
 	private element: HTMLElement;
+	private snapToGrid: boolean;
 
 	// Bounding box in screen coordinates.
 
@@ -96,4 +97,12 @@ export default class SelectionHandle {
 		}
 		this.onDragEnd();
 	}
+
+	public setSnapToGrid(snap: boolean) {
+		this.snapToGrid = snap;
+	}
+
+	public isSnappingToGrid() {
+		return this.snapToGrid;
+	}
 }

package/src/tools/SelectionTool/SelectionTool.ts

@@ -1,7 +1,3 @@
-// Allows users to select/transform portions of the `EditorImage`.
-// With respect to `extend`ing, `SelectionTool` is not stable.
-// @packageDocumentation
-
 import AbstractComponent from '../../components/AbstractComponent';
 import Editor from '../../Editor';
 import Mat33 from '../../math/Mat33';
@@ -16,7 +12,8 @@ import TextComponent from '../../components/TextComponent';
 
 export const cssPrefix = 'selection-tool-';
 
-// {@inheritDoc SelectionTool!}
+// Allows users to select/transform portions of the `EditorImage`.
+// With respect to `extend`ing, `SelectionTool` is not stable.
 export default class SelectionTool extends BaseTool {
 	private handleOverlay: HTMLElement;
 	private prevSelectionBox: Selection|null;
@@ -25,6 +22,7 @@ export default class SelectionTool extends BaseTool {
 
 	private expandingSelectionBox: boolean = false;
 	private shiftKeyPressed: boolean = false;
+	private ctrlKeyPressed: boolean = false;
 
 	public constructor(private editor: Editor, description: string) {
 		super(editor.notifier, description);
@@ -61,17 +59,47 @@ export default class SelectionTool extends BaseTool {
 		this.selectionBox.addTo(this.handleOverlay);
 	}
 
+	private snapSelectionToGrid() {
+		if (!this.selectionBox) throw new Error('No selection to snap!');
+
+		const topLeftOfBBox = this.selectionBox.region.topLeft;
+		const snapDistance =
+				this.editor.viewport.snapToGrid(topLeftOfBBox).minus(topLeftOfBBox);
+		
+		const oldTransform = this.selectionBox.getTransform();
+		this.selectionBox.setTransform(oldTransform.rightMul(Mat33.translation(snapDistance)));
+		this.selectionBox.finalizeTransform();
+	}
+
 	private selectionBoxHandlingEvt: boolean = false;
-	public onPointerDown(event: PointerEvt): boolean {
-		if (event.allPointers.length === 1 && event.current.isPrimary) {
-			if (this.lastEvtTarget && this.selectionBox?.onDragStart(event.current, this.lastEvtTarget)) {
-				this.selectionBoxHandlingEvt = true;
-				this.expandingSelectionBox = false;
+	public onPointerDown({ allPointers, current }: PointerEvt): boolean {
+		const snapToGrid = this.ctrlKeyPressed;
+		if (snapToGrid) {
+			current = current.snappedToGrid(this.editor.viewport);
+		}
+
+		if (allPointers.length === 1 && current.isPrimary) {
+			let transforming = false;
+
+			if (this.lastEvtTarget && this.selectionBox) {
+				if (snapToGrid) {
+					this.snapSelectionToGrid();
+				}
+
+				const dragStartResult = this.selectionBox.onDragStart(current, this.lastEvtTarget);
+
+				if (dragStartResult) {
+					transforming = true;
+
+					this.selectionBoxHandlingEvt = true;
+					this.expandingSelectionBox = false;
+				}
 			}
-			else {
+
+			if (!transforming) {
 				// Shift key: Combine the new and old selection boxes at the end of the gesture.
 				this.expandingSelectionBox = this.shiftKeyPressed;
-				this.makeSelectionBox(event.current.canvasPos);
+				this.makeSelectionBox(current.canvasPos);
 			}
 
 			return true;
@@ -82,10 +110,15 @@ export default class SelectionTool extends BaseTool {
 	public onPointerMove(event: PointerEvt): void {
 		if (!this.selectionBox) return;
 
+		let currentPointer = event.current;
+		if (this.ctrlKeyPressed) {
+			currentPointer = currentPointer.snappedToGrid(this.editor.viewport);
+		}
+
 		if (this.selectionBoxHandlingEvt) {
-			this.selectionBox.onDragUpdate(event.current);
+			this.selectionBox.onDragUpdate(currentPointer);
 		} else {
-			this.selectionBox!.setToPoint(event.current.canvasPos);
+			this.selectionBox!.setToPoint(currentPointer.canvasPos);
 		}
 	}
 
@@ -137,7 +170,12 @@ export default class SelectionTool extends BaseTool {
 	public onPointerUp(event: PointerEvt): void {
 		if (!this.selectionBox) return;
 
-		this.selectionBox.setToPoint(event.current.canvasPos);
+		let currentPointer = event.current;
+		if (this.ctrlKeyPressed) {
+			currentPointer = currentPointer.snappedToGrid(this.editor.viewport);
+		}
+
+		this.selectionBox.setToPoint(currentPointer.canvasPos);
 
 		// Were we expanding the previous selection?
 		if (this.expandingSelectionBox && this.prevSelectionBox) {
@@ -173,8 +211,14 @@ export default class SelectionTool extends BaseTool {
 		'e', 'j', 'ArrowDown',
 		'r', 'R',
 		'i', 'I', 'o', 'O',
+		'Control',
 	];
 	public onKeyPress(event: KeyPressEvent): boolean {
+		if (event.key === 'Control') {
+			this.ctrlKeyPressed = true;
+			return true;
+		}
+
 		if (this.selectionBox && event.ctrlKey && event.key === 'd') {
 			// Handle duplication on key up — we don't want to accidentally duplicate
 			// many times.
@@ -290,6 +334,11 @@ export default class SelectionTool extends BaseTool {
 	}
 
 	public onKeyUp(evt: KeyUpEvent) {
+		if (evt.key === 'Control') {
+			this.ctrlKeyPressed = false;
+			return true;
+		}
+
 		if (evt.key === 'Shift') {
 			this.shiftKeyPressed = false;
 			return true;
@@ -358,6 +407,9 @@ export default class SelectionTool extends BaseTool {
 		this.handleOverlay.replaceChildren();
 		this.selectionBox = null;
 
+		this.shiftKeyPressed = false;
+		this.ctrlKeyPressed = false;
+
 		this.handleOverlay.style.display = enabled ? 'block' : 'none';
 
 		if (enabled) {

package/src/tools/ToolSwitcherShortcut.ts

@@ -1,16 +1,21 @@
-// Handles ctrl+1, ctrl+2, ctrl+3, ..., shortcuts for switching tools.
-// @packageDocumentation
-
 import Editor from '../Editor';
 import { KeyPressEvent } from '../types';
 import BaseTool from './BaseTool';
 
-// {@inheritDoc ToolSwitcherShortcut!}
+/**
+ * Handles keyboard events used, by default, to select tools. By default,
+ * 1 maps to the first primary tool, 2 to the second primary tool, ... .
+ *
+ * This is in the default set of {@link ToolController} tools.
+ * 
+ * @deprecated This may be replaced in the future.
+ */
 export default class ToolSwitcherShortcut extends BaseTool {
 	public constructor(private editor: Editor) {
 		super(editor.notifier, editor.localization.changeTool);
 	}
-	
+
+	// @internal
 	public onKeyPress({ key }: KeyPressEvent): boolean {
 		const toolController = this.editor.toolController;
 		const primaryTools = toolController.getPrimaryTools();

package/src/tools/UndoRedoShortcut.ts

@@ -1,17 +1,14 @@
-// Handles ctrl+Z, ctrl+Shift+Z keyboard shortcuts.
-// @packageDocumentation
-
 import Editor from '../Editor';
 import { KeyPressEvent } from '../types';
 import BaseTool from './BaseTool';
 
-// {@inheritDoc UndoRedoShortcut!}
+// Handles ctrl+Z, ctrl+Shift+Z keyboard shortcuts.
 export default class UndoRedoShortcut extends BaseTool {
 	public constructor(private editor: Editor) {
 		super(editor.notifier, editor.localization.undoRedoTool);
 	}
     
-	// Activate undo/redo
+	// @internal
 	public onKeyPress({ key, ctrlKey }: KeyPressEvent): boolean {
 		if (ctrlKey) {
 			if (key === 'z') {

package/typedoc.json

@@ -1,6 +1,6 @@
 {
 	"entryPoints": [
-		"./src/"
+		"./src/lib.ts", "./src/bundle/bundled.ts"
 	],
 	"exclude": [
 		"**/*.test.ts",
@@ -21,4 +21,4 @@
 		"invalidLink": true,
 		"notDocumented": false
 	}
-}
+}