js-draw 0.11.3 → 0.13.0

package/dist/src/Color4.d.ts

@@ -20,6 +20,18 @@ export default class Color4 {
     static fromString(text: string): Color4;
     /** @returns true if `this` and `other` are approximately equal. */
     eq(other: Color4 | null | undefined): boolean;
+    /**
+     * If `fractionTo` is not in the range [0, 1], it will be clamped to the nearest number
+     * in that range. For example, `a.mix(b, -1)` is equivalent to `a.mix(b, 0)`.
+     *
+     * @returns a color `fractionTo` of the way from this color to `other`.
+     *
+     * @example
+     * ```ts
+     * Color4.ofRGB(1, 0, 0).mix(Color4.ofRGB(0, 1, 0), 0.1) // -> Color4(0.9, 0.1, 0)
+     * ```
+     */
+    mix(other: Color4, fractionTo: number): Color4;
     private hexString;
     /**
      * @returns a hexadecimal color string representation of `this`, in the form `#rrggbbaa`.
@@ -39,5 +51,6 @@ export default class Color4 {
     static yellow: Color4;
     static clay: Color4;
     static black: Color4;
+    static gray: Color4;
     static white: Color4;
 }

package/dist/src/Color4.js

@@ -105,6 +105,22 @@ export default class Color4 {
         }
         return this.toHexString() === other.toHexString();
     }
+    /**
+     * If `fractionTo` is not in the range [0, 1], it will be clamped to the nearest number
+     * in that range. For example, `a.mix(b, -1)` is equivalent to `a.mix(b, 0)`.
+     *
+     * @returns a color `fractionTo` of the way from this color to `other`.
+     *
+     * @example
+     * ```ts
+     * Color4.ofRGB(1, 0, 0).mix(Color4.ofRGB(0, 1, 0), 0.1) // -> Color4(0.9, 0.1, 0)
+     * ```
+     */
+    mix(other, fractionTo) {
+        fractionTo = Math.min(Math.max(fractionTo, 0), 1);
+        const fractionOfThis = 1 - fractionTo;
+        return new Color4(this.r * fractionOfThis + other.r * fractionTo, this.g * fractionOfThis + other.g * fractionTo, this.b * fractionOfThis + other.b * fractionTo, this.a * fractionOfThis + other.a * fractionTo);
+    }
     /**
      * @returns a hexadecimal color string representation of `this`, in the form `#rrggbbaa`.
      *
@@ -146,4 +162,5 @@ Color4.purple = Color4.ofRGB(0.5, 0.2, 0.5);
 Color4.yellow = Color4.ofRGB(1, 1, 0.1);
 Color4.clay = Color4.ofRGB(0.8, 0.4, 0.2);
 Color4.black = Color4.ofRGB(0, 0, 0);
+Color4.gray = Color4.ofRGB(0.5, 0.5, 0.5);
 Color4.white = Color4.ofRGB(1, 1, 1);

package/dist/src/Editor.d.ts

@@ -1,20 +1,3 @@
-/**
- * The main entrypoint for the full editor.
- *
- * @example
- * To create an editor with a toolbar,
- * ```
- * const editor = new Editor(document.body);
- *
- * const toolbar = editor.addToolbar();
- * toolbar.addActionButton('Save', () => {
- *   const saveData = editor.toSVG().outerHTML;
- *   // Do something with saveData...
- * });
- * ```
- *
- * @packageDocumentation
- */
 import EditorImage from './EditorImage';
 import ToolController from './tools/ToolController';
 import { InputEvtType, EditorNotifier, ImageLoader } from './types';
@@ -48,9 +31,25 @@ export interface EditorSettings {
     maxZoom: number;
     iconProvider: IconProvider;
 }
+/**
+ * The main entrypoint for the full editor.
+ *
+ * @example
+ * To create an editor with a toolbar,
+ * ```
+ * const editor = new Editor(document.body);
+ *
+ * const toolbar = editor.addToolbar();
+ * toolbar.addActionButton('Save', () => {
+ *   const saveData = editor.toSVG().outerHTML;
+ *   // Do something with saveData...
+ * });
+ * ```
+ */
 export declare class Editor {
     private container;
     private renderingRegion;
+    /** Manages drawing surfaces/{@link lib!AbstractRenderer}s. */
     display: Display;
     /**
      * Handles undo/redo.
@@ -87,10 +86,20 @@ export declare class Editor {
     readonly image: EditorImage;
     /** Viewport for the exported/imported image. */
     private importExportViewport;
+    /**
+     * Allows transforming the view and querying information about
+     * what is currently visible.
+     */
+    readonly viewport: Viewport;
     /** @internal */
     readonly localization: EditorLocalization;
+    /** {@link lib!EditorSettings.iconProvider} */
     readonly icons: IconProvider;
-    readonly viewport: Viewport;
+    /**
+     * Controls the list of tools. See
+     * [the custom tool example](https://github.com/personalizedrefrigerator/js-draw/tree/main/docs/example-custom-tools)
+     * for more.
+     */
     readonly toolController: ToolController;
     /**
      * Global event dispatcher/subscriber.
@@ -196,7 +205,13 @@ export declare class Editor {
      */
     queueRerender(): Promise<void>;
     rerender(showImageBounds?: boolean): void;
+    /**
+     * @see {@link Display.getWetInkRenderer} {@link Display.flatten}
+     */
     drawWetInk(...path: RenderablePathSpec[]): void;
+    /**
+     * @see {@link Display.getWetInkRenderer}
+     */
     clearWetInk(): void;
     focus(): void;
     createHTMLOverlay(overlay: HTMLElement): {

package/dist/src/Editor.js

@@ -1,20 +1,3 @@
-/**
- * The main entrypoint for the full editor.
- *
- * @example
- * To create an editor with a toolbar,
- * ```
- * const editor = new Editor(document.body);
- *
- * const toolbar = editor.addToolbar();
- * toolbar.addActionButton('Save', () => {
- *   const saveData = editor.toSVG().outerHTML;
- *   // Do something with saveData...
- * });
- * ```
- *
- * @packageDocumentation
- */
 var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
     function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
     return new (P || (P = Promise))(function (resolve, reject) {
@@ -48,7 +31,21 @@ import untilNextAnimationFrame from './util/untilNextAnimationFrame';
 import fileToBase64 from './util/fileToBase64';
 import uniteCommands from './commands/uniteCommands';
 import SelectionTool from './tools/SelectionTool/SelectionTool';
-// { @inheritDoc Editor! }
+/**
+ * The main entrypoint for the full editor.
+ *
+ * @example
+ * To create an editor with a toolbar,
+ * ```
+ * const editor = new Editor(document.body);
+ *
+ * const toolbar = editor.addToolbar();
+ * toolbar.addActionButton('Save', () => {
+ *   const saveData = editor.toSVG().outerHTML;
+ *   // Do something with saveData...
+ * });
+ * ```
+ */
 export class Editor {
     /**
      * @example
@@ -188,8 +185,7 @@ export class Editor {
     addToolbar(defaultLayout = true) {
         const toolbar = new HTMLToolbar(this, this.container, this.localization);
         if (defaultLayout) {
-            toolbar.addDefaultToolWidgets();
-            toolbar.addDefaultActionButtons();
+            toolbar.addDefaults();
         }
         return toolbar;
     }
@@ -583,11 +579,17 @@ export class Editor {
         this.nextRerenderListeners.forEach(listener => listener());
         this.nextRerenderListeners = [];
     }
+    /**
+     * @see {@link Display.getWetInkRenderer} {@link Display.flatten}
+     */
     drawWetInk(...path) {
         for (const part of path) {
             this.display.getWetInkRenderer().drawPath(part);
         }
     }
+    /**
+     * @see {@link Display.getWetInkRenderer}
+     */
     clearWetInk() {
         this.display.getWetInkRenderer().clear();
     }
@@ -682,7 +684,7 @@ export class Editor {
     // The export resolution is the same as the size of the drawing canvas.
     toDataURL(format = 'image/png') {
         const canvas = document.createElement('canvas');
-        const resolution = this.importExportViewport.getResolution();
+        const resolution = this.importExportViewport.getScreenRectSize();
         canvas.width = resolution.x;
         canvas.height = resolution.y;
         const ctx = canvas.getContext('2d');
@@ -718,9 +720,9 @@ export class Editor {
         return __awaiter(this, void 0, void 0, function* () {
             this.showLoadingWarning(0);
             this.display.setDraftMode(true);
-            yield loader.start((component) => {
-                this.dispatchNoAnnounce(EditorImage.addElement(component));
-            }, (countProcessed, totalToProcess) => {
+            yield loader.start((component) => __awaiter(this, void 0, void 0, function* () {
+                yield this.dispatchNoAnnounce(EditorImage.addElement(component));
+            }), (countProcessed, totalToProcess) => {
                 if (countProcessed % 500 === 0) {
                     this.showLoadingWarning(countProcessed / totalToProcess);
                     this.rerender();

package/dist/src/EditorImage.d.ts

@@ -22,8 +22,20 @@ export default class EditorImage {
     getElementsIntersectingRegion(region: Rect2): AbstractComponent[];
     /** @internal */
     onDestroyElement(elem: AbstractComponent): void;
+    /**
+     * @returns the AbstractComponent with `id`, if it exists.
+     *
+     * @see {@link AbstractComponent.getId}
+     */
     lookupElement(id: string): AbstractComponent | null;
     private addElementDirectly;
+    /**
+     * Returns a command that adds the given element to the `EditorImage`.
+     * If `applyByFlattening` is true, the content of the wet ink renderer is
+     * rendered onto the main rendering canvas instead of doing a full re-render.
+     *
+     * @see {@link Display.flatten}
+     */
     static addElement(elem: AbstractComponent, applyByFlattening?: boolean): SerializableCommand;
     private static AddElementCommand;
 }

package/dist/src/EditorImage.js

@@ -55,6 +55,11 @@ export default class EditorImage {
     onDestroyElement(elem) {
         delete this.componentsById[elem.getId()];
     }
+    /**
+     * @returns the AbstractComponent with `id`, if it exists.
+     *
+     * @see {@link AbstractComponent.getId}
+     */
     lookupElement(id) {
         var _a;
         return (_a = this.componentsById[id]) !== null && _a !== void 0 ? _a : null;
@@ -63,6 +68,13 @@ export default class EditorImage {
         this.componentsById[elem.getId()] = elem;
         return this.root.addLeaf(elem);
     }
+    /**
+     * Returns a command that adds the given element to the `EditorImage`.
+     * If `applyByFlattening` is true, the content of the wet ink renderer is
+     * rendered onto the main rendering canvas instead of doing a full re-render.
+     *
+     * @see {@link Display.flatten}
+     */
     static addElement(elem, applyByFlattening = false) {
         return new EditorImage.AddElementCommand(elem, applyByFlattening);
     }

package/dist/src/Pointer.d.ts

@@ -18,6 +18,7 @@ export default class Pointer {
     readonly id: number;
     readonly timeStamp: number;
     private constructor();
+    snappedToGrid(viewport: Viewport): Pointer;
     static ofEvent(evt: PointerEvent, isDown: boolean, viewport: Viewport, relativeTo?: HTMLElement): Pointer;
     static ofCanvasPoint(canvasPos: Point2, isDown: boolean, viewport: Viewport, id?: number, device?: PointerDevice, isPrimary?: boolean, pressure?: number | null): Pointer;
 }

package/dist/src/Pointer.js

@@ -31,6 +31,14 @@ export default class Pointer {
         this.id = id;
         this.timeStamp = timeStamp;
     }
+    // Snaps this pointer to the nearest grid point (rounds the coordinates of this
+    // pointer based on the current zoom). Returns a new Pointer and does not modify
+    // this.
+    snappedToGrid(viewport) {
+        const snappedCanvasPos = viewport.snapToGrid(this.canvasPos);
+        const snappedScreenPos = viewport.canvasToScreen(snappedCanvasPos);
+        return new Pointer(snappedScreenPos, snappedCanvasPos, this.pressure, this.isPrimary, this.down, this.device, this.id, this.timeStamp);
+    }
     // Creates a Pointer from a DOM event. If `relativeTo` is given, (0, 0) in screen coordinates is
     // considered the top left of `relativeTo`.
     static ofEvent(evt, isDown, viewport, relativeTo) {

package/dist/src/SVGLoader.d.ts

@@ -34,5 +34,10 @@ export default class SVGLoader implements ImageLoader {
     private visit;
     private getSourceAttrs;
     start(onAddComponent: ComponentAddedListener, onProgress: OnProgressListener, onDetermineExportRect?: OnDetermineExportRectListener | null): Promise<void>;
+    /**
+     * @see {@link Editor.loadFrom}
+     * @param text - Textual representation of the SVG (e.g. `<svg viewbox='...'>...</svg>`).
+     * @param sanitize - if `true`, don't store unknown attributes.
+     */
     static fromString(text: string, sanitize?: boolean): SVGLoader;
 }

package/dist/src/SVGLoader.js

@@ -23,6 +23,7 @@ export const defaultSVGViewRect = new Rect2(0, 0, 500, 500);
 export const svgAttributesDataKey = 'svgAttrs';
 export const svgStyleAttributesDataKey = 'svgStyleAttrs';
 const supportedStrokeFillStyleAttrs = ['stroke', 'fill', 'stroke-width'];
+// Handles loading images from SVG.
 export default class SVGLoader {
     constructor(source, onFinish, storeUnknown = true) {
         this.source = source;
@@ -125,22 +126,24 @@ export default class SVGLoader {
     // Adds a stroke with a single path
     addPath(node) {
         var _a;
-        let elem;
-        try {
-            const strokeData = this.strokeDataFromElem(node);
-            elem = new Stroke(strokeData);
-            this.attachUnrecognisedAttrs(elem, node, new Set([...supportedStrokeFillStyleAttrs, 'd']), new Set(supportedStrokeFillStyleAttrs));
-        }
-        catch (e) {
-            console.error('Invalid path in node', node, '\nError:', e, '\nAdding as an unknown object.');
-            if (this.storeUnknown) {
-                elem = new UnknownSVGObject(node);
+        return __awaiter(this, void 0, void 0, function* () {
+            let elem;
+            try {
+                const strokeData = this.strokeDataFromElem(node);
+                elem = new Stroke(strokeData);
+                this.attachUnrecognisedAttrs(elem, node, new Set([...supportedStrokeFillStyleAttrs, 'd']), new Set(supportedStrokeFillStyleAttrs));
             }
-            else {
-                return;
+            catch (e) {
+                console.error('Invalid path in node', node, '\nError:', e, '\nAdding as an unknown object.');
+                if (this.storeUnknown) {
+                    elem = new UnknownSVGObject(node);
+                }
+                else {
+                    return;
+                }
             }
-        }
-        (_a = this.onAddComponent) === null || _a === void 0 ? void 0 : _a.call(this, elem);
+            yield ((_a = this.onAddComponent) === null || _a === void 0 ? void 0 : _a.call(this, elem));
+        });
     }
     // If given, 'supportedAttrs' will have x, y, etc. attributes that were used in computing the transform added to it,
     // to prevent storing duplicate transform information when saving the component.
@@ -223,14 +226,16 @@ export default class SVGLoader {
     }
     addText(elem) {
         var _a;
-        try {
-            const textElem = this.makeText(elem);
-            (_a = this.onAddComponent) === null || _a === void 0 ? void 0 : _a.call(this, textElem);
-        }
-        catch (e) {
-            console.error('Invalid text object in node', elem, '. Continuing.... Error:', e);
-            this.addUnknownNode(elem);
-        }
+        return __awaiter(this, void 0, void 0, function* () {
+            try {
+                const textElem = this.makeText(elem);
+                yield ((_a = this.onAddComponent) === null || _a === void 0 ? void 0 : _a.call(this, textElem));
+            }
+            catch (e) {
+                console.error('Invalid text object in node', elem, '. Continuing.... Error:', e);
+                this.addUnknownNode(elem);
+            }
+        });
     }
     addImage(elem) {
         var _a, _b, _c;
@@ -243,20 +248,22 @@ export default class SVGLoader {
                 const transform = this.getTransform(elem, supportedAttrs);
                 const imageElem = yield ImageComponent.fromImage(image, transform);
                 this.attachUnrecognisedAttrs(imageElem, elem, new Set(supportedAttrs), new Set(['transform']));
-                (_c = this.onAddComponent) === null || _c === void 0 ? void 0 : _c.call(this, imageElem);
+                yield ((_c = this.onAddComponent) === null || _c === void 0 ? void 0 : _c.call(this, imageElem));
             }
             catch (e) {
                 console.error('Error loading image:', e, '. Element: ', elem, '. Continuing...');
-                this.addUnknownNode(elem);
+                yield this.addUnknownNode(elem);
             }
         });
     }
     addUnknownNode(node) {
         var _a;
-        if (this.storeUnknown) {
-            const component = new UnknownSVGObject(node);
-            (_a = this.onAddComponent) === null || _a === void 0 ? void 0 : _a.call(this, component);
-        }
+        return __awaiter(this, void 0, void 0, function* () {
+            if (this.storeUnknown) {
+                const component = new UnknownSVGObject(node);
+                yield ((_a = this.onAddComponent) === null || _a === void 0 ? void 0 : _a.call(this, component));
+            }
+        });
     }
     updateViewBox(node) {
         var _a;
@@ -278,9 +285,11 @@ export default class SVGLoader {
     }
     updateSVGAttrs(node) {
         var _a;
-        if (this.storeUnknown) {
-            (_a = this.onAddComponent) === null || _a === void 0 ? void 0 : _a.call(this, new SVGGlobalAttributesObject(this.getSourceAttrs(node)));
-        }
+        return __awaiter(this, void 0, void 0, function* () {
+            if (this.storeUnknown) {
+                yield ((_a = this.onAddComponent) === null || _a === void 0 ? void 0 : _a.call(this, new SVGGlobalAttributesObject(this.getSourceAttrs(node))));
+            }
+        });
     }
     visit(node) {
         var _a;
@@ -292,10 +301,10 @@ export default class SVGLoader {
                     // Continue -- visit the node's children.
                     break;
                 case 'path':
-                    this.addPath(node);
+                    yield this.addPath(node);
                     break;
                 case 'text':
-                    this.addText(node);
+                    yield this.addText(node);
                     visitChildren = false;
                     break;
                 case 'image':
@@ -308,14 +317,14 @@ export default class SVGLoader {
                     this.updateSVGAttrs(node);
                     break;
                 case 'style':
-                    this.addUnknownNode(node);
+                    yield this.addUnknownNode(node);
                     break;
                 default:
                     console.warn('Unknown SVG element,', node);
                     if (!(node instanceof SVGElement)) {
                         console.warn('Element', node, 'is not an SVGElement!', this.storeUnknown ? 'Continuing anyway.' : 'Skipping.');
                     }
-                    this.addUnknownNode(node);
+                    yield this.addUnknownNode(node);
                     return;
             }
             if (visitChildren) {
@@ -351,7 +360,11 @@ export default class SVGLoader {
             (_b = this.onFinish) === null || _b === void 0 ? void 0 : _b.call(this);
         });
     }
-    // @param sanitize - if `true`, don't store unknown attributes.
+    /**
+     * @see {@link Editor.loadFrom}
+     * @param text - Textual representation of the SVG (e.g. `<svg viewbox='...'>...</svg>`).
+     * @param sanitize - if `true`, don't store unknown attributes.
+     */
     static fromString(text, sanitize = false) {
         var _a, _b;
         const sandbox = document.createElement('iframe');

package/dist/src/Viewport.d.ts

@@ -2,6 +2,7 @@ import Command from './commands/Command';
 import Mat33 from './math/Mat33';
 import Rect2 from './math/Rect2';
 import { Point2, Vec2 } from './math/Vec2';
+import Vec3 from './math/Vec3';
 import { StrokeDataPoint } from './types';
 import { EditorNotifier } from './types';
 type PointDataType<T extends Point2 | StrokeDataPoint | number> = T extends Point2 ? Point2 : number;
@@ -16,17 +17,45 @@ export declare class Viewport {
     private screenRect;
     constructor(notifier: EditorNotifier);
     updateScreenSize(screenSize: Vec2): void;
+    /** Get the screen's visible region transformed into canvas space. */
     get visibleRect(): Rect2;
+    /** @returns the given point, but in canvas coordinates */
     screenToCanvas(screenPoint: Point2): Point2;
+    /** @returns the given point transformed into screen coordinates. */
     canvasToScreen(canvasPoint: Point2): Point2;
+    /** @returns a command that transforms the canvas by `transform`. */
     static transformBy(transform: Mat33): ViewportTransform;
+    /**
+     * Updates the transformation directly. Using `transformBy` is preferred.
+     * @param newTransform - should map from canvas coordinates to screen coordinates.
+     */
     resetTransform(newTransform?: Mat33): void;
     get screenToCanvasTransform(): Mat33;
     get canvasToScreenTransform(): Mat33;
-    getResolution(): Vec2;
+    /** @returns the size of the visible region in pixels. */
+    getScreenRectSize(): Vec2;
+    /** Alias for `getScreenRectSize`. @deprecated */
+    getResolution(): Vec3;
+    /** @returns the amount a vector on the canvas is scaled to become a vector on the screen. */
     getScaleFactor(): number;
+    /**
+     * @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.
+     */
+    getScaleFactorToNearestPowerOfTen(): number;
+    snapToGrid(canvasPos: Point2): Vec3;
+    /** Returns the size of one screen pixel in canvas units. */
     getSizeOfPixelOnCanvas(): number;
+    /**
+     * @returns the angle of the canvas in radians.
+     * This is the angle by which the canvas is rotated relative to the screen.
+     */
     getRotationAngle(): number;
+    /**
+     * 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.
+     */
     static roundPoint<T extends Point2 | number>(point: T, tolerance: number): PointDataType<T>;
     roundPoint(point: Point2): Point2;
     static roundScaleRatio(scaleRatio: number, roundAmount?: number): number;

package/dist/src/Viewport.js

@@ -29,22 +29,26 @@ export class Viewport {
     updateScreenSize(screenSize) {
         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. */
     get visibleRect() {
         return this.screenRect.transformedBoundingBox(this.inverseTransform);
     }
-    // the given point, but in canvas coordinates
+    /** @returns the given point, but in canvas coordinates */
     screenToCanvas(screenPoint) {
         return this.inverseTransform.transformVec2(screenPoint);
     }
+    /** @returns the given point transformed into screen coordinates. */
     canvasToScreen(canvasPoint) {
         return this.transform.transformVec2(canvasPoint);
     }
+    /** @returns a command that transforms the canvas by `transform`. */
     static transformBy(transform) {
         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.
+     */
     resetTransform(newTransform = Mat33.identity) {
         const oldTransform = this.transform;
         this.transform = newTransform;
@@ -61,20 +65,46 @@ export class Viewport {
     get canvasToScreenTransform() {
         return this.transform;
     }
-    getResolution() {
+    /** @returns the size of the visible region in pixels. */
+    getScreenRectSize() {
         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 */
+    getResolution() {
+        return this.getScreenRectSize();
+    }
+    /** @returns the amount a vector on the canvas is scaled to become a vector on the screen. */
     getScaleFactor() {
         // 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.
+     */
+    getScaleFactorToNearestPowerOfTen() {
+        const scaleFactor = this.getScaleFactor();
+        return Math.pow(10, Math.round(Math.log10(scaleFactor)));
+    }
+    snapToGrid(canvasPos) {
+        const snapCoordinate = (coordinate) => {
+            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. */
     getSizeOfPixelOnCanvas() {
         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.
+     */
     getRotationAngle() {
         return this.transform.transformVec3(Vec3.unitX).angle();
     }

package/dist/src/commands/invertCommand.js

@@ -1,6 +1,6 @@
 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 = (command) => {
     if (command instanceof SerializableCommand) {

package/dist/src/components/AbstractComponent.d.ts

@@ -7,6 +7,9 @@ import { ImageComponentLocalization } from './localization';
 export type LoadSaveData = (string[] | Record<symbol, string | number>);
 export type LoadSaveDataTable = Record<string, Array<LoadSaveData>>;
 export type DeserializeCallback = (data: string) => AbstractComponent;
+/**
+ * A base class for everything that can be added to an {@link EditorImage}.
+ */
 export default abstract class AbstractComponent {
     private readonly componentKind;
     protected lastChangedTime: number;
@@ -19,12 +22,25 @@ export default abstract class AbstractComponent {
     private static deserializationCallbacks;
     static registerComponent(componentKind: string, deserialize: DeserializeCallback | null): void;
     private loadSaveData;
+    /**
+     * Attach data that can be used while exporting the component (e.g. to SVG).
+     *
+     * This is intended for use by a {@link ImageLoader}.
+     */
     attachLoadSaveData(key: string, data: LoadSaveData): void;
+    /** See {@link attachLoadSaveData} */
     getLoadSaveData(): LoadSaveDataTable;
     getZIndex(): number;
+    /** @returns the bounding box of  */
     getBBox(): Rect2;
     abstract render(canvas: AbstractRenderer, visibleRect?: Rect2): void;
+    /** @return true if `lineSegment` intersects this component. */
     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.
+     */
+    intersectsRect(rect: Rect2): boolean;
     protected abstract serializeToJSON(): any[] | Record<string, any> | number | string | null;
     protected abstract applyTransformation(affineTransfm: Mat33): void;
     transformBy(affineTransfm: Mat33): SerializableCommand;
@@ -34,6 +50,10 @@ export default abstract class AbstractComponent {
     private static transformElementCommandId;
     private static UnresolvedTransformElementCommand;
     private static TransformElementCommand;
+    /**
+     * @return a description that could be read by a screen reader
+     *     (e.g. when adding/erasing the component)
+     */
     abstract description(localizationTable: ImageComponentLocalization): string;
     protected abstract createClone(): AbstractComponent;
     clone(): AbstractComponent;