js-draw 0.18.1 → 0.18.2

package/src/rendering/renderers/SVGRenderer.ts

@@ -0,0 +1,354 @@
+
+import { LoadSaveDataTable } from '../../components/AbstractComponent';
+import Mat33 from '../../math/Mat33';
+import Path from '../../math/Path';
+import Rect2 from '../../math/Rect2';
+import { toRoundedString } from '../../math/rounding';
+import { Point2, Vec2 } from '../../math/Vec2';
+import { svgAttributesDataKey, SVGLoaderUnknownAttribute, SVGLoaderUnknownStyleAttribute, svgStyleAttributesDataKey } from '../../SVGLoader';
+import Viewport from '../../Viewport';
+import RenderingStyle from '../RenderingStyle';
+import TextStyle from '../TextRenderingStyle';
+import AbstractRenderer, { RenderableImage, RenderablePathSpec } from './AbstractRenderer';
+
+export const renderedStylesheetId = 'js-draw-style-sheet';
+
+const svgNameSpace = 'http://www.w3.org/2000/svg';
+
+/**
+ * Renders onto an `SVGElement`.
+ * 
+ * @see {@link Editor.toSVG}
+ */
+export default class SVGRenderer extends AbstractRenderer {
+	private lastPathStyle: RenderingStyle|null = null;
+	private lastPathString: string[] = [];
+	private objectElems: SVGElement[]|null = null;
+
+	private overwrittenAttrs: Record<string, string|null> = {};
+
+	/**
+	 * Creates a renderer that renders onto `elem`. If `sanitize`, don't render potentially untrusted data.
+	 * 
+	 * `viewport` is used to determine the translation/rotation/scaling/output size of the rendered
+	 * data.
+	 */
+	public constructor(private elem: SVGSVGElement, viewport: Viewport, private sanitize: boolean = false) {
+		super(viewport);
+		this.clear();
+
+		this.addStyleSheet();
+	}
+
+	private addStyleSheet() {
+		if (!this.elem.querySelector(`#${renderedStylesheetId}`)) {
+			// Default to rounded strokes.
+			const styleSheet = document.createElementNS('http://www.w3.org/2000/svg', 'style');
+			styleSheet.innerHTML = `
+				path {
+					stroke-linecap: round;
+					stroke-linejoin: round;
+				}
+
+				text {
+					white-space: pre;
+				}
+			`.replace(/\s+/g, '');
+			styleSheet.setAttribute('id', renderedStylesheetId);
+			this.elem.appendChild(styleSheet);
+		}
+	}
+
+	// Sets an attribute on the root SVG element.
+	public setRootSVGAttribute(name: string, value: string|null) {
+		if (this.sanitize) {
+			return;
+		}
+	
+		// Make the original value of the attribute restorable on clear
+		if (!(name in this.overwrittenAttrs)) {
+			this.overwrittenAttrs[name] = this.elem.getAttribute(name);
+		}
+
+		if (value !== null) {
+			this.elem.setAttribute(name, value);
+		} else {
+			this.elem.removeAttribute(name);
+		}
+	}
+
+	public displaySize(): Vec2 {
+		return Vec2.of(this.elem.clientWidth, this.elem.clientHeight);
+	}
+
+	public clear() {
+		this.lastPathString = [];
+
+		if (!this.sanitize) {
+			// Restore all all attributes
+			for (const attrName in this.overwrittenAttrs) {
+				const value = this.overwrittenAttrs[attrName];
+
+				if (value) {
+					this.elem.setAttribute(attrName, value);
+				} else {
+					this.elem.removeAttribute(attrName);
+				}
+			}
+			this.overwrittenAttrs = {};
+		}
+	}
+
+	// Push [this.fullPath] to the SVG
+	private addPathToSVG() {
+		if (!this.lastPathStyle || this.lastPathString.length === 0) {
+			return;
+		}
+
+		const pathElem = document.createElementNS(svgNameSpace, 'path');
+		pathElem.setAttribute('d', this.lastPathString.join(' '));
+
+		const style = this.lastPathStyle;
+		if (style.fill.a > 0) {
+			pathElem.setAttribute('fill', style.fill.toHexString());
+		} else {
+			pathElem.setAttribute('fill', 'none');
+		}
+
+		if (style.stroke) {
+			pathElem.setAttribute('stroke', style.stroke.color.toHexString());
+			pathElem.setAttribute('stroke-width', toRoundedString(style.stroke.width));
+		}
+
+		this.elem.appendChild(pathElem);
+		this.objectElems?.push(pathElem);
+	}
+
+	public drawPath(pathSpec: RenderablePathSpec) {
+		const style = pathSpec.style;
+		const path = Path.fromRenderable(pathSpec).transformedBy(this.getCanvasToScreenTransform());
+
+		// Try to extend the previous path, if possible
+		if (!style.fill.eq(this.lastPathStyle?.fill) || this.lastPathString.length === 0) {
+			this.addPathToSVG();
+			this.lastPathStyle = style;
+			this.lastPathString = [];
+		}
+		this.lastPathString.push(path.toString());
+	}
+
+	// Apply [elemTransform] to [elem]. Uses both a `matrix` and `.x`, `.y` properties if `setXY` is true.
+	// Otherwise, just uses a `matrix`.
+	private transformFrom(elemTransform: Mat33, elem: SVGElement, inCanvasSpace: boolean = false, setXY: boolean = true) {
+		let transform = !inCanvasSpace ? this.getCanvasToScreenTransform().rightMul(elemTransform) : elemTransform;
+		const translation = transform.transformVec2(Vec2.zero);
+
+		if (setXY) {
+			transform = transform.rightMul(Mat33.translation(translation.times(-1)));
+		}
+
+		if (!transform.eq(Mat33.identity)) {
+			elem.style.transform = `matrix(
+				${transform.a1}, ${transform.b1},
+				${transform.a2}, ${transform.b2},
+				${transform.a3}, ${transform.b3}
+			)`;
+		} else {
+			elem.style.transform = '';
+		}
+
+		if (setXY) {
+			elem.setAttribute('x', `${toRoundedString(translation.x)}`);
+			elem.setAttribute('y', `${toRoundedString(translation.y)}`);
+		}
+	}
+
+	private textContainer: SVGTextElement|null = null;
+	private textContainerTransform: Mat33|null = null;
+	private textParentStyle: TextStyle|null = null;
+	public drawText(text: string, transform: Mat33, style: TextStyle): void {
+		const applyTextStyles = (elem: SVGTextElement|SVGTSpanElement, style: TextStyle) => {
+			if (style.fontFamily !== this.textParentStyle?.fontFamily) {
+				elem.style.fontFamily = style.fontFamily;
+			}
+			if (style.fontVariant !== this.textParentStyle?.fontVariant) {
+				elem.style.fontVariant = style.fontVariant ?? '';
+			}
+			if (style.fontWeight !== this.textParentStyle?.fontWeight) {
+				elem.style.fontWeight = style.fontWeight ?? '';
+			}
+			if (style.size !== this.textParentStyle?.size) {
+				elem.style.fontSize = style.size + 'px';
+			}
+			
+			const fillString = style.renderingStyle.fill.toHexString();
+			// TODO: Uncomment at some future major version release --- currently causes incompatibility due
+			//       to an SVG parsing bug in older versions.
+			//const parentFillString = this.textParentStyle?.renderingStyle?.fill?.toHexString();
+			//if (fillString !== parentFillString) {
+			elem.style.fill = fillString;
+			//}
+
+			if (style.renderingStyle.stroke) {
+				const strokeStyle = style.renderingStyle.stroke;
+				elem.style.stroke = strokeStyle.color.toHexString();
+				elem.style.strokeWidth = strokeStyle.width + 'px';
+			}
+		};
+		transform = this.getCanvasToScreenTransform().rightMul(transform);
+
+		if (!this.textContainer) {
+			const container = document.createElementNS(svgNameSpace, 'text');
+			container.appendChild(document.createTextNode(text));
+
+			// Don't set .x/.y properties (just use .style.transform).
+			// Child nodes aren't translated by .x/.y properties, but are by .style.transform.
+			const setXY = false;
+			this.transformFrom(transform, container, true, setXY);
+			applyTextStyles(container, style);
+
+			this.elem.appendChild(container);
+			this.objectElems?.push(container);
+			if (this.objectLevel > 0) {
+				this.textContainer = container;
+				this.textContainerTransform = transform;
+				this.textParentStyle = style;
+			}
+		} else {
+			const elem = document.createElementNS(svgNameSpace, 'tspan');
+			elem.appendChild(document.createTextNode(text));
+			this.textContainer.appendChild(elem);
+
+			// Make .x/.y relative to the parent.
+			transform = this.textContainerTransform!.inverse().rightMul(transform);
+
+			// .style.transform does nothing to tspan elements. As such, we need to set x/y:
+			const translation = transform.transformVec2(Vec2.zero);
+			elem.setAttribute('x', `${toRoundedString(translation.x)}`);
+			elem.setAttribute('y', `${toRoundedString(translation.y)}`);
+
+			applyTextStyles(elem, style);
+		}
+	}
+
+	public drawImage(image: RenderableImage) {
+		let label = image.label ?? image.image.getAttribute('aria-label') ?? '';
+		if (label === '') {
+			label = image.image.getAttribute('alt') ?? '';
+		}
+
+		const svgImgElem = document.createElementNS(svgNameSpace, 'image');
+		svgImgElem.setAttribute('href', image.base64Url);
+		svgImgElem.setAttribute('width', image.image.getAttribute('width') ?? '');
+		svgImgElem.setAttribute('height', image.image.getAttribute('height') ?? '');
+		svgImgElem.setAttribute('aria-label', label);
+		this.transformFrom(image.transform, svgImgElem);
+
+		this.elem.appendChild(svgImgElem);
+		this.objectElems?.push(svgImgElem);
+	}
+
+	public startObject(boundingBox: Rect2) {
+		super.startObject(boundingBox);
+
+		// Only accumulate a path within an object
+		this.lastPathString = [];
+		this.lastPathStyle = null;
+		this.textContainer = null;
+		this.textParentStyle = null;
+		this.objectElems = [];
+	}
+
+	public endObject(loaderData?: LoadSaveDataTable, elemClassNames?: string[]) {
+		super.endObject(loaderData);
+
+		// Don't extend paths across objects
+		this.addPathToSVG();
+
+		if (loaderData && !this.sanitize) {
+			// Restore any attributes unsupported by the app.
+			for (const elem of this.objectElems ?? []) {
+				const attrs = loaderData[svgAttributesDataKey] as SVGLoaderUnknownAttribute[]|undefined;
+				const styleAttrs = loaderData[svgStyleAttributesDataKey] as SVGLoaderUnknownStyleAttribute[]|undefined;
+
+				if (attrs) {
+					for (const [ attr, value ] of attrs) {
+						elem.setAttribute(attr, value);
+					}
+				}
+
+				if (styleAttrs) {
+					for (const attr of styleAttrs) {
+						elem.style.setProperty(attr.key, attr.value, attr.priority);
+					}
+				}
+			}
+		}
+
+		// Add class names to the object, if given.
+		if (elemClassNames) {
+			for (const elem of this.objectElems ?? []) {
+				elem.classList.add(...elemClassNames);
+			}
+		}
+	}
+
+	// Not implemented -- use drawPath instead.
+	private unimplementedMessage() { throw new Error('Not implemenented!'); }
+	protected beginPath(_startPoint: Point2) { this.unimplementedMessage(); }
+	protected endPath(_style: RenderingStyle) { this.unimplementedMessage(); }
+	protected lineTo(_point: Point2) { this.unimplementedMessage(); }
+	protected moveTo(_point: Point2) { this.unimplementedMessage(); }
+	protected traceCubicBezierCurve(
+		_controlPoint1: Point2, _controlPoint2: Point2, _endPoint: Point2
+	) { this.unimplementedMessage(); }
+	protected traceQuadraticBezierCurve(_controlPoint: Point2, _endPoint: Point2) { this.unimplementedMessage(); }
+
+	public drawPoints(...points: Point2[]) {
+		points.map(point => {
+			const elem = document.createElementNS(svgNameSpace, 'circle');
+			elem.setAttribute('cx', `${point.x}`);
+			elem.setAttribute('cy', `${point.y}`);
+			elem.setAttribute('r', '15');
+			this.elem.appendChild(elem);
+		});
+	}
+
+	// Renders a **copy** of the given element.
+	public drawSVGElem(elem: SVGElement) {
+		if (this.sanitize) {
+			return;
+		}
+
+		// Don't add multiple copies of the default stylesheet.
+		if (elem.tagName.toLowerCase() === 'style' && elem.getAttribute('id') === renderedStylesheetId) {
+			return;
+		}
+
+		this.elem.appendChild(elem.cloneNode(true));
+	}
+
+	public isTooSmallToRender(_rect: Rect2): boolean {
+		return false;
+	}
+
+	// Creates a new SVG element and SVGRenerer with attributes set for the given Viewport.
+	public static fromViewport(viewport: Viewport, sanitize: boolean = true) {
+		const svgNameSpace = 'http://www.w3.org/2000/svg';
+		const result = document.createElementNS(svgNameSpace, 'svg');
+
+		const rect = viewport.getScreenRectSize();
+		// rect.x -> size of rect in x direction, rect.y -> size of rect in y direction.
+		result.setAttribute('viewBox', [0, 0, rect.x, rect.y].map(part => toRoundedString(part)).join(' '));
+		result.setAttribute('width', toRoundedString(rect.x));
+		result.setAttribute('height', toRoundedString(rect.y));
+
+		// Ensure the image can be identified as an SVG if downloaded.
+		// See https://jwatt.org/svg/authoring/
+		result.setAttribute('version', '1.1');
+		result.setAttribute('baseProfile', 'full');
+		result.setAttribute('xmlns', svgNameSpace);
+
+		return { element: result, renderer: new SVGRenderer(result, viewport, sanitize) };
+	}
+}

