js-draw 0.23.0 → 0.24.0

package/src/tools/ToolController.ts

@@ -0,0 +1,185 @@
+import { InputEvtType, InputEvt, EditorEventType } from '../types';
+import Editor from '../Editor';
+import BaseTool from './BaseTool';
+import PanZoom, { PanZoomMode } from './PanZoom';
+import Pen from './Pen';
+import ToolEnabledGroup from './ToolEnabledGroup';
+import Eraser from './Eraser';
+import SelectionTool from './SelectionTool/SelectionTool';
+import Color4 from '../Color4';
+import { ToolLocalization } from './localization';
+import UndoRedoShortcut from './UndoRedoShortcut';
+import TextTool from './TextTool';
+import PipetteTool from './PipetteTool';
+import ToolSwitcherShortcut from './ToolSwitcherShortcut';
+import PasteHandler from './PasteHandler';
+import ToolbarShortcutHandler from './ToolbarShortcutHandler';
+import { makePressureSensitiveFreehandLineBuilder } from '../components/builders/PressureSensitiveFreehandLineBuilder';
+import FindTool from './FindTool';
+import SelectAllShortcutHandler from './SelectionTool/SelectAllShortcutHandler';
+import SoundUITool from './SoundUITool';
+
+export default class ToolController {
+	private tools: BaseTool[];
+	private activeTool: BaseTool|null = null;
+	private primaryToolGroup: ToolEnabledGroup;
+
+	/** @internal */
+	public constructor(editor: Editor, localization: ToolLocalization) {
+		const primaryToolGroup = new ToolEnabledGroup();
+		this.primaryToolGroup = primaryToolGroup;
+
+		const panZoomTool = new PanZoom(editor, PanZoomMode.TwoFingerTouchGestures | PanZoomMode.RightClickDrags, localization.touchPanTool);
+		const keyboardPanZoomTool = new PanZoom(editor, PanZoomMode.Keyboard, localization.keyboardPanZoom);
+		const primaryPenTool = new Pen(editor, localization.penTool(1), { color: Color4.purple, thickness: 8 });
+		const primaryTools = [
+			// Three pens
+			primaryPenTool,
+			new Pen(editor, localization.penTool(2), { color: Color4.clay, thickness: 4 }),
+
+			// Highlighter-like pen with width=40
+			new Pen(editor, localization.penTool(3), { color: Color4.ofRGBA(1, 1, 0, 0.5), thickness: 40 }, makePressureSensitiveFreehandLineBuilder),
+
+			new Eraser(editor, localization.eraserTool),
+			new SelectionTool(editor, localization.selectionTool),
+			new TextTool(editor, localization.textTool, localization),
+			new PanZoom(editor, PanZoomMode.SinglePointerGestures, localization.anyDevicePanning),
+		];
+
+		// Accessibility tools
+		const soundExplorer = new SoundUITool(editor, localization.soundExplorer);
+		soundExplorer.setEnabled(false);
+
+		this.tools = [
+			new PipetteTool(editor, localization.pipetteTool),
+			soundExplorer,
+			panZoomTool,
+			...primaryTools,
+			keyboardPanZoomTool,
+			new UndoRedoShortcut(editor),
+			new ToolbarShortcutHandler(editor),
+			new ToolSwitcherShortcut(editor),
+			new FindTool(editor),
+			new PasteHandler(editor),
+			new SelectAllShortcutHandler(editor),
+		];
+		primaryTools.forEach(tool => tool.setToolGroup(primaryToolGroup));
+		panZoomTool.setEnabled(true);
+		primaryPenTool.setEnabled(true);
+
+		editor.notifier.on(EditorEventType.ToolEnabled, event => {
+			if (event.kind === EditorEventType.ToolEnabled) {
+				editor.announceForAccessibility(localization.toolEnabledAnnouncement(event.tool.description));
+			}
+		});
+		editor.notifier.on(EditorEventType.ToolDisabled, event => {
+			if (event.kind === EditorEventType.ToolDisabled) {
+				editor.announceForAccessibility(localization.toolDisabledAnnouncement(event.tool.description));
+			}
+		});
+
+		this.activeTool = null;
+	}
+
+	// Replaces the current set of tools with `tools`. This should only be done before
+	// the creation of the app's toolbar (if using `HTMLToolbar`).
+	public setTools(tools: BaseTool[], primaryToolGroup?: ToolEnabledGroup) {
+		this.tools = tools;
+		this.primaryToolGroup = primaryToolGroup ?? new ToolEnabledGroup();
+	}
+
+	// Add a tool that acts like one of the primary tools (only one primary tool can be enabled at a time).
+	// This should be called before creating the app's toolbar.
+	public addPrimaryTool(tool: BaseTool) {
+		tool.setToolGroup(this.primaryToolGroup);
+		if (tool.isEnabled()) {
+			this.primaryToolGroup.notifyEnabled(tool);
+		}
+
+		this.addTool(tool);
+	}
+
+	public getPrimaryTools(): BaseTool[] {
+		return this.tools.filter(tool => {
+			return tool.getToolGroup() === this.primaryToolGroup;
+		});
+	}
+
+	// Add a tool to the end of this' tool list (the added tool receives events after tools already added to this).
+	// This should be called before creating the app's toolbar.
+	public addTool(tool: BaseTool) {
+		this.tools.push(tool);
+	}
+
+	// Returns true if the event was handled
+	public dispatchInputEvent(event: InputEvt): boolean {
+		let handled = false;
+		if (event.kind === InputEvtType.PointerDownEvt) {
+			for (const tool of this.tools) {
+				if (tool.isEnabled() && tool.onPointerDown(event)) {
+					if (this.activeTool !== tool) {
+						this.activeTool?.onGestureCancel();
+					}
+
+					this.activeTool = tool;
+					handled = true;
+					break;
+				}
+			}
+		} else if (event.kind === InputEvtType.PointerUpEvt) {
+			this.activeTool?.onPointerUp(event);
+			this.activeTool = null;
+			handled = true;
+		} else if (event.kind === InputEvtType.PointerMoveEvt) {
+			if (this.activeTool !== null) {
+				this.activeTool.onPointerMove(event);
+				handled = true;
+			}
+		} else if (event.kind === InputEvtType.GestureCancelEvt) {
+			if (this.activeTool !== null) {
+				this.activeTool.onGestureCancel();
+				this.activeTool = null;
+			}
+		} else {
+			let allCasesHandledGuard: never;
+
+			for (const tool of this.tools) {
+				if (!tool.isEnabled()) {
+					continue;
+				}
+
+				switch (event.kind) {
+				case InputEvtType.KeyPressEvent:
+					handled = tool.onKeyPress(event);
+					break;
+				case InputEvtType.KeyUpEvent:
+					handled = tool.onKeyUp(event);
+					break;
+				case InputEvtType.WheelEvt:
+					handled = tool.onWheel(event);
+					break;
+				case InputEvtType.CopyEvent:
+					handled = tool.onCopy(event);
+					break;
+				case InputEvtType.PasteEvent:
+					handled = tool.onPaste(event);
+					break;
+				default:
+					allCasesHandledGuard = event;
+					return allCasesHandledGuard;
+				}
+
+				if (handled) {
+					break;
+				}
+			}
+		}
+
+		return handled;
+	}
+
+	public getMatchingTools<Type extends BaseTool>(type: new (...args: any[])=>Type): Type[] {
+		return this.tools.filter(tool => tool instanceof type) as Type[];
+	}
+}
+

