merge master

.codesandbox/ci.json

@@ -0,0 +1,5 @@
+{
+  "sandboxes": ["/demos/ssr"],
+  "packages": ["dist"],
+  "node": "14"
+}

.github/PULL_REQUEST_TEMPLATE.md

@@ -26,6 +26,7 @@ Remove items that are irrelevant to your changes.
 -->
 
 - [ ] Documentation updated
+- [ ] Storybook entry added
 - [ ] Ready to be merged
 
 <!-- if you untick ready to be merged & you haven't submitted as a draft, we will change it to draft. -->

.github/workflows/main.yml

@@ -24,7 +24,7 @@ jobs:
         # there's a build step for post installation so we don't run build when "testing"
         run: yarn install
       - name: Lint test 🧪
-        run: yarn eslint:ci
+        run: yarn lint:ci
       - name: Prettier test
         run: yarn prettier:check
       - name: Type check
@@ -55,7 +55,7 @@ jobs:
             @semantic-release/git
           branches: |
             [
-              'master',
+              'main',
               {name: 'beta', prerelease: true},
               {name: 'alpha', prerelease: true}
             ]

.gitignore

@@ -46,3 +46,7 @@ jspm_packages/
 pnpm-lock.yaml
 
 dist
+.next
+
+# storybook
+storybook-static

.prettierignore

@@ -1,2 +1,5 @@
 dist
-.github
+.github
+.next
+node_modules
+storybook-static

.storybook/index.css

@@ -0,0 +1,30 @@
+html,
+body,
+#root {
+  width: 100%;
+  height: 100%;
+  margin: 0;
+  padding: 0;
+  -webkit-touch-callout: none;
+  -webkit-user-select: none;
+  -khtml-user-select: none;
+  -moz-user-select: none;
+  -ms-user-select: none;
+  user-select: none;
+  overflow: hidden;
+  background-color: #121212;
+}
+
+#root {
+  overflow: auto;
+}
+
+main {
+  width: 100%;
+  height: 100%;
+}
+
+canvas {
+  width: 100%;
+  height: 100%;
+}

.storybook/main.ts

@@ -0,0 +1,4 @@
+module.exports = {
+  stories: ['./stories/*.stories.@(js|jsx|ts|tsx)'],
+  addons: ['@storybook/addon-essentials', '@storybook/addon-controls', '@storybook/addon-storysource'],
+}

.storybook/manager.ts

@@ -0,0 +1,6 @@
+import { addons } from '@storybook/addons'
+
+addons.setConfig({
+  panelPosition: 'right',
+  showPanel: true,
+})

.storybook/preview.ts

@@ -0,0 +1,7 @@
+import './index.css'
+
+export const parameters = {
+  layout: 'fullscreen',
+}
+
+export const decorators = [(story) => `<canvas id="canvas-root"></canvas>${story()}`]

.storybook/setup.ts

@@ -0,0 +1,80 @@
+import { Camera, Scene, PerspectiveCamera, WebGLRenderer, Clock } from 'three'
+//@ts-ignore
+import { OrbitControls } from '../src'
+
+interface useThreeReturn {
+  camera: Camera
+  scene: Scene
+  renderer: WebGLRenderer
+}
+
+interface useFrameProps {
+  clock: Clock
+}
+
+interface useThreeProps {
+  useFrame?: ({ clock }: useFrameProps, delta: number) => void
+}
+
+export const useThree = ({ useFrame }: useThreeProps = {}): useThreeReturn => {
+  const container = document.getElementById('canvas-root') as HTMLCanvasElement
+
+  const renderer = new WebGLRenderer({
+    antialias: true,
+    canvas: container,
+    alpha: true,
+    powerPreference: 'high-performance',
+  })
+  renderer.setClearAlpha(0)
+  renderer.setPixelRatio(window.devicePixelRatio)
+  renderer.setSize(window.innerWidth, window.innerHeight)
+
+  const camera = new PerspectiveCamera(75, window.innerWidth / window.innerHeight, 0.1, 1000)
+  camera.position.set(0, 0, -5)
+  camera.lookAt(0, 0, 0)
+
+  const scene = new Scene()
+
+  function onWindowResize() {
+    camera.aspect = window.innerWidth / window.innerHeight
+    camera.updateProjectionMatrix()
+
+    renderer.setSize(window.innerWidth, window.innerHeight)
+  }
+
+  const clock = new Clock()
+
+  const controls = new OrbitControls(camera, container)
+  controls.enableDamping = true
+
+  function animate() {
+    if (useFrame) {
+      useFrame(
+        {
+          clock,
+        },
+        clock.getDelta(),
+      )
+    }
+
+    controls.update()
+
+    render()
+
+    requestAnimationFrame(animate)
+  }
+
+  function render() {
+    renderer.render(scene, camera)
+  }
+
+  window.addEventListener('resize', onWindowResize)
+
+  animate()
+
+  return {
+    camera,
+    scene,
+    renderer,
+  }
+}

