js-draw 1.21.2 → 1.22.0

package/dist/mjs/tools/InputFilter/ContextMenuRecognizer.d.ts

@@ -0,0 +1,17 @@
+import { InputEvt } from '../../inputEvents';
+import InputMapper from './InputMapper';
+export default class ContextMenuRecognizer extends InputMapper {
+    private canShowContextMenu;
+    private contextMenuTriggerPointer;
+    private contextMenuStartPoint;
+    private stationaryDetector;
+    private clickTolerance;
+    constructor();
+    /**
+     * In general, only certain events (i.e. touchscreens) are expected to be able to
+     * create long-press menus. This method checks whether `event` was generated by
+     * one such device.
+     */
+    private canMakeLongPressMenuEvent;
+    onEvent(event: InputEvt): boolean;
+}

package/dist/mjs/tools/InputFilter/ContextMenuRecognizer.mjs

@@ -0,0 +1,74 @@
+import  { InputEvtType, isPointerEvt }  from '../../inputEvents.mjs';
+import  InputMapper  from './InputMapper.mjs';
+import  StationaryPenDetector, { defaultStationaryDetectionConfig, }  from '../util/StationaryPenDetector.mjs';
+import  { PointerDevice }  from '../../Pointer.mjs';
+export default class ContextMenuRecognizer extends InputMapper {
+    constructor() {
+        super();
+        this.canShowContextMenu = false;
+        this.stationaryDetector = null;
+        this.clickTolerance = 12;
+    }
+    /**
+     * In general, only certain events (i.e. touchscreens) are expected to be able to
+     * create long-press menus. This method checks whether `event` was generated by
+     * one such device.
+     */
+    canMakeLongPressMenuEvent(event) {
+        const allowedDevices = [PointerDevice.Touch];
+        return event.allPointers.length === 1 && allowedDevices.includes(event.current.device);
+    }
+    onEvent(event) {
+        const sendContextMenuEvent = () => {
+            if (!isPointerEvt(event))
+                return false;
+            if (this.canShowContextMenu) {
+                const eventHandled = this.emit({
+                    kind: InputEvtType.ContextMenu,
+                    screenPos: event.current.screenPos,
+                    canvasPos: event.current.canvasPos,
+                });
+                if (eventHandled) {
+                    this.emit({
+                        kind: InputEvtType.GestureCancelEvt,
+                    });
+                    return true;
+                }
+            }
+            return false;
+        };
+        if (event.kind === InputEvtType.PointerDownEvt) {
+            if (event.allPointers.length === 1) {
+                this.canShowContextMenu = true;
+                this.contextMenuTriggerPointer = event.current;
+                this.contextMenuStartPoint = event.current.screenPos;
+                if (this.canMakeLongPressMenuEvent(event)) {
+                    this.stationaryDetector = new StationaryPenDetector(event.current, defaultStationaryDetectionConfig, sendContextMenuEvent);
+                }
+            }
+            else {
+                this.canShowContextMenu = false;
+            }
+        }
+        else if (event.kind === InputEvtType.PointerMoveEvt) {
+            if (this.canShowContextMenu) {
+                this.stationaryDetector?.onPointerMove(event.current);
+                // Only clicks/stationary long presses can create context menu events.
+                const deltaPosition = event.current.screenPos.minus(this.contextMenuStartPoint);
+                const threshold = this.clickTolerance;
+                if (deltaPosition.length() > threshold) {
+                    this.canShowContextMenu = false;
+                }
+            }
+        }
+        else if (event.kind === InputEvtType.PointerUpEvt) {
+            this.stationaryDetector?.destroy();
+            if (this.contextMenuTriggerPointer?.id === event.current.id &&
+                this.contextMenuTriggerPointer.device === PointerDevice.RightButtonMouse &&
+                sendContextMenuEvent()) {
+                return true;
+            }
+        }
+        return this.emit(event);
+    }
+}

package/dist/mjs/tools/InputFilter/ContextMenuRecognizer.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/mjs/tools/InputFilter/FunctionMapper.d.ts

@@ -0,0 +1,12 @@
+import { InputEvt } from '../../inputEvents';
+import InputMapper from './InputMapper';
+/**
+ * An `InputMapper` that applies a function to all events it receives.
+ *
+ * Useful for automated testing.
+ */
+export default class FunctionMapper extends InputMapper {
+    private fn;
+    constructor(fn: (event: InputEvt) => InputEvt);
+    onEvent(event: InputEvt): boolean;
+}

