js-draw 0.23.1 → 0.24.0

package/src/UndoRedoHistory.ts

@@ -0,0 +1,102 @@
+import Editor from './Editor';
+import Command from './commands/Command';
+import { EditorEventType, UndoEventType } from './types';
+
+type AnnounceRedoCallback = (command: Command)=>void;
+type AnnounceUndoCallback = (command: Command)=>void;
+
+class UndoRedoHistory {
+	#undoStack: Command[];
+	#redoStack: Command[];
+
+	private readonly maxUndoRedoStackSize: number = 700;
+
+	// @internal
+	public constructor(
+		private readonly editor: Editor,
+		private announceRedoCallback: AnnounceRedoCallback,
+		private announceUndoCallback: AnnounceUndoCallback,
+	) {
+		this.#undoStack = [];
+		this.#redoStack = [];
+	}
+
+	private fireUpdateEvent(
+		stackUpdateType: UndoEventType, triggeringCommand: Command
+	) {
+		this.editor.notifier.dispatch(EditorEventType.UndoRedoStackUpdated, {
+			kind: EditorEventType.UndoRedoStackUpdated,
+			undoStackSize: this.#undoStack.length,
+			redoStackSize: this.#redoStack.length,
+
+			command: triggeringCommand,
+			stackUpdateType,
+		});
+	}
+
+	// Adds the given command to this and applies it to the editor.
+	public push(command: Command, apply: boolean = true) {
+		if (apply) {
+			command.apply(this.editor);
+		}
+		this.#undoStack.push(command);
+
+		for (const elem of this.#redoStack) {
+			elem.onDrop(this.editor);
+		}
+		this.#redoStack = [];
+
+		if (this.#undoStack.length > this.maxUndoRedoStackSize) {
+			const removeAtOnceCount = Math.ceil(this.maxUndoRedoStackSize / 100);
+			const removedElements = this.#undoStack.splice(0, removeAtOnceCount);
+			removedElements.forEach(elem => elem.onDrop(this.editor));
+		}
+
+		this.fireUpdateEvent(UndoEventType.CommandDone, command);
+		this.editor.notifier.dispatch(EditorEventType.CommandDone, {
+			kind: EditorEventType.CommandDone,
+			command,
+		});
+	}
+
+	// Remove the last command from this' undo stack and apply it.
+	public undo() {
+		const command = this.#undoStack.pop();
+		if (command) {
+			this.#redoStack.push(command);
+			command.unapply(this.editor);
+			this.announceUndoCallback(command);
+
+			this.fireUpdateEvent(UndoEventType.CommandUndone, command);
+			this.editor.notifier.dispatch(EditorEventType.CommandUndone, {
+				kind: EditorEventType.CommandUndone,
+				command,
+			});
+		}
+	}
+
+	public redo() {
+		const command = this.#redoStack.pop();
+		if (command) {
+			this.#undoStack.push(command);
+			command.apply(this.editor);
+			this.announceRedoCallback(command);
+
+			this.fireUpdateEvent(UndoEventType.CommandRedone, command);
+			this.editor.notifier.dispatch(EditorEventType.CommandDone, {
+				kind: EditorEventType.CommandDone,
+				command,
+			});
+		}
+	}
+
+	public get undoStackSize(): number {
+		return this.#undoStack.length;
+	}
+
+	public get redoStackSize(): number {
+		return this.#redoStack.length;
+	}
+}
+
+export default UndoRedoHistory;

package/src/Viewport.ts

