js-draw 1.0.0 → 1.0.1

package/src/components/AbstractComponent.ts

@@ -0,0 +1,383 @@
+import SerializableCommand from '../commands/SerializableCommand';
+import Editor from '../Editor';
+import EditorImage from '../EditorImage';
+import { LineSegment2, Mat33, Mat33Array, Rect2 } from '@js-draw/math';
+import { EditorLocalization } from '../localization';
+import AbstractRenderer from '../rendering/renderers/AbstractRenderer';
+import { ImageComponentLocalization } from './localization';
+import UnresolvedSerializableCommand from '../commands/UnresolvedCommand';
+
+export type LoadSaveData = (string[]|Record<symbol, string|number>);
+export type LoadSaveDataTable = Record<string, Array<LoadSaveData>>;
+export type DeserializeCallback = (data: string)=>AbstractComponent;
+type ComponentId = string;
+
+/**
+ * A base class for everything that can be added to an {@link EditorImage}.
+ */
+export default abstract class AbstractComponent {
+	// The timestamp (milliseconds) at which the component was
+	// last changed (i.e. created/translated).
+	// @deprecated
+	protected lastChangedTime: number;
+
+	// The bounding box of this component.
+	// {@link getBBox}, by default, returns `contentBBox`.
+	// This must be set by components.
+	protected abstract contentBBox: Rect2;
+
+	private zIndex: number;
+	private id: string;
+
+	// Topmost z-index
+	private static zIndexCounter: number = 0;
+
+	protected constructor(
+		// A unique identifier for the type of component
+		private readonly componentKind: string,
+		initialZIndex?: number,
+	) {
+		this.lastChangedTime = (new Date()).getTime();
+
+		if (initialZIndex !== undefined) {
+			this.zIndex = initialZIndex;
+		} else {
+			this.zIndex = AbstractComponent.zIndexCounter++;
+		}
+
+		// Create a unique ID.
+		this.id = `${new Date().getTime()}-${Math.random()}`;
+
+		if (AbstractComponent.deserializationCallbacks[componentKind] === undefined) {
+			throw new Error(`Component ${componentKind} has not been registered using AbstractComponent.registerComponent`);
+		}
+	}
+
+	// Returns a unique ID for this element.
+	// @see { @link EditorImage.lookupElement }
+	public getId() {
+		return this.id;
+	}
+
+	private static deserializationCallbacks: Record<ComponentId, DeserializeCallback|null> = {};
+
+	// Store the deserialization callback (or lack of it) for [componentKind].
+	// If components are registered multiple times (as may be done in automated tests),
+	// the most recent deserialization callback is used.
+	public static registerComponent(
+		componentKind: string,
+		deserialize: DeserializeCallback|null,
+	) {
+		this.deserializationCallbacks[componentKind] = deserialize ?? null;
+	}
+
+	// Stores data attached by a loader.
+	private loadSaveData: LoadSaveDataTable = {};
+
+	/**
+	 * Attach data that can be used while exporting the component (e.g. to SVG).
+	 *
+	 * This is intended for use by an {@link ImageLoader}.
+	 */
+	public attachLoadSaveData(key: string, data: LoadSaveData) {
+		if (!this.loadSaveData[key]) {
+			this.loadSaveData[key] = [];
+		}
+		this.loadSaveData[key].push(data);
+	}
+
+	/** See {@link attachLoadSaveData} */
+	public getLoadSaveData(): LoadSaveDataTable {
+		return this.loadSaveData;
+	}
+
+	public getZIndex(): number {
+		return this.zIndex;
+	}
+
+	/**
+	 * @returns the bounding box of this. This can be a slight overestimate if doing so
+	 * 			significantly improves performance.
+	 */
+	public getBBox(): Rect2 {
+		return this.contentBBox;
+	}
+
+	/**
+	 * @returns the bounding box of this. Unlike `getBBox`, this should **not** be a rough estimate.
+	 */
+	public getExactBBox() {
+		return this.getBBox();
+	}
+
+	/** Called when this component is added to the given image. */
+	public onAddToImage(_image: EditorImage): void { }
+	public onRemoveFromImage(): void { }
+
+	/**
+	 * Renders this component onto the given `canvas`.
+	 *
+	 * If `visibleRect` is given, it should be the region of `canvas` that is visible --
+	 * rendering anything outside of `visibleRect` should have no visible effect on the
+	 * resultant image.
+	 *
+	 * For optimal performance, implementers should call `canvas.startObject` and `canvas.endObject`
+	 * before and after rendering.
+	 */
+	public abstract render(canvas: AbstractRenderer, visibleRect?: Rect2): void;
+
+	/** @return true if `lineSegment` intersects this component. */
+	public abstract intersects(lineSegment: LineSegment2): boolean;
+
+	/**
+	 * @returns true if this component intersects `rect` -- it is entirely contained
+	 *  within the rectangle or one of the rectangle's edges intersects this component.
+	 *
+	 * The default implementation assumes that `this.getExactBBox()` returns a tight bounding box
+	 * -- that any horiziontal/vertical line that intersects this' boounding box also
+	 * intersects a point in this component. If this is not the case, components must override
+	 * this function.
+	 */
+	public intersectsRect(rect: Rect2): boolean {
+		// If this component intersects the given rectangle,
+		// it is either contained entirely within rect or intersects one of rect's edges.
+
+		// If contained within,
+		if (rect.containsRect(this.getExactBBox())) {
+			return true;
+		}
+
+		// Otherwise check if it intersects one of the rectangle's edges.
+		const testLines = rect.getEdges();
+		return testLines.some(edge => this.intersects(edge));
+	}
+
+	// Return null iff this object cannot be safely serialized/deserialized.
+	protected abstract serializeToJSON(): any[]|Record<string, any>|number|string|null;
+
+	// Private helper for transformBy: Apply the given transformation to all points of this.
+	protected abstract applyTransformation(affineTransfm: Mat33): void;
+
+	// Returns a command that, when applied, transforms this by [affineTransfm] and
+	// updates the editor.
+	// This also increases the element's z-index so that it is on top.
+	public transformBy(affineTransfm: Mat33): SerializableCommand {
+		return new AbstractComponent.TransformElementCommand(affineTransfm, this.getId(), this);
+	}
+
+	// Returns a command that updates this component's z-index.
+	public setZIndex(newZIndex: number): SerializableCommand {
+		return new AbstractComponent.TransformElementCommand(Mat33.identity, this.getId(), this, newZIndex, this.getZIndex());
+	}
+
+	// @returns true iff this component can be selected (e.g. by the selection tool.)
+	public isSelectable(): boolean {
+		return true;
+	}
+
+	// @returns true iff this component should be added to the background, rather than the
+	// foreground of the image.
+	public isBackground(): boolean {
+		return false;
+	}
+
+	// @returns an approximation of the proportional time it takes to render this component.
+	// This is intended to be a rough estimate, but, for example, a stroke with two points sould have
+	// a renderingWeight approximately twice that of a stroke with one point.
+	public getProportionalRenderingTime(): number {
+		return 1;
+	}
+
+	private static transformElementCommandId = 'transform-element';
+
+	private static TransformElementCommand = class extends UnresolvedSerializableCommand {
+		private targetZIndex: number;
+
+		// Construct a new TransformElementCommand. `component`, while optional, should
+		// be provided if available. If not provided, it will be fetched from the editor's
+		// document when the command is applied.
+		public constructor(
+			private affineTransfm: Mat33,
+			componentID: string,
+			component?: AbstractComponent,
+			targetZIndex?: number,
+			private origZIndex?: number,
+		) {
+			super(AbstractComponent.transformElementCommandId, componentID, component);
+			this.targetZIndex = targetZIndex ?? AbstractComponent.zIndexCounter++;
+
+			// Ensure that we keep drawing on top even after changing the z-index.
+			if (this.targetZIndex >= AbstractComponent.zIndexCounter) {
+				AbstractComponent.zIndexCounter = this.targetZIndex + 1;
+			}
+
+			if (component && origZIndex === undefined) {
+				this.origZIndex = component.getZIndex();
+			}
+		}
+
+		protected override resolveComponent(image: EditorImage): void {
+			if (this.component) {
+				return;
+			}
+
+			super.resolveComponent(image);
+			this.origZIndex ??= this.component!.getZIndex();
+		}
+
+		private updateTransform(editor: Editor, newTransfm: Mat33) {
+			if (!this.component) {
+				throw new Error('this.component is undefined or null!');
+			}
+
+			// Any parent should have only one direct child.
+			const parent = editor.image.findParent(this.component);
+			let hadParent = false;
+			if (parent) {
+				parent.remove();
+				hadParent = true;
+			}
+
+			this.component.applyTransformation(newTransfm);
+			this.component.lastChangedTime = (new Date()).getTime();
+
+			// Add the element back to the document.
+			if (hadParent) {
+				EditorImage.addElement(this.component).apply(editor);
+			}
+		}
+
+		public apply(editor: Editor) {
+			this.resolveComponent(editor.image);
+
+			this.component!.zIndex = this.targetZIndex;
+			this.updateTransform(editor, this.affineTransfm);
+			editor.queueRerender();
+		}
+
+		public unapply(editor: Editor) {
+			this.resolveComponent(editor.image);
+
+			this.component!.zIndex = this.origZIndex!;
+			this.updateTransform(editor, this.affineTransfm.inverse());
+			editor.queueRerender();
+		}
+
+		public description(_editor: Editor, localizationTable: EditorLocalization) {
+			return localizationTable.transformedElements(1);
+		}
+
+		static {
+			SerializableCommand.register(AbstractComponent.transformElementCommandId, (json: any, editor: Editor) => {
+				const elem = editor.image.lookupElement(json.id) ?? undefined;
+				const transform = new Mat33(...(json.transfm as Mat33Array));
+				const targetZIndex = json.targetZIndex;
+				const origZIndex = json.origZIndex ?? undefined;
+
+				return new AbstractComponent.TransformElementCommand(
+					transform,
+					json.id,
+					elem,
+					targetZIndex,
+					origZIndex,
+				);
+			});
+		}
+
+		protected serializeToJSON() {
+			return {
+				id: this.componentID,
+				transfm: this.affineTransfm.toArray(),
+				targetZIndex: this.targetZIndex,
+				origZIndex: this.origZIndex,
+			};
+		}
+	};
+
+	/**
+	 * @return a description that could be read by a screen reader
+	 *     (e.g. when adding/erasing the component)
+	 */
+	public abstract description(localizationTable: ImageComponentLocalization): string;
+
+	// Component-specific implementation of {@link clone}.
+	protected abstract createClone(): AbstractComponent;
+
+	// Returns a copy of this component.
+	public clone() {
+		const clone = this.createClone();
+
+		for (const attachmentKey in this.loadSaveData) {
+			for (const val of this.loadSaveData[attachmentKey]) {
+				clone.attachLoadSaveData(attachmentKey, val);
+			}
+		}
+
+		return clone;
+	}
+
+	// Convert the component to an object that can be passed to
+	// `JSON.stringify`.
+	//
+	// Do not rely on the output of this function to take a particular form —
+	// this function's output can change form without a major version increase.
+	public serialize() {
+		const data = this.serializeToJSON();
+
+		if (data === null) {
+			throw new Error(`${this} cannot be serialized.`);
+		}
+
+		return {
+			name: this.componentKind,
+			zIndex: this.zIndex,
+			id: this.id,
+			loadSaveData: this.loadSaveData,
+			data,
+		};
+	}
+
+	// Returns true if `data` is not deserializable. May return false even if [data]
+	// is not deserializable.
+	private static isNotDeserializable(json: any|string) {
+		if (typeof json === 'string') {
+			json = JSON.parse(json);
+		}
+
+		if (typeof json !== 'object') {
+			return true;
+		}
+
+		if (!this.deserializationCallbacks[json?.name]) {
+			return true;
+		}
+
+		if (!json.data) {
+			return true;
+		}
+
+		return false;
+	}
+
+	// Convert a string or an object produced by `JSON.parse` into an `AbstractComponent`.
+	public static deserialize(json: string|any): AbstractComponent {
+		if (typeof json === 'string') {
+			json = JSON.parse(json);
+		}
+
+		if (AbstractComponent.isNotDeserializable(json)) {
+			throw new Error(`Element with data ${json} cannot be deserialized.`);
+		}
+
+		const instance = this.deserializationCallbacks[json.name]!(json.data);
+		instance.zIndex = json.zIndex;
+		instance.id = json.id;
+
+		// TODO: What should we do with json.loadSaveData?
+		//       If we attach it to [instance], we create a potential security risk — loadSaveData
+		//       is often used to store unrecognised attributes so they can be preserved on output.
+		//       ...but what if we're deserializing data sent across the network?
+
+		return instance;
+	}
+}

