@12-apps/ui 6.50.1 → 6.51.1

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

@@ -1,15 +1,25 @@
 import Typography from '@mui/material/Typography/index.js';
-import { useTheme } from '@mui/material/styles/index.js';
+import { useTheme, type SxProps, type Theme } from '@mui/material/styles/index.js';
 import { useState, type ElementType, type ReactNode } from 'react';
 
 import type { SectionNavCopy } from '../../../copy';
+import { stackedOverlayZIndex } from '../../../tokens/layers';
 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 { barSlots, destinationState, isMenu, menuActive, menuCount, type BarSlot } from './SectionNav.helpers';
+import {
+  Box,
+  CONTROL_RESET,
+  CountedIcon,
+  NOT_LIVE,
+  SlotIcon,
+  controlProps,
+  destinationControl,
+  focusRing,
+} from './SectionNav.parts';
 import { RaisedActionButton } from './SectionNav.primary';
 import { SectionNavSheet } from './SectionNav.sheet';
-import type { SectionNavMenu, SectionNavProps } from './SectionNav.types';
+import type { SectionNavAction, SectionNavDestination, SectionNavMenu, SectionNavProps } from './SectionNav.types';
 
 /** Which of the bar's two menus is open, if any. */
 type OpenMenu = 'primary' | 'more' | null;
@@ -29,13 +39,17 @@ export function sectionNavBarInset(theme: Parameters<typeof rem>[0]): string {
 /**
  * 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.
+ * `current` is the page the viewer is on and is what `aria-current` reports —
+ * a link's claim only; an action slot that is ON says so with `aria-pressed`,
+ * which arrives in `control`. `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.
+ * A destination is a link or an action; 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. A `disabled` slot is a disabled button,
+ * dimmed — the act is still where the hand expects it. A `loading` or
+ * `dimmed` slot is drawn the same and stays focusable (`aria-disabled`).
  */
 function Slot({
   label,
@@ -47,6 +61,7 @@ function Slot({
   testId,
   control,
   expanded,
+  loading = false,
 }: {
   label: string;
   icon: ReactNode;
@@ -57,6 +72,7 @@ function Slot({
   testId: string;
   control: Record<string, unknown>;
   expanded?: boolean;
+  loading?: boolean;
 }): React.JSX.Element {
   const theme = useTheme();
   return (
@@ -64,36 +80,17 @@ function Slot({
       {...control}
       aria-current={current ? 'page' : undefined}
       aria-expanded={expanded}
+      aria-busy={loading || undefined}
       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) },
-      }}
+      sx={slotSx(theme, lit)}
     >
-      <CountedIcon icon={icon} count={count} label={copy.badge} testId={`${testId}-badge`} />
+      <CountedIcon
+        icon={<SlotIcon icon={icon} loading={loading} />}
+        count={count}
+        label={copy.badge}
+        testId={`${testId}-badge`}
+      />
       <Typography
         component="span"
         variant="caption"
@@ -112,71 +109,152 @@ function Slot({
   );
 }
 
-/** 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;
+/** A slot's look: icon over label, the lit rule on its top edge, dimmed when disabled. */
+function slotSx(theme: Theme, lit: boolean): SxProps<Theme> {
+  return {
+    ...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) },
+    [NOT_LIVE]: { color: 'text.disabled' },
+  } as SxProps<Theme>;
+}
+
+/** What every slot kind is handed: the bar's open state and how to change it. */
+interface SlotContext {
   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) {
+}
+
+/** The raised button: an action runs on tap; a menu opens its sheet. */
+function PrimarySlot({
+  primary,
+  context,
+}: {
+  primary: SectionNavMenu | SectionNavAction;
+  context: SlotContext;
+}): React.JSX.Element {
+  const testId = primary.dataTestId ?? `${context.dataTestId}-primary`;
+  if (!isMenu(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') })}
+        captioned
+        disabled={primary.disabled}
+        loading={primary.loading}
+        dataTestId={testId}
+        onClick={() => {
+          context.close();
+          primary.onSelect();
+        }}
       />
     );
   }
-  if (slot.kind !== 'destination') return null;
-  const { destination } = slot;
+  return (
+    <RaisedActionButton
+      label={primary.label}
+      icon={primary.icon}
+      open={context.open === 'primary'}
+      closeLabel={context.copy.close}
+      disabled={primary.disabled}
+      dataTestId={testId}
+      onClick={() => context.toggle('primary')}
+    />
+  );
+}
+
+/** The "more" slot: a button that opens its sheet, carrying its entries' counts. */
+function MoreSlot({ more, context }: { more: SectionNavMenu; context: SlotContext }): React.JSX.Element {
+  const { open } = context;
+  return (
+    <Slot
+      label={more.label}
+      icon={more.icon}
+      count={menuCount(more)}
+      current={false}
+      lit={open === 'more' || (open === null && menuActive(more))}
+      expanded={open === 'more'}
+      copy={context.copy}
+      testId={more.dataTestId ?? `${context.dataTestId}-more`}
+      control={controlProps({
+        href: undefined,
+        linkComponent: context.linkComponent,
+        inert: more.disabled === true,
+        onClick: () => context.toggle('more'),
+      })}
+    />
+  );
+}
+
+/** A destination: a link, or an action slot (a toggle when it carries `active`). */
+function DestinationSlot({
+  destination,
+  context,
+}: {
+  destination: SectionNavDestination;
+  context: SlotContext;
+}): React.JSX.Element {
+  const { current, lit } = destinationState(destination);
   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 })}
+      current={current}
+      lit={context.open === null && lit}
+      copy={context.copy}
+      testId={destination.dataTestId ?? `${context.dataTestId}-dest-${destination.id}`}
+      loading={destination.loading === true}
+      control={destinationControl(destination, context.linkComponent, () => {
+        context.close();
+        destination.onSelect?.();
+      })}
     />
   );
 }
 
