@react-three/drei 9.31.2 → 9.32.1

package/README.md

@@ -48,7 +48,8 @@ The `native` route of the library **does not** export `Html` or `Loader`. The de
           <li><a href="#controls">PointerLockControls</a></li>
           <li><a href="#controls">FirstPersonControls</a></li>          
           <li><a href="#scrollcontrols">ScrollControls</a></li>
-          <li><a href="#presentationcontrols">PresentationControls</a></li>          
+          <li><a href="#presentationcontrols">PresentationControls</a></li>
+          <li><a href="#keyboardcontrols">KeyboardControls</a></li>
         </ul>
         <li><a href="#gizmos">Gizmos</a></li>
         <ul>
@@ -385,6 +386,79 @@ Semi-OrbitControls with spring-physics, polar zoom and snap-back, for presentati
 </PresentationControls>
 ```
 
+#### KeyboardControls
+
+![](https://img.shields.io/badge/-Dom only-red)
+
+A rudimentary keyboard controller which distributes your defined data-model to the `useKeyboard` hook. It's a rather simple way to get started with keyboard input.
+
+```tsx
+type KeyboardControlsState = { [key: string]: boolean }
+
+type KeyboardControlsEntry = {
+  /** Name of the action */
+  name: string
+  /** The keys that define it, you can use either event.key, or event.code */
+  keys: string[]
+  /** If the event receives the keyup event, true by default */
+  up?: boolean
+}
+
+type KeyboardControlsProps = {
+  /** A map of named keys */
+  map: KeyboardControlsEntry[]
+  /** All children will be able to useKeyboardControls */
+  children: React.ReactNode
+  /** Optional onchange event */
+  onChange: (name: string, pressed: boolean, state: KeyboardControlsState) => void
+  /** Optional event source */
+  domElement?: HTMLElement
+}
+```
+
+You start by wrapping your app, or scene, into `<KeyboardControls>`.
+
+```jsx
+function App() {
+  return (
+    <KeyboardControls
+      map={[
+        { name: 'forward', keys: ['ArrowUp', 'w', 'W'] },
+        { name: 'backward', keys: ['ArrowDown', 's', 'S'] },
+        { name: 'leftward', keys: ['ArrowLeft', 'a', 'A'] },
+        { name: 'rightward', keys: ['ArrowRight', 'd', 'D'] },
+        { name: 'jump', keys: ['Space'] },
+      ]}>
+      <App />
+    </KeyboardControls>
+```
+
+You can either respond to input reactively, it uses zustand (width the `subscribeWithSelector` middleware) so all the rules apply:
+
+```jsx
+function Foo() {
+  const pressed = useKeyboardControls(state => foward)
+```
+
+Or transiently, either by `subscribe`, which is a function which returns a function to unsubscribe, so you can pair it with useEffect for cleanup, or `get`, which fetches fresh state non-reactively.
+
+```jsx
+function Foo() {
+  const [sub, get] = useKeyboardControls()
+
+  useEffect(() => {
+    return sub(state => state.forward, pressed => {
+      console.log('forward', pressed)
+    })
+  }, [])
+
+  useFrame(() => {
+    // Fetch fresh data from store
+    const pressed = get().backward
+  })
+}
+```
+
 # Gizmos
 
 #### GizmoHelper
@@ -2124,15 +2198,17 @@ function App() {
       <PerformanceMonitor onIncline={() => setDpr(2)} onDecline={() => setDpr(1)} >
 ```
 
-You can also use the `onChange` callback to get notified when the average changes in whichever direction. This allows you to make gradual changes. It gives you a factor between 0 and 1, which is increased by incline and decreased by decline. The factor is initially 0.5 by default.
+You can also use the `onChange` callback to get notified when the average changes in whichever direction. This allows you to make gradual changes. It gives you a `factor` between 0 and 1, which is increased by incline and decreased by decline. The `factor` is initially 0.5 by default. If your app starts with lowest defaults and gradually increases quality set `factor` to 0. If it starts with highest defaults and decreases quality, set it to 1. If it starts in the middle and can either increase or decrease, set it to 0.5.
+
+The following starts at the highest dpr (2) and clamps the gradual dpr between 0.5 at the lowest and 2 at the highest. If the app is in trouble it will reduce `factor` by `step` until it is either 0 or the app has found its sweet spot above that. 
 
 ```jsx
 import round from 'lodash/round'
 
-const [dpr, set] = useState(1)
+const [dpr, set] = useState(2)
 return (
  <Canvas dpr={dpr}>
-  <PerformanceMonitor onChange={({ factor }) => setDpr(round(0.5 + 1.5 * factor, 1))} >
+  <PerformanceMonitor factor={1} onChange={({ factor }) => setDpr(round(0.5 + 1.5 * factor, 1))} >
 ```
 
 If you still experience flip flops despite the bounds you can define a limit of `flipflops`. If it is met `onFallback` will be triggered which typically sets a lowest possible baseline for the app. After the fallback has been called PerformanceMonitor will shut down.

package/core/FlyControls.cjs.js

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,"__esModule",{value:!0});var e=require("@babel/runtime/helpers/extends"),t=require("@react-three/fiber"),r=require("react"),n=require("three-stdlib");function u(e){return e&&"object"==typeof e&&"default"in e?e:{default:e}}function l(e){if(e&&e.__esModule)return e;var t=Object.create(null);return e&&Object.keys(e).forEach((function(r){if("default"!==r){var n=Object.getOwnPropertyDescriptor(e,r);Object.defineProperty(t,r,n.get?n:{enumerable:!0,get:function(){return e[r]}})}})),t.default=e,Object.freeze(t)}var o=u(e),a=l(r);const i=a.forwardRef((({domElement:e,...r},u)=>{const{onChange:l,...i}=r,c=t.useThree((e=>e.invalidate)),s=t.useThree((e=>e.camera)),d=t.useThree((e=>e.gl)),f=t.useThree((e=>e.events)),v=e||f.connected||d.domElement,[b]=a.useState((()=>new n.FlyControls(s,v)));return a.useEffect((()=>{const e=e=>{c(),l&&l(e)};return null==b||null==b.addEventListener||b.addEventListener("change",e),()=>null==b||null==b.removeEventListener?void 0:b.removeEventListener("change",e)}),[l,b,c]),t.useFrame(((e,t)=>null==b?void 0:b.update(t))),b?a.createElement("primitive",o.default({ref:u,object:b},i)):null}));exports.FlyControls=i;
+"use strict";Object.defineProperty(exports,"__esModule",{value:!0});var e=require("@babel/runtime/helpers/extends"),t=require("@react-three/fiber"),r=require("react"),n=require("three-stdlib");function u(e){return e&&"object"==typeof e&&"default"in e?e:{default:e}}function o(e){if(e&&e.__esModule)return e;var t=Object.create(null);return e&&Object.keys(e).forEach((function(r){if("default"!==r){var n=Object.getOwnPropertyDescriptor(e,r);Object.defineProperty(t,r,n.get?n:{enumerable:!0,get:function(){return e[r]}})}})),t.default=e,Object.freeze(t)}var s=u(e),c=o(r);const a=c.forwardRef((({domElement:e,...r},u)=>{const{onChange:o,...a}=r,i=t.useThree((e=>e.invalidate)),l=t.useThree((e=>e.camera)),f=t.useThree((e=>e.gl)),d=t.useThree((e=>e.events)),v=e||d.connected||f.domElement,b=c.useMemo((()=>new n.FlyControls(l)),[l]);return c.useEffect((()=>(b.connect(v),()=>{b.dispose()})),[v,b,i]),c.useEffect((()=>{const e=e=>{i(),o&&o(e)};return null==b.addEventListener||b.addEventListener("change",e),()=>null==b.removeEventListener?void 0:b.removeEventListener("change",e)}),[o,i]),t.useFrame(((e,t)=>b.update(t))),c.createElement("primitive",s.default({ref:u,object:b,args:[l,v]},a))}));exports.FlyControls=a;

package/core/FlyControls.d.ts

@@ -6,4 +6,4 @@ export declare type FlyControlsProps = ReactThreeFiber.Object3DNode<FlyControlsI
     onChange?: (e?: THREE.Event) => void;
     domElement?: HTMLElement;
 };
-export declare const FlyControls: React.ForwardRefExoticComponent<Pick<FlyControlsProps, "object" | "attach" | "args" | "children" | "key" | "onUpdate" | "position" | "up" | "scale" | "rotation" | "matrix" | "quaternion" | "layers" | "dispose" | "addEventListener" | "hasEventListener" | "removeEventListener" | "dispatchEvent" | "onChange" | keyof import("@react-three/fiber/dist/declarations/src/core/events").EventHandlers | "update" | "domElement" | "movementSpeed" | "rollSpeed" | "dragToLook" | "autoForward"> & React.RefAttributes<FlyControlsImpl>>;
+export declare const FlyControls: React.ForwardRefExoticComponent<Pick<FlyControlsProps, "object" | "attach" | "args" | "children" | "key" | "onUpdate" | "position" | "up" | "scale" | "rotation" | "matrix" | "quaternion" | "layers" | "dispose" | "addEventListener" | "hasEventListener" | "removeEventListener" | "dispatchEvent" | "onChange" | keyof import("@react-three/fiber/dist/declarations/src/core/events").EventHandlers | "connect" | "update" | "domElement" | "movementSpeed" | "rollSpeed" | "dragToLook" | "autoForward"> & React.RefAttributes<FlyControlsImpl>>;

package/core/FlyControls.js

@@ -6,7 +6,7 @@ import { FlyControls as FlyControls$1 } from 'three-stdlib';
 const FlyControls = /*#__PURE__*/React.forwardRef(({
   domElement,
   ...props
-}, ref) => {
+}, fref) => {
   const {
     onChange,
     ...rest
@@ -16,21 +16,26 @@ const FlyControls = /*#__PURE__*/React.forwardRef(({
   const gl = useThree(state => state.gl);
   const events = useThree(state => state.events);
   const explDomElement = domElement || events.connected || gl.domElement;
-  const [controls] = React.useState(() => new FlyControls$1(camera, explDomElement));
+  const controls = React.useMemo(() => new FlyControls$1(camera), [camera]);
+  React.useEffect(() => {
+    controls.connect(explDomElement);
+    return () => void controls.dispose();
+  }, [explDomElement, controls, invalidate]);
   React.useEffect(() => {
     const callback = e => {
       invalidate();
       if (onChange) onChange(e);
     };
 
-    controls == null ? void 0 : controls.addEventListener == null ? void 0 : controls.addEventListener('change', callback);
-    return () => controls == null ? void 0 : controls.removeEventListener == null ? void 0 : controls.removeEventListener('change', callback);
-  }, [onChange, controls, invalidate]);
-  useFrame((_, delta) => controls == null ? void 0 : controls.update(delta));
-  return controls ? /*#__PURE__*/React.createElement("primitive", _extends({
-    ref: ref,
-    object: controls
-  }, rest)) : null;
+    controls.addEventListener == null ? void 0 : controls.addEventListener('change', callback);
+    return () => controls.removeEventListener == null ? void 0 : controls.removeEventListener('change', callback);
+  }, [onChange, invalidate]);
+  useFrame((_, delta) => controls.update(delta));
+  return /*#__PURE__*/React.createElement("primitive", _extends({
+    ref: fref,
+    object: controls,
+    args: [camera, explDomElement]
+  }, rest));
 });
 
 export { FlyControls };

package/core/MapControls.d.ts

@@ -11,4 +11,4 @@ export declare type MapControlsProps = ReactThreeFiber.Overwrite<ReactThreeFiber
     onEnd?: (e?: THREE.Event) => void;
     domElement?: HTMLElement;
 }>;
-export declare const MapControls: React.ForwardRefExoticComponent<Pick<MapControlsProps, "object" | "attach" | "args" | "children" | "key" | "onUpdate" | "position" | "up" | "scale" | "rotation" | "matrix" | "quaternion" | "layers" | "dispose" | "addEventListener" | "hasEventListener" | "removeEventListener" | "dispatchEvent" | "onChange" | keyof import("@react-three/fiber/dist/declarations/src/core/events").EventHandlers | "camera" | "reset" | "enabled" | "connect" | "update" | "target" | "onStart" | "keys" | "touches" | "makeDefault" | "domElement" | "minDistance" | "maxDistance" | "minZoom" | "maxZoom" | "minPolarAngle" | "maxPolarAngle" | "minAzimuthAngle" | "maxAzimuthAngle" | "enableDamping" | "dampingFactor" | "enableZoom" | "zoomSpeed" | "enableRotate" | "rotateSpeed" | "enablePan" | "panSpeed" | "screenSpacePanning" | "keyPanSpeed" | "autoRotate" | "autoRotateSpeed" | "reverseOrbit" | "mouseButtons" | "target0" | "position0" | "zoom0" | "_domElementKeyEvents" | "getPolarAngle" | "getAzimuthalAngle" | "setPolarAngle" | "setAzimuthalAngle" | "getDistance" | "listenToKeyEvents" | "saveState" | "onEnd"> & React.RefAttributes<MapControlsImpl>>;
+export declare const MapControls: React.ForwardRefExoticComponent<Pick<MapControlsProps, "object" | "attach" | "args" | "children" | "key" | "onUpdate" | "position" | "up" | "scale" | "rotation" | "matrix" | "quaternion" | "layers" | "dispose" | "addEventListener" | "hasEventListener" | "removeEventListener" | "dispatchEvent" | "onChange" | keyof import("@react-three/fiber/dist/declarations/src/core/events").EventHandlers | "camera" | "reset" | "enabled" | "connect" | "update" | "target" | "onStart" | "keys" | "touches" | "domElement" | "makeDefault" | "minDistance" | "maxDistance" | "minZoom" | "maxZoom" | "minPolarAngle" | "maxPolarAngle" | "minAzimuthAngle" | "maxAzimuthAngle" | "enableDamping" | "dampingFactor" | "enableZoom" | "zoomSpeed" | "enableRotate" | "rotateSpeed" | "enablePan" | "panSpeed" | "screenSpacePanning" | "keyPanSpeed" | "autoRotate" | "autoRotateSpeed" | "reverseOrbit" | "mouseButtons" | "target0" | "position0" | "zoom0" | "_domElementKeyEvents" | "getPolarAngle" | "getAzimuthalAngle" | "setPolarAngle" | "setAzimuthalAngle" | "getDistance" | "listenToKeyEvents" | "saveState" | "onEnd"> & React.RefAttributes<MapControlsImpl>>;

package/core/TrackballControls.d.ts

@@ -12,4 +12,4 @@ export declare type TrackballControlsProps = ReactThreeFiber.Overwrite<ReactThre
     onStart?: (e?: THREE.Event) => void;
     onEnd?: (e?: THREE.Event) => void;
 }>;
