@12-apps/ui 6.44.3 → 6.45.0

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

@@ -0,0 +1,258 @@
+import Typography from '@mui/material/Typography/index.js';
+import { useTheme } from '@mui/material/styles/index.js';
+import { useState, type ElementType, type ReactNode } from 'react';
+
+import type { SectionNavCopy } from '../../../copy';
+import { rem } from '../../../tokens/scales';
+
+import { barSlots, menuActive, menuCount, type BarSlot } from './SectionNav.helpers';
+import { Box, CONTROL_RESET, CountedIcon, controlProps, focusRing } from './SectionNav.parts';
+import { RaisedActionButton } from './SectionNav.primary';
+import { SectionNavSheet } from './SectionNav.sheet';
+import type { SectionNavMenu, SectionNavProps } from './SectionNav.types';
+
+/** Which of the bar's two menus is open, if any. */
+type OpenMenu = 'primary' | 'more' | null;
+
+/** The bar's height above the safe area — tall enough for an icon over a label. */
+const barHeight = (theme: Parameters<typeof rem>[0]): string => rem(theme, 60);
+
+/**
+ * The bar's full height on screen, the safe area included — where its sheets
+ * stop, and what a host reserves at the foot of its content so nothing it
+ * floats (a toast, a receipt) lands under the bar.
+ */
+export function sectionNavBarInset(theme: Parameters<typeof rem>[0]): string {
+  return `calc(${barHeight(theme)} + env(safe-area-inset-bottom))`;
+}
+
+/**
+ * One slot: icon over label, a count on the icon.
+ *
+ * `current` is the page the viewer is on and is what `aria-current` reports;
+ * `lit` is only how the slot looks, and goes out while a sheet is open so the
+ * bar shows where the thumb is. Opening a sheet is `aria-expanded`'s to say.
+ *
+ * A destination is a link; the "more" slot is a button that opens its sheet.
+ * Either way the whole slot is the target, so a thumb landing on the label
+ * lands on the control.
+ */
+function Slot({
+  label,
+  icon,
+  count,
+  current,
+  lit,
+  copy,
+  testId,
+  control,
+  expanded,
+}: {
+  label: string;
+  icon: ReactNode;
+  count: number | undefined;
+  current: boolean;
+  lit: boolean;
+  copy: SectionNavCopy;
+  testId: string;
+  control: Record<string, unknown>;
+  expanded?: boolean;
+}): React.JSX.Element {
+  const theme = useTheme();
+  return (
+    <Box
+      {...control}
+      aria-current={current ? 'page' : undefined}
+      aria-expanded={expanded}
+      data-lit={lit ? 'true' : undefined}
+      data-testid={testId}
+      sx={{
+        ...CONTROL_RESET,
+        ...focusRing(theme),
+        flex: 1,
+        minWidth: 0,
+        display: 'flex',
+        flexDirection: 'column',
+        alignItems: 'center',
+        justifyContent: 'center',
+        gap: 0.25,
+        position: 'relative',
+        color: lit ? 'primary.main' : 'text.secondary',
+        // The current slot is marked by more than its colour: a short rule on
+        // its top edge, so the state survives a colour-blind reading.
+        '&[data-lit="true"]::before': {
+          content: '""',
+          position: 'absolute',
+          top: 0,
+          insetInline: '22%',
+          height: rem(theme, 3),
+          borderBottomLeftRadius: rem(theme, 3),
+          borderBottomRightRadius: rem(theme, 3),
+          bgcolor: 'primary.main',
+        },
+        '& svg': { fontSize: rem(theme, 22) },
+      }}
+    >
+      <CountedIcon icon={icon} count={count} label={copy.badge} testId={`${testId}-badge`} />
+      <Typography
+        component="span"
+        variant="caption"
+        sx={{
+          maxWidth: '100%',
+          overflow: 'hidden',
+          textOverflow: 'ellipsis',
+          whiteSpace: 'nowrap',
+          lineHeight: 1.3,
+          fontWeight: lit ? 700 : 400,
+        }}
+      >
+        {label}
+      </Typography>
+    </Box>
+  );
+}
+
+/** One slot of the bar, whichever kind it is. */
+function BarSlotView({
+  slot,
+  primary,
+  more,
+  open,
+  toggle,
+  close,
+  linkComponent,
+  copy,
+  dataTestId,
+}: {
+  slot: BarSlot;
+  primary: SectionNavMenu | undefined;
+  more: SectionNavMenu | undefined;
+  open: OpenMenu;
+  toggle: (menu: Exclude<OpenMenu, null>) => void;
+  close: () => void;
+  linkComponent: ElementType | undefined;
+  copy: SectionNavCopy;
+  dataTestId: string;
+}): React.JSX.Element | null {
+  if (slot.kind === 'primary' && primary) {
+    return (
+      <RaisedActionButton
+        label={primary.label}
+        icon={primary.icon}
+        open={open === 'primary'}
+        closeLabel={copy.close}
+        dataTestId={`${dataTestId}-primary`}
+        onClick={() => toggle('primary')}
+      />
+    );
+  }
+  if (slot.kind === 'more' && more) {
+    return (
+      <Slot
+        label={more.label}
+        icon={more.icon}
+        count={menuCount(more)}
+        current={false}
+        lit={open === 'more' || (open === null && menuActive(more))}
+        expanded={open === 'more'}
+        copy={copy}
+        testId={`${dataTestId}-more`}
+        control={controlProps({ href: undefined, linkComponent, onClick: () => toggle('more') })}
+      />
+    );
+  }
+  if (slot.kind !== 'destination') return null;
+  const { destination } = slot;
+  return (
+    <Slot
+      label={destination.label}
+      icon={destination.icon}
+      count={destination.badge}
+      current={destination.active === true}
+      lit={open === null && destination.active === true}
+      copy={copy}
+      testId={`${dataTestId}-dest-${destination.id}`}
+      control={controlProps({ href: destination.href, linkComponent, onClick: close })}
+    />
+  );
+}
+
+/** The phone layout: a bottom bar, with its menus as bottom sheets. */
+export function SectionNavBar({
+  label,
+  destinations,
+  primary,
+  more,
+  linkComponent,
+  copy,
+  dataTestId,
+}: Required<Pick<SectionNavProps, 'label' | 'destinations' | 'copy' | 'dataTestId'>> &
+  Pick<SectionNavProps, 'primary' | 'more'> & { linkComponent: ElementType | undefined }): React.JSX.Element {
+  const theme = useTheme();
+  const [open, setOpen] = useState<OpenMenu>(null);
+  const toggle = (menu: Exclude<OpenMenu, null>): void => setOpen((current) => (current === menu ? null : menu));
+  const close = (): void => setOpen(null);
+
+  return (
+    <>
+      <Box
+        component="nav"
+        aria-label={label}
+        data-testid={dataTestId}
+        sx={{
+          flex: 'none',
+          display: 'flex',
+          alignItems: 'stretch',
+          boxSizing: 'border-box',
+          height: sectionNavBarInset(theme),
+          paddingBottom: 'env(safe-area-inset-bottom)',
+          borderTop: `1px solid ${theme.palette.divider}`,
+          bgcolor: 'background.paper',
+          // Above the backdrop ONLY while one of its own sheets is open, so the
+          // primary button can close what it opened. Raised all the time it
+          // would sit over every dialog the page opens, and on a small phone a
+          // dialog's own footer is exactly where the bar is.
+          position: 'relative',
+          zIndex: open === null ? 'auto' : theme.zIndex.modal + 1,
+        }}
+      >
+        {barSlots(destinations, more !== undefined, primary !== undefined).map((slot) => (
+          <BarSlotView
+            key={slot.kind === 'destination' ? `dest-${slot.destination.id}` : `menu-${slot.kind}`}
+            slot={slot}
+            primary={primary}
+            more={more}
+            open={open}
+            toggle={toggle}
+            close={close}
+            linkComponent={linkComponent}
+            copy={copy}
+            dataTestId={dataTestId}
+          />
+        ))}
+      </Box>
+      {primary ? (
+        <SectionNavSheet
+          menu={primary}
+          open={open === 'primary'}
+          onClose={close}
+          linkComponent={linkComponent}
+          copy={copy}
+          testId={`${dataTestId}-primary-sheet`}
+          bottomOffset={sectionNavBarInset(theme)}
+        />
+      ) : null}
+      {more ? (
+        <SectionNavSheet
+          menu={more}
+          open={open === 'more'}
+          onClose={close}
+          linkComponent={linkComponent}
+          copy={copy}
+          testId={`${dataTestId}-more-sheet`}
+          bottomOffset={sectionNavBarInset(theme)}
+        />
+      ) : null}
+    </>
+  );
+}

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

