@12-apps/ui 6.77.2 → 6.78.0

package/src/components/feedback/SequenceResolver/SequenceResolver.parts.tsx

@@ -0,0 +1,307 @@
+import ChevronLeftIcon from '@mui/icons-material/ChevronLeft';
+import ChevronRightIcon from '@mui/icons-material/ChevronRight';
+import CheckCircleOutlineIcon from '@mui/icons-material/CheckCircleOutline';
+import CloseIcon from '@mui/icons-material/Close';
+import Box from '@mui/material/Box/index.js';
+import ButtonBase from '@mui/material/ButtonBase/index.js';
+import IconButton from '@mui/material/IconButton/index.js';
+import Typography from '@mui/material/Typography/index.js';
+import React, { useEffect, useRef } from 'react';
+
+import { Alert } from '../../data-display/Alert';
+import { Progress } from '../../data-display/Progress';
+import { Button } from '../../form/Button';
+import {
+  actionSx,
+  backButtonSx,
+  categoryDescriptionSx,
+  categoryRowSx,
+  categoryTextSx,
+  closeButtonSx,
+  countBadgeSx,
+  doneConfirmSx,
+  doneIconSx,
+  doneSx,
+  doneTitleSx,
+  footerSx,
+  handleSx,
+  headerStartSx,
+  headerSx,
+  introListSx,
+  stepLabelSx,
+  startAllSx,
+  tertiarySx,
+  titleSx,
+} from './SequenceResolver.styles';
+import type { SequenceAction, SequenceDone, SequenceIntro, SequenceStep } from './SequenceResolver.types';
+
+interface HeaderProps {
+  touch: boolean;
+  label: string;
+  /** Absent: no back button (intro, first step, or the host turned it off). */
+  back?: { label: string; accessible?: string; onClick: () => void; disabled: boolean };
+  closeLabel: string;
+  onClose: () => void;
+  progress: number;
+  progressLabel: string;
+  testId: string;
+}
+
+/** The drag handle (phone), the header row and the progress bar. */
+export function SequenceHeader(props: HeaderProps): React.JSX.Element {
+  const { touch, label, back, closeLabel, onClose, progress, progressLabel, testId } = props;
+  return (
+    <>
+      {touch ? <Box aria-hidden sx={handleSx} data-testid={`${testId}-handle`} /> : null}
+      <Box sx={headerSx}>
+        <Box sx={headerStartSx}>
+          {back ? (
+            <Button
+              variant="text"
+              color="primary"
+              size="md"
+              icon={<ChevronLeftIcon />}
+              aria-label={back.accessible}
+              onClick={back.onClick}
+              disabled={back.disabled}
+              sx={backButtonSx(touch)}
+              dataTestId={`${testId}-back`}
+            >
+              {back.label}
+            </Button>
+          ) : null}
+          <Typography component="span" sx={stepLabelSx} data-testid={`${testId}-step-label`}>
+            {label}
+          </Typography>
+        </Box>
+        <IconButton aria-label={closeLabel} onClick={onClose} sx={closeButtonSx(touch)} data-testid={`${testId}-close`}>
+          <CloseIcon />
+        </IconButton>
+      </Box>
+      <Progress
+        variant="linear"
+        size="md"
+        color="warning"
+        value={progress}
+        aria-label={progressLabel}
+        dataTestId={`${testId}-progress`}
+      />
+    </>
+  );
+}
+
+/**
+ * Moves focus to `target` (else `fallback`) whenever `screenKey` changes — and
+ * on mount, which happens inside the dialog's portal, before MUI's focus trap
+ * looks: finding focus already inside, the trap and `focusDialogOnEntered`
+ * both leave it there.
+ */
+export function useFocusOnScreen(
+  screenKey: string,
+  target: React.RefObject<HTMLElement | null>,
+  fallback: React.RefObject<HTMLElement | null>,
+): void {
+  useEffect(() => {
+    (target.current ?? fallback.current)?.focus();
+  }, [screenKey, target, fallback]);
+}
+
+/**
+ * A button that disables itself under the pointer drops focus to the page
+ * behind the dialog. While busy, focus that fell out lands on the step body
+ * (`aria-busy`) instead, so a screen reader stays in the dialog.
+ */
+function useKeepFocusWhileBusy(busy: boolean, body: React.RefObject<HTMLElement | null>): void {
+  useEffect(() => {
+    if (!busy) return undefined;
+    const rescue = (): void => {
+      const node = body.current;
+      const active = node?.ownerDocument.activeElement;
+      if (node && (!active || active === node.ownerDocument.body)) node.focus();
+    };
+    rescue();
+    const frame = requestAnimationFrame(rescue);
+    return () => cancelAnimationFrame(frame);
+  }, [busy, body]);
+}
+
+interface IntroProps {
+  intro: SequenceIntro;
+  titleId: string;
+  testId: string;
+  screenKey: string;
+}
+
+/** The kinds with their counts, and "resolve them all". */
+export function SequenceIntroBody({ intro, titleId, testId, screenKey }: IntroProps): React.JSX.Element {
+  const titleRef = useRef<HTMLHeadingElement | null>(null);
+  useFocusOnScreen(screenKey, titleRef, titleRef);
+  const last = intro.categories.length - 1;
+  return (
+    <>
+      <Box sx={{ display: 'flex', flexDirection: 'column', gap: 0.5 }}>
+        <Typography component="h2" id={titleId} tabIndex={-1} ref={titleRef} sx={titleSx}>
+          {intro.title}
+        </Typography>
+        {intro.description ? (
+          <Typography variant="body2" color="text.secondary">
+            {intro.description}
+          </Typography>
+        ) : null}
+      </Box>
+      <Box component="ul" sx={introListSx}>
+        {intro.categories.map((category, index) => (
+          <li key={`${index}-${category.label}`}>
+            <ButtonBase
+              onClick={category.onPick}
+              sx={categoryRowSx(index === last)}
+              data-testid={`${testId}-category-${index}`}
+            >
+              <Box component="span" sx={countBadgeSx}>
+                {category.count}
+              </Box>
+              <Box component="span" sx={categoryTextSx}>
+                <Typography component="span" variant="body2" fontWeight={500}>
+                  {category.label}
+                </Typography>
+                {category.description ? (
+                  <Typography component="span" sx={categoryDescriptionSx}>
+                    {category.description}
+                  </Typography>
+                ) : null}
+              </Box>
+              <ChevronRightIcon aria-hidden sx={{ color: 'text.secondary' }} />
+            </ButtonBase>
+          </li>
+        ))}
+      </Box>
+      <Button
+        variant="solid"
+        color="primary"
+        size="lg"
+        fullWidth
+        onClick={intro.onStartAll}
+        dataTestId={`${testId}-start-all`}
+        sx={startAllSx}
+      >
+        {intro.startAllLabel}
+      </Button>
+    </>
+  );
+}
+
+interface StepProps {
+  step: SequenceStep;
+  /** The default secondary: skip. */
+  skip: SequenceAction;
+  busy: boolean;
+  error: string | null;
+  touch: boolean;
+  testId: string;
+  screenKey: string;
+  titleRef: React.RefObject<HTMLElement | null>;
+}
+
+function ActionButton({
+  action,
+  busy,
+  touch,
+  variant,
+  testId,
+}: {
+  action: SequenceAction;
+  busy: boolean;
+  touch: boolean;
+  variant: 'solid' | 'outline' | 'text';
+  testId: string;
+}): React.JSX.Element {
+  return (
+    <Button
+      variant={variant}
+      color={variant === 'outline' ? 'neutral' : 'primary'}
+      size="md"
+      onClick={action.onClick}
+      disabled={busy || action.disabled}
+      dataTestId={testId}
+      sx={variant === 'text' ? tertiarySx(touch) : actionSx(touch)}
+    >
+      {action.label}
+    </Button>
+  );
+}
+
+/** The host's body, its error, the tertiary text button and the footer. */
+export function SequenceStepBody(props: StepProps): React.JSX.Element {
+  const { step, skip, busy, error, touch, testId, screenKey, titleRef } = props;
+  const bodyRef = useRef<HTMLDivElement | null>(null);
+  useFocusOnScreen(screenKey, titleRef, bodyRef);
+  useKeepFocusWhileBusy(busy, bodyRef);
+  const secondary = step.secondary === false ? undefined : (step.secondary ?? skip);
+  const hasFooter = Boolean(secondary || step.primary);
+  return (
+    <>
+      <Box ref={bodyRef} tabIndex={-1} aria-busy={busy} sx={{ outline: 'none', minWidth: 0 }}>
+        {step.content}
+      </Box>
+      {error ? (
+        <Alert variant="danger" announce="assertive" description={error} dataTestId={`${testId}-error`} />
+      ) : null}
+      {step.tertiary ? (
+        <ActionButton action={step.tertiary} busy={busy} touch={touch} variant="text" testId={`${testId}-tertiary`} />
+      ) : null}
+      {hasFooter ? (
+        <Box sx={footerSx(touch, step.footer ?? 'end')} data-testid={`${testId}-footer`}>
+          {secondary ? (
+            <ActionButton action={secondary} busy={busy} touch={touch} variant="outline" testId={`${testId}-secondary`} />
+          ) : null}
+          {step.primary ? (
+            <ActionButton action={step.primary} busy={busy} touch={touch} variant="solid" testId={`${testId}-primary`} />
+          ) : null}
+        </Box>
+      ) : null}
+    </>
+  );
+}
+
+interface DoneProps {
+  done: SequenceDone;
+  titleId: string;
+  error: string | null;
+  touch: boolean;
+  onConfirm: () => void;
+  testId: string;
+  screenKey: string;
+}
+
+/** The end screen: a check, the host's title and sentence, one button that closes. */
+export function SequenceDoneBody({ done, titleId, error, touch, onConfirm, testId, screenKey }: DoneProps): React.JSX.Element {
+  const titleRef = useRef<HTMLHeadingElement | null>(null);
+  useFocusOnScreen(screenKey, titleRef, titleRef);
+  return (
+    <Box sx={doneSx} data-testid={`${testId}-done`}>
+      <CheckCircleOutlineIcon aria-hidden sx={doneIconSx} />
+      <Typography component="h2" id={titleId} tabIndex={-1} ref={titleRef} sx={doneTitleSx}>
+        {done.title}
+      </Typography>
+      {done.description ? (
+        <Typography variant="body2" color="text.secondary">
+          {done.description}
+        </Typography>
+      ) : null}
+      {error ? (
+        <Alert variant="danger" announce="assertive" description={error} dataTestId={`${testId}-error`} />
+      ) : null}
+      <Button
+        variant="solid"
+        color="primary"
+        size="md"
+        fullWidth={touch}
+        onClick={onConfirm}
+        dataTestId={`${testId}-done-confirm`}
+        sx={doneConfirmSx()}
+      >
+        {done.confirmLabel}
+      </Button>
+    </Box>
+  );
+}

