baya-monorepo/dev/post-phase/ui/ui-phase-5-booking-lifecycle.md

# UI Phase 5 — Booking lifecycle

> **Mission:** the request→track→booking→cancel→review flow is functionally rich but visually generic, and
> hides real defects: a confirm dialog whose **dismiss button carries the destructive action's own label**,
> required-field validation that is **provably dead code**, and a customer requests inbox
> (`useCustomerRequests`) **exported but wired to nothing** — a pending, money-adjacent request is orphaned
> once the user leaves C5. Make the lifecycle legible, calm, and trustworthy: the family always sees *who*
> they're inviting home, always has a way back to a pending request, and every terminal state offers recovery.
>
> **Track:** frontend · **Depends on:** [Phases 0–2](ui-phase-2-shells-and-navigation.md);
> [Phase 4](ui-phase-4-customer-storefront.md) recommended (funnel order) · **Unlocks:**
> [Phase 6](ui-phase-6-checkout-and-money.md) (checkout follows acceptance)
> **Before you start, read [../../phases/_shared/agent-operating-rules.md](../../phases/_shared/agent-operating-rules.md)
> and invoke the frontend-designer skill — both are mandatory.**

## 1. Context — where this sits

The booking lifecycle is the emotional core of the product: a family hands a stranger their patient's details
and home address, then waits on two countdowns (nurse response, then a 30-minute payment window). Every
screen already works — services real or contract-shaped, deadlines server-frozen, money display-only — but
the presentation is a default-MUI form stack that undersells the trust story and ships four verified defects
(all re-confirmed in code, 2026-07-16):

1. **The cancel-request dialog is mislabeled.** In `bookings/request/[id]/page.tsx` lines 223–225 the
   dismiss button renders `t('cancel_request')` («انصراف از درخواست») — the destructive action's own label —
   next to the real destructive `cancel_confirm_yes`; users who want to cancel click the button that keeps
   the request.
2. **C4's inline errors are unreachable.** `setAttempted(true)` runs only inside `handleSubmit` (line 128)
   while submit is `disabled={!requiredChosen || …}` (line 439), so `error={attempted && …}` (line 230 etc.)
   never renders; the only feedback for an incomplete form is a silently disabled button.
3. **A pending request is unreachable once you leave C5.** `useCustomerRequests` is exported from
   `services/bookingRequests` and consumed by **zero** pages (grep: only `index.ts` + its own hook file);
   `bookings/page.tsx` lists only post-payment bookings; the bottom nav has no requests entry.
4. **The family never sees who they're inviting home.** C4 fetches `useNurseProfile` (line 61) but renders no
   nurse name, avatar, rating, or badge — the profile is used only for the gender-mismatch check.

Also verified: the bookings list calls `useBookingList('customer')` with no `page` param though the hook
paginates — booking #21 is unreachable; C4 keeps a native Gregorian `type="date"` (line 336), a
`pointerEvents: 'none'` fake-map preview (line 317), and negative-margin stitching (lines 272/424);
`BookingRequestSummaryCard.tsx` builds `whenLabel` (line 60) with no bidi isolation while
`SessionCard.tsx:99` wraps its identical range in `dir="ltr"`; the review page fires `useMyReviewForBooking`
ungated (line 43) though the hook accepts `{ enabled }`; the cancel page pre-defaults its reason to
`'changed_mind'` (line 58); `BookingDetailView.tsx:92` reuses the `unnamed_nurse` *fallback* key as the
nurse field *label*.

**What already exists (do not rebuild):**

- The full functional flow: C4 form, C5 tracker, bookings list + detail, cancel flow with
  `CancellationPolicyDisclosure`, refund status, review page — and the service layer beneath it:
  `services/bookingRequests` (incl. the unused `useCustomerRequests`), `services/bookings` (paginated
  `useBookingList`, sessions/EVV), `services/refunds`, `services/reviews` (`useReviewEligibility`,
  `useMyReviewForBooking` with an `enabled` option), `services/tickets`.
- Phase 1's primitives: CountdownTimer v2 (progress ring), the vertical `StatusTimeline`, StatusChip v2
  (soft tints), the Jalali date picker, `<Money>`, skeleton twins, EmptyState/ErrorState. **Consume these;
  never fork a local variant** (README ownership rules). Phase 4's trust components (`TrustBadge` patterns,
  NurseResultCard v2, rating display).