@@ -0,0 +1,51 @@
+import type { SectionNavDestination, SectionNavMenu } from './SectionNav.types';
+
+/** A count worth drawing: positive and finite. Zero and "unknown" draw nothing. */
+export function shownCount(count: number | undefined): number | undefined {
+  return count !== undefined && Number.isFinite(count) && count > 0 ? count : undefined;
+}
+
+/**
+ * The "more" slot's badge: its entries' counts, rolled up.
+ *
+ * The same reason a folded sidebar parent shows its children's counts — the
+ * sheet starts closed, so a count only visible once it is opened is one nobody
+ * sees.
+ */
+export function menuCount(menu: SectionNavMenu | undefined): number | undefined {
+  if (!menu) return undefined;
+  const total = menu.groups
+    .flatMap((group) => group.entries)
+    .reduce((sum, entry) => sum + (shownCount(entry.badge) ?? 0), 0);
+  return shownCount(total);
+}
+
+/** Is the viewer on one of this menu's entries? Then its slot reads as current. */
+export function menuActive(menu: SectionNavMenu | undefined): boolean {
+  return menu?.groups.some((group) => group.entries.some((entry) => entry.active === true)) ?? false;
+}
+
+/** What one bar slot holds, in left-to-right order. */
+export type BarSlot =
+  | { kind: 'destination'; destination: SectionNavDestination }
+  | { kind: 'more' }
+  | { kind: 'primary' };
+
+/**
+ * The bar's slots: the destinations, then `more`, with `primary` in the MIDDLE.
+ *
+ * The middle is where a thumb rests and where a raised button reads as the
+ * one thing this bar is for. With four slots it lands between the second and
+ * the third; with an odd count it takes the lower middle, so the heavier side
+ * is the right one, under the thumb of a right-handed phone.
+ */
+export function barSlots(
+  destinations: readonly SectionNavDestination[],
+  hasMore: boolean,
+  hasPrimary: boolean,
+): BarSlot[] {
+  const slots: BarSlot[] = destinations.map((destination) => ({ kind: 'destination', destination }));
+  if (hasMore) slots.push({ kind: 'more' });
+  if (hasPrimary) slots.splice(Math.floor(slots.length / 2), 0, { kind: 'primary' });
+  return slots;
+}