package/src/components/BackgroundComponent.test.ts

@@ -0,0 +1,44 @@
+import { Path, Rect2, Color4 } from '@js-draw/math';
+import createEditor from '../testing/createEditor';
+import AbstractComponent from './AbstractComponent';
+import BackgroundComponent, { BackgroundType, imageBackgroundCSSClassName } from './BackgroundComponent';
+
+describe('ImageBackground', () => {
+	it('should render to fill exported SVG', () => {
+		const editor = createEditor();
+		const background = new BackgroundComponent(BackgroundType.SolidColor, Color4.green);
+		editor.image.addElement(background).apply(editor);
+
+		const expectedImportExportRect = new Rect2(-10, 10, 15, 20);
+		editor.setImportExportRect(expectedImportExportRect).apply(editor);
+		expect(editor.getImportExportRect()).objEq(expectedImportExportRect);
+
+		expect(background.getBBox()).objEq(expectedImportExportRect);
+
+		const rendered = editor.toSVG();
+		const renderedBackground = rendered.querySelector(`.${imageBackgroundCSSClassName}`);
+
+		if (renderedBackground === null) {
+			throw new Error('ImageBackground did not render in exported SVG');
+		}
+
+		expect(renderedBackground.tagName.toLowerCase()).toBe('path');
+
+		const pathString = renderedBackground.getAttribute('d')!;
+		expect(pathString).not.toBeNull();
+
+		const path = Path.fromString(pathString);
+		expect(path.bbox).objEq(editor.getImportExportRect());
+	});
+
+	it('should be serializable', () => {
+		const background = BackgroundComponent.ofGrid(Color4.red, 10, Color4.purple);
+
+		const deserializedBackground = AbstractComponent.deserialize(background.serialize()) as BackgroundComponent;
+		expect(deserializedBackground.getBackgroundType()).toBe(BackgroundType.Grid);
+		expect(deserializedBackground.getStyle().color).objEq(Color4.red);
+		expect(deserializedBackground.getMainColor()).objEq(Color4.red);
+		expect(deserializedBackground.getGridSize()).toBe(background.getGridSize());
+		expect(deserializedBackground.getSecondaryColor()).objEq(Color4.purple);
+	});
+});