@12-apps/ui 6.77.1 → 6.78.0

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',
+};

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

@@ -0,0 +1,179 @@
+'use client';
+
+import Box from '@mui/material/Box/index.js';
+import { useTheme } from '@mui/material/styles/index.js';
+import useMediaQuery from '@mui/material/useMediaQuery/index.js';
+import React, { useCallback, useId, useRef } from 'react';
+
+import { Dialog } from '../Dialog';
+import { currentOf, positionOf, progressOf, summaryOf, type RunState } from './sequence-model';
+import { SequenceDoneBody, SequenceHeader, SequenceIntroBody, SequenceStepBody } from './SequenceResolver.parts';
+import { SEQUENCE_METRICS } from './SequenceResolver.metrics';
+import { chromeSx, columnSx, paperSx, scrollBodySx } from './SequenceResolver.styles';
+import type { SequenceItem, SequenceResolverProps, SequenceStepApi } from './SequenceResolver.types';
+import { useSequenceRun, type SequenceRun } from './useSequenceRun';
+
+/** What the header's label says on the screen showing. */
+function headerLabelOf<I extends SequenceItem, R>(
+  props: SequenceResolverProps<I, R>,
+  run: RunState<I, R>,
+  current: I | undefined,
+): string {
+  const { labels } = props;
+  if (props.intro) return labels.introStep;
+  if (!current) return labels.doneStep;
+  return labels.step(positionOf(run), summaryOf(run).total, current);
+}
+
+/** The header's back button, once a previous step exists and the host allows it. */
+function backOf<I extends SequenceItem, R>(props: SequenceResolverProps<I, R>, state: SequenceRun<I, R>) {
+  const { intro, labels, canGoBack = true } = props;
+  if (intro || !canGoBack || state.run.visits.length === 0) return undefined;
+  return { label: labels.back, accessible: labels.backAccessible, onClick: state.back, disabled: state.busy };
+}
+
+/**
+ * Esc closes. `persistent` turns MUI's own Esc off together with the veil's
+ * click (the prototype's veil does nothing), so Esc is put back here; a popup
+ * inside a step that handles its own Esc stops it before it gets here.
+ */
+function escapeCloses(close: () => void) {
+  return (event: React.KeyboardEvent): void => {
+    if (event.key !== 'Escape' || event.defaultPrevented) return;
+    event.stopPropagation();
+    close();
+  };
+}
+
+interface BodyProps<I extends SequenceItem, R> {
+  props: SequenceResolverProps<I, R>;
+  state: SequenceRun<I, R>;
+  current: I | undefined;
+  api: SequenceStepApi<R>;
+  titleId: string;
+  stepTitleRef: React.RefObject<HTMLElement | null>;
+  touch: boolean;
+  testId: string;
+  close: () => void;
+}
+
+/** The intro, the step on screen, or the end screen. */
+function SequenceBody<I extends SequenceItem, R>(body: BodyProps<I, R>): React.JSX.Element {
+  const { props, state, current, api, titleId, stepTitleRef, touch, testId, close } = body;
+  if (props.intro) {
+    return <SequenceIntroBody intro={props.intro} titleId={titleId} testId={testId} screenKey="intro" />;
+  }
+  if (current) {
+    return (
+      <SequenceStepBody
+        step={props.renderStep(current, api)}
+        skip={{ label: props.labels.skip, onClick: state.skip }}
+        busy={state.busy}
+        error={state.error}
+        touch={touch}
+        testId={testId}
+        screenKey={`step:${current.key}`}
+        titleRef={stepTitleRef}
+      />
+    );
+  }
+  const summary = summaryOf(state.run);
+  return (
+    <SequenceDoneBody
+      done={typeof props.done === 'function' ? props.done(summary) : props.done}
+      titleId={titleId}
+      error={state.error}
+      touch={touch}
+      onConfirm={close}
+      testId={testId}
+      screenKey="done"
+    />
+  );
+}
+
+/**
+ * Resolve a queue of problems one at a time, in ONE dialog whose body is
+ * replaced step by step: a header with "‹ Back", the step's label and close,
+ * a progress bar, the host's step, and an end screen (FUT-3671).
+ *
+ * A centred `Dialog` from the `sm` breakpoint up; the `Dialog` inset
+ * bottom-sheet variant below it, never taller than 95% of the viewport. Either
+ * way the paper scrolls inside the viewport, so a long step is never cut off.
+ *
+ * The component owns the run — which step is on screen, what was answered or
+ * skipped, where Back returns to — and nothing about the domain: every step
+ * body, every word and every server call is the host's.
+ */
+export function SequenceResolver<I extends SequenceItem, R = unknown>(
+  props: SequenceResolverProps<I, R>,
+): React.JSX.Element {
+  const { open, onClose, intro, labels } = props;
+  const testId = props.dataTestId ?? 'sequence-resolver';
+  const theme = useTheme();
+  const touch = useMediaQuery(theme.breakpoints.down(SEQUENCE_METRICS.sheetBreakpoint));
+  const titleId = `${useId()}-title`;
+  const stepTitleRef = useRef<HTMLElement | null>(null);
+  const titleRef = useCallback((node: HTMLElement | null) => {
+    stepTitleRef.current = node;
+  }, []);
+
+  const state = useSequenceRun<I, R>({
+    open,
+    active: open && !intro,
+    queue: props.queue,
+    onBack: props.onBack,
+    failed: labels.failed,
+  });
+  const { run, busy } = state;
+  const current = intro ? undefined : currentOf(run);
+  const close = (): void => onClose(summaryOf(run));
+  const api: SequenceStepApi<R> = {
+    resolve: state.resolve,
+    skip: state.skip,
+    back: state.back,
+    busy,
+    titleProps: { id: titleId, tabIndex: -1, ref: titleRef },
+  };
+
+  return (
+    <Dialog
+      open={open}
+      onClose={close}
+      persistent
+      variant={touch ? 'bottom-sheet' : 'default'}
+      size="sm"
+      aria-labelledby={titleId}
+      onKeyDown={escapeCloses(close)}
+      slotProps={{ paper: { sx: paperSx(touch) } }}
+      dataTestId={testId}
+    >
+      <Box sx={columnSx}>
+        <Box sx={chromeSx}>
+          <SequenceHeader
+          touch={touch}
+          label={headerLabelOf(props, run, current)}
+          back={backOf(props, state)}
+          closeLabel={labels.close}
+          onClose={close}
+          progress={intro ? 0 : progressOf(run)}
+          progressLabel={labels.progress}
+          testId={testId}
+          />
+        </Box>
+        <Box sx={scrollBodySx} data-testid={`${testId}-body`}>
+          <SequenceBody
+          props={props}
+          state={state}
+          current={current}
+          api={api}
+          titleId={titleId}
+          stepTitleRef={stepTitleRef}
+          touch={touch}
+          testId={testId}
+          close={close}
+          />
+        </Box>
+      </Box>
+    </Dialog>
+  );
+}

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

