@12-apps/ui 6.44.2 → 6.45.0

package/src/components/navigation/SectionNav/SectionNav.rail.tsx

@@ -0,0 +1,208 @@
+import Typography from '@mui/material/Typography/index.js';
+import { useTheme } from '@mui/material/styles/index.js';
+import type { ElementType, ReactNode } from 'react';
+
+import type { SectionNavCopy } from '../../../copy';
+import { rem } from '../../../tokens/scales';
+
+import { Box, CONTROL_RESET, CountedIcon, controlProps, focusRing } from './SectionNav.parts';
+import type { SectionNavMenu, SectionNavProps } from './SectionNav.types';
+
+/**
+ * One rail row: icon, label, and the count at the far end.
+ *
+ * Destinations and menu entries draw the same row — in the rail there is room
+ * for everything, so the difference between "a place" and "an action" is the
+ * section it sits in, not its shape.
+ */
+function RailRow({
+  label,
+  description,
+  icon,
+  count,
+  active,
+  copy,
+  testId,
+  control,
+}: {
+  label: string;
+  description?: string;
+  icon: ReactNode;
+  count: number | undefined;
+  active: boolean;
+  copy: SectionNavCopy;
+  testId: string;
+  control: Record<string, unknown>;
+}): React.JSX.Element {
+  const theme = useTheme();
+  return (
+    <Box
+      {...control}
+      aria-current={active ? 'page' : undefined}
+      data-testid={testId}
+      sx={{
+        ...CONTROL_RESET,
+        ...focusRing(theme),
+        display: 'flex',
+        alignItems: 'center',
+        gap: 1.5,
+        width: '100%',
+        minHeight: rem(theme, 40),
+        px: 1.25,
+        py: 0.75,
+        borderRadius: 1,
+        textAlign: 'start',
+        color: active ? 'primary.main' : 'text.primary',
+        bgcolor: active ? 'action.selected' : 'transparent',
+        '&:hover': { bgcolor: active ? 'action.selected' : 'action.hover' },
+        '& svg': { color: 'primary.main', fontSize: rem(theme, 20) },
+      }}
+    >
+      <CountedIcon icon={icon} count={count} label={copy.badge} testId={`${testId}-badge`} />
+      <Box component="span" sx={{ display: 'flex', flexDirection: 'column', minWidth: 0 }}>
+        <Typography component="span" variant="body2" sx={{ fontWeight: active ? 700 : 500 }}>
+          {label}
+        </Typography>
+        {description ? (
+          <Typography component="span" variant="caption" color="text.secondary">
+            {description}
+          </Typography>
+        ) : null}
+      </Box>
+    </Box>
+  );
+}
+
+/** A heading between the rail's sections, in the sidebar's small-caps voice. */
+function RailHeading({ children }: { children: ReactNode }): React.JSX.Element {
+  return (
+    <Typography variant="overline" color="text.secondary" sx={{ px: 1.25, pt: 1.5, lineHeight: 1.6 }}>
+      {children}
+    </Typography>
+  );
+}
+
+/** A menu's groups, listed under its title — nothing folded away on a wide screen. */
+function RailMenu({
+  menu,
+  linkComponent,
+  copy,
+  testId,
+}: {
+  menu: SectionNavMenu;
+  linkComponent: ElementType | undefined;
+  copy: SectionNavCopy;
+  testId: string;
+}): React.JSX.Element {
+  return (
+    <Box component="section" data-testid={testId} sx={{ display: 'flex', flexDirection: 'column', gap: 0.25 }}>
+      <RailHeading>{menu.title}</RailHeading>
+      {menu.groups.map((group) => (
+        <Box key={group.id} sx={{ display: 'flex', flexDirection: 'column', gap: 0.25 }}>
+          {group.title ? (
+            <Typography variant="caption" color="text.secondary" sx={{ px: 1.25, pt: 0.5 }}>
+              {group.title}
+            </Typography>
+          ) : null}
+          {group.entries.map((entry) => (
+            <RailRow
+              key={entry.id}
+              label={entry.label}
+              description={entry.description}
+              icon={entry.icon}
+              count={entry.badge}
+              active={entry.active === true}
+              copy={copy}
+              testId={`${testId}-entry-${entry.id}`}
+              control={controlProps({ href: entry.href, linkComponent, onClick: () => entry.onSelect?.() })}
+            />
+          ))}
+        </Box>
+      ))}
+    </Box>
+  );
+}
+
+/**
+ * The wide-screen layout: a vertical rail — the way back, the destinations,
+ * then every menu's entries.
+ *
+ * It fills the column the host gives it and scrolls on its own, like the
+ * sidebar it stands in for.
+ */
+export function SectionNavRail({
+  label,
+  destinations,
+  primary,
+  more,
+  back,
+  heading,
+  linkComponent,
+  copy,
+  dataTestId,
+}: Required<Pick<SectionNavProps, 'label' | 'destinations' | 'copy' | 'dataTestId'>> &
+  Pick<SectionNavProps, 'primary' | 'more' | 'back' | 'heading'> & {
+    linkComponent: ElementType | undefined;
+  }): React.JSX.Element {
+  const theme = useTheme();
+  return (
+    <Box
+      component="nav"
+      aria-label={label}
+      data-testid={dataTestId}
+      sx={{
+        display: 'flex',
+        flexDirection: 'column',
+        gap: 0.25,
+        height: '100%',
+        overflowY: 'auto',
+        px: 1,
+        py: 1.5,
+        bgcolor: 'background.paper',
+      }}
+    >
+      {back ? (
+        <Box
+          {...controlProps({ href: back.href, linkComponent })}
+          data-testid={`${dataTestId}-back`}
+          sx={{
+            ...CONTROL_RESET,
+            ...focusRing(theme),
+            display: 'flex',
+            alignItems: 'center',
+            gap: 1,
+            px: 1.25,
+            py: 0.75,
+            mb: 0.5,
+            borderRadius: 1,
+            color: 'text.secondary',
+            '&:hover': { bgcolor: 'action.hover', color: 'text.primary' },
+            '& svg': { fontSize: rem(theme, 20) },
+          }}
+        >
+          {back.icon}
+          <Typography component="span" variant="body2" sx={{ fontWeight: 600 }}>
+            {back.label}
+          </Typography>
+        </Box>
+      ) : null}
+      {heading ? <RailHeading>{heading}</RailHeading> : null}
+      {destinations.map((destination) => (
+        <RailRow
+          key={destination.id}
+          label={destination.label}
+          icon={destination.icon}
+          count={destination.badge}
+          active={destination.active === true}
+          copy={copy}
+          testId={`${dataTestId}-dest-${destination.id}`}
+          control={controlProps({ href: destination.href, linkComponent })}
+        />
+      ))}
+      {primary ? (
+        <RailMenu menu={primary} linkComponent={linkComponent} copy={copy} testId={`${dataTestId}-primary`} />
+      ) : null}
+      {more ? <RailMenu menu={more} linkComponent={linkComponent} copy={copy} testId={`${dataTestId}-more`} /> : null}
+    </Box>
+  );
+}