package/dist/mjs/tools/InputFilter/FunctionMapper.mjs

@@ -0,0 +1,15 @@
+import  InputMapper  from './InputMapper.mjs';
+/**
+ * An `InputMapper` that applies a function to all events it receives.
+ *
+ * Useful for automated testing.
+ */
+export default class FunctionMapper extends InputMapper {
+    constructor(fn) {
+        super();
+        this.fn = fn;
+    }
+    onEvent(event) {
+        return this.emit(this.fn(event));
+    }
+}

package/dist/mjs/tools/InputFilter/InputMapper.d.ts

@@ -0,0 +1,23 @@
+import { InputEvt } from '../../inputEvents';
+type OnEventCallback = (event: InputEvt) => boolean;
+export interface InputEventListener {
+    onEvent: OnEventCallback;
+}
+/**
+ * Accepts input events and emits input events.
+ */
+export default abstract class InputMapper implements InputEventListener {
+    #private;
+    constructor();
+    setEmitListener(listener: InputEventListener | OnEventCallback | null): void;
+    protected emit(event: InputEvt): boolean;
+    /**
+     * @returns true if the given `event` should be considered "handled" by the app and thus not
+     * forwarded to other targets. For example, returning "true" for a touchpad pinch event prevents
+     * the pinch event from zooming the webpage.
+     *
+     * Generally, this should return the result of calling `this.emit` with some event.
+     */
+    abstract onEvent(event: InputEvt): boolean;
+}
+export {};

package/dist/mjs/tools/InputFilter/InputMapper.mjs

@@ -0,0 +1,36 @@
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var _InputMapper_listener;
+/**
+ * Accepts input events and emits input events.
+ */
+class InputMapper {
+    constructor() {
+        _InputMapper_listener.set(this, null);
+    }
+    // @internal
+    setEmitListener(listener) {
+        if (listener && typeof listener === 'object') {
+            __classPrivateFieldSet(this, _InputMapper_listener, (event) => {
+                return listener.onEvent(event) ?? false;
+            }, "f");
+        }
+        else {
+            __classPrivateFieldSet(this, _InputMapper_listener, listener, "f");
+        }
+    }
+    emit(event) {
+        return __classPrivateFieldGet(this, _InputMapper_listener, "f")?.call(this, event) ?? false;
+    }
+}
+_InputMapper_listener = new WeakMap();
+export default InputMapper;

package/dist/mjs/tools/InputFilter/InputPipeline.d.ts

@@ -0,0 +1,15 @@
+import { InputEvt } from '../../inputEvents';
+import InputMapper from './InputMapper';
+/**
+ * The composition of multiple `InputMapper`s.
+ */
+export default class InputPipeline extends InputMapper {
+    #private;
+    onEvent(event: InputEvt): boolean;
+    /**
+     * Adds a new `InputMapper` to the *tail* of this pipeline.
+     * Note that an instance of an `InputMapper` can only be used in a single
+     * pipeline.
+     */
+    addToTail(mapper: InputMapper): void;
+}

package/dist/mjs/tools/InputFilter/InputPipeline.mjs

@@ -0,0 +1,49 @@
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+var _InputPipeline_head, _InputPipeline_tail;
+import  InputMapper  from './InputMapper.mjs';
+/**
+ * The composition of multiple `InputMapper`s.
+ */
+class InputPipeline extends InputMapper {
+    constructor() {
+        super(...arguments);
+        _InputPipeline_head.set(this, null);
+        _InputPipeline_tail.set(this, null);
+    }
+    onEvent(event) {
+        if (__classPrivateFieldGet(this, _InputPipeline_head, "f") === null) {
+            return this.emit(event);
+        }
+        else {
+            return __classPrivateFieldGet(this, _InputPipeline_head, "f").onEvent(event);
+        }
+    }
+    /**
+     * Adds a new `InputMapper` to the *tail* of this pipeline.
+     * Note that an instance of an `InputMapper` can only be used in a single
+     * pipeline.
+     */
+    addToTail(mapper) {
+        if (!__classPrivateFieldGet(this, _InputPipeline_tail, "f")) {
+            __classPrivateFieldSet(this, _InputPipeline_head, mapper, "f");
+            __classPrivateFieldSet(this, _InputPipeline_tail, __classPrivateFieldGet(this, _InputPipeline_head, "f"), "f");
+        }
+        else {
+            __classPrivateFieldGet(this, _InputPipeline_tail, "f").setEmitListener(mapper);
+            __classPrivateFieldSet(this, _InputPipeline_tail, mapper, "f");
+        }
+        __classPrivateFieldGet(this, _InputPipeline_tail, "f").setEmitListener((event) => this.emit(event));
+    }
+}
+_InputPipeline_head = new WeakMap(), _InputPipeline_tail = new WeakMap();
+export default InputPipeline;

