js-draw 0.25.0 → 1.0.0

package/src/shortcuts/KeyBinding.ts

@@ -1,218 +0,0 @@
-
-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

@@ -1,95 +0,0 @@
-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

@@ -1,163 +0,0 @@
-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

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

package/src/testing/createEditor.ts

@@ -1,11 +0,0 @@
-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/getUniquePointerId.ts

@@ -1,18 +0,0 @@
-import Pointer from '../Pointer';
-
-/** Returns the smallest ID not used by the pointers in the given list. */
-const getUniquePointerId = (pointers: Pointer[]) => {
-	let ptrId = 0;
-
-	const pointerIds = pointers.map(ptr => ptr.id);
-	pointerIds.sort();
-	for (const pointerId of pointerIds) {
-		if (ptrId === pointerId) {
-			ptrId = pointerId + 1;
-		}
-	}
-
-	return ptrId;
-};
-
-export default getUniquePointerId;

package/src/testing/lib.ts

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

package/src/testing/sendPenEvent.ts

@@ -1,36 +0,0 @@
-import Editor from '../Editor';
-import { Point2 } from '../math/Vec2';
-import Pointer from '../Pointer';
-import { InputEvtType } from '../types';
-import getUniquePointerId from './getUniquePointerId';
-
-/**
- * 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 id = getUniquePointerId(allPointers ?? []);
-
-	const mainPointer = Pointer.ofCanvasPoint(
-		point, eventType !== InputEvtType.PointerUpEvt, editor.viewport, id
-	);
-
-	editor.toolController.dispatchInputEvent({
-		kind: eventType,
-		allPointers: allPointers ?? [
-			mainPointer,
-		],
-		current: mainPointer,
-	});
-
-	return mainPointer;
-};
-export default sendPenEvent;

package/src/testing/sendTouchEvent.ts

@@ -1,71 +0,0 @@
-import Editor from '../Editor';
-import { Vec2 } from '../math/Vec2';
-import Pointer, { PointerDevice } from '../Pointer';
-import { InputEvtType } from '../types';
-import getUniquePointerId from './getUniquePointerId';
-
-/**
- * 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);
-
-	// Get a unique ID for the main pointer
-	// (try to use id=0, but don't use it if it's already in use).
-	const ptrId = getUniquePointerId(allOtherPointers ?? []);
-
-	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;