package/src/components/navigation/SectionNav/SectionNav.sheet.tsx

@@ -0,0 +1,206 @@
+import Typography from '@mui/material/Typography/index.js';
+import { useTheme } from '@mui/material/styles/index.js';
+import type { ElementType } from 'react';
+
+import { rem } from '../../../tokens/scales';
+import { Drawer, DrawerContent, DrawerHeader } from '../../layout/Drawer';
+
+import { Box, CONTROL_RESET, CountedIcon, controlProps, focusRing } from './SectionNav.parts';
+import type { SectionNavEntry, SectionNavGroup, SectionNavMenu } from './SectionNav.types';
+import type { SectionNavCopy } from '../../../copy';
+
+interface EntryProps {
+  entry: SectionNavEntry;
+  linkComponent: ElementType | undefined;
+  copy: SectionNavCopy;
+  testId: string;
+  onDone: () => void;
+}
+
+/** A tile in a `grid` group: icon over a short label. */
+function GridEntry({ entry, linkComponent, copy, testId, onDone }: EntryProps): React.JSX.Element {
+  const theme = useTheme();
+  return (
+    <Box
+      {...controlProps({
+        href: entry.href,
+        linkComponent,
+        onClick: () => {
+          entry.onSelect?.();
+          onDone();
+        },
+      })}
+      aria-current={entry.active ? 'page' : undefined}
+      data-testid={`${testId}-entry-${entry.id}`}
+      sx={{
+        ...CONTROL_RESET,
+        ...focusRing(theme),
+        display: 'flex',
+        flexDirection: 'column',
+        alignItems: 'center',
+        justifyContent: 'center',
+        gap: 0.75,
+        minHeight: rem(theme, 76),
+        px: 0.5,
+        py: 1,
+        borderRadius: 1.5,
+        textAlign: 'center',
+        bgcolor: entry.active ? 'action.selected' : 'action.hover',
+        color: entry.active ? 'primary.main' : 'text.primary',
+        '& svg': { color: 'primary.main' },
+      }}
+    >
+      <CountedIcon icon={entry.icon} count={entry.badge} label={copy.badge} testId={`${testId}-badge-${entry.id}`} />
+      <Typography component="span" variant="caption" sx={{ lineHeight: 1.2, fontWeight: entry.active ? 700 : 500 }}>
+        {entry.label}
+      </Typography>
+    </Box>
+  );
+}
+
+/** A row in a `list` group: icon, label, and the description under it. */
+function ListEntry({ entry, linkComponent, copy, testId, onDone }: EntryProps): React.JSX.Element {
+  const theme = useTheme();
+  return (
+    <Box
+      {...controlProps({
+        href: entry.href,
+        linkComponent,
+        onClick: () => {
+          entry.onSelect?.();
+          onDone();
+        },
+      })}
+      aria-current={entry.active ? 'page' : undefined}
+      data-testid={`${testId}-entry-${entry.id}`}
+      sx={{
+        ...CONTROL_RESET,
+        ...focusRing(theme),
+        display: 'flex',
+        alignItems: 'center',
+        gap: 1.5,
+        width: '100%',
+        minHeight: rem(theme, 52),
+        px: 1.5,
+        py: 1,
+        borderRadius: 1.5,
+        textAlign: 'start',
+        bgcolor: entry.active ? 'action.selected' : 'action.hover',
+        '& svg': { color: 'primary.main' },
+      }}
+    >
+      <CountedIcon icon={entry.icon} count={entry.badge} label={copy.badge} testId={`${testId}-badge-${entry.id}`} />
+      <Box component="span" sx={{ display: 'flex', flexDirection: 'column', minWidth: 0 }}>
+        <Typography component="span" variant="body2" sx={{ fontWeight: 600 }}>
+          {entry.label}
+        </Typography>
+        {entry.description ? (
+          <Typography component="span" variant="caption" color="text.secondary">
+            {entry.description}
+          </Typography>
+        ) : null}
+      </Box>
+    </Box>
+  );
+}
+
+/** One titled run of entries, as tiles or rows. */
+function SheetGroup({
+  group,
+  linkComponent,
+  copy,
+  testId,
+  onDone,
+}: Omit<EntryProps, 'entry'> & { group: SectionNavGroup }): React.JSX.Element {
+  const grid = group.layout === 'grid';
+  const Entry = grid ? GridEntry : ListEntry;
+  return (
+    <Box component="section" data-testid={`${testId}-group-${group.id}`} sx={{ display: 'flex', flexDirection: 'column', gap: 1 }}>
+      {group.title ? (
+        <Typography variant="overline" color="text.secondary" sx={{ lineHeight: 1.6 }}>
+          {group.title}
+        </Typography>
+      ) : null}
+      <Box
+        sx={
+          grid
+            ? { display: 'grid', gridTemplateColumns: 'repeat(3, minmax(0, 1fr))', gap: 1 }
+            : { display: 'flex', flexDirection: 'column', gap: 0.75 }
+        }
+      >
+        {group.entries.map((entry) => (
+          <Entry key={entry.id} entry={entry} linkComponent={linkComponent} copy={copy} testId={testId} onDone={onDone} />
+        ))}
+      </Box>
+    </Box>
+  );
+}
+
+/**
+ * A menu opened from the bar: a bottom sheet over the page.
+ *
+ * Choosing an entry closes it — a link has somewhere to go and an action has
+ * something to do, and neither wants the sheet still covering the screen.
+ */
+export function SectionNavSheet({
+  menu,
+  open,
+  onClose,
+  linkComponent,
+  copy,
+  testId,
+  bottomOffset,
+}: {
+  menu: SectionNavMenu;
+  open: boolean;
+  onClose: () => void;
+  linkComponent: ElementType | undefined;
+  copy: SectionNavCopy;
+  testId: string;
+  /** How far above the viewport's foot the sheet stops — the bar's own height, so the bar stays visible. */
+  bottomOffset: string;
+}): React.JSX.Element {
+  const theme = useTheme();
+  return (
+    <Drawer
+      open={open}
+      onClose={onClose}
+      anchor="bottom"
+      height="auto"
+      dataTestId={testId}
+      paperSx={{
+        borderTopLeftRadius: rem(theme, Number(theme.shape.borderRadius) * 3),
+        borderTopRightRadius: rem(theme, Number(theme.shape.borderRadius) * 3),
+        maxHeight: `calc(85dvh - ${bottomOffset})`,
+        bottom: bottomOffset,
+      }}
+    >
+      {/* The library Drawer names nothing: the dialog role and its name live
+          here, around everything the focus trap holds. */}
+      <Box
+        role="dialog"
+        aria-modal="true"
+        aria-label={menu.title}
+        sx={{ display: 'flex', flexDirection: 'column', flex: 1, minHeight: 0 }}
+      >
+        <DrawerHeader onClose={onClose} closeLabel={copy.close} dataTestId={`${testId}-header`}>
+          {menu.title}
+        </DrawerHeader>
+        <DrawerContent>
+          <Box sx={{ display: 'flex', flexDirection: 'column', gap: 2 }}>
+            {menu.groups.map((group) => (
+              <SheetGroup
+                key={group.id}
+                group={group}
+                linkComponent={linkComponent}
+                copy={copy}
+                testId={testId}
+                onDone={onClose}
+              />
+            ))}
+          </Box>
+        </DrawerContent>
+      </Box>
+    </Drawer>
+  );
+}