package/src/components/navigation/SectionNav/SectionNav.md

@@ -0,0 +1,91 @@
+# SectionNav
+
+A section's own navigation: the handful of screens one kind of work moves
+between, drawn 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,
+which destination is current, and how links navigate. The component decides
+only how they are drawn: the order of the bar's slots, the raised primary
+action, the sheets, and the rail's sections.
+
+## When to use it
+
+- A work area a person moves around many times an hour, where a menu behind a
+  ☰ costs a tap and a scroll every time.
+- Use `Tabs` instead when the screens are views of ONE thing on one page, and
+  `NavigationMenu` for a whole app's menu.
+
+## Layouts
+
+| `layout` | draws | menus |
+|---|---|---|
+| `bar` | a bottom row: the destinations, `more` last, `primary` raised in the middle | open as bottom sheets over the page, stopping above the bar |
+| `rail` | a vertical list: `back`, `heading`, the destinations, then each menu | listed under their `title`: nothing is folded on a wide screen |
+
+Which layout to use is the HOST's call. A bar beside a sidebar is two
+navigations competing for one glance, and only the host knows what else is on
+screen.
+
+## Props
+
+- **layout**: `'bar' | 'rail'`.
+- **label**: the navigation landmark's accessible name.
+- **destinations**: `SectionNavDestination[]`, each with `id`, `label`, `icon`,
+  `href`, `badge?` and `active?`.
+- **primary**: a `SectionNavMenu` (`label`, `icon`, `title`, `groups`). In the
+  bar it is the raised button, whose name becomes `copy.close` while its sheet
+  is open.
+- **more**: a `SectionNavMenu`. In the bar it is the last slot, and its badge
+  is the sum of its entries' badges.
+- **back**, **heading**: the rail only.
+- **linkComponent**: the element every `href` renders through, for example a
+  router adapter taking `href`. It defaults to a plain `<a>`. The adapter must
+  pass on `className` (the styling), `onClick` (a sheet entry closes its sheet
+  through it), `aria-current` and `data-testid`; one that drops `onClick`
+  leaves the sheet open after the navigation.
+- **copy**: `SectionNavCopy` (`close`, `badge(count)`), REQUIRED. The component
+  carries no words. `PT_BR_SECTION_NAV_COPY` and `EN_US_SECTION_NAV_COPY` are
+  named packs; `SECTION_NAV_COPY` is the locale pack.
+- **dataTestId**: the prefix for every test id (`section-nav`).
+
+A menu's **groups** carry `entries`. Each entry has an `href` (a link) or an
+`onSelect` (an action). `layout: 'grid'` draws three tiles across in the sheet;
+`list` (the default) draws one row per entry with its `description`. Choosing
+an entry closes the sheet.
+
+## Counts
+
+`badge` is how many things behind a destination wait on the viewer. `0` and
+`undefined` draw nothing, because "nothing waiting" and "not known yet" are not
+numbers. The count's accessible name is `copy.badge(n)`, and it is quiet
+(`aria-live="off"`) because it moves on a poll.
+
+## Docking the bar
+
+Dock the bar at the foot of a flex column. `sectionNavBarInset(theme)` is its
+full height, the phone's safe area included. Reserve it at the foot of the
+content, so nothing the page floats (a toast, a receipt) lands under the bar.
+
+The bar rises above a modal backdrop only while one of its OWN sheets is open,
+so a pointer can close the sheet from the button that opened it. The rest of
+the time a dialog the page opens sits above it. The sheet is a modal dialog
+named by the menu's `title`: while it is open, focus stays inside it, and
+Escape or the sheet's own close button is the way out for a keyboard or a
+screen reader.
+
+`aria-current="page"` stays on the destination the viewer is on, sheet open or
+not. While a sheet is open only the LOOK moves to its slot (`data-lit`), and
+the slot reports the sheet through `aria-expanded`.
+
+## RaisedActionButton
+
+The raised round button on its own, for a host that already draws its own bar:
+drop it between two tabs in a flex row. Without `open` it is a plain action.
+With `open` it reports `aria-expanded`, takes `closeLabel` as its name, and its
+icon turns 45° while open.
+
+## Test ids
+
+`<prefix>-dest-<id>`, `<prefix>-primary`, `<prefix>-more`,
+`<prefix>-{primary,more}-sheet`, `<prefix>-{primary,more}-sheet-entry-<id>` (bar),
+`<prefix>-{primary,more}-entry-<id>` (rail), and `<prefix>-back`.

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

