js-draw 0.23.0 → 0.24.0

package/src/shortcuts/KeyBinding.ts

@@ -0,0 +1,218 @@
+
+export interface KeyCombination {
+	/** A key (e.g. `a`, `b`, `control`). */
+	readonly key: string;
+
+	/**
+	 * Whether the shift key must be pressed to trigger the shortcut.
+	 */
+	readonly shiftKey: boolean|undefined;
+
+	/** Whether the control key must be pressed to trigger the shortcut */
+	readonly ctrlKey: boolean;
+
+	/** Whether the alt key must be pressed to trigger the shortcut */
+	readonly altKey: boolean;
+
+	/** Whether the meta key must be pressed to trigger the shortcut */
+	readonly metaKey: boolean;
+
+	/** True if this shortcut/key combination applies for either control or meta. */
+	readonly controlOrMeta: boolean;
+}
+
+/** Represents a key combination that can trigger a keyboard shortcut. */
+export default class KeyBinding implements KeyCombination {
+	/** @inheritdoc */
+	public readonly key: string;
+
+	/**
+	 * If undefined, the state of the shift key is ignored.
+	 */
+	public readonly shiftKey: boolean|undefined;
+
+	/** @inheritdoc */
+	public readonly ctrlKey: boolean;
+
+	/** @inheritdoc */
+	public readonly altKey: boolean;
+
+	/** @inheritdoc */
+	public readonly metaKey: boolean;
+
+	/** @inheritdoc */
+	public readonly controlOrMeta: boolean;
+
+	public constructor(trigger: KeyCombination) {
+		this.key = trigger.key;
+		this.shiftKey = trigger.shiftKey;
+		this.ctrlKey = trigger.ctrlKey;
+		this.altKey = trigger.altKey;
+		this.metaKey = trigger.metaKey;
+		this.controlOrMeta = trigger.controlOrMeta;
+	}
+
+	/** Returns true if and only if `keyEvent` should trigger this shortcut. */
+	public matchesEvent(keyEvent: Partial<KeyCombination>) {
+		const lowercaseKey = keyEvent.key?.toLowerCase();
+
+		// Determine whether the input is an upper case letter or not.
+		const isUpperCaseKey = keyEvent.key?.toUpperCase() === keyEvent.key
+			&& keyEvent.key?.toLowerCase() !== keyEvent.key
+			&& keyEvent.key?.length === 1;
+		const isLowercaseKey = keyEvent.key?.toLowerCase() !== keyEvent.key
+			&& !isUpperCaseKey
+			&& keyEvent.key?.length === 1;
+
+		const ctrlKey = (keyEvent.ctrlKey ?? false) || lowercaseKey === 'control';
+		const altKey = (keyEvent.altKey ?? false) || lowercaseKey === 'alt';
+		const metaKey = (keyEvent.metaKey ?? false) || lowercaseKey === 'meta';
+		const shiftKey =
+				(keyEvent.shiftKey ?? isUpperCaseKey) || lowercaseKey === 'shift';
+		const keyEventHasCtrlOrMeta =
+				keyEvent.controlOrMeta || keyEvent.ctrlKey || keyEvent.metaKey || false;
+
+		// Different keys entirely? They don't match.
+		if (this.key.toLowerCase() !== lowercaseKey) {
+			return false;
+		}
+
+		// If a case where the ASCII case of the given key might matter,
+		// compare.
+		if ((isUpperCaseKey || isLowercaseKey) && this.key !== keyEvent.key) {
+			// this.shiftKey may be interpreted as allowing this shortcut to be uppercased.
+			// If so, try making this.key uppercase and matching the shortcut.
+			const uppercaseKeyMatches = this.shiftKey === true && this.key.toUpperCase() === keyEvent.key;
+			if (!uppercaseKeyMatches) {
+				return false;
+			}
+		}
+
+		const shortcutControlOrMeta = this.controlOrMeta;
+		// Match ctrl/meta if the shortcut doesn't have controlOrMeta specified
+		// (controlOrMeta should match either).
+		const ctrlAndMetaMatches =
+			ctrlKey === this.ctrlKey
+			&& metaKey === this.metaKey
+			&& !shortcutControlOrMeta;
+
+		const matches =
+			(ctrlAndMetaMatches || (shortcutControlOrMeta && keyEventHasCtrlOrMeta))
+			&& altKey === this.altKey
+			&& (shiftKey === this.shiftKey || this.shiftKey === undefined);
+		return matches;
+	}
+
+	/**
+	 * Returns a string representation of this shortcut in the same format accepted by
+	 * {@link fromString}.
+	 */
+	public toString() {
+		const result = [];
+
+		if (this.ctrlKey && this.key !== 'control') {
+			result.push('Ctrl');
+		}
+		if (this.controlOrMeta) {
+			result.push('CtrlOrMeta');
+		}
+		if (this.altKey && this.key !== 'alt') {
+			result.push('Alt');
+		}
+		if (this.metaKey && this.key !== 'meta') {
+			result.push('Meta');
+		}
+		if (this.shiftKey && this.key !== 'shift') {
+			result.push('Shift');
+		}
+		result.push(this.key);
+
+		return result.join('+');
+	}
+
+	/**
+	 * Accepts a string in the form `modifier1+modifier2+...+key` (e.g. `Ctrl+Shift+a`)
+	 * and returns the corresponding `KeyboardShortcut`.
+	 */
+	public static fromString(shortcutStr: string): KeyBinding {
+		const hasNoModifiers = shortcutStr.search(/[-+]/) === -1 || shortcutStr.length === 1;
+		if (hasNoModifiers) {
+			const lowercaseKey = shortcutStr.toLowerCase();
+
+			// undefined: don't require or not require shift.
+			let shiftKey: boolean|undefined = undefined;
+
+			// shiftKey should always be true if the key is 'shift'
+			if (lowercaseKey === 'shift') {
+				shiftKey = true;
+			}
+
+			return new KeyBinding({
+				key: shortcutStr,
+				shiftKey: shiftKey,
+				ctrlKey: lowercaseKey === 'control' || lowercaseKey === 'ctrl',
+				altKey: lowercaseKey === 'alt',
+				metaKey: lowercaseKey === 'meta',
+				controlOrMeta: lowercaseKey === 'control or meta' || lowercaseKey === 'ctrlormeta',
+			});
+		}
+
+		const keyModifiersExp = /^(.*[-+])?(.+)$/g;
+		const match = keyModifiersExp.exec(shortcutStr);
+
+		if (!match) {
+			throw new Error(`Invalid shortcut expression, ${shortcutStr}!`);
+		}
+
+		const key = match[2];
+		const modifiers = (match[1] ?? '').split(/[-+]/);
+
+		let shiftKey = undefined;
+		let ctrlKey = false;
+		let altKey = false;
+		let metaKey = false;
+		let controlOrMeta = false;
+
+		for (const modifier of modifiers) {
+			if (modifier === '') {
+				continue;
+			}
+
+			switch (modifier.toLowerCase()) {
+			case 'shift':
+				shiftKey = true;
+				break;
+			case 'noshift':
+				shiftKey = false;
+				break;
+			case 'ctrl':
+			case 'control':
+				ctrlKey = true;
+				break;
+			case 'meta':
+				metaKey = true;
+				break;
+			case 'ctrlormeta':
+			case 'ctrl or meta':
+			case 'controlormeta':
+				controlOrMeta = true;
+				break;
+			case 'alt':
+				altKey = true;
+				break;
+			default:
+				throw new Error(`Unknown modifier: "${modifier}" in shortcut ${shortcutStr}.`);
+			}
+		}
+
+		const shortcut = new KeyBinding({
+			key,
+			shiftKey,
+			ctrlKey,
+			altKey,
+			metaKey,
+			controlOrMeta,
+		});
+		return shortcut;
+	}
+}

