Checkout Progress

1"use client";
2 
3import * as React from "react";
4import { motion, AnimatePresence, type Transition } from "motion/react";
5 
6import { cn } from "@/lib/utils";
7import {
8  useReducedMotion,
9  useAsyncStatus,
10  statusVars,
11  type StatusTone,
12} from "@/lib/motiq";
13 
14/* --------------------------------------------------------------------------
15 * CheckoutProgress — a presentation + orchestration surface for an app-owned,
16 * multi-STEP checkout flow (Cart → Customer details → Delivery → Billing →
17 * Payment → Review → Confirmation, or whatever steps the app defines). It shows
18 * where the shopper is, which steps are done and editable, which step needs
19 * attention, and drives navigation between steps.
20 *
21 * It is NOT a payment processor, a cart, or a full checkout page: it never
22 * collects card data, prices an order, charges anything, or talks to a payment
23 * provider. The host application owns every fact — the steps, their validity,
24 * blocked reasons, the order summary, and the actual save/submit work — and
25 * hands them in. The "Payment" step here is just another step whose completion
26 * the app reports; a real card field / payment element is the app's own
27 * `children` for that step, rendered through `renderStep`.
28 *
29 * What earns its keep over a row of numbered circles: editable completed steps
30 * (jump back to change an earlier answer), per-step validation with an error
31 * summary that links to the offending step, an app-owned blocked-step reason, an
32 * honest async "saving" state for a step (no fabricated progress bar), a
33 * checkout-level lifecycle (editing → validating → submitting → processing →
34 * completed | failed | cancelled), a sticky order-summary integration slot, a
35 * mobile compact summary, and fully controlled navigation callbacks.
36 *
37 * Accessibility: an ordered <ol> of steps with `aria-current="step"` on the
38 * active one; status is always conveyed by icon + text, never colour alone;
39 * blocked/invalid reasons are exposed to assistive tech; an error summary
40 * receives focus on an invalid advance; focus moves to the active step's
41 * heading after every step change; Previous/Next/Save are real keyboard-operable
42 * <button>s; ≥44px touch targets; a polite live region announces transitions;
43 * and under prefers-reduced-motion every transition renders in its final state.
44 * Clean-room original.
45 * ----------------------------------------------------------------------- */
46 
47// … truncated