- The do-not-regress architecture: server-frozen deadlines, two-stage disclosure gate, honest refund copy,
  advisory EVV, shaped skeletons (§5).

## 2. Required reading (do this first)

- [audit/booking-lifecycle.md](audit/booking-lifecycle.md) — the 19 problems, 10 opportunities, and
  keep-list this phase is built from, with file/line evidence.
- Code — read before touching, under `client/src/app/[locale]/(private-routes)/(customer)/bookings/`:
  `request/page.tsx` (C4), `request/[id]/page.tsx` (C5), `page.tsx` (list), `[id]/page.tsx`,
  `[id]/cancel/page.tsx`, `[id]/review/page.tsx`. Components: `booking/BookingDetailView/`,
  `BookingRequestSummaryCard/`, `booking/SessionCard/` (the `dir="ltr"` precedent), `CountdownTimer/`.
  Services: `services/bookingRequests/hooks/useCustomerRequests.ts`,
  `services/bookings/hooks/useBookingList.ts` (it already paginates).
- Phase 1's report (`dev/shared-working-context/reports/ui-phase-1-report.md`) for the exact APIs of
  CountdownTimer v2, StatusTimeline, StatusChip v2, the Jalali picker.
- `.claude/skills/frontend-designer/SKILL.md` — the design contract (invoke the skill, don't just read it).
- Product rules: [product/business/05-booking-and-scheduling.md](../../../product/business/05-booking-and-scheduling.md)
  (request lifecycle, deadlines, two-stage disclosure),
  [product/business/07-cancellation-and-refunds.md](../../../product/business/07-cancellation-and-refunds.md)
  (policy tiers — the disclosure copy is product-mandated),
  [product/business/11-reviews-trust-and-safety.md](../../../product/business/11-reviews-trust-and-safety.md)
  (moderation-before-publish), [product/business/06-evv-and-service-delivery.md](../../../product/business/06-evv-and-service-delivery.md)
  (EVV is advisory, never blocking).

## 3. Scope — build this

### 3.1 C4 request form — a trust-anchored request, not a form stack

`bookings/request/page.tsx`:

- **Sticky nurse identity summary** at the top: avatar, name, rating + review count, `TrustBadge`, gender —
  all already available from the fetched `useNurseProfile` (line 61). The family must always see who they're
  inviting home. Compose from phase-4's card anatomy; compact and sticky on mobile scroll.
- **«چه اتفاقی می‌افتد؟» strip** — a 3-step visual (درخواست → پاسخ پرستار → پرداخت امن) reinforcing the
  money-free promise already in `form_subtitle`; use phase 1's step primitives, no new one-off stepper.
- **Jalali picker + time-window chips** replacing the native Gregorian `type="date"` (line 336) and free
  time fields: phase 1's Jalali date picker plus tappable window presets (صبح ۸–۱۲ / بعدازظهر ۱۲–۱۶ /
  عصر ۱۶–۲۰) with a «زمان دلخواه» custom option that reveals the time fields — presets kill the end≤start
  error class for most users. Nurse-availability hints on the picker are (DEFERRED → needs a backend
  availability read; file a REQ only if you build the seam now).
- **Fix the dead validation:** switch to touched-on-blur field errors **plus** a disabled-CTA explainer — a
  one-line caption under the disabled submit listing what's missing («برای ادامه: انتخاب بیمار، تاریخ»).
  Delete the unreachable `attempted`-only branches. Keep the gender-mismatch inline block exactly as is.
- **Replace the fake-map preview** (lines 315–327, `pointerEvents: 'none'` around `AddressMapPicker`) with a
  compact address row: icon, title, one-line street text, an «تغییر» affordance back to the select — the
  grid-canvas stand-in communicates nothing and eats vertical space.
- **Remove the negative-margin hacks** (`mt: -1.5` line 272, `mt: -2` line 424) — group price-under-select
  and counter-under-notes with real composed containers (Stack spacing), so helper text can't collide.

### 3.2 C5 tracker — a calm wait with a way out

`bookings/request/[id]/page.tsx`:

