Introduce usePage and useSuperglue hooks.

These are lightweight wrappers around Redux's `useSelector` and a nice, but
must have convenience as we move away from `mapStateToProps`.

mkdocs.yml

@@ -121,6 +121,7 @@ nav:
   - Reference:
     - Rails Utilities: rails-utils.md
     - Page utilities: functions-passed.md
+    - Hooks: reference/hooks.md
     - Nav: reference/components.Nav.md
     - Superglue: reference/index.md
     - Types: reference/types.md

superglue/lib/hooks/index.ts

@@ -0,0 +1,19 @@
+import { useSelector } from 'react-redux'
+import { Page, RootState, SuperglueState } from '../types'
+
+/**
+ * A lightweight hook that grabs the superglue state from the store.
+ */
+export function useSuperglue() {
+  return useSelector<RootState, SuperglueState>((state) => state.superglue)
+}
+
+/**
+ * A lightweight hook that grabs the current page from the store.
+ */
+export function usePage() {
+  const superglueState = useSuperglue()
+  const currentPageKey = superglueState.currentPageKey
+
+  return useSelector<RootState, Page>((state) => state.pages[currentPageKey])
+}

superglue/lib/index.tsx

@@ -44,6 +44,7 @@ import {
 export { fragmentMiddleware } from './middleware'
 export { getIn } from './utils/immutability'
 export { urlToPageKey }
+export { usePage, useSuperglue } from './hooks'
 
 function pageToInitialState(key: string, page: VisitResponse) {
   const slices = page.slices || {}

superglue/spec/lib/hooks.spec.jsx

@@ -0,0 +1,73 @@
+import { renderHook } from '@testing-library/react'
+import { usePage, useSuperglue } from '../../lib'
+import { describe, it } from 'vitest'
+import { Provider } from 'react-redux'
+import { configureStore } from '@reduxjs/toolkit'
+
+describe('hooks', () => {
+  describe('useSuperglue', () => {
+    it('returns the superglue state', () => {
+      const preloadedState = {
+        superglue: {
+          currentPageKey: '/current?abc=123',
+          pathname: '/current',
+          search: '?abc=123',
+          csrfToken: 'csrf123',
+          assets: ['js-asset-123'],
+        },
+      }
+
+      let store = configureStore({
+        preloadedState,
+        reducer: (state) => state,
+      })
+      const wrapper = ({ children }) => (
+        <Provider store={store}>{children}</Provider>
+      )
+      const { result } = renderHook(() => useSuperglue(), { wrapper })
+
+      expect(result.current).toEqual(preloadedState.superglue)
+    })
+  })
+
+  describe('usePage', () => {
+    it('returns the page state', () => {
+      const preloadedState = {
+        superglue: {
+          currentPageKey: '/current?abc=123',
+          pathname: '/current',
+          search: '?abc=123',
+          csrfToken: 'csrf123',
+          assets: ['js-asset-123'],
+        },
+        pages: {
+          '/current?abc=123': {
+            data: {
+              heading: 'selected',
+            },
+          },
+          '/other': {
+            data: {
+              heading: 'not selected',
+            },
+          },
+        },
+      }
+
+      let store = configureStore({
+        preloadedState,
+        reducer: (state) => state,
+      })
+      const wrapper = ({ children }) => (
+        <Provider store={store}>{children}</Provider>
+      )
+      const { result } = renderHook(() => usePage(), { wrapper })
+
+      expect(result.current).toEqual({
+        data: {
+          heading: 'selected',
+        },
+      })
+    })
+  })
+})

superglue/typedoc.json

@@ -4,6 +4,7 @@
   "entryPoints": [
     "./lib/index.tsx",
     "./lib/types/index.ts",
+    "./lib/hooks/index.ts",
     "./lib/types/requests.ts",
     "./lib/components/Nav.tsx"
   ],