package/src/rendering/renderers/TextOnlyRenderer.ts

@@ -0,0 +1,70 @@
+import Mat33 from '../../math/Mat33';
+import Rect2 from '../../math/Rect2';
+import { Vec2 } from '../../math/Vec2';
+import Vec3 from '../../math/Vec3';
+import Viewport from '../../Viewport';
+import { TextRendererLocalization } from '../localization';
+import RenderingStyle from '../RenderingStyle';
+import TextStyle from '../TextRenderingStyle';
+import AbstractRenderer, { RenderableImage } from './AbstractRenderer';
+
+// Outputs a description of what was rendered.
+export default class TextOnlyRenderer extends AbstractRenderer {
+	private descriptionBuilder: string[] = [];
+	private pathCount: number = 0;
+	private textNodeCount: number = 0;
+	private imageNodeCount: number = 0;
+
+	public constructor(viewport: Viewport, private localizationTable: TextRendererLocalization) {
+		super(viewport);
+	}
+
+	public displaySize(): Vec3 {
+		// We don't have a graphical display, export a reasonable size.
+		return Vec2.of(500, 500);
+	}
+
+	public clear(): void {
+		this.descriptionBuilder = [];
+		this.pathCount = 0;
+		this.textNodeCount = 0;
+	}
+
+	public getDescription(): string {
+		return [
+			this.localizationTable.pathNodeCount(this.pathCount),
+			...(this.textNodeCount > 0 ? [this.localizationTable.textNodeCount(this.textNodeCount)] : []),
+			...(this.imageNodeCount > 0 ? [this.localizationTable.imageNodeCount(this.imageNodeCount)] : []),
+			...this.descriptionBuilder
+		].join('\n');
+	}
+
+	protected beginPath(_startPoint: Vec3): void {
+	}
+	protected endPath(_style: RenderingStyle): void {
+		this.pathCount ++;
+	}
+	protected lineTo(_point: Vec3): void {
+	}
+	protected moveTo(_point: Vec3): void {
+	}
+	protected traceCubicBezierCurve(_p1: Vec3, _p2: Vec3, _p3: Vec3): void {
+	}
+	protected traceQuadraticBezierCurve(_controlPoint: Vec3, _endPoint: Vec3): void {
+	}
+	public drawText(text: string, _transform: Mat33, _style: TextStyle): void {
+		this.descriptionBuilder.push(this.localizationTable.textNode(text));
+		this.textNodeCount ++;
+	}
+	public drawImage(image: RenderableImage) {
+		const label = image.label ? this.localizationTable.imageNode(image.label) : this.localizationTable.unlabeledImageNode;
+
+		this.descriptionBuilder.push(label);
+		this.imageNodeCount ++;
+	}
+	public isTooSmallToRender(rect: Rect2): boolean {
+		return rect.maxDimension < 15 / this.getSizeOfCanvasPixelOnScreen();
+	}
+	public drawPoints(..._points: Vec3[]): void {
+	}
+}

