@opsydyn/effect-three 0.3.0 → 0.6.4

package/src/kernel/pointer.ts

@@ -26,10 +26,15 @@ export type Modifiers = {
   readonly alt: boolean;
 };
 
+/** What pressed: `PointerEvent.pointerType`. A finger is less steady than a mouse or pen. */
+export type PointerDevice = 'mouse' | 'pen' | 'touch';
+
 /**
  * Pointer input in normalised device coordinates. `button` follows `MouseEvent.button`.
  * `pointer` is the input's `PointerEvent.pointerId` (0 when absent): with two pointers
- * pressed (two fingers), the second only takes part in pinches.
+ * pressed (two fingers), the second only takes part in pinches. A press's `device` is
+ * what pressed (a mouse when absent); it decides how far a press may travel and still be
+ * a click on nothing.
  */
 export type PointerInput =
   | {
@@ -45,6 +50,7 @@ export type PointerInput =
       readonly button: number;
       readonly pointer?: number;
       readonly modifiers?: Modifiers;
+      readonly device?: PointerDevice;
     }
   | {
       readonly _tag: 'PointerUp';
@@ -209,6 +215,18 @@ export type SceneEvent =
     }
   /** A drag, wheel or pinch on the canvas, when the scene claims gestures. */
   | { readonly _tag: 'Gesture'; readonly gesture: Gesture }
