feat: CameraControls[impl] custom subclass (#2466)

* CameraControls[impl] subclass

* .

* doc

* .

Author: abernier

.storybook/stories/CameraControls.stories.tsx

@@ -4,7 +4,7 @@ import * as THREE from 'three'
 import { Meta, StoryObj } from '@storybook/react-vite'
 
 import { Setup } from '../Setup'
-import { Box, CameraControls, PerspectiveCamera, Plane, useFBO } from '../../src'
+import { Box, CameraControls, CameraControlsImpl, PerspectiveCamera, Plane, useFBO } from '../../src'
 
 export default {
   title: 'Controls/CameraControls',
@@ -131,3 +131,34 @@ export const CameraControlsSt3 = {
   ),
   name: 'frameloop="demand"',
 } satisfies Story
+
+//
+
+function CameraControlsScene4(props: ComponentProps<typeof CameraControls>) {
+  const cameraControlRef = useRef<CameraControls>(null)
+
+  return (
+    <Setup controls={false}>
+      <CameraControls ref={cameraControlRef} {...props} />
+      <Box
+        onClick={() => {
+          cameraControlRef.current?.rotate(Math.PI / 4, 0, true)
+        }}
+      >
+        <meshBasicMaterial wireframe />
+      </Box>
+    </Setup>
+  )
+}
+
+class MyCameraControls extends CameraControlsImpl {
+  override rotate(...args: Parameters<CameraControlsImpl['rotate']>) {
+    console.log('rotate', ...args)
+    return super.rotate(...args)
+  }
+}
+
+export const CameraControlsSt4 = {
+  render: (args) => <CameraControlsScene4 impl={MyCameraControls} {...args} />,
+  name: 'Subclass',
+} satisfies Story

docs/controls/camera-controls.mdx

@@ -17,6 +17,8 @@ This is an implementation of the [camera-controls](https://github.com/yomotsu/ca
 
 ```tsx
 type CameraControlsProps = {
+  /** Optional CameraControls subclass, default to `CameraControlsImpl` official class */
+  impl?: typeof CameraControlsImpl
   /** The camera to control, default to the state's `camera` */
   camera?: PerspectiveCamera | OrthographicCamera
   /** DOM element to connect to, default to the state's `gl` renderer */
@@ -77,3 +79,18 @@ const { ACTION } = CameraControlsImpl;
   }}
 />
 ```
+
+### `[impl]` custom subclass
+
+You can pass a custom subclass of `CameraControlsImpl` to the `impl` prop. This allows you to override methods or add new functionality:
+
+```tsx
+class MyCameraControls extends CameraControlsImpl {
+  override rotate(...args: Parameters<CameraControlsImpl['rotate']>) {
+    console.log('my rotate', ...args)
+    return super.rotate(...args)
+  }
+}
+
+<CameraControls impl={MyCameraControls} />
+```

src/core/CameraControls.tsx

@@ -26,6 +26,7 @@ export type CameraControlsProps = Omit<
   Overwrite<
     ThreeElement<typeof CameraControlsImpl>,
     {
+      impl?: typeof CameraControlsImpl
       camera?: PerspectiveCamera | OrthographicCamera
       domElement?: HTMLElement
       makeDefault?: boolean
@@ -57,6 +58,28 @@ export const CameraControls: ForwardRefComponent<CameraControlsProps, CameraCont
   CameraControlsImpl,
   CameraControlsProps
 >((props, ref) => {
+  const {
+    impl: SubclassImpl,
+    camera,
+    domElement,
+    makeDefault,
+    onControlStart,
+    onControl,
+    onControlEnd,
+    onTransitionStart,
+    onUpdate,
+    onWake,
+    onRest,
+    onSleep,
+    onStart,
+    onEnd,
+    onChange,
+    regress,
+    ...restProps
+  } = props
+
+  const Impl = SubclassImpl ?? CameraControlsImpl
+
   // useMemo is used here instead of useEffect, otherwise the useMemo below runs first and throws
   useMemo(() => {
     // to allow for tree shaking, we only import the subset of THREE that is used by camera-controls
@@ -76,28 +99,9 @@ export const CameraControls: ForwardRefComponent<CameraControlsProps, CameraCont
       Vector4,
     }
 
-    CameraControlsImpl.install({ THREE: subsetOfTHREE })
-    extend({ CameraControlsImpl })
-  }, [])
-
-  const {
-    camera,
-    domElement,
-    makeDefault,
-    onControlStart,
-    onControl,
-    onControlEnd,
-    onTransitionStart,
-    onUpdate,
-    onWake,
-    onRest,
-    onSleep,
-    onStart,
-    onEnd,
-    onChange,
-    regress,
-    ...restProps
-  } = props
+    Impl.install({ THREE: subsetOfTHREE })
+    extend({ CameraControlsImpl: Impl })
+  }, [Impl])
 
   const defaultCamera = useThree((state) => state.camera)
   const gl = useThree((state) => state.gl)
@@ -111,7 +115,7 @@ export const CameraControls: ForwardRefComponent<CameraControlsProps, CameraCont
   const explCamera = camera || defaultCamera
   const explDomElement = (domElement || events.connected || gl.domElement) as HTMLElement
 
-  const controls = useMemo(() => new CameraControlsImpl(explCamera), [explCamera])
+  const controls = useMemo(() => new Impl(explCamera), [Impl, explCamera])
 
   useFrame((state, delta) => {
     controls.update(delta)