CCM-15826: Add user claims popover and header navigation components; update navigation structure and related styles

Author: m-houston

frontend/.env.template

@@ -4,7 +4,9 @@ NEXT_PUBLIC_BASE_PATH=''
 # Optional local override for the backend API base URL.
 API_BASE_URL=''
 
-# Amplify / Cognito values used by `npm run create-amplify-outputs env`.
+# Amplify / Cognito values used to generate `frontend/amplify_outputs.json`
+# for local development. Frontend package scripts regenerate that file from
+# `.env` / `.env.local` before running.
 AWS_REGION=''
 USER_POOL_CLIENT_ID=''
 USER_POOL_ID=''

frontend/AGENTS.md

@@ -0,0 +1,75 @@
+# AGENTS.md
+<!-- vale off -->
+
+## Scope
+
+This file applies to work under `frontend/`.
+Follow the root `AGENTS.md` first, then use this file for frontend-specific guidance.
+
+## What this package is
+
+- A Next.js App Router frontend workspace.
+- Uses `nhsuk-frontend` Sass/CSS alongside React components and Amplify auth UI.
+- Package-local scripts live in `frontend/package.json` and are the source of truth for package verification.
+
+## Change guidance
+
+- Keep changes small and focused.
+- Prefer existing package entrypoints over deep imports when bringing in framework assets or styles.
+- Treat `.next/` as generated output; do not edit generated files.
+- If you change routing, auth, styles, Next config, ESLint config, or dependencies, run the full verification flow below.
+
+## Known fragile areas
+
+### Sass imports
+
+- `frontend/src/styles/app.scss` must import NHS styles from the package entrypoint:
+
+  ```scss
+  @use "nhsuk-frontend";
+  ```
+
+- Do not switch this back to a deep path such as `nhsuk-frontend/dist/nhsuk` unless you have verified that the installed package still resolves that path in this workspace.
+- After changing Sass imports or style tooling, run `npm run build --workspace frontend` from the repo root to catch stylesheet resolution problems.
+
+### App Router query params and auth pages
+
+- Build-time and prerender-sensitive routes should prefer resolving query params in the server `page.tsx` via `searchParams`, then passing plain props into client components.
+- Be careful when introducing `useSearchParams()` in client components used by prerendered routes such as `frontend/src/app/auth/page.tsx`; this can require a suspense boundary or cause build failures.
+- If you touch auth flow or redirect handling, test both the production build and a manual auth URL such as `/auth?redirect=%2F`.
+
+### ESLint and generated Next.js files
+
+- `frontend/.next/` must stay ignored by ESLint.
+- If you change `frontend/eslint.config.mjs`, verify that `.next/**` is still ignored and run lint after a build, not only before it.
+- A clean lint result before `next build` is not sufficient; generated `.next/types/**` files can reveal config regressions only after a build has run.
+
+## Required verification flow
+
+Run these commands from the repository root when making non-trivial changes in `frontend/`:
+
+```sh
+pre-commit run --config scripts/config/pre-commit.yaml
+rm -rf frontend/.next
+npm run build --workspace frontend
+npm run lint --workspace frontend
+npm run typecheck --workspace frontend
+npm run test:unit --workspace frontend
+```
+
+## Verification notes
+
+- Use the clean build step to surface Sass resolution and App Router prerender issues.
+- Keep the post-build lint step to catch accidental linting of generated `.next` artifacts.
+- `typecheck` and `test:unit` both create mock Amplify outputs automatically via package scripts; prefer the existing scripts over ad hoc commands.
+- If you change auth, routing, middleware, or base-path handling, add a quick manual browser check in development as an extra validation step.
+
+## Minimum review summary for frontend changes
+
+Include in your handoff or PR summary:
+
+- what changed in `frontend/`
+- why the change was needed
+- that the root pre-commit checks were run
+- that `build`, `lint`, `typecheck`, and `test:unit` were run for the frontend workspace
+- any manual route or auth checks you performed

frontend/eslint.config.mjs