.storybook/stories/BasicScene.stories.ts

@@ -0,0 +1,50 @@
+import {
+  AmbientLight,
+  DirectionalLight,
+  PointLight,
+  SpotLight,
+  Mesh,
+  IcosahedronBufferGeometry,
+  MeshStandardMaterial,
+  Color,
+} from 'three'
+import { useEffect } from '@storybook/client-api'
+
+import { useThree } from '../setup'
+
+export default {
+  title: 'Basic/Scene',
+}
+
+export const Default = () => {
+  // must run in this so the canvas has mounted in the iframe & can be accessed by `three`
+  useEffect(() => {
+    const mesh = new Mesh(new IcosahedronBufferGeometry(1), new MeshStandardMaterial({ color: 'pink' }))
+
+    const ambientLight = new AmbientLight('white', 0.2)
+    const directionalLight = new DirectionalLight('pink', 2)
+    directionalLight.position.set(0, -5, 0)
+    const pointLight1 = new PointLight('pink', 0.4)
+    pointLight1.position.set(-10, -10, 10)
+    const pointLight2 = new PointLight('white', 0.2)
+    pointLight2.position.set(-10, -10, 10)
+    const spotLight = new SpotLight('white', 2, 35, Math.PI / 4, 2, 3.5)
+    spotLight.position.set(-3, 6, -4)
+
+    const { scene, renderer } = useThree({
+      useFrame: (_, delta) => {
+        mesh.rotation.x += delta
+        mesh.rotation.y += delta
+      },
+    })
+
+    scene.background = new Color(0x0000ff).convertSRGBToLinear()
+    scene.add(ambientLight, directionalLight, pointLight1, pointLight2, spotLight, mesh)
+
+    return () => {
+      renderer.dispose()
+    }
+  }, [])
+
+  return ''
+}

.storybook/tsconfig.json

@@ -0,0 +1,5 @@
+{
+  "extends": "../tsconfig",
+  "exclude": [],
+  "include": ["./stories/*"]
+}

CONTRIBUTING.md

@@ -13,6 +13,15 @@ Thanks for wanting to make a contribution and wanting to improve this library fo
 
 Be sure your commit messages follow this specification: https://www.conventionalcommits.org/en/v1.0.0-beta.4/
 
+## Storybook
+
+If you're adding a brand new feature, you need to make sure you add a storybook entry, here's a few tips:
+
+- Make use of @storybook/controls to show component variants & configuration
+- Keep the story simple & show the essence of the component, remember some people may be looking at using drei for the first time & it's important the stories are clear and concise.
+- Keep assets minimal (3D Models, textures) to avoid bloating the repository
+- If you think a more involved example is necessary, you can always add a codesandbox CI in the `/demos/*` folder
+
 ## Publishing
 
 We use `semantic-release-action` to deploy the package. Because of this only certain commits will trigger the action of creating a release:

README.md

@@ -1,10 +1,18 @@
 # three-stdlib
 