- **Countdown as the phase-1 progress ring** with humanized framing: the ring shows the fraction of the
  response window remaining ((deadline − createdAt), server fields only — the client never recomputes the
  deadline, §5); above ~10 minutes remaining render «حدود ۳ ساعت» instead of per-second digits, switching to
  precise digits in the final minutes. Add a one-line «نتیجه را اطلاع می‌دهیم» note so users feel safe leaving.
- **FIX the cancel-request dialog defect** (lines 223–225): the dismiss button must never carry the
  destructive label. Adopt a clear confirm convention — destructive: «بله، انصراف از درخواست» (error,
  contained); dismiss: «نه، نگه دار» (text, neutral) — and apply it to every confirm dialog you touch.
- **Terminal-state recovery:** rejected/expired cards currently funnel to generic search. When the rejection
  reason permits (not gender/coverage), offer «درخواست دوباره با زمان دیگر» — C4 reopened prefilled with the
  same nurse/variant/patient/address (extend the query params C4 already accepts from C3) — plus a
  «پرستاران مشابه» entry (same service + area) into existing search. Recover the intent, not from zero.

### 3.3 Customer requests visibility — /bookings becomes the lifecycle home

`bookings/page.tsx`:

- **Segmented tabs:** «در انتظار پاسخ» / «فعال» / «گذشته». The pending tab finally wires the
  exported-but-unused `useCustomerRequests` — rows show the nurse name, requested Shamsi slot, and a **live
  mini-countdown chip** (compact CountdownTimer v2); accepted-awaiting-payment rows make the payment deadline
  the primary CTA. Rows deep-link to C5.
- **Pagination:** the list renders page 1 only while `useBookingList` already accepts `{ page, pageSize }`
  and returns `total`. Add a pager (or load-more, matching the C2 results pattern) with locale digits.
