js-draw 1.9.1 → 1.11.0

package/dist/cjs/tools/util/StationaryPenDetector.d.ts

@@ -0,0 +1,22 @@
+import Pointer from '../../Pointer';
+interface Config {
+    maxSpeed: number;
+    minTimeSeconds: number;
+    maxRadius: number;
+}
+type OnStationaryCallback = (lastPointer: Pointer) => void;
+export default class StationaryPenDetector {
+    private config;
+    private onStationary;
+    private stationaryStartPointer;
+    private lastPointer;
+    private averageVelocity;
+    private timeout;
+    constructor(startPointer: Pointer, config: Config, onStationary: OnStationaryCallback);
+    onPointerMove(currentPointer: Pointer): boolean | undefined;
+    onPointerUp(pointer: Pointer): void;
+    destroy(): void;
+    private cancelStationaryTimeout;
+    private setStationaryTimeout;
+}
+export {};

package/dist/cjs/tools/util/StationaryPenDetector.js

@@ -0,0 +1,95 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const math_1 = require("@js-draw/math");
+class StationaryPenDetector {
+    // Only handles one pen. As such, `startPointer` should be the same device/finger
+    // as `updatedPointer` in `onPointerMove`.
+    //
+    // A new `StationaryPenDetector` should be created for each gesture.
+    constructor(startPointer, config, onStationary) {
+        this.config = config;
+        this.onStationary = onStationary;
+        this.timeout = null;
+        this.stationaryStartPointer = startPointer;
+        this.lastPointer = startPointer;
+        this.averageVelocity = math_1.Vec2.zero;
+    }
+    // Returns true if stationary
+    onPointerMove(currentPointer) {
+        if (!this.stationaryStartPointer) {
+            // Destoroyed
+            return;
+        }
+        if (currentPointer.id !== this.stationaryStartPointer.id) {
+            return false;
+        }
+        // dx: "Δx" Displacement from last.
+        const dxFromLast = currentPointer.screenPos.minus(this.lastPointer.screenPos);
+        const dxFromStationaryStart = currentPointer.screenPos.minus(this.stationaryStartPointer.screenPos);
+        // dt: Delta time:
+        // /1000: Convert to s.
+        let dtFromLast = (currentPointer.timeStamp - this.lastPointer.timeStamp) / 1000; // s
+        // Don't divide by zero
+        if (dtFromLast === 0) {
+            dtFromLast = 1;
+        }
+        const currentVelocity = dxFromLast.times(1 / dtFromLast); // px/s
+        // Slight smoothing of the velocity to prevent input jitter from affecting the
+        // velocity too significantly.
+        this.averageVelocity = this.averageVelocity.lerp(currentVelocity, 0.5); // px/s
+        const dtFromStart = currentPointer.timeStamp - this.stationaryStartPointer.timeStamp; // ms
+        // If not stationary
+        if (dxFromStationaryStart.length() > this.config.maxRadius
+            || this.averageVelocity.length() > this.config.maxSpeed
+            || dtFromStart < this.config.minTimeSeconds) {
+            this.stationaryStartPointer = currentPointer;
+            this.lastPointer = currentPointer;
+            this.setStationaryTimeout(this.config.minTimeSeconds * 1000);
+            return false;
+        }
+        const stationaryTimeoutMs = this.config.minTimeSeconds * 1000 - dtFromStart;
+        this.lastPointer = currentPointer;
+        return stationaryTimeoutMs <= 0;
+    }
+    onPointerUp(pointer) {
+        if (pointer.id !== this.stationaryStartPointer?.id) {
+            this.cancelStationaryTimeout();
+        }
+    }
+    destroy() {
+        this.cancelStationaryTimeout();
+        this.stationaryStartPointer = null;
+    }
+    cancelStationaryTimeout() {
+        if (this.timeout !== null) {
+            clearTimeout(this.timeout);
+            this.timeout = null;
+        }
+    }
+    setStationaryTimeout(timeoutMs) {
+        if (this.timeout !== null) {
+            return;
+        }
+        if (timeoutMs <= 0) {
+            this.onStationary(this.lastPointer);
+        }
+        else {
+            this.timeout = setTimeout(() => {
+                this.timeout = null;
+                if (!this.stationaryStartPointer) {
+                    // Destroyed
+                    return;
+                }
+                const timeSinceStationaryStart = performance.now() - this.stationaryStartPointer.timeStamp;
+                const timeRemaining = this.config.minTimeSeconds * 1000 - timeSinceStationaryStart;
+                if (timeRemaining <= 0) {
+                    this.onStationary(this.lastPointer);
+                }
+                else {
+                    this.setStationaryTimeout(timeRemaining);
+                }
+            }, timeoutMs);
+        }
+    }
+}
+exports.default = StationaryPenDetector;