package/src/tools/ToolEnabledGroup.ts

@@ -0,0 +1,14 @@
+import BaseTool from './BaseTool';
+
+// Connects a group of tools -- at most one tool in the group can be enabled.
+export default class ToolEnabledGroup {
+	private activeTool: BaseTool|null;
+	public constructor() { }
+
+	public notifyEnabled(tool: BaseTool) {
+		if (tool !== this.activeTool) {
+			this.activeTool?.setEnabled(false);
+			this.activeTool = tool;
+		}
+	}
+}

package/src/tools/ToolSwitcherShortcut.ts

@@ -0,0 +1,39 @@
+import Editor from '../Editor';
+import { KeyPressEvent } from '../types';
+import BaseTool from './BaseTool';
+
+/**
+ * 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 override onKeyPress({ key }: KeyPressEvent): boolean {
+		const toolController = this.editor.toolController;
+		const primaryTools = toolController.getPrimaryTools();
+
+		// Map keys 0-9 to primary tools.
+		const keyMatch = /^[0-9]$/.exec(key);
+
+		let targetTool: BaseTool|undefined;
+		if (keyMatch) {
+			const targetIdx = parseInt(keyMatch[0], 10) - 1;
+			targetTool = primaryTools[targetIdx];
+		}
+
+		if (targetTool) {
+			targetTool.setEnabled(true);
+			return true;
+		}
+
+		return false;
+	}
+}

package/src/tools/ToolbarShortcutHandler.ts

@@ -0,0 +1,39 @@
+// Allows the toolbar to register keyboard events.
+// @packageDocumentation
+
+import Editor from '../Editor';
+import { KeyPressEvent } from '../types';
+import BaseTool from './BaseTool';
+
+// Returns true if the event was handled, false otherwise.
+type KeyPressListener = (event: KeyPressEvent)=>boolean;
+
+export default class ToolbarShortcutHandler extends BaseTool {
+	private listeners: Set<KeyPressListener> = new Set([]);
+	public constructor(editor: Editor) {
+		super(editor.notifier, editor.localization.changeTool);
+	}
+
+	public registerListener(listener: KeyPressListener) {
+		this.listeners.add(listener);
+	}
+
+	public removeListener(listener: KeyPressListener) {
+		this.listeners.delete(listener);
+	}
+
+	public override onKeyPress(event: KeyPressEvent): boolean {
+		// TypeScript seems to automatically convert for of loops into for(init;check;update)
+		// loops (even with target set to es6). Thus, we cannot iterate directly through the
+		// set here.
+		// See https://stackoverflow.com/q/48886500
+		const listeners = Array.from(this.listeners.values());
+		for (const listener of listeners) {
+			if (listener(event)) {
+				return true;
+			}
+		}
+
+		return false;
+	}
+}

package/src/tools/UndoRedoShortcut.test.ts

@@ -0,0 +1,56 @@
+/* @jest-environment jsdom */
+
+import Color4 from '../Color4';
+import Stroke from '../components/Stroke';
+import EditorImage from '../EditorImage';
+import Path from '../math/shapes/Path';
+import createEditor from '../testing/createEditor';
+import { InputEvtType } from '../types';
+
+describe('UndoRedoShortcut', () => {
+	const testStroke = new Stroke([Path.fromString('M0,0L10,10').toRenderable({ fill: Color4.red })]);
+	const addTestStrokeCommand = EditorImage.addElement(testStroke);
+
+	it('ctrl+z should undo', () => {
+		const editor = createEditor();
+		editor.dispatch(addTestStrokeCommand);
+		expect(editor.history.undoStackSize).toBe(1);
+
+		editor.toolController.dispatchInputEvent({
+			kind: InputEvtType.KeyPressEvent,
+			ctrlKey: true,
+			altKey: false,
+			key: 'z',
+		});
+
+		expect(editor.history.undoStackSize).toBe(0);
+		expect(editor.history.redoStackSize).toBe(1);
+	});
+
+	it('ctrl+shift+Z should re-do', () => {
+		const editor = createEditor();
+		editor.dispatch(addTestStrokeCommand);
+		editor.dispatch(addTestStrokeCommand);
+		expect(editor.history.undoStackSize).toBe(2);
+
+		editor.toolController.dispatchInputEvent({
+			kind: InputEvtType.KeyPressEvent,
+			ctrlKey: true,
+			altKey: false,
+			key: 'z',
+		});
+
+		expect(editor.history.undoStackSize).toBe(1);
+		expect(editor.history.redoStackSize).toBe(1);
+
+		editor.toolController.dispatchInputEvent({
+			kind: InputEvtType.KeyPressEvent,
+			ctrlKey: true,
+			altKey: false,
+			key: 'Z',
+		});
+
+		expect(editor.history.undoStackSize).toBe(2);
+		expect(editor.history.redoStackSize).toBe(0);
+	});
+});