@@ -0,0 +1,88 @@
+import Box from '@mui/material/Box/index.js';
+import type { SxProps, Theme } from '@mui/material/styles/index.js';
+import type { ElementType, ReactNode } from 'react';
+
+import { rem } from '../../../tokens/scales';
+import { Badge } from '../../data-display/Badge';
+
+import { shownCount } from './SectionNav.helpers';
+
+/**
+ * An icon with its count on the shoulder.
+ *
+ * Quiet to assistive tech on change: the count moves on a poll, and a control
+ * that announces itself every minute is noise. Its NAME carries the number,
+ * so it is read when the control is.
+ */
+export function CountedIcon({
+  icon,
+  count,
+  label,
+  testId,
+}: {
+  icon: ReactNode;
+  count: number | undefined;
+  label: (count: number) => string;
+  testId: string;
+}): React.JSX.Element {
+  const shown = shownCount(count);
+  if (shown === undefined) return <>{icon}</>;
+  return (
+    // The library's corner count, in the warning role the sidebar's pill is
+    // drawn from.
+    <Badge
+      content={shown}
+      variant="count"
+      color="warning"
+      max={99}
+      aria-label={label(shown)}
+      aria-live="off"
+      data-testid={testId}
+    >
+      {icon}
+    </Badge>
+  );
+}
+
+/** The keyboard ring every control in the nav draws, in the theme's own colour. */
+export function focusRing(theme: Theme): SxProps<Theme> {
+  return {
+    '&:focus-visible': {
+      outline: `${rem(theme, 2)} solid ${theme.palette.primary.main}`,
+      outlineOffset: rem(theme, -2),
+    },
+  };
+}
+
+/**
+ * The element an entry or destination renders as: the host's link for an
+ * `href`, a button for an `onSelect`.
+ *
+ * Returned as props for a `Box`, so the control stays ONE interactive
+ * element — never a button wrapped around a link.
+ */
+export function controlProps({
+  href,
+  onClick,
+  linkComponent,
+}: {
+  href: string | undefined;
+  onClick?: () => void;
+  linkComponent: ElementType | undefined;
+}): Record<string, unknown> {
+  if (href !== undefined) return { component: linkComponent ?? 'a', href, onClick };
+  return { component: 'button', type: 'button', onClick };
+}
+
+/** The base reset every clickable in the nav shares: no underline, no button chrome. */
+export const CONTROL_RESET = {
+  border: 0,
+  background: 'none',
+  font: 'inherit',
+  color: 'inherit',
+  textDecoration: 'none',
+  cursor: 'pointer',
+  margin: 0,
+} as const;
+
+export { Box };

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

