Docs, finally

.github/workflows/deploy-docs.yml

@@ -0,0 +1,20 @@
+name: Deploy Documentation
+on:
+  push:
+    branches:
+      - master
+jobs:
+  build_docs:
+    name: Build and Deploy Documentation
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checking out Repository
+        uses: actions/checkout@v1
+      - name: Setup Node.js
+        uses: actions/setup-node@v1
+      - name: Install Dependencies
+        run: yarn bootstrap
+      - name: Build and Deploy Production Files
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: yarn deploy-docs

.github/workflows/test.yml

@@ -0,0 +1,29 @@
+name: Run Tests
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+    branches:
+      - master
+jobs:
+  test:
+    name: Run Testing Suite
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checking out Repository
+        uses: actions/checkout@v2
+      - name: Setup Node.js
+        uses: actions/setup-node@v1
+        with:
+          node-version: 12.x
+      - name: Install Dependencies
+        run: yarn bootstrap
+      - name: Run Tests
+        run: yarn test
+      - name: Build Project
+        run: yarn build
+      - name: Upload Test Coverage to CodeCov
+        uses: codecov/codecov-action@v1.0.2
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}

package.json

@@ -18,10 +18,12 @@
   },
   "homepage": "https://github.com/react-restart/hooks#readme",
   "scripts": {
+    "bootstrap": "yarn && yarn --cwd www",
     "test": "jest --coverage",
     "tdd": "jest --watch",
     "build:pick": "cherry-pick --name=@restart/hooks --cwd=lib --input-dir=../src --cjs-dir=cjs --esm-dir=esm",
     "build": "rimraf lib && 4c build src && yarn build:pick",
+    "deploy-docs": "yarn --cwd www build --prefix-paths && gh-pages -d www/public",
     "prepublishOnly": "yarn build"
   },
   "jest": {
@@ -65,6 +67,7 @@
     "enzyme": "^3.10.0",
     "enzyme-adapter-react-16": "^1.15.1",
     "eslint": "^6.7.0",
+    "gh-pages": "^2.2.0",
     "husky": "^4.2.3",
     "jest": "^25.1.0",
     "lint-staged": "^10.0.8",

src/globals.d.ts

@@ -53,7 +53,7 @@ interface ResizeObserverEntry {
 }
 
 interface DOMRectReadOnly {
-  static fromRect(other: DOMRectInit | undefined): DOMRectReadOnly
+  fromRect(other: DOMRectInit | undefined): DOMRectReadOnly
 
   readonly x: number
   readonly y: number

src/useFocusManager.ts

@@ -1,7 +1,6 @@
 import { useCallback, useRef } from 'react'
-
-import useMounted from './useMounted'
 import useEventCallback from './useEventCallback'
+import useMounted from './useMounted'
 
 export interface FocusManagerOptions {
   /**
@@ -26,13 +25,17 @@ export interface FocusManagerOptions {
   isDisabled: () => boolean
 }
 
+export interface FocusController {
+  onBlur: (event: any) => void
+  onFocus: (event: any) => void
+}
 /**
  * useFocusManager provides a way to track and manage focus as it moves around
  * a container element. An `onChange` is fired when focus enters or leaves the
  * element, but not when it moves around inside the element, similar to
  * `pointerenter` and `pointerleave` DOM events.
  *
- * ```ts
+ * ```tsx
  * const [focused, setFocusState] = useState(false)
  *
  * const { onBlur, onFocus } = useFocusManager({
@@ -49,10 +52,10 @@ export interface FocusManagerOptions {
  *   </div>
  * ```
  *
- * @param opts Options
- * @returns FocusController a set of paired focus and blur event handlers
  */
-export default function useFocusManager(opts: FocusManagerOptions) {
+export default function useFocusManager(
+  opts: FocusManagerOptions,
+): FocusController {
   const isMounted = useMounted()
 
   const lastFocused = useRef<boolean | undefined>()

src/useInterval.ts

@@ -4,6 +4,15 @@ import useCommittedRef from './useCommittedRef'
 /**
  * Creates a `setInterval` that is properly cleaned up when a component unmounted
  *
+ * ```tsx
+ *  function Timer() {
+ *    const [timer, setTimer] = useState(0)
+ *    useInterval(() => setTimer(i => i + 1), 1000)
+ *
+ *    return <span>{timer} seconds past</span>
+ *  }
+ * ```
+ *
  * @param fn an function run on each interval
  * @param ms The milliseconds duration of the interval
  */
@@ -12,22 +21,53 @@ function useInterval(fn: () => void, ms: number): void
 /**
  * Creates a pausable `setInterval` that is properly cleaned up when a component unmounted
  *
+ * ```tsx
+ *  const [paused, setPaused] = useState(false)
+ *  const [timer, setTimer] = useState(0)
+ *
+ *  useInterval(() => setTimer(i => i + 1), 1000, paused)
+ *
+ *  return (
+ *    <span>
+ *      {timer} seconds past
+ *
+ *      <button onClick={() => setPaused(p => !p)}>{paused ? 'Play' : 'Pause' }</button>
+ *    </span>
+ * )
+ * ```
+ *
  * @param fn an function run on each interval
  * @param ms The milliseconds duration of the interval
  * @param paused Whether or not the interval is currently running
  */
 function useInterval(fn: () => void, ms: number, paused: boolean): void
 
 /**
- * Creates a pausable `setInterval` that is properly cleaned up when a component unmounted
+ * Creates a pausable `setInterval` that _fires_ immediately and is
+ * properly cleaned up when a component unmounted
+ *
+ * ```tsx
+ *  const [timer, setTimer] = useState(-1)
+ *  useInterval(() => setTimer(i => i + 1), 1000, false, true)
+ *
+ *  // will update to 0 on the first effect
+ *  return <span>{timer} seconds past</span>
+ * ```
  *
  * @param fn an function run on each interval
  * @param ms The milliseconds duration of the interval
  * @param paused Whether or not the interval is currently running
  * @param runImmediately Whether to run the function immediately on mount or unpause
  * rather than waiting for the first interval to elapse
+ *
+
  */
-function useInterval(fn: () => void, ms: number, paused: boolean, runImmediately: boolean): void
+function useInterval(
+  fn: () => void,
+  ms: number,
+  paused: boolean,
+  runImmediately: boolean,
+): void
 
 function useInterval(
   fn: () => void,

src/useSet.ts

@@ -49,7 +49,7 @@ export class ObservableSet<V> extends Set<V> {
  *
  * @param init initial Set values
  */
-function useSet<V>(init?: Iterable<V>) {
+function useSet<V>(init?: Iterable<V>): ObservableSet<V> {
   const forceUpdate = useForceUpdate()
   return useStableMemo(() => new ObservableSet<V>(forceUpdate, init), [])
 }

www/.babelrc

@@ -0,0 +1,3 @@
+{
+  "extends": "../.babelrc"
+}

www/.gitignore

@@ -0,0 +1,2 @@
+.cache/
+public/

www/gatsby-config.js

@@ -0,0 +1,26 @@
+const path = require('path')
+
+module.exports = {
+  siteMetadata: {
+    title: '@restart/hooks',
+    author: 'Jason Quense',
+  },
+  plugins: [
+    {
+      resolve: '@docpocalypse/gatsby-theme',
+      options: {
+        sources: [`${__dirname}/../src`],
+        getImportName(docNode) {
+          return `import ${docNode.name} from '${docNode.packageName}/${docNode.name}'`
+        },
+      },
+    },
+    {
+      resolve: 'gatsby-plugin-typedoc',
+      options: {
+        debugRaw: true,
+        projects: [path.resolve(__dirname, '../src')],
+      },
+    },
+  ],
+}

www/gatsby-node.js

@@ -0,0 +1,8 @@
+// Tells gatsby how to find the babel config for the src files as well as itself
+exports.onCreateBabelConfig = ({ actions }) => {
+  actions.setBabelOptions({
+    options: {
+      babelrcRoots: true,
+    },
+  })
+}

www/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "docs-site",
+  "version": "0.0.0",
+  "private": true,
+  "scripts": {
+    "start": "gatsby develop",
+    "build": "gatsby build"
+  },
+  "dependencies": {
+    "@docpocalypse/gatsby-theme": "^0.11.25",
+    "gatsby": "^2.21.24",
+    "gatsby-plugin-typedoc": "^0.3.11",
+    "react": "^16.13.1",
+    "react-dom": "^16.13.1"
+  }
+}

www/src/pages/index.mdx

@@ -0,0 +1,17 @@
+# Getting Started
+
+`@restart/hooks` is a utility library of React hooks. There is a hook for almost any use case.
+Try them all!
+
+## Installation
+
+Install via your favorite package manager:
+
+```sh
+npm install @restart/hooks
+```
+
+## Usage
+
+Check out the indivudal API docs for each hook for descriptions of what it does and
+how to use it.

www/tailwind.config.js

@@ -0,0 +1,12 @@
+module.exports = {
+  theme: {
+    extend: {
+      colors: {
+        primary: '#A93F55',
+        black: '#19323C',
+        accent: '#B2675E',
+        subtle: '#EEE0CB',
+      },
+    },
+  },
+}

www/templates/component.js

@@ -0,0 +1 @@
+export default () => null