package/src/shortcuts/KeyboardShortcutManager.test.ts

@@ -0,0 +1,95 @@
+import { undoKeyboardShortcutId } from '../tools/keybindings';
+import KeyBinding from './KeyBinding';
+import KeyboardShortcutManager from './KeyboardShortcutManager';
+
+describe('KeyboardShortcutManager', () => {
+	it('should contain default shortcuts for undo', () => {
+		const defaultUndoShortcutKeybinds =
+				KeyboardShortcutManager.getShortcutDefaultKeybindings(undoKeyboardShortcutId);
+		expect(defaultUndoShortcutKeybinds.length).toBeGreaterThanOrEqual(1);
+		expect(defaultUndoShortcutKeybinds.some(shortcut => {
+			return shortcut.key === 'z' && shortcut.controlOrMeta;
+		})).toBe(true);
+	});
+
+	it('should be possible to override keyboard shortcuts', () => {
+		const testNewId = 'someIdThatDoesNowExist';
+		KeyboardShortcutManager.registerDefaultKeyboardShortcut(
+			testNewId,
+			[ KeyBinding.fromString('ctrl-1'), KeyBinding.fromString('-') ],
+			'Some description'
+		);
+
+		const shortcutManager = new KeyboardShortcutManager({
+			someIdThatDoesNotExist: [
+				KeyBinding.fromString('ctrl-shift-a'),
+				KeyBinding.fromString('ctrl-a'),
+			],
+		});
+
+		// Should work before overriding
+		expect(
+			shortcutManager.matchesShortcut(testNewId, KeyBinding.fromString('ctrl-1'))
+		).toBe(true);
+		expect(
+			shortcutManager.matchesShortcut(testNewId, KeyBinding.fromString('-'))
+		).toBe(true);
+		expect(
+			shortcutManager.matchesShortcut(testNewId, KeyBinding.fromString('ctrl-b'))
+		).toBe(false);
+		expect(
+			shortcutManager.matchesShortcut(testNewId, KeyBinding.fromString('ctrl-0'))
+		).toBe(false);
+		expect(
+			shortcutManager.matchesShortcut(testNewId, KeyBinding.fromString('1'))
+		).toBe(false);
+
+		shortcutManager.overrideShortcut(testNewId, [
+			KeyBinding.fromString('ctrl-b'),
+		]);
+
+
+		// Should work after overriding
+		expect(
+			shortcutManager.matchesShortcut(testNewId, KeyBinding.fromString('ctrl-1'))
+		).toBe(false);
+		expect(
+			shortcutManager.matchesShortcut(testNewId, KeyBinding.fromString('-'))
+		).toBe(false);
+		expect(
+			shortcutManager.matchesShortcut(testNewId, KeyBinding.fromString('ctrl-b'))
+		).toBe(true);
+		expect(
+			shortcutManager.matchesShortcut(testNewId, KeyBinding.fromString('ctrl-0'))
+		).toBe(false);
+		expect(
+			shortcutManager.matchesShortcut(testNewId, KeyBinding.fromString('1'))
+		).toBe(false);
+	});
+
+	it('should provide localized descriptions of keyboard shortcuts', () => {
+		const testNewId = 'someIdThatDoesNowExist--testingLocalization';
+		const defaultDescription = 'Some description 1';
+		KeyboardShortcutManager.registerDefaultKeyboardShortcut(
+			testNewId,
+			[ KeyBinding.fromString('ctrl-1'), KeyBinding.fromString('-') ],
+			defaultDescription
+		);
+
+		expect(KeyboardShortcutManager.getShortcutDescription(testNewId)).toBe(defaultDescription);
+		expect(
+			KeyboardShortcutManager.getShortcutDescription(testNewId, ['fakeLocale'])
+		).toBe(defaultDescription);
+
+		const spanishDescription = 'Alguna descripción';
+		KeyboardShortcutManager.provideShortcutDescription(
+			testNewId,
+			'es',
+			spanishDescription
+		);
+
+		expect(
+			KeyboardShortcutManager.getShortcutDescription(testNewId, ['es', 'en'])
+		).toBe(spanishDescription);
+	});
+});