@@ -0,0 +1,81 @@
+import { useTheme } from '@mui/material/styles/index.js';
+import type { ReactNode } from 'react';
+
+import { rem } from '../../../tokens/scales';
+
+import { Box, CONTROL_RESET, focusRing } from './SectionNav.parts';
+
+export interface RaisedActionButtonProps {
+  /** The button's accessible name — it has no visible label. */
+  label: string;
+  icon: ReactNode;
+  onClick: () => void;
+  /**
+   * Whether what the button opens is open. Omit for a button that opens
+   * nothing (a plain action): it then carries no `aria-expanded` and its icon
+   * never turns.
+   */
+  open?: boolean;
+  /** The name it takes while `open` — the same control closes what it opened. REQUIRED with `open`. */
+  closeLabel?: string;
+  dataTestId?: string;
+}
+
+/**
+ * The raised round button in the middle of a bottom bar — the one control in
+ * the row that is an ACTION rather than a place.
+ *
+ * Lifted half out of the bar so it reads as different in kind from the tabs
+ * beside it, and unlabelled so it costs the row less width than a tab: that
+ * width is what lets a bar keep four labelled tabs AND this button at 320px.
+ *
+ * `SectionNav` draws it for its `primary` menu. It is exported on its own for
+ * a bar the host already draws — drop it between two tabs, in a flex row.
+ */
+export function RaisedActionButton({
+  label,
+  icon,
+  onClick,
+  open,
+  closeLabel,
+  dataTestId = 'raised-action',
+}: RaisedActionButtonProps): React.JSX.Element {
+  const theme = useTheme();
+  const size = rem(theme, 52);
+  const expanded = open === true;
+  return (
+    <Box sx={{ flex: 'none', display: 'flex', alignItems: 'flex-start', justifyContent: 'center', px: 0.5 }}>
+      <Box
+        component="button"
+        type="button"
+        onClick={onClick}
+        aria-label={expanded && closeLabel ? closeLabel : label}
+        aria-expanded={open}
+        data-testid={dataTestId}
+        sx={{
+          ...CONTROL_RESET,
+          ...focusRing(theme),
+          width: size,
+          height: size,
+          // Lifted half out of the bar: the one control that is not a place.
+          marginTop: rem(theme, -18),
+          borderRadius: '50%',
+          display: 'flex',
+          alignItems: 'center',
+          justifyContent: 'center',
+          bgcolor: 'primary.main',
+          color: 'primary.contrastText',
+          boxShadow: theme.shadows[6],
+          '& svg': {
+            fontSize: rem(theme, 26),
+            transition: theme.transitions.create('transform', { duration: theme.transitions.duration.shorter }),
+            transform: expanded ? 'rotate(45deg)' : 'none',
+          },
+          '@media (prefers-reduced-motion: reduce)': { '& svg': { transition: 'none' } },
+        }}
+      >
+        {icon}
+      </Box>
+    </Box>
+  );
+}