package/src/styles.js

@@ -0,0 +1,7 @@
+/**
+ * Applies the editor's styles to the document.
+ * @packageDocumentation
+ */
+
+import './Editor.css';
+import '@melloware/coloris/dist/coloris.css';

package/src/testing/beforeEachFile.ts

@@ -0,0 +1,8 @@
+import loadExpectExtensions from './loadExpectExtensions';
+loadExpectExtensions();
+jest.useFakeTimers();
+
+// jsdom doesn't support HTMLCanvasElement#getContext — it logs an error
+// to the console. Make it return null so we can handle a non-existent Canvas
+// at runtime (e.g. use something else, if available).
+HTMLCanvasElement.prototype.getContext = () => null;

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/global.d.ts

@@ -0,0 +1,17 @@
+
+
+// Type declarations for custom matchers
+interface CustomMatchers<R = unknown> {
+	objEq(expected: {
+		eq: (other: any, ...args: any)=> boolean;
+	}, ...opts: any): R;
+}
+
+declare namespace jest {
+	interface Expect extends CustomMatchers {}
+	interface Matchers<R> extends CustomMatchers<R> {}
+	interface AsyncAsymmetricMatchers extends CustomMatchers {}
+}
+
+declare interface JestMatchers<T> extends CustomMatchers<T> {
+}

package/src/testing/lib.ts

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

package/src/testing/loadExpectExtensions.ts

@@ -0,0 +1,25 @@
+export const loadExpectExtensions = () => {
+	// Custom matchers. See
+	// https://jestjs.io/docs/expect#expectextendmatchers
+	expect.extend({
+		// Determine whether expected = actual based on the objects'
+		// .eq methods
+		objEq(actual: any, expected: any, ...eqArgs: any) {
+			let pass = false;
+			if ((expected ?? null) === null) {
+				pass = actual.eq(expected, ...eqArgs);
+			} else {
+				pass = expected.eq(actual, ...eqArgs);
+			}
+
+			return {
+				pass,
+				message: () => {
+					return `Expected ${pass ? '!' : ''}(${actual}).eq(${expected}). Options(${eqArgs})`;
+				},
+			};
+		},
+	});
+};
+
+export default loadExpectExtensions;

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;