feat: replace global T for createT factory-function, rename Primitive to Entity and export useProps

Author: bigmistqke

README.md

@@ -6,55 +6,40 @@
 
 `solid-three` is a port of [react-three-fiber](https://github.com/pmndrs/react-three-fiber) to [solid-js](https://www.solidjs.com/). It allows you to declaratively construct a [Three.js](https://threejs.org/) scene, with reactive primitives, just as you would construct a DOM tree in `solid-js`.
 
+- **Declarative `three.js` Components**: Utilize `three.js` objects as JSX components.
+- **Reactive Prop Updates**: Properties of 3D objects update reactively, promoting efficient re-renders.
+- **Integrated Animation Loop**: `useFrame` hook allows for easy animations.
+- **Comprehensive Event System**: Enhanced event handling with support for `three.js` pointer and mouse events.
+- **Extensible and Customizable**: Easily extendable with additional `three.js` entities or custom behaviors.
+- **Optimized for `solid-js`**: Leverages `solid-js`' fine-grained reactivity for optimal performance.
+
 ## Table of Contents
 
-1. [Features](#features)
-2. [Differences from React-Three-Fiber](#differences-from-react-three-fiber)
-3. [Installation](#installation)
-4. [Setup with extend()](#setup-with-extend)
-5. [Basic Usage](#basic-usage)
-6. [Components](#components)
+1. [Installation](#installation)
+2. [Basic Usage](#basic-usage)
+3. [Components](#components)
    - [Canvas](#canvas)
-   - [Primitive Components (`<T/>`)](#primitive-components-t)
+   - [T Namespace (`<T/>`)](#t-namespace-t)
    - [Portal](#portal)
    - [Primitive](#primitive)
-7. [Hooks](#hooks)
+4. [Hooks](#hooks)
    - [useThree](#usethree)
    - [useFrame](#useframe)
    - [useLoader](#useloader)
-8. [Event Handling](#event-handling)
+5. [Event Handling](#event-handling)
    - [Controlling Raycasting with pointerEvents](#controlling-raycasting-with-pointerevents)
    - [Supported Events](#supported-events)
    - [Event Object](#event-object)
    - [Event Propagation](#event-propagation)
    - [Missed Events](#missed-events)
    - [Hover Events](#hover-events)
-9. [TypeScript Support](#typescript-support)
-10. [Performance Optimization](#performance-optimization)
-11. [Testing](#testing)
-12. [API Reference](#api-reference)
-13. [Contributing](#contributing)
-14. [License](#license)
-
-## Features
-
-- **Declarative `three.js` Components**: Utilize `three.js` objects as JSX components.
-- **Reactive Prop Updates**: Properties of 3D objects update reactively, promoting efficient re-renders.
-- **Integrated Animation Loop**: `useFrame` hook allows for easy animations.
-- **Comprehensive Event System**: Enhanced event handling with support for `three.js` pointer and mouse events.
-- **Extensible and Customizable**: Easily extendable with additional `three.js` entities or custom behaviors.
-- **Optimized for `solid-js`**: Leverages `solid-js`' fine-grained reactivity for optimal performance.
-
-## Differences from React-Three-Fiber
-
-While `solid-three` is heavily inspired by– and initially shared a lot of code with– react-three-fiber, there are currently several key differences:
-
-- **No `performance` Prop**: The `Canvas` component does not support a `performance` prop as optimization is handled differently in `solid-js`.
-- **Simplified Event Objects**: The event object provided to event handlers is more minimalistic.
-- **Minimal `useThree` Hook**: Returns a more concise context object, focusing on essential properties.
-- **Missed Events**: Implements `onClickMissed`, `onDoubleClickMissed`, and `onContextMenuMissed` for handling events on empty space or stopped propagation.
-- **TODO**:
-  - **No Pointer Capture**: Pointer events do not support pointer capture management.
+6. [TypeScript Support](#typescript-support)
+7. [Performance Optimization](#performance-optimization)
+8. [Testing](#testing)
+9. [API Reference](#api-reference)
+10. [Differences from React-Three-Fiber](#differences-from-react-three-fiber)
+11. [Contributing](#contributing)
+12. [License](#license)
 
 ## Installation
 
@@ -72,43 +57,20 @@ yarn add solid-three three
 
 Ensure that `solid-js` is installed in your environment, as it is a peer dependency of `solid-three`.
 
-## Setup with `extend()`
-
-Before using solid-three components, you must register THREE.js objects with the `extend()` function:
-
-```tsx
-import { extend } from "solid-three"
-import * as THREE from "three"
-
-// Register all THREE.js objects (required step)
-extend(THREE)
-```
-
-This registration step is required and must be done before rendering any `<T.*>` components. You can also register specific objects, allowing for treeshaking:
-
-```tsx
-import { extend } from "solid-three"
-import { Mesh, BoxGeometry, MeshBasicMaterial } from "three"
-
-// Register only specific objects
-extend({ Mesh, BoxGeometry, MeshBasicMaterial })
-```
-
 ## Basic Usage
 
 Here's a simple example to get you started:
 
 ```tsx
 import { Component, createSignal } from "solid-js"
-import { Canvas, T, extend, useFrame } from "solid-three"
-import { Mesh } from "three"
+import { Canvas, createT, useFrame } from "solid-three"
 import * as THREE from "three"
 
-// Required: Register THREE.js objects before using them
-extend(THREE)
+// Create the T namespace with THREE.js objects
+const T = createT(THREE)
 
 const Box = () => {
-  let mesh: Mesh | undefined
+  let mesh: THREE.Mesh | undefined
   const [hovered, setHovered] = createSignal(false)
 
   useFrame(() => (mesh!.rotation.y += 0.01))
@@ -183,19 +145,36 @@ Example with all props:
 </Canvas>
 ```
 
-### Primitive Components (`<T/>`)
+### T Namespace (`<T/>`)
 
-`<T/>` components are wrappers around `three.js` objects, allowing you to insert these objects into your scene declaratively. These components are created dynamically based on the `three.js` classes you've registered with `extend()`.
-
-Example:
+The `T` namespace contains components that wrap `three.js` objects, allowing you to insert them into your scene declaratively. Before using these components, you must create the namespace using the `createT()` function:
 
 ```tsx
+import { createT } from "solid-three"
+import * as THREE from "three"
+
+// Create T namespace with all THREE.js objects
+const T = createT(THREE)
+
+// Now you can use T components
 <T.Mesh>
   <T.BoxGeometry args={[1, 1, 1]} />
   <T.MeshBasicMaterial color="hotpink" />
 </T.Mesh>
 ```
 
+You can also create a namespace with specific objects for better tree-shaking:
+
+```tsx
+import { createT } from "solid-three"
+import { Mesh, BoxGeometry, MeshBasicMaterial } from "three"
+
+// Create T namespace with only specific objects
+const T = createT({ Mesh, BoxGeometry, MeshBasicMaterial })
+```
+
+The `T` namespace can be created once and imported throughout your application, or created locally in each file as needed. The components are typed based on the objects you pass to `createT()`, providing full TypeScript support and autocomplete.
+
 #### Advanced Prop Patterns
 
 `solid-three` supports advanced prop attachment patterns for precise control:
@@ -231,7 +210,6 @@ const AdvancedProps = () => {
 
 These patterns automatically trigger `needsUpdate` flags on materials and geometries when necessary.
 
-
 ### Portal
 
 The `Portal` component allows you to place children outside the regular scene graph while maintaining reactive updates. This is useful for rendering objects into different scenes or bypassing the normal parent-child relationships.
@@ -394,7 +372,7 @@ function useLoader<TLoader, TArgs>(
 
 ```tsx
 import { createSignal } from "solid-js"
-import { Canvas, T, useLoader } from "solid-three"
+import { Canvas, useLoader } from "solid-three"
 import { TextureLoader } from "three"
 
 const TexturedSphere = () => {
@@ -421,7 +399,7 @@ export const App = () => {
 ### Multiple textures
 
 ```tsx
-import { Canvas, T, useLoader } from "solid-three"
+import { Canvas, useLoader } from "solid-three"
 import { TextureLoader } from "three"
 
 const TexturedPlanes = () => {
@@ -716,13 +694,14 @@ solid-three's hover event handling differs from react-three-fiber in several key
 
 ```tsx
 import type { S3 } from "solid-three"
+import type * as THREE from "three"
 
 // Component types
-type MeshComponent = S3.Component<Mesh>
-type BoxProps = S3.ClassProps<BoxGeometry>
+type MeshComponent = S3.Component<THREE.Mesh>
+type BoxProps = S3.Props<THREE.BoxGeometry>
 
 // Instance types - `three.js` objects augmented with solid-three metadata
-type AugmentedMesh = S3.Instance<Mesh>
+type AugmentedMesh = S3.Instance<THREE.Mesh>
 
 // Generic Three instance
 type AnyInstance = S3.ThreeInstance
@@ -734,9 +713,11 @@ type Camera = S3.CameraType // PerspectiveCamera | OrthographicCamera
 ### Props Types
 
 ```tsx
+import type { S3 } from "solid-three"
+
 // Get props type for a specific `three.js` class
-type MeshProps = S3.Props<"Mesh">
-type MaterialProps = S3.Props<"MeshStandardMaterial">
+type MeshProps = S3.Props<THREE.Mesh>
+type MaterialProps = S3.Props<THREE.MeshStandardMaterial>
 
 // Using in components
 const MyMesh = (props: MeshProps) => {
@@ -1003,7 +984,6 @@ const SharedResource = () => {
 ```tsx
 import { test, TestCanvas } from "solid-three/testing"
 import { render } from "@solidjs/testing-library"
-import { T } from "solid-three"
 
 test("renders a mesh", () => {
   const { canvas, scene, unmount, waitTillNextFrame } = test(() => (
@@ -1050,6 +1030,7 @@ import { WebGL2RenderingContext } from "solid-three/testing"
 
 ```tsx
 import { fireEvent } from "@solidjs/testing-library"
+import { test } from "solid-three/testing"
 
 test("handles click events", () => {
   let clicked = false
@@ -1104,6 +1085,9 @@ test("useThree returns context", () => {
 ### Testing Animations
 
 ```tsx
+import { test } from "solid-three/testing"
+import { useFrame } from "solid-three"
+
 test("animates on frame", async () => {
   let rotation = 0
 
@@ -1124,6 +1108,17 @@ test("animates on frame", async () => {
 })
 ```
 
+## Differences from React-Three-Fiber
+
+While `solid-three` is heavily inspired by– and initially shared a lot of code with– react-three-fiber, there are currently several key differences:
+
+- **No `performance` Prop**: The `Canvas` component does not support a `performance` prop as optimization is handled differently in `solid-js`.
+- **Simplified Event Objects**: The event object provided to event handlers is more minimalistic.
+- **Minimal `useThree` Hook**: Returns a more concise context object, focusing on essential properties.
+- **Missed Events**: Implements `onClickMissed`, `onDoubleClickMissed`, and `onContextMenuMissed` for handling events on empty space or stopped propagation.
+- **TODO**:
+  - **No Pointer Capture**: Pointer events do not support pointer capture management.
+
 ## Contributing
 
 We welcome contributions! Please see our [Contributing Guide](CONTRIBUTION.md) for details on how to get started.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "solid-three",
-  "version": "0.3.0-next.4",
+  "version": "0.3.0-next.5",
   "description": "SolidJS bindings for ThreeJS",
   "repository": {
     "type": "git",

playground/App.tsx

@@ -1,11 +1,11 @@
 import { A, Route, Router } from "@solidjs/router"
 import type { ParentProps } from "solid-js"
 import * as THREE from "three"
-import { Canvas, extend, T } from "../src/index.ts"
+import { Canvas, createT } from "../src/index.ts"
 import { SimpleSolar } from "./examples/SimpleSolar.tsx"
 import "./index.css"
 
-extend(THREE)
+const T = createT(THREE)
 
 function Layout(props: ParentProps) {
   return (

playground/controls/OrbitControls.tsx

@@ -2,11 +2,11 @@ import { createEffect, createMemo, onCleanup, type Ref } from "solid-js"
 import type { Event } from "three"
 import { OrbitControls as ThreeOrbitControls } from "three-stdlib"
 import { useFrame, useThree, type S3 } from "../../src/index.ts"
-import { manageProps } from "../../src/props.ts"
+import { useProps } from "../../src/props.ts"
 import { whenEffect } from "../../src/utils/conditionals.ts"
 import { processProps } from "./process-props.ts"
 
-export type OrbitControlsProps = S3.ClassProps<typeof ThreeOrbitControls> & {
+export interface OrbitControlsProps extends S3.Props<typeof ThreeOrbitControls> {
   ref?: Ref<ThreeOrbitControls>
   camera?: S3.CameraType
   domElement?: HTMLElement
@@ -70,15 +70,7 @@ export function OrbitControls(props: OrbitControlsProps) {
     onCleanup(() => _controls.removeEventListener("end", callback))
   })
 
-  manageProps(controls, rest)
+  useProps(controls, rest)
 
   return null!
 }
-
-function createEventListener() {
-  const callback = config.onStart
-  if (!callback) return
-  const _controls = controls()
-  _controls.addEventListener("start", callback)
-  onCleanup(() => _controls.removeEventListener("start", callback))
-}

playground/controls/default-props.ts

@@ -1,6 +1,6 @@
 import type { MergeProps } from "solid-js"
 import { mergeProps } from "solid-js"
-import type { KeyOfOptionals } from "./type-utils.ts"
+import type { KeyOfOptionals } from "./type-utils"
 
 export function defaultProps<T, K extends KeyOfOptionals<T>>(
   props: T,

playground/examples/SimpleSolar.tsx

@@ -1,9 +1,11 @@
 import { createEffect, createMemo, createSignal, Show, type ParentProps, type Ref } from "solid-js"
 import type { Instance } from "src/types.ts"
 import * as THREE from "three"
-import { Canvas, T, useFrame } from "../../src/index.ts"
+import { Canvas, createT, Entity, useFrame } from "../../src/index.ts"
 import { OrbitControls } from "../controls/OrbitControls.tsx"
 
+const T = createT(THREE)
+
 function OrbitPath(
   props: ParentProps<{
     ref?: Ref<THREE.Line>
@@ -45,7 +47,7 @@ function OrbitPath(
       }}
     >
       <T.LineBasicMaterial color="#ffffff" />
-      <T.Primitive object={curve()} />
+      <Entity from={curve()} />
       {props.children}
     </T.Line>
   )

src/canvas.tsx

@@ -6,7 +6,14 @@ import {
   onCleanup,
   onMount,
 } from "solid-js"
-import { Camera, OrthographicCamera, Raycaster, Scene, WebGLRenderer } from "three"
+import {
+  Camera,
+  OrthographicCamera,
+  PerspectiveCamera,
+  Raycaster,
+  Scene,
+  WebGLRenderer,
+} from "three"
 import { createThree } from "./create-three.tsx"
 import type { EventHandlers, Props } from "./types.ts"
 
@@ -16,21 +23,21 @@ import type { EventHandlers, Props } from "./types.ts"
 export interface CanvasProps extends ParentProps<Partial<EventHandlers>> {
   class?: string
   /** Configuration for the camera used in the scene. */
-  camera?: Partial<Props<"PerspectiveCamera"> | Props<"OrthographicCamera">> | Camera
+  camera?: Partial<Props<PerspectiveCamera> | Props<OrthographicCamera>> | Camera
   /** Element to render while the main content is loading asynchronously.  */
   fallback?: JSX.Element
   /** Options for the WebGLRenderer or a function returning a customized renderer. */
   gl?:
-    | Partial<Props<"WebGLRenderer">>
+    | Partial<Props<WebGLRenderer>>
     | ((canvas: HTMLCanvasElement) => WebGLRenderer)
     | WebGLRenderer
   /** Toggles between Orthographic and Perspective camera. */
   orthographic?: boolean
   /** Configuration for the Raycaster used for mouse and pointer events. */
-  raycaster?: Partial<Props<"Raycaster">> | Raycaster
+  raycaster?: Partial<Props<Raycaster>> | Raycaster
   ref?: Ref<HTMLDivElement>
   /** Configuration for the Scene instance. */
-  scene?: Partial<Props<"Scene">> | Scene
+  scene?: Partial<Props<Scene>> | Scene
   /** Custom CSS styles for the canvas container. */
   style?: JSX.CSSProperties
   /** Enables and configures shadows in the scene. */