js-draw 0.11.3 → 0.13.0

package/src/Viewport.ts

@@ -92,26 +92,30 @@ export class Viewport {
 		this.screenRect = this.screenRect.resizedTo(screenSize);
 	}
 
-	// Get the screen's visible region transformed into canvas space.
+	/** Get the screen's visible region transformed into canvas space. */
 	public get visibleRect(): Rect2 {
 		return this.screenRect.transformedBoundingBox(this.inverseTransform);
 	}
 
-	// the given point, but in canvas coordinates
+	/** @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.
-	// [newTransform] should map from canvas coordinates to screen coordinates.
+	/**
+	 * 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;
@@ -131,29 +135,64 @@ export class Viewport {
 		return this.transform;
 	}
 
-	public getResolution(): Vec2 {
+	/** @returns the size of the visible region in pixels. */
+	public getScreenRectSize(): Vec2 {
 		return this.screenRect.size;
 	}
 
-	// Returns the amount a vector on the canvas is scaled to become a vector on the screen.
+	/** 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 the size of one screen pixel in canvas units.
+	/**
+	 * @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() {
+		const scaleFactor = this.getScaleFactor();
+		return Math.pow(10, Math.round(Math.log10(scaleFactor)));
+	}
+
+	public snapToGrid(canvasPos: Point2) {
+		const snapCoordinate = (coordinate: number) => {
+			const scaleFactor = this.getScaleFactorToNearestPowerOfTen();
+			const roundFactor = scaleFactor / 100;
+			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.
+	/**
+	 * @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.
+	/**
+	 * 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>;

package/src/commands/invertCommand.ts

@@ -3,7 +3,7 @@ import { EditorLocalization } from '../localization';
 import Command from './Command';
 import SerializableCommand from './SerializableCommand';
 
-// Returns a command taht does the opposite of the given command --- `result.apply()` calls
+// Returns a command that does the opposite of the given command --- `result.apply()` calls
 // `command.unapply()` and `result.unapply()` calls `command.apply()`.
 const invertCommand = <T extends Command> (command: T): T extends SerializableCommand ? SerializableCommand : Command => {
 	if (command instanceof SerializableCommand) {

package/src/components/AbstractComponent.ts

@@ -13,9 +13,20 @@ 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;
 
@@ -38,7 +49,7 @@ export default abstract class AbstractComponent {
 	}
 
 	// Returns a unique ID for this element.
-	// @see { @link EditorImage!default.lookupElement }
+	// @see { @link lib!EditorImage.lookupElement }
 	public getId() {
 		return this.id;
 	}
@@ -55,14 +66,22 @@ export default abstract class AbstractComponent {
 		this.deserializationCallbacks[componentKind] = deserialize ?? null;
 	}
 
-	// Get and manage data attached by a loader.
+	// 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 a {@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;
 	}
@@ -71,13 +90,39 @@ export default abstract class AbstractComponent {
 		return this.zIndex;
 	}
 
+	/** @returns the bounding box of  */
 	public getBBox(): Rect2 {
 		return this.contentBBox;
 	}
 
 	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.