@@ -11,7 +11,7 @@ export default defineConfig([
     },
   },
   {
-    ignores: ["jest.config.mjs"],
+    ignores: [".next/**", "jest.config.mjs", "next-env.d.ts"],
   },
   {
     files: ["next.config.js"],

frontend/jest.config.mjs

@@ -9,7 +9,7 @@ const config = {
   testEnvironment: "node",
   testPathIgnorePatterns: ["/node_modules/", ".next/"],
   transform: {
-    "^.+\\.(ts|tsx)$": ["ts-jest", { tsconfig: "<rootDir>/tsconfig.json" }],
+    "^.+\\.(ts|tsx)$": ["ts-jest", { tsconfig: "<rootDir>/tsconfig.jest.json" }],
   },
 };
 

frontend/next-env.d.ts

@@ -0,0 +1,6 @@
+/// <reference types="next" />
+/// <reference types="next/image-types/global" />
+/// <reference path="./.next/types/routes.d.ts" />
+
+// NOTE: This file should not be edited
+// see https://nextjs.org/docs/app/api-reference/config/typescript for more information.

frontend/package.json

@@ -28,14 +28,15 @@
   "name": "@supplier-config/frontend",
   "private": true,
   "scripts": {
-    "build": "next build",
-    "dev": "next dev",
-    "lint": "npm run mock-amplify-outputs && eslint .",
+    "build": "npm run sync-amplify-outputs && next build",
+    "dev": "npm run sync-amplify-outputs && next dev",
+    "lint": "npm run sync-amplify-outputs && eslint .",
     "lint:fix": "npm run lint -- --fix",
     "mock-amplify-outputs": "if [ ! -f ./amplify_outputs.json ]; then echo \"{}\" > ./amplify_outputs.json ; fi",
-    "start": "next start",
-    "test:unit": "npm run mock-amplify-outputs && jest --runInBand",
-    "typecheck": "npm run mock-amplify-outputs && tsc --noEmit"
+    "start": "npm run sync-amplify-outputs && next start",
+    "sync-amplify-outputs": "if [ -f ./.env ] || [ -f ./.env.local ]; then npm --prefix .. run create-amplify-outputs env; else npm run mock-amplify-outputs; fi",
+    "test:unit": "npm run sync-amplify-outputs && jest --runInBand",
+    "typecheck": "npm run sync-amplify-outputs && tsc --noEmit"
   },
   "version": "0.1.0"
 }

frontend/src/__tests__/navigation-links.test.ts

@@ -0,0 +1,50 @@
+import {
+  getNavigationLinkForPath,
+  getNavigationSectionForPath,
+  overviewNavigationLink,
+} from "@/components/navigation-links";
+
+describe("navigation-links", () => {
+  it("maps supplier pages to the Suppliers section", () => {
+    expect(getNavigationSectionForPath("/suppliers")?.label).toBe("Suppliers");
+    expect(getNavigationSectionForPath("/supplier-allocations")?.label).toBe(
+      "Suppliers",
+    );
+    expect(getNavigationSectionForPath("/volume-groups")?.label).toBe(
+      "Suppliers",
+    );
+  });
+
+  it("maps specification pages to the Specifications section", () => {
+    expect(getNavigationSectionForPath("/pack-specifications")?.label).toBe(
+      "Specifications",
+    );
+    expect(getNavigationSectionForPath("/postage")?.label).toBe(
+      "Specifications",
+    );
+  });
+
+  it("maps mapping pages to the Mapping section", () => {
+    expect(getNavigationSectionForPath("/letter-variants")?.label).toBe(
+      "Mapping",
+    );
+    expect(getNavigationSectionForPath("/reports/suppliers")?.label).toBe(
+      "Mapping",
+    );
+  });
+
+  it("returns the exact active link for subsection pages", () => {
+    expect(getNavigationLinkForPath("/reports/suppliers")?.label).toBe(
+      "Supplier reports",
+    );
+    expect(getNavigationLinkForPath("/letter-variants")?.label).toBe(
+      "Letter variants",
+    );
+  });
+
+  it("keeps overview outside the grouped sections", () => {
+    expect(overviewNavigationLink.href).toBe("/");
+    expect(getNavigationSectionForPath("/")).toBeUndefined();
+    expect(getNavigationLinkForPath("/")).toBeUndefined();
+  });
+});

frontend/src/__tests__/token-utils.test.ts

