feat(docs): add some proper generated docs with Typedoc (pmndrs#248)

* feat(docs): add some proper generated docs with Typedoc

- Clean up a lot of types
  - Rename a heck ton of types in the back
  - Export a lot of missing types that could be  useful

.changeset/sour-roses-live.md

@@ -0,0 +1,5 @@
+---
+"@react-three/rapier": minor
+---
+
+Clean up exported types, add typedoc for generating html docs

.github/workflows/r3-rapier-docs.yml

@@ -1,5 +1,5 @@
 # Simple workflow for deploying static content to GitHub Pages
-name: Deploy static content to Pages
+name: Deploy @react-three/rapier docs
 
 on:
   # Runs on pushes targeting the default branch
@@ -27,29 +27,29 @@ jobs:
       name: github-pages
       url: ${{ steps.deployment.outputs.page_url }}
     runs-on: ubuntu-latest
-    steps:        
+    steps:
       - name: Checkout
         uses: actions/checkout@v3
-        
+
       - name: Setup Node.js environment
         uses: actions/[email protected]
         with:
           node-version: 16.x
 
       - name: Install Node Dependencies
         run: yarn
-        
+
       - name: Run typedoc
         run: yarn r3r-docs
-        
+
       - name: Setup Pages
         uses: actions/configure-pages@v2
-        
+
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v1
         with:
           # Upload docs folder
-          path: './packages/react-three-rapier/docs'
+          path: "./packages/react-three-rapier/docs"
       - name: Deploy to GitHub Pages
         id: deployment
         uses: actions/deploy-pages@v1

.gitignore

@@ -107,4 +107,6 @@ dist
 .parcel-cache
 
 # OSX
-.DS_Store
+.DS_Store
+
+packages/react-three-rapier/docs

demo/src/examples/collision-events/CollisionEventsExample.tsx

@@ -5,7 +5,7 @@ import {
   HeightfieldCollider,
   interactionGroups,
   RigidBody,
-  UseRigidBodyOptions
+  RigidBodyOptions
 } from "@react-three/rapier";
 import {
   createContext,
@@ -67,7 +67,7 @@ const Explosion = ({ position }: { position: [number, number, number] }) => {
 };
 
 const Collisioner = (
-  props: Omit<UseRigidBodyOptions, "children"> & {
+  props: Omit<RigidBodyOptions, "children"> & {
     children(color: string): ReactNode;
   }
 ) => {

demo/src/examples/cradle/CradleExample.tsx

@@ -5,13 +5,13 @@ import {
   RapierRigidBody,
   RigidBody,
   RigidBodyApi,
-  UseRigidBodyOptions,
+  RigidBodyOptions,
   useSphericalJoint
 } from "@react-three/rapier";
 import { useRef } from "react";
 import { Demo } from "../../App";
 
-const Rod = (props: UseRigidBodyOptions) => {
+const Rod = (props: RigidBodyOptions) => {
   const anchor = useRef<RigidBodyApi>(null);
   const rod = useRef<RigidBodyApi>(null);
 

demo/src/examples/performance/PeformanceExample.tsx

@@ -1,7 +1,7 @@
 import { useGLTF } from "@react-three/drei";
 import { GroupProps, useFrame } from "@react-three/fiber";
 import { RigidBody, RigidBodyProps } from "@react-three/rapier";
-import { RigidBodyApi } from "@react-three/rapier/dist/declarations/src/types";
+import { RigidBodyApi } from "@react-three/rapier";
 import { ReactNode, useEffect, useRef, useState } from "react";
 import { Mesh } from "three";
 import { GLTF } from "three-stdlib";

package.json

@@ -32,6 +32,7 @@
     "np": "^7.6.1",
     "prettier": "2.7.1",
     "simple-git-hooks": "^2.8.0",
+    "typedoc": "0.23.24",
     "typescript": "^4.6.3"
   },
   "scripts": {
@@ -44,7 +45,8 @@
     "release": "yarn build && changeset publish",
     "test": "vitest run",
     "test:ui": "vitest --ui",
-    "ts": "cd packages/react-three-rapier && yarn ts"
+    "ts": "cd packages/react-three-rapier && yarn ts",
+    "r3r-docs": "typedoc --out ./packages/react-three-rapier/docs ./packages/react-three-rapier/src/index.ts --excludeInternal"
   },
   "simple-git-hooks": {
     "commit-msg": "npx --no -- commitlint --edit ${1}",

packages/react-three-rapier/readme.md

@@ -18,7 +18,6 @@ For contributions, please read the <a href="https://github.com/pmndrs/react-thre
 
 The goal of this library to is to provide a fast physics engine with minimal friction and small, straight forward API.
 
-
 ## Basic Usage
 
 ```tsx
@@ -53,10 +52,8 @@ const App = () => {
 - [Readme Topics](#readme-topics)
 - [The Physics Component](#the-physics-component)
 - [The RigidBody Component](#the-rigidbody-component)
-  - [RigidBody props](#rigidbody-props)
 - [Automatic Colliders](#automatic-colliders)
 - [Collider Components](#collider-components)
-  - [Collider props](#collider-props)
   - [🖼 Collider Examples](#-collider-examples)
 - [Instanced Meshes](#instanced-meshes)
 - [Debug](#debug)
@@ -114,58 +111,8 @@ const RigidBodyMesh = () => (
 );
 ```
 
-### RigidBody props
-- `type`?: `string`  
-Specify the type of this rigid body. Default: "dynamic".
-  - "dynamic": The rigid body is fully dynamic.
-  - "fixed": The rigid body is fully fixed.
-  - "kinematicPosition": The rigid body is kinematic, and its forces are computed by changing position.
-  - "kinematicVelocity": The rigid body is kinematic, and its forced are computed by changing velocit .
-- `canSleep`?: `boolean`  
-  Whether or not this body can sleep. Default: `true`.
-- `linearDamping`?: `number`  
-  The linear damping coefficient of this rigid body. Default: `0.0`.
-- `angularDamping`?: `number`  
-  The angular damping coefficient of this rigid body. Default: `0.0`.
-- `linearVelocity`?: `[number, number, number]`  
-  The initial linear velocity of this body. Default: `[0, 0, 0]`.
-- `angularVelocity`?: `[number, number, number]`  
-  The initial angular velocity of this body. Default: `[0, 0, 0]`.
-- `gravityScale`?: `number` The scaling factor applied to the gravity affecting the rigid body. Default: `1.0`.
-- `ccd`?: `boolean`  
-  Whether or not Continous Collision Detection is enabled for this rigid body. Default: `false`.
-- `position`?: `[number, number, number]` or `Vector3`  
-  Initial position of the RigidBody.
-- `rotation`?: `[number, number, number]` or `Euler`  
-  Initial rotation of the RigidBody.
-- `quaternion`?: `Quaternion`  
-  Initial rotation of the RigidBody. Can be used in place of `rotation`.
-- `colliders`?: `string` or `false`  
-  Automatically generate colliders based on meshes inside this rigid body. See [Automatic colliders](#automatic-colliders).
-- `friction`?: `number`  
-  Set the friction of auto-generated colliders.
-- `restitution`?: `number`  
-  Set the restitution (bounciness) of auto-generated colliders. Does not affect any non-automatic child collider components.
-- `collisionGroups`?: `InteractionGroups`   
-  See [Configuring collision and solver groups](#configuring-collision-and-solver-groups).
-- `solverGroups`?: `InteractionGroups`  
-  See [Configuring collision and solver groups](#configuring-collision-and-solver-groups).
-- `onSleep`?: `function`  
-  Callback function that is called when the rigid body sleeps.
-- `onWake`?: `function`  
-  Callback function that is called when the rigid body wakes up.
-- `enabledRotations`?: `[boolean, boolean, boolean]`  
-  Allow rotation of this rigid body only along specific axes.
-- `enabledTranslations`?: `[boolean, boolean, boolean]`  
-  Allow translation of this rigid body only along specific axes.
-- `userData`?: `any`  
-  Passed down to the object3d representing this collider.
-- `includeInvisible`?: `boolean`  
-  Include invisible objects on the collider creation estimation.
-- `onCollisionEnter`?: `function`  
-  See [Collision Events](#collision-events).
-- `onCollisionExit`?: `function`  
-  See [Collision Events](#collision-events).
+For available props: see [RigidBody docs](#rigidbody-props)
+
 
 ## Automatic Colliders
 
@@ -216,69 +163,6 @@ const Scene = () => (
 
 You can also create `Colliders` by hand and add them to a `RigidBody` to create compound colliders. This is useful for creating more complex shapes, for creating simplified shapes for performance reasons, or for detecting collisions on specific parts of a mesh.
 
-Available `Collider` components:
-- `<CuboidCollider args={[halfWidth, halfHeight, halfDepth]} />`  
-  A cuboid collider.
-- `<RoundCuboidCollider args={[halfWidth, halfHeight, halfDepth, borderRadius]} />`  
-  A cuboid collider with rounded corners.
-- `<BallCollider args={[radius]} />`  
-  A ball collider.
-- `<CapsuleCollider args={[halfHeight, radius]} />`  
-  A capsule collider. The capsule is centered on the local-space Y axis.
-- `<HeightfieldCollider args={[width, height, heights, scale]} />`  
-  A heightfield collider is a heightmap represented by a grid of heights. The heightmap is centered on the local-space Y axis.
-- `<TrimeshCollider args={[vertices, indices]} />`  
-  A trimesh collider is a concave shape that is automatically computed from a set of points. It is more precise than a convex hull collider, but it is also more expensive to compute and to simulate.
-- `<ConeCollider args={[halfHeight, radius]} />`  
-  A cone collider. The cone is centered on the local-space Y axis.
-- `<CylinderCollider args={[halfHeight, radius]} />`  
-  A cylinder collider. The cylinder is centered on the local-space Y axis.
-- `<ConvexHullCollider args={[vertices, indices]} />`  
-  A convex hull collider is a convex shape that is automatically computed from a set of points. It is a good approximation of a concave shape, but it is not as precise as a trimesh collider. It is also more efficient to compute and to simulate.
-- `<MeshCollider />`   
-  Wraps one or more `meshes` to generate automatic colliders. Useful for combining with other primitive colliders where you need both simple and complex shapes.
-
-### Collider props
-- `principalAngularInertia`?: `[number, number, number]`  
-  Principal angular inertia of this collider
-- `restitution`?: `number`  
-  Restitution (bounciness) of this collider
-- restitutionCombineRule?: `CoefficientCombineRule`  
-  What happens when two bodies meet. See https://rapier.rs/docs/user_guides/javascript/colliders#friction.
-- `friction`?: `number`  
-  Friction of this collider
-- frictionCombineRule?: `CoefficientCombineRule`  
-  What happens when two bodies meet. See https://rapier.rs/docs/user_guides/javascript/colliders#friction.
-- `position`?: `[number, number, number]`  or `Vector3`  
-  Position of the collider relative to the rigid body.
-- `rotation`?: `[number, number, number]` or `Euler`  
-  Rotation of the collider relative to the rigid body.
-- `quaternion`?: `[number, number, number, number]` or `Quaternion`  
-  Rotation of the collider relative to the rigid body.
-- `scale`?: `[number, number, number]` or `Vector3`  
-  Scale of the collider relative to the rigid body.
-- onCollisionEnter?: `CollisionEnterHandler`  
-  See [Collision Events](#collision-events).
-- onCollisionExit?: `CollisionExitHandler`  
-  See [Collision Events](#collision-events).
-- `sensor`?: `boolean`  
-  See [Sensors](#sensors).  
-- onIntersectionEnter?: `IntersectionEnterHandler`  
-  See [Sensors](#sensors).  
-- onIntersectionExit?: `IntersectionExitHandler`  
-  See [Sensors](#sensors).  
-- solverGroups?: `InteractionGroups`  
-  See [Solver Groups](#solver-groups).
-- `collisionGroups`?: `InteractionGroups`  
-  See [Collision Groups](#collision-groups).
-- `density`?: `number`  
-  Sets the uniform density of this collider. If this is set, other mass-properties like the angular inertia tensor are computed automatically from the collider's shape. More info https://rapier.rs/docs/user_guides/javascript/colliders#mass-properties
-- `mass`?: `number`  
-  Generally, it's not recommended to adjust the mass properties as it could lead to unexpected behaviors. Cannot be used at the same time as the density or massProperties values. More info https://rapier.rs/docs/user_guides/javascript/colliders#mass-properties
-- `massProperties`?: `{ mass: number; centerOfMass: Vector; principalAngularInertia: Vector angularInertiaLocalFrame: Rotation; }`  
-  The mass properties of this rigid body. Cannot be used at the same time as the density or mass values. More info https://rapier.rs/docs/user_guides/javascript/colliders#mass-properties
-
-
 ```tsx
 const Scene = () => (<>
   {/* Make a compound shape with two custom BallColliders */}

packages/react-three-rapier/src/AnyCollider.tsx

@@ -9,11 +9,12 @@ import React, {
   MutableRefObject
 } from "react";
 import { Object3D, Vector3, InstancedMesh } from "three";
+import { RigidBodyApi } from "./api";
 import { useRapier } from "./hooks";
 import { useRigidBodyContext, RigidBodyProps } from "./RigidBody";
 import { _euler, _position, _rotation, _scale } from "./shared-objects";
 import {
-  UseColliderOptions,
+  ColliderOptions,
   CuboidArgs,
   RoundCuboidArgs,
   BallArgs,
@@ -22,8 +23,7 @@ import {
   TrimeshArgs,
   ConeArgs,
   CylinderArgs,
-  ConvexHullArgs,
-  RigidBodyApi
+  ConvexHullArgs
 } from "./types";
 import { vectorArrayToVector3 } from "./utils";
 import {
@@ -33,7 +33,7 @@ import {
   useUpdateColliderOptions
 } from "./utils-collider";
 
-export interface ColliderProps extends UseColliderOptions<any> {
+export interface ColliderProps extends ColliderOptions<any> {
   children?: ReactNode;
 }
 
@@ -140,27 +140,26 @@ export const AnyCollider = memo(
   )
 );
 
-type UseColliderOptionsRequiredArgs<T extends unknown[]> = Omit<
-  UseColliderOptions<T>,
+export type ColliderOptionsRequiredArgs<T extends unknown[]> = Omit<
+  ColliderOptions<T>,
   "args"
 > & {
   args: T;
   children?: ReactNode;
 };
 
-export type CuboidColliderProps = UseColliderOptionsRequiredArgs<CuboidArgs>;
+export type CuboidColliderProps = ColliderOptionsRequiredArgs<CuboidArgs>;
 export type RoundCuboidColliderProps =
-  UseColliderOptionsRequiredArgs<RoundCuboidArgs>;
-export type BallColliderProps = UseColliderOptionsRequiredArgs<BallArgs>;
-export type CapsuleColliderProps = UseColliderOptionsRequiredArgs<CapsuleArgs>;
+  ColliderOptionsRequiredArgs<RoundCuboidArgs>;
+export type BallColliderProps = ColliderOptionsRequiredArgs<BallArgs>;
+export type CapsuleColliderProps = ColliderOptionsRequiredArgs<CapsuleArgs>;
 export type HeightfieldColliderProps =
-  UseColliderOptionsRequiredArgs<HeightfieldArgs>;
-export type TrimeshColliderProps = UseColliderOptionsRequiredArgs<TrimeshArgs>;
-export type ConeColliderProps = UseColliderOptionsRequiredArgs<ConeArgs>;
-export type CylinderColliderProps =
-  UseColliderOptionsRequiredArgs<CylinderArgs>;
+  ColliderOptionsRequiredArgs<HeightfieldArgs>;
+export type TrimeshColliderProps = ColliderOptionsRequiredArgs<TrimeshArgs>;
+export type ConeColliderProps = ColliderOptionsRequiredArgs<ConeArgs>;
+export type CylinderColliderProps = ColliderOptionsRequiredArgs<CylinderArgs>;
 export type ConvexHullColliderProps =
-  UseColliderOptionsRequiredArgs<ConvexHullArgs>;
+  ColliderOptionsRequiredArgs<ConvexHullArgs>;
 
 export const CuboidCollider = React.forwardRef(
   (props: CuboidColliderProps, ref: ForwardedRef<Collider[]>) => {

packages/react-three-rapier/src/Attractor.tsx

@@ -5,18 +5,10 @@ import { FC, memo, useEffect, useRef } from "react";
 import { Object3D, Vector3 } from "three";
 import { _position, _vector3 } from "./shared-objects";
 import { Object3DProps } from "@react-three/fiber";
-import {
-  BallArgs,
-  BallCollider,
-  interactionGroups,
-  IntersectionEnterHandler,
-  IntersectionExitHandler,
-  UseColliderOptions
-} from ".";
-
-type GravityType = "static" | "linear" | "newtonian";
-
-interface AttractorProps {
+
+export type AttractorGravityType = "static" | "linear" | "newtonian";
+
+export interface AttractorProps {
   /**
    * The relative position of this attractor
    */
@@ -45,7 +37,7 @@ interface AttractorProps {
    * - newtonian: The gravity is calculated using the newtonian gravity formula.
    * @default "static"
    */
-  type?: GravityType;
+  type?: AttractorGravityType;
 
   /**
    * The mass of the attractor. Used when type is `newtonian`.