package/src/tools/UndoRedoShortcut.ts

@@ -0,0 +1,24 @@
+import Editor from '../Editor';
+import { KeyPressEvent } from '../types';
+import BaseTool from './BaseTool';
+import { redoKeyboardShortcutId, undoKeyboardShortcutId } from './keybindings';
+
+// 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);
+	}
+
+	// @internal
+	public override onKeyPress(event: KeyPressEvent): boolean {
+		if (this.editor.shortcuts.matchesShortcut(undoKeyboardShortcutId, event)) {
+			this.editor.history.undo();
+			return true;
+		} else if (this.editor.shortcuts.matchesShortcut(redoKeyboardShortcutId, event)) {
+			this.editor.history.redo();
+			return true;
+		}
+
+		return false;
+	}
+}

package/src/tools/keybindings.ts

@@ -0,0 +1,85 @@
+import KeyboardShortcutManager from '../shortcuts/KeyboardShortcutManager';
+
+// This file contains user-overridable tool-realted keybindings.
+
+// Undo/redo
+export const undoKeyboardShortcutId = 'jsdraw.tools.undo';
+export const redoKeyboardShortcutId = 'jsdaw.tools.redo';
+
+KeyboardShortcutManager.registerDefaultKeyboardShortcut(
+	undoKeyboardShortcutId, [ 'ctrlOrMeta+z' ], 'Undo'
+);
+KeyboardShortcutManager.registerDefaultKeyboardShortcut(
+	redoKeyboardShortcutId, [ 'ctrlOrMeta+Z', 'ctrlOrMeta+Shift+z' ], 'Redo'
+);
+
+// Pen/eraser/selection keybindings
+export const increaseSizeKeyboardShortcutId = 'jsdraw.tools.increaseSize';
+KeyboardShortcutManager.registerDefaultKeyboardShortcut(
+	increaseSizeKeyboardShortcutId, [ '+', '=' ], 'Increase pen/eraser size'
+);
+export const decreaseSizeKeyboardShortcutId = 'jsdraw.tools.decreaseSize';
+KeyboardShortcutManager.registerDefaultKeyboardShortcut(
+	decreaseSizeKeyboardShortcutId, [ '-', '_' ], 'Decrease pen/eraser size'
+);
+export const snapToGridKeyboardShortcutId = 'jsdraw.tools.snapToGrid';
+KeyboardShortcutManager.registerDefaultKeyboardShortcut(
+	snapToGridKeyboardShortcutId, [ 'control', 'meta' ], 'Snap to grid (press and hold)'
+);
+export const lineLockKeyboardShortcutId = 'jsdraw.tools.lockToLine';
+KeyboardShortcutManager.registerDefaultKeyboardShortcut(
+	lineLockKeyboardShortcutId, [ 'shift' ], 'Snap to XY axes (press and hold)'
+);
+
+// Find tool
+export const toggleFindVisibleShortcutId = 'js-draw.tools.FindTool.toggleVisible';
+KeyboardShortcutManager.registerDefaultKeyboardShortcut(
+	toggleFindVisibleShortcutId,
+	[ 'ctrlOrMeta+f' ],
+	'Shows/hides the find tool'
+);
+
+// Pan/zoom
+export const moveLeftKeyboardShortcutId = 'jsdraw.tools.PanZoom.moveLeft';
+KeyboardShortcutManager.registerDefaultKeyboardShortcut(
+	moveLeftKeyboardShortcutId, [ 'ArrowLeft', 'h', 'a' ], 'Pan left'
+);
+export const moveRightKeyboardShortcutId = 'jsdraw.tools.PanZoom.moveRight';
+KeyboardShortcutManager.registerDefaultKeyboardShortcut(
+	moveRightKeyboardShortcutId, [ 'ArrowRight', 'l', 'd' ], 'Pan right'
+);
+export const moveUpKeyboardShortcutId = 'jsdraw.tools.PanZoom.moveUp';
+KeyboardShortcutManager.registerDefaultKeyboardShortcut(
+	moveUpKeyboardShortcutId, [ 'ArrowUp', 'k', 'q' ], 'Pan up'
+);
+export const moveDownKeyboardShortcutId = 'jsdraw.tools.PanZoom.moveDown';
+KeyboardShortcutManager.registerDefaultKeyboardShortcut(
+	moveDownKeyboardShortcutId, [ 'ArrowDown', 'j', 'e' ], 'Pan down'
+);
+export const rotateClockwiseKeyboardShortcutId = 'jsdraw.tools.PanZoom.rotateViewClockwise';
+KeyboardShortcutManager.registerDefaultKeyboardShortcut(
+	rotateClockwiseKeyboardShortcutId, [ 'R' ], 'Rotate viewport clockwise'
+);
+export const rotateCounterClockwiseKeyboardShortcutId = 'jsdraw.tools.PanZoom.rotateViewCounterClockwise';
+KeyboardShortcutManager.registerDefaultKeyboardShortcut(
+	rotateCounterClockwiseKeyboardShortcutId, [ 'r' ], 'Rotate viewport counter-clockwise'
+);
+export const zoomInKeyboardShortcutId = 'jsdraw.tools.PanZoom.zoomIn';
+KeyboardShortcutManager.registerDefaultKeyboardShortcut(
+	zoomInKeyboardShortcutId, [ 'w' ], 'Zoom in'
+);
+export const zoomOutKeyboardShortcutId = 'jsdraw.tools.PanZoom.zoomOut';
+KeyboardShortcutManager.registerDefaultKeyboardShortcut(
+	zoomOutKeyboardShortcutId, [ 's' ], 'Zoom out'
+);
+
+// Selection
+export const selectAllKeyboardShortcut = 'jsdraw.tools.SelectionTool.selectAll';
+KeyboardShortcutManager.registerDefaultKeyboardShortcut(
+	selectAllKeyboardShortcut, [ 'ctrlOrMeta+a' ], 'Select all'
+);
+export const duplicateSelectionShortcut = 'jsdraw.tools.SelectionTool.duplicateSelection';
+KeyboardShortcutManager.registerDefaultKeyboardShortcut(
+	duplicateSelectionShortcut, [ 'ctrlOrMeta+d' ], 'Duplicate selection'
+);
+

