docs: update with suggestions

Co-authored-by: Michael Peyper <[email protected]>

Author: joshuaellis

docs/usage/ssr-hooks.md

@@ -1,96 +1,139 @@
 ---
-name: SSR Hooks
+---
+name: Server-Side Rendering
 menu: Usage
 route: '/usage/ssr-hooks'
 ---
 
-# Server Side Renderering
+# Server-Side Rendering (SSR)
 
 ## Setup
 
-To SSR your hook, you must ensure `react-dom >= 16.9.0` is installed in your project and then import
-the server module in your test:
+To test how your hook will behave when rendered on the server, you can change your import to the use
+the `server` module:
 
 ```ts
 import { renderHook } from '@testing-library/react-hooks/server'
 ```
 
-## Render Hook
+> SSR is only available when using the `react-dom` renderer. Please refer to the
+> [installation guide](/installation#peer-dependencies) for instructions and supported versions.
 
-`renderHook` when called returns the same result as documented in the
-[API](/reference/api#renderhook-result) but includes an additional argument, `hydrate`:
+This import has the same [API as the standard import](/reference/api) except the behaviour changes
+to use SSR semantics.
 
-```ts
-function hydrate(): void
-```
+## Example
 
-The `hydrate` function is a light wrapper around
-[`ReactDOM.hydrate`](https://reactjs.org/docs/react-dom.html#hydrate) but no arguments are required
-as the library will pass the element & container for you. Remember, certain effects such as
-`useEffect` will not run server side and `hydrate` must be called before those effects are
-ran.`hydrate`is also necessary before the first `act` or `rerender` call. For more information on
-`hydrate` see the [API documentation](/reference/api#hydrate). There is also an
-[example below](/usage/ssr-hooks#example)
+## Hydration
 
-## Example
+The result of rendering you hook is static are not interactive until it is hydrated into the DOM.
+This can be done using the `hydrate` function that is returned from `renderHook`.
+
+Consider the `useCounter` example from the [Basic Hooks section](/usage/basic-hooks):
+
+```js
+import { useState, useCallback } from 'react'
+
+export default function useCounter() {
+  const [count, setCount] = useState(0)
+  const increment = useCallback(() => setCount((x) => x + 1), [])
+  return { count, increment }
+}
+```
 
-### Hydration
+If we try to call `increment` immediately after server rendering, nothing happens and the hook is
+not interactive:
 
 ```js
 import { renderHook, act } from '@testing-library/react-hooks/server'
+import useCounter from './useCounter'
 
-describe('custom hook tests', () => {
-  function useCounter() {
-    const [count, setCount] = useState(0)
+test('should increment counter', () => {
+  const { result } = renderHook(() => useCounter(0))
 
-    const increment = useCallback(() => setCount(count + 1), [count])
-    const decrement = useCallback(() => setCount(count - 1), [count])
+  act(() => {
+    result.current.increment()
+  })
 
-    return { count, increment, decrement }
-  }
+  expect(result.current.count).toBe(1) // fails as result.current.count is still 0
+})
+```
 
-  test('should decrement counter', () => {
-    const { result, hydrate } = renderHook(() => useCounter())
+We can make the hook interactive by calling the `hydrate` function that is returned from
+`renderHook`:
 
-    expect(result.current.count).toBe(0)
+```js
+import { renderHook, act } from '@testing-library/react-hooks/server'
+import useCounter from './useCounter'
 
-    // hydrate is called because we want to interact with the hook
-    hydrate()
+test('should increment counter', () => {
+  const { result, hydrate } = renderHook(() => useCounter(0))
 
-    act(() => result.current.decrement())
+  hydrate()
 
-    expect(result.current.count).toBe(-1)
+  act(() => {
+    result.current.increment()
   })
+
+  expect(result.current.count).toBe(1) // now it passes
 })
 ```
 
+Anything that causes the hook's state to change will not work until `hydrate` is called. This
+includes both the [`rerender`](http://localhost:3000/reference/api#rerender) and
+[`unmount`](http://localhost:3000/reference/api#unmount) functionality.
+
 ### Effects
 
+Another caveat of SSR is that `useEffect` and `useLayoutEffect` hooks, by design, do not run on when
+rendering.
+
+Consider this `useTimer` hook:
+
 ```js
-describe('useEffect tests', () => {
-  test('should handle useEffect hook', () => {
-    const sideEffect = { 1: false, 2: false }
-
-    const useEffectHook = ({ id }) => {
-      useEffect(() => {
-        sideEffect[id] = true
-        return () => {
-          sideEffect[id] = false
-        }
-      }, [id])
+import { useState, useCallback, useEffect } from 'react'
+
+export default function useTimer() {
+  const [count, setCount] = useState(0)
+  const reset = useCallback(() => setCount(0), [])
+  useEffect(() => {
+    const intervalId = setInterval(() => setCount((c) => c + 1, 1000))
+    return () => {
+      clearInterval(intervalId)
     }
+  })
+  return { count, reset }
+}
+```
 
-    const { hydrate, rerender, unmount } = renderHook((id) => useEffectHook({ id }), {
-      initialProps: { id: 1 }
-    })
+Upon initial render, the interval will not start:
 
-    expect(sideEffect[1]).toBe(false)
-    expect(sideEffect[2]).toBe(false)
+```js
+import { renderHook, act } from '@testing-library/react-hooks/server'
+import useTimer from './useTimer'
 
-    hydrate()
+test('should start the timer', async () => {
+  const { result, waitForValueToChange } = renderHook(() => useTimer(0))
 
-    expect(sideEffect[1]).toBe(true)
-    expect(sideEffect[2]).toBe(false)
-  })
+  await waitForValueToChange(() => result.current.count) // times out as the value never changes
+
+  expect(result.current.count).toBe(1) // fails as result.current.count is still 0
+})
+```
+
+Similarly to updating the hooks state, the effect will start after `hydrate` is called:
+
+```js
+import { renderHook, act } from '@testing-library/react-hooks/server'
+import useTimer from './useTimer'
+
+test('should start the timer', async () => {
+  const { result, hydrate, waitForValueToChange } = renderHook(() => useTimer(0))
+
+  hydrate()
+
+  await waitForValueToChange(() => result.current.count) // now resolves when the interval fires
+
+  expect(result.current.count).toBe(1)
 })
 ```