@solidrt/3d 0.0.56 → 0.0.58

package/src/scene-pointer.ts

@@ -1,28 +1,102 @@
-// Pointer dispatch behind scene.handlers: element pointer events in,
-// instance/mesh/group handler calls out - nearest hit wins, down/move/up
-// bubble from the struck instance (or the mesh) up through the ancestors,
-// pointer-down captures until up, enter/leave pair on hover changes. One
-// system per scene; everything it needs of the scene is `pick` and the
-// target size (makePointerInput's deps), the capture/hover bookkeeping is
-// its own.
+// Pointer dispatch behind scene.handlers (and a view's): the element event
+// model one tree deeper, with the SCENE - or the view whose leaf received
+// the event - as the root of the walk. Down, move, up and wheel dispatch
+// on the nearest hit, bubble from the struck instance (when the mesh is
+// instanced) through the mesh and its ancestors and end at the root's
+// listeners; over empty space the walk is the root alone (`mesh` null).
+// Claiming is stopPropagation: a handler that stops an event keeps every
+// later target, the root included, from seeing it, and the DOWN decides
+// the press - a pointer whose down never reached the root stays claimed
+// by the node chain for its move, up and tap too, so a mesh that drags
+// itself stops its down once and an orbit control fed at the root never
+// turns. Capture is per pointer to the press target, the root included: a
+// drag from empty space keeps delivering to the root as it crosses meshes,
+// exactly as a drag from a mesh keeps naming that mesh. Enter/leave pair
+// on the struck node alone. Taps are synthesized here (DOM's click,
+// Unity's IPointerClickHandler): a press that releases on the same target
+// within the slop, the only pointer down for its whole press, counted up
+// for repeats (DOM's detail, Unity's clickCount). @solidrt/2d's
+// dispatch.ts is the same model one dimension down.
+//
+// Pure BY DESIGN (types only, nothing with GPU imports) so
+// checks/dispatch-check.ts drives it headless with a fake pick.
 
-import type { PointerEvent as ElementPointerEvent } from "@solidrt/core"
-import type { SceneNode, ScenePointerEvent } from "./node.ts"
+import type { PointerEvent as ElementPointerEvent, PointerFeed } from "@solidrt/core"
+import type { NodePointerEvent, SceneNode, ScenePointerListener } from "./node.ts"
 import type { InstanceNode, Mesh } from "./mesh.ts"
-import type { Hit, SceneHandlers } from "./scene.ts"
+import type { Hit, Scene, SceneHandlers, ViewHandle } from "./scene.ts"
+import type { Vec3 } from "./math.ts"
 
-type BubbleName = "onPointerDown" | "onPointerMove" | "onPointerUp"
-type InternalEvent = ScenePointerEvent & { _stopped: boolean }
-// What a press captures and a hover tracks: the struck mesh, and the
-// instance when the mesh is instanced.
+// Finger travel from the down point, in window pixels, past which a press
+// is a drag and never a tap. Core's pan and transform recognizers engage
+// at the same 8, so a press is never both a tap and a drag.
+const TAP_SLOP = 8
+// Successive taps closer in time than this, on the same target and within
+// TAP_REPEAT_SLOP of each other, count up (Unity's 0.3 s clickCount
+// window, Android's double-tap timeout).
+const TAP_INTERVAL_MS = 300
+// Window pixels a repeat tap may land from the previous one and still
+// count: a thumb repeats within about this (Hammer.js uses 10, Android
+// 100 dp); 20 tolerates touch without a mouse double-click spanning
+// neighbouring meshes.
+const TAP_REPEAT_SLOP = 20
+
+type HandlerName = "onPointerDown" | "onPointerMove" | "onPointerUp" | "onWheel" | "onTap"
+
+// What a press captures, a hover tracks and a tap compares: the struck
+// mesh, and the instance when the mesh is instanced.
 type Target = { mesh: Mesh; instance: InstanceNode | null }
 