package/dist/mjs/tools/InputFilter/InputPipeline.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/mjs/tools/InputFilter/InputStabilizer.d.ts

@@ -0,0 +1,29 @@
+import { InputEvt } from '../../inputEvents';
+import InputMapper from './InputMapper';
+import Viewport from '../../Viewport';
+import Editor from '../../Editor';
+declare enum StabilizerType {
+    IntertialStabilizer = 0
+}
+interface InputStabilizerOptions {
+    kind: StabilizerType.IntertialStabilizer;
+    mass: number;
+    springConstant: number;
+    frictionCoefficient: number;
+    maxPointDist: number;
+    minSimilarityToFinalize: number;
+    inertiaFraction: number;
+    velocityDecayFactor: number;
+}
+export default class InputStabilizer extends InputMapper {
+    private viewport;
+    private readonly options;
+    private stabilizer;
+    private lastPointerEvent;
+    constructor(viewport: Viewport, options?: InputStabilizerOptions);
+    private mapPointerEvent;
+    private emitPointerMove;
+    onEvent(event: InputEvt): boolean;
+    static fromEditor(editor: Editor): InputStabilizer;
+}
+export {};

package/dist/mjs/tools/InputFilter/InputStabilizer.mjs

@@ -0,0 +1,182 @@
+import  { InputEvtType, isPointerEvt, }  from '../../inputEvents.mjs';
+import  InputMapper  from './InputMapper.mjs';
+import { Vec2 } from '@js-draw/math';
+import  untilNextAnimationFrame  from '../../util/untilNextAnimationFrame.mjs';
+var StabilizerType;
+(function (StabilizerType) {
+    StabilizerType[StabilizerType["IntertialStabilizer"] = 0] = "IntertialStabilizer";
+})(StabilizerType || (StabilizerType = {}));
+const defaultOptions = {
+    kind: StabilizerType.IntertialStabilizer,
+    mass: 0.4, // kg
+    springConstant: 100.0, // N/m
+    frictionCoefficient: 0.28,
+    maxPointDist: 10, // screen units
+    inertiaFraction: 0.75,
+    minSimilarityToFinalize: 0.0,
+    velocityDecayFactor: 0.1,
+};
+// Stabilizes input for a single cursor
+class StylusInputStabilizer {
+    constructor(
+    // The initial starting point of the pointer.
+    start, 
+    // Emits a pointer motion event, returns true if the event was handled.
+    updatePointer, options) {
+        this.updatePointer = updatePointer;
+        this.options = options;
+        this.runLoop = true;
+        this.lastUpdateTime = 0;
+        this.velocity = Vec2.zero;
+        this.strokePoint = start;
+        this.targetPoint = start;
+        this.targetInterval = 10; // ms
+        void this.loop();
+    }
+    async loop() {
+        this.lastUpdateTime = performance.now();
+        while (this.runLoop) {
+            this.update(false);
+            await untilNextAnimationFrame();
+        }
+    }
+    setTarget(point) {
+        this.targetPoint = point;
+    }
+    getNextVelocity(deltaTimeMs) {
+        const toTarget = this.targetPoint.minus(this.strokePoint);
+        const springForce = toTarget.times(this.options.springConstant);
+        const gravityAccel = 10;
+        const normalForceMagnitude = this.options.mass * gravityAccel;
+        const frictionForce = this.velocity
+            .normalizedOrZero()
+            .times(-this.options.frictionCoefficient * normalForceMagnitude);
+        const acceleration = springForce.plus(frictionForce).times(1 / this.options.mass);
+        const decayFactor = this.options.velocityDecayFactor;
+        const springVelocity = this.velocity
+            .times(1 - decayFactor)
+            .plus(acceleration.times(deltaTimeMs / 1000));
+        // An alternate velocity that goes directly towards the target.
+        const toTargetVelocity = toTarget.normalizedOrZero().times(springVelocity.length());
+        return toTargetVelocity.lerp(springVelocity, this.options.inertiaFraction);
+    }
+    update(force) {
+        const nowTime = performance.now();
+        const deltaTime = nowTime - this.lastUpdateTime;
+        const reachedTarget = this.strokePoint.eq(this.targetPoint);
+        if (deltaTime > this.targetInterval || force) {
+            if (!reachedTarget) {
+                let velocity;
+                let deltaX;
+                let parts = 1;
+                do {
+                    velocity = this.getNextVelocity(deltaTime / parts);
+                    deltaX = velocity.times(deltaTime / 1000);
+                    parts++;
+                } while (deltaX.magnitude() > this.options.maxPointDist && parts < 10);
+                for (let i = 0; i < parts; i++) {
+                    this.velocity = this.getNextVelocity(deltaTime / parts);
+                    deltaX = this.velocity.times(deltaTime / 1000);
+                    this.strokePoint = this.strokePoint.plus(deltaX);
+                    // Allows the last updatePointer to be returned.
+                    if (i < parts - 1) {
+                        this.updatePointer(this.strokePoint, nowTime);
+                    }
+                }
+            }
+            // Even if we have reached the target, ensure that lastUpdateTime is updated
+            // (prevent large deltaTime).
+            this.lastUpdateTime = nowTime;
+            if (force || !reachedTarget) {
+                return this.updatePointer(this.strokePoint, nowTime);
+            }
+        }
+        return false;
+    }
+    /** Finalizes the current stroke. */
+    finish() {
+        this.runLoop = false;
+        const toTarget = this.targetPoint.minus(this.strokePoint);
+        if (this.velocity.dot(toTarget) > this.options.minSimilarityToFinalize) {
+            // Connect the stroke to its end point
+            this.updatePointer(this.targetPoint, performance.now());
+        }
+    }
+    cancel() {
+        this.runLoop = false;
+    }
+}
+export default class InputStabilizer extends InputMapper {
+    constructor(viewport, options = defaultOptions) {
+        super();
+        this.viewport = viewport;
+        this.options = options;
+        this.stabilizer = null;
+        this.lastPointerEvent = null;
+    }
+    mapPointerEvent(event) {
+        // Don't store the last pointer event for use with pressure/button data --
+        // this information can be very different for a pointerup event.
+        if (isPointerEvt(event) && event.kind !== InputEvtType.PointerUpEvt) {
+            this.lastPointerEvent = event;
+        }
+        // Only apply smoothing if there is a single pointer.
+        if (event.kind === InputEvtType.GestureCancelEvt ||
+            event.allPointers.length > 1 ||
+            this.stabilizer === null) {
+            return this.emit(event);
+        }
+        this.stabilizer.setTarget(event.current.screenPos);
+        if (event.kind === InputEvtType.PointerMoveEvt) {
+            return this.stabilizer.update(true);
+        }
+        else if (event.kind === InputEvtType.PointerUpEvt) {
+            this.stabilizer.finish();
+            return this.emit(event);
+        }
+        else {
+            return this.emit(event);
+        }
+    }
+    // Assumes that there is exactly one pointer that is currently down.
+    emitPointerMove(screenPoint, timeStamp) {
+        if (!this.lastPointerEvent) {
+            return false;
+        }
+        const pointer = this.lastPointerEvent.current
+            .withScreenPosition(screenPoint, this.viewport)
+            .withTimestamp(timeStamp);
+        const event = {
+            kind: InputEvtType.PointerMoveEvt,
+            current: pointer,
+            allPointers: [pointer],
+        };
+        const handled = this.emit(event);
+        return handled;
+    }
+    onEvent(event) {
+        if (isPointerEvt(event) || event.kind === InputEvtType.GestureCancelEvt) {
+            if (event.kind === InputEvtType.PointerDownEvt) {
+                if (this.stabilizer === null) {
+                    this.stabilizer = new StylusInputStabilizer(event.current.screenPos, (screenPoint, timeStamp) => this.emitPointerMove(screenPoint, timeStamp), this.options);
+                }
+                else if (event.allPointers.length > 1) {
+                    // Do not attempt to stabilize multiple pointers.
+                    this.stabilizer.cancel();
+                    this.stabilizer = null;
+                }
+            }
+            const handled = this.mapPointerEvent(event);
+            if (event.kind === InputEvtType.PointerUpEvt ||
+                event.kind === InputEvtType.GestureCancelEvt) {
+                this.stabilizer?.cancel();
+                this.stabilizer = null;
+            }
+            return handled;
+        }
+        return this.emit(event);
+    }
+    static fromEditor(editor) {
+        return new InputStabilizer(editor.viewport);
+    }
+}