package/src/components/navigation/SectionNav/SectionNav.tsx

@@ -0,0 +1,56 @@
+import { SectionNavBar } from './SectionNav.bar';
+import { SectionNavRail } from './SectionNav.rail';
+import type { SectionNavProps } from './SectionNav.types';
+
+/**
+ * A section's own navigation — the handful of screens one kind of work moves
+ * between — as a bottom bar on a phone or a rail on a wide screen.
+ *
+ * It knows no product. The host decides every destination, label, icon,
+ * count and which one is current, and renders links through its own router
+ * (`linkComponent`). The nav decides only how they are drawn: the order of the
+ * bar's slots, the raised primary action, the sheets, the rail's sections.
+ *
+ * Which layout to use is the host's call too, because the host knows what
+ * else is on screen: a bar next to a sidebar is two navigations competing for
+ * one glance.
+ */
+export function SectionNav({
+  layout,
+  label,
+  destinations,
+  primary,
+  more,
+  back,
+  heading,
+  linkComponent,
+  copy,
+  dataTestId = 'section-nav',
+}: SectionNavProps): React.JSX.Element {
+  if (layout === 'rail') {
+    return (
+      <SectionNavRail
+        label={label}
+        destinations={destinations}
+        primary={primary}
+        more={more}
+        back={back}
+        heading={heading}
+        linkComponent={linkComponent}
+        copy={copy}
+        dataTestId={dataTestId}
+      />
+    );
+  }
+  return (
+    <SectionNavBar
+      label={label}
+      destinations={destinations}
+      primary={primary}
+      more={more}
+      linkComponent={linkComponent}
+      copy={copy}
+      dataTestId={dataTestId}
+    />
+  );
+}