@@ -0,0 +1,325 @@
+import Command from './commands/Command';
+import { CommandLocalization } from './commands/localization';
+import Editor from './Editor';
+import Mat33 from './math/Mat33';
+import Rect2 from './math/shapes/Rect2';
+import { Point2, Vec2 } from './math/Vec2';
+import Vec3 from './math/Vec3';
+import { StrokeDataPoint } from './types';
+
+// Returns the base type of some type of point/number
+type PointDataType<T extends Point2|StrokeDataPoint|number> = T extends Point2 ? Point2 : number;
+
+export abstract class ViewportTransform extends Command {
+	public abstract readonly transform: Mat33;
+}
+
+type TransformChangeCallback = (oldTransform: Mat33, newTransform: Mat33)=> void;
+
+export class Viewport {
+	// Command that translates/scales the viewport.
+	private static ViewportTransform = class extends ViewportTransform {
+		readonly #inverseTransform: Mat33;
+
+		public constructor(public readonly transform: Mat33) {
+			super();
+			this.#inverseTransform = transform.inverse();
+		}
+
+		public apply(editor: Editor) {
+			const viewport = editor.viewport;
+			viewport.resetTransform(viewport.transform.rightMul(this.transform));
+			editor.queueRerender();
+		}
+
+		public unapply(editor: Editor) {
+			const viewport = editor.viewport;
+			viewport.resetTransform(viewport.transform.rightMul(this.#inverseTransform));
+			editor.queueRerender();
+		}
+
+		public description(editor: Editor, localizationTable: CommandLocalization): string {
+			const result: string[] = [];
+
+			// Describe the transformation's affect on the viewport (note that transformation transforms
+			// the **elements** within the viewport). Assumes the transformation only does rotation/scale/translation.
+			const origVec = editor.viewport.visibleRect.center;
+			const linearTransformedVec = this.transform.transformVec3(Vec2.unitX);
+			const affineTransformedVec = this.transform.transformVec2(origVec);
+
+			const scale = linearTransformedVec.magnitude();
+			const rotation = 180 / Math.PI * linearTransformedVec.angle();
+			const translation = affineTransformedVec.minus(origVec);
+
+			if (scale > 1.2) {
+				result.push(localizationTable.zoomedIn);
+			} else if (scale < 0.8) {
+				result.push(localizationTable.zoomedOut);
+			}
+
+			if (Math.floor(Math.abs(rotation)) > 0) {
+				result.push(localizationTable.rotatedBy(Math.round(rotation)));
+			}
+
+			const minTranslation = 1e-4;
+			if (translation.x > minTranslation) {
+				result.push(localizationTable.movedLeft);
+			} else if (translation.x < -minTranslation) {
+				result.push(localizationTable.movedRight);
+			}
+
+			if (translation.y < -minTranslation) {
+				result.push(localizationTable.movedDown);
+			} else if (translation.y > minTranslation) {
+				result.push(localizationTable.movedUp);
+			}
+
+			return result.join('; ');
+		}
+	};
+
+	private transform: Mat33;
+	private inverseTransform: Mat33;
+	private screenRect: Rect2;
+
+	// @internal
+	public constructor(private onTransformChangeCallback: TransformChangeCallback) {
+		this.resetTransform(Mat33.identity);
+		this.screenRect = Rect2.empty;
+	}
+
+	/**
+	 * @returns a temporary copy of `this` that does not notify when modified. This is
+	 * useful when rendering with a temporarily different viewport.
+	 */
+	public getTemporaryClone(): Viewport {
+		const result = new Viewport(() => {});
+		result.transform = this.transform;
+		result.inverseTransform = this.inverseTransform;
+		result.screenRect = this.screenRect;
+
+		return result;
+	}
+
+	// @internal
+	public updateScreenSize(screenSize: Vec2) {
+		this.screenRect = this.screenRect.resizedTo(screenSize);
+	}
+
+	/** Get the screen's visible region transformed into canvas space. */
+	public get visibleRect(): Rect2 {
+		return this.screenRect.transformedBoundingBox(this.inverseTransform);
+	}
+
+	/** @returns the given point, but in canvas coordinates */
+	public screenToCanvas(screenPoint: Point2): Point2 {
+		return this.inverseTransform.transformVec2(screenPoint);
+	}
+
+	/** @returns the given point transformed into screen coordinates. */
+	public canvasToScreen(canvasPoint: Point2): Point2 {
+		return this.transform.transformVec2(canvasPoint);
+	}
+
+	/** @returns a command that transforms the canvas by `transform`. */
+	public static transformBy(transform: Mat33): ViewportTransform {
+		return new Viewport.ViewportTransform(transform);
+	}
+
+	/**
+	 * Updates the transformation directly. Using `transformBy` is preferred.
+	 * @param newTransform - should map from canvas coordinates to screen coordinates.
+	 */
+	public resetTransform(newTransform: Mat33 = Mat33.identity) {
+		const oldTransform = this.transform;
+		this.transform = newTransform;
+		this.inverseTransform = newTransform.inverse();
+		this.onTransformChangeCallback?.(oldTransform, newTransform);
+	}
+
+	public get screenToCanvasTransform(): Mat33 {
+		return this.inverseTransform;
+	}
+
+	public get canvasToScreenTransform(): Mat33 {
+		return this.transform;
+	}
+
+	/** @returns the size of the visible region in pixels. */
+	public getScreenRectSize(): Vec2 {
+		return this.screenRect.size;
+	}
+
+	/** Alias for `getScreenRectSize`. @deprecated */
+	public getResolution() {
+		return this.getScreenRectSize();
+	}
+
+	/** @returns the amount a vector on the canvas is scaled to become a vector on the screen. */
+	public getScaleFactor(): number {
+		// Use transformVec3 to avoid translating the vector
+		return this.transform.transformVec3(Vec3.unitX).magnitude();
+	}
+
+	/**
+	 * @returns `getScaleFactor()` rounded to the nearest power of 10.
+	 * For example, if `getScaleFactor()` returns 101, `getScaleFactorToNearestPowerOfTen()`
+	 * should return `100` because `100` is the nearest power of 10 to 101.
+	 */
+	public getScaleFactorToNearestPowerOfTen() {
+		return this.getScaleFactorToNearestPowerOf(10);
+	}
+
+	private getScaleFactorToNearestPowerOf(powerOf: number) {
+		const scaleFactor = this.getScaleFactor();
+		return Math.pow(powerOf, Math.round(Math.log(scaleFactor) / Math.log(powerOf)));
+	}
+
+	/** Returns the size of a grid cell (in canvas units) as used by {@link snapToGrid}. */
+	public static getGridSize(scaleFactor: number) {
+		return 50 / scaleFactor;
+	}
+
+	public snapToGrid(canvasPos: Point2) {
+		const scaleFactor = this.getScaleFactorToNearestPowerOf(2);
+
+		const snapCoordinate = (coordinate: number) => {
+			const roundFactor = 1 / Viewport.getGridSize(scaleFactor);
+			const snapped = Math.round(coordinate * roundFactor) / roundFactor;
+
+			return snapped;
+		};
+
+		const snappedCanvasPos = Vec2.of(
+			snapCoordinate(canvasPos.x), snapCoordinate(canvasPos.y)
+		);
+		return snappedCanvasPos;
+	}
+
+	/** Returns the size of one screen pixel in canvas units. */
+	public getSizeOfPixelOnCanvas(): number {
+		return 1/this.getScaleFactor();
+	}
+
+	/**
+	 * @returns the angle of the canvas in radians.
+	 * This is the angle by which the canvas is rotated relative to the screen.
+	 */
+	public getRotationAngle(): number {
+		return this.transform.transformVec3(Vec3.unitX).angle();
+	}
+
+	/**
+	 * Rounds the given `point` to a multiple of 10 such that it is within `tolerance` of
+	 * its original location. This is useful for preparing data for base-10 conversion.
+	 */
+	public static roundPoint<T extends Point2|number>(
+		point: T, tolerance: number,
+	): PointDataType<T>;
+
+	// The separate function type definition seems necessary here.
+	// See https://stackoverflow.com/a/58163623/17055750.
+	// eslint-disable-next-line no-dupe-class-members
+	public static roundPoint(
+		point: Point2|number, tolerance: number
+	): Point2|number {
+		const scaleFactor = 10 ** Math.floor(Math.log10(tolerance));
+		const roundComponent = (component: number): number => {
+			return Math.round(component / scaleFactor) * scaleFactor;
+		};
+
+		if (typeof point === 'number') {
+			return roundComponent(point);
+		}
+
+		return point.map(roundComponent);
+	}
+
+	// Round a point with a tolerance of ±1 screen unit.
+	public roundPoint(point: Point2): Point2 {
+		return Viewport.roundPoint(point, 1 / this.getScaleFactor());
+	}
+
+	// `roundAmount`: An integer >= 0, larger numbers cause less rounding. Smaller numbers cause more
+	// (as such `roundAmount = 0` does the most rounding).
+	public static roundScaleRatio(scaleRatio: number, roundAmount: number = 1): number {
+		if (Math.abs(scaleRatio) <= 1e-12) {
+			return 0;
+		}
+
+		// Represent as k 10ⁿ for some n, k ∈ ℤ.
+		const decimalComponent = 10 ** Math.floor(Math.log10(Math.abs(scaleRatio)));
+		const roundAmountFactor = 2 ** roundAmount;
+		scaleRatio = Math.round(scaleRatio / decimalComponent * roundAmountFactor) / roundAmountFactor * decimalComponent;
+
+		return scaleRatio;
+	}
+
+	// Computes and returns an affine transformation that makes `toMakeVisible` visible and roughly centered on the screen.
+	public computeZoomToTransform(toMakeVisible: Rect2, allowZoomIn: boolean = true, allowZoomOut: boolean = true): Mat33 {
+		let transform = Mat33.identity;
+
+		if (toMakeVisible.w === 0 || toMakeVisible.h === 0) {
+			throw new Error(`${toMakeVisible.toString()} rectangle is empty! Cannot zoom to!`);
+		}
+
+		if (isNaN(toMakeVisible.size.magnitude())) {
+			throw new Error(`${toMakeVisible.toString()} rectangle has NaN size! Cannot zoom to!`);
+		}
+
+		// Try to move the selection within the center 4/5ths of the viewport.
+		const recomputeTargetRect = () => {
+			// transform transforms objects on the canvas. As such, we need to invert it
+			// to transform the viewport.
+			const visibleRect = this.visibleRect.transformedBoundingBox(transform.inverse());
+			return visibleRect.transformedBoundingBox(Mat33.scaling2D(4/5, visibleRect.center));
+		};
+
+		let targetRect = recomputeTargetRect();
+		const largerThanTarget = targetRect.w < toMakeVisible.w || targetRect.h < toMakeVisible.h;
+
+		// Ensure that toMakeVisible is at least 1/3rd of the visible region.
+		const muchSmallerThanTarget = toMakeVisible.maxDimension / targetRect.maxDimension < 1/3;
+
+		if ((largerThanTarget && allowZoomOut) || (muchSmallerThanTarget && allowZoomIn)) {
+			const multiplier = Math.max(
+				toMakeVisible.w / targetRect.w, toMakeVisible.h / targetRect.h
+			);
+			const visibleRectTransform = Mat33.scaling2D(multiplier, targetRect.topLeft);
+			const viewportContentTransform = visibleRectTransform.inverse();
+
+			transform = transform.rightMul(viewportContentTransform);
+		}
+
+		targetRect = recomputeTargetRect();
+
+		// Ensure that the center of the region is visible
+		if (!targetRect.containsRect(toMakeVisible)) {
+			// target position - current position
+			const translation = toMakeVisible.center.minus(targetRect.center);
+			const visibleRectTransform = Mat33.translation(translation);
+			const viewportContentTransform = visibleRectTransform.inverse();
+
+			transform = transform.rightMul(viewportContentTransform);
+		}
+
+		if (!transform.invertable()) {
+			console.warn('Unable to zoom to ', toMakeVisible, '! Computed transform', transform, 'is singular.');
+			transform = Mat33.identity;
+		}
+
+		return transform;
+	}
+
+	// Returns a Command that transforms the view such that [rect] is visible, and perhaps
+	// centered in the viewport.
+	// Returns null if no transformation is necessary
+	//
+	// @see {@link computeZoomToTransform}
+	public zoomTo(toMakeVisible: Rect2, allowZoomIn: boolean = true, allowZoomOut: boolean = true): Command {
+		const transform = this.computeZoomToTransform(toMakeVisible, allowZoomIn, allowZoomOut);
+		return new Viewport.ViewportTransform(transform);
+	}
+}
+
+export default Viewport;

package/src/bundle/bundled.ts

@@ -0,0 +1,7 @@
+// Main entrypoint for Webpack when building a bundle for release.
+
+import '../styles';
+import Editor from '../Editor';
+export * from '../lib';
+
+export default Editor;

package/src/commands/Command.ts

@@ -0,0 +1,45 @@
+import Editor from '../Editor';
+import { EditorLocalization } from '../localization';
+
+export abstract class Command {
+	public abstract apply(editor: Editor): Promise<void>|void;
+	public abstract unapply(editor: Editor): Promise<void>|void;
+
+	// Called when the command is being deleted
+	public onDrop(_editor: Editor) { }
+
+	public abstract description(editor: Editor, localizationTable: EditorLocalization): string;
+
+	public static union(a: Command, b: Command): Command {
+		return new class extends Command {
+			public apply(editor: Editor) {
+				a.apply(editor);
+				b.apply(editor);
+			}
+
+			public unapply(editor: Editor) {
+				b.unapply(editor);
+				a.unapply(editor);
+			}
+
+			public description(editor: Editor, localizationTable: EditorLocalization) {
+				const aDescription = a.description(editor, localizationTable);
+				const bDescription = b.description(editor, localizationTable);
+
+				if (aDescription === bDescription) {
+					return aDescription;
+				}
+
+				return `${aDescription}, ${bDescription}`;
+			}
+		};
+	}
+
+	public static readonly empty = new class extends Command {
+		public description(_editor: Editor, _localizationTable: EditorLocalization) { return ''; }
+		public apply(_editor: Editor) { }
+		public unapply(_editor: Editor) { }
+	};
+}
+
+export default Command;

package/src/commands/Duplicate.ts

@@ -0,0 +1,75 @@
+import AbstractComponent from '../components/AbstractComponent';
+import describeComponentList from '../components/util/describeComponentList';
+import Editor from '../Editor';
+import { EditorLocalization } from '../localization';
+import Erase from './Erase';
+import SerializableCommand from './SerializableCommand';
+
+/**
+ * A command that duplicates the {@link AbstractComponent}s it's given. This command
+ * is the reverse of an {@link Erase} command.
+ *
+ * @example
+ * ```ts
+ * // Given some editor...
+ *
+ * // Find all elements intersecting the rectangle with top left (0,0) and
+ * // (width,height)=(100,100).
+ * const elems = editor.image.getElementsIntersectingRegion(
+ * 	new Rect2(0, 0, 100, 100)
+ * );
+ *
+ * // Create a command that, when applied, will duplicate the elements.
+ * const duplicateElems = new Duplicate(elems);
+ *
+ * // Apply the command (and make it undoable)
+ * editor.dispatch(duplicateElems);
+ * ```
+ *
+ * @see {@link Editor.dispatch} {@link EditorImage.getElementsIntersectingRegion}
+ */
+export default class Duplicate extends SerializableCommand {
+	private duplicates: AbstractComponent[];
+	private reverse: Erase;
+
+	public constructor(private toDuplicate: AbstractComponent[]) {
+		super('duplicate');
+
+		this.duplicates = toDuplicate.map(elem => elem.clone());
+		this.reverse = new Erase(this.duplicates);
+	}
+
+	public apply(editor: Editor): void {
+		this.reverse.unapply(editor);
+	}
+
+	public unapply(editor: Editor): void {
+		this.reverse.apply(editor);
+	}
+
+	public override onDrop(editor: Editor): void {
+		this.reverse.onDrop(editor);
+	}
+
+	public description(_editor: Editor, localizationTable: EditorLocalization): string {
+		if (this.duplicates.length === 0) {
+			return localizationTable.duplicatedNoElements;
+		}
+
+		return localizationTable.duplicateAction(
+			describeComponentList(localizationTable, this.duplicates) ?? localizationTable.elements,
+			this.duplicates.length
+		);
+	}
+
+	protected serializeToJSON() {
+		return this.toDuplicate.map(elem => elem.getId());
+	}
+
+	static {
+		SerializableCommand.register('duplicate', (json: any, editor: Editor) => {
+			const elems = json.map((id: string) => editor.image.lookupElement(id));
+			return new Duplicate(elems);
+		});
+	}
+}

package/src/commands/Erase.ts

@@ -0,0 +1,94 @@
+import AbstractComponent from '../components/AbstractComponent';
+import describeComponentList from '../components/util/describeComponentList';
+import Editor from '../Editor';
+import EditorImage from '../EditorImage';
+import { EditorLocalization } from '../localization';
+import SerializableCommand from './SerializableCommand';
+
+/**
+ * Removes the given {@link AbstractComponent}s from the image.
+ *
+ * @example
+ * ```ts
+ * // Given some editor...
+ *
+ * // Find all elements intersecting the rectangle with top left (-10,-30) and
+ * // (width,height)=(50,100).
+ * const elems = editor.image.getElementsIntersectingRegion(
+ * 	new Rect2(-10, -30, 50, 100)
+ * );
+ *
+ * // Create a command that erases [elems] when applied
+ * const eraseElemsCmd = new Erase(elems);
+ *
+ * // Apply the command (and make it undoable)
+ * editor.dispatch(eraseElemsCmd);
+ * ```
+ */
+export default class Erase extends SerializableCommand {
+	private toRemove: AbstractComponent[];
+	private applied: boolean;
+
+	public constructor(toRemove: AbstractComponent[]) {
+		super('erase');
+
+		// Clone the list
+		this.toRemove = toRemove.map(elem => elem);
+		this.applied = false;
+	}
+
+	public apply(editor: Editor) {
+		for (const part of this.toRemove) {
+			const parent = editor.image.findParent(part);
+
+			if (parent) {
+				parent.remove();
+			}
+		}
+
+		this.applied = true;
+		editor.queueRerender();
+	}
+
+	public unapply(editor: Editor) {
+		for (const part of this.toRemove) {
+			if (!editor.image.findParent(part)) {
+				EditorImage.addElement(part).apply(editor);
+			}
+		}
+
+		this.applied = false;
+		editor.queueRerender();
+	}
+
+	public override onDrop(editor: Editor) {
+		if (this.applied) {
+			for (const part of this.toRemove) {
+				editor.image.onDestroyElement(part);
+			}
+		}
+	}
+
+	public description(_editor: Editor, localizationTable: EditorLocalization): string {
+		if (this.toRemove.length === 0) {
+			return localizationTable.erasedNoElements;
+		}
+
+		const description = describeComponentList(localizationTable, this.toRemove) ?? localizationTable.elements;
+		return localizationTable.eraseAction(description, this.toRemove.length);
+	}
+
+	protected serializeToJSON() {
+		const elemIds = this.toRemove.map(elem => elem.getId());
+		return elemIds;
+	}
+
+	static {
+		SerializableCommand.register('erase', (json: any, editor) => {
+			const elems = json
+				.map((elemId: string) => editor.image.lookupElement(elemId))
+				.filter((elem: AbstractComponent|null) => elem !== null);
+			return new Erase(elems);
+		});
+	}
+}

package/src/commands/SerializableCommand.ts

@@ -0,0 +1,49 @@
+import Editor from '../Editor';
+import Command from './Command';
+
+export type DeserializationCallback = (data: Record<string, any>|any[], editor: Editor) => SerializableCommand;
+
+export default abstract class SerializableCommand extends Command {
+	public constructor(private commandTypeId: string) {
+		super();
+
+		if (!(commandTypeId in SerializableCommand.deserializationCallbacks)) {
+			throw new Error(
+				`Command ${commandTypeId} must have a registered deserialization callback. To do this, call SerializableCommand.register.`
+			);
+		}
+	}
+
+	protected abstract serializeToJSON(): string|Record<string, any>|any[];
+	private static deserializationCallbacks: Record<string, DeserializationCallback> = {};
+
+	// Convert this command to an object that can be passed to `JSON.stringify`.
+	//
+	// Do not rely on the stability of the optupt of this function — it can change
+	// form without a major version increase.
+	public serialize(): Record<string|symbol, any> {
+		return {
+			data: this.serializeToJSON(),
+			commandType: this.commandTypeId,
+		};
+	}
+
+	// Convert a `string` containing JSON data (or the output of `JSON.parse`) into a
+	// `Command`.
+	public static deserialize(data: string|Record<string, any>, editor: Editor): SerializableCommand {
+		const json = typeof data === 'string' ? JSON.parse(data) : data;
+		const commandType = json.commandType as string;
+
+		if (!(commandType in SerializableCommand.deserializationCallbacks)) {
+			throw new Error(`Unrecognised command type ${commandType}!`);
+		}
+
+		return SerializableCommand.deserializationCallbacks[commandType](json.data, editor);
+	}
+
+	// Register a deserialization callback. This must be called at least once for every subclass of
+	// `SerializableCommand`.
+	public static register(commandTypeId: string, deserialize: DeserializationCallback) {
+		SerializableCommand.deserializationCallbacks[commandTypeId] = deserialize;
+	}
+}