+  /**
+   * A gesture that moved has ended: released, or the pointer left. Only after a `Drag`
+   * or `Pinch`, with the press's button, modifiers, mesh and view: the moment to finish
+   * what the gesture drew, such as a selection box.
+   */
+  | {
+      readonly _tag: 'GestureEnd';
+      readonly button: number;
+      readonly modifiers: Modifiers;
+      readonly key?: string;
+      readonly view?: string;
+    }
   /**
    * A gesture is about to begin on a camera that has turned by itself (`autoRotate`):
    * where it got to, so the Model can keep it (`autoRotated(camera, detail)`) and the
@@ -273,6 +291,19 @@ export type SceneEvent =
       readonly maxForceDirection: Vec3;
       readonly maxForceMagnitude: number;
     }
+  /**
+   * A world on `physics({ until })` reached that step and waits there: its run, its
+   * step count, and a checksum of every body's pose, which peers running the same inputs
+   * share (ADR-014). It comes after the collisions of the steps that led there. At
+   * `physics({ snapshotAt })` it carries a snapshot of the world, to start another `from`.
+   */
+  | {
+      readonly _tag: 'PhysicsReached';
+      readonly run: number;
+      readonly step: number;
+      readonly checksum: string;
+      readonly snapshot?: string;
+    }
   /**
    * A measured label's laid-out size changed (`scene({ measure })`, after its glyphs are
    * laid out): in its own units, before its scale, for sizing what goes behind it, as
@@ -405,14 +436,17 @@ export const createPicker = (graph: SceneGraph): Picker => {
   const rayOrigin = new Vector3();
   const rayDirection = new Vector3();
 
-  /** The nearest keyed hit along the raycaster's ray, reporting `view` when there is one. */
-  const nearestHit = (view: string | undefined): Hit | undefined => {
+  /**
+   * The nearest keyed hit in `on` (the scene's graph or its HUD's) along the raycaster's
+   * ray, reporting `view` when there is one.
+   */
+  const nearestHit = (on: SceneGraph, view: string | undefined): Hit | undefined => {
     // Recursive, so an interactive group makes every mesh inside it pickable.
-    for (const intersection of raycaster.intersectObjects(graph.interactiveObjects(), true)) {
+    for (const intersection of raycaster.intersectObjects(on.interactiveObjects(), true)) {
       // Hidden things are not hit: a level of detail not showing, as three's `LOD.raycast`.
       if (!shown(intersection.object)) continue;
-      const owner = keyedOwner(graph, intersection.object);
-      const key = owner === undefined ? undefined : graph.keyOf(owner);
+      const owner = keyedOwner(on, intersection.object);
+      const key = owner === undefined ? undefined : on.keyOf(owner);
       if (owner !== undefined && key !== undefined) {
         normal.set(0, 0, 0);
         if (intersection.face) {
@@ -421,13 +455,13 @@ export const createPicker = (graph: SceneGraph): Picker => {
         const instance =
           intersection.instanceId === undefined
             ? undefined
-            : graph.instanceKeyOf(intersection.object, intersection.instanceId);
+            : on.instanceKeyOf(intersection.object, intersection.instanceId);
         return {
           key,
           ...(instance === undefined ? {} : { instance }),
           ...partOf(owner, intersection.object),
           ...(view === undefined ? {} : { view }),
-          path: pathOf(graph, owner),
+          path: pathOf(on, owner),
           point: toVec3(intersection.point),
           distance: intersection.distance,
           normal: toVec3(normal),
@@ -439,6 +473,17 @@ export const createPicker = (graph: SceneGraph): Picker => {
     return undefined;
   };
 
+  /** A hit on the HUD's interactive meshes, which are over everything else. */
+  const hudHit = (x: number, y: number): Hit | undefined => {
+    const hud = graph.hud();
+    if (hud === undefined || hud.graph.interactiveObjects().length === 0) return undefined;
+    hud.graph.scene.updateMatrixWorld();
+    hud.graph.camera.updateMatrixWorld();
+    ndc.set(x, y);
+    raycaster.setFromCamera(ndc, hud.graph.camera);
+    return nearestHit(hud.graph, undefined);
+  };
+
   const currentRay = (): Ray => ({
     origin: toVec3(raycaster.ray.origin),
     direction: toVec3(raycaster.ray.direction),
@@ -472,10 +517,12 @@ export const createPicker = (graph: SceneGraph): Picker => {
     holdCameras: graph.holdCameras,
     turned: graph.turned,
     pick: (x, y) => {
+      const hud = hudHit(x, y);
+      if (hud !== undefined) return hud;
       if (graph.interactiveObjects().length === 0) return undefined;
       const view = aim(x, y);
       if (view === false) return undefined;
-      return nearestHit(view);
+      return nearestHit(graph, view);
     },
     pickRay: (ray) => {
       if (graph.interactiveObjects().length === 0) return undefined;
@@ -484,7 +531,7 @@ export const createPicker = (graph: SceneGraph): Picker => {
         rayOrigin.fromArray(ray.origin),
         rayDirection.fromArray(ray.direction).normalize(),
       );
-      return nearestHit(undefined);
+      return nearestHit(graph, undefined);
     },
     viewport: graph.viewport,
   };
@@ -502,14 +549,24 @@ export type PointerTracker = {
 
 const none: ReadonlyArray<SceneEvent> = [];
 
-/** A click moving further than this, in CSS pixels, is a drag and never a miss. */
-const missTolerance = 2;
+/**
+ * How far, in CSS pixels, a press on nothing may travel and still be a miss rather than a
+ * drag. React Three Fiber allows 2 (`events.ts`, `delta <= 2`, at pinned `d74622e`), but
+ * measures it on the browser's `click`, which a browser only synthesises from a tap that
+ * kept within its own, larger touch slop. This kernel works from pointer down and up, so
+ * it gives a finger its own allowance: a steady tap wanders a few pixels, a drag far more.
+ */
+const missTolerances = { mouse: 2, pen: 2, touch: 10 } as const satisfies Record<
+  PointerDevice,
+  number
+>;
 
 type Press = {
   readonly key: string | undefined;
   readonly button: number;
   readonly x: number;
   readonly y: number;
+  readonly device: PointerDevice;
 };
 
 /** The press a gesture began with: its button, modifiers, mesh and region. */
@@ -532,6 +589,8 @@ export const createPointerTracker = (picker: Picker): PointerTracker => {
   const pressedPointers = new Map<number, Point>();
   let primary: number | undefined;
   let gesturePress: GesturePress | undefined;
+  // Whether the gesture press has moved: only then does its release end a gesture.
+  let gestureMoved = false;
   let hovered: string | undefined;
   // The latest press, kept after release: double-click and context-menu events follow it.
   let press: Press | undefined;
@@ -569,7 +628,10 @@ export const createPointerTracker = (picker: Picker): PointerTracker => {
       }
       return;
     }
-    if (from?.button === event.button && travel(from, event.x, event.y) <= missTolerance) {
+    if (
+      from?.button === event.button &&
+      travel(from, event.x, event.y) <= missTolerances[from.device]
+    ) {
       events.push({ _tag: 'PointerMissed', button: event.button });
     }
   };
@@ -624,6 +686,7 @@ export const createPointerTracker = (picker: Picker): PointerTracker => {
     pressedPointers.clear();
     primary = id;
     pressedPointers.set(id, { x: event.x, y: event.y });
+    gestureMoved = false;
     const region = picker.region(event.x, event.y);
     reportTurned(region, events);
     // Cameras turning by themselves hold still while it is pressed, as `OrbitControls`.
@@ -641,6 +704,7 @@ export const createPointerTracker = (picker: Picker): PointerTracker => {
     const from = pressedPointers.get(id);
     if (from === undefined || gesturePress === undefined) return;
     pressedPointers.set(id, to);
+    gestureMoved = true;
     const { view, width, height, x, y } = gesturePress;
     const region = { ...(view === undefined ? {} : { view }), width, height, x, y };
     const moved = pixels(from, to);
@@ -680,11 +744,22 @@ export const createPointerTracker = (picker: Picker): PointerTracker => {
     });
   };
 
-  const endGestures = (): void => {
+  const endGestures = (events: Array<SceneEvent>): void => {
     if (gesturePress !== undefined) picker.holdCameras(false);
+    if (gesturePress !== undefined && gestureMoved) {
+      const { button, modifiers, key, view } = gesturePress;
+      events.push({
+        _tag: 'GestureEnd',
+        button,
+        modifiers,
+        ...(key === undefined ? {} : { key }),
+        ...(view === undefined ? {} : { view }),
+      });
+    }
     pressedPointers.clear();
     primary = undefined;
     gesturePress = undefined;
+    gestureMoved = false;
   };
 
   /**
@@ -714,7 +789,7 @@ export const createPointerTracker = (picker: Picker): PointerTracker => {
     if (isSecondary(event, id)) return secondary(event, id);
     const events: Array<SceneEvent> = [];
     if (event._tag === 'PointerLeave') {
-      endGestures();
+      endGestures(events);
       // A cancelled or abandoned press still ends its drag, at the last known position.
       if (position !== undefined) endDrag(captured(), position.x, position.y, events);
       dragged = false;
@@ -738,7 +813,13 @@ export const createPointerTracker = (picker: Picker): PointerTracker => {
         moveGesture(id, event, events);
         break;
       case 'PointerDown':
-        press = { key: hit?.key, button: event.button, x: event.x, y: event.y };
+        press = {
+          key: hit?.key,
+          button: event.button,
+          x: event.x,
+          y: event.y,
+          device: event.device ?? 'mouse',
+        };
         pressing = true;
         dragged = false;
         if (hit !== undefined) events.push({ _tag: 'PointerDown', button: event.button, ...hit });
@@ -748,7 +829,7 @@ export const createPointerTracker = (picker: Picker): PointerTracker => {
         release(hit, event, events);
         // Any release ends capture: a mouse's buttons share one pointer.
         endDrag(drag, event.x, event.y, events);
-        endGestures();
+        endGestures(events);
         break;
       case 'DoubleClick':
         if (hit !== undefined && pressed(hit)) {