r3f components typing (#1008)

kayden1940 · gkjohnson · web-flow · commit 8be9b483f517 · 2025-04-03T18:01:15.000+09:00
* /r3f components typing

* type update

* r3f type fixes, test cases

* type fixes, formating and misc

* type fixes, misc

* Fix newline

* eslint fixes

* Fix remaining lint errors

* Install eslint version

* Fix lint command, fix lint issues

* Remove unused import

* using tsc to test type checking for r3f props, remove unnecessary packages

* Restore TilesRenderer.test.ts

* Fix lint errors

* package lock update

* Remove DS_STORE from ignore

* spelling error

* incorrect import paths

* types/react install, remove skipLibCheck

* lint fixes

* rollback testing using jest, for switching to vitest in the next pr

* lint, import fixes

---------

Co-authored-by: Garrett Johnson &lt;garrett.kjohnson@gmail.com&gt;
diff --git a/.gitignore b/.gitignore
@@ -62,3 +62,5 @@ typings/
 
 example/local-data
 example/dev-bundle
+
+pnpm-lock.yaml
diff --git a/babel.config.json b/babel.config.json
@@ -11,12 +11,16 @@
 
 					"node": "current"
 
-				}
-
+				},
+				"modules": "auto"
 			}
 
-		]
-
+		],
+		"@babel/preset-react",
+		"@babel/preset-typescript",
+		"@babel/preset-modules"
+	],
+	"ignore": [
+		"/node_modules/"
 	]
-
 }
diff --git a/jest.config.json b/jest.config.json
@@ -1,3 +1,14 @@
 {
-	"testPathIgnorePatterns": ["types"]
+	"transformIgnorePatterns": [
+		"/node_modules/"
+	],
+	"testPathIgnorePatterns": [
+		"/node_modules/",
+		"types"
+	],
+	"preset": "ts-jest",
+	"testEnvironment": "node",
+	"transform": {
+		"^.+\\.js$": "babel-jest"
+	}
 }
diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -29,7 +29,7 @@
   "scripts": {
     "start": "vite --config ./vite.config.js",
     "build-examples": "vite build --config ./vite.config.js",
-    "lint": "eslint \"src/**/*.{js,jsx,ts}\" \"test/**/*.js\" \"example/*.{js,jsx}\" && tsc -p tsconfig.json --noEmit",
+    "lint": "eslint \"src/**/*.{js,jsx,ts}\" \"test/**/*.{js,ts,tsx,jsx}\" \"example/*.{js,jsx}\" && tsc -p tsconfig.json --noEmit",
     "test": "tsc --project tsconfig.test.json && jest"
   },
   "repository": {
@@ -45,19 +45,26 @@
   "devDependencies": {
     "@babel/core": "^7.21.8",
     "@babel/preset-env": "^7.21.5",
+    "@babel/preset-modules": "^0.1.6",
+    "@babel/preset-react": "^7.26.3",
+    "@babel/preset-typescript": "^7.26.0",
     "@react-three/drei": "^9.114.3",
     "@react-three/postprocessing": "^2.16.3",
     "@takram/three-atmosphere": "^0.10.3",
     "@takram/three-geospatial": "^0.1.0",
     "@takram/three-geospatial-effects": "^0.1.0",
     "@types/eslint": "^7.28.1",
+    "@types/jest": "^27.5.2",
+    "@types/react": "^18.3.12",
+    "@types/react-dom": "^18.3.1",
     "@types/three": "^0.166.0",
     "@typescript-eslint/eslint-plugin": "^7.14.1",
     "@typescript-eslint/parser": "^7.14.1",
     "@vitejs/plugin-react": "^4.3.2",
-    "babel-jest": "^29.5.0",
+    "babel-jest": "^27.5.1",
     "cesium": "^1.97.0",
     "concurrently": "^6.2.1",
+    "eslint": "^8.57.1",
     "eslint-config-mdcs": "^5.0.0",
     "eslint-plugin-jest": "^28.6.0",
     "eslint-plugin-react": "^7.37.1",
@@ -67,7 +74,8 @@
     "leva": "^0.9.35",
     "postprocessing": "^6.36.4",
     "three": "^0.170.0",
-    "typescript": "^5.1.3",
+    "ts-jest": "^27.1.5",
+    "typescript": "^4.9.5",
     "vite": "^6.2.2"
   },
   "peerDependencies": {
diff --git a/src/r3f/components/CameraControls.d.ts b/src/r3f/components/CameraControls.d.ts
@@ -0,0 +1,28 @@
+import type { ForwardRefExoticComponent, RefAttributes } from 'react';
+import type { Camera, Object3D } from 'three';
+import type { EnvironmentControls as EnvironmentControlsImpl } from '../../three/controls/EnvironmentControls';
+import type { GlobeControls as GlobeControlsImpl } from '../../three/controls/GlobeControls';
+import type { TilesRenderer } from './TilesRenderer';
+
+interface ControlsBaseProps {
+	domElement?: HTMLCanvasElement | null;
+	scene?: Object3D | null;
+	camera?: Camera | null;
+	tilesRenderer?: typeof TilesRenderer | null;
+}
+
+type EnvironmentControlsProps = Partial<
+	InstanceType<typeof EnvironmentControlsImpl>
+> &
+	ControlsBaseProps;
+
+type GlobeControlsProps = Partial<InstanceType<typeof GlobeControlsImpl>> &
+	ControlsBaseProps;
+
+export declare const EnvironmentControls: ForwardRefExoticComponent<
+	EnvironmentControlsProps & RefAttributes<EnvironmentControlsImpl>
+>;
+
+export declare const GlobeControls: ForwardRefExoticComponent<
+	GlobeControlsProps & RefAttributes<GlobeControlsImpl>
+>;
diff --git a/src/r3f/components/CameraTransition.d.ts b/src/r3f/components/CameraTransition.d.ts
@@ -0,0 +1,13 @@
+import { Camera } from 'three';
+import { CameraTransitionManager } from '../../three/controls/CameraTransitionManager';
+
+interface CameraTransitionProps {
+    mode?: 'perspective' | 'orthographic';
+    onBeforeToggle?: ( manager: CameraTransitionManager, targetCamera: Camera ) => void;
+    perspectiveCamera?: Camera;
+    orthographicCamera?: Camera;
+}
+
+export declare const CameraTransition: React.ForwardRefExoticComponent<
+    CameraTransitionProps & React.RefAttributes<CameraTransitionManager>
+>;
diff --git a/src/r3f/components/CameraTransition.jsx b/src/r3f/components/CameraTransition.jsx
@@ -1,6 +1,6 @@
 import { forwardRef, useEffect, useMemo } from 'react';
 import { useFrame, useThree } from '@react-three/fiber';
-import { CameraTransitionManager } from '3d-tiles-renderer';
+import { CameraTransitionManager } from '../../three/controls/CameraTransitionManager.js';
 import { useDeepOptions } from '../utilities/useOptions.js';
 import { useApplyRefs } from '../utilities/useApplyRefs.js';
 
diff --git a/src/r3f/components/CanvasDOMOverlay.d.ts b/src/r3f/components/CanvasDOMOverlay.d.ts
@@ -0,0 +1,5 @@
+import type { ComponentPropsWithoutRef, ReactNode } from 'react';
+
+export interface CanvasDOMOverlayProps extends ComponentPropsWithoutRef<'div'> {
+    children?: ReactNode;
+}
diff --git a/src/r3f/components/CompassGizmo.d.ts b/src/r3f/components/CompassGizmo.d.ts
@@ -0,0 +1,19 @@
+import type {
+	ReactNode,
+	ForwardRefExoticComponent,
+	RefAttributes,
+} from 'react';
+import type { Group } from 'three';
+
+interface CompassGizmoProps {
+	children?: ReactNode;
+	mode?: '3d' | '2d';
+	visible?: boolean;
+	scale?: number;
+	margin?: number | [number, number];
+	overrideRenderLoop?: boolean;
+}
+
+export declare const CompassGizmo: ForwardRefExoticComponent<
+	CompassGizmoProps & RefAttributes<Group>
+>;
diff --git a/src/r3f/components/SettledObjects.d.ts b/src/r3f/components/SettledObjects.d.ts
@@ -0,0 +1,47 @@
+import { ReactNode } from 'react';
+import { Vector3, Ray } from 'three';
+import { Camera } from '@react-three/fiber';
+
+interface SettledObjectProps {
+    component?: ReactNode;
+    lat?: number | null;
+    lon?: number | null;
+    rayorigin?: Vector3 | null;
+    raydirection?: Vector3 | null;
+    onQueryUpdate?: ( hit: any ) => void;
+    [key: string]: any;
+}
+
+interface AnimatedSettledObjectProps extends SettledObjectProps {
+    interpolationFactor?: number;
+}
+
+interface SettledObjectsProps {
+    scene?: any;
+    children?: ReactNode;
+    [key: string]: any;
+}
+
+interface QueryManagerContextType {
+    registerLatLonQuery( lat: number, lon: number, callback: Function ): number;
+    unregisterQuery( index: number ): void;
+    registerRayQuery( ray: Ray, callback: Function ): number;
+    setScene( scene: any[] ): void;
+    addCamera( camera: Camera ): void;
+    setEllipsoidFromTilesRenderer( tiles: any ): void;
+    dispose(): void;
+}
+
+export const QueryManagerContext: React.Context<QueryManagerContextType | null>;
+
+export const AnimatedSettledObject: React.ForwardRefExoticComponent<
+    AnimatedSettledObjectProps & React.RefAttributes<AnimatedSettledObjectProps>
+>;
+
+export const SettledObject: React.ForwardRefExoticComponent<
+    SettledObjectProps & React.RefAttributes<SettledObjectProps>
+>;
+
+export const SettledObjects: React.ForwardRefExoticComponent<
+    SettledObjectsProps & React.RefAttributes<SettledObjectsProps>
+>;
diff --git a/src/r3f/components/TilesAttributionOverlay.d.ts b/src/r3f/components/TilesAttributionOverlay.d.ts
@@ -0,0 +1,17 @@
+import type { CanvasDOMOverlayProps } from './CanvasDOMOverlay';
+import type { ReactNode, ForwardRefExoticComponent, RefAttributes } from 'react';
+import type { CSSProperties } from 'react';
+
+type Attribution = {
+    type: 'string' | 'html' | 'image';
+    value: any;
+};
+
+interface TilesAttributionOverlayProps extends CanvasDOMOverlayProps {
+    style?: CSSProperties;
+    generateAttributions?: ( ( attributions: Attribution[], classId: string ) => ReactNode ) | null;
+}
+
+export declare const TilesAttributionOverlay: ForwardRefExoticComponent<
+    TilesAttributionOverlayProps & RefAttributes<TilesAttributionOverlayProps>
+>;
diff --git a/src/r3f/components/TilesRenderer.d.ts b/src/r3f/components/TilesRenderer.d.ts
@@ -0,0 +1,66 @@
+import type { TilesRenderer as TilesRendererImpl, TilesRendererEventMap } from '../../three/TilesRenderer';
+import type {
+	ReactNode,
+	Context,
+	ForwardRefExoticComponent,
+	RefAttributes,
+	JSX,
+} from 'react';
+
+export declare const TilesRendererContext: Context<TilesRendererImpl | null>;
+
+interface EastNorthUpFrameProps {
+	lat?: number;
+	lon?: number;
+	height?: number;
+	az?: number;
+	el?: number;
+	roll?: number;
+	children?: ReactNode;
+}
+
+export declare const EastNorthUpFrame: ForwardRefExoticComponent<
+	EastNorthUpFrameProps & RefAttributes<any>
+>;
+
+interface TilesPluginProps<
+	Plugin extends new ( ...args: any[] ) => void,
+	Params extends any[] = ConstructorParameters<Plugin>,
+> {
+	plugin: Plugin;
+	args?: Params;
+	[key: string]: Params | Plugin | any;
+}
+
+export declare const TilesPlugin: <
+	Plugin extends new ( ...args: any[] ) => void,
+	Params extends any[] = ConstructorParameters<Plugin>,
+>(
+	props: TilesPluginProps<Plugin, Params> & RefAttributes<Plugin>,
+) => JSX.Element;
+
+// dynamically mapping keys of TilesRendererEventMap to onCamelCased
+type CamelCase<S extends string> = S extends `${infer T}-${infer U}`
+	? `${T}${Capitalize<CamelCase<U>>}`
+	: S;
+
+type EventHandler<K extends keyof TilesRendererEventMap> = (
+	event: TilesRendererEventMap[K],
+) => void;
+
+type TilesRendererEventMapForR3f = {
+	[K in keyof TilesRendererEventMap as `on${Capitalize<CamelCase<K>>}`]?: EventHandler<K>;
+};
+
+interface TilesRendererProps
+	extends Partial<TilesRendererImpl>,
+	TilesRendererEventMapForR3f {
+	url?: string;
+	enabled?: boolean;
+	dispose?: () => void;
+	children?: ReactNode;
+}
+
+export declare const TilesRenderer: ForwardRefExoticComponent<
+	TilesRendererProps & RefAttributes<TilesRendererImpl>
+>;
diff --git a/src/r3f/index.d.ts b/src/r3f/index.d.ts
@@ -0,0 +1,7 @@
+export * from './components/CameraControls';
+export * from './components/CameraTransition';
+export * from './components/CanvasDOMOverlay';
+export * from './components/CompassGizmo';
+export * from './components/SettledObjects';
+export * from './components/TilesAttributionOverlay';
+export * from './components/TilesRenderer';
diff --git a/test/types/TilesRenderer.test.ts b/test/types/TilesRenderer.test.ts
@@ -1,15 +1,16 @@
 import { Camera, Object3D } from 'three';
 import { Tile, TilesRenderer } from '../../src';
+import { expect, test } from '@jest/globals';
 
-function addCamera( event: { camera: Camera } ) {}
-function deleteCamera( event: { camera: Camera } ) {}
-function emptyEvent( event: { } ) {}
-function loadTileset( event: { tileSet: object, url: string } ) {}
-function loadModel( event: { scene: Object3D; tile: Tile } ) {}
-function disposeModel( event: { scene: Object3D; tile: Tile; } ) {}
-function tileVisibilityChange( event: { scene: Object3D; tile: Tile; visible: boolean } ) {}
+function addCamera( event: { camera: Camera } ) { }
+function deleteCamera( event: { camera: Camera } ) { }
+function emptyEvent( event: {} ) { }
+function loadTileset( event: { tileSet: object, url: string } ) { }
+function loadModel( event: { scene: Object3D; tile: Tile } ) { }
+function disposeModel( event: { scene: Object3D; tile: Tile; } ) { }
+function tileVisibilityChange( event: { scene: Object3D; tile: Tile; visible: boolean } ) { }
 
-function whatever( event: unknown ) {}
+function whatever( event: unknown ) { }
 
 // This function is not meant to be executed, but just here to
 // guarantee that the exported types match what is expected.
@@ -35,3 +36,15 @@ function typecheck( renderer: TilesRenderer ) {
 	renderer.addEventListener( 'my-unknown-event', whatever );
 
 }
+
+test( 'TilesRenderer should not throw', () => {
+
+	const renderer = new TilesRenderer( 'https://raw.githubusercontent.com/NASA-AMMOS/3DTilesSampleData/master/msl-dingo-gap/0528_0260184_to_s64o256_colorize/0528_0260184_to_s64o256_colorize/0528_0260184_to_s64o256_colorize_tileset.json' );
+
+	expect( () => {
+
+		typecheck( renderer );
+
+	} ).not.toThrow();
+
+} );
diff --git a/test/types/r3f/typeCheck.test.tsx b/test/types/r3f/typeCheck.test.tsx
@@ -0,0 +1,12 @@
+import { EnvironmentControls } from '../../../src/r3f';
+import React from 'react';
+
+// EnvironmentControls taking valid props, not expect ts error.
+<EnvironmentControls enableDamping={ true } />;
+
+// EnvironmentControls taking invalid props, expect ts error. tsc test will fail if ts-expect-error directive failed to capture error.
+//@ts-expect-error
+<EnvironmentControls enableDamping={ 'incorrect type' }/>;
+
+//@ts-expect-error
+<EnvironmentControls foo={ 'bar' } />;
diff --git a/tsconfig.test.json b/tsconfig.test.json
@@ -2,6 +2,10 @@
 	"extends": "./tsconfig.json",
 	"compilerOptions": {
 		"noEmit": true,
+		"target": "esnext",
+		"module": "commonjs",
+		"esModuleInterop": true,
+		"jsx": "react-jsx"
 	},
 	"include": [
 		"test/types/"
diff --git a/vite.config.js b/vite.config.js
@@ -31,6 +31,6 @@ export default ( { mode } ) => {
 			},
 		},
 		plugins: [ react() ],
-	}
+	};
 
 };

Original file line number	Diff line number	Diff line change
`@@ -11,12 +11,16 @@`
`11`	`11`
`12`	`12`	`"node": "current"`
`13`	`13`
`14`		`- }`
`15`		`-`
	`14`	`+ },`
	`15`	`+ "modules": "auto"`
`16`	`16`	`}`
`17`	`17`
`18`		`- ]`
`19`		`-`
	`18`	`+ ],`
	`19`	`+ "@babel/preset-react",`
	`20`	`+ "@babel/preset-typescript",`
	`21`	`+ "@babel/preset-modules"`
	`22`	`+ ],`
	`23`	`+ "ignore": [`
	`24`	`+ "/node_modules/"`
`20`	`25`	`]`
`21`		`-`
`22`	`26`	`}`