- **Status-accent rows:** a soft `StatusChip` (phase 1's soft-tint system) plus a status-colored
  `borderInlineStart` accent per row so a page of bookings ranks visually without reading every chip.
- **Rows fully tappable** — the whole row navigates (keyboard-focusable, `role`/`aria` correct), not just
  the small button; give the error branch a retry and the empty state a CTA into search.

### 3.4 Booking detail — a hero that answers where/when/who

`components/booking/BookingDetailView/BookingDetailView.tsx` (+ detail page):

- **Next-upcoming-session headline** («ویزیت ۲ · فردا ۹:۰۰» — derived from the served sessions,
  display-only), the visit address, nurse avatar with a support entry (reuse `BookingSupportEntry`), and
  **add-to-calendar** — a client-side `.ics` download for the next session (no backend; Gregorian UTC in the
  file, Shamsi in the UI).
- **Adopt phase 1's vertical `StatusTimeline`** in place of the horizontal `StepperHeader` usage — per-stage
  icons, timestamps where the server provides them, terracotta marker on the current stage, distinct terminal
  branch. The timeline remains server truth: never advance a step client-side.
- **EVV as a presence state:** elevate the existing advisory EVV data into a headline on the detail («پرستار
  در محل است · ورود ۰۹:۰۲») and a compact indicator on the in-progress list row. Keep the tri-state semantics
  (in-range / out-of-range warning / no-GPS neutral) — never error-toned, never blocking.
- **Session list polish:** align session cards to the phase-1 card anatomy; keep SessionCard's `dir="ltr"`
  isolation. Fix the `unnamed_nurse` key misuse (line 92) — add a proper `bd_nurse_label` key and leave
  `unnamed_nurse` as the fallback value it was written to be.

### 3.5 Cancel flow — off-ramps before the kill switch

`bookings/[id]/cancel/page.tsx`:

- **Keep the policy disclosure untouched** — `CancellationPolicyDisclosure` (tier, refund %/fee %,
  reconciled Toman split, per-session refundable/locked, acknowledgement checkbox) is do-not-regress.
- **Add off-ramps above the disclosure:** «تغییر زمان» — opens a support ticket via the existing
  `ContactSupportDialog`/tickets service, pre-categorized `coordination`; real rescheduling is (DEFERRED →
  product decision + backend) — and «گفتگو با پشتیبانی», plus one human line about nurse impact. The
  destructive path stays fully available — these are exits, not obstacles.
- **Do not pre-default the reason:** replace `useState<CancelReasonCategory>('changed_mind')` (line 58) with
  an empty placeholder state; confirm stays disabled until a reason is chosen. Keeps the analytics honest.

### 3.6 Review flow — context and expectations up front

`bookings/[id]/review/page.tsx` + the bookings-list row:

- **Context recap header:** service name, Shamsi visit date, nurse name/avatar (from the cached booking
  detail — no new fetch) so the user knows exactly what they're reviewing.
- **Moderation expectation note up front:** «نظر شما پس از بررسی منتشر می‌شود» before submit, not only in the
  post-submit state — moderation-before-publish is a product rule the UI should disclose early.
- **Post-completion star-strip CTA on the list row:** a completed booking without a review shows a compact
  RatingInput-styled strip on its /bookings row deep-linking into the review page (the eligibility +
  my-review hooks exist; gate the extra queries to completed rows only).
- **Fix the ungated hook call:** pass `{ enabled }` to `useMyReviewForBooking` on the review page (line 43)
  exactly as the detail page gates it — the hook already accepts the option.

### 3.7 Misc verified defects

- **Bidi-isolate `BookingRequestSummaryCard`'s `whenLabel`** (line 60/123): wrap the time-range segment in a
  `dir="ltr"` span with tabular-nums, exactly matching `SessionCard.tsx` line 99. This is a shared, tested
  component — update `BookingRequestSummaryCard.test.tsx` accordingly.
- The «ادامه پرداخت ←» arrow-in-string CTA (fa/en `continue_payment`) is **phase 12's catalog sweep** — note
  it in your report; removing the arrow on strings you already touch is fine, but don't sweep copy-wide here.

## 4. Mocks & seams in this phase

**None introduced.** Every deliverable is client-side over existing seams: `useCustomerRequests`,
`useBookingList` pagination, and the review hooks already exist; the `.ics` file is generated in the browser;
the «تغییر زمان» off-ramp rides the existing tickets service. `bookingRequests`/`bookings`/`reviews` run
real (de-mocked in refinement-phase-4) — build against the real wire, UI mock-tolerant behind the seams.

**REQ posture:** if a deliverable surfaces a genuine backend gap (a rejection-reason code C5's recovery logic
needs, nurse-availability for the time chips), append a REQ to
[for-backend.md](../../shared-working-context/frontend/requests/for-backend.md) — **REQ-001…038 are taken
(tracker verified); number from REQ-039** — and ship degraded-gracefully. Never edit `server/`.

## 5. Critical rules you must not get wrong

From the audit keep-list (all currently true in code — regressions fail this phase):

1. **Server-truth discipline.** `CountdownTimer` never computes or extends a deadline — the ring is
   presentation over server-frozen instants; timelines never advance a step client-side; money stays
   display-only IRR digit-strings via the money utils — never summed or re-split.
2. **Two-stage disclosure is a hard UI gate.** The customer's care-instructions query **never fires**
   (`useCareInstructions` stays enabled-gated to the nurse on confirmed+); keep the BookingDetailView test
   proving it.
3. **Honest cancel/refund copy stays.** The full pre-confirm disclosure, the acknowledgement checkbox, the
   failed-refund state that suppresses all success framing, and the BNPL 7–10-day ETA are product-mandated.
4. **Gender preference stays first-class.** Never silently defaulted; the inline mismatch block stays; the
   culturally-tuned hint copy is untouched.
5. **EVV stays advisory.** Out-of-range is warning-toned, no-GPS neutral, never blocking — the presence
   headline is a positive reframe, not a new gate.
6. **Skeletons stay shaped like content.** Every redesigned layout updates its skeleton twin in the same
   change — no spinner-only regressions.

Design-contract non-negotiables that bite here: i18n keys in **both** catalogs (this phase adds many);
tokens/palette only, never hexes (soft chips use the phase-0/1 `--bal-*-soft` tokens); RTL logical props
(`borderInlineStart` accents, `dir="ltr"` islands for times/digits); dark mode on every new surface; MUI v9
API only; changed shared components keep/gain co-located tests; fetch/cookies rules untouched.

## 6. Definition of Done

On top of the shared [definition-of-done.md](../../phases/_shared/definition-of-done.md):

- [ ] `npm run check` green; `npm run test:ci` green including updated tests for every touched shared
      component (`BookingRequestSummaryCard`, booking composites, new list-row components);
      `en.json`/`fa.json` in sync.
- [ ] Cancel-request dialog: dismiss reads «نه، نگه دار», destructive reads «بله، انصراف از درخواست» — the
      dismiss button never carries a destructive label anywhere in the flow.
- [ ] C4: nurse identity summary renders; blurred-empty required fields show inline errors; the disabled CTA
      explains what's missing; no Gregorian `type="date"`, fake-map preview, or negative-margin stitching.
- [ ] /bookings: three tabs; pending tab lists live requests with mini-countdowns deep-linking to C5; a list
      of >20 bookings is fully reachable via the pager; rows fully tappable with status accents.
- [ ] Booking detail: next-session hero with address + `.ics` download; vertical StatusTimeline (no
      horizontal stepper); EVV presence headline while checked-in.
- [ ] Cancel page: reason select starts empty (confirm disabled until chosen); both off-ramps present;
      `CancellationPolicyDisclosure` byte-identical in behavior.
- [ ] Review page: context recap + up-front moderation note; `useMyReviewForBooking` gated with `enabled`;
      completed list rows show the star-strip CTA.
- [ ] Visual verification on all four axes — `/fa` + `/en` × light + dark — and mobile + desktop for C4, C5,
      /bookings, booking detail (`/fa` mobile first: the primary user).

## 7. How to test (what a human can verify after this phase)

1. From a nurse profile (C3) tap «درخواست رزرو» → C4 shows the sticky nurse card and the 3-step strip. Blur
   the empty patient select → inline error; the disabled CTA lists the missing fields.
2. Pick a date from the **Jalali** picker and tap the «صبح» chip → times fill; choose «زمان دلخواه» → custom
   time fields appear. The address select shows a compact text row, not a grid canvas.
3. Submit → C5 shows the countdown progress ring with «حدود …» framing. Tap «انصراف از درخواست» → the
   dialog's keep-button reads «نه، نگه دار» and keeps the request; «بله، انصراف از درخواست» cancels it.
4. Leave C5 → /bookings «در انتظار پاسخ» tab shows the pending request with a live mini-countdown; the row
   returns to C5. Reject/expire a request (dev sim) → the terminal card offers «درخواست دوباره با زمان
   دیگر» (C4 opens prefilled) and «پرستاران مشابه».
5. With >20 bookings seeded, page 2 is reachable and booking #21 opens. Rows are tappable end-to-end; each
   carries a soft status chip + matching inline-start accent.
6. Open an active booking → hero shows «ویزیت … · <Shamsi>», the visit address, nurse avatar, support entry,
   a working `.ics` download, and a vertical timeline. Check a nurse in (dev EVV) → detail and list row show
   «پرستار در محل است · ورود …».
7. Start a cancellation → reason select is empty and confirm disabled; the off-ramps open a support ticket /
   support chat; completing the flow shows the unchanged policy disclosure and acknowledgement gate.
8. Open a completed booking's /bookings row → star-strip CTA → review page shows the service/date/nurse recap
   and «نظر شما پس از بررسی منتشر می‌شود» before submit. Repeat 1–8 spot-wise on `/en` (LTR) and in dark
   mode: `BookingRequestSummaryCard` time ranges read start–end both directions; no stock-MUI colors appear.

## 8. Hand off & document (close the phase)

- Update `client/CLAUDE.md` **Project Structure**: the /bookings entry (tabs + wired `useCustomerRequests` +
  pagination), the C4/C5 descriptions, and any new shared components under `components/(booking/)`.
- Write the report at `dev/shared-working-context/reports/ui-phase-5-report.md`: what changed per scope item,
  the defects fixed (dialog labels, dead validation, orphaned inbox, ungated hook, bidi label), REQs filed
  (REQ-039+, appended to [for-backend.md](../../shared-working-context/frontend/requests/for-backend.md) in
  the standard entry shape — or "none"), and the phase-12 note (arrow-in-string CTA sweep).
- Save a memory note per operating-rules §8: the lifecycle redesign decisions (tabs model, recovery paths,
  presence state), the confirm-dialog labeling convention now in force, and what phase 6 (checkout) should
  know about the accepted-request → payment handoff surfaces you touched.