package/src/components/feedback/SequenceResolver/SequenceResolver.styles.ts

@@ -0,0 +1,238 @@
+import type { SxProps, Theme } from '@mui/material/styles/index.js';
+
+import { rem, sxRem } from '../../../tokens/relative';
+import { softSignal } from '../../../tokens/surfaces';
+import { SEQUENCE_METRICS } from './SequenceResolver.metrics';
+
+/**
+ * The paper's column: chrome (handle, header, progress) on top, the screen's
+ * body below — one gap, as the prototype draws it. The body is the ONLY scroll
+ * region, so Back, the step label, close and the progress never scroll away
+ * with a long step. A title focused by script (`tabIndex={-1}`, the host's
+ * included) is not a control and draws no focus ring.
+ */
+export const columnSx: SxProps<Theme> = {
+  display: 'flex',
+  flexDirection: 'column',
+  flex: '1 1 auto',
+  minHeight: 0,
+  gap: 2.25,
+  '& [tabindex="-1"]:focus': { outline: 0 },
+};
+
+/** The chrome above the body: never shrinks, never scrolls. */
+export const chromeSx: SxProps<Theme> = { display: 'flex', flexDirection: 'column', gap: 2.25, flex: 'none' };
+
+/** The screen's body: takes what the paper has left and scrolls inside it. */
+export const scrollBodySx: SxProps<Theme> = {
+  display: 'flex',
+  flexDirection: 'column',
+  gap: 2.25,
+  flex: '1 1 auto',
+  minHeight: 0,
+  overflowY: 'auto',
+  overscrollBehavior: 'contain',
+  // The body's children keep their own height and the BODY scrolls: a
+  // shrinking child (the intro's clipped list, a host's step) would
+  // otherwise be crushed instead (320×568, 700×420).
+  '& > *': { flexShrink: 0 },
+  // Room inside the scroll edge for focus rings and the primary's shadow,
+  // which an `overflow` box would otherwise clip; the negative margin keeps
+  // the content where the prototype puts it.
+  px: 0.5,
+  mx: -0.5,
+  pb: 0.5,
+};
+
+/**
+ * The paper stops scrolling itself and lets its one child (the Dialog's padded
+ * body box around `columnSx`) shrink, so the height cap reaches the body.
+ * Below the sheet breakpoint the paper is also capped at 95% of the viewport.
+ */
+export function paperSx(touch: boolean): SxProps<Theme> {
+  const share = SEQUENCE_METRICS.sheetMaxHeightPercent;
+  const column = {
+    overflowY: 'hidden',
+    '& > *': { display: 'flex', flexDirection: 'column', flex: '1 1 auto', minHeight: 0 },
+  } as const;
+  if (!touch) return column;
+  return {
+    ...column,
+    maxHeight: `${share}vh`,
+    '@supports (height: 100dvh)': { maxHeight: `${share}dvh` },
+  };
+}
+
+/** The end screen's button: a step down from the sentence, at the touch-target height on a phone. */
+export function doneConfirmSx(): SxProps<Theme> {
+  return { mt: 1, minHeight: sxRem(SEQUENCE_METRICS.touchTarget) };
+}
+
+/** "All in sequence": the prototype's 48px, and taller when a long label wraps. */
+export const startAllSx: SxProps<Theme> = { height: 'auto', minHeight: sxRem(SEQUENCE_METRICS.startAllHeight) };
+
+/** A button at the touch-target height below the sheet breakpoint; its own size above it. */
+export function actionSx(touch: boolean): SxProps<Theme> {
+  // On a phone the footer's actions share the row while both labels fit on
+  // one line each; one that does not takes a full row instead of wrapping
+  // word by word, and a label wider than the row itself wraps inside it
+  // rather than pushing the sheet sideways.
+  return touch
+    ? { minHeight: sxRem(SEQUENCE_METRICS.touchTarget), flex: '1 1 max-content', minWidth: 0, maxWidth: '100%' }
+    : {};
+}
+
+export const handleSx: SxProps<Theme> = {
+  alignSelf: 'center',
+  width: sxRem(SEQUENCE_METRICS.handle.width),
+  height: sxRem(SEQUENCE_METRICS.handle.height),
+  borderRadius: sxRem(SEQUENCE_METRICS.handle.height / 2),
+  bgcolor: 'divider',
+  flex: 'none',
+};
+
+export const headerSx: SxProps<Theme> = {
+  display: 'flex',
+  alignItems: 'center',
+  justifyContent: 'space-between',
+  gap: 1.5,
+};
+
+/** Back and the label; on a narrow sheet the label takes its own row rather than squeeze. */
+export const headerStartSx: SxProps<Theme> = {
+  display: 'inline-flex',
+  flexWrap: 'wrap',
+  alignItems: 'center',
+  columnGap: 0.75,
+  minWidth: 0,
+};
+
+export const stepLabelSx: SxProps<Theme> = {
+  fontSize: sxRem(SEQUENCE_METRICS.stepLabel),
+  fontWeight: 500,
+  color: 'text.secondary',
+  minWidth: 0,
+};
+
+export function closeButtonSx(touch: boolean): SxProps<Theme> {
+  const size = touch ? SEQUENCE_METRICS.closeSize.touch : SEQUENCE_METRICS.closeSize.pointer;
+  return { width: sxRem(size), height: sxRem(size), color: 'text.secondary', flex: 'none' };
+}
+
+export function backButtonSx(touch: boolean): SxProps<Theme> {
+  return touch ? { flex: 'none', minHeight: sxRem(SEQUENCE_METRICS.touchTarget) } : { flex: 'none' };
+}
+
+export const titleSx: SxProps<Theme> = {
+  fontSize: sxRem(SEQUENCE_METRICS.title),
+  fontWeight: 500,
+  lineHeight: 1.25,
+  outline: 'none',
+};
+
+export const introListSx: SxProps<Theme> = {
+  display: 'flex',
+  flexDirection: 'column',
+  border: '1px solid',
+  borderColor: 'divider',
+  borderRadius: sxRem(SEQUENCE_METRICS.listRadius),
+  overflow: 'hidden',
+  m: 0,
+  p: 0,
+  listStyle: 'none',
+};
+
+export function categoryRowSx(last: boolean): SxProps<Theme> {
+  return {
+  display: 'flex',
+  alignItems: 'center',
+  gap: 1.5,
+  width: '100%',
+  minHeight: sxRem(SEQUENCE_METRICS.categoryMinHeight),
+  px: 1.75,
+  py: 1.25,
+  textAlign: 'left',
+  justifyContent: 'flex-start',
+  borderBottom: last ? 0 : '1px solid',
+  borderColor: 'divider',
+  '&:hover': { bgcolor: 'action.hover' },
+  '&.Mui-focusVisible': { bgcolor: 'action.focus' },
+  };
+}
+
+export const countBadgeSx: SxProps<Theme> = (theme: Theme) => ({
+  flex: 'none',
+  display: 'inline-flex',
+  alignItems: 'center',
+  justifyContent: 'center',
+  boxSizing: 'border-box',
+  minWidth: rem(theme, SEQUENCE_METRICS.countBadge),
+  height: rem(theme, SEQUENCE_METRICS.countBadge),
+  px: 0.75,
+  borderRadius: rem(theme, SEQUENCE_METRICS.countBadge / 2),
+  bgcolor: softSignal(theme, 'error'),
+  // The signal's deep step on its soft ground; the light step on a dark one.
+  color: theme.palette.mode === 'dark' ? 'error.light' : 'error.dark',
+  fontWeight: 500,
+});
+
+export const categoryTextSx: SxProps<Theme> = {
+  display: 'flex',
+  flexDirection: 'column',
+  gap: 0.25,
+  flex: '1 1 auto',
+  minWidth: 0,
+};
+
+export const categoryDescriptionSx: SxProps<Theme> = {
+  fontSize: sxRem(SEQUENCE_METRICS.categoryDescription),
+  color: 'text.secondary',
+};
+
+/**
+ * The step's footer, as the prototype draws each kind:
+ * - phone: the actions share the row (a label that does not fit takes a full
+ *   row), no hairline;
+ * - pointer, `'split'`: two equal full-width columns, no hairline (limits, a purchase);
+ * - pointer, `'end'`: auto-width actions, right-aligned, over a hairline (restock).
+ */
+export function footerSx(touch: boolean, layout: 'end' | 'split'): SxProps<Theme> {
+  if (touch) return { display: 'flex', flexWrap: 'wrap', gap: 1.25 };
+  if (layout === 'split') {
+    return { display: 'grid', gridAutoFlow: 'column', gridAutoColumns: 'minmax(0, 1fr)', gap: 1.25 };
+  }
+  return {
+    display: 'flex',
+    flexWrap: 'wrap',
+    justifyContent: 'flex-end',
+    alignItems: 'center',
+    gap: 1.25,
+    pt: 1.5,
+    borderTop: '1px solid',
+    borderColor: 'divider',
+  };
+}
+
+export function tertiarySx(touch: boolean): SxProps<Theme> {
+  return touch ? { alignSelf: 'flex-start', minHeight: sxRem(SEQUENCE_METRICS.touchTarget) } : { alignSelf: 'flex-start' };
+}
+
+export const doneSx: SxProps<Theme> = {
+  display: 'flex',
+  flexDirection: 'column',
+  alignItems: 'center',
+  gap: 1.25,
+  py: 1.5,
+  textAlign: 'center',
+};
+
+export const doneIconSx: SxProps<Theme> = {
+  fontSize: sxRem(SEQUENCE_METRICS.doneIcon),
+  color: 'success.main',
+};
+
+export const doneTitleSx: SxProps<Theme> = {
+  fontSize: sxRem(SEQUENCE_METRICS.doneTitle),
+  fontWeight: 500,
+  outline: 'none',
+};