Merge pull request #28 from react-restart/docs2

Docs, finally

Author: jquense

.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/[email protected]
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}

.travis.yml

@@ -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",

package.json

@@ -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/globals.d.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/useBreakpoint.tsx renamed to src/useBreakpoint.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/useFocusManager.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), [])
 }

src/useInterval.ts

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