feat: add currentIntersection, intersection, intersections to event

Author: bigmistqke

playground/controls/type-utils.ts

@@ -2,15 +2,15 @@ export type Args<T> = T extends new (...args: any) => any ? ConstructorParameter
 
 export type Mandatory<T, K extends keyof T> = T & { [P in K]-?: T[P] }
 
-type OmitFunctionProperties<T> = { [K in keyof T]: T[K] extends Function ? never : K }[keyof T]
-/** Overwrites the properties in `T` with the properties from `O`. */
-export type Overwrite<T, O> = Omit<T, OmitFunctionProperties<O>> & O
-
 export type KeyOfOptionals<T> = keyof {
   [K in keyof T as T extends Record<K, T[K]> ? never : K]: T[K]
 }
 
 /** Allows using a TS v4 labeled tuple even with older typescript versions */
 export type NamedArrayTuple<T extends (...args: any) => any> = Parameters<T>
 
-export type Ref<TRef> = TRef | ((value: TRef) => void)
+export type Intersect<T extends any[]> = T extends [infer U, ...infer Rest]
+  ? Rest["length"] extends 0
+    ? U
+    : U & Intersect<Rest>
+  : T

playground/examples/SolarExample.tsx

@@ -98,6 +98,7 @@ function CelestialBody(
         ref={ref}
         position={props.position || [0, 0, 0]}
         rotation={props.rotation || [0, 0, 0]}
+        onPointerDown={console.log}
         onPointerEnter={() => setHovered(true)}
         onPointerLeave={() => setHovered(false)}
       >

src/canvas.tsx

@@ -10,39 +10,39 @@ import {
 } from "three"
 import { createThree } from "./create-three.tsx"
 import type { EventRaycaster } from "./raycasters.tsx"
-import type { Context, EventHandlers, Props } from "./types.ts"
+import type { CanvasEventHandlers, Context, Props } from "./types.ts"
 
 /**
  * Props for the Canvas component, which initializes the Three.js rendering context and acts as the root for your 3D scene.
  */
-export interface CanvasProps extends ParentProps<Partial<EventHandlers>> {
+export interface CanvasProps extends ParentProps<Partial<CanvasEventHandlers>> {
+  ref?: Ref<Context>
   class?: string
   /** Configuration for the camera used in the scene. */
   defaultCamera?: Partial<Props<PerspectiveCamera> | Props<OrthographicCamera>> | Camera
-  /** Configuration for the Scene instance. */
-  scene?: Partial<Props<Scene>> | Scene
+  /** Configuration for the Raycaster used for mouse and pointer events. */
+  defaultRaycaster?: Partial<Props<EventRaycaster>> | EventRaycaster | Raycaster
   /** Element to render while the main content is loading asynchronously.  */
   fallback?: JSX.Element
+  /** Toggles flat interpolation for texture filtering. */
+  flat?: boolean
+  /** Controls the rendering loop's operation mode. */
+  frameloop?: "never" | "demand" | "always"
   /** Options for the WebGLRenderer or a function returning a customized renderer. */
   gl?:
     | Partial<Props<WebGLRenderer>>
     | ((canvas: HTMLCanvasElement) => WebGLRenderer)
     | WebGLRenderer
+  /** Toggles linear interpolation for texture filtering. */
+  linear?: boolean
   /** Toggles between Orthographic and Perspective camera. */
   orthographic?: boolean
-  /** Configuration for the Raycaster used for mouse and pointer events. */
-  raycaster?: Partial<Props<EventRaycaster>> | EventRaycaster | Raycaster
-  ref?: Ref<Context>
-  /** Custom CSS styles for the canvas container. */
-  style?: JSX.CSSProperties
+  /** Configuration for the Scene instance. */
+  scene?: Partial<Props<Scene>> | Scene
   /** Enables and configures shadows in the scene. */
   shadows?: boolean | "basic" | "percentage" | "soft" | "variance" | WebGLRenderer["shadowMap"]
-  /** Toggles linear interpolation for texture filtering. */
-  linear?: boolean
-  /** Toggles flat interpolation for texture filtering. */
-  flat?: boolean
-  /** Controls the rendering loop's operation mode. */
-  frameloop?: "never" | "demand" | "always"
+  /** Custom CSS styles for the canvas container. */
+  style?: JSX.CSSProperties
 }
 
 /**

src/components.tsx

@@ -71,11 +71,13 @@ export const Portal = (props: PortalProps) => {
 /**********************************************************************************/
 
 type EntityProps<T extends object | Constructor<object>> = Overwrite<
-  Props<T>,
-  {
-    from: T | undefined
-    children?: JSXElement
-  }
+  [
+    Props<T>,
+    {
+      from: T | undefined
+      children?: JSXElement
+    },
+  ]
 >
 /**
  * Wraps a `ThreeElement` and allows it to be used as a JSX-component within a `solid-three` scene.
@@ -97,10 +99,10 @@ export function Entity<T extends object | Constructor<object>>(props: EntityProp
           props,
         },
       ) as Meta<T>
+      useProps(instance, rest)
       return instance
     },
   )
-  useProps(memo, rest)
   return memo as unknown as JSX.Element
 }
 

src/create-events.ts

@@ -1,6 +1,7 @@
 import { Object3D, type Intersection } from "three"
+import type { Intersect } from "../playground/controls/type-utils.ts"
 import { $S3C } from "./constants.ts"
-import type { Context, EventName, Meta, ThreeEvent } from "./types.ts"
+import type { BaseEvent, Context, EventName, Meta, StoppableEvent } from "./types.ts"
 import { isInstance } from "./utils.ts"
 
 const eventNameMap = {
@@ -52,36 +53,46 @@ export const isEventType = (type: string): type is EventName =>
 
 /**********************************************************************************/
 /*                                                                                */
-/*                                Create Three Event                              */
+/*                                      Events                                    */
 /*                                                                                */
 /**********************************************************************************/
+//
+/** Creates a `ThreeEvent` (intersection excluded) from the current `MouseEvent` | `WheelEvent`. */
+function createThreeEvent<
+  TEvent extends Event,
+  TConfig extends { stoppable?: boolean; intersections?: Intersection[] },
+>(nativeEvent: TEvent, { stoppable = true, intersections }: TConfig = {}) {
+  const event: Record<string, any> = stoppable
+    ? {
+        nativeEvent,
+        stopped: false,
+        stopPropagation() {
+          event.stopped = true
+        },
+      }
+    : { nativeEvent }
 
-// Creates a `ThreeEvent` from the current `MouseEvent` | `WheelEvent`.
-function createThreeEvent<TEvent extends Event>(
-  nativeEvent: TEvent,
-  stoppable?: true,
-): ThreeEvent<TEvent>
-function createThreeEvent<TEvent extends Event>(
-  nativeEvent: TEvent,
-  stoppable: false,
-): ThreeEvent<TEvent, false>
-function createThreeEvent<TEvent extends Event>(
-  nativeEvent: TEvent,
-  stoppable = true,
-): ThreeEvent<TEvent, boolean> {
-  if (!stoppable) {
-    return {
-      nativeEvent,
-    }
+  if (intersections) {
+    event.intersections = intersections
+    event.intersection = intersections[0]
   }
-  const event = {
-    nativeEvent,
-    stopped: false,
-    stopPropagation() {
-      event.stopped = true
-    },
-  }
-  return event
+
+  return event as Intersect<
+    [
+      TConfig["stoppable"] extends false
+        ? TConfig["stoppable"] extends undefined
+          ? StoppableEvent<TEvent>
+          : BaseEvent<TEvent>
+        : StoppableEvent<TEvent>,
+      TConfig["intersections"] extends Intersection[]
+        ? {
+            intersections: Intersection[]
+            intersection: Intersection
+            currentIntersection?: Intersection
+          }
+        : unknown,
+    ]
+  >
 }
 
 /**********************************************************************************/
@@ -139,7 +150,6 @@ function createMissableEventRegistry(
 
   context.canvas.addEventListener(eventNameMap[type], nativeEvent => {
     if (registry.array.length === 0) return
-    const event = createThreeEvent(nativeEvent)
     const missedType = `${type}Missed` as const
 
     // Track which objects have been visited during event processing
@@ -149,22 +159,30 @@ function createMissableEventRegistry(
     // Phase #1 - Process normal click events
     const intersections = raycast(context, registry.array, nativeEvent)
 
-    for (const { object } of intersections) {
-      let node: Object3D | null = object
-      while (node && !event.stopped && !visitedObjects.has(node)) {
+    const stoppableEvent = createThreeEvent(nativeEvent, { intersections })
+
+    for (const intersection of intersections) {
+      let node: Object3D | null = intersection.object
+
+      stoppableEvent.currentIntersection = intersection
+
+      while (node && !stoppableEvent.stopped && !visitedObjects.has(node)) {
         missedObjects.delete(node)
         visitedObjects.add(node)
         if (isInstance(node)) {
-          node[$S3C].props?.[type]?.(event)
+          node[$S3C].props[type]?.(stoppableEvent)
         }
         node = node.parent
       }
     }
 
     // Call the respective canvas event-handler
     // if event propagated all the way down
-    if (!event.stopped) {
-      context.props[type]?.(event)
+    if (!stoppableEvent.stopped) {
+      if ("currentIntersection" in stoppableEvent) {
+        delete stoppableEvent.currentIntersection
+      }
+      context.props[type]?.(stoppableEvent)
     }
 
     // Phase #2 - Raycast remaining missed objects
@@ -186,11 +204,11 @@ function createMissableEventRegistry(
     }
 
     // Phase #3 - Fire missed event-handler on missed objects
-    const missedEvent = createThreeEvent(nativeEvent, false)
+    const missedEvent = createThreeEvent(nativeEvent, { stoppable: false })
 
     for (const object of missedObjects) {
       if (isInstance(object)) {
-        object[$S3C].props?.[missedType]?.(missedEvent)
+        object[$S3C].props[missedType]?.(missedEvent)
       }
     }
 
@@ -229,17 +247,20 @@ function createHoverEventRegistry(type: "Mouse" | "Pointer", context: Context) {
     intersections = raycast(context, registry.array, nativeEvent)
 
     // Phase #1 - Enter
-    const enterEvent = createThreeEvent(nativeEvent, false)
+    const enterEvent = createThreeEvent(nativeEvent, { stoppable: false, intersections })
     const enterSet = new Set<Object3D>()
 
-    for (const { object } of intersections) {
+    for (const intersection of intersections) {
+      // Mutate event
+      enterEvent.intersection = intersection
+
       // Bubble up
-      let current: Object3D | null = object
+      let current: Object3D | null = intersection.object
       while (current && !enterSet.has(current)) {
         enterSet.add(current)
 
         if (isInstance(current) && !hoveredSet.has(current)) {
-          current[$S3C].props?.[`on${type}Enter`]?.(enterEvent)
+          current[$S3C].props[`on${type}Enter`]?.(enterEvent)
         }
         // We bubble a layer down.
         current = current.parent
@@ -252,18 +273,22 @@ function createHoverEventRegistry(type: "Mouse" | "Pointer", context: Context) {
     }
 
     // Phase #2 - Move
-    const moveEvent = createThreeEvent(nativeEvent)
+    const moveEvent = createThreeEvent(nativeEvent, { intersections })
     const moveSet = new Set()
 
-    for (const { object } of intersections) {
-      if (moveEvent.stopped) break
+    for (const intersection of intersections) {
+      // Mutate currentIntersection
+      moveEvent.currentIntersection = intersection
+
       // Bubble up
-      let current: Object3D | null = object
+      let current: Object3D | null = intersection.object
+
       while (current && !moveSet.has(current)) {
         moveSet.add(current)
 
         if (isInstance(current)) {
-          current[$S3C].props?.[`on${type}Move`]?.(moveEvent)
+          // @ts-expect-error TODO: fix type-error
+          current[$S3C].props[`on${type}Move`]?.(moveEvent)
           // Break if event was
           if (moveEvent.stopped) {
             break
@@ -275,6 +300,8 @@ function createHoverEventRegistry(type: "Mouse" | "Pointer", context: Context) {
     }
 
     if (!moveEvent.stopped) {
+      // Remove currentIntersection from moveEvent
+      delete moveEvent.currentIntersection
       context.props[`on${type}Move`]?.(moveEvent)
     }
 
@@ -291,13 +318,13 @@ function createHoverEventRegistry(type: "Mouse" | "Pointer", context: Context) {
   })
 
   context.canvas.addEventListener(eventNameMap[`on${type}Leave`], nativeEvent => {
-    const leaveEvent = createThreeEvent(nativeEvent, false)
+    const leaveEvent = createThreeEvent(nativeEvent, { stoppable: false })
     context.props[`on${type}Leave`]?.(leaveEvent)
     hoveredCanvas = false
 
     for (const object of hoveredSet) {
       if (isInstance(object)) {
-        object[$S3C].props?.[`on${type}Leave`]?.(leaveEvent)
+        object[$S3C].props[`on${type}Leave`]?.(leaveEvent)
       }
     }
     hoveredSet.clear()
@@ -330,23 +357,29 @@ function createDefaultEventRegistry(
   context.canvas.addEventListener(
     eventNameMap[type],
     nativeEvent => {
-      const event = createThreeEvent(nativeEvent)
       const intersections = raycast(context, registry.array, nativeEvent)
+      const event = createThreeEvent(nativeEvent, { intersections })
 
-      for (const { object } of intersections) {
+      for (const intersection of intersections) {
         // Bubble up
-        let node: Object3D | null = object
+        let node: Object3D | null = intersection.object
+
+        event.intersection = intersection
 
         while (node && !event.stopped) {
-          if (isInstance(object)) {
+          if (isInstance(intersection.object)) {
             // @ts-expect-error TODO: fix type-error
-            object[$S3C].props?.[type]?.(event)
+            intersection.object[$S3C].props[type]?.(event)
           }
           node = node.parent
         }
       }
 
       if (!event.stopped) {
+        // Remove trailing intersection from event
+        if ("intersection" in event) {
+          delete event.intersection
+        }
         // @ts-expect-error TODO: fix type-error
         context.props[type]?.(event)
       }

src/create-three.tsx

@@ -195,10 +195,10 @@ export function createThree(canvas: HTMLCanvasElement, props: CanvasProps) {
 
   const defaultRaycaster = createMemo(() =>
     augment<Raycaster | EventRaycaster>(
-      props.raycaster instanceof Raycaster ? props.raycaster : new CursorRaycaster(),
+      props.defaultRaycaster instanceof Raycaster ? props.defaultRaycaster : new CursorRaycaster(),
       {
         get props() {
-          return props.raycaster || {}
+          return props.defaultRaycaster || {}
         },
       },
     ),
@@ -314,8 +314,8 @@ export function createThree(canvas: HTMLCanvasElement, props: CanvasProps) {
 
     // Manage raycaster
     createRenderEffect(() => {
-      if (!props.raycaster || props.raycaster instanceof Raycaster) return
-      useProps(defaultRaycaster, props.raycaster)
+      if (!props.defaultRaycaster || props.defaultRaycaster instanceof Raycaster) return
+      useProps(defaultRaycaster, props.defaultRaycaster)
     })
 
     // Manage gl

src/index.ts

@@ -6,4 +6,4 @@ export { useFrame, useThree } from "./hooks.ts"
 export { useProps } from "./props.ts"
 export * from "./raycasters.tsx"
 export * as S3 from "./types.ts"
-export { autodispose, autolisten, load } from "./utils.ts"
+export { augment, autodispose, autolisten, load } from "./utils.ts"