@12-apps/ui 6.77.2 → 6.78.0

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';

package/src/components/feedback/SequenceResolver/sequence-model.ts

@@ -0,0 +1,181 @@
+import type { SequenceItem, SequenceSummary } from './SequenceResolver.types';
+
+/**
+ * THE RUN, as pure data: what was answered or passed over, and what is ahead.
+ *
+ * The queue is the host's live data, not a snapshot. An answer can resolve
+ * other entries with it (one limit saved for every sibling of a product), a
+ * refetch can drop the entry just answered, and a realtime push can add one —
+ * so the run is NOT an index into the queue. It keeps the visited steps in the
+ * order they were visited, and the steps still ahead in the order the queue
+ * gave them; `syncRun` reconciles the second list with each new queue.
+ */
+
+/** How a visited step was left. */
+export type Visit<I extends SequenceItem, R> =
+  | { item: I; outcome: 'resolved'; result: R; alsoResolved?: number }
+  | { item: I; outcome: 'skipped' };
+
+export interface RunState<I extends SequenceItem, R> {
+  /** Every step left behind, oldest first. Back pops the last one. */
+  visits: Visit<I, R>[];
+  /** The steps still ahead; the first is on screen. Empty means the end screen. */
+  ahead: I[];
+  /**
+   * The step whose answer is being written, kept ahead even while the queue
+   * lacks it (the host's refetch may drop it before the write returns).
+   * Cleared when the run leaves it.
+   */
+  pinned?: string;
+  /**
+   * The steps Back returned to, kept ahead while the queue lacks them (the
+   * host's inverse ran, its refetch has not put the entry back yet). A SET:
+   * two Backs before one refetch hold both. A key leaves it when the queue
+   * confirms the entry or the run leaves the step.
+   */
+  held: readonly string[];
+}
+
+function dedupe<I extends SequenceItem>(items: readonly I[], skip: ReadonlySet<string>): I[] {
+  const seen = new Set(skip);
+  const out: I[] = [];
+  for (const item of items) {
+    if (seen.has(item.key)) continue;
+    seen.add(item.key);
+    out.push(item);
+  }
+  return out;
+}
+
+/** A fresh run over `queue` (a repeated key counts once). */
+export function startRun<I extends SequenceItem, R>(queue: readonly I[]): RunState<I, R> {
+  return { visits: [], ahead: dedupe(queue, new Set()), held: [] };
+}
+
+/**
+ * The run against a new queue.
+ *
+ * - A step ahead that the queue no longer has is dropped — it was resolved
+ *   elsewhere (siblings answered together, another device) — unless it is
+ *   `pinned` or `held`.
+ * - A held key the queue has again is released: the host confirmed it.
+ * - A queue entry the run has not seen is appended, in queue order.
+ * - The entries kept are refreshed from the queue (same key, newer data).
+ * - Visited steps are history and never change.
+ */
+export function syncRun<I extends SequenceItem, R>(
+  state: RunState<I, R>,
+  queue: readonly I[],
+): RunState<I, R> {
+  const fresh = new Map(queue.map((item) => [item.key, item] as const));
+  const kept = state.ahead.flatMap((item) => {
+    const next = fresh.get(item.key);
+    if (next) return [next];
+    return item.key === state.pinned || state.held.includes(item.key) ? [item] : [];
+  });
+  const known = new Set([...state.visits.map((visit) => visit.item.key), ...kept.map((item) => item.key)]);
+  const held = state.held.filter((key) => !fresh.has(key));
+  return { ...state, ahead: [...kept, ...dedupe(queue, known)], held };
+}
+
+/** Keep `key` ahead whatever the queue says, until the run moves on (see {@link RunState.pinned}). */
+export function pinRun<I extends SequenceItem, R>(state: RunState<I, R>, key: string): RunState<I, R> {
+  return { ...state, pinned: key };
+}
+
+/** The step on screen, or `undefined` at the end. */
+export function currentOf<I extends SequenceItem, R>(state: RunState<I, R>): I | undefined {
+  return state.ahead[0];
+}
+
+/** The pins once the run leaves `key`: neither the write pin nor the held set keeps it. */
+function leaving<I extends SequenceItem, R>(state: RunState<I, R>, key: string): Pick<RunState<I, R>, 'pinned' | 'held'> {
+  return {
+    pinned: state.pinned === key ? undefined : state.pinned,
+    held: state.held.filter((held) => held !== key),
+  };
+}
+
+/**
+ * Answer `item` — the step that was on screen when the answer began (a pending
+ * write keeps it there, see {@link RunState.pinned}). An item no longer ahead
+ * was already answered (a double call): a no-op, as at the end.
+ */
+export function resolveRun<I extends SequenceItem, R>(
+  state: RunState<I, R>,
+  result: R,
+  item: I | undefined = state.ahead[0],
+  alsoResolved = 0,
+): RunState<I, R> {
+  if (!item || !state.ahead.some((entry) => entry.key === item.key)) return state;
+  const visit: Visit<I, R> = alsoResolved > 0 ? { item, outcome: 'resolved', result, alsoResolved } : { item, outcome: 'resolved', result };
+  return {
+    visits: [...state.visits, visit],
+    ahead: state.ahead.filter((entry) => entry.key !== item.key),
+    ...leaving(state, item.key),
+  };
+}
+
+/**
+ * Pass over the step on screen. Given the `key` that was on screen when the
+ * skip began, a step that has moved on since (a double call) is left alone. At
+ * the end it is a no-op.
+ */
+export function skipRun<I extends SequenceItem, R>(state: RunState<I, R>, key?: string): RunState<I, R> {
+  const [item, ...rest] = state.ahead;
+  if (!item || (key !== undefined && item.key !== key)) return state;
+  return { visits: [...state.visits, { item, outcome: 'skipped' }], ahead: rest, ...leaving(state, item.key) };
+}
+
+/** The step Back would return to, or `undefined` on the first one. */
+export function previousOf<I extends SequenceItem, R>(state: RunState<I, R>): Visit<I, R> | undefined {
+  return state.visits[state.visits.length - 1];
+}
+
+/**
+ * Return to the previous step: it is on screen again, ahead of the rest, and
+ * held until the queue confirms it. Given the `key` Back began from, a step
+ * already returned to (a double call) is left alone.
+ */
+export function backRun<I extends SequenceItem, R>(state: RunState<I, R>, key?: string): RunState<I, R> {
+  const last = previousOf(state);
+  if (!last || (key !== undefined && last.item.key !== key)) return state;
+  const ahead = state.ahead.filter((item) => item.key !== last.item.key);
+  // The step being left keeps no write pin: `pinned` is for a write in flight
+  // on the step ON SCREEN, and a failed one must not hold an entry the
+  // host's refetch has since dropped (it was applied server-side).
+  const leftKey = state.ahead[0]?.key;
+  return {
+    ...state,
+    pinned: state.pinned === leftKey ? undefined : state.pinned,
+    visits: state.visits.slice(0, -1),
+    ahead: [last.item, ...ahead],
+    held: [...state.held.filter((held) => held !== last.item.key), last.item.key],
+  };
+}
+
+/** Where the run stands. */
+export function summaryOf<I extends SequenceItem, R>(state: RunState<I, R>): SequenceSummary {
+  const resolved = state.visits.filter((visit) => visit.outcome === 'resolved').length;
+  const alsoResolved = state.visits.reduce(
+    (sum, visit) => sum + (visit.outcome === 'resolved' ? Math.max(0, visit.alsoResolved ?? 0) : 0),
+    0,
+  );
+  return {
+    alsoResolved,
+    resolved,
+    skipped: state.visits.length - resolved,
+    total: state.visits.length + state.ahead.length,
+  };
+}
+
+/** 1-based position of the step on screen (`total + 1` never happens: at the end it is `total`). */
+export function positionOf<I extends SequenceItem, R>(state: RunState<I, R>): number {
+  return Math.min(state.visits.length + 1, state.visits.length + state.ahead.length);
+}
+
+/** How far along, 0..100. An empty run is complete. */
+export function progressOf<I extends SequenceItem, R>(state: RunState<I, R>): number {
+  const total = state.visits.length + state.ahead.length;
+  return total === 0 ? 100 : Math.round((state.visits.length / total) * 100);
+}