+// One runtime event object serves every view (NodePointerEvent for the
+// node chain, ScenePointerEvent at the root, plus the wheel and tap
+// fields); the public types narrow it per handler.
+type InternalEvent = {
+  mesh: Mesh | null
+  instance: InstanceNode | null
+  currentTarget: SceneNode | Scene | ViewHandle
+  point: Vec3 | null
+  distance: number | null
+  x: number
+  y: number
+  pointerId: number
+  pointerType: string
+  button?: number
+  shiftKey: boolean
+  ctrlKey: boolean
+  altKey: boolean
+  metaKey: boolean
+  native: ElementPointerEvent
+  deltaX?: number
+  deltaY?: number
+  tapCount?: number
+  _stopped: boolean
+  stopPropagation(): void
+}
+
+// A pointer between its down and up: what it pressed (null = the root),
+// whether the down reached the root, the down point for the slop, and
+// whether it has been the only pointer down for its whole press.
+type Press = {
+  target: Target | null
+  claimed: boolean
+  cx: number
+  cy: number
+  moved: boolean
+  alone: boolean
+}
+
 export type PointerInputDeps = {
-  /** The scene's pick: camera ray through a scene pixel, hits nearest
-   * first. */
+  /** The root's pick: the camera ray through one of its pixels, hits
+   * nearest first. */
   pick(x: number, y: number): Hit[]
-  /** The scene target's current size (handlersFor's layout scaling). */
+  /** The root target's current size (handlersFor's layout scaling). */
   targetSize(): { width: number; height: number }
+  /** The scene or view: the walk's root and the listeners' currentTarget. */
+  root: Scene | ViewHandle
+  /** The root's listeners, in registration order. */
+  listeners: Set<ScenePointerListener>
+  /** The clock for tap repeats (default performance.now; checks inject). */
+  now?: () => number
 }
 
 export type PointerInput = {
@@ -34,133 +108,187 @@ export type PointerInput = {
 }
 
 export function makePointerInput(deps: PointerInputDeps): PointerInput {
-  let capture = new Map<number, Target>()
+  let now = deps.now ?? (() => performance.now())
+  let presses = new Map<number, Press>()
   let hover = new Map<number, Target>()
+  let lastTap: { time: number; cx: number; cy: number; target: Target | null; count: number } | null = null
 
   let targetOf = (hit: Hit): Target => ({ mesh: hit.mesh, instance: hit.instance ?? null })
-  let sameTarget = (hit: Hit, target: Target): boolean => hit.mesh === target.mesh && (hit.instance ?? null) === target.instance
+  let sameHit = (hit: Hit, target: Target): boolean => hit.mesh === target.mesh && (hit.instance ?? null) === target.instance
+  let sameTarget = (a: Target | null, b: Target | null): boolean => (a === null ? b === null : b !== null && a.mesh === b.mesh && a.instance === b.instance)
   // The node the walk starts at, and the one enter/leave fire on.
   let nodeOf = (target: Target): SceneNode => target.instance ?? target.mesh
-
-  let makeEvent = (e: ElementPointerEvent, target: Target, x: number, y: number, hit: Hit | null): InternalEvent => {
-    let event: InternalEvent = {
-      mesh: target.mesh,
-      instance: target.instance,
-      currentTarget: nodeOf(target),
-      point: hit !== null ? hit.point : null,
-      distance: hit !== null ? hit.distance : null,
-      x,
-      y,
-      pointerId: e.pointerId,
-      pointerType: e.pointerType,
-      button: e.button,
-      shiftKey: e.shiftKey,
-      ctrlKey: e.ctrlKey,
-      altKey: e.altKey,
-      metaKey: e.metaKey,
-      _stopped: false,
-      stopPropagation() {
-        event._stopped = true
-      },
-    }
-    return event
+  // The captured target's own hit, if the ray still strikes it.
+  let hitOn = (target: Target | null, x: number, y: number): Hit | null => {
+    if (target === null) return null
+    for (let h of deps.pick(x, y)) if (sameHit(h, target)) return h
+    return null
   }
 
-  // The struck instance first (its chain passes through the mesh), then
-  // the mesh, then its ancestors.
-  let bubble = (name: BubbleName, event: InternalEvent): void => {
+  // Bubble from the struck node through its ancestors; then, when the
+  // press lets it, the root's listeners (every one of them - the root is
+  // the last stop, there is nothing left to claim). Returns whether the
+  // root ran.
+  let walk = (name: HandlerName, event: InternalEvent, toRoot: boolean): boolean => {
     for (let n: SceneNode | null = event.instance ?? event.mesh; n !== null && !event._stopped; n = n.parent) {
-      let handler = n[name]
+      // A node that left the scene mid-press has no handlers to run.
+      if (n._scene === null) continue
+      let handler = n[name] as ((event: InternalEvent) => void) | undefined
       if (handler) {
         event.currentTarget = n
         handler(event)
       }
     }
-  }
-
-  // The captured target's own hit, if the ray still strikes it.
-  let hitOn = (target: Target, x: number, y: number): Hit | null => {
-    for (let h of deps.pick(x, y)) if (sameTarget(h, target)) return h
-    return null
+    if (event._stopped || !toRoot) return false
+    event.currentTarget = deps.root
+    for (let listener of deps.listeners) {
+      let handler = listener[name] as ((event: InternalEvent) => void) | undefined
+      if (handler) handler(event)
+    }
+    return true
   }
 
   // localX/localY arrive in the leaf's LAYOUT frame (the hit test undoes
-  // every transform above it, design-size fits included), so a leaf laid out at
-  // the target size - the built-in <Scene> leaf, a d-texture at natural
-  // size - is already in scene pixels. Only a leaf deliberately laid out at
-  // a DIFFERENT size (the supersampling pattern) needs the ratio, and only
-  // the app knows that layout: handlersFor takes it.
+  // every transform above it, design-size fits included), so a leaf laid
+  // out at the target size - the built-in <Scene> leaf, a d-texture at
+  // natural size - is already in scene pixels. Only a leaf deliberately
+  // laid out at a DIFFERENT size (the supersampling pattern) needs the
+  // ratio, and only the app knows that layout: handlersFor takes it.
   let makeHandlers = (layout: (() => { width: number; height: number }) | null): SceneHandlers => {
-    let eventX = 0
-    let eventY = 0
-    let toScene = (e: ElementPointerEvent): void => {
-      if (layout === null) {
-        eventX = e.localX
-        eventY = e.localY
-        return
-      }
+    let toScene = (e: ElementPointerEvent): [number, number] => {
+      if (layout === null) return [e.localX, e.localY]
       let l = layout()
       let size = deps.targetSize()
-      eventX = e.localX * (l.width > 0 ? size.width / l.width : 1)
-      eventY = e.localY * (l.height > 0 ? size.height / l.height : 1)
+      return [e.localX * (l.width > 0 ? size.width / l.width : 1), e.localY * (l.height > 0 ? size.height / l.height : 1)]
     }
+    let makeEvent = (e: ElementPointerEvent, target: Target | null, x: number, y: number, hit: Hit | null): InternalEvent => {
+      let event: InternalEvent = {
+        mesh: target === null ? null : target.mesh,
+        instance: target === null ? null : target.instance,
+        currentTarget: target === null ? deps.root : nodeOf(target),
+        point: hit === null ? null : hit.point,
+        distance: hit === null ? null : hit.distance,
+        x,
+        y,
+        pointerId: e.pointerId,
+        pointerType: e.pointerType,
+        button: e.button,
+        shiftKey: e.shiftKey,
+        ctrlKey: e.ctrlKey,
+        altKey: e.altKey,
+        metaKey: e.metaKey,
+        native: e,
+        _stopped: false,
+        stopPropagation() {
+          event._stopped = true
+        },
+      }
+      return event
+    }
+    let nearest = (x: number, y: number): Hit | null => deps.pick(x, y)[0] ?? null
+    // Enter/leave go to one node directly, outside the walk: the event
+    // in its node view.
+    let hoverEvent = (e: ElementPointerEvent, target: Target, x: number, y: number, hit: Hit | null): NodePointerEvent =>
+      makeEvent(e, target, x, y, hit) as unknown as NodePointerEvent
+
     return {
       onPointerDown(e) {
-        toScene(e)
-        let hit = deps.pick(eventX, eventY)[0]
-        if (hit === undefined) return
-        let target = targetOf(hit)
-        capture.set(e.pointerId, target)
-        bubble("onPointerDown", makeEvent(e, target, eventX, eventY, hit))
+        let [x, y] = toScene(e)
+        let hit = nearest(x, y)
+        // A second pointer landing ends "alone" for every press in flight.
+        for (let p of presses.values()) p.alone = false
+        let press: Press = { target: hit === null ? null : targetOf(hit), claimed: false, cx: e.clientX, cy: e.clientY, moved: false, alone: presses.size === 0 }
+        presses.set(e.pointerId, press)
+        press.claimed = !walk("onPointerDown", makeEvent(e, press.target, x, y, hit), true)
       },
       onPointerMove(e) {
-        toScene(e)
-        let captured = capture.get(e.pointerId)
-        if (captured !== undefined) {
-          bubble("onPointerMove", makeEvent(e, captured, eventX, eventY, hitOn(captured, eventX, eventY)))
+        let [x, y] = toScene(e)
+        let press = presses.get(e.pointerId)
+        if (press) {
+          if (!press.moved && Math.hypot(e.clientX - press.cx, e.clientY - press.cy) >= TAP_SLOP) press.moved = true
+          walk("onPointerMove", makeEvent(e, press.target, x, y, hitOn(press.target, x, y)), !press.claimed)
           return
         }
-        let hit = deps.pick(eventX, eventY)[0]
-        let prev = hover.get(e.pointerId)
-        let changed = prev === undefined ? hit !== undefined : hit === undefined || !sameTarget(hit, prev)
+        let hit = nearest(x, y)
+        let prev = hover.get(e.pointerId) ?? null
+        let changed = prev === null ? hit !== null : hit === null || !sameHit(hit, prev)
         if (changed) {
-          if (prev !== undefined) {
+          if (prev !== null) {
             hover.delete(e.pointerId)
-            nodeOf(prev).onPointerLeave?.(makeEvent(e, prev, eventX, eventY, null))
+            let node = nodeOf(prev)
+            if (node._scene !== null) node.onPointerLeave?.(hoverEvent(e, prev, x, y, null))
           }
-          if (hit !== undefined) {
+          if (hit !== null) {
             let target = targetOf(hit)
             hover.set(e.pointerId, target)
-            nodeOf(target).onPointerEnter?.(makeEvent(e, target, eventX, eventY, hit))
+            nodeOf(target).onPointerEnter?.(hoverEvent(e, target, x, y, hit))
           }
         }
-        if (hit !== undefined) {
-          bubble("onPointerMove", makeEvent(e, targetOf(hit), eventX, eventY, hit))
-        }
+        walk("onPointerMove", makeEvent(e, hit === null ? null : targetOf(hit), x, y, hit), true)
       },
       onPointerUp(e) {
-        toScene(e)
-        let captured = capture.get(e.pointerId)
-        if (captured !== undefined) {
-          capture.delete(e.pointerId)
-          bubble("onPointerUp", makeEvent(e, captured, eventX, eventY, hitOn(captured, eventX, eventY)))
+        let [x, y] = toScene(e)
+        let press = presses.get(e.pointerId)
+        if (!press) {
+          // A press this root never saw go down: deliver to what is under
+          // it, as the element model does.
+          let hit = nearest(x, y)
+          walk("onPointerUp", makeEvent(e, hit === null ? null : targetOf(hit), x, y, hit), true)
           return
         }
-        let hit = deps.pick(eventX, eventY)[0]
-        if (hit !== undefined) {
-          bubble("onPointerUp", makeEvent(e, targetOf(hit), eventX, eventY, hit))
-        }
+        presses.delete(e.pointerId)
+        let under = hitOn(press.target, x, y)
+        walk("onPointerUp", makeEvent(e, press.target, x, y, under), !press.claimed)
+        // The tap rule: no travel past the slop, alone for the whole
+        // press, released over the target it pressed (empty space for the
+        // root itself).
+        if (press.moved || !press.alone) return
+        let release = nearest(x, y)
+        if (press.target === null ? release !== null : release === null || !sameHit(release, press.target)) return
+        let time = now()
+        let repeat = lastTap !== null && time - lastTap.time <= TAP_INTERVAL_MS && sameTarget(lastTap.target, press.target) && Math.hypot(e.clientX - lastTap.cx, e.clientY - lastTap.cy) <= TAP_REPEAT_SLOP
+        let count = repeat ? lastTap!.count + 1 : 1
+        lastTap = { time, cx: e.clientX, cy: e.clientY, target: press.target, count }
+        let tap = makeEvent(e, press.target, x, y, release)
+        tap.tapCount = count
+        walk("onTap", tap, !press.claimed)
+      },
+      onWheel(e) {
+        let [x, y] = toScene(e)
+        let hit = nearest(x, y)
+        let event = makeEvent(e, hit === null ? null : targetOf(hit), x, y, hit)
+        event.deltaX = e.deltaX
+        event.deltaY = e.deltaY
+        walk("onWheel", event, true)
       },
       onPointerLeave(e) {
         let prev = hover.get(e.pointerId)
-        if (prev !== undefined) {
-          hover.delete(e.pointerId)
-          toScene(e)
-          nodeOf(prev).onPointerLeave?.(makeEvent(e, prev, eventX, eventY, null))
-        }
+        if (prev === undefined) return
+        hover.delete(e.pointerId)
+        let node = nodeOf(prev)
+        if (node._scene === null) return
+        let [x, y] = toScene(e)
+        node.onPointerLeave?.(hoverEvent(e, prev, x, y, null))
       },
     }
   }
 
   return { handlers: makeHandlers(null), handlersFor: makeHandlers }
 }
+
+/**
+ * Feed a pointer feed (createPointerFeed) from a root's listeners: the
+ * events the meshes let through - a mesh that claims its press
+ * (stopPropagation on its down) keeps a camera control bound to the feed
+ * out of that drag, a drag on empty space or an unclaimed mesh orbits, a
+ * wheel anywhere zooms. Returns the detach. The components do this for
+ * their `pointer` prop; an imperative scene or view calls it directly.
+ */
+export function feedPointer(root: { listen(listener: ScenePointerListener): () => void }, feed: PointerFeed): () => void {
+  return root.listen({
+    onPointerDown: e => feed.handlers.onPointerDown(e.native),
+    onPointerMove: e => feed.handlers.onPointerMove(e.native),
+    onPointerUp: e => feed.handlers.onPointerUp(e.native),
+    onWheel: e => feed.handlers.onWheel(e.native),
+  })
+}