package/src/shortcuts/KeyboardShortcutManager.ts

@@ -0,0 +1,163 @@
+import { matchingLocalizationTable } from '../localizations/getLocalizationTable';
+import KeyBinding, { KeyCombination } from './KeyBinding';
+
+type ShortcutDictionary = Record<string, KeyBinding[]>;
+
+// Maps from shortcut IDs to a description of each.
+type ShortcutDescriptionDictionary = Record<string, string>;
+
+/**
+ * Allows adding/changing keyboard shortcuts. This class provides static methods for registering
+ * default shortcuts. An instance of this class must be used to access or change keyboard shortcuts.
+ */
+export default class KeyboardShortcutManager {
+	private static shortcuts: ShortcutDictionary = Object.create(null);
+	private static shortcutDefaultDescriptions: ShortcutDescriptionDictionary
+		= Object.create(null);
+	private static shortcutLocalizedDescriptions: Record<string, ShortcutDescriptionDictionary>
+		= Object.create(null);
+
+	private shortcutOverrides: ShortcutDictionary = Object.create(null);
+
+	/**
+	 * Creates a new `ShortcutManager` with an initial set of shortcut overrides.
+	 *
+	 * @internal
+	 */
+	public constructor(initialOverrides: ShortcutDictionary) {
+		for (const id in initialOverrides) {
+			this.overrideShortcut(id, initialOverrides[id]);
+		}
+	}
+
+	/**
+	 * Override an existing shortcut with a custom set of triggers.
+	 * @internal
+	 */
+	public overrideShortcut(shortcutId: string, overrideWith: KeyBinding[]) {
+		this.shortcutOverrides[shortcutId] = [ ...overrideWith ];
+	}
+
+	/** Returns true if `keyEvent` matches the shortcut with `shortcutId`. @internal */
+	public matchesShortcut(shortcutId: string, keyEvent: Partial<KeyCombination>) {
+		// Get all shortcucts associated with `shortcutId`.
+		let shortcutList = this.shortcutOverrides[shortcutId];
+
+		if (!shortcutList) {
+			if (shortcutId in KeyboardShortcutManager.shortcuts) {
+				shortcutList = KeyboardShortcutManager.shortcuts[shortcutId];
+			} else {
+				throw new Error(`No shortcut with ID ${shortcutId} exists!`);
+			}
+		}
+
+		// return true if keyEvent matches *any* shortcuts in shortcutList
+		for (const shortcut of shortcutList) {
+			if (shortcut.matchesEvent(keyEvent)) {
+				return true;
+			}
+		}
+
+		return false;
+	}
+
+	/**
+	 * Registers a default keyboard shortcut that can be overridden by individual instances
+	 * of `ShortcutManager`. Note that `id` should be a globally unique identifier.
+	 *
+	 * Only the first call to this method for a given `id` has an effect.
+	 *
+	 * @example
+	 * ```ts
+	 * const shortcutId = 'io.github.personalizedrefrigerator.js-draw.select-all';
+	 *
+	 * // Associate two shortcuts with the same ID
+	 * const shortcut1 = KeyboardShortcutManager.keyboardShortcutFromString('ctrlOrMeta+a');
+	 * const shortcut2 = KeyboardShortcutManager.keyboardShortcutFromString('ctrlOrMeta+shift+a');
+	 * KeyboardShortcutManager.registerDefaultKeyboardShortcut(
+	 * 	shortcutId,
+	 * 	[ shortcut1, shortcut2 ],
+	 * 	"Select All",
+	 * );
+	 *
+	 * // Provide a localized description
+	 * KeyboardShortcutManager.provideShortcutDescription(
+	 * 	shotcutId,
+	 * 	'es',
+	 * 	'Seleccionar todo',
+	 * );
+	 * ```
+	 *
+	 * @internal
+	 */
+	public static registerDefaultKeyboardShortcut(
+		id: string,
+		shortcuts: (KeyBinding|string)[],
+		defaultDescription: string,
+	): boolean {
+		if (id in KeyboardShortcutManager.shortcuts) {
+			return false;
+		}
+
+		// Convert the strings to shortcut maps.
+		const shortcutsAsShortcuts = shortcuts.map(shortcut => {
+			if (typeof (shortcut) === 'string') {
+				return KeyBinding.fromString(shortcut);
+			}
+			return shortcut;
+		});
+
+		KeyboardShortcutManager.shortcuts[id] = [ ...shortcutsAsShortcuts ];
+		KeyboardShortcutManager.shortcutDefaultDescriptions[id] = defaultDescription;
+		return true;
+	}
+
+	/** Provides a localized description of a keyboard shortcut. @internal */
+	public static provideShortcutDescription(id: string, locale: string, description: string) {
+		if (!(locale in KeyboardShortcutManager.shortcutLocalizedDescriptions)) {
+			KeyboardShortcutManager.shortcutLocalizedDescriptions[locale] = Object.create(null);
+		}
+
+		KeyboardShortcutManager.shortcutLocalizedDescriptions[locale][id] = description;
+	}
+
+	/**
+	 * Gets all registered keyboard shortcut IDs.
+	 *
+	 * @see {@link getShortcutDescription}
+	 */
+	public static getAllShortcutIds() {
+		const ids = [];
+		for (const id in this.shortcuts) {
+			ids.push(id);
+		}
+		return ids;
+	}
+
+	/**
+	 * Get the default keybindings associated with a keyboard shortcut.
+	 *
+	 * Any keybinding in the resultant list, by default, can trigger the function associated
+	 * with the shortcut.
+	 */
+	public static getShortcutDefaultKeybindings(shortcutId: string): KeyBinding[] {
+		if (!(shortcutId in KeyboardShortcutManager.shortcuts)) {
+			throw new Error(`No shortcut with ID ${shortcutId} exists!`);
+		}
+
+		return KeyboardShortcutManager.shortcuts[shortcutId];
+	}
+
+	/**
+	 * Get a description of a keyboard shortcut.
+	 *
+	 * `localeList`, if given, attempts to
+	 */
+	public static getShortcutDescription(id: string, localeList?: readonly string[]): string|null {
+		const localizationTable = matchingLocalizationTable(
+			localeList ?? [], this.shortcutLocalizedDescriptions, this.shortcutDefaultDescriptions
+		);
+
+		return localizationTable[id] ?? this.shortcutDefaultDescriptions[id] ?? null;
+	}
+}