package/src/components/navigation/SectionNav/SectionNav.types.ts

@@ -0,0 +1,108 @@
+import type { ElementType, ReactNode } from 'react';
+
+import type { SectionNavCopy } from '../../../copy';
+
+/**
+ * One place the section leads to — a bar slot on a phone, a row in the rail.
+ */
+export interface SectionNavDestination {
+  /** Stable key. Also the suffix of the slot's `data-testid`. */
+  id: string;
+  label: string;
+  icon: ReactNode;
+  href: string;
+  /**
+   * How many things behind this destination wait on the viewer. `0` and
+   * `undefined` render no badge — "nothing waiting" and "not known yet" are
+   * different claims and neither is a number.
+   */
+  badge?: number;
+  /** The destination the viewer is on. The host decides; the nav never reads the URL. */
+  active?: boolean;
+}
+
+/**
+ * One entry inside a menu — a sheet tile on a phone, a row in the rail.
+ *
+ * An entry either LEADS somewhere (`href`, rendered through `linkComponent`)
+ * or DOES something (`onSelect`). Give it one or the other.
+ */
+export interface SectionNavEntry {
+  id: string;
+  label: string;
+  /** A second line under the label. Shown by `list` groups and in the rail. */
+  description?: string;
+  icon: ReactNode;
+  href?: string;
+  onSelect?: () => void;
+  badge?: number;
+  active?: boolean;
+}
+
+/** A titled run of entries inside a menu. */
+export interface SectionNavGroup {
+  id: string;
+  /** Heading above the entries. Omit for a group that needs none. */
+  title?: string;
+  /**
+   * How the phone sheet draws the entries: `grid` is three tiles across,
+   * `list` one row each with its description. The rail always lists.
+   * Defaults to `list`.
+   */
+  layout?: 'grid' | 'list';
+  entries: SectionNavEntry[];
+}
+
+/**
+ * A menu the nav opens: the centred primary action, or the "more" slot.
+ *
+ * On a phone it opens as a bottom sheet over the page. In the rail there is
+ * room for everything, so its groups are listed under `title` instead of
+ * hiding behind a trigger.
+ */
+export interface SectionNavMenu {
+  /** The trigger's accessible name, and the visible label of the "more" slot. */
+  label: string;
+  icon: ReactNode;
+  /** The sheet's heading, and the rail section's. */
+  title: string;
+  groups: SectionNavGroup[];
+}
+
+/** The way out of the section, drawn at the top of the rail. */
+export interface SectionNavBack {
+  label: string;
+  href: string;
+  icon?: ReactNode;
+}
+
+export interface SectionNavProps {
+  /**
+   * `bar` — a bottom tab bar for a phone: the destinations, `more` as the last
+   * slot, and `primary` as a raised button in the middle.
+   *
+   * `rail` — a vertical list for a wide screen, with `back` and `heading` on
+   * top and every menu's entries listed rather than folded away.
+   */
+  layout: 'bar' | 'rail';
+  /** The navigation landmark's accessible name. */
+  label: string;
+  destinations: SectionNavDestination[];
+  /** The raised action in the middle of the bar. */
+  primary?: SectionNavMenu;
+  /** The last slot of the bar. Its badge is the sum of its entries' badges. */
+  more?: SectionNavMenu;
+  /** Rail only: the way back out of the section. */
+  back?: SectionNavBack;
+  /** Rail only: a heading above the destinations. */
+  heading?: string;
+  /**
+   * The component every `href` renders through — a router's link adapter that
+   * takes `href`. Omitted, a plain `<a>` is used and navigation reloads.
+   */
+  linkComponent?: ElementType;
+  /** The nav's own words. REQUIRED — the component carries none. */
+  copy: SectionNavCopy;
+  /** Prefix for every `data-testid`. Defaults to `"section-nav"`. */
+  dataTestId?: string;
+}