+/** One slot of the bar, whichever kind it is. */
+function BarSlotView({
+  slot,
+  primary,
+  more,
+  context,
+}: {
+  slot: BarSlot;
+  primary: SectionNavMenu | SectionNavAction | undefined;
+  more: SectionNavMenu | undefined;
+  context: SlotContext;
+}): React.JSX.Element | null {
+  if (slot.kind === 'primary') return primary ? <PrimarySlot primary={primary} context={context} /> : null;
+  if (slot.kind === 'more') return more ? <MoreSlot more={more} context={context} /> : null;
+  return <DestinationSlot destination={slot.destination} context={context} />;
+}
+
 /** The phone layout: a bottom bar, with its menus as bottom sheets. */
 export function SectionNavBar({
   label,
@@ -188,6 +266,7 @@ export function SectionNavBar({
   dataTestId,
 }: Required<Pick<SectionNavProps, 'label' | 'destinations' | 'copy' | 'dataTestId'>> &
   Pick<SectionNavProps, 'primary' | 'more'> & { linkComponent: ElementType | undefined }): React.JSX.Element {
+  const sheetMenu = isMenu(primary) ? primary : undefined;
   const theme = useTheme();
   const [open, setOpen] = useState<OpenMenu>(null);
   const toggle = (menu: Exclude<OpenMenu, null>): void => setOpen((current) => (current === menu ? null : menu));
@@ -211,9 +290,11 @@ export function SectionNavBar({
           // 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.
+          // dialog's own footer is exactly where the bar is. `stackedOverlayZIndex`,
+          // not `zIndex.modal + 1`: a host lifting a bottom Drawer clear of a
+          // stacked sheet catches this bar's OWN sheets too.
           position: 'relative',
-          zIndex: open === null ? 'auto' : theme.zIndex.modal + 1,
+          zIndex: open === null ? 'auto' : stackedOverlayZIndex(theme) + 1,
         }}
       >
         {barSlots(destinations, more !== undefined, primary !== undefined).map((slot) => (
@@ -222,18 +303,13 @@ export function SectionNavBar({
             slot={slot}
             primary={primary}
             more={more}
-            open={open}
-            toggle={toggle}
-            close={close}
-            linkComponent={linkComponent}
-            copy={copy}
-            dataTestId={dataTestId}
+            context={{ open, toggle, close, linkComponent, copy, dataTestId }}
           />
         ))}
       </Box>
-      {primary ? (
+      {sheetMenu ? (
         <SectionNavSheet
-          menu={primary}
+          menu={sheetMenu}
           open={open === 'primary'}
           onClose={close}
           linkComponent={linkComponent}

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

@@ -1,4 +1,4 @@
-import type { SectionNavDestination, SectionNavMenu } from './SectionNav.types';
+import type { SectionNavAction, 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 {
@@ -49,3 +49,18 @@ export function barSlots(
   if (hasPrimary) slots.splice(Math.floor(slots.length / 2), 0, { kind: 'primary' });
   return slots;
 }
+
+/** A primary that opens a sheet, as opposed to one that acts on tap. */
+export function isMenu(primary: SectionNavMenu | SectionNavAction | undefined): primary is SectionNavMenu {
+  return primary !== undefined && 'groups' in primary;
+}
+
+/**
+ * How a destination reads. `current` is `aria-current="page"` and belongs to a
+ * LINK only — an action slot that is ON reports `aria-pressed` instead. `lit`
+ * is the look, and a `dimmed` slot is never lit: it says "not now".
+ */
+export function destinationState(destination: SectionNavDestination): { current: boolean; lit: boolean } {
+  const active = destination.active === true;
+  return { current: active && destination.href !== undefined, lit: active && destination.dimmed !== true };
+}

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

@@ -31,10 +31,13 @@ screen.
 - **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.
+  `href` OR `onSelect`, `badge?`, `active?`, `disabled?`, `dimmed?`,
+  `loading?` and `dataTestId?`.
+- **primary**: a `SectionNavMenu` (`label`, `icon`, `title`, `groups`) or a
+  `SectionNavAction` (`label`, `icon`, `onSelect`, `disabled?`, `loading?`). In
+  the bar it is the raised button. A menu opens its sheet, and the button's name
+  becomes `copy.close` while it is open. An action runs on tap and its label is
+  drawn under the button.
 - **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.
@@ -48,6 +51,36 @@ screen.
   named packs; `SECTION_NAV_COPY` is the locale pack.
 - **dataTestId**: the prefix for every test id (`section-nav`).
 
+## A bar of verbs
+
+The same bar pins a SCREEN's actions at its foot: give destinations an
+`onSelect` instead of an `href`, and `primary` a `SectionNavAction`. A bar of
+places and a bar of verbs are one component, so they cannot drift into two
+looks one tap apart.
+
+- `disabled` draws the slot dimmed and makes it a native disabled button, even
+  when it carries an `href`: a link cannot be disabled, and one that looks
+  dimmed but still navigates is a lie. A tap does nothing; `onSelect` is not
+  called.
+- `dimmed` is for an act the screen cannot do now but should EXPLAIN when
+  tapped. It is drawn exactly like `disabled` (the `text.disabled` colour) and
+  reports `aria-disabled="true"`, but it is NOT natively disabled: it stays
+  focusable, its `onSelect` still fires, and the host answers with a message
+  (why not, and what would make it possible). It is never lit.
+- `loading` replaces the icon with a spinner and reports `aria-busy` and
+  `aria-disabled="true"` until the write it started answers. It stays
+  focusable, so the keyboard keeps its place, and a tap is ignored. The same
+  holds for a loading action `primary`. Native `disabled` is used only for
+  `disabled`.
+- `active` on an action slot marks a TOGGLE that is on: it lights the slot and
+  reports `aria-pressed="true"` (`false` when `active: false`). Only a link
+  reports `aria-current="page"`; an action is not a page.
+- A menu entry, and a whole menu, can be `disabled` too. In the bar a disabled
+  menu's trigger is inert and opens no sheet; in the rail, where the menu is
+  listed rather than behind a trigger, every row of it is inert.
+- `dataTestId` on a destination, entry, action or menu replaces the id the nav
+  would derive, for a host whose suites already drive their own.
+
 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
@@ -81,6 +114,9 @@ the slot reports the sheet through `aria-expanded`.
 
 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 `captioned` its label is drawn under it, hidden from assistive tech so
+the button is named once. `disabled` is native; `loading` keeps it focusable
+with `aria-busy` and `aria-disabled`, and drops the click.
 With `open` it reports `aria-expanded`, takes `closeLabel` as its name, and its
 icon turns 45° while open.
 

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

@@ -1,4 +1,5 @@
 import Box from '@mui/material/Box/index.js';
+import CircularProgress from '@mui/material/CircularProgress/index.js';
 import type { SxProps, Theme } from '@mui/material/styles/index.js';
 import type { ElementType, ReactNode } from 'react';
 
@@ -6,6 +7,7 @@ import { rem } from '../../../tokens/scales';
 import { Badge } from '../../data-display/Badge';
 
 import { shownCount } from './SectionNav.helpers';
+import type { SectionNavDestination } from './SectionNav.types';
 
 /**
  * An icon with its count on the shoulder.
@@ -59,21 +61,76 @@ export function focusRing(theme: Theme): SxProps<Theme> {
  * `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.
+ * element — never a button wrapped around a link. Whatever it would lead to,
+ * a control that is not live is a BUTTON: a link cannot be disabled, and one
+ * that looks dimmed but still navigates is the lie this rules out.
+ *
+ * - `inert` — a native `disabled` button: no focus, no click.
+ * - `busy` — a write is in flight: `aria-disabled`, still focusable, and the
+ *   click is dropped, so the keyboard keeps its place until the write answers.
+ * - `dimmed` — `aria-disabled`, still focusable, and the click STILL runs, so
+ *   the host can explain why the act cannot be done now.
  */
 export function controlProps({
   href,
   onClick,
   linkComponent,
+  inert = false,
+  busy = false,
+  dimmed = false,
 }: {
   href: string | undefined;
   onClick?: () => void;
   linkComponent: ElementType | undefined;
+  inert?: boolean;
+  busy?: boolean;
+  dimmed?: boolean;
 }): Record<string, unknown> {
+  if (inert) return { component: 'button', type: 'button', disabled: true };
+  if (busy) return { component: 'button', type: 'button', 'aria-disabled': 'true' };
+  if (dimmed) return { component: 'button', type: 'button', 'aria-disabled': 'true', onClick };
   if (href !== undefined) return { component: linkComponent ?? 'a', href, onClick };
   return { component: 'button', type: 'button', onClick };
 }
 
+/**
+ * A destination's control: `controlProps` from its own state, plus
+ * `aria-pressed` when it is an action slot that is a toggle. A link reports
+ * where the viewer is through `aria-current` instead — the row draws that.
+ */
+export function destinationControl(
+  destination: SectionNavDestination,
+  linkComponent: ElementType | undefined,
+  onClick: () => void,
+): Record<string, unknown> {
+  return {
+    ...controlProps({
+      href: destination.href,
+      linkComponent,
+      inert: destination.disabled === true,
+      busy: destination.loading === true,
+      dimmed: destination.dimmed === true,
+      onClick,
+    }),
+    'aria-pressed': destination.href === undefined ? destination.active : undefined,
+  };
+}
+
+/**
+ * The selector for a control drawn as not live: natively disabled, or
+ * `aria-disabled` (in flight, or dimmed) and still focusable.
+ */
+export const NOT_LIVE = '&:disabled, &[aria-disabled="true"]';
+
+/**
+ * The icon, or the spinner that stands in for it while the slot's write is in
+ * flight — the same box, so the label under it does not move.
+ */
+export function SlotIcon({ icon, loading }: { icon: ReactNode; loading: boolean }): React.JSX.Element {
+  if (!loading) return <>{icon}</>;
+  return <CircularProgress size="1em" color="inherit" thickness={5} data-testid="section-nav-spinner" />;
+}
+
 /** The base reset every clickable in the nav shares: no underline, no button chrome. */
 export const CONTROL_RESET = {
   border: 0,
@@ -83,6 +140,7 @@ export const CONTROL_RESET = {
   textDecoration: 'none',
   cursor: 'pointer',
   margin: 0,
+  [NOT_LIVE]: { cursor: 'default' },
 } as const;
 
 export { Box };