-[![release](https://github.com/pmndrs/three-stdlib/actions/workflows/main.yml/badge.svg)](https://github.com/pmndrs/three-stdlib/actions/workflows/main.yml)
+[![Version](https://img.shields.io/npm/v/three-stdlib?style=flat&colorA=000000&colorB=000000)](https://npmjs.com/package/three-stdlib)
+[![Downloads](https://img.shields.io/npm/dt/three-stdlib.svg?style=flat&colorA=000000&colorB=000000)](https://npmjs.com/package/three-stdlib)
+[![Twitter](https://img.shields.io/twitter/follow/pmndrs?label=%40pmndrs&style=flat&colorA=000000&colorB=000000&logo=twitter&logoColor=000000)](https://twitter.com/pmndrs)
+[![Discord](https://img.shields.io/discord/740090768164651008?style=flat&colorA=000000&colorB=000000&label=discord&logo=discord&logoColor=000000)](https://discord.gg/ZZjjNvJ)
+[![release](https://github.com/pmndrs/three-stdlib/actions/workflows/main.yml/badge.svg?style=flat&colorA=000000&colorB=000000)](https://github.com/pmndrs/three-stdlib/actions/workflows/main.yml)
+
+Stand-alone version of [threejs/examples/jsm](https://github.com/mrdoob/three.js/tree/dev/examples/jsm) written in Typescript & built for ESM & CJS.
+
+## Basic usage
 
     npm install three-stdlib
 
-```jsx
+```ts
 // Export collection
 import * as STDLIB from 'three-stdlib'
 // Flatbundle
@@ -13,9 +21,11 @@ import { OrbitControls, ... } from 'three-stdlib'
 import { OrbitControls } from 'three-stdlib/controls/OrbitControls'
 ```
 
-This is a stand-alone of https://github.com/mrdoob/three.js/tree/dev/examples/jsm
+## Problem
 
-Our main goals are:
+`threejs/examples` were always considered as something that you need to copy/paste into your project and adapt to your needs. But that's not how people use them. This causes numerous issues & little support.
+
+## Solution
 
 - Real, npm/node conform esm modules with marked dependencies
 - Class based, optimized for tree-shaking, no global pollution, exports instead of collections
@@ -24,11 +34,14 @@ Our main goals are:
 - Typesafety with simple annotation-like types
 - CI, tests, linting, formatting (prettier)
 
-But most importantly, allowing the people that use and rely on these primitives to hold a little stake, and to distribute the weight of maintaining it. Jsm/examples were always considered as something that you copy/paste into your project and adapt to your needs. But that is not how people use it.
+But most importantly, allowing the people that use and rely on these primitives to hold a little stake, and to distribute the weight of maintaining it.
 
 Let's give jsm/examples the care it deserves!
 
-## Changes
+## How to contribute
+
+If you want to get involved you could do any of the following:
 
-- [x] All Collections have been converted to export maps (GeometryUtils, CurveExtras, etc)
-- [x] WebGL has been moved to /misc
+- Create amazing stories for these examples for our dedicate storybook
+- Convert some of the files to Typescript
+- Add new examples for the library you think could be awesome for others

demos/ssr/.babelrc

@@ -0,0 +1,12 @@
+{
+  "presets": ["next/babel"],
+  "plugins": [
+    [
+      "styled-components",
+      {
+        "ssr": true,
+        "preprocess": false
+      }
+    ]
+  ]
+}

demos/ssr/components/Controls.tsx

@@ -0,0 +1,27 @@
+import { useEffect, useState } from 'react'
+// @ts-ignore
+import { OrbitControls } from 'three-stdlib'
+import { useThree } from 'react-three-fiber'
+
+export const Controls = (): JSX.Element | null => {
+  const { camera, gl, invalidate } = useThree()
+
+  const [controls, setControls] = useState<OrbitControls>()
+
+  useEffect(() => {
+    setControls(new OrbitControls(camera, gl.domElement))
+  }, [camera, gl])
+
+  useEffect(() => {
+    if (controls) {
+      controls.addEventListener('change', invalidate)
+    }
+    return (): void => {
+      if (controls) {
+        controls.removeEventListener('change', invalidate)
+      }
+    }
+  }, [controls, invalidate])
+
+  return controls ? <primitive dispose={undefined} object={controls} enableDamping /> : null
+}

demos/ssr/components/Lights.tsx

@@ -0,0 +1,11 @@
+export const Lights = (): JSX.Element => {
+  return (
+    <group>
+      <spotLight position={[-3, 6, -4]} intensity={10} angle={Math.PI / 4} decay={3.5} distance={35} penumbra={2} />
+      <pointLight position={[-10, -10, 10]} color="pink" intensity={1} />
+      <pointLight position={[-5, -5, 5]} intensity={0.2} />
+      <directionalLight position={[0, -5, 0]} color="pink" intensity={2} />
+      <ambientLight intensity={0.2} color="white" />
+    </group>
+  )
+}

demos/ssr/components/Scene.tsx

@@ -0,0 +1,30 @@
+import { useRef } from 'react'
+import { useFrame } from 'react-three-fiber'
+import { Mesh } from 'three'
+
+import { Lights } from './Lights'
+import { Controls } from './Controls'
+
+export const Scene = (): JSX.Element => {
+  const meshRef = useRef<Mesh>()
+
+  useFrame((_, delta) => {
+    const { current: mesh } = meshRef
+
+    if (mesh) {
+      mesh.rotation.x += delta
+      mesh.rotation.y += delta
+    }
+  })
+
+  return (
+    <>
+      <Controls />
+      <Lights />
+      <mesh ref={meshRef}>
+        <icosahedronBufferGeometry args={[1]} />
+        <meshStandardMaterial color="pink" roughness={0} />
+      </mesh>
+    </>
+  )
+}

demos/ssr/next-env.d.ts

@@ -0,0 +1,2 @@
+/// <reference types="next" />
+/// <reference types="next/types/global" />

demos/ssr/next.config.js

@@ -0,0 +1,3 @@
+module.exports = {
+  future: { webpack5: true },
+}