diff --git a/.storybook/storybook.css b/.storybook/storybook.css
index 03cbfd65..4a701853 100644
--- a/.storybook/storybook.css
+++ b/.storybook/storybook.css
@@ -1,3 +1,13 @@
+/* Gives the plain story canvas (not the Docs page, which sets its own
+ fixed height per docs.story.height) a definite height, so a story's
+ `minHeight: "100%"` resolves against the real viewport instead of
+ collapsing to its content's height. */
+html,
+body,
+#storybook-root {
+ height: 100%;
+}
+
:root {
--sb-ds-background: #f6f6f9;
--sb-ds-surface: #ffffff;
diff --git a/src/components/navigation/SidebarNav.stories.tsx b/src/components/navigation/SidebarNav.stories.tsx
index 15649fae..61a3b187 100644
--- a/src/components/navigation/SidebarNav.stories.tsx
+++ b/src/components/navigation/SidebarNav.stories.tsx
@@ -25,10 +25,11 @@ import {
ListItemIcon,
ListItemText,
} from "@mui/material";
-import { Theme } from "@mui/material/styles";
+import { Theme, useTheme } from "@mui/material/styles";
+import useMediaQuery from "@mui/material/useMediaQuery";
import { Logo } from "../controls/Logo";
import { ColourSchemeButton } from "../controls/ColourSchemeButton";
-import { NavLink, MemoryRouter } from "react-router-dom";
+import { NavLink, MemoryRouter, type NavLinkProps } from "react-router-dom";
const meta: Meta
= {
title: "Components/Navigation/SidebarNav",
@@ -42,15 +43,27 @@ const meta: Meta = {
],
tags: ["autodocs"],
parameters: {
+ // SidebarNav's permanent Drawer is position:fixed on desktop - the story
+ // canvas's default padding wrapper would otherwise misalign it against
+ // the normal-flow content beside it.
+ fullBleed: true,
docs: {
- disable: true,
- pages: {},
description: {
- component: `
-A collapsing/expanding sidebar for your app's primary navigation.
+ component: `A collapsing/expanding sidebar for your app's primary navigation, with an optional contextual secondary panel alongside it.
-For normal screen sizes, the implementation uses MUI's permanent drawer toggling between two widths showing either icon and text or just icon.
-For smaller screens, we use the temporary variant instead.`,
+- **\`hasAppBar\`**: set this when your app renders a fixed AppBar above SidebarNav, so its drawers/panels reserve space for it. Omit it if there's no AppBar, or content is pushed down by an empty gap.
+- **Without \`subNav\`**: renders the primary drawer alone. For normal screen sizes, the implementation uses MUI's permanent drawer toggling between two widths, showing either icon and text or just icon. For smaller screens, we use the temporary variant instead.
+- **With \`subNav\`**: SidebarNav also owns the responsive coordination between the primary drawer and a secondary panel. On mobile only one drawer is visible at a time: opening the secondary panel drills in and hides the primary sidebar, with a back affordance to drill back out. On desktop both panels are shown side by side. Which primary item a secondary panel belongs to (e.g. "Setup" having its own sub-navigation) is entirely up to the consumer — SidebarNav only owns the responsive mechanics, not when the panel opens.
+
+**Using an AppBar**
+- Render your \`AppBar\` as a sibling of SidebarNav, with \`position="fixed"\` and a \`zIndex\` above \`theme.zIndex.drawer\` — MUI wants to draw a Drawer above everything else otherwise.
+- Set \`hasAppBar\` on SidebarNav so its drawers/panels line up below the AppBar, rather than starting at the very top of the screen.
+- Wire the AppBar's own menu button to toggle \`open\`, as shown in \`WithAppBar\`.
+
+**Using SubNav**
+- Only pass \`subNav\` for the primary items that actually have their own sub-navigation. Most items can have none.
+- Drive \`subNavOpen\`/\`setSubNavOpen\` from whichever primary item is currently selected (see \`WithAppBarAndSubNav\`), not from SidebarNav itself. It only owns the responsive mechanics, not when the panel opens.
+- Use \`SubNav\`'s own \`beforeNavSlot\`/\`afterNavSlot\`/\`footerSlot\` for content like search or quick actions inside the secondary panel, rather than reaching into its internals.`,
},
story: {
height: "600px",
@@ -89,16 +102,17 @@ export const NormalLinks: Story = {
render: (_args) => {
const [open, setOpen] = React.useState(true);
return (
-
+
setOpen(!open)}>
-
- When using standard links, the caller must handle the selected state
- and set it to the correct item.
-
+
+
+
+ Main content here
+
);
@@ -106,6 +120,14 @@ export const NormalLinks: Story = {
args: {
navigation: standardLinks,
},
+ parameters: {
+ docs: {
+ description: {
+ story:
+ "When using standard links, the caller must handle the selected state and set it to the correct item.",
+ },
+ },
+ },
};
const reactRouterNavigation = [
@@ -143,7 +165,7 @@ export const RouterLinks: Story = {
render: (_args) => {
const [open, setOpen] = React.useState(false);
return (
-
+
setOpen(!open)}>
-
- React Router NavLinks will handle selected state
- internally.
-
+
+
+
+ Main content here
+
);
@@ -164,6 +187,13 @@ export const RouterLinks: Story = {
args: {
navigation: reactRouterNavigation,
},
+ parameters: {
+ docs: {
+ description: {
+ story: "React Router NavLinks will handle selected state internally.",
+ },
+ },
+ },
};
const groupedNavigation = [
@@ -210,7 +240,7 @@ export const GroupedNavigation: Story = {
render: (_args) => {
const [open, setOpen] = React.useState(true);
return (
-
+
setOpen(!open)}>
- Sections are grouped with dividers.
+
+
+
+ Main content here
+
);
},
+ parameters: {
+ docs: {
+ description: {
+ story: "Sections are grouped with dividers.",
+ },
+ },
+ },
};
/** A dashed, tinted wrapper so it's obvious in the story which content is coming from a slot vs. the `navigation` prop. */
@@ -265,7 +306,7 @@ export const WithSlots: Story = {
render: (_args) => {
const [open, setOpen] = React.useState(true);
return (
-
+
setOpen(!open)}>
-
- Adds slots to the navbar, boxes are only there to highlight what
- each slot renders, they aren't part of the component.{" "}
- afterNavSlot renders inside the scrollable area, right
- after the navigation items. footerSlot is pinned to the
- bottom of the drawer, outside the scroll area.
-
+
+
+
+ Main content here
+
);
},
+ parameters: {
+ docs: {
+ description: {
+ story:
+ "The dashed boxes are only there to highlight what each slot renders - they aren't part of the component. afterNavSlot renders inside the scrollable area, right after the navigation items. footerSlot is pinned to the bottom of the drawer, outside the scroll area.",
+ },
+ },
+ },
};
export const WithAppBar: Story = {
render: (_args) => {
const [open, setOpen] = React.useState(true);
return (
-
+
+
+ {/* spacer equal to the AppBar's height */}
+
+ Main content here
+
+
+
+ );
+ },
+ parameters: {
+ docs: {
+ description: {
+ story:
+ "MUI wants to draw a Drawer above everything, so in this example the AppBar's zIndex is increased. Clicking the menu icon toggles the sidebar open and closed. hasAppBar reserves space at the top of the drawer for the AppBar - omit it when there's no AppBar.",
+ },
+ },
+ },
+};
+
+const setupGroups = [
+ {
+ items: [
+ {
+ label: "General",
+ linkProps: { to: "/setup/general", component: NavLink },
+ },
+ {
+ label: "Devices",
+ linkProps: { to: "/setup/devices", component: NavLink },
+ },
+ {
+ label: "Permissions",
+ linkProps: { to: "/setup/permissions", component: NavLink },
+ },
+ ],
+ },
+];
+
+export const WithAppBarAndSubNav: Story = {
+ render: () => {
+ const theme = useTheme();
+ const desktopLayout = useMediaQuery(theme.breakpoints.up("sm"));
+
+ const [sidebarOpen, setSidebarOpen] = React.useState(true);
+ const [subNavOpen, setSubNavOpen] = React.useState(false);
+ const [selectedItem, setSelectedItem] = React.useState<
+ "setup" | "acquisition" | "analysis"
+ >("acquisition");
+
+ // Only "Setup" has an associated secondary panel, so its link opens it
+ // and every other top-level link closes it.
+ const makeNavLink = React.useCallback(
+ (id: "setup" | "acquisition" | "analysis", opensSubNav: boolean) => {
+ const Component = React.forwardRef(
+ (props, ref) => (
+ {
+ props.onClick?.(e);
+ setSubNavOpen(opensSubNav);
+ setSelectedItem(id);
+ }}
+ />
+ ),
+ );
+ Component.displayName = `${id}Link`;
+ return Component;
+ },
+ [],
+ );
+ const SetupLink = React.useMemo(
+ () => makeNavLink("setup", true),
+ [makeNavLink],
+ );
+ const AcquisitionLink = React.useMemo(
+ () => makeNavLink("acquisition", false),
+ [makeNavLink],
+ );
+ const AnalysisLink = React.useMemo(
+ () => makeNavLink("analysis", false),
+ [makeNavLink],
+ );
+
+ // On desktop the secondary panel is persistent chrome for the active
+ // section, so it should always match `selectedItem` - even if it was
+ // closed while drilling into it on mobile (selecting "General" closes
+ // the mobile overlay without changing `selectedItem`).
+ React.useEffect(() => {
+ if (desktopLayout) {
+ setSubNavOpen(selectedItem === "setup");
+ }
+ }, [desktopLayout, selectedItem]);
+
+ // Selecting a destination inside the secondary panel closes both panels
+ // on mobile, dropping all the way to main content. No-op on desktop,
+ // where the panel stays open side by side.
+ const ChildLink = React.useMemo(() => {
+ const Component = React.forwardRef(
+ (props, ref) => (
+ {
+ props.onClick?.(e);
+ if (!desktopLayout) {
+ setSubNavOpen(false);
+ setSidebarOpen(false);
+ }
+ }}
+ />
+ ),
+ );
+ Component.displayName = "ChildLink";
+ return Component;
+ }, [desktopLayout]);
+
+ const setupGroupsWithChildLinks = React.useMemo(
+ () => [
+ {
+ items: [
+ {
+ label: "General",
+ linkProps: { to: "/setup/general", component: ChildLink },
+ },
+ {
+ label: "Devices",
+ linkProps: { to: "/setup/devices", component: ChildLink },
+ },
+ {
+ label: "Permissions",
+ linkProps: { to: "/setup/permissions", component: ChildLink },
+ },
+ ],
+ },
+ ],
+ [ChildLink],
+ );
+
+ const navigation = [
+ {
+ navItems: [
+ {
+ label: "Setup",
+ icon: ,
+ linkProps: { to: "/1", component: SetupLink },
+ selected: selectedItem === "setup",
+ },
+ {
+ label: "Acquisition",
+ icon: ,
+ linkProps: { to: "/2", component: AcquisitionLink },
+ selected: selectedItem === "acquisition",
+ },
+ {
+ label: "Analysis",
+ icon: ,
+ linkProps: { to: "/3", component: AnalysisLink },
+ selected: selectedItem === "analysis",
+ },
+ ],
+ },
+ ];
+
+ return (
+
+ theme.zIndex.drawer + 1,
+ borderBottom: "1px solid",
+ borderColor: "divider",
+ }}
+ elevation={0}
+ >
+
+ setSidebarOpen(!sidebarOpen)}
+ >
+
+
+
+
+
+
+
+
+
+
+ My app
+
+
+
+
+
+
+
+
+
+
+
+ {/* spacer equal to the AppBar's height */}
+
+ Main content here
+
+
+
+ );
+ },
+ parameters: {
+ docs: {
+ description: {
+ story:
+ 'Clicking "Setup" opens its secondary panel; clicking any other top-level item closes it. On a mobile viewport this drills in and replaces the sidebar, with a back arrow in the panel\'s header to drill back out. On a desktop viewport the panel appears side by side with the sidebar.',
+ },
+ },
+ },
+};
+
+const desktopSideBySideNavigation = [
+ {
+ navItems: [
+ {
+ label: "Setup",
+ icon: ,
+ linkProps: { to: "/1", component: NavLink },
+ selected: true,
+ },
+ {
+ label: "Acquisition",
+ icon: ,
+ linkProps: { to: "/2", component: NavLink },
+ },
+ {
+ label: "Analysis",
+ icon: ,
+ linkProps: { to: "/3", component: NavLink },
+ },
+ ],
+ },
+];
+
+export const DesktopSideBySide: Story = {
+ // Real state so the drawers stay closeable if autodocs' real browser
+ // viewport narrows this below desktop width.
+ render: () => {
+ const [sidebarOpen, setSidebarOpen] = React.useState(true);
+ const [subNavOpen, setSubNavOpen] = React.useState(true);
+
+ return (
+
+
-
-
-
- MUI wants to draw a Drawer above everything, so in this example the
- AppBar's zIndex is increased.
-
+
+ {/* spacer equal to the AppBar's height */}
+
+ Main content here
+
);
diff --git a/src/components/navigation/SidebarNav.test.tsx b/src/components/navigation/SidebarNav.test.tsx
index a282b333..d5bb8946 100644
--- a/src/components/navigation/SidebarNav.test.tsx
+++ b/src/components/navigation/SidebarNav.test.tsx
@@ -1,232 +1,485 @@
-import { render, screen } from "@testing-library/react";
-import { Navigation, SidebarNav } from "./SidebarNav";
+import { render, screen, waitFor } from "@testing-library/react";
+import { useState } from "react";
+import { SidebarNav, type Navigation } from "./SidebarNav";
+import type { SubNavContentProps } from "./SubNav";
import { createMemoryRouter, NavLink, RouterProvider } from "react-router-dom";
import userEvent from "@testing-library/user-event";
import useMediaQuery from "@mui/material/useMediaQuery";
+import { addProviders } from "../../__test-utils__/helpers";
vi.mock("@mui/material/useMediaQuery");
const mockedUseMediaQuery = vi.mocked(useMediaQuery);
describe("SidebarNav", () => {
- const navigation: Navigation = [
- {
- navItems: [
- {
- label: "Setup",
- icon: ,
- linkProps: { component: NavLink, to: "/setup" },
- },
- {
- label: "Acquisition",
- icon: ,
- linkProps: { component: NavLink, to: "/acq" },
- },
- {
- label: "Analysis",
- icon: ,
- linkProps: { component: NavLink, to: "/analysis" },
- },
- ],
- },
- {
- navItems: [
+ describe("primary nav only (no subNav)", () => {
+ const navigation: Navigation = [
+ {
+ navItems: [
+ {
+ label: "Setup",
+ icon: ,
+ linkProps: { component: NavLink, to: "/setup" },
+ },
+ {
+ label: "Acquisition",
+ icon: ,
+ linkProps: { component: NavLink, to: "/acq" },
+ },
+ {
+ label: "Analysis",
+ icon: ,
+ linkProps: { component: NavLink, to: "/analysis" },
+ },
+ ],
+ },
+ {
+ navItems: [
+ {
+ label: "Organisation",
+ icon: ,
+ linkProps: { href: "https://www.example.com" },
+ },
+ ],
+ },
+ ];
+
+ function renderSidenav(
+ open: boolean,
+ setOpen = vi.fn(),
+ hasAppBar = false,
+ ) {
+ const router = createMemoryRouter([
{
- label: "Organisation",
- icon: ,
- linkProps: { href: "https://www.example.com" },
+ path: "/",
+ element: (
+
+ ),
},
- ],
- },
- ];
+ ]);
+ render();
+ }
- function renderSidenav(open: boolean, setOpen = vi.fn()) {
- const router = createMemoryRouter([
- {
- path: "/",
- element: (
-
- ),
- },
- ]);
- render();
- }
+ describe("Desktop layout", () => {
+ beforeEach(() => {
+ mockedUseMediaQuery.mockReturnValue(true);
+ });
- describe("Desktop layout", () => {
- beforeEach(() => {
- mockedUseMediaQuery.mockReturnValue(true);
- });
+ it("shows icons and names when open", () => {
+ renderSidenav(true);
- it("Shows icons and names when open", () => {
- renderSidenav(true);
+ const items = navigation[0].navItems;
- const items = navigation[0].navItems;
+ items.forEach((item) => {
+ const button = screen.getByRole("link", { name: item.label });
+ expect(button).toBeVisible();
+ const label = screen.getByText(item.label);
+ expect(label).toBeVisible();
+ });
+ ["navicon1", "navicon2", "navicon3", "navicon4"].forEach((id) =>
+ expect(screen.getByTestId(id)).toBeVisible(),
+ );
+ });
- items.forEach((item) => {
- const button = screen.getByRole("link", { name: item.label });
- expect(button).toBeVisible();
- const label = screen.getByText(item.label);
- expect(label).toBeVisible();
+ it("shows icons only when closed", () => {
+ renderSidenav(false);
+ const items = navigation[0].navItems;
+ items.forEach((item) => {
+ const button = screen.getByRole("link", { name: item.label });
+ expect(button).toBeVisible(); // a11y-wise still visible
+ const label = screen.getByText(item.label);
+ expect(label).toBeInTheDocument(); // label exists but
+ expect(label).not.toBeVisible(); // not visible
+ });
+ ["navicon1", "navicon2", "navicon3", "navicon4"].forEach((id) =>
+ expect(screen.getByTestId(id)).toBeVisible(),
+ );
});
- ["navicon1", "navicon2", "navicon3", "navicon4"].forEach((id) =>
- expect(screen.getByTestId(id)).toBeVisible(),
- );
- });
- it("Shows icons only when closed", () => {
- renderSidenav(false);
- const items = navigation[0].navItems;
- items.forEach((item) => {
- const button = screen.getByRole("link", { name: item.label });
- expect(button).toBeVisible(); // a11y-wise still visible
- const label = screen.getByText(item.label);
- expect(label).toBeInTheDocument(); // label exists but
- expect(label).not.toBeVisible(); // not visible
- });
- ["navicon1", "navicon2", "navicon3", "navicon4"].forEach((id) =>
- expect(screen.getByTestId(id)).toBeVisible(),
- );
- });
+ it("shows tooltip on buttons when closed", async () => {
+ renderSidenav(false);
+
+ const icon = screen.getByTestId("navicon2");
+ const user = userEvent.setup();
+ await user.hover(icon);
+
+ // notice we await because the tooltip appears after some time
+ const tooltip = await screen.findByRole("tooltip", {
+ name: "Acquisition",
+ });
+ expect(tooltip).toBeVisible();
+ });
- it("shows tooltip on buttons when closed", async () => {
- renderSidenav(false);
+ it("shows no tooltip on buttons when open", async () => {
+ renderSidenav(true);
- const icon = screen.getByTestId("navicon2");
- const user = userEvent.setup();
- await user.hover(icon);
+ const icon = screen.getByTestId("navicon2");
+ const user = userEvent.setup();
+ await user.hover(icon);
- // notice we await because the tooltip appears after some time
- const tooltip = await screen.findByRole("tooltip", {
- name: "Acquisition",
+ const tooltip = screen.queryByRole("tooltip", {
+ name: "Acquisition",
+ });
+ expect(tooltip).not.toBeInTheDocument();
});
- expect(tooltip).toBeVisible();
- });
- it("shows no tooltip on buttons when open", async () => {
- renderSidenav(true);
+ it("creates divider between nav sections", () => {
+ renderSidenav(true);
+ const divider = screen.queryByRole("separator");
+ expect(divider).toBeInTheDocument();
+ });
- const icon = screen.getByTestId("navicon2");
- const user = userEvent.setup();
- await user.hover(icon);
+ it("does not reserve space for an AppBar when hasAppBar is not set", () => {
+ renderSidenav(true);
+ expect(
+ document.querySelector(".MuiToolbar-root"),
+ ).not.toBeInTheDocument();
+ });
- const tooltip = screen.queryByRole("tooltip", {
- name: "Acquisition",
+ it("reserves space for an AppBar when hasAppBar is set", () => {
+ renderSidenav(true, vi.fn(), true);
+ expect(document.querySelector(".MuiToolbar-root")).toBeInTheDocument();
});
- expect(tooltip).not.toBeInTheDocument();
- });
- it("creates divider between nav sections", () => {
- renderSidenav(true);
- const divider = screen.queryByRole("separator");
- expect(divider).toBeInTheDocument();
+ it("renders afterNavSlot after the navigation items", () => {
+ const router = createMemoryRouter([
+ {
+ path: "/",
+ element: (
+ Extra links }
+ />
+ ),
+ },
+ ]);
+ render(