package/dist/cjs/util/ReactiveValue.d.ts

@@ -13,6 +13,8 @@ type UpdateCallback<T> = (value: T) => void;
  *
  * Static methods in the `ReactiveValue` and `MutableReactiveValue` classes are
  * constructors (e.g. `fromImmutable`).
+ *
+ * Avoid extending this class from an external library, as that may not be stable.
  */
 export declare abstract class ReactiveValue<T> {
     /**

package/dist/cjs/util/ReactiveValue.js

@@ -34,6 +34,8 @@ const noOpSetUpdateListener = () => {
  *
  * Static methods in the `ReactiveValue` and `MutableReactiveValue` classes are
  * constructors (e.g. `fromImmutable`).
+ *
+ * Avoid extending this class from an external library, as that may not be stable.
  */
 class ReactiveValue {
     /** Creates a `ReactiveValue` with an initial value, `initialValue`. */

package/dist/cjs/util/lib.d.ts

@@ -1 +1,2 @@
 export { default as adjustEditorThemeForContrast } from './adjustEditorThemeForContrast';
+export { ReactiveValue, MutableReactiveValue } from './ReactiveValue';

package/dist/cjs/util/lib.js

@@ -3,6 +3,9 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.adjustEditorThemeForContrast = void 0;
+exports.MutableReactiveValue = exports.ReactiveValue = exports.adjustEditorThemeForContrast = void 0;
 var adjustEditorThemeForContrast_1 = require("./adjustEditorThemeForContrast");
 Object.defineProperty(exports, "adjustEditorThemeForContrast", { enumerable: true, get: function () { return __importDefault(adjustEditorThemeForContrast_1).default; } });
+var ReactiveValue_1 = require("./ReactiveValue");
+Object.defineProperty(exports, "ReactiveValue", { enumerable: true, get: function () { return ReactiveValue_1.ReactiveValue; } });
+Object.defineProperty(exports, "MutableReactiveValue", { enumerable: true, get: function () { return ReactiveValue_1.MutableReactiveValue; } });

package/dist/cjs/util/waitForImageLoaded.d.ts

@@ -0,0 +1,2 @@
+declare const waitForImageLoad: (image: HTMLImageElement) => Promise<void>;
+export default waitForImageLoad;

package/dist/cjs/util/waitForImageLoaded.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const waitForImageLoad = async (image) => {
+    if (!image.complete) {
+        await new Promise((resolve, reject) => {
+            image.onload = event => resolve(event);
+            image.onerror = event => reject(event);
+            image.onabort = event => reject(event);
+        });
+    }
+};
+exports.default = waitForImageLoad;

package/dist/cjs/version.js

@@ -1,5 +1,5 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.default = {
-    number: '1.9.1',
+    number: '1.11.0',
 };

package/dist/mjs/Editor.d.ts

@@ -156,6 +156,38 @@ export declare class Editor {
     readonly toolController: ToolController;
     /**
      * Global event dispatcher/subscriber.
+     *
+     * @example
+     *
+     * ```ts,runnable
+     * import { Editor, EditorEventType, SerializableCommand } from 'js-draw';
+     *
+     * // Create a minimal editor
+     * const editor = new Editor(document.body);
+     * editor.addToolbar();
+     *
+     * // Create a place to show text output
+     * const log = document.createElement('textarea');
+     * document.body.appendChild(log);
+     * log.style.width = '100%';
+     * log.style.height = '200px';
+     *
+     * // Listen for CommandDone events (there's also a CommandUndone)
+     * editor.notifier.on(EditorEventType.CommandDone, event => {
+     *   // Type narrowing for TypeScript -- event will always be of kind CommandDone,
+     *   // but TypeScript doesn't know this.
+     *   if (event.kind !== EditorEventType.CommandDone) return;
+     *
+     *   log.value = `Command done ${event.command.description(editor, editor.localization)}\n`;
+     *
+     *   if (event.command instanceof SerializableCommand) {
+     *     log.value += `serializes to: ${JSON.stringify(event.command.serialize())}`;
+     *   }
+     * });
+     *
+     * // Dispatch an initial command to trigger the event listener for the first time
+     * editor.dispatch(editor.image.setAutoresizeEnabled(true));
+     * ```
      */
     readonly notifier: EditorNotifier;
     private loadingWarning;
@@ -395,6 +427,12 @@ export declare class Editor {
      * @see {@link sendPenEvent} {@link sendTouchEvent}
      */
     sendPenEvent(eventType: InputEvtType.PointerDownEvt | InputEvtType.PointerMoveEvt | InputEvtType.PointerUpEvt, point: Point2, allPointers?: Pointer[]): void;
+    /**
+     * Adds all components in `components` such that they are in the center of the screen.
+     * This is a convenience method that creates **and applies** a single command.
+     *
+     * If `selectComponents` is true (the default), the components are selected.
+     */
     addAndCenterComponents(components: AbstractComponent[], selectComponents?: boolean): Promise<void>;
     /**
      * Get a data URL (e.g. as produced by `HTMLCanvasElement::toDataURL`).
@@ -403,6 +441,9 @@ export declare class Editor {
      *
      * The export resolution is the same as the size of the drawing canvas, unless `outputSize`
      * is given.
+     *
+     * **Example**:
+     * [[include:doc-pages/inline-examples/adding-an-image-and-data-urls.md]]
      */
     toDataURL(format?: 'image/png' | 'image/jpeg' | 'image/webp', outputSize?: Vec2): string;
     /**

package/dist/mjs/Editor.mjs

@@ -886,6 +886,12 @@ export class Editor {
     allPointers) {
         sendPenEvent(this, eventType, point, allPointers);
     }
+    /**
+     * Adds all components in `components` such that they are in the center of the screen.
+     * This is a convenience method that creates **and applies** a single command.
+     *
+     * If `selectComponents` is true (the default), the components are selected.
+     */
     async addAndCenterComponents(components, selectComponents = true) {
         let bbox = null;
         for (const component of components) {
@@ -932,6 +938,9 @@ export class Editor {
      *
      * The export resolution is the same as the size of the drawing canvas, unless `outputSize`
      * is given.
+     *
+     * **Example**:
+     * [[include:doc-pages/inline-examples/adding-an-image-and-data-urls.md]]
      */
     toDataURL(format = 'image/png', outputSize) {
         const canvas = document.createElement('canvas');

package/dist/mjs/Pointer.mjs

@@ -112,7 +112,7 @@ export default class Pointer {
     // Intended for unit tests.
     static ofCanvasPoint(canvasPos, isDown, viewport, id = 0, device = PointerDevice.Pen, isPrimary = true, pressure = null) {
         const screenPos = viewport.canvasToScreen(canvasPos);
-        const timeStamp = (new Date()).getTime();
+        const timeStamp = performance.now();
         return new Pointer(screenPos, canvasPos, pressure, isPrimary, isDown, device, id, timeStamp);
     }
 }

package/dist/mjs/commands/Erase.d.ts

@@ -5,8 +5,28 @@ import SerializableCommand from './SerializableCommand';
 /**
  * Removes the given {@link AbstractComponent}s from the image.
  *
- * @example
- * ```ts
+ * **Example**:
+ * ```ts,runnable
+ * import { Editor, Erase, uniteCommands, Color4, Path, Stroke, Rect2, pathToRenderable } from 'js-draw';
+ *
+ * const editor = new Editor(document.body);
+ * editor.addToolbar();
+ *
+ * // Add a large number of strokes
+ * const commands = [];
+ * for (let x = -20; x < 20; x++) {
+ *   for (let y = 0; y < 60; y++) {
+ *     const stroke = new Stroke([
+ *       pathToRenderable(
+ *         Path.fromString(`m${x * 5},${y * 5}l1,1`),
+ *         { fill: Color4.transparent, stroke: {width: 2, color: Color4.ofRGB(x / 10, y / 10, 0.5)}} )
+ *       ]);
+ *     commands.push(editor.image.addElement(stroke));
+ *   }
+ * }
+ * await editor.dispatch(uniteCommands(commands, 100));
+ *
+ * ---visible---
  * // Given some editor...
  *
  * // Find all elements intersecting the rectangle with top left (-10,-30) and

package/dist/mjs/commands/Erase.mjs

@@ -5,8 +5,28 @@ import  SerializableCommand  from './SerializableCommand.mjs';
 /**
  * Removes the given {@link AbstractComponent}s from the image.
  *
- * @example
- * ```ts
+ * **Example**:
+ * ```ts,runnable
+ * import { Editor, Erase, uniteCommands, Color4, Path, Stroke, Rect2, pathToRenderable } from 'js-draw';
+ *
+ * const editor = new Editor(document.body);
+ * editor.addToolbar();
+ *
+ * // Add a large number of strokes
+ * const commands = [];
+ * for (let x = -20; x < 20; x++) {
+ *   for (let y = 0; y < 60; y++) {
+ *     const stroke = new Stroke([
+ *       pathToRenderable(
+ *         Path.fromString(`m${x * 5},${y * 5}l1,1`),
+ *         { fill: Color4.transparent, stroke: {width: 2, color: Color4.ofRGB(x / 10, y / 10, 0.5)}} )
+ *       ]);
+ *     commands.push(editor.image.addElement(stroke));
+ *   }
+ * }
+ * await editor.dispatch(uniteCommands(commands, 100));
+ *
+ * ---visible---
  * // Given some editor...
  *
  * // Find all elements intersecting the rectangle with top left (-10,-30) and

package/dist/mjs/commands/invertCommand.mjs

@@ -6,6 +6,11 @@ const invertCommand = (command) => {
     if (command instanceof SerializableCommand) {
         // SerializableCommand that does the inverse of [command]
         return new class extends SerializableCommand {
+            constructor() {
+                super(...arguments);
+                // For debugging
+                this._command = command;
+            }
             serializeToJSON() {
                 return command.serialize();
             }

package/dist/mjs/commands/uniteCommands.d.ts

@@ -1,4 +1,40 @@
 import Command from './Command';
 import SerializableCommand from './SerializableCommand';
+/**
+ * Creates a single command from `commands`. This is useful when undoing should undo *all* commands
+ * in `commands` at once, rather than one at a time.
+ *
+ * @example
+ *
+ * ```ts,runnable
+ * import { Editor, pathToRenderable, Stroke, uniteCommands } from 'js-draw';
+ * import { Path, Color4 } from '@js-draw/math';
+ *
+ * const editor = new Editor(document.body);
+ * editor.addToolbar();
+ *
+ * // Create strokes!
+ * const strokes = [];
+ * for (let i = 0; i < 10; i++) {
+ *   const renderablePath = pathToRenderable(
+ *     Path.fromString(`M0,${i * 10} L100,100 L300,30 z`),
+ *     { fill: Color4.transparent, stroke: { color: Color4.red, width: 1, } }
+ *   );
+ *   strokes.push(new Stroke([ renderablePath ]));
+ * }
+ *
+ * // Convert to commands
+ * const addStrokesCommands = strokes.map(stroke => editor.image.addElement(stroke));
+ *
+ * // Apply all as a single undoable command (try applying each in a loop instead!)
+ * await editor.dispatch(uniteCommands(addStrokesCommands));
+ *
+ * // The second parameter to uniteCommands is for very large numbers of commands, when
+ * // applying them shouldn't be done all at once (which would block the UI).
+ *
+ * // The second parameter to uniteCommands is for very large numbers of commands, when
+ * // applying them shouldn't be done all at once (which would block the UI).
+ * ```
+ */
 declare const uniteCommands: <T extends Command>(commands: T[], applyChunkSize?: number) => T extends SerializableCommand ? SerializableCommand : Command;
 export default uniteCommands;

package/dist/mjs/commands/uniteCommands.mjs

@@ -84,6 +84,42 @@ class SerializableUnion extends SerializableCommand {
         return this.nonserializableCommand.description(editor, localizationTable);
     }
 }
+/**
+ * Creates a single command from `commands`. This is useful when undoing should undo *all* commands
+ * in `commands` at once, rather than one at a time.
+ *
+ * @example
+ *
+ * ```ts,runnable
+ * import { Editor, pathToRenderable, Stroke, uniteCommands } from 'js-draw';
+ * import { Path, Color4 } from '@js-draw/math';
+ *
+ * const editor = new Editor(document.body);
+ * editor.addToolbar();
+ *
+ * // Create strokes!
+ * const strokes = [];
+ * for (let i = 0; i < 10; i++) {
+ *   const renderablePath = pathToRenderable(
+ *     Path.fromString(`M0,${i * 10} L100,100 L300,30 z`),
+ *     { fill: Color4.transparent, stroke: { color: Color4.red, width: 1, } }
+ *   );
+ *   strokes.push(new Stroke([ renderablePath ]));
+ * }
+ *
+ * // Convert to commands
+ * const addStrokesCommands = strokes.map(stroke => editor.image.addElement(stroke));
+ *
+ * // Apply all as a single undoable command (try applying each in a loop instead!)
+ * await editor.dispatch(uniteCommands(addStrokesCommands));
+ *
+ * // The second parameter to uniteCommands is for very large numbers of commands, when
+ * // applying them shouldn't be done all at once (which would block the UI).
+ *
+ * // The second parameter to uniteCommands is for very large numbers of commands, when
+ * // applying them shouldn't be done all at once (which would block the UI).
+ * ```
+ */
 const uniteCommands = (commands, applyChunkSize) => {
     let allSerializable = true;
     for (const command of commands) {

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

@@ -116,6 +116,14 @@ export default abstract class AbstractComponent {
     protected abstract applyTransformation(affineTransfm: Mat33): void;
     transformBy(affineTransfm: Mat33): SerializableCommand;
     setZIndex(newZIndex: number): SerializableCommand;
+    /**
+     * Combines {@link transformBy} and {@link setZIndex} into a single command.
+     *
+     * @param newZIndex - The z-index this component should have after applying this command.
+     * @param originalZIndex - @internal The z-index the component should revert to after unapplying
+     *                         this command.
+     */
+    setZIndexAndTransformBy(affineTransfm: Mat33, newZIndex: number, originalZIndex?: number): SerializableCommand;
     isSelectable(): boolean;
     isBackground(): boolean;
     getProportionalRenderingTime(): number;

package/dist/mjs/components/AbstractComponent.mjs

@@ -138,13 +138,25 @@ class AbstractComponent {
     }
     // 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.
+    //
+    // The transformed component is also moved to the top (use {@link setZIndexAndTransformBy} to
+    // avoid this behavior).
     transformBy(affineTransfm) {
         return new AbstractComponent.TransformElementCommand(affineTransfm, this.getId(), this);
     }
     // Returns a command that updates this component's z-index.
     setZIndex(newZIndex) {
-        return new AbstractComponent.TransformElementCommand(Mat33.identity, this.getId(), this, newZIndex, this.getZIndex());
+        return new AbstractComponent.TransformElementCommand(Mat33.identity, this.getId(), this, newZIndex);
+    }
+    /**
+     * Combines {@link transformBy} and {@link setZIndex} into a single command.
+     *
+     * @param newZIndex - The z-index this component should have after applying this command.
+     * @param originalZIndex - @internal The z-index the component should revert to after unapplying
+     *                         this command.
+     */
+    setZIndexAndTransformBy(affineTransfm, newZIndex, originalZIndex) {
+        return new AbstractComponent.TransformElementCommand(affineTransfm, this.getId(), this, newZIndex, originalZIndex);
     }
     // @returns true iff this component can be selected (e.g. by the selection tool.)
     isSelectable() {
@@ -215,8 +227,12 @@ class AbstractComponent {
             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;
+        if (isFinite(json.zIndex)) {
+            instance.zIndex = json.zIndex;
+            // Ensure that new components will be added on top.
+            AbstractComponent.zIndexCounter = Math.max(AbstractComponent.zIndexCounter, instance.zIndex + 1);
+        }
         // 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.
@@ -225,6 +241,7 @@ class AbstractComponent {
     }
 }
 // Topmost z-index
+// TODO: Should be a property of the EditorImage.
 AbstractComponent.zIndexCounter = 0;
 AbstractComponent.deserializationCallbacks = {};
 AbstractComponent.transformElementCommandId = 'transform-element';
@@ -252,7 +269,7 @@ AbstractComponent.TransformElementCommand = (_a = class extends UnresolvedSerial
             super.resolveComponent(image);
             this.origZIndex ??= this.component.getZIndex();
         }
-        updateTransform(editor, newTransfm) {
+        updateTransform(editor, newTransfm, targetZIndex) {
             if (!this.component) {
                 throw new Error('this.component is undefined or null!');
             }
@@ -264,7 +281,12 @@ AbstractComponent.TransformElementCommand = (_a = class extends UnresolvedSerial
                 hadParent = true;
             }
             this.component.applyTransformation(newTransfm);
+            this.component.zIndex = targetZIndex;
             this.component.lastChangedTime = (new Date()).getTime();
+            // Ensure that new components are automatically drawn above the current component.
+            if (targetZIndex >= AbstractComponent.zIndexCounter) {
+                AbstractComponent.zIndexCounter = targetZIndex + 1;
+            }
             // Add the element back to the document.
             if (hadParent) {
                 EditorImage.addElement(this.component).apply(editor);
@@ -272,14 +294,12 @@ AbstractComponent.TransformElementCommand = (_a = class extends UnresolvedSerial
         }
         apply(editor) {
             this.resolveComponent(editor.image);
-            this.component.zIndex = this.targetZIndex;
-            this.updateTransform(editor, this.affineTransfm);
+            this.updateTransform(editor, this.affineTransfm, this.targetZIndex);
             editor.queueRerender();
         }
         unapply(editor) {
             this.resolveComponent(editor.image);
-            this.component.zIndex = this.origZIndex;
-            this.updateTransform(editor, this.affineTransfm.inverse());
+            this.updateTransform(editor, this.affineTransfm.inverse(), this.origZIndex);
             editor.queueRerender();
         }
         description(_editor, localizationTable) {

package/dist/mjs/components/ImageComponent.d.ts

@@ -2,12 +2,24 @@ import { Mat33Array, Rect2, Mat33, LineSegment2 } from '@js-draw/math';
 import AbstractRenderer, { RenderableImage } from '../rendering/renderers/AbstractRenderer';
 import AbstractComponent from './AbstractComponent';
 import { ImageComponentLocalization } from './localization';
+/**
+ * Represents a raster image.
+ *
+ * **Example: Adding images**:
+ * [[include:doc-pages/inline-examples/adding-an-image-and-data-urls.md]]
+ */
 export default class ImageComponent extends AbstractComponent {
     protected contentBBox: Rect2;
     private image;
     constructor(image: RenderableImage);
     private getImageRect;
     private recomputeBBox;
+    /**
+     * Load from an image. Waits for the image to load if incomplete.
+     *
+     * The image, `elem`, must not [taint](https://developer.mozilla.org/en-US/docs/Web/HTML/CORS_enabled_image#security_and_tainted_canvases)
+     * an HTMLCanvasElement when rendered.
+     */
     static fromImage(elem: HTMLImageElement, transform: Mat33): Promise<ImageComponent>;
     render(canvas: AbstractRenderer, _visibleRect?: Rect2): void;
     getProportionalRenderingTime(): number;

package/dist/mjs/components/ImageComponent.mjs

@@ -1,7 +1,13 @@
 import { Rect2, Mat33 } from '@js-draw/math';
 import  { assertIsNumber, assertIsNumberArray }  from '../util/assertions.mjs';
 import  AbstractComponent  from './AbstractComponent.mjs';
-// Represents a raster image.
+import  waitForImageLoaded  from '../util/waitForImageLoaded.mjs';
+/**
+ * Represents a raster image.
+ *
+ * **Example: Adding images**:
+ * [[include:doc-pages/inline-examples/adding-an-image-and-data-urls.md]]
+ */
 export default class ImageComponent extends AbstractComponent {
     constructor(image) {
         super('image-component');
@@ -24,15 +30,14 @@ export default class ImageComponent extends AbstractComponent {
         this.contentBBox = this.getImageRect();
         this.contentBBox = this.contentBBox.transformedBoundingBox(this.image.transform);
     }
-    // Load from an image. Waits for the image to load if incomplete.
+    /**
+     * Load from an image. Waits for the image to load if incomplete.
+     *
+     * The image, `elem`, must not [taint](https://developer.mozilla.org/en-US/docs/Web/HTML/CORS_enabled_image#security_and_tainted_canvases)
+     * an HTMLCanvasElement when rendered.
+     */
     static async fromImage(elem, transform) {
-        if (!elem.complete) {
-            await new Promise((resolve, reject) => {
-                elem.onload = resolve;
-                elem.onerror = reject;
-                elem.onabort = reject;
-            });
-        }
+        await waitForImageLoaded(elem);
         let width, height;
         if (typeof elem.width === 'number' && typeof elem.height === 'number'
             && elem.width !== 0 && elem.height !== 0) {
@@ -74,6 +79,7 @@ export default class ImageComponent extends AbstractComponent {
         canvas.drawImage(this.image);
         canvas.endObject(this.getLoadSaveData());
     }
+    // A *very* rough estimate of how long it takes to render this component
     getProportionalRenderingTime() {
         // Estimate: Equivalent to a stroke with 10 segments.
         return 10;
@@ -98,6 +104,7 @@ export default class ImageComponent extends AbstractComponent {
     getAltText() {
         return this.image.label;
     }
+    // The base64 image URL of this image.
     getURL() {
         return this.image.base64Url;
     }

package/dist/mjs/components/Stroke.d.ts

@@ -5,7 +5,7 @@ import AbstractRenderer from '../rendering/renderers/AbstractRenderer';
 import AbstractComponent from './AbstractComponent';
 import { ImageComponentLocalization } from './localization';
 import RestyleableComponent, { ComponentStyle } from './RestylableComponent';
-import RenderablePathSpec from '../rendering/RenderablePathSpec';
+import RenderablePathSpec, { RenderablePathSpecWithPath } from '../rendering/RenderablePathSpec';
 /**
  * Represents an {@link AbstractComponent} made up of one or more {@link Path}s.
  *
@@ -21,6 +21,9 @@ import RenderablePathSpec from '../rendering/RenderablePathSpec';
  * ```ts
  * editor.dispatch(stroke.transformBy(Mat33.translation(Vec2.of(10, 0))));
  * ```
+ *
+ * **Adding**:
+ * [[include:doc-pages/inline-examples/adding-a-stroke.md]]
  */
 export default class Stroke extends AbstractComponent implements RestyleableComponent {
     private parts;
@@ -39,7 +42,7 @@ export default class Stroke extends AbstractComponent implements RestyleableComp
      *
      * const stroke = new Stroke([
      *     // Fill with red
-     *     pathToRenderable({ fill: Color4.red })
+     *     pathToRenderable(path, { fill: Color4.red })
      * ]);
      * ```
      */
@@ -57,6 +60,17 @@ export default class Stroke extends AbstractComponent implements RestyleableComp
     private bboxForPart;
     getExactBBox(): Rect2;
     protected applyTransformation(affineTransfm: Mat33): void;
+    /**
+     * @returns A list of the parts that make up this path. Many paths only have one part.
+     *
+     * Each part (a {@link RenderablePathSpec}) contains information about the style and geometry
+     * of that part of the stroke. Use the `.path` property to do collision detection and other
+     * operations involving the stroke's geometry.
+     *
+     * Note that many of {@link Path}'s methods (e.g. {@link Path.intersection}) take a
+     * `strokeWidth` parameter that can be gotten from {@link RenderablePathSpec.style} `.stroke.width`.
+     */
+    getParts(): Readonly<RenderablePathSpecWithPath>[];
     /**
      * @returns the {@link Path.union} of all paths that make up this stroke.
      */