v9 type export coverage

[krispya]

I started a branch to update Drei to use R3F v9. Attached is a log of all the type errors I got, which are mostly along the lines of prop types. I'd like to talk about the best way to handle this in v9, if there is already a strategy I am unaware of or if we should create one.

drei-type-errors.txt

[CodyJasonBennett]

children looks like a straight type regression, will have to look into that specifically. The ReactThreeFiber namespace and individual ClassProps were depreciated since mapped types in #2465, and narrowed extend to a single interface.

import { type ThreeElement, extend } from '@react-three/fiber'

declare module '@react-three/fiber' {
  interface ThreeElements {
    customElement: ThreeElement<typeof CustomElement>
  }
}

extend({ CustomElement })

As you pointed out earlier, specific math helpers are missing which don't have an upgrade path. I think we can break up what is now MathProps into a generic math helper or alias previous common ones like Vector3.

[krispya]

Working through this one issue at a time, ClassProps can now be done with ThreeElements['class'] or JSX.IntrinsicElements['class']. So GroupProps becomes ThreeElements['groups'].

Next is Color and Vector3 (along with other MathProps), which includes the Three definition and then the other valid data types like arrays and scalars. Maybe a good interface would be Prop.Color, Prop.Vector3, etc.?

And then I'm not sure what this was supposed to be doing.

ReactThreeFiber.Overwrite<
    ReactThreeFiber.Object3DNode<ArcballControlsImpl, typeof ArcballControlsImpl>,
    {
      target?: ReactThreeFiber.Vector3
      camera?: OrthographicCamera | PerspectiveCamera
      domElement?: HTMLElement
      regress?: boolean
      makeDefault?: boolean
      onChange?: (e?: Event) => void
      onStart?: (e?: Event) => void
      onEnd?: (e?: Event) => void
    }
  >

Maybe it is the same as:

ThreeElements['object3D'] & { /*props*/ }

[krispya]

So, digging a little deeper it looks like ReactThreeFiber.Object3DNode and ThreeElement are the same since they both add all the React and Event props. But what about ReactThreeFiber.Node? A use case I found was ReactThreeFiber.Node<EffectComposer, typeof EffectComposer> where this element doesn't use the Event props but still has the React props. Specifically, these were the props added to ReactThreeFiber.Node:

interface NodeProps<T, P> {
    attach?: AttachType;
    args?: Args<P>;
    children?: React.ReactNode;
    ref?: React.RefCallback<T> | React.RefObject<React.ReactNode> | null;
    key?: React.Key;
    onUpdate?: (self: T) => void;
}

[krispya]

Okay so my previous assumption about ThreeElement was wrong.

v8 type:

export type FlyControlsProps = ReactThreeFiber.Object3DNode<FlyControlsImpl, typeof FlyControlsImpl> & {
  onChange?: (e?: THREE.Event) => void
  domElement?: HTMLElement
  makeDefault?: boolean
}

And the computed type (sorry it is a screenshot):

And then here is the v9 type I attempted:

export type FirstPersonControlsProps = ThreeElement<typeof FirstPersonControlImpl> & {
  domElement?: HTMLElement
  makeDefault?: boolean
}

And the computed type for it:

There is a big difference, but I'm not familiar enough with the typing in total to know how much of a problem it is. I do notice though that the events actually don't get included like I expected.

[krispya]

Finally, I have found that using the declare snippet you provided completely replaces ThreeElements. For example, when I do:

declare module '@react-three/fiber' {
  interface ThreeElements {
    effectComposer: ThreeElement<typeof EffectComposer>
    renderPass: ThreeElement<typeof RenderPass>
    shaderPass: ThreeElement<typeof ShaderPass>
  }
}

ThreeElements then computes as just those elements:

Declaring directly to JSX.InstrinsicElements works though:

declare global {
  namespace JSX {
    interface IntrinsicElements {
      effectComposer: ThreeElement<typeof EffectComposer>
      renderPass: ThreeElement<typeof RenderPass>
      shaderPass: ThreeElement<typeof ShaderPass>
    }
  }
}

[krispya]

I'm sorry to keep pilling these up. I believe this is related to the children props being replaced with {}. I noticed it was happening to all the instance props, for example here is ThreeElements['spotLight'].

I tried looking through the type code for an answer but I haven't yet mastered TS wizardry to properly read it. It appears to have something to do with Mutable and line 41 of three-types.

export type ThreeElement<T extends ConstructorRepresentation> = Mutable<
  Overwrite<ElementProps<T>, Omit<InstanceProps<InstanceType<T>>, 'object'>>
>

[CodyJasonBennett]

Thanks for the deep analysis. Mutable is supposed to address #2374 for math classes but I kept it for general props. Can try stripping it back on a branch and see what's causing this behavior.

[krispya]

I narrowed it down to the MathProps type. I believe it has to do with P[K] extends infer M and when the infer fails, it falls back to {}. Removing MathProps from line 38 resolves the issue.

[krispya]

The remaining type issues for Drei can be generalized to:

MathProp types
I think we just need to decide on an API and go with it. For example MathProps['vector3'] would keep it consistent with ThreeElements.

Uses of Node and Object3DNode
Node is the base type that adds the ReactProps. Object3DNode extends Node to add EventHandlers. I think ThreeElement is supposed to handle this but it currently gives me curious results.
type ArcballControlsProps = ThreeElement<typeof ArcballControls> gives me a computed type with generic args and no properties:

And then how should we know if the type should have events attached? Is that inferred?

Declaring new intrinsic types
This currently works if you declare on JSX.IntrinsicElements, but using the ThreeElements example provided overwrites it each declare instead of merging. I'm not sure why.

There are various minor type issues but these are the big ones.

[CodyJasonBennett]

Events are inferred from a compatible raycast signature, but elements may have overloads. I'm not familiar with them, but I'd like to make optional args compatible if present.

react-three-fiber/packages/fiber/src/three-types.ts

Lines 30 to 33 in 0df10bb

	interface RaycastableRepresentation {
	raycast(raycaster: THREE.Raycaster, intersects: THREE.Intersection[]): void
	}
	type EventProps<P> = P extends RaycastableRepresentation ? Partial<EventHandlers> : {}

[krispya]

I am now getting this error all over Drei with the latest type merges:

error TS4023: Exported variable {ComponentName} has or is using name 'ReactProps' from external module "C:/dev/nt--drei/node_modules/@react-three/fiber/dist/declarations/src/three-types" but cannot be named.

microsoft/TypeScript#40718
microsoft/TypeScript#9944

I tried upgrading to the latest TypeScript but it didn't help me.

Also, I'm not sure this is an actual problem, but the tuple definitions aren't being recognized as valid for rotation:
Type '[number, number, number]' is not assignable to type 'Euler | Readonly<Euler | undefined>'.ts(2322)

Edit: Turns out any number[] fails, so this is indeed a problem.

The full error::

Type 'number[]' is not assignable to type 'Euler | Readonly<Euler | undefined>'.ts(2322)
Object3D.d.ts(69, 14): The expected type comes from property 'rotation' which is declared here on type 'Mutable<Overwrite<Partial<Overwrite<WithMathProps<Mesh<BufferGeometry, Material | Material[]>>, ReactProps<Mesh<BufferGeometry, Material | Material[]>> & Partial<...>>>, Omit<...>>>'