Add auto-gen for r3f comonents (#1515)

Author: gkjohnson

src/r3f/components/CameraControls.jsx

@@ -108,12 +108,30 @@ const ControlsBaseComponent = forwardRef( function ControlsBaseComponent( props,
 
 } );
 
+/**
+ * Wraps the three.js EnvironmentControls class. Automatically attaches to the R3F camera, scene,
+ * and canvas. All EnvironmentControls properties can be set as props.
+ * @component
+ * @param {Object} props
+ * @param {Camera} [props.camera] - Override the default R3F camera.
+ * @param {Object3D} [props.scene] - Override the default R3F scene.
+ * @param {HTMLCanvasElement} [props.domElement] - Override the default canvas element.
+ */
 export const EnvironmentControls = forwardRef( function EnvironmentControls( props, ref ) {
 
 	return <ControlsBaseComponent { ...props } ref={ ref } controlsConstructor={ EnvironmentControlsImpl } />;
 
 } );
 
+/**
+ * Wraps the three.js GlobeControls class. Must be a child of TilesRenderer to receive ellipsoid
+ * context. All GlobeControls properties can be set as props.
+ * @component
+ * @param {Object} props
+ * @param {Camera} [props.camera] - Override the default R3F camera.
+ * @param {Object3D} [props.scene] - Override the default R3F scene.
+ * @param {HTMLCanvasElement} [props.domElement] - Override the default canvas element.
+ */
 export const GlobeControls = forwardRef( function GlobeControls( props, ref ) {
 
 	return <ControlsBaseComponent { ...props } ref={ ref } controlsConstructor={ GlobeControlsImpl } />;

src/r3f/components/CameraTransition.jsx

@@ -4,6 +4,17 @@ import { CameraTransitionManager } from '3d-tiles-renderer/three';
 import { useDeepOptions } from '../utilities/useOptions.js';
 import { useApplyRefs } from '../utilities/useApplyRefs.js';
 
+/**
+ * Manages transitions between perspective and orthographic cameras. Wraps CameraTransitionManager
+ * and integrates with R3F's camera state. All CameraTransitionManager properties can be set as props.
+ * @component
+ * @param {Object} props
+ * @param {string} [props.mode='perspective'] - Active camera mode: `'perspective'` or `'orthographic'`.
+ * @param {PerspectiveCamera} [props.perspectiveCamera] - Override the internal perspective camera.
+ * @param {OrthographicCamera} [props.orthographicCamera] - Override the internal orthographic camera.
+ * @param {Function} [props.onBeforeToggle] - Called before the camera mode switches, with the manager
+ * and target camera as arguments. Defaults to syncing via active controls if present.
+ */
 export const CameraTransition = forwardRef( function CameraTransition( props, ref ) {
 
 	const {

src/r3f/components/CanvasDOMOverlay.jsx

@@ -2,6 +2,13 @@ import { useMemo, useEffect, StrictMode, forwardRef, useState } from 'react';
 import { createRoot } from 'react-dom/client';
 import { useThree } from '@react-three/fiber';
 
+/**
+ * Creates a DOM overlay positioned absolutely over the canvas. Children are rendered into a
+ * separate React root. Remaining props are passed to the root div element.
+ * @component
+ * @param {Object} props
+ * @param {ReactNode} [props.children] - DOM content to render in the overlay.
+ */
 // Utility class for overlaying dom elements on top of the canvas
 export const CanvasDOMOverlay = forwardRef( function CanvasDOMOverlay( { children, ...rest }, ref ) {
 

src/r3f/components/CompassGizmo.jsx

@@ -149,6 +149,19 @@ function CompassGraphic( { northColor = 0xEF5350, southColor = 0xFFFFFF } ) {
 
 }
 
+/**
+ * Renders a compass overlay that rotates to indicate north based on the camera orientation relative
+ * to the tileset ellipsoid. Must be a child of TilesRenderer. Remaining props are passed to the
+ * root group element.
+ * @component
+ * @param {Object} props
+ * @param {string} [props.mode='3d'] - Rotation mode: `'3d'` tracks full camera orientation, `'2d'` tracks yaw only.
+ * @param {number} [props.scale=35] - Size of the compass in pixels.
+ * @param {number|Array} [props.margin=10] - Margin from the bottom-right corner in pixels. Pass `[x, y]` to set each axis independently.
+ * @param {boolean} [props.visible=true] - Whether the compass is rendered.
+ * @param {boolean} [props.overrideRenderLoop] - If true, renders the main scene before drawing the compass overlay.
+ * @param {ReactNode} [props.children] - Custom compass graphic replacing the default. Should fit within a -0.5 to 0.5 unit cube with +Y pointing north and +X pointing east.
+ */
 export function CompassGizmo( { children, overrideRenderLoop, mode = '3d', margin = 10, scale = 35, visible = true, ...rest } ) {
 
 	const [ defaultCamera, defaultScene, size ] = useThree( state => [ state.camera, state.scene, state.size ] );

src/r3f/components/SettledObjects.jsx

@@ -12,6 +12,14 @@ const QueryManagerContext = createContext( null );
 const _matrix = /* @__PURE__ */ new Matrix4();
 const _ray = /* @__PURE__ */ new Ray();
 
+/**
+ * A SettledObject that smoothly interpolates its position as the query result updates.
+ * Must be a descendant of SettledObjects.
+ * @component
+ * @param {Object} props
+ * @param {number} [props.interpolationFactor=0.025] - Controls interpolation speed. Smaller values produce slower, smoother movement.
+ * @param {Function} [props.onQueryUpdate] - Called with the raycast hit result each time the query updates.
+ */
 export const AnimatedSettledObject = forwardRef( function AnimatedSettledObject( props, ref ) {
 
 	const {
@@ -115,6 +123,18 @@ export const AnimatedSettledObject = forwardRef( function AnimatedSettledObject(
 
 } );
 
+/**
+ * Positions a component on the surface of the tileset at a lat/lon coordinate or along a ray.
+ * Must be a descendant of SettledObjects.
+ * @component
+ * @param {Object} props
+ * @param {ReactNode} [props.component=<group/>] - The element to clone and position on the surface.
+ * @param {number} [props.lat=null] - Latitude in radians. Use with `lon` for geographic positioning.
+ * @param {number} [props.lon=null] - Longitude in radians. Use with `lat` for geographic positioning.
+ * @param {Vector3} [props.rayorigin=null] - Ray origin for arbitrary ray-based positioning.
+ * @param {Vector3} [props.raydirection=null] - Ray direction for arbitrary ray-based positioning.
+ * @param {Function} [props.onQueryUpdate] - Called with the raycast hit result each time the query updates.
+ */
 // Object that updates its "settled" state
 export const SettledObject = forwardRef( function SettledObject( props, ref ) {
 
@@ -184,6 +204,14 @@ export const SettledObject = forwardRef( function SettledObject( props, ref ) {
 
 } );
 
+/**
+ * Manages raycasting queries against the tileset for positioning child SettledObject components.
+ * Must be a child of TilesRenderer. All QueryManager properties can be set as props.
+ * @component
+ * @param {Object} props
+ * @param {Object3D|Array} [props.scene] - Scene(s) to raycast against. Defaults to the R3F scene.
+ * @param {ReactNode} [props.children] - SettledObject or AnimatedSettledObject components.
+ */
 export const SettledObjects = forwardRef( function SettledObjects( props, ref ) {
 
 	const threeScene = useThree( ( { scene } ) => scene );

src/r3f/components/TilesAttributionOverlay.jsx

@@ -8,6 +8,16 @@ function randomID() {
 
 }
 
+/**
+ * Displays attributions collected from the loaded tileset. Must be a child of TilesRenderer.
+ * Remaining props are passed to the underlying CanvasDOMOverlay element.
+ * @component
+ * @param {Object} props
+ * @param {Function} [props.generateAttributions] - Custom function to generate attribution elements.
+ * Receives the attributions array and the overlay element's unique id. Defaults to built-in rendering.
+ * @param {Object} [props.style] - Style overrides applied to the overlay container.
+ * @param {ReactNode} [props.children] - Additional content rendered above the attributions.
+ */
 // Overlay for displaying tile data set attributions
 export function TilesAttributionOverlay( { children, style, generateAttributions, ...rest } ) {
 

src/r3f/components/TilesRenderer.jsx

@@ -32,6 +32,20 @@ function TileSetRoot( { children } ) {
 
 }
 
+/**
+ * Creates a group positioned and oriented at a geographic coordinate on the tileset ellipsoid.
+ * Must be a child of TilesRenderer. Does not modify the tileset transform.
+ * @component
+ * @param {Object} props
+ * @param {number} [props.lat=0] - Latitude in radians.
+ * @param {number} [props.lon=0] - Longitude in radians.
+ * @param {number} [props.height=0] - Height above the ellipsoid in meters.
+ * @param {number} [props.az=0] - Azimuth rotation in radians, applied first.
+ * @param {number} [props.el=0] - Elevation rotation in radians, applied second.
+ * @param {number} [props.roll=0] - Roll rotation in radians, applied third.
+ * @param {Ellipsoid} [props.ellipsoid] - Ellipsoid to use when no TilesRenderer parent is present.
+ * @param {ReactNode} [props.children] - Children positioned relative to the east-north-up frame.
+ */
 export function EastNorthUpFrame( props ) {
 
 	const {
@@ -142,6 +156,16 @@ export function EastNorthUpFrame( props ) {
 
 }
 
+/**
+ * Registers a plugin on the nearest parent TilesRenderer. Must be a child of TilesRenderer.
+ * All properties on the plugin instance can be set as props directly. Note that some plugin
+ * properties cannot be changed after construction.
+ * @component
+ * @param {Object} props
+ * @param {Function} props.plugin - The plugin class to instantiate.
+ * @param {Object|Array} [props.args] - Constructor arguments: an object (single arg) or array (spread as multiple args).
+ * @param {ReactNode} [props.children] - Children rendered once the plugin is registered.
+ */
 // component for registering a plugin
 export const TilesPlugin = forwardRef( function TilesPlugin( props, ref ) {
 
@@ -221,6 +245,17 @@ export const TilesPlugin = forwardRef( function TilesPlugin( props, ref ) {
 
 } );
 
+/**
+ * Wrapper for the three.js TilesRenderer class. All properties on the TilesRenderer instance can
+ * be set as props using dot-notation for nested properties (e.g. `lruCache-minSize`). Events are
+ * registered with a camel-cased `on` prefix (e.g. `onLoadModel`).
+ * @component
+ * @param {Object} props
+ * @param {string} [props.url] - URL of the tileset to load.
+ * @param {boolean} [props.enabled=true] - If false, `update` is not called on the renderer each frame.
+ * @param {Object} [props.group] - Props applied to the root Three.js group of the tileset.
+ * @param {ReactNode} [props.children] - Child components such as TilesPlugin, GlobeControls, etc.
+ */
 // component for adding a TilesRenderer to the scene
 export const TilesRenderer = forwardRef( function TilesRenderer( props, ref ) {
 

utils/docs/RenderDocsUtils.js

@@ -332,6 +332,71 @@ export function renderEvents( events, callbackMap = {} ) {
 
 }
 
+export function renderComponent( doc, callbackMap = {} ) {
+
+	const lines = [];
+
+	lines.push( `## ${ doc.name }` );
+	lines.push( '' );
+
+	if ( doc.description ) {
+
+		lines.push( doc.description );
+		lines.push( '' );
+
+	}
+
+	const props = ( doc.params || [] ).filter( p => p.name.includes( '.' ) );
+
+	if ( props.length > 0 ) {
+
+		lines.push( '### Props' );
+		lines.push( '' );
+		lines.push( '```jsx' );
+		lines.push( `<${ doc.name }` );
+
+		for ( const prop of props ) {
+
+			const name = prop.name.split( '.' ).pop();
+			const type = formatType( prop.type, callbackMap );
+			const optional = prop.optional ? '?' : '';
+			const defStr = prop.defaultvalue !== undefined ? ` = ${ prop.defaultvalue }` : '';
+			lines.push( `\t${ name }${ optional }: ${ type }${ defStr }` );
+
+		}
+
+		lines.push( '/>' );
+		lines.push( '```' );
+		lines.push( '' );
+
+		for ( const prop of props ) {
+
+			const name = prop.name.split( '.' ).pop();
+			const type = formatType( prop.type, callbackMap );
+			const optional = prop.optional ? '?' : '';
+			const defStr = prop.defaultvalue !== undefined ? ` = ${ prop.defaultvalue }` : '';
+			lines.push( `### .${ name }` );
+			lines.push( '' );
+			lines.push( '```jsx' );
+			lines.push( `${ name }${ optional }: ${ type }${ defStr }` );
+			lines.push( '```' );
+			lines.push( '' );
+
+			if ( prop.description ) {
+
+				lines.push( prop.description );
+				lines.push( '' );
+
+			}
+
+		}
+
+	}
+
+	return lines.join( '\n' );
+
+}
+
 export function renderClass( classDoc, members, callbackMap = {}, resolveLink = null ) {
 
 	const lines = [];

utils/docs/build.js

@@ -1,7 +1,7 @@
 import { execSync } from 'child_process';
 import fs from 'fs';
 import path from 'path';
-import { renderClass, renderTypedef, renderConstants, toAnchor } from './RenderDocsUtils.js';
+import { renderClass, renderComponent, renderTypedef, renderConstants, toAnchor } from './RenderDocsUtils.js';
 import { findRootDir } from '../CommandUtils.js';
 
 const ROOT_DIR = findRootDir();
@@ -32,11 +32,11 @@ const ENTRY_POINTS = [
 		title: '3d-tiles-renderer/core/plugins',
 		source: 'src/core/plugins',
 	},
-	// {
-	// 	output: 'src/r3f/API.md',
-	// 	title: '3d-tiles-renderer/r3f',
-	// 	source: null,
-	// },
+	{
+		output: 'src/r3f/API.md',
+		title: '3d-tiles-renderer/r3f',
+		source: 'src/r3f/components',
+	},
 ];
 
 // Run JSDoc for all entry points and build a global type registry for cross-file links
@@ -45,15 +45,20 @@ const results = ENTRY_POINTS.map( entry => ( {
 	jsdoc: filterDocumented( runJsDoc( path.resolve( ROOT_DIR, entry.source ) ) )
 } ) );
 
-// Only classes and non-callback typedefs get sections (and therefore anchors) in the output.
+// Doclet type predicates
+const isClass = d => d.kind === 'class';
+const isObjectTypedef = d => d.kind === 'typedef' && d.type.names[ 0 ] !== 'function';
+const isCallbackTypedef = d => d.kind === 'typedef' && d.type.names[ 0 ] === 'function';
+const isReactComponent = d => ( d.kind === 'function' || d.kind === 'constant' ) && d.tags && d.tags.some( t => t.title === 'component' );
+const isConstant = d => d.kind === 'constant' && ! d.memberof && ! isReactComponent( d );
+
+// Only classes, non-callback typedefs, and React components get sections (and therefore anchors) in the output.
 const typeRegistry = {}; // name -> output path
 for ( const { entry, jsdoc } of results ) {
 
 	for ( const d of jsdoc ) {
 
-		const isClass = d.kind === 'class';
-		const isObjectTypedef = ( d.kind === 'typedef' && d.type.names[ 0 ] !== 'function' );
-		if ( isClass || isObjectTypedef ) {
+		if ( isClass( d ) || isObjectTypedef( d ) || isReactComponent( d ) ) {
 
 			typeRegistry[ d.name ] = entry.output;
 
@@ -94,7 +99,7 @@ for ( const { entry, jsdoc } of results ) {
 
 	// Sort classes so base classes appear before subclasses
 	const classes = jsdoc
-		.filter( d => d.kind === 'class' )
+		.filter( d => isClass( d ) )
 		.sort( ( a, b ) => {
 
 			const aIsBase = ! a.augments || a.augments.length === 0;
@@ -109,7 +114,7 @@ for ( const { entry, jsdoc } of results ) {
 	const callbackMap = {};
 	for ( const d of jsdoc ) {
 
-		if ( d.kind === 'typedef' && d.type.names[ 0 ] === 'function' ) {
+		if ( isCallbackTypedef( d ) ) {
 
 			callbackMap[ d.name ] = d;
 
@@ -119,7 +124,7 @@ for ( const { entry, jsdoc } of results ) {
 
 	// Sort typedefs so plain-object bases appear before derived types; exclude @callback entries
 	const typedefs = jsdoc
-		.filter( d => d.kind === 'typedef' && d.type.names[ 0 ] !== 'function' )
+		.filter( d => isObjectTypedef( d ) )
 		.sort( ( a, b ) => {
 
 			const aIsBase = a.type.names[ 0 ] === 'Object';
@@ -130,9 +135,14 @@ for ( const { entry, jsdoc } of results ) {
 
 		} );
 
+	// sort components by source line order
+	const components = jsdoc
+		.filter( d => isReactComponent( d ) )
+		.sort( ( a, b ) => a.meta.lineno - b.meta.lineno );
+
 	// sort constants by source line order
 	const constants = jsdoc
-		.filter( d => d.kind === 'constant' && ! d.memberof )
+		.filter( d => isConstant( d ) )
 		.sort( ( a, b ) => a.meta.lineno - b.meta.lineno );
 
 	// cache all fields by associated class name
@@ -158,6 +168,12 @@ for ( const { entry, jsdoc } of results ) {
 
 	sections.push( renderConstants( constants, callbackMap ) );
 
+	for ( const component of components ) {
+
+		sections.push( renderComponent( component, callbackMap ) );
+
+	}
+
 	for ( const cls of classes ) {
 
 		sections.push( renderClass( cls, classMembers[ cls.name ] || [], callbackMap, resolveLink ) );