Update: [AEA-5328] - Adds back go back button functionality (#1315)

## Summary
✨ New Feature

### Details
Added "go back" link functionality to fix an accessibility audit issue
and make navigation more consistent across the Prescription Tracker UI

#### What’s new:
- `NavigationProvider` – keeps track of history + search params
- `useBackNavigation` hook – centralised back nav logic
- `EpsBackLink` component – reusable, accessible back link
- Smart routing:
a. behaves like normal browser back in standard flows
b. preserves search context (e.g. list → results → patient search)
c. treats search list tabs as a single page (avoids polluting history)
d. context-aware: if navigating from a future-dated list → details,
“Back” takes you to the same list, not current prescriptions

#### Other improvements:
- Keeps original search params when going back
- Better breadcrumb behaviour across entry points (basic details, NHS
number, prescription ID)
- WCAG fix: back link now sits outside `<main>`
- changes `"Go Back"` strings to `"Back"`

---------

Signed-off-by: Bence Gadanyi <[email protected]>
Co-authored-by: Jonno <[email protected]>
Co-authored-by: MatthewPopat-NHS <[email protected]>
Co-authored-by: jonathanwelch1-nhs <[email protected]>

Author: 3 people

packages/cpt-ui/__tests__/BasicDetailsSearch.test.tsx

@@ -21,6 +21,7 @@ import {STRINGS} from "@/constants/ui-strings/BasicDetailsSearchStrings"
 import {FRONTEND_PATHS} from "@/constants/environment"
 import {AuthContext, AuthContextType} from "@/context/AuthProvider"
 import {SearchContext, SearchProviderContextType} from "@/context/SearchProvider"
+import {NavigationProvider} from "@/context/NavigationProvider"
 
 jest.mock("react-router-dom", () => {
   const actual = jest.requireActual("react-router-dom")
@@ -68,10 +69,12 @@ const mockSetLastName = jest.fn()
 const mockSetDobDay = jest.fn()
 const mockSetDobMonth = jest.fn()
 const mockSetDobYear = jest.fn()
-const mockSetPostcode =jest.fn()
+const mockSetPostcode = jest.fn()
 const mockSetNhsNumber = jest.fn()
 const mockGetAllSearchParameters = jest.fn()
 const mockSetAllSearchParameters = jest.fn()
+const mockSetSearchType = jest.fn()
+
 const defaultSearchState: SearchProviderContextType = {
   prescriptionId: undefined,
   issueNumber: undefined,
@@ -82,6 +85,7 @@ const defaultSearchState: SearchProviderContextType = {
   dobYear: undefined,
   postcode: undefined,
   nhsNumber: undefined,
+  searchType: undefined,
   clearSearchParameters: mockClearSearchParameters,
   setPrescriptionId: mockSetPrescriptionId,
   setIssueNumber: mockSetIssueNumber,
@@ -93,7 +97,8 @@ const defaultSearchState: SearchProviderContextType = {
   setPostcode: mockSetPostcode,
   setNhsNumber: mockSetNhsNumber,
   getAllSearchParameters: mockGetAllSearchParameters,
-  setAllSearchParameters: mockSetAllSearchParameters
+  setAllSearchParameters: mockSetAllSearchParameters,
+  setSearchType: mockSetSearchType
 }
 
 const LocationDisplay = () => {
@@ -106,10 +111,12 @@ const renderWithRouter = (ui: React.ReactElement, searchState: SearchProviderCon
     <AuthContext.Provider value={signedInAuthState}>
       <SearchContext.Provider value={searchState}>
         <MemoryRouter initialEntries={["/search"]}>
-          <Routes>
-            <Route path="/search" element={ui} />
-            <Route path="*" element={<LocationDisplay />} />
-          </Routes>
+          <NavigationProvider>
+            <Routes>
+              <Route path="/search" element={ui} />
+              <Route path="*" element={<LocationDisplay />} />
+            </Routes>
+          </NavigationProvider>
         </MemoryRouter>
       </SearchContext.Provider>
     </AuthContext.Provider>

packages/cpt-ui/__tests__/BasicDetailsSearchResultsPage.test.tsx

@@ -11,12 +11,37 @@ import {SearchResultsPageStrings} from "@/constants/ui-strings/BasicDetailsSearc
 import http from "@/helpers/axios"
 import {AuthContext, type AuthContextType} from "@/context/AuthProvider"
 import {SearchContext, SearchProviderContextType} from "@/context/SearchProvider"
+import {NavigationProvider} from "@/context/NavigationProvider"
 import {AxiosError, AxiosHeaders} from "axios"
 
 // Mock the axios module
 jest.mock("@/helpers/axios")
 const mockAxiosGet = http.get as jest.MockedFunction<typeof http.get>
 
+const mockGetRelevantSearchParameters = jest.fn()
+const mockGetBackPath = jest.fn()
+const mockGoBack = jest.fn()
+const mockNavigationContext = {
+  pushNavigation: jest.fn(),
+  goBack: mockGoBack,
+  getBackPath: mockGetBackPath,
+  clearNavigation: jest.fn(),
+  getCurrentEntry: jest.fn(),
+  getNavigationStack: jest.fn(),
+  canGoBack: jest.fn(),
+  setOriginalSearchPage: jest.fn(),
+  getOriginalSearchPage: jest.fn(),
+  captureOriginalSearchParameters: jest.fn(),
+  getOriginalSearchParameters: jest.fn(),
+  getRelevantSearchParameters: mockGetRelevantSearchParameters,
+  startNewNavigationSession: jest.fn()
+}
+
+jest.mock("@/context/NavigationProvider", () => ({
+  ...jest.requireActual("@/context/NavigationProvider"),
+  useNavigationContext: () => mockNavigationContext
+}))
+
 const mockAuthContext: AuthContextType = {
   error: null,
   user: null,
@@ -49,7 +74,7 @@ const mockSetLastName = jest.fn()
 const mockSetDobDay = jest.fn()
 const mockSetDobMonth = jest.fn()
 const mockSetDobYear = jest.fn()
-const mockSetPostcode =jest.fn()
+const mockSetPostcode = jest.fn()
 const mockSetNhsNumber = jest.fn()
 const mockGetAllSearchParameters = jest.fn()
 const mockSetAllSearchParameters = jest.fn()
@@ -63,6 +88,7 @@ const defaultSearchState: SearchProviderContextType = {
   dobYear: undefined,
   postcode: undefined,
   nhsNumber: undefined,
+  searchType: undefined,
   clearSearchParameters: mockClearSearchParameters,
   setPrescriptionId: mockSetPrescriptionId,
   setIssueNumber: mockSetIssueNumber,
@@ -73,6 +99,7 @@ const defaultSearchState: SearchProviderContextType = {
   setDobYear: mockSetDobYear,
   setPostcode: mockSetPostcode,
   setNhsNumber: mockSetNhsNumber,
+  setSearchType: jest.fn(),
   getAllSearchParameters: mockGetAllSearchParameters,
   setAllSearchParameters: mockSetAllSearchParameters
 }
@@ -96,17 +123,20 @@ const mockPatients = [
   }
 ]
 
-function renderWithRouter() {
+function renderWithRouter(initialEntries = ["/patient-search-results"]) {
   return render(
     <AuthContext.Provider value={mockAuthContext}>
       <SearchContext.Provider value={defaultSearchState}>
-        <MemoryRouter initialEntries={["/patient-search-results"]}>
-          <Routes>
-            <Route path="/patient-search-results" element={<BasicDetailsSearchResultsPage />} />
-            <Route path="/login" element={<div data-testid="login-page-shown" />} />
-            <Route path="/prescription-list-current" element={<div data-testid="prescription-list-shown" />} />
-            <Route path="/search-by-basic-details" element={<div data-testid="search-page-shown" />} />
-          </Routes>
+        <MemoryRouter initialEntries={initialEntries}>
+          <NavigationProvider>
+            <Routes>
+              <Route path="/patient-search-results" element={<BasicDetailsSearchResultsPage />} />
+              <Route path="/login" element={<div data-testid="login-page-shown" />} />
+              <Route path="/prescription-list-current" element={<div data-testid="prescription-list-shown" />} />
+              <Route path="/search-by-basic-details" element={<div data-testid="search-page-shown" />} />
+              <Route path="/search-by-prescription-id" element={<div data-testid="search-page-shown" />} />
+            </Routes>
+          </NavigationProvider>
         </MemoryRouter>
       </SearchContext.Provider>
     </AuthContext.Provider>
@@ -115,11 +145,24 @@ function renderWithRouter() {
 
 describe("BasicDetailsSearchResultsPage", () => {
   beforeEach(() => {
+    jest.clearAllMocks()
+
     // Mock successful API response
     mockAxiosGet.mockResolvedValue({
       status: 200,
       data: mockPatients
     })
+
+    mockGetRelevantSearchParameters.mockReturnValue({
+      firstName: "John",
+      lastName: "Doe",
+      dobDay: "01",
+      dobMonth: "01",
+      dobYear: "1990",
+      postcode: "SW1A 1AA"
+    })
+
+    mockGetBackPath.mockReturnValue("/search-by-basic-details")
   })
 
   it("shows loading state initially", () => {
@@ -201,20 +244,42 @@ describe("BasicDetailsSearchResultsPage", () => {
 
     await waitFor(() => {
       expect(screen.getByTestId("prescription-list-shown")).toBeInTheDocument()
-      expect(mockClearSearchParameters).toHaveBeenCalled()
-      expect(mockSetNhsNumber).toHaveBeenCalledWith("9726919207")
+      expect(mockGetRelevantSearchParameters).toHaveBeenCalledWith(
+        "basicDetails"
+      )
+      expect(mockSetAllSearchParameters).toHaveBeenCalledWith({
+        firstName: "John",
+        lastName: "Doe",
+        dobDay: "01",
+        dobMonth: "01",
+        dobYear: "1990",
+        postcode: "SW1A 1AA",
+        nhsNumber: "9726919207"
+      })
     })
   })
 
   it("navigates to prescription list when clicking a patient row", async () => {
     renderWithRouter()
     await waitFor(() => {
-      const firstPatientRow = screen.getByText("Issac Wolderton-Rodriguez").closest("tr")
+      const firstPatientRow = screen
+        .getByText("Issac Wolderton-Rodriguez")
+        .closest("tr")
       fireEvent.click(firstPatientRow!)
 
       expect(screen.getByTestId("prescription-list-shown")).toBeInTheDocument()
-      expect(mockClearSearchParameters).toHaveBeenCalled()
-      expect(mockSetNhsNumber).toHaveBeenCalledWith("9726919207")
+      expect(mockGetRelevantSearchParameters).toHaveBeenCalledWith(
+        "basicDetails"
+      )
+      expect(mockSetAllSearchParameters).toHaveBeenCalledWith({
+        firstName: "John",
+        lastName: "Doe",
+        dobDay: "01",
+        dobMonth: "01",
+        dobYear: "1990",
+        postcode: "SW1A 1AA",
+        nhsNumber: "9726919207"
+      })
     })
   })
 
@@ -226,20 +291,35 @@ describe("BasicDetailsSearchResultsPage", () => {
       fireEvent.click(patientNameLink)
 
       expect(screen.getByTestId("prescription-list-shown")).toBeInTheDocument()
-      expect(mockClearSearchParameters).toHaveBeenCalled()
-      expect(mockSetNhsNumber).toHaveBeenCalledWith("9726919207")
+      expect(mockGetRelevantSearchParameters).toHaveBeenCalledWith(
+        "basicDetails"
+      )
+      expect(mockSetAllSearchParameters).toHaveBeenCalledWith({
+        firstName: "John",
+        lastName: "Doe",
+        dobDay: "01",
+        dobMonth: "01",
+        dobYear: "1990",
+        postcode: "SW1A 1AA",
+        nhsNumber: "9726919207"
+      })
     })
   })
 
   it("navigates back when clicking the back link", async () => {
     renderWithRouter()
 
     await waitFor(() => {
-      const backLink = screen.getByText(SearchResultsPageStrings.GO_BACK)
-      fireEvent.click(backLink)
-
-      expect(screen.getByTestId("search-page-shown")).toBeInTheDocument()
+      expect(
+        screen.getByText(SearchResultsPageStrings.GO_BACK)
+      ).toBeInTheDocument()
     })
+
+    const backLink = screen.getByText(SearchResultsPageStrings.GO_BACK)
+    fireEvent.click(backLink)
+
+    expect(mockGoBack).toHaveBeenCalled()
+    expect(mockGetBackPath).toHaveBeenCalled()
   })
 
   it("handles enter key navigation for patient rows", async () => {
@@ -250,8 +330,18 @@ describe("BasicDetailsSearchResultsPage", () => {
       fireEvent.keyDown(firstPatientRow!, {key: "Enter"})
 
       expect(screen.getByTestId("prescription-list-shown")).toBeInTheDocument()
-      expect(mockClearSearchParameters).toHaveBeenCalled()
-      expect(mockSetNhsNumber).toHaveBeenCalledWith("9726919207")
+      expect(mockGetRelevantSearchParameters).toHaveBeenCalledWith(
+        "basicDetails"
+      )
+      expect(mockSetAllSearchParameters).toHaveBeenCalledWith({
+        firstName: "John",
+        lastName: "Doe",
+        dobDay: "01",
+        dobMonth: "01",
+        dobYear: "1990",
+        postcode: "SW1A 1AA",
+        nhsNumber: "9726919207"
+      })
     })
   })
 
@@ -263,8 +353,18 @@ describe("BasicDetailsSearchResultsPage", () => {
       fireEvent.keyDown(firstPatientRow!, {key: " "})
 
       expect(screen.getByTestId("prescription-list-shown")).toBeInTheDocument()
-      expect(mockClearSearchParameters).toHaveBeenCalled()
-      expect(mockSetNhsNumber).toHaveBeenCalledWith("9726919207")
+      expect(mockGetRelevantSearchParameters).toHaveBeenCalledWith(
+        "basicDetails"
+      )
+      expect(mockSetAllSearchParameters).toHaveBeenCalledWith({
+        firstName: "John",
+        lastName: "Doe",
+        dobDay: "01",
+        dobMonth: "01",
+        dobYear: "1990",
+        postcode: "SW1A 1AA",
+        nhsNumber: "9726919207"
+      })
     })
   })