@@ -0,0 +1,185 @@
+import type * as React from 'react';
+
+/**
+ * One entry of the queue a {@link SequenceResolverProps} walks through.
+ *
+ * Extend it with whatever the host's step needs (`item.payload`, an id, the
+ * row it came from): the component only reads `key` and `kindLabel`, and hands
+ * the WHOLE item back to `renderStep` and `onBack`.
+ */
+export interface SequenceItem {
+  /** Stable identity across re-renders and refetches — what the run tracks. */
+  key: string;
+  /** The kind word the header shows next to the position ("Purchase"). */
+  kindLabel: string;
+}
+
+/** Where the run stands, handed to the end screen, `onClose` and `labels.step`. */
+export interface SequenceSummary {
+  /** Steps answered with `resolve`. */
+  resolved: number;
+  /** Steps passed over with `skip`. */
+  skipped: number;
+  /** Every step of the run so far: answered + skipped + still ahead. */
+  total: number;
+  /**
+   * Problems the host reported as resolved TOGETHER with an answered step
+   * (`api.resolve(result, { alsoResolved })` — "apply to every sibling"),
+   * which never became steps. `resolved + alsoResolved` is what a close toast
+   * counts; the end screen's "N of M" counts steps.
+   */
+  alsoResolved: number;
+}
+
+/** What an answer can say besides its result. */
+export interface SequenceResolveOptions {
+  /** How many OTHER problems this answer resolved too (siblings that never became steps). */
+  alsoResolved?: number;
+}
+
+/** A button a step puts in the resolver's footer. */
+export interface SequenceAction {
+  label: string;
+  onClick: () => void;
+  /** Disabled on top of the resolver's own `busy`. */
+  disabled?: boolean;
+}
+
+/** What `renderStep` gets: the run's verbs and its state. */
+export interface SequenceStepApi<R> {
+  /**
+   * Answer this step and move to the next one. Pass the result itself, or the
+   * PROMISE of it (the host's server write): the step stays on screen and
+   * `busy` until it settles; a rejection keeps it and shows the rejection's
+   * message. The result is what `onBack` receives if the reader returns.
+   */
+  resolve: (result: R | PromiseLike<R>, options?: SequenceResolveOptions) => void;
+  /** Leave this step unanswered and move on. */
+  skip: () => void;
+  /** Return to the previous step (the header's back button does the same). */
+  back: () => void;
+  /** True while a `resolve` promise or an `onBack` is pending — disable the step's own answers. */
+  busy: boolean;
+  /**
+   * Spread on the step's TITLE — the item's name, first and large. It names
+   * the dialog (`aria-labelledby`) and takes focus on every advance.
+   */
+  titleProps: {
+    id: string;
+    tabIndex: -1;
+    ref: React.RefCallback<HTMLElement>;
+  };
+}
+
+/** What a step renders: its body and, at most, two footer actions plus one tertiary. */
+export interface SequenceStep {
+  /** The body: item name (spread `titleProps` on it), question, facts, inputs. */
+  content: React.ReactNode;
+  /** The step's verb ("Save limits"). Omit for a step answered from its body (a list of reasons). */
+  primary?: SequenceAction;
+  /**
+   * The secondary action. Omitted, it is SKIP with `labels.skip`; pass one to
+   * reword it ("Not bought yet") or to replace it (a split mode's "One reason
+   * only"); `false` removes it.
+   */
+  secondary?: SequenceAction | false;
+  /** One text button above the footer ("It was a stock count, not a loss"). */
+  tertiary?: SequenceAction;
+  /**
+   * How the footer lays its actions out on a pointer: `'end'` (default) —
+   * auto-width, right-aligned, over a hairline; `'split'` — two equal
+   * full-width columns, no hairline (a form step: limits, a purchase). On a
+   * phone the actions always share the row, with no hairline.
+   */
+  footer?: 'end' | 'split';
+}
+
+/** One kind on the intro screen. */
+export interface SequenceCategory {
+  label: string;
+  description?: string;
+  /** How many problems of this kind there are. A kind at zero should not be listed. */
+  count: number;
+  /** Resolve only this kind: set the queue to it and drop `intro`. */
+  onPick: () => void;
+}
+
+/** The screen before the run: the kinds with their counts, and "resolve them all". */
+export interface SequenceIntro {
+  title: string;
+  description?: string;
+  categories: SequenceCategory[];
+  startAllLabel: string;
+  /** Resolve every kind: set the queue to all of them and drop `intro`. */
+  onStartAll: () => void;
+}
+
+/** The end screen's words. */
+export interface SequenceDone {
+  title: string;
+  description?: string;
+  /** The one button there; it closes the resolver. */
+  confirmLabel: string;
+}
+
+/** The chrome's words. The package ships none: every one is the host's. */
+export interface SequenceResolverLabels {
+  /** The back button's visible word ("Back"); a chevron icon precedes it. */
+  back: string;
+  /** The back button's accessible name, when it says more ("Back to the previous problem"). Must contain `back`. */
+  backAccessible?: string;
+  /** The close button's accessible name. */
+  close: string;
+  /** The default secondary action: leave the step unanswered. */
+  skip: string;
+  /** The header label on a step: `"Problem 3 of 13 · Purchase"`. `position` is 1-based. */
+  step: (position: number, total: number, item: SequenceItem) => string;
+  /** The header label on the intro screen. */
+  introStep: string;
+  /** The header label on the end screen. */
+  doneStep: string;
+  /** The progress bar's accessible name. */
+  progress: string;
+  /** Shown when `onBack` / a `resolve` promise rejects with no message of its own. */
+  failed: string;
+}
+
+export interface SequenceResolverProps<I extends SequenceItem = SequenceItem, R = unknown> {
+  open: boolean;
+  /**
+   * The close button, Esc, and the end screen's button. Gets where the run
+   * stood, for the host's "N resolved · Undo" toast.
+   */
+  onClose: (summary: SequenceSummary) => void;
+  /**
+   * While given, the intro screen shows instead of the run. The host drops it
+   * (and sets `queue`) in the same update as a category's `onPick` / `onStartAll`.
+   */
+  intro?: SequenceIntro;
+  /**
+   * The problems to walk, in order. The host's live data: it may shrink while
+   * the run goes (an answer that resolves siblings too) or grow; the run keeps
+   * pointing at the next unresolved key and never runs past the end.
+   */
+  queue: readonly I[];
+  /** The body and actions of the current step. */
+  renderStep: (item: I, api: SequenceStepApi<R>) => SequenceStep;
+  /**
+   * Undo the previous answer before showing its step again — the host's server
+   * inverse. Called only when the step being returned to was RESOLVED (a skipped
+   * one has nothing to undo). A rejection keeps the current step and shows its message.
+   */
+  onBack?: (item: I, result: R) => Promise<void> | void;
+  /** Offer the back button at all (default `true`). It shows only once a previous step exists. */
+  canGoBack?: boolean;
+  /** The end screen's words, from the run's summary. */
+  done: SequenceDone | ((summary: SequenceSummary) => SequenceDone);
+  labels: SequenceResolverLabels;
+  /**
+   * Base test id (default `sequence-resolver`). Parts get `${id}-back`,
+   * `${id}-close`, `${id}-step-label`, `${id}-progress`, `${id}-category-${index}`,
+   * `${id}-start-all`, `${id}-primary`, `${id}-secondary`, `${id}-tertiary`,
+   * `${id}-error`, `${id}-done`, `${id}-done-confirm`.
+   */
+  dataTestId?: string;
+}

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

@@ -0,0 +1,14 @@
+export { SequenceResolver } from './SequenceResolver';
+export type {
+  SequenceAction,
+  SequenceCategory,
+  SequenceDone,
+  SequenceIntro,
+  SequenceItem,
+  SequenceResolverLabels,
+  SequenceResolveOptions,
+  SequenceResolverProps,
+  SequenceStep,
+  SequenceStepApi,
+  SequenceSummary,
+} from './SequenceResolver.types';