package/src/tools/lib.ts

@@ -0,0 +1,22 @@
+
+/**
+ * @packageDocumentation
+ */
+
+export { default as BaseTool } from './BaseTool';
+export { default as ToolController } from './ToolController';
+export { default as ToolEnabledGroup } from './ToolEnabledGroup';
+
+export { default as UndoRedoShortcut } from './UndoRedoShortcut';
+export { default as ToolSwitcherShortcut } from './ToolSwitcherShortcut';
+export { default as PanZoomTool, PanZoomMode } from './PanZoom';
+
+export { default as PenTool, PenStyle } from './Pen';
+export { default as TextTool } from './TextTool';
+export { default as SelectionTool } from './SelectionTool/SelectionTool';
+export { default as SelectAllShortcutHandler } from './SelectionTool/SelectAllShortcutHandler';
+export { default as EraserTool } from './Eraser';
+export { default as PasteHandler } from './PasteHandler';
+export { default as SoundUITool } from './SoundUITool';
+
+export { default as ToolbarShortcutHandler } from './ToolbarShortcutHandler';

package/src/tools/localization.ts

@@ -0,0 +1,74 @@
+
+export interface ToolLocalization {
+	keyboardPanZoom: string;
+	penTool: (penId: number)=>string;
+	selectionTool: string;
+	selectAllTool: string;
+	eraserTool: string;
+	touchPanTool: string;
+	twoFingerPanZoomTool: string;
+	undoRedoTool: string;
+	pipetteTool: string;
+	rightClickDragPanTool: string;
+
+	textTool: string;
+	enterTextToInsert: string;
+	changeTool: string;
+	pasteHandler: string;
+
+	soundExplorer: string;
+	disableAccessibilityExploreTool: string;
+	enableAccessibilityExploreTool: string;
+
+	findLabel: string;
+	toNextMatch: string;
+	closeFindDialog: string;
+	findDialogShown: string;
+	findDialogHidden: string;
+	focusedFoundText: (currentMatchNumber: number, totalMatches: number)=> string;
+
+	anyDevicePanning: string;
+
+	copied: (count: number, description: string) => string;
+	pasted: (count: number, description: string) => string;
+
+	toolEnabledAnnouncement: (toolName: string) => string;
+	toolDisabledAnnouncement: (toolName: string) => string;
+}
+
+export const defaultToolLocalization: ToolLocalization = {
+	penTool: (penId) => `Pen ${penId}`,
+	selectionTool: 'Selection',
+	selectAllTool: 'Select all shortcut',
+	eraserTool: 'Eraser',
+	touchPanTool: 'Touch panning',
+	twoFingerPanZoomTool: 'Panning and zooming',
+	undoRedoTool: 'Undo/Redo',
+	rightClickDragPanTool: 'Right-click drag',
+	pipetteTool: 'Pick color from screen',
+	keyboardPanZoom: 'Keyboard pan/zoom shortcuts',
+
+	textTool: 'Text',
+	enterTextToInsert: 'Text to insert',
+	changeTool: 'Change tool',
+	pasteHandler: 'Copy paste handler',
+
+	soundExplorer: 'Sound-based image exploration',
+	disableAccessibilityExploreTool: 'Disable sound-based exploration',
+	enableAccessibilityExploreTool: 'Enable sound-based exploration',
+
+	findLabel: 'Find',
+	toNextMatch: 'Next',
+	closeFindDialog: 'Close',
+	findDialogShown: 'Find dialog shown',
+	findDialogHidden: 'Find dialog hidden',
+	focusedFoundText: (matchIdx: number, totalMatches: number) => `Viewing match ${matchIdx} of ${totalMatches}`,
+
+	anyDevicePanning: 'Any device panning',
+
+	copied: (count: number, description: string) => `Copied ${count} ${description}`,
+	pasted: (count: number, description: string) => `Pasted ${count} ${description}`,
+
+	toolEnabledAnnouncement: (toolName) => `${toolName} enabled`,
+	toolDisabledAnnouncement: (toolName) => `${toolName} disabled`,
+};