update docs and examples for the exchange of in useTargetFromContext favor of targetRef="from-context"

Author: bbohlender

docs/handles/handle-component.md

@@ -41,8 +41,8 @@ Normally, an interaction is canceled when the user releases the button that star
 **handleRef**  
 Allows overriding to pass a custom handle object.
 
-**useTargetFromContext**  
-Required to use the target provided by a surrounding `HandleTarget` component.
+**targetRef**  
+Allows to pass in a ref to an object that should be the target of the handle. Alternatively `targetRef` can be set to `"from-context"` use the target provided by a surrounding `HandleTarget` component.
 
 **getHandleOptions**  
 Allows passing a function that dynamically generates options to override the current handle options.
@@ -76,15 +76,15 @@ Allows retrieval of a reference to the internal handle store (`<Handle ref={hand
 
 ## Handle Target Component
 
-The `HandleTarget` component allows declaratively specifying a handle target that is hierarchically above the `Handle` component. To prevent accidentally providing a different target to a handle, using the target from the context requires setting the `useTargetFromContext` on the `Handle` component.
+The `HandleTarget` component allows declaratively specifying a handle target that is hierarchically above the `Handle` component. To prevent accidentally providing a different target to a handle, using the target from the context requires setting `targetRef="from-context"` on the `Handle` component.
 
 **Example**
 ```tsx
 <HandleTarget>
     <group>
         <mesh>
             <boxGeometry />
-            <Handle useTargetFromContext>
+            <Handle targetRef="from-context">
                 <mesh position-x={2}>  
                     <boxGeometry />
                 </mesh>

docs/handles/introduction.md

@@ -27,7 +27,7 @@ export function Door() {
           <mesh geometry={nodes.Plane001_Glossy_0.geometry} material={materials.Glossy} />
           <mesh geometry={nodes.Plane001_Door_0.geometry} material={materials.Door} />
           <mesh geometry={nodes.Plane003_Door_0.geometry} material={materials.Door} position={[0.852, 0.017, 0.782]} />
-          <Handle useTargetFromContext translate="as-rotate" rotate={{ x: false, y: false, z: [-Math.PI, 0] }}>
+          <Handle targetRef="from-context" translate="as-rotate" rotate={{ x: false, y: false, z: [-Math.PI, 0] }}>
             <group position={[0.81, 0.043, 0.803]}>
               <mesh geometry={nodes.Circle002_Glossy_0.geometry} material={materials.Glossy} />
             </group>
@@ -41,7 +41,7 @@ export function Door() {
 }
 ```
 
-Next, we need to configure the handle to rotate the door when grabbed. We instruct it to use the target from the context using `useTargetFromContext`, making sure the transformations are applied to the door body. Additionally, we ensure that moving the handle is translated into a rotation using the `translate="as-rotate"` property. Lastly, we disable rotations on all axes except for the `z` axis and limit the rotation between -180° and 0°.
+Next, we need to configure the handle to rotate the door when grabbed. We instruct it to use the target from the context using `targetRef="from-context"`, making sure the transformations are applied to the door body. Additionally, we ensure that moving the handle is translated into a rotation using the `translate="as-rotate"` property. Lastly, we disable rotations on all axes except for the `z` axis and limit the rotation between -180° and 0°.
 
 *Learn more about all the available properties for the handle component [here](./handle-component.md).*
 

examples/editor/app.tsx

@@ -143,7 +143,7 @@ export function App() {
             <HandleTarget>
               <Scene isNotInRT />
 
-              <HandleWithAudio useTargetFromContext scale={false} multitouch={false} rotate={false}>
+              <HandleWithAudio targetRef="from-context" scale={false} multitouch={false} rotate={false}>
                 <Hover>
                   {(hovered) => (
                     <RoundedBox position-x={0.35} position-y={-0.05} args={[0.2, 0.2, 2]} scale={hovered ? 0.125 : 0.1}>
@@ -159,7 +159,7 @@ export function App() {
               </HandleWithAudio>
 
               <HandleWithAudio
-                useTargetFromContext
+                targetRef="from-context"
                 scale={{ uniform: true }}
                 multitouch={false}
                 translate="as-rotate-and-scale"
@@ -315,7 +315,7 @@ function Screen() {
                 </NotInXR>
               </XRLayer>
               <HandleWithAudio
-                useTargetFromContext
+                targetRef="from-context"
                 translate="as-scale"
                 apply={(state, target) => {
                   defaultApply(state, target)
@@ -345,7 +345,7 @@ function Screen() {
               </HandleWithAudio>
             </HandleTarget>
           </group>
-          <HandleWithAudio useTargetFromContext ref={storeRef} scale={false} multitouch={false} rotate={false}>
+          <HandleWithAudio targetRef="from-context" ref={storeRef} scale={false} multitouch={false} rotate={false}>
             <Hover>
               {(hovered) => (
                 <RoundedBox scale={hovered ? 0.125 : 0.1} args={[2, 0.2, 0.2]}>
@@ -385,7 +385,7 @@ function CameraHelper() {
         {(hovered) => (
           <>
             <HandleWithAudio
-              useTargetFromContext
+              targetRef="from-context"
               apply={(state) => cameraStore.getState().setCameraPosition(...state.current.position.toArray())}
               scale={false}
               multitouch={false}
@@ -471,7 +471,7 @@ function Scene({ isNotInRT = false }: { isNotInRT?: boolean }) {
               {isNotInRT && (
                 <>
                   <HandleWithAudio
-                    useTargetFromContext
+                    targetRef="from-context"
                     apply={(state) => useSceneStore.setState({ lightPosition: state.current.position.toArray() })}
                     scale={false}
                     multitouch={false}
@@ -595,7 +595,7 @@ function CustomTransformHandles({
   if (isInXR) {
     return (
       <HandleTarget ref={targetRef}>
-        <HandleWithAudio useTargetFromContext apply={apply}>
+        <HandleWithAudio targetRef="from-context" apply={apply}>
           {children}
         </HandleWithAudio>
       </HandleTarget>

examples/handle/door.tsx

@@ -41,7 +41,7 @@ export function Door(props: JSX.IntrinsicElements['group']) {
               material={materials.Door}
               position={[0.852, 0.017, 0.782]}
             />
-            <Handle useTargetFromContext translate="as-rotate" rotate={{ x: false, y: false, z: [-Math.PI, 0] }}>
+            <Handle targetRef="from-context" translate="as-rotate" rotate={{ x: false, y: false, z: [-Math.PI, 0] }}>
               <group position={[0.81, 0.043, 0.803]}>
                 <Handle
                   stopPropagation={false}

packages/react/handle/src/component.tsx

@@ -41,7 +41,7 @@ export const Handle = forwardRef<
   if (targetRef === 'from-context') {
     if (contextHandleTargetRef == null) {
       throw new Error(
-        `no HandleTarget found in the context of this handle while 'useTargetFromContext' is set. Either wrap the Handle in a <HandleTarget> or remove the 'useTargetFromContext' flag.`,
+        `no HandleTarget found in the context of this handle while 'targetRef="from-context"' is set. Either wrap the Handle in a <HandleTarget> or remove the 'targetRef="from-context"' property or set it to an ref.`,
       )
     }
     targetRef = contextHandleTargetRef