js-draw 0.17.3 → 0.17.4

package/dist/src/Editor.d.ts

@@ -46,6 +46,9 @@ export interface EditorSettings {
  *   // Do something with saveData...
  * });
  * ```
+ *
+ * See also
+ * [`docs/example/example.ts`](https://github.com/personalizedrefrigerator/js-draw/blob/main/docs/example/example.ts#L15).
  */
 export declare class Editor {
     private container;
@@ -123,6 +126,8 @@ export declare class Editor {
      *
      * // Add the default toolbar
      * const toolbar = editor.addToolbar();
+     *
+     * // Add a save button
      * toolbar.addActionButton({
      *   label: 'Save'
      *   icon: createSaveIcon(),
@@ -138,6 +143,7 @@ export declare class Editor {
      *
      * @example
      * ```
+     *   // Set the editor's height to 500px
      *   editor.getRootElement().style.height = '500px';
      * ```
      */
@@ -146,6 +152,10 @@ export declare class Editor {
     showLoadingWarning(fractionLoaded: number): void;
     hideLoadingWarning(): void;
     private previousAccessibilityAnnouncement;
+    /**
+     * Announce `message` for screen readers. If `message` is the same as the previous
+     * message, it is re-announced.
+     */
     announceForAccessibility(message: string): void;
     /**
      * Creates a toolbar. If `defaultLayout` is true, default buttons are used.
@@ -162,6 +172,25 @@ export declare class Editor {
     handleHTMLPointerEvent(eventType: 'pointerdown' | 'pointermove' | 'pointerup' | 'pointercancel', evt: PointerEvent): boolean;
     private isEventSink;
     private handlePaste;
+    /**
+     * Forward pointer events from `elem` to this editor. Such that right-click/right-click drag
+     * events are also forwarded, `elem`'s contextmenu is disabled.
+     *
+     * @example
+     * ```ts
+     * const overlay = document.createElement('div');
+     * editor.createHTMLOverlay(overlay);
+     *
+     * // Send all pointer events that don't have the control key pressed
+     * // to the editor.
+     * editor.handlePointerEventsFrom(overlay, (event) => {
+     *   if (event.ctrlKey) {
+     *     return false;
+     *   }
+     *   return true;
+     * });
+     * ```
+     */
     handlePointerEventsFrom(elem: HTMLElement, filter?: HTMLPointerEventFilter): void;
     /** Adds event listners for keypresses to `elem` and forwards those events to the editor. */
     handleKeyEventsFrom(elem: HTMLElement): void;
@@ -200,25 +229,52 @@ export declare class Editor {
      * Schedule a re-render for some time in the near future. Does not schedule an additional
      * re-render if a re-render is already queued.
      *
-     * @returns a promise that resolves when
+     * @returns a promise that resolves when re-rendering has completed.
      */
     queueRerender(): Promise<void>;
     isRerenderQueued(): boolean;
+    /**
+     * Re-renders the entire image.
+     *
+     * @see {@link Editor.queueRerender}
+     */
     rerender(showImageBounds?: boolean): void;
     /**
+     * Draws the given path onto the wet ink renderer. The given path will
+     * be displayed on top of the main image.
+     *
      * @see {@link Display.getWetInkRenderer} {@link Display.flatten}
      */
     drawWetInk(...path: RenderablePathSpec[]): void;
     /**
+     * Clears the wet ink display.
+     *
      * @see {@link Display.getWetInkRenderer}
      */
     clearWetInk(): void;
+    /**
+     * Focuses the region used for text input/key commands.
+     */
     focus(): void;
+    /**
+     * Creates an element that will be positioned on top of the dry/wet ink
+     * renderers.
+     *
+     * This is useful for displaying content on top of the rendered content
+     * (e.g. a selection box).
+     */
     createHTMLOverlay(overlay: HTMLElement): {
         remove: () => void;
     };
     addStyleSheet(content: string): HTMLStyleElement;
     sendKeyboardEvent(eventType: InputEvtType.KeyPressEvent | InputEvtType.KeyUpEvent, key: string, ctrlKey?: boolean, altKey?: boolean): void;
+    /**
+     * Dispatch a pen event to the currently selected tool.
+     * Intended primarially for unit tests.
+     *
+     * @deprecated
+     * @see {@link sendPenEvent} {@link sendTouchEvent}
+     */
     sendPenEvent(eventType: InputEvtType.PointerDownEvt | InputEvtType.PointerMoveEvt | InputEvtType.PointerUpEvt, point: Point2, allPointers?: Pointer[]): void;
     addAndCenterComponents(components: AbstractComponent[], selectComponents?: boolean): Promise<void>;
     toDataURL(format?: 'image/png' | 'image/jpeg' | 'image/webp'): string;

package/dist/src/Editor.js

@@ -32,6 +32,7 @@ import uniteCommands from './commands/uniteCommands';
 import SelectionTool from './tools/SelectionTool/SelectionTool';
 import Erase from './commands/Erase';
 import ImageBackground, { BackgroundType } from './components/ImageBackground';
+import sendPenEvent from './testing/sendPenEvent';
 /**
  * The main entrypoint for the full editor.
  *
@@ -46,6 +47,9 @@ import ImageBackground, { BackgroundType } from './components/ImageBackground';
  *   // Do something with saveData...
  * });
  * ```