+	 */
+	public intersectsRect(rect: Rect2): boolean {
+		// If this component intersects rect,
+		// it is either contained entirely within rect or intersects one of rect's edges.
+
+		// If contained within,
+		if (rect.containsRect(this.getBBox())) {
+			return true;
+		}
+
+		// Calculated bounding boxes can be slightly larger than their actual contents' bounding box.
+		// As such, test with more lines than just the rect's edges.
+		const testLines = [];
+		for (const subregion of rect.divideIntoGrid(2, 2)) {
+			testLines.push(...subregion.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;
 
@@ -181,6 +226,7 @@ export default abstract class AbstractComponent {
 			}
 
 			this.component.applyTransformation(newTransfm);
+			this.component.lastChangedTime = (new Date()).getTime();
 
 			// Add the element back to the document.
 			if (hadParent) {
@@ -231,6 +277,10 @@ export default abstract class AbstractComponent {
 		}
 	};
 
+	/**
+	 * @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}.

package/src/lib.ts

@@ -8,25 +8,28 @@
  * ```
  * 
  * @see
- * {@link Editor!}
+ * {@link Editor}
  * 
  * @packageDocumentation
  */
 
-import Editor from './Editor';
+import Editor, { EditorSettings } from './Editor';
 export { default as EditorImage } from './EditorImage';
 export * from './types';
 export { default as getLocalizationTable } from './localizations/getLocalizationTable';
 export * from './localization';
 
 export { default as Color4 } from './Color4';
+export { default as SVGLoader } from './SVGLoader';
+export { default as Viewport } from './Viewport';
 export * from './math/lib';
 export * from './components/lib';
 export * from './commands/lib';
 export * from './tools/lib';
 export * from './toolbar/lib';
+export * from './rendering/lib';
 export { default as Pointer, PointerDevice } from './Pointer';
 export { default as HTMLToolbar } from './toolbar/HTMLToolbar';
 
-export { Editor };
+export { Editor, EditorSettings };
 export default Editor;

package/src/math/Mat33.ts

@@ -338,7 +338,7 @@ export default class Mat33 {
 		return result.rightMul(Mat33.translation(center.times(-1)));
 	}
 
-	/** @see {@link !fromCSSMatrix} */
+	/** @see {@link fromCSSMatrix} */
 	public toCSSMatrix(): string {
 		return `matrix(${this.a1},${this.b1},${this.a2},${this.b2},${this.a3},${this.b3})`;
 	}

package/src/rendering/Display.ts

@@ -1,18 +1,3 @@
-/**
- * Handles `HTMLCanvasElement`s (or other drawing surfaces if being used) used to display the editor's contents.
- *
- * @example
- * ```
- * const editor = new Editor(document.body);
- * const w = editor.display.width;
- * const h = editor.display.height;
- * const center = Vec2.of(w / 2, h / 2);
- * const colorAtCenter = editor.display.getColorAt(center);
- * ```
- * 
- * @packageDocumentation
- */
-
 import AbstractRenderer from './renderers/AbstractRenderer';
 import CanvasRenderer from './renderers/CanvasRenderer';
 import { Editor } from '../Editor';
@@ -29,6 +14,18 @@ export enum RenderingMode {
 	// SVGRenderer is not supported by the main display
 }
 
+/**
+ * Handles `HTMLCanvasElement`s (or other drawing surfaces if being used) used to display the editor's contents.
+ *
+ * @example
+ * ```
+ * const editor = new Editor(document.body);
+ * const w = editor.display.width;
+ * const h = editor.display.height;
+ * const center = Vec2.of(w / 2, h / 2);
+ * const colorAtCenter = editor.display.getColorAt(center);
+ * ```
+ */
 export default class Display {
 	private dryInkRenderer: AbstractRenderer;
 	private wetInkRenderer: AbstractRenderer;

package/src/rendering/RenderingStyle.ts

@@ -13,7 +13,7 @@ export default RenderingStyle;
 export const stylesEqual = (a: RenderingStyle, b: RenderingStyle): boolean => {
 	const result = a === b || (a.fill.eq(b.fill)
 		&& (a.stroke == undefined) === (b.stroke == undefined)
-        && (a.stroke?.color?.eq(b.stroke?.color) ?? true)
+		&& (a.stroke?.color?.eq(b.stroke?.color) ?? true)
 		&& a.stroke?.width === b.stroke?.width);
     
 	// Map undefined/null -> false

package/src/rendering/lib.ts

@@ -0,0 +1,4 @@
+
+export { default as AbstractRenderer } from './renderers/AbstractRenderer';
+export { default as DummyRenderer } from './renderers/DummyRenderer';
+export { default as Display } from './Display';

package/src/rendering/renderers/DummyRenderer.ts

@@ -1,5 +1,3 @@
-// Renderer that outputs nothing. Useful for automated tests.
-
 import { TextStyle } from '../../components/TextComponent';
 import Mat33 from '../../math/Mat33';
 import Rect2 from '../../math/Rect2';
@@ -9,6 +7,7 @@ import Viewport from '../../Viewport';
 import RenderingStyle from '../RenderingStyle';
 import AbstractRenderer, { RenderableImage } from './AbstractRenderer';
 
+// Renderer that outputs almost nothing. Useful for automated tests.
 export default class DummyRenderer extends AbstractRenderer {
 	// Variables that track the state of what's been rendered
 	public clearedCount: number = 0;
@@ -28,7 +27,7 @@ export default class DummyRenderer extends AbstractRenderer {
 
 	public displaySize(): Vec2 {
 		// Do we have a stored viewport size?
-		const viewportSize = this.getViewport().getResolution();
+		const viewportSize = this.getViewport().getScreenRectSize();
 
 		// Don't use a 0x0 viewport — DummyRenderer is often used
 		// for tests that run without a display, so pretend we have a

package/src/rendering/renderers/SVGRenderer.ts

@@ -38,6 +38,10 @@ export default class SVGRenderer extends AbstractRenderer {
 					stroke-linecap: round;
 					stroke-linejoin: round;
 				}
+
+				text {
+					white-space: pre;
+				}
 			`.replace(/\s+/g, '');
 			styleSheet.setAttribute('id', renderedStylesheetId);
 			this.elem.appendChild(styleSheet);

package/src/rendering/renderers/TextOnlyRenderer.ts

@@ -9,7 +9,6 @@ import RenderingStyle from '../RenderingStyle';
 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;

package/src/toolbar/HTMLToolbar.ts

@@ -16,12 +16,25 @@ import SelectionToolWidget from './widgets/SelectionToolWidget';
 import TextToolWidget from './widgets/TextToolWidget';
 import HandToolWidget from './widgets/HandToolWidget';
 import BaseWidget from './widgets/BaseWidget';
-import { ActionButtonWidget, InsertImageWidget } from './lib';
+import ActionButtonWidget from './widgets/ActionButtonWidget';
+import InsertImageWidget from './widgets/InsertImageWidget';
 
 export const toolbarCSSPrefix = 'toolbar-';
 
 type UpdateColorisCallback = ()=>void;
 
+interface SpacerOptions {
+	// Defaults to 0. If a non-zero number, determines the rate at which the
+	// spacer should grow (like flexGrow).
+	grow: number;
+
+	// Minimum size (e.g. "23px")
+	minSize: string;
+
+	// Maximum size (e.g. "50px")
+	maxSize: string;
+}
+
 export default class HTMLToolbar {
 	private container: HTMLElement;
 
@@ -121,8 +134,17 @@ export default class HTMLToolbar {
 		});
 	}
 
-	// Adds an `ActionButtonWidget` or `BaseToolWidget`. The widget should not have already have a parent
-	// (i.e. its `addTo` method should not have been called).
+	/**
+	 * Adds an `ActionButtonWidget` or `BaseToolWidget`. The widget should not have already have a parent
+	 * (i.e. its `addTo` method should not have been called).
+	 * 
+	 * @example
+	 * ```ts
+	 * const toolbar = editor.addToolbar();
+	 * const insertImageWidget = new InsertImageWidget(editor);
+	 * toolbar.addWidget(insertImageWidget);
+	 * ```
+	 */
 	public addWidget(widget: BaseWidget) {
 		// Prevent name collisions
 		const id = widget.getUniqueIdIn(this.widgets);
@@ -135,6 +157,46 @@ export default class HTMLToolbar {
 		this.setupColorPickers();
 	}
 
+	/**
+	 * Adds a spacer.
+	 * 
+	 * @example
+	 * Adding a save button that moves to the very right edge of the toolbar
+	 * while keeping the other buttons centered:
+	 * ```ts
+	 * const toolbar = editor.addToolbar(false);
+	 *
+	 * toolbar.addSpacer({ grow: 1 });
+	 * toolbar.addDefaults();
+	 * toolbar.addSpacer({ grow: 1 });
+	 *
+	 * toolbar.addActionButton({
+	 * 	label: 'Save',
+	 * 	icon: editor.icons.makeSaveIcon(),
+	 * }, () => {
+	 * 	  saveCallback();
+	 * });
+	 * ```
+	 */
+	public addSpacer(options: Partial<SpacerOptions> = {}) {
+		const spacer = document.createElement('div');
+		spacer.classList.add(`${toolbarCSSPrefix}spacer`);
+
+		if (options.grow) {
+			spacer.style.flexGrow = `${options.grow}`;
+		}
+
+		if (options.minSize) {
+			spacer.style.minWidth = options.minSize;
+		}
+
+		if (options.maxSize) {
+			spacer.style.maxWidth = options.maxSize;
+		}
+
+		this.container.appendChild(spacer);
+	}
+
 	public serializeState(): string {
 		const result: Record<string, any> = {};
 
@@ -145,8 +207,10 @@ export default class HTMLToolbar {
 		return JSON.stringify(result);
 	}
 
-	// Deserialize toolbar widgets from the given state.
-	// Assumes that toolbar widgets are in the same order as when state was serialized.
+	/**
+	 * Deserialize toolbar widgets from the given state.
+	 * Assumes that toolbar widgets are in the same order as when state was serialized.
+	 */
 	public deserializeState(state: string) {
 		const data = JSON.parse(state);
 
@@ -247,4 +311,16 @@ export default class HTMLToolbar {
 	public addDefaultActionButtons() {
 		this.addUndoRedoButtons();
 	}
+
+	/**
+	 * Adds both the default tool widgets and action buttons. Equivalent to
+	 * ```ts
+	 * toolbar.addDefaultToolWidgets();
+	 * toolbar.addDefaultActionButtons();
+	 * ```
+	 */
+	public addDefaults() {
+		this.addDefaultToolWidgets();
+		this.addDefaultActionButtons();
+	}
 }