feat: configure behavior on text instance

Author: Amatewasu

packages/fiber/src/core/index.tsx

@@ -104,6 +104,14 @@ export type RenderProps<TCanvas extends Canvas> = {
   onCreated?: (state: RootState) => void
   /** Response for pointer clicks that have missed any target */
   onPointerMissed?: (event: MouseEvent) => void
+
+  /**
+   * Controls how React Three Fiber handles text instances.
+   * - 'noop': No action is taken.
+   * - 'warn': Logs a warning when a text instance is detected. (default)
+   * - 'throw': Throws an error when a text instance is detected.
+   */
+  onTextInstance?: 'noop' | 'warn' | 'throw'
 }
 
 const createRendererInstance = <TCanvas extends Canvas>(gl: GLProps, canvas: TCanvas): THREE.WebGLRenderer => {
@@ -197,6 +205,7 @@ function createRoot<TCanvas extends Canvas>(canvas: TCanvas): ReconcilerRoot<TCa
         raycaster: raycastOptions,
         camera: cameraOptions,
         onPointerMissed,
+        onTextInstance = 'warn',
       } = props
 
       let state = store.getState()
@@ -370,6 +379,8 @@ function createRoot<TCanvas extends Canvas>(canvas: TCanvas): ReconcilerRoot<TCa
       // Check performance
       if (performance && !is.equ(performance, state.performance, shallowLoose))
         state.set((state) => ({ performance: { ...state.performance, ...performance } }))
+      // Check onTextInstance
+      if (state.onTextInstance !== onTextInstance) state.set({ onTextInstance })
 
       // Set locals
       onCreated = onCreatedCallback

packages/fiber/src/core/renderer.ts

@@ -1,22 +1,22 @@
-import * as THREE from 'three'
-import { UseBoundStore } from 'zustand'
 import Reconciler from 'react-reconciler'
-import { unstable_IdlePriority as idlePriority, unstable_scheduleCallback as scheduleCallback } from 'scheduler'
 import { DefaultEventPriority } from 'react-reconciler/constants'
+import { unstable_IdlePriority as idlePriority, unstable_scheduleCallback as scheduleCallback } from 'scheduler'
+import * as THREE from 'three'
+import { UseBoundStore } from 'zustand'
+import { EventHandlers, removeInteractivity } from './events'
+import { RootState } from './store'
 import {
-  is,
-  prepare,
-  findInitialRoot,
-  diffProps,
   DiffSet,
   applyProps,
-  updateInstance,
-  invalidateInstance,
   attach,
   detach,
+  diffProps,
+  findInitialRoot,
+  invalidateInstance,
+  is,
+  prepare,
+  updateInstance,
 } from './utils'
-import { RootState } from './store'
-import { EventHandlers, removeInteractivity } from './events'
 
 export type Root = { fiber: Reconciler.FiberRoot; store: UseBoundStore<RootState> }
 
@@ -85,7 +85,19 @@ interface Catalogue {
 export const catalogue: Catalogue = {}
 const extend = (objects: object): void => void Object.assign(catalogue, objects)
 
-function createRenderer<TCanvas>(_roots: Map<TCanvas, Root>, _getEventPriority?: () => any) {
+type OnTextInstanceOption = 'noop' | 'warn' | 'throw'
+
+interface RendererOptions {
+  onTextInstance?: OnTextInstanceOption
+}
+
+function createRenderer<TCanvas>(
+  _roots: Map<TCanvas, Root>,
+  _getEventPriority?: () => any,
+  options: RendererOptions = {},
+) {
+  const { onTextInstance = 'warn' } = options
+
   function createInstance(
     type: string,
     { args = [], attach, ...props }: InstanceProps,
@@ -301,9 +313,20 @@ function createRenderer<TCanvas>(_roots: Map<TCanvas, Root>, _getEventPriority?:
     })
   }
 
-  // Don't handle text instances, warn on undefined behavior
-  const handleTextInstance = () =>
-    console.warn('Text is not allowed in the R3F tree! This could be stray whitespace or characters.')
+  const handleTextInstance = (text: string) => {
+    switch (onTextInstance) {
+      case 'noop': {
+        break
+      }
+      case 'throw': {
+        throw new Error(`Text is not allowed in the R3F tree! This could be stray whitespace or characters: "${text}"`)
+      }
+      case 'warn':
+      default: {
+        console.warn(`Text is not allowed in the R3F tree! This could be stray whitespace or characters: "${text}"`)
+      }
+    }
+  }
 
   const reconciler = Reconciler<
     HostConfig['type'],
@@ -445,4 +468,4 @@ function createRenderer<TCanvas>(_roots: Map<TCanvas, Root>, _getEventPriority?:
   return { reconciler, applyProps }
 }
 
-export { prepare, createRenderer, extend }
+export { createRenderer, extend, prepare }

packages/fiber/src/core/store.ts

@@ -161,6 +161,8 @@ export type RootState = {
   previousRoot?: UseBoundStore<RootState, StoreApi<RootState>>
   /** Internals */
   internal: InternalState
+  /** Controls how React Three Fiber handles text instances. */
+  onTextInstance: 'noop' | 'warn' | 'throw'
 }
 
 const context = React.createContext<UseBoundStore<RootState>>(null!)
@@ -221,6 +223,7 @@ const createStore = (invalidate: Invalidate, advance: Advance): UseBoundStore<Ro
       mouse: pointer,
 
       frameloop: 'always',
+      onTextInstance: 'warn',
       onPointerMissed: undefined,
 
       performance: {