@12-apps/ui 6.86.2 → 6.87.0

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

@@ -1,94 +1,35 @@
-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,
+  stepScreenSx,
   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`}
-      />
-    </>
-  );
-}
+import type {
+  SequenceAction,
+  SequenceDone,
+  SequenceIntro,
+  SequenceStep,
+} from './SequenceResolver.types';
 
 /**
  * Moves focus to `target` (else `fallback`) whenever `screenKey` changes — and
@@ -102,6 +43,8 @@ export function useFocusOnScreen(
   fallback: React.RefObject<HTMLElement | null>,
 ): void {
   useEffect(() => {
+    // An empty key: the screen is kept but not showing, so it takes no focus.
+    if (!screenKey) return;
     (target.current ?? fallback.current)?.focus();
   }, [screenKey, target, fallback]);
 }
@@ -192,6 +135,12 @@ export function SequenceIntroBody({ intro, titleId, testId, screenKey }: IntroPr
 
 interface StepProps {
   step: SequenceStep;
+  /**
+   * Kept mounted under the overview, out of sight and out of the
+   * accessibility tree, so what the person half-filled in the host's step is
+   * still there when they continue. Focus returns to it when it shows again.
+   */
+  hidden?: boolean;
   /** The default secondary: skip. */
   skip: SequenceAction;
   busy: boolean;
@@ -230,16 +179,30 @@ function ActionButton({
   );
 }
 
+/** The step's footer: its secondary (skip by default; `false` for none) and its primary. */
+function StepFooter({ step, skip, busy, touch, testId }: Pick<StepProps, 'step' | 'skip' | 'busy' | 'touch' | 'testId'>) {
+  const secondary = step.secondary === false ? undefined : (step.secondary ?? skip);
+  if (!secondary && !step.primary) return null;
+  return (
+    <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>
+  );
+}
+
 /** 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 { step, skip, busy, error, touch, testId, screenKey, titleRef, hidden = false } = 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);
+  useFocusOnScreen(hidden ? '' : screenKey, titleRef, bodyRef);
+  useKeepFocusWhileBusy(busy && !hidden, bodyRef);
   return (
-    <>
+    <Box hidden={hidden} sx={stepScreenSx(hidden)} data-testid={`${testId}-step`}>
       <Box ref={bodyRef} tabIndex={-1} aria-busy={busy} sx={{ outline: 'none', minWidth: 0 }}>
         {step.content}
       </Box>
@@ -249,17 +212,8 @@ export function SequenceStepBody(props: StepProps): React.JSX.Element {
       {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}
-    </>
+      <StepFooter step={step} skip={skip} busy={busy} touch={touch} testId={testId} />
+    </Box>
   );
 }
 

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

@@ -236,3 +236,50 @@ export const doneTitleSx: SxProps<Theme> = {
   fontWeight: 500,
   outline: 'none',
 };
+
+/** The overview's title, in the header row where a step shows its label. */
+export const overviewTitleSx: SxProps<Theme> = {
+  fontSize: sxRem(SEQUENCE_METRICS.overviewTitle),
+  fontWeight: 500,
+  lineHeight: 1.3,
+  outline: 'none',
+  minWidth: 0,
+};
+
+/**
+ * One kind: its words take the width and its pick keeps its size on the right,
+ * a hairline under it. Where the words would have less than `overviewTextMin`
+ * beside the pick (a 320px phone), the pick drops under them, still at its
+ * content width, instead of the label breaking word by word.
+ */
+export const overviewRowSx: SxProps<Theme> = (theme: Theme) => ({
+  display: 'flex',
+  flexWrap: 'wrap',
+  alignItems: 'center',
+  columnGap: 1.5,
+  rowGap: 1,
+  py: 1.5,
+  borderBottom: '1px solid',
+  borderColor: 'divider',
+  '& > :not(button)': { flex: `1 1 ${rem(theme, SEQUENCE_METRICS.overviewTextMin)}`, minWidth: 0 },
+  '& > button': { flex: 'none' },
+});
+
+/** "Continue in sequence": start-aligned under a hairline, as the prototype draws it. */
+export const overviewFooterSx: SxProps<Theme> = {
+  display: 'flex',
+  justifyContent: 'flex-start',
+  pt: 2,
+  mt: 2,
+  borderTop: '1px solid',
+  borderColor: 'divider',
+};
+
+/**
+ * The step's own wrapper: no box of its own while it shows (its parts stay the
+ * body's flex items, keeping the body's gap and their height), nothing at all
+ * while the overview covers it.
+ */
+export function stepScreenSx(hidden: boolean): SxProps<Theme> {
+  return hidden ? { display: 'none' } : { display: 'contents', '& > *': { flexShrink: 0 } };
+}

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

@@ -3,14 +3,26 @@
 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 React, { useCallback, useId, useRef, useState } 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 { canReturn, currentOf, jumpTargetOf, positionOf, progressOf, summaryOf, type RunState } from './sequence-model';
+import {
+  SequenceDoneBody,
+  SequenceIntroBody,
+  SequenceStepBody,
+} from './SequenceResolver.parts';
+import { SequenceHeader } from './SequenceResolver.header';
+import { SequenceOverviewBody } from './SequenceResolver.overview';
 import { SEQUENCE_METRICS } from './SequenceResolver.metrics';
 import { chromeSx, columnSx, paperSx, scrollBodySx } from './SequenceResolver.styles';
-import type { SequenceItem, SequenceResolverProps, SequenceStepApi } from './SequenceResolver.types';
+import type {
+  SequenceItem,
+  SequenceOverviewCategory,
+  SequenceResolverProps,
+  SequenceStep,
+  SequenceStepApi,
+} from './SequenceResolver.types';
 import { useSequenceRun, type SequenceRun } from './useSequenceRun';
 
 /** What the header's label says on the screen showing. */
@@ -28,10 +40,90 @@ function headerLabelOf<I extends SequenceItem, R>(
 /** 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;
+  if (intro || !canGoBack || !canReturn(state.run)) return undefined;
   return { label: labels.back, accessible: labels.backAccessible, onClick: state.back, disabled: state.busy };
 }
 
+interface OverviewState {
+  /** The overview is on screen instead of the step. */
+  shown: boolean;
+  /** The header's "Ver todos (N)", while there is a step and more than one problem. */
+  button?: { label: string; onClick: () => void; disabled: boolean };
+  canPick: (category: SequenceOverviewCategory) => boolean;
+  pick: (category: SequenceOverviewCategory) => void;
+  hide: () => void;
+  /** The overview's title (in the header row): focus goes to it when it opens. */
+  titleRef: React.RefObject<HTMLHeadingElement | null>;
+}
+
+/**
+ * "Ver todos" inside the run: whether it shows, its header button, and its
+ * picks. Opening it changes nothing in the run; a pick jumps; "continue"
+ * returns to the step it left. Every opening of the resolver starts closed.
+ */
+function useOverview<I extends SequenceItem, R>(
+  props: SequenceResolverProps<I, R>,
+  state: SequenceRun<I, R>,
+  current: I | undefined,
+  open: boolean,
+): OverviewState {
+  const [shown, setShown] = useState(false);
+  const [wasOpen, setWasOpen] = useState(open);
+  const titleRef = useRef<HTMLHeadingElement | null>(null);
+  if (wasOpen !== open) {
+    setWasOpen(open);
+    if (shown) setShown(false);
+  }
+  const { overview } = props;
+  const total = summaryOf(state.run).total;
+  const available = Boolean(overview && current && total > 1);
+  const hide = (): void => setShown(false);
+  return {
+    shown: shown && available,
+    button:
+      available && overview
+        ? { label: overview.label(total), onClick: () => setShown(true), disabled: state.busy }
+        : undefined,
+    canPick: (category) => jumpTargetOf(state.run, category.keys) !== undefined,
+    pick: (category) => {
+      const target = jumpTargetOf(state.run, category.keys);
+      if (target === undefined) return;
+      state.jumpTo(target);
+      setShown(false);
+      category.onPick?.();
+    },
+    hide,
+    titleRef,
+  };
+}
+
+/** What the host's `renderStep` gets: the run's verbs, `busy`, and the props for its title. */
+function stepApiOf<I extends SequenceItem, R>(
+  state: SequenceRun<I, R>,
+  titleProps: SequenceStepApi<R>['titleProps'],
+): SequenceStepApi<R> {
+  return { resolve: state.resolve, skip: state.skip, back: state.back, jumpTo: state.jumpTo, busy: state.busy, titleProps };
+}
+
+interface HeaderInputs<I extends SequenceItem, R> {
+  props: SequenceResolverProps<I, R>;
+  state: SequenceRun<I, R>;
+  current: I | undefined;
+  overview: OverviewState;
+  titleId: string;
+}
+
+/** The header's back, "Ver todos" and label — or, over the overview, its title and close alone. */
+function headerOf<I extends SequenceItem, R>(inputs: HeaderInputs<I, R>) {
+  const { props, state, current, overview, titleId } = inputs;
+  const run = state.run;
+  const base = { label: headerLabelOf(props, run, current), progress: props.intro ? 0 : progressOf(run) };
+  if (overview.shown && props.overview) {
+    return { ...base, title: { id: titleId, text: props.overview.title, ref: overview.titleRef } };
+  }
+  return { ...base, back: backOf(props, state), seeAll: overview.button };
+}
+
 /**
  * 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
@@ -49,7 +141,9 @@ interface BodyProps<I extends SequenceItem, R> {
   props: SequenceResolverProps<I, R>;
   state: SequenceRun<I, R>;
   current: I | undefined;
-  api: SequenceStepApi<R>;
+  /** The step on screen, rendered once by the resolver (it also reads `canGoBack` from it). */
+  step: SequenceStep | undefined;
+  overview: OverviewState;
   titleId: string;
   stepTitleRef: React.RefObject<HTMLElement | null>;
   touch: boolean;
@@ -59,14 +153,15 @@ interface BodyProps<I extends SequenceItem, R> {
 
 /** 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;
+  const { props, state, current, step, overview, titleId, stepTitleRef, touch, testId, close } = body;
   if (props.intro) {
     return <SequenceIntroBody intro={props.intro} titleId={titleId} testId={testId} screenKey="intro" />;
   }
-  if (current) {
-    return (
+  const stepBody =
+    current && step ? (
       <SequenceStepBody
-        step={props.renderStep(current, api)}
+        key={`step:${current.key}`}
+        step={step}
         skip={{ label: props.labels.skip, onClick: state.skip }}
         busy={state.busy}
         error={state.error}
@@ -74,9 +169,30 @@ function SequenceBody<I extends SequenceItem, R>(body: BodyProps<I, R>): React.J
         testId={testId}
         screenKey={`step:${current.key}`}
         titleRef={stepTitleRef}
+        hidden={overview.shown}
       />
+    ) : null;
+  if (overview.shown && props.overview) {
+    // The step stays mounted under the overview, so a half-filled answer survives "continue".
+    return (
+      <>
+        <SequenceOverviewBody
+          key="overview"
+          categories={props.overview.categories}
+          canPick={overview.canPick}
+          onPick={overview.pick}
+          pickLabel={props.overview.pickLabel}
+          continueLabel={props.overview.continueLabel}
+          onContinue={overview.hide}
+          titleRef={overview.titleRef}
+          touch={touch}
+          testId={testId}
+        />
+        {stepBody}
+      </>
     );
   }
+  if (stepBody) return <>{stepBody}</>;
   const summary = summaryOf(state.run);
   return (
     <SequenceDoneBody
@@ -117,23 +233,25 @@ export function SequenceResolver<I extends SequenceItem, R = unknown>(
     stepTitleRef.current = node;
   }, []);
 
+  // Read when an answer is recorded: the step on screen's own `canGoBack`.
+  const stepAllowsBack = useRef(true);
   const state = useSequenceRun<I, R>({
     open,
     active: open && !intro,
     queue: props.queue,
+    initialKey: props.initialKey,
     onBack: props.onBack,
     failed: labels.failed,
+    stepAllowsBack: () => stepAllowsBack.current,
   });
-  const { run, busy } = state;
+  const { run } = 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 },
-  };
+  const overview = useOverview(props, state, current, open);
+  // Under the overview the step is kept but hidden, and the overview's title names the dialog.
+  const titleProps = { id: overview.shown ? `${titleId}-kept` : titleId, tabIndex: -1, ref: titleRef } as const;
+  const step = current ? props.renderStep(current, stepApiOf(state, titleProps)) : undefined;
+  stepAllowsBack.current = step?.canGoBack !== false;
 
   return (
     <Dialog
@@ -150,27 +268,26 @@ export function SequenceResolver<I extends SequenceItem, R = unknown>(
       <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}
+            touch={touch}
+            {...headerOf({ props, state, current, overview, titleId })}
+            closeLabel={labels.close}
+            onClose={close}
+            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}
+            props={props}
+            state={state}
+            current={current}
+            step={step}
+            overview={overview}
+            titleId={titleId}
+            stepTitleRef={stepTitleRef}
+            touch={touch}
+            testId={testId}
+            close={close}
           />
         </Box>
       </Box>

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

@@ -58,6 +58,12 @@ export interface SequenceStepApi<R> {
   skip: () => void;
   /** Return to the previous step (the header's back button does the same). */
   back: () => void;
+  /**
+   * Jump to the problem with this key, as the overview's "Resolver" does: the
+   * step on screen is passed over (Back from the target returns to it at once)
+   * and the target shows. An answered or unknown key does nothing.
+   */
+  jumpTo: (key: string) => void;
   /** True while a `resolve` promise or an `onBack` is pending — disable the step's own answers. */
   busy: boolean;
   /**
@@ -92,6 +98,12 @@ export interface SequenceStep {
    * phone the actions always share the row, with no hairline.
    */
   footer?: 'end' | 'split';
+  /**
+   * `false` marks this step's answer as having NO inverse: once it is answered,
+   * Back is not offered from the next step (default `true`). The resolver's own
+   * `canGoBack` still turns Back off everywhere.
+   */
+  canGoBack?: boolean;
 }
 
 /** One kind on the intro screen. */
@@ -114,6 +126,43 @@ export interface SequenceIntro {
   onStartAll: () => void;
 }
 
+/** One kind in the overview "Ver todos" opens inside the run. */
+export interface SequenceOverviewCategory {
+  label: string;
+  description?: string;
+  /**
+   * How many problems of this kind are still open — the host's bookkeeping
+   * (to drop a kind at zero, to write the label's "· N"). The overview does not
+   * draw it: the prototype says the number in the label ("Atrasado · 1").
+   */
+  count?: number;
+  /**
+   * The keys of this kind's problems. Its pick jumps to the first one still
+   * unanswered (ahead in the run, else one passed over); with none left the
+   * pick is disabled.
+   */
+  keys: readonly string[];
+  /** Called after the jump, for the host's own bookkeeping. */
+  onPick?: () => void;
+}
+
+/**
+ * "Ver todos (N)" inside the run: a header text button that shows every kind
+ * of problem with its count, a pick per kind that jumps there, and a button back
+ * to the step it left. The run is never ended or restarted by it.
+ */
+export interface SequenceOverview {
+  /** The header button's text, from the run's total ("Ver todos (2)"). */
+  label: (total: number) => string;
+  /** The overview's title ("2 problemas a resolver"). */
+  title: string;
+  categories: SequenceOverviewCategory[];
+  /** Each category's button ("Resolver"). */
+  pickLabel: string;
+  /** Back to the step the overview was opened from ("Continuar em sequência"). */
+  continueLabel: string;
+}
+
 /** The end screen's words. */
 export interface SequenceDone {
   title: string;
@@ -172,6 +221,13 @@ export interface SequenceResolverProps<I extends SequenceItem = SequenceItem, R
   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;
+  /**
+   * "Ver todos (N)" in the header of every step while the run has more than
+   * one problem: shows the kinds inside the dialog without ending the run.
+   */
+  overview?: SequenceOverview;
+  /** Open the run at this problem (a click on its block); the ones before it follow it. */
+  initialKey?: string;
   /** The end screen's words, from the run's summary. */
   done: SequenceDone | ((summary: SequenceSummary) => SequenceDone);
   labels: SequenceResolverLabels;
@@ -179,7 +235,8 @@ export interface SequenceResolverProps<I extends SequenceItem = SequenceItem, R
    * 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`.
+   * `${id}-error`, `${id}-done`, `${id}-done-confirm`, `${id}-see-all`,
+   * `${id}-overview`, `${id}-overview-pick-${index}`, `${id}-continue`.
    */
   dataTestId?: string;
 }

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

@@ -5,6 +5,8 @@ export type {
   SequenceDone,
   SequenceIntro,
   SequenceItem,
+  SequenceOverview,
+  SequenceOverviewCategory,
   SequenceResolverLabels,
   SequenceResolveOptions,
   SequenceResolverProps,