package/src/shortcuts/lib.ts

@@ -0,0 +1,3 @@
+
+export { default as KeyboardShortcutManager } from './KeyboardShortcutManager';
+export { default as KeyBinding } from './KeyBinding';

package/src/testing/createEditor.ts

@@ -0,0 +1,11 @@
+import { RenderingMode } from '../rendering/Display';
+import Editor from '../Editor';
+
+/** Creates an editor. Should only be used in test files. */
+export default () => {
+	if (jest === undefined) {
+		throw new Error('Files in the testing/ folder should only be used in tests!');
+	}
+
+	return new Editor(document.body, { renderingMode: RenderingMode.DummyRenderer });
+};

package/src/testing/lib.ts

@@ -0,0 +1,3 @@
+
+export { default as sendPenEvent } from './sendPenEvent';
+export { default as sendTouchEvent } from './sendTouchEvent';

package/src/testing/sendPenEvent.ts

@@ -0,0 +1,31 @@
+import Editor from '../Editor';
+import { Point2 } from '../math/Vec2';
+import Pointer from '../Pointer';
+import { InputEvtType } from '../types';
+
+/**
+ * Dispatch a pen event to the currently selected tool.
+ * Intended for unit tests.
+ *
+ * @see {@link sendTouchEvent}
+ */
+const sendPenEvent = (
+	editor: Editor,
+	eventType: InputEvtType.PointerDownEvt|InputEvtType.PointerMoveEvt|InputEvtType.PointerUpEvt,
+	point: Point2,
+
+	allPointers?: Pointer[]
+) => {
+	const mainPointer = Pointer.ofCanvasPoint(
+		point, eventType !== InputEvtType.PointerUpEvt, editor.viewport
+	);
+
+	editor.toolController.dispatchInputEvent({
+		kind: eventType,
+		allPointers: allPointers ?? [
+			mainPointer,
+		],
+		current: mainPointer,
+	});
+};
+export default sendPenEvent;