+ *
+ * See also
+ * [`docs/example/example.ts`](https://github.com/personalizedrefrigerator/js-draw/blob/main/docs/example/example.ts#L15).
  */
 export class Editor {
     /**
@@ -62,6 +66,8 @@ export class Editor {
      *
      * // Add the default toolbar
      * const toolbar = editor.addToolbar();
+     *
+     * // Add a save button
      * toolbar.addActionButton({
      *   label: 'Save'
      *   icon: createSaveIcon(),
@@ -156,6 +162,7 @@ export class Editor {
      *
      * @example
      * ```
+     *   // Set the editor's height to 500px
      *   editor.getRootElement().style.height = '500px';
      * ```
      */
@@ -172,8 +179,10 @@ export class Editor {
         this.loadingWarning.style.display = 'none';
         this.announceForAccessibility(this.localization.doneLoading);
     }
-    // Announce `message` for screen readers. If `message` is the same as the previous
-    // message, it is re-announced.
+    /**
+     * Announce `message` for screen readers. If `message` is the same as the previous
+     * message, it is re-announced.
+     */
     announceForAccessibility(message) {
         // Force re-announcing an announcement if announced again.
         if (message === this.previousAccessibilityAnnouncement) {
@@ -424,6 +433,25 @@ export class Editor {
             }
         });
     }
+    /**
+     * Forward pointer events from `elem` to this editor. Such that right-click/right-click drag
+     * events are also forwarded, `elem`'s contextmenu is disabled.
+     *
+     * @example
+     * ```ts
+     * const overlay = document.createElement('div');
+     * editor.createHTMLOverlay(overlay);
+     *
+     * // Send all pointer events that don't have the control key pressed
+     * // to the editor.
+     * editor.handlePointerEventsFrom(overlay, (event) => {
+     *   if (event.ctrlKey) {
+     *     return false;
+     *   }
+     *   return true;
+     * });
+     * ```
+     */
     handlePointerEventsFrom(elem, filter) {
         // May be required to prevent text selection on iOS/Safari:
         // See https://stackoverflow.com/a/70992717/17055750
@@ -560,7 +588,7 @@ export class Editor {
      * Schedule a re-render for some time in the near future. Does not schedule an additional
      * re-render if a re-render is already queued.
      *
-     * @returns a promise that resolves when
+     * @returns a promise that resolves when re-rendering has completed.
      */
     queueRerender() {
         if (!this.rerenderQueued) {
@@ -582,6 +610,11 @@ export class Editor {
     isRerenderQueued() {
         return this.rerenderQueued;
     }
+    /**
+     * Re-renders the entire image.
+     *
+     * @see {@link Editor.queueRerender}
+     */
     rerender(showImageBounds = true) {
         this.display.startRerender();
         // Don't render if the display has zero size.
@@ -601,6 +634,9 @@ export class Editor {
         this.nextRerenderListeners = [];
     }
     /**
+     * Draws the given path onto the wet ink renderer. The given path will
+     * be displayed on top of the main image.
+     *
      * @see {@link Display.getWetInkRenderer} {@link Display.flatten}
      */
     drawWetInk(...path) {
@@ -609,17 +645,26 @@ export class Editor {
         }
     }
     /**
+     * Clears the wet ink display.
+     *
      * @see {@link Display.getWetInkRenderer}
      */
     clearWetInk() {
         this.display.getWetInkRenderer().clear();
     }
-    // Focuses the region used for text input/key commands.
+    /**
+     * Focuses the region used for text input/key commands.
+     */
     focus() {
         this.renderingRegion.focus();
     }
-    // Creates an element that will be positioned on top of the dry/wet ink
-    // renderers.
+    /**
+     * Creates an element that will be positioned on top of the dry/wet ink
+     * renderers.
+     *
+     * This is useful for displaying content on top of the rendered content
+     * (e.g. a selection box).
+     */
     createHTMLOverlay(overlay) {
         overlay.classList.add('overlay');
         this.container.appendChild(overlay);
@@ -643,19 +688,17 @@ export class Editor {
             altKey,
         });
     }
-    // Dispatch a pen event to the currently selected tool.
-    // Intended primarially for unit tests.
+    /**
+     * Dispatch a pen event to the currently selected tool.
+     * Intended primarially for unit tests.
+     *
+     * @deprecated
+     * @see {@link sendPenEvent} {@link sendTouchEvent}
+     */
     sendPenEvent(eventType, point, 
     // @deprecated
     allPointers) {
-        const mainPointer = Pointer.ofCanvasPoint(point, eventType !== InputEvtType.PointerUpEvt, this.viewport);
-        this.toolController.dispatchInputEvent({
-            kind: eventType,
-            allPointers: allPointers !== null && allPointers !== void 0 ? allPointers : [
-                mainPointer,
-            ],
-            current: mainPointer,
-        });
+        sendPenEvent(this, eventType, point, allPointers);
     }
     addAndCenterComponents(components, selectComponents = true) {
         return __awaiter(this, void 0, void 0, function* () {
@@ -717,9 +760,8 @@ export class Editor {
     }
     toSVG() {
         const importExportViewport = this.image.getImportExportViewport().getTemporaryClone();
-        const svgNameSpace = 'http://www.w3.org/2000/svg';
-        const result = document.createElementNS(svgNameSpace, 'svg');
-        const renderer = new SVGRenderer(result, importExportViewport);
+        const sanitize = false;
+        const { element: result, renderer } = SVGRenderer.fromViewport(importExportViewport, sanitize);
         const origTransform = importExportViewport.canvasToScreenTransform;
         // Render with (0,0) at (0,0) — we'll handle translation with
         // the viewBox property.
@@ -731,11 +773,6 @@ export class Editor {
         result.setAttribute('viewBox', [rect.x, rect.y, rect.w, rect.h].map(part => toRoundedString(part)).join(' '));
         result.setAttribute('width', toRoundedString(rect.w));
         result.setAttribute('height', toRoundedString(rect.h));
-        // 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 result;
     }
     /**

package/dist/src/EditorImage.d.ts

@@ -26,8 +26,10 @@ export default class EditorImage {
     /** @internal */
     renderWithCache(screenRenderer: AbstractRenderer, cache: RenderingCache, viewport: Viewport): void;
     /**
-     * Renders all nodes visible from `viewport` (or all nodes if `viewport = null`)
-     * @internal
+     * Renders all nodes visible from `viewport` (or all nodes if `viewport = null`).
+     *
+     * `viewport` is used to improve rendering performance. If given, it must match
+     * the viewport used by the `renderer` (if any).
      */
     render(renderer: AbstractRenderer, viewport: Viewport | null): void;
     /** Renders all nodes, even ones not within the viewport. @internal */

package/dist/src/EditorImage.js

@@ -67,8 +67,10 @@ export default class EditorImage {
         cache.render(screenRenderer, this.root, viewport);
     }
     /**
-     * Renders all nodes visible from `viewport` (or all nodes if `viewport = null`)
-     * @internal
+     * Renders all nodes visible from `viewport` (or all nodes if `viewport = null`).
+     *
+     * `viewport` is used to improve rendering performance. If given, it must match
+     * the viewport used by the `renderer` (if any).
      */
     render(renderer, viewport) {
         this.background.render(renderer, viewport === null || viewport === void 0 ? void 0 : viewport.visibleRect);

package/dist/src/SVGLoader.d.ts

@@ -36,6 +36,10 @@ export default class SVGLoader implements ImageLoader {
     private getSourceAttrs;
     start(onAddComponent: ComponentAddedListener, onProgress: OnProgressListener, onDetermineExportRect?: OnDetermineExportRectListener | null): Promise<void>;
     /**
+     * Create an `SVGLoader` from the content of an SVG image. SVGs are loaded within a sandboxed
+     * iframe with `sandbox="allow-same-origin"`
+     * [thereby disabling JavaScript](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe#sandbox).
+     *
      * @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.

package/dist/src/SVGLoader.js

@@ -387,6 +387,10 @@ export default class SVGLoader {
         });
     }
     /**
+     * Create an `SVGLoader` from the content of an SVG image. SVGs are loaded within a sandboxed
+     * iframe with `sandbox="allow-same-origin"`
+     * [thereby disabling JavaScript](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe#sandbox).
+     *
      * @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.

package/dist/src/lib.d.ts

@@ -1,6 +1,6 @@
 /**
  * The main entrypoint for the NPM package. Everything exported by this file
- * is available through the `js-draw` package.
+ * is available through the [`js-draw` package](https://www.npmjs.com/package/js-draw).
  *
  * @example
  * ```
@@ -26,6 +26,7 @@ export * from './commands/lib';
 export * from './tools/lib';
 export * from './toolbar/lib';
 export * from './rendering/lib';
+export * from './testing/lib';
 export { default as Pointer, PointerDevice } from './Pointer';
 export { default as HTMLToolbar } from './toolbar/HTMLToolbar';
 export { default as UndoRedoHistory } from './UndoRedoHistory';

package/dist/src/lib.js

@@ -1,6 +1,6 @@
 /**
  * The main entrypoint for the NPM package. Everything exported by this file
- * is available through the `js-draw` package.
+ * is available through the [`js-draw` package](https://www.npmjs.com/package/js-draw).
  *
  * @example
  * ```
@@ -26,6 +26,7 @@ export * from './commands/lib';
 export * from './tools/lib';
 export * from './toolbar/lib';
 export * from './rendering/lib';
+export * from './testing/lib';
 export { default as Pointer, PointerDevice } from './Pointer';
 export { default as HTMLToolbar } from './toolbar/HTMLToolbar';
 export { default as UndoRedoHistory } from './UndoRedoHistory';

package/dist/src/rendering/lib.d.ts

@@ -1,3 +1,5 @@
 export { default as AbstractRenderer } from './renderers/AbstractRenderer';
 export { default as DummyRenderer } from './renderers/DummyRenderer';
+export { default as SVGRenderer } from './renderers/SVGRenderer';
+export { default as CanvasRenderer } from './renderers/CanvasRenderer';
 export { default as Display } from './Display';

package/dist/src/rendering/lib.js

@@ -1,3 +1,5 @@
 export { default as AbstractRenderer } from './renderers/AbstractRenderer';
 export { default as DummyRenderer } from './renderers/DummyRenderer';
+export { default as SVGRenderer } from './renderers/SVGRenderer';
+export { default as CanvasRenderer } from './renderers/CanvasRenderer';
 export { default as Display } from './Display';

package/dist/src/rendering/renderers/CanvasRenderer.d.ts

@@ -6,6 +6,26 @@ import Viewport from '../../Viewport';
 import RenderingStyle from '../RenderingStyle';
 import TextStyle from '../TextRenderingStyle';
 import AbstractRenderer, { RenderableImage, RenderablePathSpec } from './AbstractRenderer';
+/**
+ * Renders onto a `CanvasRenderingContext2D`.
+ *
+ * @example
+ * ```ts
+ * const editor = new Editor(document.body);
+ *
+ * const canvas = document.createElement('canvas');
+ * const ctx = canvas.getContext('2d');
+ *
+ * // Ensure that the canvas can fit the entire rendering
+ * const viewport = editor.image.getImportExportViewport();
+ * canvas.width = viewport.getScreenRectSize().x;
+ * canvas.height = viewport.getScreenRectSize().y;
+ *
+ * // Render editor.image onto the renderer
+ * const renderer = new CanvasRenderer(ctx, viewport);
+ * editor.image.render(renderer, viewport);
+ * ```
+ */
 export default class CanvasRenderer extends AbstractRenderer {
     private ctx;
     private ignoreObjectsAboveLevel;
@@ -14,6 +34,11 @@ export default class CanvasRenderer extends AbstractRenderer {
     private minSquareCurveApproxDist;
     private minRenderSizeAnyDimen;
     private minRenderSizeBothDimens;
+    /**
+     * Creates a new `CanvasRenderer` that renders to the given rendering context.
+     * The `viewport` is used to determine the translation/rotation/scaling of the content
+     * to draw.
+     */
     constructor(ctx: CanvasRenderingContext2D, viewport: Viewport);
     private transformBy;
     canRenderFromWithoutDataLoss(other: AbstractRenderer): boolean;

package/dist/src/rendering/renderers/CanvasRenderer.js

@@ -3,7 +3,32 @@ import TextComponent from '../../components/TextComponent';
 import Path from '../../math/Path';
 import { Vec2 } from '../../math/Vec2';
 import AbstractRenderer from './AbstractRenderer';
+/**
+ * Renders onto a `CanvasRenderingContext2D`.
+ *
+ * @example
+ * ```ts
+ * const editor = new Editor(document.body);
+ *
+ * const canvas = document.createElement('canvas');
+ * const ctx = canvas.getContext('2d');
+ *
+ * // Ensure that the canvas can fit the entire rendering
+ * const viewport = editor.image.getImportExportViewport();
+ * canvas.width = viewport.getScreenRectSize().x;
+ * canvas.height = viewport.getScreenRectSize().y;
+ *
+ * // Render editor.image onto the renderer
+ * const renderer = new CanvasRenderer(ctx, viewport);
+ * editor.image.render(renderer, viewport);
+ * ```
+ */
 export default class CanvasRenderer extends AbstractRenderer {
+    /**
+     * Creates a new `CanvasRenderer` that renders to the given rendering context.
+     * The `viewport` is used to determine the translation/rotation/scaling of the content
+     * to draw.
+     */
     constructor(ctx, viewport) {
         super(viewport);
         this.ctx = ctx;
@@ -175,6 +200,7 @@ export default class CanvasRenderer extends AbstractRenderer {
             this.ignoringObject = false;
         }
     }
+    // @internal
     drawPoints(...points) {
         const pointRadius = 10;
         for (let i = 0; i < points.length; i++) {
@@ -191,6 +217,7 @@ export default class CanvasRenderer extends AbstractRenderer {
             this.ctx.fillText(`${i}`, point.x, point.y, pointRadius * 2);
         }
     }
+    // @internal
     isTooSmallToRender(rect) {
         // Should we ignore all objects within this object's bbox?
         const diagonal = this.getCanvasToScreenTransform().transformVec3(rect.size);

package/dist/src/rendering/renderers/SVGRenderer.d.ts

@@ -7,6 +7,11 @@ import RenderingStyle from '../RenderingStyle';
 import TextStyle from '../TextRenderingStyle';
 import AbstractRenderer, { RenderableImage, RenderablePathSpec } from './AbstractRenderer';
 export declare const renderedStylesheetId = "js-draw-style-sheet";
+/**
+ * Renders onto an `SVGElement`.
+ *
+ * @see {@link Editor.toSVG}
+ */
 export default class SVGRenderer extends AbstractRenderer {
     private elem;
     private sanitize;
@@ -14,6 +19,12 @@ export default class SVGRenderer extends AbstractRenderer {
     private lastPathString;
     private objectElems;
     private overwrittenAttrs;
+    /**
+     * 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.
+     */
     constructor(elem: SVGSVGElement, viewport: Viewport, sanitize?: boolean);
     private addStyleSheet;
     setRootSVGAttribute(name: string, value: string | null): void;
@@ -39,4 +50,8 @@ export default class SVGRenderer extends AbstractRenderer {
     drawPoints(...points: Point2[]): void;
     drawSVGElem(elem: SVGElement): void;
     isTooSmallToRender(_rect: Rect2): boolean;
+    static fromViewport(viewport: Viewport, sanitize?: boolean): {
+        element: SVGSVGElement;
+        renderer: SVGRenderer;
+    };
 }

package/dist/src/rendering/renderers/SVGRenderer.js

@@ -6,8 +6,18 @@ import { svgAttributesDataKey, svgStyleAttributesDataKey } from '../../SVGLoader
 import AbstractRenderer 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 {
-    // Renders onto `elem`. If `sanitize`, don't render potentially untrusted data.
+    /**
+     * 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.
+     */
     constructor(elem, viewport, sanitize = false) {
         super(viewport);
         this.elem = elem;
@@ -275,4 +285,20 @@ export default class SVGRenderer extends AbstractRenderer {
     isTooSmallToRender(_rect) {
         return false;
     }
+    // Creates a new SVG element and SVGRenerer with attributes set for the given Viewport.
+    static fromViewport(viewport, sanitize = 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/dist/src/testing/lib.d.ts

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

package/dist/src/testing/lib.js

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

package/dist/src/testing/sendPenEvent.d.ts

@@ -0,0 +1,12 @@
+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}
+ */
+declare const sendPenEvent: (editor: Editor, eventType: InputEvtType.PointerDownEvt | InputEvtType.PointerMoveEvt | InputEvtType.PointerUpEvt, point: Point2, allPointers?: Pointer[]) => void;
+export default sendPenEvent;

package/dist/src/testing/sendPenEvent.js

@@ -0,0 +1,19 @@
+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, eventType, point, allPointers) => {
+    const mainPointer = Pointer.ofCanvasPoint(point, eventType !== InputEvtType.PointerUpEvt, editor.viewport);
+    editor.toolController.dispatchInputEvent({
+        kind: eventType,
+        allPointers: allPointers !== null && allPointers !== void 0 ? allPointers : [
+            mainPointer,
+        ],
+        current: mainPointer,
+    });
+};
+export default sendPenEvent;

package/dist/src/testing/sendTouchEvent.d.ts

@@ -2,5 +2,41 @@ import Editor from '../Editor';
 import { Vec2 } from '../math/Vec2';
 import Pointer 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 ]);
+ * }
+ * ```
+ */
 declare const sendTouchEvent: (editor: Editor, eventType: InputEvtType.PointerDownEvt | InputEvtType.PointerMoveEvt | InputEvtType.PointerUpEvt, screenPos: Vec2, allOtherPointers?: Pointer[]) => Pointer;
 export default sendTouchEvent;