package/src/components/navigation/SectionNav/__stories__/fixtures.tsx

@@ -0,0 +1,111 @@
+import AddIcon from '@mui/icons-material/Add';
+import AppsIcon from '@mui/icons-material/Apps';
+import CalendarMonthOutlinedIcon from '@mui/icons-material/CalendarMonthOutlined';
+import DashboardOutlinedIcon from '@mui/icons-material/DashboardOutlined';
+import DeliveryDiningOutlinedIcon from '@mui/icons-material/DeliveryDiningOutlined';
+import GridViewOutlinedIcon from '@mui/icons-material/GridViewOutlined';
+import GroupsOutlinedIcon from '@mui/icons-material/GroupsOutlined';
+import PauseCircleOutlineIcon from '@mui/icons-material/PauseCircleOutline';
+import ReceiptLongOutlinedIcon from '@mui/icons-material/ReceiptLongOutlined';
+import RoomServiceOutlinedIcon from '@mui/icons-material/RoomServiceOutlined';
+import ShoppingBagOutlinedIcon from '@mui/icons-material/ShoppingBagOutlined';
+import StorefrontOutlinedIcon from '@mui/icons-material/StorefrontOutlined';
+import TableRestaurantOutlinedIcon from '@mui/icons-material/TableRestaurantOutlined';
+import Box from '@mui/material/Box/index.js';
+import React from 'react';
+
+import { sxRem } from '../../../../tokens/scales';
+
+import type { SectionNavDestination, SectionNavMenu } from '../SectionNav.types';
+
+/**
+ * The stories' example section, shared by the showcase and the interaction
+ * tests. Kept out of the `*.stories.tsx` files because Storybook reads every
+ * named export there as a story.
+ */
+
+/** A restaurant's shift, as the example section: the floor, the board, the waiter's round. */
+export const DESTINATIONS: SectionNavDestination[] = [
+  { id: 'floor', label: 'Floor', icon: <GridViewOutlinedIcon />, href: '#floor' },
+  { id: 'board', label: 'Board', icon: <DashboardOutlinedIcon />, href: '#board', badge: 3, active: true },
+  { id: 'serve', label: 'Serve', icon: <TableRestaurantOutlinedIcon />, href: '#serve', badge: 2 },
+];
+
+export const PRIMARY: SectionNavMenu = {
+  label: 'Create',
+  icon: <AddIcon />,
+  title: 'Create now',
+  groups: [
+    {
+      id: 'order',
+      title: 'New order',
+      layout: 'grid',
+      entries: [
+        { id: 'delivery', label: 'Delivery', icon: <DeliveryDiningOutlinedIcon />, onSelect: () => undefined },
+        { id: 'pickup', label: 'Pickup', icon: <ShoppingBagOutlinedIcon />, onSelect: () => undefined },
+        { id: 'counter', label: 'Counter', icon: <StorefrontOutlinedIcon />, onSelect: () => undefined },
+      ],
+    },
+    {
+      id: 'menu',
+      title: 'Menu',
+      entries: [
+        {
+          id: 'pause',
+          label: 'Pause an item',
+          description: 'Take it off sale until it is back',
+          icon: <PauseCircleOutlineIcon />,
+          onSelect: () => undefined,
+        },
+      ],
+    },
+  ],
+};
+
+export const MORE: SectionNavMenu = {
+  label: 'More',
+  icon: <AppsIcon />,
+  title: 'More',
+  groups: [
+    {
+      id: 'rest',
+      layout: 'grid',
+      entries: [
+        { id: 'queue', label: 'Queue', icon: <GroupsOutlinedIcon />, href: '#queue', badge: 1 },
+        { id: 'pass', label: 'Pass', icon: <RoomServiceOutlinedIcon />, href: '#pass' },
+        { id: 'runs', label: 'Deliveries', icon: <DeliveryDiningOutlinedIcon />, href: '#runs' },
+        { id: 'booked', label: 'Bookings', icon: <CalendarMonthOutlinedIcon />, href: '#booked' },
+        { id: 'orders', label: 'Orders', icon: <ReceiptLongOutlinedIcon />, href: '#orders' },
+      ],
+    },
+  ],
+};
+
+/** A phone-sized frame with the bar at its foot, the way a host docks it. */
+export function PhoneFrame({ children }: { children: React.ReactNode }): React.ReactElement {
+  return (
+    <Box
+      sx={{
+        width: sxRem(360),
+        maxWidth: '100%',
+        height: sxRem(640),
+        display: 'flex',
+        flexDirection: 'column',
+        border: 1,
+        borderColor: 'divider',
+        borderRadius: 3,
+        overflow: 'hidden',
+        bgcolor: 'background.default',
+      }}
+    >
+      <Box sx={{ flex: 1, p: 2 }} />
+      {children}
+    </Box>
+  );
+}
+
+
+/** A desktop-column-sized frame for the rail. */
+export function RailFrame({ children }: { children: React.ReactNode }): React.ReactElement {
+  return <Box sx={{ width: sxRem(240), height: sxRem(560), border: 1, borderColor: 'divider' }}>{children}</Box>;
+}