chore: docs folder (#2071)

* docs: docs folder

* introduction

* doc

* docs workflow

* fixing toc's hn

* redirects links

* archive links warning

* ai typos

* gh + dd

* doc

.github/workflows/docs.yml

@@ -0,0 +1,41 @@
+name: Build documentation and deploy to GitHub Pages
+on:
+  push:
+    branches: ['master']
+  workflow_dispatch:
+
+# Cancel previous run (see: https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#concurrency)
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    uses: pmndrs/docs/.github/workflows/build.yml@v2
+    with:
+      mdx: 'docs'
+      libname: 'Drei'
+      libname_short: 'drei'
+      home_redirect: '/getting-started/introduction'
+      icon: '🥉'
+      logo: '/logo.jpg'
+      github: 'https://github.com/pmndrs/drei'
+      discord: 'https://discord.com/channels/740090768164651008/741751532592038022'
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+
+    # Grant GITHUB_TOKEN the permissions required to make a Pages deployment
+    permissions:
+      pages: write # to deploy to Pages
+      id-token: write # to verify the deployment originates from an appropriate source
+
+    # Deploy to the github-pages environment
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

docs/abstractions/ascii-renderer.mdx

@@ -0,0 +1,35 @@
+---
+title: AsciiRenderer
+---
+
+<Grid cols={4}>
+  <li>
+    <Codesandbox id="vq9wsl" />
+  </li>
+</Grid>
+
+Abstraction of three's [AsciiEffect](https://threejs.org/examples/?q=as#webgl_effects_ascii). It creates a DOM layer on top of the canvas and renders the scene as ascii characters.
+
+```tsx
+type AsciiRendererProps = {
+  /** Render index, default: 1 */
+  renderIndex?: number
+  /** CSS background color (can be "transparent"), default: black */
+  bgColor?: string
+  /** CSS character color, default: white */
+  fgColor?: string
+  /** Characters, default: ' .:-+*=%@#' */
+  characters?: string
+  /** Invert character, default: true */
+  invert?: boolean
+  /** Colorize output (very expensive!), default: false */
+  color?: boolean
+  /** Level of detail, default: 0.15 */
+  resolution?: number
+}
+```
+
+```jsx
+<Canvas>
+  <AsciiRenderer />
+```

docs/abstractions/billboard.mdx

@@ -0,0 +1,18 @@
+---
+title: Billboard
+---
+
+[![](https://img.shields.io/badge/-storybook-%23ff69b4)](https://drei.pmnd.rs/?path=/story/abstractions-billboard--billboard-st)
+
+Adds a `<group />` that always faces the camera.
+
+```jsx
+<Billboard
+  follow={true}
+  lockX={false}
+  lockY={false}
+  lockZ={false} // Lock the rotation on the z axis (default=false)
+>
+  <Text fontSize={1}>I'm a billboard</Text>
+</Billboard>
+```

docs/abstractions/clone.mdx

@@ -0,0 +1,58 @@
+---
+title: Clone
+---
+
+<Grid cols={4}>
+  <li>
+    <Codesandbox id="42glz0" />
+  </li>
+</Grid>
+
+Declarative abstraction around THREE.Object3D.clone. This is useful when you want to create a shallow copy of an existing fragment (and Object3D, Groups, etc) into your scene, for instance a group from a loaded GLTF. This clone is now re-usable, but it will still refer to the original geometries and materials.
+
+```ts
+<Clone
+  /** Any pre-existing THREE.Object3D (groups, meshes, ...), or an array of objects */
+  object: THREE.Object3D | THREE.Object3D[]
+  /** Children will be placed within the object, or within the group that holds arrayed objects */
+  children?: React.ReactNode
+  /** Can clone materials and/or geometries deeply (default: false) */
+  deep?: boolean | 'materialsOnly' | 'geometriesOnly'
+  /** The property keys it will shallow-clone (material, geometry, visible, ...) */
+  keys?: string[]
+  /** Can either spread over props or fill in JSX children, applies to every mesh within */
+  inject?: MeshProps | React.ReactNode | ((object: THREE.Object3D) => React.ReactNode)
+  /** Short access castShadow, applied to every mesh within */
+  castShadow?: boolean
+  /** Short access receiveShadow, applied to every mesh within */
+  receiveShadow?: boolean
+/>
+```
+
+You create a shallow clone by passing a pre-existing object to the `object` prop.
+
+```jsx
+const { nodes } = useGLTF(url)
+return (
+  <Clone object={nodes.table} />
+```
+
+Or, multiple objects:
+
+```jsx
+<Clone object={[nodes.foo, nodes.bar]} />
+```
+
+You can dynamically insert objects, these will apply to anything that isn't a group or a plain object3d (meshes, lines, etc):
+
+```jsx
+<Clone object={nodes.table} inject={<meshStandardMaterial color="green" />} />
+```
+
+Or make inserts conditional:
+
+```jsx
+<Clone object={nodes.table} inject={
+  {(object) => (object.name === 'table' ? <meshStandardMaterial color="green" /> : null)}
+} />
+```

docs/abstractions/computed-attribute.mdx

@@ -0,0 +1,22 @@
+---
+title: ComputedAttribute
+---
+
+[![](https://img.shields.io/badge/-storybook-%23ff69b4)](https://drei.vercel.app/?path=/story/misc-sampler--sampler-weight-st)
+
+Create and attach an attribute declaratively.
+
+```tsx
+<sphereGeometry>
+  <ComputedAttribute
+    // attribute will be added to the geometry with this name
+    name="my-attribute-name"
+    compute={(geometry) => {
+      // ...someLogic;
+      return new THREE.BufferAttribute([1, 2, 3], 1)
+    }}
+    // you can pass any BufferAttribute prop to this component, eg.
+    usage={THREE.StaticReadUsage}
+  />
+</sphereGeometry>
+```

docs/abstractions/decal.mdx

@@ -0,0 +1,52 @@
+---
+title: Decal
+---
+
+[![](https://img.shields.io/badge/-storybook-%23ff69b4)](https://drei.pmnd.rs/?path=/story/misc-decal--decal-st)
+
+<Grid cols={4}>
+  <li>
+    <Codesandbox id="ymb5d9" />
+  </li>
+</Grid>
+
+Abstraction around Three's `DecalGeometry`. It will use the its parent `mesh` as the decal surface by default.
+
+The decal box has to intersect the surface, otherwise it will not be visible. if you do not specifiy a rotation it will look at the parents center point. You can also pass a single number as the rotation which allows you to spin it.
+
+```js
+<mesh>
+  <sphereGeometry />
+  <meshBasicMaterial />
+  <Decal
+    debug // Makes "bounding box" of the decal visible
+    position={[0, 0, 0]} // Position of the decal
+    rotation={[0, 0, 0]} // Rotation of the decal (can be a vector or a degree in radians)
+    scale={1} // Scale of the decal
+  >
+    <meshBasicMaterial
+      map={texture}
+      polygonOffset
+      polygonOffsetFactor={-1} // The material should take precedence over the original
+    />
+  </Decal>
+</mesh>
+```
+
+If you do not specify a material it will create a transparent meshBasicMaterial with a polygonOffsetFactor of -10.
+
+```jsx
+<mesh>
+  <sphereGeometry />
+  <meshBasicMaterial />
+  <Decal map={texture} />
+</mesh>
+```
+
+If declarative composition is not possible, use the `mesh` prop to define the surface the decal must attach to.
+
+```js
+<Decal mesh={ref}>
+  <meshBasicMaterial map={texture} polygonOffset polygonOffsetFactor={-1} />
+</Decal>
+```

docs/abstractions/edges.mdx

@@ -0,0 +1,24 @@
+---
+title: Edges
+---
+
+<Grid cols={4}>
+  <li>
+    <Codesandbox id="ny3p4" />
+  </li>
+</Grid>
+
+Abstracts [THREE.EdgesGeometry](https://threejs.org/docs/#api/en/geometries/EdgesGeometry). It pulls the geometry automatically from its parent, optionally you can ungroup it and give it a `geometry` prop. You can give it children, for instance a custom material. Edges is based on `<Line>` and supports all of its props.
+
+```jsx
+<mesh>
+  <boxGeometry />
+  <meshBasicMaterial />
+  <Edges
+    linewidth={4}
+    scale={1.1}
+    threshold={15} // Display edges only when the angle between two faces exceeds this value (default=15 degrees)
+    color="white"
+  />
+</mesh>
+```

docs/abstractions/effects.mdx

@@ -0,0 +1,17 @@
+---
+title: Effects
+---
+
+Abstraction around threes own [EffectComposer](https://threejs.org/docs/#examples/en/postprocessing/EffectComposer). By default it will prepend a render-pass and a gammacorrection-pass. Children are cloned, `attach` is given to them automatically. You can only use passes or effects in there.
+
+By default it creates a render target with HalfFloatType, RGBAFormat. You can change all of this to your liking, inspect the types.
+
+```jsx
+import { SSAOPass } from "three-stdlib"
+
+extend({ SSAOPass })
+
+<Effects multisamping={8} renderIndex={1} disableGamma={false} disableRenderPass={false} disableRender={false}>
+  <sSAOPass args={[scene, camera, 100, 100]} kernelRadius={1.2} kernelSize={0} />
+</Effects>
+```

docs/abstractions/gradient-texture.mdx

@@ -0,0 +1,44 @@
+---
+title: GradientTexture
+---
+
+<Grid cols={4}>
+  <li>
+    <Codesandbox id="l03yb" />
+  </li>
+</Grid>
+
+A declarative THREE.Texture which attaches to "map" by default. You can use this to create gradient backgrounds.
+
+```jsx
+<mesh>
+  <planeGeometry />
+  <meshBasicMaterial>
+    <GradientTexture
+      stops={[0, 1]} // As many stops as you want
+      colors={['aquamarine', 'hotpink']} // Colors need to match the number of stops
+      size={1024} // Size is optional, default = 1024
+    />
+  </meshBasicMaterial>
+</mesh>
+```
+
+Radial gradient.
+
+```jsx
+import { GradientTexture, GradientType } from './GradientTexture'
+;<mesh>
+  <planeGeometry />
+  <meshBasicMaterial>
+    <GradientTexture
+      stops={[0, 0.5, 1]} // As many stops as you want
+      colors={['aquamarine', 'hotpink', 'yellow']} // Colors need to match the number of stops
+      size={1024} // Size (height) is optional, default = 1024
+      width={1024} // Width of the canvas producing the texture, default = 16
+      type={GradientType.Radial} // The type of the gradient, default = GradientType.Linear
+      innerCircleRadius={0} // Optional, the radius of the inner circle of the gradient, default = 0
+      outerCircleRadius={'auto'} // Optional, the radius of the outer circle of the gradient, default = auto
+    />
+  </meshBasicMaterial>
+</mesh>
+```

docs/abstractions/image.mdx

@@ -0,0 +1,71 @@
+---
+title: Image
+---
+
+<Grid cols={4}>
+  <li>
+    <Codesandbox id="9s2wd9" />
+  </li>
+  <li>
+    <Codesandbox id="l4klb" />
+  </li>
+  <li>
+    <Codesandbox id="gsm1y" />
+  </li>
+  <li>
+    <Codesandbox id="x8gvs" />
+  </li>
+  <li>
+    <Codesandbox id="yjhzv" />
+  </li>
+</Grid>
+
+A shader-based image component with auto-cover (similar to css/background: cover).
+
+```tsx
+export type ImageProps = Omit<JSX.IntrinsicElements['mesh'], 'scale'> & {
+  segments?: number
+  scale?: number | [number, number]
+  color?: Color
+  zoom?: number
+  radius?: number
+  grayscale?: number
+  toneMapped?: boolean
+  transparent?: boolean
+  opacity?: number
+  side?: THREE.Side
+}
+```
+
+```jsx
+function Foo() {
+  const ref = useRef()
+  useFrame(() => {
+    ref.current.material.radius = ... // between 0 and 1
+    ref.current.material.zoom = ... // 1 and higher
+    ref.current.material.grayscale = ... // between 0 and 1
+    ref.current.material.color.set(...) // mix-in color
+  })
+  return <Image ref={ref} url="/file.jpg" />
+}
+```
+
+To make the material transparent:
+
+```jsx
+<Image url="/file.jpg" transparent opacity={0.5} />
+```
+
+You can have custom planes, for instance a rounded-corner plane.
+
+```jsx
+import { extend } from '@react-three/fiber'
+import { Image } from '@react-three/drei'
+import { easing, geometry } from 'maath'
+
+extend({ RoundedPlaneGeometry: geometry.RoundedPlaneGeometry })
+
+<Image url="/file.jpg">
+  <roundedPlaneGeometry args={[1, 2, 0.15]} />
+</Image>
+```