@@ -1,4 +1,8 @@
-import { getDisplayName, hasAdminGroup } from "@/utils/token-utils";
+import {
+  getClaimsFromToken,
+  getDisplayName,
+  hasAdminGroup,
+} from "@/utils/token-utils";
 
 function encodeBase64Url(value: unknown) {
   return Buffer.from(JSON.stringify(value)).toString("base64url");
@@ -11,15 +15,15 @@ function createToken(payload: Record<string, unknown>) {
 describe("token-utils", () => {
   it("recognises the admin group from Cognito groups", () => {
     const token = createToken({
-      "cognito:groups": ["editor", "admin"],
+      "cognito:groups": ["Editors", "Admins"],
     });
 
     expect(hasAdminGroup(token)).toBe(true);
   });
 
-  it("returns false when the admin group is not present", () => {
+  it("returns false when the canonical admin group is not present", () => {
     const token = createToken({
-      "cognito:groups": ["viewer"],
+      "cognito:groups": ["admin"],
     });
 
     expect(hasAdminGroup(token)).toBe(false);
@@ -34,4 +38,21 @@ describe("token-utils", () => {
 
     expect(getDisplayName(token)).toBe("Alex Morgan");
   });
+
+  it("returns decoded claims when a token is provided", () => {
+    const token = createToken({
+      email: "alex@example.nhs.uk",
+      sub: "user-123",
+    });
+
+    expect(getClaimsFromToken(token)).toEqual({
+      email: "alex@example.nhs.uk",
+      sub: "user-123",
+    });
+  });
+
+  it("returns undefined for a missing or invalid token", () => {
+    expect(getClaimsFromToken()).toBeUndefined();
+    expect(getClaimsFromToken("not-a-jwt")).toBeUndefined();
+  });
 });

frontend/src/__tests__/user-claims-popover.test.tsx

@@ -0,0 +1,72 @@
+import { createElement } from "react";
+import { renderToStaticMarkup } from "react-dom/server";
+import { UserClaimsPopover } from "@/components/user-claims-popover";
+import {
+  isPopoverDismissKey,
+  isPopoverInteractionOutside,
+} from "@/utils/user-claims-popover";
+
+describe("UserClaimsPopover", () => {
+  it("renders token claims when the popover is open", () => {
+    const markup = renderToStaticMarkup(
+      createElement(UserClaimsPopover, {
+        claims: {
+          "cognito:groups": ["Admins"],
+          email: "alex@example.nhs.uk",
+          sub: "user-123",
+        },
+        displayName: "Alex Morgan",
+        initialOpen: true,
+      }),
+    );
+
+    expect(markup).toContain("Current user token claims");
+    expect(markup).toContain("Alex Morgan");
+    expect(markup).toContain("email");
+    expect(markup).toContain("alex@example.nhs.uk");
+    expect(markup).toContain("["Admins"]");
+  });
+
+  it("does not render token claims when the popover is closed", () => {
+    const markup = renderToStaticMarkup(
+      createElement(UserClaimsPopover, {
+        claims: { email: "alex@example.nhs.uk" },
+        displayName: "Alex Morgan",
+      }),
+    );
+
+    expect(markup).toContain("Alex Morgan");
+    expect(markup).not.toContain("Current user token claims");
+  });
+
+  it("recognises interactions inside the popover container", () => {
+    const insideTarget = {} as Node;
+
+    expect(
+      isPopoverInteractionOutside(
+        {
+          contains: (node) => [insideTarget].includes(node as Node),
+        },
+        insideTarget as unknown as EventTarget,
+      ),
+    ).toBe(false);
+  });
+
+  it("recognises interactions outside the popover container", () => {
+    const outsideTarget = {} as Node;
+
+    expect(
+      isPopoverInteractionOutside(
+        {
+          contains: () => false,
+        },
+        outsideTarget as unknown as EventTarget,
+      ),
+    ).toBe(true);
+  });
+
+  it("closes the popover when Escape is pressed", () => {
+    expect(isPopoverDismissKey("Escape")).toBe(true);
+    expect(isPopoverDismissKey("Enter")).toBe(false);
+  });
+});

frontend/src/app/auth/page.tsx

@@ -1,5 +1,26 @@
 import { AuthPageContent } from "@/components/auth-page-content";
+import { getBasePath } from "@/utils/get-base-path";
 
-export default function AuthPage() {
-  return <AuthPageContent />;
+type AuthPageProps = Readonly<{
+  searchParams: Promise<{
+    error?: string | string[];
+    redirect?: string | string[];
+  }>;
+}>;
+
+function getFirstValue(value?: string | string[]) {
+  return Array.isArray(value) ? value[0] : value;
+}
+
+export default async function AuthPage({ searchParams }: AuthPageProps) {
+  const resolvedSearchParams = await searchParams;
+  const redirectTarget = getFirstValue(resolvedSearchParams.redirect);
+  const error = getFirstValue(resolvedSearchParams.error);
+
+  return (
+    <AuthPageContent
+      error={error}
+      redirectTarget={redirectTarget || getBasePath() || "/"}
+    />
+  );
 }