feat: Example component (#1439)

* docs(Example): an Example component

* docs: inner-links

.github/PULL_REQUEST_TEMPLATE.md

@@ -25,8 +25,8 @@ To check an item, place an "x" in the box like so: "- [x] Documentation"
 Remove items that are irrelevant to your changes.
 -->
 
-- [ ] Documentation updated
-- [ ] Storybook entry added
+- [ ] Documentation updated ([example](../README.md#example))
+- [ ] Storybook entry added ([example](../.storybook/stories/Example.stories.tsx))
 - [ ] Ready to be merged
 
 <!-- if you untick ready to be merged & you haven't submitted as a draft, we will change it to draft. -->

.storybook/stories/Example.stories.tsx

@@ -0,0 +1,64 @@
+import * as THREE from 'three'
+import * as React from 'react'
+import { withKnobs } from '@storybook/addon-knobs'
+import { Vector3 } from 'three'
+
+import { Setup } from '../Setup'
+
+import { Example, ExampleApi, Sparkles } from '../../src'
+
+export default {
+  title: 'Misc/Example',
+  component: Example,
+  decorators: [
+    withKnobs,
+    (storyFn) => (
+      <Setup cameraPosition={new Vector3(1, 2, 4)} cameraFov={60}>
+        {storyFn()}
+      </Setup>
+    ),
+  ],
+}
+
+export const ExampleSt = ({ fontUrl, color, bevelSize, debug }) => {
+  const apiRef = React.useRef<ExampleApi>(null)
+
+  return (
+    <>
+      <color attach="background" args={['#303030']} />
+      <axesHelper />
+
+      <Example
+        font={fontUrl}
+        color={color}
+        bevelSize={bevelSize}
+        debug={debug}
+        ref={apiRef}
+        onClick={(e) => {
+          if ((e as any as PointerEvent).metaKey) {
+            apiRef.current?.decr()
+          } else {
+            apiRef.current?.incr()
+          }
+        }}
+      >
+        <Sparkles scale={2} />
+      </Example>
+    </>
+  )
+}
+ExampleSt.args = {
+  fontUrl: '/fonts/Inter_Bold.json',
+  bevelSize: undefined,
+  color: '#cbcbcb',
+  debug: false,
+}
+
+ExampleSt.argTypes = {
+  fontUrl: { control: 'select', options: ['/fonts/Inter_Bold.json', '/fonts/helvetiker_regular.typeface.json'] },
+  bevelSize: { control: { type: 'range', min: 0, max: 0.1, step: 0.01 } },
+  color: { control: { type: 'color' } },
+  debug: { control: { type: 'boolean' } },
+}
+
+ExampleSt.storyName = 'Default'

CONTRIBUTING.md

@@ -9,6 +9,12 @@ Thanks for wanting to make a contribution and wanting to improve this library fo
 3.  Create a branch for your PR with `git checkout -b pr-type/issue-number-your-branch-name`
 4.  Let's get cooking! 👨🏻‍🍳🥓
 
+You can also just [![Open in GitHub Codespaces](https://img.shields.io/static/v1?&message=Open%20in%20%20Codespaces&style=flat&colorA=000000&colorB=000000&label=GitHub&logo=github&logoColor=ffffff)](https://github.com/codespaces/new?template_repository=pmndrs%2Fdrei).
+
+## Example
+
+You'll find a sample [`Example.tsx`](src/core/Example.tsx) component and its associated [`Example.stories.tsx`](.storybook/stories/Example.stories.tsx) to start with, as well as its documentation in the [`README`](README.md#example)
+
 ## Commit Guidelines
 
 Be sure your commit messages follow this specification: https://www.conventionalcommits.org/en/v1.0.0-beta.4/

README.md

@@ -5,7 +5,7 @@
 [![Discord Shield](https://img.shields.io/discord/740090768164651008?style=flat&colorA=000000&colorB=000000&label=discord&logo=discord&logoColor=ffffff)](https://discord.com/channels/740090768164651008/741751532592038022)
 [![Open in GitHub Codespaces](https://img.shields.io/static/v1?&message=Open%20in%20%20Codespaces&style=flat&colorA=000000&colorB=000000&label=GitHub&logo=github&logoColor=ffffff)](https://github.com/codespaces/new?template_repository=pmndrs%2Fdrei)
 
-A growing collection of useful helpers and fully functional, ready-made abstractions for [@react-three/fiber](https://github.com/pmndrs/react-three-fiber). If you make a component that is generic enough to be useful to others, think about making it available here through a PR!
+A growing collection of useful helpers and fully functional, ready-made abstractions for [@react-three/fiber](https://github.com/pmndrs/react-three-fiber). If you make a component that is generic enough to be useful to others, think about [CONTRIBUTING](CONTRIBUTING.md)!
 
 ```bash
 npm install @react-three/drei
@@ -101,6 +101,7 @@ The `native` route of the library **does not** export `Html` or `Loader`. The de
       <ul>
         <li><a href="#misc">Misc</a></li>
         <ul>
+          <li><a href="#example">Example</a></li>
           <li><a href="#html">Html</a></li>
           <li><a href="#cycleraycast">CycleRaycast</a></li>
           <li><a href="#select">Select</a></li>
@@ -1882,6 +1883,42 @@ function Scene() {
 }
 ```
 
+#### Example
+
+[![](https://img.shields.io/badge/-storybook-%23ff69b4)](https://drei.vercel.app/?path=/story/misc-example--example-st)
+
+> :warning: solely for [`CONTRIBUTING`](CONTRIBUTING.md#example) purposes
+
+A "counter" example.
+
+```tsx
+<Example />
+```
+
+```tsx
+type ExampleProps = {
+  color?: Color
+  debug?: boolean
+  bevelSize?: number
+  font?: string
+}
+```
+
+Ref-api:
+
+```tsx
+const api = useRef<ExampleApi>()
+
+<Example ref={api} />
+```
+
+```tsx
+type ExampleApi = {
+  incr: (x?: number) => void
+  decr: (x?: number) => void
+}
+```
+
 #### Html
 
 [![](https://img.shields.io/badge/-storybook-%23ff69b4)](https://drei.vercel.app/?path=/story/misc-html--html-st) ![](https://img.shields.io/badge/-Dom only-red)

src/core/Example.tsx

@@ -0,0 +1,47 @@
+/* eslint react-hooks/exhaustive-deps: 1 */
+import * as React from 'react'
+import * as THREE from 'three'
+import { type Color } from '@react-three/fiber'
+
+import { Text3D } from './Text3D'
+import { Center } from './Center'
+
+export type ExampleProps = {
+  color?: Color
+  debug?: boolean
+  bevelSize?: number
+  font?: string
+} & JSX.IntrinsicElements['group']
+
+export type ExampleApi = {
+  incr: (x?: number) => void
+  decr: (x?: number) => void
+}
+
+export const Example = React.forwardRef<ExampleApi, ExampleProps>(
+  (
+    { font = '/fonts/Inter_Bold.json', color = '#cbcbcb', bevelSize = 0.04, debug = false, children, ...props },
+    fref
+  ) => {
+    const [counter, setCounter] = React.useState(0)
+
+    const incr = React.useCallback((x = 1) => setCounter(counter + x), [counter])
+    const decr = React.useCallback((x = 1) => setCounter(counter - x), [counter])
+
+    // ref-API
+    const api = React.useMemo<ExampleApi>(() => ({ incr, decr }), [incr, decr])
+    React.useImperativeHandle(fref, () => api, [api])
+
+    return (
+      <group {...props}>
+        <Center top cacheKey={JSON.stringify({ counter, font })}>
+          <Text3D bevelEnabled bevelSize={bevelSize} font={font}>
+            {counter}
+            {debug ? <meshNormalMaterial wireframe /> : <meshStandardMaterial color={color} />}
+          </Text3D>
+        </Center>
+        {children}
+      </group>
+    )
+  }
+)

src/core/index.ts

@@ -71,6 +71,7 @@ export * from './useBoxProjectedEnv'
 export * from './BBAnchor'
 export * from './useTrailTexture'
 export * from './useCubeCamera'
+export * from './Example'
 
 // Modifiers
 export * from './CurveModifier'