-export declare const TrackballControls: React.ForwardRefExoticComponent<Pick<TrackballControlsProps, "object" | "attach" | "args" | "children" | "key" | "onUpdate" | "position" | "up" | "scale" | "rotation" | "matrix" | "quaternion" | "layers" | "dispose" | "addEventListener" | "hasEventListener" | "removeEventListener" | "dispatchEvent" | "onChange" | keyof import("@react-three/fiber/dist/declarations/src/core/events").EventHandlers | "camera" | "screen" | "reset" | "enabled" | "connect" | "update" | "target" | "onStart" | "keys" | "makeDefault" | "domElement" | "minDistance" | "maxDistance" | "zoomSpeed" | "rotateSpeed" | "panSpeed" | "mouseButtons" | "onEnd" | "regress" | "noRotate" | "noZoom" | "noPan" | "staticMoving" | "dynamicDampingFactor" | "cursorZoom" | "handleResize"> & React.RefAttributes<TrackballControlsImpl>>;
+export declare const TrackballControls: React.ForwardRefExoticComponent<Pick<TrackballControlsProps, "object" | "attach" | "args" | "children" | "key" | "onUpdate" | "position" | "up" | "scale" | "rotation" | "matrix" | "quaternion" | "layers" | "dispose" | "addEventListener" | "hasEventListener" | "removeEventListener" | "dispatchEvent" | "onChange" | keyof import("@react-three/fiber/dist/declarations/src/core/events").EventHandlers | "camera" | "screen" | "reset" | "enabled" | "connect" | "update" | "target" | "onStart" | "keys" | "domElement" | "makeDefault" | "minDistance" | "maxDistance" | "zoomSpeed" | "rotateSpeed" | "panSpeed" | "mouseButtons" | "onEnd" | "regress" | "noRotate" | "noZoom" | "noPan" | "staticMoving" | "dynamicDampingFactor" | "cursorZoom" | "handleResize"> & React.RefAttributes<TrackballControlsImpl>>;

package/core/useGLTF.d.ts

@@ -1,5 +1,5 @@
-import { GLTFLoader, GLTF } from 'three-stdlib';
-export declare function useGLTF<T extends string | string[]>(path: T, useDraco?: boolean | string, useMeshOpt?: boolean, extendLoader?: (loader: GLTFLoader) => void): T extends any[] ? GLTF[] : GLTF;
+import { GLTFLoader } from 'three-stdlib';
+export declare function useGLTF<T extends string | string[]>(path: T, useDraco?: boolean | string, useMeshOpt?: boolean, extendLoader?: (loader: GLTFLoader) => void): T extends any[] ? (import("three/examples/jsm/loaders/GLTFLoader").GLTF & import("@react-three/fiber").ObjectMap)[] : import("three/examples/jsm/loaders/GLTFLoader").GLTF & import("@react-three/fiber").ObjectMap;
 export declare namespace useGLTF {
     var preload: (path: string | string[], useDraco?: string | boolean, useMeshOpt?: boolean, extendLoader?: ((loader: GLTFLoader) => void) | undefined) => undefined;
     var clear: (input: string | string[]) => void;