package/dist/mjs/tools/InputFilter/StrokeKeyboardControl.d.ts

@@ -0,0 +1,21 @@
+import { InputEvt } from '../../inputEvents';
+import InputMapper from './InputMapper';
+import KeyboardShortcutManager from '../../shortcuts/KeyboardShortcutManager';
+import Viewport from '../../Viewport';
+import Editor from '../../Editor';
+/**
+ * Provides keyboard shortcuts that provide some amount of control over
+ * drawing (e.g. snap to grid, plane lock).
+ */
+export default class StrokeKeyboardControl extends InputMapper {
+    private shortcuts;
+    private viewport;
+    private snapToGridEnabled;
+    private angleLockEnabled;
+    private startPointCanvas;
+    constructor(shortcuts: KeyboardShortcutManager, viewport: Viewport);
+    private xyAxesSnap;
+    private mapPointerEvent;
+    onEvent(event: InputEvt): boolean;
+    static fromEditor(editor: Editor): StrokeKeyboardControl;
+}

package/dist/mjs/tools/InputFilter/StrokeKeyboardControl.mjs

@@ -0,0 +1,81 @@
+import  { InputEvtType }  from '../../inputEvents.mjs';
+import  InputMapper  from './InputMapper.mjs';
+import  { lineLockKeyboardShortcutId, snapToGridKeyboardShortcutId }  from '../keybindings.mjs';
+/**
+ * Provides keyboard shortcuts that provide some amount of control over
+ * drawing (e.g. snap to grid, plane lock).
+ */
+export default class StrokeKeyboardControl extends InputMapper {
+    constructor(shortcuts, viewport) {
+        super();
+        this.shortcuts = shortcuts;
+        this.viewport = viewport;
+        this.snapToGridEnabled = false;
+        this.angleLockEnabled = false;
+        // The point at which the last pointerDown event happened (or null if
+        // no such event has occurred).
+        this.startPointCanvas = null;
+    }
+    // Snap the given pointer to the nearer of the x/y axes.
+    xyAxesSnap(pointer) {
+        if (!this.startPointCanvas) {
+            return pointer;
+        }
+        // Convert this.startPointCanvas here because the viewport might change
+        // while drawing a stroke.
+        const screenPos = this.viewport.canvasToScreen(this.startPointCanvas);
+        return pointer.lockedToXYAxesScreen(screenPos, this.viewport);
+    }
+    mapPointerEvent(event) {
+        const mapPointer = (pointer) => {
+            // Only map if there's exactly one pointer.
+            if (event.allPointers.length > 1) {
+                return pointer;
+            }
+            if (this.snapToGridEnabled) {
+                return pointer.snappedToGrid(this.viewport);
+            }
+            if (this.angleLockEnabled && this.startPointCanvas) {
+                return this.xyAxesSnap(pointer);
+            }
+            return pointer;
+        };
+        return {
+            kind: event.kind,
+            current: mapPointer(event.current),
+            allPointers: event.allPointers.map(mapPointer),
+        };
+    }
+    onEvent(event) {
+        const shortcuts = this.shortcuts;
+        if (event.kind === InputEvtType.PointerDownEvt ||
+            event.kind === InputEvtType.PointerMoveEvt ||
+            event.kind === InputEvtType.PointerUpEvt) {
+            if (event.kind === InputEvtType.PointerDownEvt) {
+                this.startPointCanvas = event.current.canvasPos;
+            }
+            event = this.mapPointerEvent(event);
+        }
+        let handled = this.emit(event);
+        if (
+        // Always check keyUpEvents (in case we handled the corresponding keyDown event)
+        event.kind === InputEvtType.KeyUpEvent ||
+            // Only handle key press events if another tool isn't handling it. We don't want
+            // snap to grid/angle lock to conflict with selection/another tool's shortcuts.
+            (!handled && event.kind === InputEvtType.KeyPressEvent)) {
+            const isKeyPress = event.kind === InputEvtType.KeyPressEvent;
+            if (shortcuts.matchesShortcut(snapToGridKeyboardShortcutId, event)) {
+                this.snapToGridEnabled = isKeyPress;
+                handled = true;
+            }
+            if (shortcuts.matchesShortcut(lineLockKeyboardShortcutId, event)) {
+                this.angleLockEnabled = isKeyPress;
+                handled = true;
+            }
+        }
+        return handled;
+    }
+    static fromEditor(editor) {
+        return new StrokeKeyboardControl(editor.shortcuts, editor.viewport);
+    }
+}