docs(component): minimal sensor documentation

docs/components/collider.md

@@ -11,33 +11,73 @@ Be aware that the event will be emitted by the `RigidBody` parent
 <RigidBody @collision-enter="onCollisionEnter" @collision-exit="onCollisionExit">
   <BallCollider activeCollision />
 </RigidBody>
-...
+...
 ```
 
 ## Props
 
-| Prop            | Description                                                                                                   | Default   |
-| :-------------- | :------------------------------------------------------------------------------------------------------------ | --------- |
-| **shape**       | shape of the collider                                                                                         | `cuboid`  |
-| **args**        | The half-sizes of the collider shapes                                                                         | `[1,1,1]` |
-| **object**      | Required for certain shapes like `trimesh`, `hull`, `heightfield`.                                            |           |
-| **friction**    | The friction coefficient of this collider. (automatic-collider)                                               | `0.5`     |
-| **mass**        | Mass of the collider. (automatic-collider)                                                                    | `1`       |
-| **density**     | Restitution controls how elastic (aka. bouncy) a contact is. (automatic-collider)                             | `0`       |
-| **restitution** | The collider density. If non-zero the collider's mass and angular inertia will be added. (automatic-collider) | `1`       |
-| **activeCollision**      | To set the collider receiver/emitter collision events                                                                    | `false`                            |
-| **activeCollisionTypes** | Type of the collision event.                                                                    | `ActiveCollisionTypes.DEFAULT`                            |
-| **collisionGroups**      | To specify collision groups.                                                                    | `undefined`                            |
-
-:::info
-You can access the [Collider](https://rapier.rs/docs/user_guides/javascript/colliders) instance
-which offers full control over all the properties & methods available
-by using [Template refs](https://vuejs.org/guide/essentials/template-refs.html#template-refs).
-:::
+| Prop                     | Description                  | Default |
+| :----------------------- | :--------------------------- | :------- |
+| **shape**                | shape of the collider | `cuboid` |
+| **args**                 | The half-sizes of the collider shapes | `[1,1,1]` |
+| **object**               | Required for certain shapes like `trimesh`, `hull`, `heightfield`. | |
+| **friction**             | The friction coefficient of this collider. (automatic-collider) | `0.5` |
+| **mass**                 | Mass of the collider. (automatic-collider) | `1` |
+| **density**              | Restitution controls how elastic (aka. bouncy) a contact is. (automatic-collider) | `0` |
+| **restitution**          | The collider density. If non-zero the collider's mass and angular inertia will be added. (automatic-collider). | `1` |
+| **activeCollision**      | To set the collider receiver/emitter collision events | `false` |
+| **activeCollisionTypes** | Type of the collision event. | `ActiveCollisionTypes.DEFAULT` |
+| **collisionGroups**      | To specify collision groups. | `undefined` |
+| **sensor**      | Set the collider as senor. More details [here](#sensor). | `undefined` |
 
-## Expose object
+## Events
+
+The `Collider` component comes with a set of useful events allowing actions based on collisions or intersections (aka sensor).
+
+### Sensor
+
+The **Sensor** feature allows events to be triggered when there's an intersection or in other words, when the collider is traversed by another collider.
+
+The traversed `Collider` (or the collider that will trigger events), is the sensor and should set the `activeCollision` and `sensor` properties to `true`.
+By passing the above properties, the collider will no longer be affected by the physics law and will now start triggering the following intersection events:
+
+- **@intersection-enter**:  When another collider starts to traverse the *sensor*
+- **@intersection-exit**: When another collider leave the *sensor*
 
+I.e:
+
+```vue
+<RigidBody type="fixed">
+  <CuboidCollider
+    :args="[10, 3, 0.5]"
+    :position="[0, 3, 3]"
+    activeCollision
+    sensor
+    @intersection-enter="onIntersection1Enter"
+    @intersection-exit="onIntersectionExit"
+  />
+
+  <CuboidCollider
+    :args="[10, 3, 0.5]"
+    :position="[0, 3, -3]"
+    activeCollision
+    sensor
+    @intersection-enter="onIntersection2Enter"
+    @intersection-exit="onIntersectionExit"
+  />
+</RigidBody>
 ```
+<!-- Add the demo link -->
+
+> ::: info
+> You can access the [Collider](https://rapier.rs/docs/user_guides/javascript/colliders) instance
+> which offers full control over all the properties & methods available
+> by using [Template refs](https://vuejs.org/guide/essentials/template-refs.html#template-refs).
+> :::
+
+## Expose object
+
+```md
 {
   instance,
   colliderDesc,

playground/src/pages/basics/SensorDemo.vue

@@ -81,7 +81,6 @@ onMounted(() => {
           />
 
           <CuboidCollider
-            name="cuboid-sensor"
             :args="[10, 3, 0.5]"
             :position="[0, 3, -3]"
             activeCollision

src/types/collision.ts

@@ -6,9 +6,9 @@ export interface CollisionSource {
   rigidBody: RigidBody | undefined
 };
 
-export interface sourceTarget {
+export interface SourceTarget {
   object: TresVNodeObject
   context: CollisionSource
 }
 
-export type collisionType = 'enter' | 'exit'
+export type CollisionType = 'enter' | 'exit'

src/types/object.ts

@@ -1,7 +1,7 @@
 import type { TresObject } from '@tresjs/core'
 import type { SetupContext, VNode } from 'vue'
 
-/** @description */
+/** @description approximate {@link VNode} representation. */
 export type TresVNode = Omit<VNode, 'children'> & {
   __vnode: VNode & {
     children: Array<TresVNode>
@@ -11,6 +11,7 @@ export type TresVNode = Omit<VNode, 'children'> & {
   ctx: SetupContext
 }
 
+/** @description approximate {@link TresObject} representation. */
 export type TresVNodeObject = TresObject & { __vnode: TresVNode }
 
 /** @description Utility type to exclude properties with the type `never` */
@@ -23,4 +24,5 @@ export type Methods<T extends object> = NonNever<{
   [K in keyof T]: T[K] extends (...args: any[]) => any ? T[K] : never;
 }>
 
+/** @description Utility picking methods/functions withing object. */
 export type CallableProps<T extends object = object> = Record<keyof Methods<T>, (...args: any[]) => unknown>

src/utils/collisions.ts

@@ -1,7 +1,7 @@
 import type { ColliderHandle, World } from '@dimforge/rapier3d-compat'
 import type { Scene } from 'three'
 import type { Ref } from 'vue'
-import type { CollisionSource, collisionType, sourceTarget, TresVNodeObject } from '../types'
+import type { CollisionSource, CollisionType, SourceTarget, TresVNodeObject } from '../types'
 
 export const getSourceFromColliderHandle = (world: World, handle: ColliderHandle) => {
   const collider = world.getCollider(handle)
@@ -26,10 +26,10 @@ export const get3DGroupFromSource = (source: CollisionSource, scene: Ref<Scene>)
 }
 
 export const collisionEmisor = (
-  source: sourceTarget,
-  target: sourceTarget,
+  source: SourceTarget,
+  target: SourceTarget,
   started: boolean,
 ) => {
-  const collisionType: collisionType = started ? 'enter' : 'exit'
-  source.object?.__vnode?.ctx?.emit?.(`collision-${collisionType}`, { source, target })
+  const CollisionType: CollisionType = started ? 'enter' : 'exit'
+  source.object?.__vnode?.ctx?.emit?.(`collision-${CollisionType}`, { source, target })
 }

src/utils/intersections.ts

@@ -1,12 +1,21 @@
-import type { collisionType, sourceTarget } from '../types'
+import type { CollisionType, SourceTarget } from '../types'
 
+/**
+ * @description Make traversed {@link SourceTarget Source} emit an intersection event.
+ *
+ * Either `@intersection-start` or `intersection-exist` based on the {@link CollisionType}.
+ *
+ * @param source - The traversed source.
+ * @param target - The traversing target.
+ * @param started - Whether the intersection started or ended
+ */
 export const emitIntersection = (
-  source: sourceTarget,
-  target: sourceTarget,
+  source: SourceTarget,
+  target: SourceTarget,
   started: boolean,
 ) => {
-  const collisionType: collisionType = started ? 'enter' : 'exit'
+  const CollisionType: CollisionType = started ? 'enter' : 'exit'
   const colliderNode = source.object?.__vnode?.children?.[1]?.children?.find(child => child?.component?.exposed?.instance?.value === source.context.collider)
 
-  colliderNode?.component?.emit?.(`intersection-${collisionType}`, { source, target })
+  colliderNode?.component?.emit?.(`intersection-${CollisionType}`, { source, target })
 }