package/src/testing/sendTouchEvent.ts

@@ -0,0 +1,78 @@
+import Editor from '../Editor';
+import { Vec2 } from '../math/Vec2';
+import Pointer, { PointerDevice } from '../Pointer';
+import { InputEvtType } from '../types';
+
+/**
+ * Dispatch a touch event to the currently selected tool. Intended for unit tests.
+ *
+ * @see {@link sendPenEvent}
+ *
+ * @example
+ * **Simulating a horizontal swipe gesture:**
+ * ```ts
+ * sendTouchEvent(editor, InputEvtType.PointerDownEvt, Vec2.of(0, 0));
+ * for (let i = 1; i <= 10; i++) {
+ *   jest.advanceTimersByTime(10);
+ *   sendTouchEvent(editor, InputEvtType.PointerMoveEvt, Vec2.of(i * 10, 0));
+ * }
+ * ```
+ *
+ * @example
+ * **Simulating a pinch gesture.** This example assumes that you're using [Jest with timer mocks enabled](https://jestjs.io/docs/timer-mocks).
+ * ```ts
+ * let firstPointer = sendTouchEvent(editor, InputEvtType.PointerDownEvt, Vec2.of(0, 0));
+ * let secondPointer = sendTouchEvent(editor, InputEvtType.PointerDownEvt, Vec2.of(100, 0), [ firstPointer ]);
+ *
+ * // Simulate a pinch
+ * const maxIterations = 10;
+ * for (let i = 0; i < maxIterations; i++) {
+ *   // Use the unit testing framework's tool for increasing the current time
+ *   // returned by (new Date()).getTime(), etc.
+ *   jest.advanceTimersByTime(100);
+ *
+ *   const point1 = Vec2.of(-i * 5, 0);
+ *   const point2 = Vec2.of(i * 5 + 100, 0);
+ *
+ *   firstPointer = sendTouchEvent(editor, InputEvtType.PointerMoveEvt, point1, [ secondPointer ]);
+ *   secondPointer = sendTouchEvent(editor, InputEvtType.PointerMoveEvt, point2, [ firstPointer ]);
+ * }
+ * ```
+ */
+const sendTouchEvent = (
+	editor: Editor,
+	eventType: InputEvtType.PointerDownEvt|InputEvtType.PointerMoveEvt|InputEvtType.PointerUpEvt,
+	screenPos: Vec2,
+	allOtherPointers?: Pointer[]
+) => {
+	const canvasPos = editor.viewport.screenToCanvas(screenPos);
+
+	let ptrId = 0;
+	let maxPtrId = 0;
+
+	// Get a unique ID for the main pointer
+	// (try to use id=0, but don't use it if it's already in use).
+	for (const pointer of allOtherPointers ?? []) {
+		maxPtrId = Math.max(pointer.id, maxPtrId);
+		if (pointer.id === ptrId) {
+			ptrId = maxPtrId + 1;
+		}
+	}
+
+	const mainPointer = Pointer.ofCanvasPoint(
+		canvasPos, eventType !== InputEvtType.PointerUpEvt, editor.viewport, ptrId, PointerDevice.Touch
+	);
+
+	editor.toolController.dispatchInputEvent({
+		kind: eventType,
+		allPointers: [
+			...(allOtherPointers ?? []),
+			mainPointer,
+		],
+		current: mainPointer,
+	});
+
+	return mainPointer;
+};
+
+export default sendTouchEvent;