From fff19f9d2ad7f2fbc5d68d89054a3fe2543da6b2 Mon Sep 17 00:00:00 2001
From: Chris Chudzicki <christopher.chudzicki@gmail.com>
Date: Thu, 13 Apr 2023 16:44:26 -0400
Subject: [PATCH] Allow using for UI management but not API mangement (#51)

---
 jest.config.ts     |   2 +-
 package.json       |   3 +-
 src/hooks.ts       |  15 +-
 src/index.test.tsx | 413 ++++++++++++++++++++++++++++++++++++++++-
 src/index.ts       | 446 ++++++++++++++++++++++++++++++++-------------
 src/url_utils.ts   |   8 +-
 yarn.lock          |  27 +++
 7 files changed, 772 insertions(+), 142 deletions(-)

diff --git a/jest.config.ts b/jest.config.ts
index 41f2f5e..9cfc46c 100644
--- a/jest.config.ts
+++ b/jest.config.ts
@@ -27,4 +27,4 @@ const config: Config.InitialOptions = {
   ]
 }
 
-export default config
\ No newline at end of file
+export default config
diff --git a/package.json b/package.json
index 5e4626f..ba25c8f 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@mitodl/course-search-utils",
-  "version": "2.0.4",
+  "version": "2.1.0",
   "description": "JS utils for interacting with MIT Open Course search",
   "main": "dist/index.js",
   "files": [
@@ -41,6 +41,7 @@
   "devDependencies": {
     "@swc/core": "^1.3.0",
     "@swc/jest": "^0.2.22",
+    "@testing-library/react-hooks": "^8.0.1",
     "@types/enzyme": "^3.10.7",
     "@types/jest": "^29.0.1",
     "@types/lodash": "^4.14.162",
diff --git a/src/hooks.ts b/src/hooks.ts
index a109d7d..f8c5034 100644
--- a/src/hooks.ts
+++ b/src/hooks.ts
@@ -1,14 +1,17 @@
-import { useEffect, useRef } from "react"
+import { useEffect, useState } from "react"
 
-export function useDidMountEffect(fn: () => void, deps: any[]): void {
-  const renderedOnce = useRef(false)
+/**
+ * Like `useEffect`, but only runs after component has rendered at least once.
+ */
+export function useEffectAfterMount(fn: () => void, deps: any[]): void {
+  const [hasRendered, setHasRendered] = useState(false)
 
   useEffect(() => {
-    if (renderedOnce.current) {
+    if (hasRendered) {
       fn()
     } else {
-      renderedOnce.current = true
+      setHasRendered(true)
     }
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, deps)
+  }, [hasRendered, ...deps])
 }
diff --git a/src/index.test.tsx b/src/index.test.tsx
index 549a035..1977a15 100644
--- a/src/index.test.tsx
+++ b/src/index.test.tsx
@@ -1,7 +1,12 @@
 import * as React from "react"
 import { mount } from "enzyme"
 import { act } from "react-dom/test-utils"
-import { MemoryHistoryOptions, createMemoryHistory } from "history"
+import { renderHook } from "@testing-library/react-hooks/dom"
+import {
+  MemoryHistoryOptions,
+  createMemoryHistory,
+  InitialEntry
+} from "history"
 
 import {
   LearningResourceType,
@@ -9,7 +14,7 @@ import {
   LR_TYPE_ALL
 } from "./constants"
 
-import { useCourseSearch } from "./index"
+import { useCourseSearch, useSearchInputs, useSyncUrlAndSearch } from "./index"
 import { facetMap, wait } from "./test_util"
 import { serializeSort, serializeSearchParams } from "./url_utils"
 
@@ -309,14 +314,18 @@ describe("useCourseSearch", () => {
     const { wrapper, runSearch } = render()
     act(() => {
       // @ts-expect-error
-      wrapper.find(".toggleFacet").prop("onClick")("topic", "mathematics", true)
+      wrapper.find(".toggleFacet").prop("onClick")(
+        "topics",
+        "mathematics",
+        true
+      )
     })
     checkSearchCall(runSearch, [
       "",
       {
         ...INITIAL_FACET_STATE,
-        type:  LR_TYPE_ALL,
-        topic: ["mathematics"]
+        type:   LR_TYPE_ALL,
+        topics: ["mathematics"]
       },
       0,
       null,
@@ -329,7 +338,7 @@ describe("useCourseSearch", () => {
     act(() => {
       // @ts-expect-error
       wrapper.find(".toggleFacets").prop("onClick")([
-        ["topic", "mathematics", true],
+        ["topics", "mathematics", true],
         ["type", LearningResourceType.Course, false],
         ["type", LearningResourceType.ResourceFile, true]
       ])
@@ -338,8 +347,8 @@ describe("useCourseSearch", () => {
       "",
       {
         ...INITIAL_FACET_STATE,
-        type:  [LearningResourceType.ResourceFile],
-        topic: ["mathematics"]
+        type:   [LearningResourceType.ResourceFile],
+        topics: ["mathematics"]
       },
       0,
       null,
@@ -519,3 +528,391 @@ describe("useCourseSearch", () => {
     ])
   })
 })
+
+describe("useSearchInputs", () => {
+  it.each([
+    {
+      descrip:  "initial: empty",
+      initial:  null,
+      expected: {
+        text:         "",
+        activeFacets: INITIAL_FACET_STATE,
+        sort:         null,
+        ui:           null
+      }
+    },
+    {
+      descrip: "initial: text, facets, ui",
+      initial: {
+        text:         "cat",
+        activeFacets: { topics: ["math", "bio"] },
+        ui:           "list"
+      },
+      expected: {
+        text:         "cat",
+        activeFacets: { ...INITIAL_FACET_STATE, topics: ["math", "bio"] },
+        ui:           "list",
+        sort:         null
+      }
+    },
+    {
+      descrip:  "initial: sort",
+      initial:  { sort: { field: "coursenum", option: "asc" } },
+      expected: {
+        text:         "",
+        activeFacets: INITIAL_FACET_STATE,
+        sort:         { field: "coursenum", option: "asc" },
+        ui:           null
+      }
+    }
+  ])(
+    "Reads initial searchParams and text from history ($desc)",
+    ({ initial, expected }) => {
+      const initialEntries = initial ?
+        [`?${serializeSearchParams(initial)}`] :
+        undefined
+      const history = createMemoryHistory({ initialEntries })
+      const { result } = renderHook(() => useSearchInputs(history))
+      expect(result.current.searchParams).toEqual(expected)
+      expect(result.current.text).toEqual(expected.text)
+
+      /**
+       * We want to ensure that the initial state is set from the URL, as
+       * opposed to the initial state being empty and updated via a useEffect
+       * hook. The latter approach could lead to extra runSearch calls in
+       * useCourseSearch, or extra history entries with useSyncUrlAndSearch
+       */
+      expect(result.all.length).toBe(1)
+    }
+  )
+
+  test("setSearchParams updates searchParams when given an object", () => {
+    const history = createMemoryHistory()
+    const { result } = renderHook(() => useSearchInputs(history))
+    act(() => {
+      result.current.setSearchParams({
+        text:         "cat",
+        activeFacets: { topics: ["math", "bio"] },
+        ui:           null,
+        sort:         null
+      })
+    })
+    expect(result.current.searchParams).toEqual({
+      text:         "cat",
+      activeFacets: { topics: ["math", "bio"] },
+      sort:         null,
+      ui:           null
+    })
+  })
+
+  test("setSearchParams updates searchParams when given an callback", () => {
+    const history = createMemoryHistory()
+    const { result } = renderHook(() => useSearchInputs(history))
+    act(() => {
+      result.current.setSearchParams(current => ({ ...current, text: "cat" }))
+    })
+    expect(result.current.searchParams).toEqual({
+      text:         "cat",
+      activeFacets: INITIAL_FACET_STATE,
+      sort:         null,
+      ui:           null
+    })
+  })
+
+  test("setText updates text but NOT searchParams", () => {
+    const history = createMemoryHistory()
+    const { result } = renderHook(() => useSearchInputs(history))
+    expect(result.current.text).toEqual("")
+    const initialSearchParams = result.current.searchParams
+    act(() => {
+      result.current.setText("cat")
+    })
+    expect(result.current.searchParams).toEqual(initialSearchParams)
+    expect(result.current.text).toEqual("cat")
+  })
+
+  test("clearAllFilters clears text and searchParams", () => {
+    const initialEntries = [
+      `?${serializeSearchParams({
+        text:         "cat",
+        activeFacets: { topics: ["math", "bio"] },
+        ui:           "list",
+        sort:         { field: "coursenum", option: "asc" }
+      })}`
+    ]
+    const history = createMemoryHistory({ initialEntries })
+    const { result } = renderHook(() => useSearchInputs(history))
+    const initialSearchParams = result.current.searchParams
+    const initialText = result.current.text
+
+    act(() => result.current.clearAllFilters())
+    // data changed
+    expect(result.current.searchParams).not.toEqual(initialSearchParams)
+    expect(result.current.text).not.toEqual(initialText)
+
+    // reset as expected
+    expect(result.current.searchParams).toEqual({
+      text:         "",
+      activeFacets: INITIAL_FACET_STATE,
+      sort:         null,
+      ui:           null
+    })
+    expect(result.current.text).toEqual("")
+  })
+
+  test("toggleFacet adds/removes a facet", () => {
+    const initialEntries = [
+      `?${serializeSearchParams({
+        text:         "cat",
+        activeFacets: { topics: ["math", "bio"] }
+      })}`
+    ]
+    const history = createMemoryHistory({ initialEntries })
+    const { result } = renderHook(() => useSearchInputs(history))
+    act(() => {
+      result.current.toggleFacet("topics", "math", false)
+    })
+    expect(result.current.searchParams.activeFacets.topics).toEqual(["bio"])
+    act(() => {
+      result.current.toggleFacet("topics", "math", true)
+    })
+    expect(result.current.searchParams.activeFacets.topics).toEqual([
+      "bio",
+      "math"
+    ])
+  })
+
+  test("toggleFacets adds/removes multiple facets", () => {
+    const initialEntries = [
+      `?${serializeSearchParams({
+        text:         "cat",
+        activeFacets: {
+          topics:          ["math", "bio"],
+          level:           ["beginner"],
+          department_name: ["physics", "biology"]
+        }
+      })}`
+    ]
+    const history = createMemoryHistory({ initialEntries })
+    const { result } = renderHook(() => useSearchInputs(history))
+    act(() => {
+      result.current.toggleFacets([
+        ["topics", "chem", true],
+        ["level", "beginner", false],
+        ["department_name", "chemistry", true]
+      ])
+    })
+    expect(result.current.searchParams.activeFacets.topics).toEqual([
+      "math",
+      "bio",
+      "chem"
+    ])
+    expect(result.current.searchParams.activeFacets.level).toEqual([])
+    expect(result.current.searchParams.activeFacets.department_name).toEqual([
+      "physics",
+      "biology",
+      "chemistry"
+    ])
+  })
+
+  test("onUpdateFacet adds/removes a facet", () => {
+    const initialEntries = [
+      `?${serializeSearchParams({
+        text:         "cat",
+        activeFacets: { topics: ["math", "bio"] }
+      })}`
+    ]
+    const history = createMemoryHistory({ initialEntries })
+    const { result } = renderHook(() => useSearchInputs(history))
+    act(() => {
+      result.current.onUpdateFacet({
+        target: { name: "topics", value: "math", checked: false }
+      })
+    })
+    expect(result.current.searchParams.activeFacets.topics).toEqual(["bio"])
+    act(() => {
+      result.current.onUpdateFacet({
+        target: { name: "topics", value: "math", checked: true }
+      })
+    })
+    expect(result.current.searchParams.activeFacets.topics).toEqual([
+      "bio",
+      "math"
+    ])
+  })
+
+  test("toggleFacet sets texts -> searchParams.text", () => {
+    const history = createMemoryHistory()
+    const { result } = renderHook(() => useSearchInputs(history))
+
+    act(() => result.current.setText("algebra"))
+
+    expect(result.current.searchParams.text).toEqual("")
+    act(() => {
+      result.current.toggleFacet("topics", "math", true)
+    })
+    expect(result.current.searchParams.text).toEqual("algebra")
+  })
+
+  test("toggleFacets sets texts -> searchParams.text", () => {
+    const history = createMemoryHistory()
+    const { result } = renderHook(() => useSearchInputs(history))
+
+    act(() => result.current.setText("algebra"))
+
+    expect(result.current.searchParams.text).toEqual("")
+    act(() => {
+      result.current.toggleFacets([["topics", "math", true]])
+    })
+    expect(result.current.searchParams.text).toEqual("algebra")
+  })
+
+  test("onUpdateFacet sets texts -> searchParams.text", () => {
+    const history = createMemoryHistory()
+    const { result } = renderHook(() => useSearchInputs(history))
+
+    act(() => result.current.setText("algebra"))
+
+    expect(result.current.searchParams.text).toEqual("")
+    act(() => {
+      result.current.onUpdateFacet({
+        target: { name: "topics", value: "math", checked: true }
+      })
+    })
+    expect(result.current.searchParams.text).toEqual("algebra")
+  })
+
+  test("onUpdateText updates texts but not searchParams.text; submitText finalizes text", () => {
+    const history = createMemoryHistory()
+    const { result } = renderHook(() => useSearchInputs(history))
+
+    act(() => result.current.setText("algebra"))
+    expect(result.current.text).toBe("algebra")
+    expect(result.current.searchParams.text).toBe("")
+
+    act(() => result.current.submitText())
+    expect(result.current.searchParams.text).toBe("algebra")
+  })
+
+  test("clearText clears text and searchParams.text", () => {
+    const history = createMemoryHistory({
+      initialEntries: [`?${serializeSearchParams({ text: "algebra" })}`]
+    })
+    const { result } = renderHook(() => useSearchInputs(history))
+
+    expect(result.current.text).toBe("algebra")
+    expect(result.current.searchParams.text).toBe("algebra")
+
+    act(() => result.current.clearText())
+    expect(result.current.text).toBe("")
+    expect(result.current.searchParams.text).toBe("")
+  })
+
+  test("updateSort updates sort and sets text -> searchParams.text", () => {
+    const history = createMemoryHistory()
+    const { result } = renderHook(() => useSearchInputs(history))
+
+    act(() => result.current.setText("algebra"))
+
+    expect(result.current.searchParams.sort).toBe(null)
+    expect(result.current.searchParams.text).toBe("")
+
+    act(() => {
+      result.current.updateSort({ target: { value: "-title" } })
+    })
+    expect(result.current.searchParams.sort).toEqual({
+      field:  "title",
+      option: "desc"
+    })
+    expect(result.current.searchParams.text).toBe("algebra")
+  })
+
+  test("updateUI updates ui and sets text -> searchParams.text", () => {
+    const history = createMemoryHistory()
+    const { result } = renderHook(() => useSearchInputs(history))
+
+    act(() => result.current.setText("algebra"))
+
+    expect(result.current.searchParams.sort).toBe(null)
+    expect(result.current.searchParams.text).toBe("")
+
+    act(() => {
+      result.current.updateUI("list")
+    })
+    expect(result.current.searchParams.ui).toBe("list")
+    expect(result.current.searchParams.text).toBe("algebra")
+  })
+})
+
+describe("useSyncUrlAndSearch", () => {
+  const setupHook = (initialEntries?: InitialEntry[]) => {
+    const history = createMemoryHistory({ initialEntries })
+    const all = renderHook(() => {
+      const search = useSearchInputs(history)
+      useSyncUrlAndSearch(history, search)
+      return search
+    })
+    return [all, history] as const
+  }
+
+  it("syncs searchParams to url", async () => {
+    const [{ result }, history] = setupHook(["/search"])
+
+    expect(history.index).toBe(0)
+    act(() => {
+      result.current.setText("algebra")
+      result.current.toggleFacet("topics", "math", true)
+      result.current.submitText()
+    })
+
+    act(() => {
+      result.current.setText("linear algebra")
+    })
+
+    expect(result.current.searchParams.text).toBe("algebra")
+    expect(result.current.text).toBe("linear algebra") // not submitted yet
+
+    expect(history.location).toEqual(
+      expect.objectContaining({
+        pathname: "/search",
+        search:   "?q=algebra&t=math"
+      })
+    )
+    expect(history.index).toBe(1)
+  })
+
+  it("syncs empty search parameters to URL correctly", () => {
+    const [{ result }, history] = setupHook(["/search?q=algebra"])
+    act(() => {
+      result.current.clearText()
+    })
+    expect(history.location).toEqual(
+      expect.objectContaining({
+        pathname: "/search",
+        search:   ""
+      })
+    )
+  })
+
+  it("syncs url to searchParams", async () => {
+    const [{ result }, history] = setupHook([
+      `?${serializeSearchParams({
+        text:         "algebra",
+        activeFacets: { topics: ["math"] }
+      })}`
+    ])
+
+    act(() => {
+      result.current.clearAllFilters()
+    })
+
+    expect(result.current.searchParams.text).toBe("")
+    expect(history.location.search).toBe("")
+
+    act(() => history.go(-1))
+
+    expect(history.location.search).toBe("?q=algebra&t=math")
+    expect(result.current.searchParams.text).toBe("algebra")
+    expect(result.current.searchParams.activeFacets.topics).toEqual(["math"])
+  })
+})
diff --git a/src/index.ts b/src/index.ts
index 105ef8c..3e8842e 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -3,7 +3,8 @@ import React, {
   useCallback,
   useEffect,
   MouseEvent,
-  ChangeEvent
+  useMemo,
+  useRef
 } from "react"
 import { unionWith, eqBy, prop, clone } from "ramda"
 import _ from "lodash"
@@ -20,9 +21,10 @@ import {
   deserializeSearchParams,
   deserializeSort,
   serializeSearchParams,
-  SortParam
+  SortParam,
+  SearchParams
 } from "./url_utils"
-import { useDidMountEffect } from "./hooks"
+import { useEffectAfterMount } from "./hooks"
 
 export * from "./constants"
 
@@ -70,72 +72,13 @@ const history4or5Listen = (
   })
 }
 
-interface PreventableEvent {
-  preventDefault?: () => void
-  type?: string
-}
-interface CourseSearchResult {
-  facetOptions: (group: string) => Aggregation | null
-  clearAllFilters: () => void
-  toggleFacet: (name: string, value: string, isEnbaled: boolean) => void
-  toggleFacets: (facets: [string, string, boolean][]) => void
-  onUpdateFacets: React.ChangeEventHandler<HTMLInputElement>
-  updateText: React.ChangeEventHandler<HTMLInputElement>
-  clearText: React.MouseEventHandler
-  updateSort: React.ChangeEventHandler
-  acceptSuggestion: (suggestion: string) => void
-  loadMore: () => void
-  incremental: boolean
-  text: string
-  sort: SortParam | null
-  activeFacets: Facets
-  /**
-   * Callback that handles search submission. Pass this to your search input
-   * submission event target, e.g., `<form onSubmit={onSubmit} />` or
-   * `<button onClick={onSubmit} />`.
-   *
-   * The event target does not need to emit submit events, but if it does, the
-   * default form action will be prevented.
-   */
-  onSubmit: (e: PreventableEvent) => void
-  from: number
-  updateUI: (newUI: string | null) => void
-  ui: string | null
-}
-
-export const useCourseSearch = (
-  runSearch: (
-    text: string,
-    searchFacets: Facets,
-    nextFrom: number,
-    sort?: SortParam | null,
-    ui?: string | null
-  ) => Promise<void>,
-  clearSearch: () => void,
+export const useFacetOptions = (
   aggregations: Aggregations,
-  loaded: boolean,
-  searchPageSize: number | GetSearchPageSize,
-  history: HHistory
-): CourseSearchResult => {
-  const [incremental, setIncremental] = useState(false)
-  const [from, setFrom] = useState(0)
-  const [text, setText] = useState<string>(() => {
-    const { text } = deserializeSearchParams(history.location)
-    return text
-  })
-  const [activeFacetsAndSort, setActiveFacetsAndSort] = useState<FacetsAndSort>(
-    () => {
-      const { activeFacets, sort, ui } = deserializeSearchParams(
-        history.location
-      )
-      return { activeFacets, sort, ui }
-    }
-  )
-
-  const facetOptions = useCallback(
-    (group: string): Aggregation | null => {
+  activeFacets: Facets
+): ((group: string) => Aggregation | null) => {
+  return useCallback(
+    (group: string) => {
       const emptyFacet = { buckets: [] }
-      const { activeFacets } = activeFacetsAndSort
       const emptyActiveFacets = {
         buckets: (activeFacets[group] || []).map((facet: string) => ({
           key:       facet,
@@ -152,56 +95,173 @@ export const useCourseSearch = (
         emptyActiveFacets
       )
     },
-    [aggregations, activeFacetsAndSort]
+    [aggregations, activeFacets]
   )
+}
+
+type UseSearchInputsResult = {
+  /**
+   * Parameters to be used for a search query.
+   *
+   * Typically, these are the parameters of the previous search query. Thus,
+   * `searchParams.text` may be different from `text` if the has typed new text
+   * without submitting the search.
+   */
+  searchParams: SearchParams
+  setSearchParams: React.Dispatch<React.SetStateAction<SearchParams>>
+  /**
+   * `text` displayed in the UI.
+   *
+   * May be different from `searchParams.text` if user has typed new text
+   * without submitting the search.
+   */
+  text: string
+  setText: (text: string) => void
+  /**
+   * Reset `searchParams` and `text`.
+   */
+  clearAllFilters: () => void
+  /**
+   * Toggle a single facet; also sets text -> searchParams.text.
+   */
+  toggleFacet: (name: string, value: string, isEnbaled: boolean) => void
+  /**
+   * Toggle multiple facets; also sets text -> searchParams.text.
+   */
+  toggleFacets: (facets: [string, string, boolean][]) => void
+  /**
+   * Event handler for toggling a single facet; also sets text -> searchParams.text.
+   */
+  onUpdateFacet: ({
+    target
+  }: {
+    target: Pick<HTMLInputElement, "value" | "checked" | "name">
+  }) => void
+  /**
+   * Input handler for updating `text` (des NOT update `searchParams.text`).
+   */
+  updateText: (event: { target: { value: string } }) => void
+  /**
+   * Event handler for clearing `text`; also clears searchParams.text.
+   */
+  clearText: () => void
+  /**
+   * Event handler for updating `searchParams.sort`; also sets text -> searchParams.text.
+   */
+  updateSort: (event: { target: { value: string } }) => void
+  /**
+   * Updates `searchParams.sort`; also sets text -> searchParams.text.
+   */
+  updateUI: (newUI: string | null) => void
+  /**
+   * Set `searchParams.text` to the current value of `text`.
+   */
+  submitText: () => void
+}
+
+/**
+ * Provides state and event handlers for learning resources search UI; state
+ * includes data for facets, query text, sort order, ui variant (e.g.,
+ * 'compact').
+ *
+ * Note that there are two different state values for search text, `text` and
+ * `searchParams.text`. In the typical setup:
+ *  - `text` represents the text currently displayed in the UI and updates
+ *    frequently (e.g., on every keypress).
+ *  - `searchParams.text` represents the text used for the currently displayed
+ *     search results and updates less often (e.g., when a user presses "submit"
+ *     or on debounced keypresses).
+ *
+ * The provided event handlers for updating other search parameters (sort, ui,
+ * facets) sync `text` -> `searchParams.text`.
+ */
+export const useSearchInputs = (history: HHistory): UseSearchInputsResult => {
+  const [searchParamsInternal, setSearchParams] = useState<SearchParams>(() =>
+    deserializeSearchParams(history.location)
+  )
+
+  const searchParams = useMemo(() => {
+    return searchParamsInternal
+    // This is intentional: let's maintain referential equality when
+    // serialization is the same.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [serializeSearchParams(searchParamsInternal)])
+
+  /**
+   * Store text in state + ref. State for re-renders, and ref for render-stable
+   * callbacks.
+   */
+  const textRef = useRef(searchParamsInternal.text)
+  const [text, setTextState] = useState(searchParamsInternal.text)
+  const setText = useCallback((val: string) => {
+    setTextState(val)
+    textRef.current = val
+  }, [])
 
   const clearAllFilters = useCallback(() => {
-    setText("")
-    setActiveFacetsAndSort({
-      activeFacets: INITIAL_FACET_STATE,
+    setSearchParams({
+      text:         "",
       sort:         null,
-      ui:           null
+      ui:           null,
+      activeFacets: INITIAL_FACET_STATE
     })
-  }, [setText, setActiveFacetsAndSort])
+    setText("")
+  }, [setText])
 
-  const toggleFacet: CourseSearchResult["toggleFacet"] = useCallback(
+  const toggleFacet: UseSearchInputsResult["toggleFacet"] = useCallback(
     (name, value, isEnabled) => {
-      const { activeFacets, sort, ui } = activeFacetsAndSort
-      const newFacets = clone(activeFacets)
-
-      if (isEnabled) {
-        newFacets[name] = _.union(newFacets[name] || [], [value])
-      } else {
-        newFacets[name] = _.without(newFacets[name] || [], value)
-      }
-      setActiveFacetsAndSort({ activeFacets: newFacets, sort, ui })
-    },
-    [activeFacetsAndSort, setActiveFacetsAndSort]
-  )
+      setSearchParams(current => {
+        const { activeFacets, sort, ui } = current
+        const newFacets = clone(activeFacets)
 
-  const toggleFacets: CourseSearchResult["toggleFacets"] = useCallback(
-    facets => {
-      const { activeFacets, sort, ui } = activeFacetsAndSort
-      const newFacets = clone(activeFacets)
-
-      facets.forEach(([name, value, isEnabled]) => {
         if (isEnabled) {
           newFacets[name] = _.union(newFacets[name] || [], [value])
         } else {
           newFacets[name] = _.without(newFacets[name] || [], value)
         }
+        return {
+          ...current,
+          activeFacets: newFacets,
+          sort,
+          ui,
+          text:         textRef.current
+        }
       })
-      setActiveFacetsAndSort({ activeFacets: newFacets, sort, ui })
     },
-    [activeFacetsAndSort, setActiveFacetsAndSort]
+    []
   )
 
-  const onUpdateFacets: CourseSearchResult["onUpdateFacets"] = useCallback(
+  const toggleFacets: UseSearchInputsResult["toggleFacets"] = useCallback(
+    facets => {
+      setSearchParams(current => {
+        const { activeFacets, sort, ui } = current
+        const newFacets = clone(activeFacets)
+
+        facets.forEach(([name, value, isEnabled]) => {
+          if (isEnabled) {
+            newFacets[name] = _.union(newFacets[name] || [], [value])
+          } else {
+            newFacets[name] = _.without(newFacets[name] || [], value)
+          }
+        })
+        return {
+          ...current,
+          activeFacets: newFacets,
+          sort,
+          ui,
+          text:         textRef.current
+        }
+      })
+    },
+    []
+  )
+
+  const onUpdateFacet: UseSearchInputsResult["onUpdateFacet"] = useCallback(
     e => toggleFacet(e.target.name, e.target.value, e.target.checked),
     [toggleFacet]
   )
 
-  const updateText: CourseSearchResult["updateText"] = useCallback(
+  const updateText: UseSearchInputsResult["updateText"] = useCallback(
     event => {
       const text = event ? event.target.value : ""
       setText(text)
@@ -209,23 +269,174 @@ export const useCourseSearch = (
     [setText]
   )
 
-  const updateSort = useCallback(
-    (event: ChangeEvent): void => {
+  const updateSort: UseSearchInputsResult["updateSort"] = useCallback(
+    (event): void => {
       const param = event ? (event.target as HTMLSelectElement).value : ""
       const newSort = deserializeSort(param)
-      const { activeFacets, ui } = activeFacetsAndSort
-      setActiveFacetsAndSort({ activeFacets, sort: newSort, ui: ui }) // this will cause a search via useDidMountEffect
+      setSearchParams(current => ({
+        ...current,
+        sort: newSort,
+        text: textRef.current
+      }))
     },
-    [setActiveFacetsAndSort, activeFacetsAndSort]
+    []
   )
 
-  const updateUI = useCallback(
-    (newUI: string | null): void => {
-      const { activeFacets, sort } = activeFacetsAndSort
-      setActiveFacetsAndSort({ activeFacets, sort, ui: newUI }) // this will cause a search via useDidMountEffect
-    },
-    [setActiveFacetsAndSort, activeFacetsAndSort]
+  const updateUI = useCallback((newUI: string | null): void => {
+    setSearchParams(current => ({
+      ...current,
+      ui:   newUI,
+      text: textRef.current
+    }))
+  }, [])
+
+  const clearText = useCallback(() => {
+    setText("")
+    setSearchParams(current => ({ ...current, text: "" }))
+  }, [setText, setSearchParams])
+
+  const submitText = useCallback(() => {
+    setSearchParams(current => ({
+      ...current,
+      text: textRef.current
+    }))
+  }, [])
+
+  return {
+    searchParams,
+    setSearchParams,
+    text,
+    setText,
+    clearAllFilters,
+    toggleFacet,
+    toggleFacets,
+    onUpdateFacet,
+    updateText,
+    updateSort,
+    clearText,
+    updateUI,
+    submitText
+  }
+}
+
+const setLocation = (history: HHistory, searchParams: SearchParams) => {
+  const currentSearch = serializeSearchParams(
+    deserializeSearchParams(history.location)
   )
+  const { activeFacets, sort, ui, text } = searchParams
+  const newSearch = serializeSearchParams({
+    text,
+    activeFacets,
+    sort,
+    ui
+  })
+  if (currentSearch !== newSearch) {
+    const prefix = newSearch ? "?" : ""
+    history.push({
+      search: `${prefix}${newSearch}`
+    })
+  }
+}
+
+/**
+ * Sync changes to URL search parameters with `searchParams`, and vice versa.
+ *
+ * Pushes a new entry to the history stack every time the URL would change.
+ */
+export const useSyncUrlAndSearch = (
+  history: HHistory,
+  {
+    searchParams,
+    setSearchParams,
+    setText
+  }: Pick<UseSearchInputsResult, "searchParams" | "setSearchParams" | "setText">
+) => {
+  // sync URL to search
+  useEffect(() => {
+    const unlisten = history4or5Listen(history, location => {
+      const { activeFacets, sort, ui, text } = deserializeSearchParams(location)
+      setSearchParams({ activeFacets, sort, ui, text })
+      setText(text)
+    })
+    return unlisten
+  }, [history, setSearchParams, setText])
+
+  useEffect(() => {
+    setLocation(history, searchParams)
+  }, [history, searchParams])
+}
+
+interface PreventableEvent {
+  preventDefault?: () => void
+  type?: string
+}
+interface CourseSearchResult {
+  facetOptions: (group: string) => Aggregation | null
+  clearAllFilters: UseSearchInputsResult["clearAllFilters"]
+  toggleFacet: UseSearchInputsResult["toggleFacet"]
+  toggleFacets: UseSearchInputsResult["toggleFacets"]
+  onUpdateFacets: UseSearchInputsResult["onUpdateFacet"]
+  updateText: UseSearchInputsResult["updateText"]
+  clearText: React.MouseEventHandler
+  updateSort: UseSearchInputsResult["updateSort"]
+  acceptSuggestion: (suggestion: string) => void
+  loadMore: () => void
+  incremental: boolean
+  text: string
+  sort: SortParam | null
+  activeFacets: Facets
+  /**
+   * Callback that handles search submission. Pass this to your search input
+   * submission event target, e.g., `<form onSubmit={onSubmit} />` or
+   * `<button onClick={onSubmit} />`.
+   *
+   * The event target does not need to emit submit events, but if it does, the
+   * default form action will be prevented.
+   */
+  onSubmit: (e: PreventableEvent) => void
+  from: number
+  updateUI: (newUI: string | null) => void
+  ui: string | null
+}
+
+export const useCourseSearch = (
+  runSearch: (
+    text: string,
+    searchFacets: Facets,
+    nextFrom: number,
+    sort?: SortParam | null,
+    ui?: string | null
+  ) => Promise<void>,
+  clearSearch: () => void,
+  aggregations: Aggregations,
+  loaded: boolean,
+  searchPageSize: number | GetSearchPageSize,
+  history: HHistory
+): CourseSearchResult => {
+  const [incremental, setIncremental] = useState(false)
+  const [from, setFrom] = useState(0)
+
+  const seachUI = useSearchInputs(history)
+  const {
+    searchParams,
+    setSearchParams,
+    text,
+    setText,
+    clearAllFilters,
+    toggleFacet,
+    toggleFacets,
+    onUpdateFacet: onUpdateFacets,
+    updateText,
+    updateSort,
+    updateUI
+  } = seachUI
+  const { activeFacets, sort, ui } = searchParams
+  const activeFacetsAndSort = useMemo(() => ({ activeFacets, sort, ui }), [
+    activeFacets,
+    sort,
+    ui
+  ])
+  const facetOptions = useFacetOptions(aggregations, activeFacets)
 
   const internalRunSearch = useCallback(
     async (
@@ -263,19 +474,7 @@ export const useCourseSearch = (
 
       await runSearch(text, searchFacets, nextFrom, sort, ui)
 
-      // search is updated, now echo params to URL bar
-      const currentSearch = serializeSearchParams(
-        deserializeSearchParams(history.location)
-      )
-      const newSearch = serializeSearchParams({
-        text,
-        activeFacets,
-        sort,
-        ui
-      })
-      if (currentSearch !== newSearch) {
-        history.push(`?${newSearch}`)
-      }
+      setLocation(history, { text, activeFacets, sort, ui })
     },
     [
       from,
@@ -293,9 +492,9 @@ export const useCourseSearch = (
       const { text, activeFacets, sort, ui } = deserializeSearchParams(location)
       clearSearch()
       setText(text)
-      setActiveFacetsAndSort({ activeFacets, sort, ui })
+      setSearchParams(current => ({ ...current, activeFacets, sort, ui }))
     },
-    [clearSearch, setText, setActiveFacetsAndSort]
+    [clearSearch, setText, setSearchParams]
   )
 
   const clearText = useCallback(
@@ -357,7 +556,7 @@ export const useCourseSearch = (
   // facet-related callbacks (toggleFacet, etc) be dependent on then value of
   // the runSearch function, which leads to too much needless churn in the
   // facet callbacks and then causes excessive re-rendering of the facet UI
-  useDidMountEffect(() => {
+  useEffectAfterMount(() => {
     internalRunSearch(text, activeFacetsAndSort)
   }, [activeFacetsAndSort])
 
@@ -372,7 +571,6 @@ export const useCourseSearch = (
     [internalRunSearch, text, activeFacetsAndSort]
   )
 
-  const { sort, activeFacets, ui } = activeFacetsAndSort
   return {
     facetOptions,
     clearAllFilters,
diff --git a/src/url_utils.ts b/src/url_utils.ts
index 3ce027b..4c00e08 100644
--- a/src/url_utils.ts
+++ b/src/url_utils.ts
@@ -34,7 +34,7 @@ export interface FacetsAndSort {
   ui: string | null
 }
 
-type SearchParams = {
+export type SearchParams = {
   text: string
   activeFacets: Facets
   sort: SortParam | null
@@ -142,8 +142,12 @@ export const serializeSearchParams = ({
     department_name,
     level,
     course_feature_tags,
-    resource_type
+    resource_type,
+    ...others
   } = activeFacets ?? {}
+  if (Object.keys(others).length > 0) {
+    console.warn("Unrecognized facets:", others)
+  }
 
   return qs.stringify({
     q: text || undefined,
diff --git a/yarn.lock b/yarn.lock
index 7ffdbee..434ec60 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -272,6 +272,13 @@
   dependencies:
     regenerator-runtime "^0.13.4"
 
+"@babel/runtime@^7.12.5":
+  version "7.21.0"
+  resolved "https://registry.yarnpkg.com/@babel/runtime/-/runtime-7.21.0.tgz#5b55c9d394e5fcf304909a8b00c07dc217b56673"
+  integrity sha512-xwII0//EObnq89Ji5AKYQaRYiW/nZ3llSv29d49IuxPhKbtJoLP+9QUUZ4nVragQVtaVGeZrpB+ZtG/Pdy/POw==
+  dependencies:
+    regenerator-runtime "^0.13.11"
+
 "@babel/template@^7.18.10", "@babel/template@^7.3.3":
   version "7.18.10"
   resolved "https://registry.npmjs.org/@babel/template/-/template-7.18.10.tgz"
@@ -775,6 +782,14 @@
   resolved "https://registry.yarnpkg.com/@swc/wasm/-/wasm-1.2.130.tgz#88ac26433335d1f957162a9a92f1450b73c176a0"
   integrity sha512-rNcJsBxS70+pv8YUWwf5fRlWX6JoY/HJc25HD/F8m6Kv7XhJdqPPMhyX6TKkUBPAG7TWlZYoxa+rHAjPy4Cj3Q==
 
+"@testing-library/react-hooks@^8.0.1":
+  version "8.0.1"
+  resolved "https://registry.yarnpkg.com/@testing-library/react-hooks/-/react-hooks-8.0.1.tgz#0924bbd5b55e0c0c0502d1754657ada66947ca12"
+  integrity sha512-Aqhl2IVmLt8IovEVarNDFuJDVWVvhnr9/GCU6UUnrYXwgDFF9h2L2o2P9KBni1AST5sT6riAyoukFLyjQUgD/g==
+  dependencies:
+    "@babel/runtime" "^7.12.5"
+    react-error-boundary "^3.1.0"
+
 "@tootallnate/once@2":
   version "2.0.0"
   resolved "https://registry.npmjs.org/@tootallnate/once/-/once-2.0.0.tgz"
@@ -4143,6 +4158,13 @@ react-dom@^16.13.1:
     prop-types "^15.6.2"
     scheduler "^0.19.1"
 
+react-error-boundary@^3.1.0:
+  version "3.1.4"
+  resolved "https://registry.yarnpkg.com/react-error-boundary/-/react-error-boundary-3.1.4.tgz#255db92b23197108757a888b01e5b729919abde0"
+  integrity sha512-uM9uPzZJTF6wRQORmSrvOIgt4lJ9MC1sNgEOj2XGsDTRE4kmpWxg7ENK9EWNKJRMAOY9z0MuF4yIfl6gp4sotA==
+  dependencies:
+    "@babel/runtime" "^7.12.5"
+
 react-is@^16.13.1, react-is@^16.8.1, react-is@^16.8.6:
   version "16.13.1"
   resolved "https://registry.npmjs.org/react-is/-/react-is-16.13.1.tgz"
@@ -4186,6 +4208,11 @@ reflect.ownkeys@^0.2.0:
   resolved "https://registry.npmjs.org/reflect.ownkeys/-/reflect.ownkeys-0.2.0.tgz"
   integrity "sha1-dJrO7H8/34tj+SegSAnpDFwLNGA= sha512-qOLsBKHCpSOFKK1NUOCGC5VyeufB6lEsFe92AL2bhIJsacZS1qdoOZSbPk3MYKuT2cFlRDnulKXuuElIrMjGUg=="
 
+regenerator-runtime@^0.13.11:
+  version "0.13.11"
+  resolved "https://registry.yarnpkg.com/regenerator-runtime/-/regenerator-runtime-0.13.11.tgz#f6dca3e7ceec20590d07ada785636a90cdca17f9"
+  integrity sha512-kY1AZVr2Ra+t+piVaJ4gxaFaReZVH40AKNo7UCX6W+dEwBo/2oZJzqfuN1qLq1oL45o56cPaTXELwrTh8Fpggg==
+
 regenerator-runtime@^0.13.4:
   version "0.13.7"
   resolved "https://registry.npmjs.org/regenerator-runtime/-/regenerator-runtime-0.13.7.tgz"