# UI Phase 4 — Customer storefront

> **Mission:** turn home → search → results → nurse profile from functional screens into a **storefront that
> answers "would I let this person into my mother's home?"**. The data layer already fetches the trust signals
> (gender, completed visits, verification badge, ratings) — the UI drops most of them on the floor, ships a dead
> search bar, a fake sort control, a Gregorian date picker in a Shamsi product, and a primary CTA buried under an
> infinite review list. This phase fixes the funnel's honesty defects and builds the reusable trust-presentation
> components (`VerificationPanel`, the tappable `TrustBadge` explainer) that phase 8's public-profile preview reuses.
>
> **Track:** frontend · **Depends on:** [Phases 0–2](ui-phase-2-shells-and-navigation.md) ·
> **Unlocks:** [Phase 5 (booking funnel)](ui-phase-5-booking-lifecycle.md) + [Phase 8](ui-phase-8-nurse-business-and-verification.md) (reuses the trust components built here)
> **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 storefront is the four customer discovery screens: `client/src/app/[locale]/(private-routes)/(customer)/page.tsx`
(A5 home), `search/page.tsx` (C1 filters), `search/results/page.tsx` (C2 results), and
`search/nurse/[nurseId]/page.tsx` (C3 profile). Phases 0–2 already de-startered the theme, primitives, and chrome —
this phase redesigns the route tree itself. Diagnosed defects (all verified in code, full evidence in
[audit/customer-storefront.md](audit/customer-storefront.md)):

1. **The home search bar is a dead affordance.** `HomeSearchBar` pushes `?q=<query>` (page.tsx L130) but
   `SearchFilterScreen` reads only `category_id` (search/page.tsx L49–50) and silently discards `q`. The placeholder
   promises «جستجوی خدمت یا پرستار…» and the input does nothing.
2. **A failed patients query bricks the home forever.** The gate `if (data == null || isEmpty) return <AppLoading />`
   (page.tsx L66–68) has no `isError`/retry branch — a transient API failure leaves the app's front door on a spinner.
3. **The patient-record nudge renders unconditionally forever** (page.tsx L96–102), unlike the profile nudge which is
   gated on `hasCustomerProfile` (L103).
4. **The C1 visit-date filter is a native Gregorian `type="date"`** (search/page.tsx L104–110) in a product where
   every displayed date is Shamsi; the gender facet re-implements an inline `ToggleButtonGroup` (L86–100) instead of
   the shared `GenderToggle`; the live-count CTA is the last child of a long scrolling form (L130–140).
5. **C2 ships a fake sort** — a `TextField select` with one hard-coded `MenuItem`, `value="rating"`, no `onChange`
   (results/page.tsx L67–69) — and no filter recap: `backToFilters` renders only inside the EmptyState (L58/L88), so
   editing filters from a populated list means browser-back.
6. **`NurseResultCard` is information-thin.** The result row IS a bookable variant, but the card never names the
   service — three variants of one nurse render as identical cards differing only in price. `nurseGender` and
   `totalCompletedBookings` are **served by the real backend today** (REQ-012 delivered them onto the index row — see
   `services/search/apis/clientApi.ts` `NurseSearchResultDto`) and never rendered. The variant display name is a
   genuine wire gap: neither `NurseSearchResult` (types.ts) nor the DTO carries it.
7. **C3 doesn't read as a dossier.** The «درخواست رزرو» CTA is the last page child (nurse/[nurseId]/page.tsx L92–101)
   — below the infinite reviews list when that tab is open — and not sticky. `totalCompletedBookings` is fetched and
   never shown; `TrustBadge` is a static chip with no affordance to learn *what* was verified; and the profile DTO
   does **not** serve gender (`clientApi.ts` stubs `nurseGender: 'female'` with an "unused" comment — never render it).
8. **The empty-results copy is nonsense**: `search.empty_suggest_city` = «شهر نزدیک دیگری مانند مشهد، اصفهان یا شیراز
   را امتحان کنید» (fa.json L361) — a family cannot "try Shiraz"; the patient lives where they live.

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

- The search architecture: **the filter object IS the URL IS the React Query cache key**
  (`services/search/keys.ts` + `filterParams.ts`), `keepPreviousData`, debounced Toman price inputs, live count on C1.
- The **real** search backend (`USE_SEARCH_MOCK = false` since refinement-phase-4): the index row serves
  `nurseName`/`avatarUrl`/`distanceKm`/`nurseGender`/`totalCompletedBookings`; `GET nurses/{id}/profile` serves
  bio/years/services/latestReview.
- The public trust-badge read: `useNurseTrustBadge(nurseId)` → `GET nurses/{id}/trust_badge` →
  `{ isVerified, approvedAt, credentialTypes[] }` (`services/verification`) — real data for the explainer.
- Phase 0's theme/brand/icon registry; phase 1's primitives (EmptyState/ErrorState kit, PageHeader, `<Money>`,
  **Jalali date picker**, skeleton twins pattern, RatingInput v2 with honest fractional stars); phase 2's shells,
  safe-area-aware `BottomBar`, and contextual customer header. Consume them; never fork local variants.
- All four data states on C1/C2/C3, `ProfileSkeleton`, the honest «کل شهر» district semantics, `PriceDisplay` money
  rules, the gender facet's humane hint copy.

## 2. Required reading (do this first)

- [audit/customer-storefront.md](audit/customer-storefront.md) — the 21 problems + keep-list for this route tree.
- [audit/feature-components.md](audit/feature-components.md) — `NurseResultCard`/`TrustBadge` findings + the
  component-layer keep-list (presentational purity, caller-owned i18n, token discipline).
- The four pages under `client/src/app/[locale]/(private-routes)/(customer)/` listed above, plus
  `search/useSearchFilters.ts` and `services/search/{types.ts,filterParams.ts,apis/clientApi.ts}` — know exactly what
  the wire serves before deciding what needs a REQ.
- `client/src/components/{NurseResultCard,TrustBadge,GenderToggle,ServicePriceRow,PriceDisplay}/` — the components
  this phase owns or extends.
- `client/src/services/verification/types.ts` (`TrustBadge` wire type, `publicBadgeState`) and
  `hooks/useNurseTrustBadge.ts` — the explainer's data source.
- [../../../.claude/skills/frontend-designer/SKILL.md](../../../.claude/skills/frontend-designer/SKILL.md) — invoke it;
  and skim `client/CLAUDE.md` "Golden rules".
- Product rules: [../../../product/overview/platform-summary.md](../../../product/overview/platform-summary.md) (the
  four ground truths), [../../../product/business/04-search-and-matching.md](../../../product/business/04-search-and-matching.md)
  (verified-only, same-gender, variant-is-the-unit), and
  [../../../product/business/02-nurse-verification.md](../../../product/business/02-nurse-verification.md) (what the
  pipeline actually verifies — the explainer must narrate this truthfully).

## 3. Scope — build this

### 3.1 Customer home — a front door that works

- **Fix the dead search bar — decision: convert it into an honest search entry point.** Replace the free-text
  `TextField` with a tappable search affordance (a faux-input `ButtonBase` styled as the search field) that routes to
  C1 (`/search`), optionally focusing the category grid. *Why not client-side text match:* the index has no text
  column, variant names are not queryable client-side, and the only matchable dataset (5–6 cached category names) is
  already better served by the category grid directly below — a half-working text field over-promises exactly where
  trust matters. File the **text-search REQ** (`q` over nurse/variant/category names on `search/nurses`) so the bar
  can upgrade to a real typeahead when the backend serves it; note the upgrade path in the component's JSDoc.
- **Add the missing `isError` branch**: `usePatients()` failure renders the phase-1 `ErrorState` with retry — never an
  eternal spinner. Keep the onboarding redirect logic (`isEmpty` → onboarding) exactly as is.
- **Compact trust strip** under the greeting: three icon+label items — «پرداخت امن امانی» · «پرستاران تاییدشده» ·
  «پشتیبانی» — quiet, one row, tokens only. This is ambient reassurance, not a hero; keep it to one line on mobile.
- **Gate the patient-record NudgeCard on actual record incompleteness.** Derive a completeness signal from the cached
  patients data (e.g. a patient missing conditions/age — inspect `services/patients` types for what's derivable). If
  no honest signal is derivable client-side, show the nudge only when a patient list exists but a patient was never
  opened/completed — and make it dismissible (session-scoped) rather than permanent. Never a forever-nudge.
- **Rebook shortcut row**: source recent bookings from the existing `useBookingList('customer')` cache
  (`services/bookings`) and render up to 2 «رزرو دوباره با …» cards deep-linking to the nurse's C3 profile. Repeat
  care is the dominant pattern in home nursing. Render nothing (no empty state) when there are no past bookings.

### 3.2 Search (C1) — Persian-native filters, visible feedback

- **Replace the native `type="date"`** with the phase-1 Jalali controls: a horizontal day-chip strip — «امروز»،
  «فردا»، then day-name + Shamsi date chips for the next 7 days — plus an entry to the full Jalali picker for later
  dates. The value stays the same ISO string `dateIntent` the flow already carries (intent-only, never a hard filter
  — preserve that semantic and its hint copy).
- **Make the live-count CTA a sticky bottom bar**: «مشاهده N پرستار» pinned above the `BottomBar`, safe-area aware
  (compose with phase 2's safe-area handling — don't reimplement `env(safe-area-inset-bottom)` locally). The count is
  the screen's best feedback instrument; it must be visible while adjusting the upper filters.
- **Reuse the shared `GenderToggle`** instead of the divergent inline `ToggleButtonGroup`. `GenderToggle` is
  male/female-only by design (required, never defaulted — booking context); extend it with an **opt-in `allowAny`
  prop** (adds the «فرقی ندارد» option) rather than forking, keep the booking-context behavior unchanged, and update
  its co-located test for both modes.
- **Never render «مشاهده ۰ پرستار» as a tappable CTA.** When the live count is 0, the sticky bar shows a non-CTA
  message («پرستاری با این فیلترها یافت نشد») with the same relaxation hints as 3.6. Full ICU zero-case catalog sweep
  is (DEFERRED → [phase 12](ui-phase-12-copy-motion-and-polish.md)) — just don't ship the zero-CTA here.

### 3.3 Results (C2) — honest header, editable filters

- **Tappable filter-recap chip row** under the count: category · region (city/district or «کل شهر») · gender · price
  range — each chip deep-links back to C1 **with state preserved**. The filters already live in the URL
  (do-not-regress); C1 must initialize from the carried params, not just `category_id` — extend `useSearchFilters` to
  hydrate from a full `searchParamsToFilters` read.
- **Kill the fake sort.** Replace the single-option `TextField select` with a static caption «مرتب‌شده بر اساس
  امتیاز» (the contract's only MVP sort — `SearchSort = 'rating'`). Real sort options only if the API grows them
  (DEFERRED — do not file a REQ for sorts the product hasn't asked for).
- **Adopt skeleton twins**: replace the generic `Skeleton height={112}` rows with `NurseResultCard.Skeleton`
  (built in 3.4, following phase 1's twin pattern) so loading matches the card anatomy exactly.

### 3.4 `NurseResultCard` v2 — the decision card (this phase owns it)

Rebuild the card as the four-second decision unit, staying **presentational + memoized** with its co-located test:

- **Service/variant display name** — the row IS a variant; the card must name what is being bought. This field is
  missing from the wire (`NurseSearchResultDto` has no display name — verified): **file the REQ** to denormalize
  `variantDisplayName` onto the index row. Until it lands, render the row's category name (available via the cached
  catalog reference data, passed in by the page — the card stays data-agnostic) so multi-variant nurses are at least
  distinguishable by price row; switch to the served name when the REQ lands.
- **Nurse gender indicator** — load-bearing for same-gender matching; `nurseGender` is served today and never
  rendered. A quiet chip/glyph («خانم»/«آقا» styled per the design language), never color-only.
- **Completed-visits count** — `totalCompletedBookings` is served today; render «N ویزیت موفق» (fa digits). This
  carries more information than the uniform verified chip (every row is verified by invariant).
- **Optional top review tag** — one line, e.g. «منظم و دقیق», only if served. The index row carries no review tag
  (verified): file it as an optional field on the same index-row REQ; the card renders it conditionally.
- **`NurseResultCard.Skeleton`** static twin matching the new anatomy (avatar disc, name+badge row, meta row, price
  row).
- Keep: `memo`, stable `onSelect`, keyboard/focus a11y, `PriceDisplay` for money, `TrustBadge` for the badge.

### 3.5 Nurse profile (C3) — the trust dossier + the shared trust components

- **Header identity card**: large avatar, name, gender chip, years of experience, completed visits («N ویزیت موفق» —
  fetched today, never rendered), rating + count. The profile DTO does **not** serve gender (the client stub is a
  placeholder — never render it): **file the REQ** to add `nurseGender` to `NursePublicProfileDto`; until it lands,
  omit the gender chip on C3 (the C2 card and the carried `required_gender` param cover the matching flow honestly).
- **`VerificationPanel` — new shared component** (`src/components/VerificationPanel/`, barrel + test): "what
  Balinyaar verified" as a check-listed panel, fed by `useNurseTrustBadge(nurseId)` — verified state, `approvedAt`
  (Shamsi), and one row per `credentialTypes[]` entry (stable codes → i18n labels, never raw wire values). Render
  only what is served — no invented steps, no fake dates.
- **Tappable `TrustBadge` explainer**: give `TrustBadge` an opt-in `onClick`/expand affordance that opens a
  bottom-sheet (mobile) / dialog (desktop) narrating the verification story — «این پرستار این مراحل را گذرانده است…»
  — rendering the same `VerificationPanel` inside. The default (non-interactive) badge everywhere else is unchanged;
  update `TrustBadge.test.tsx`. Wire it up on C2 cards and C3. **File the REQ** for public per-step verification
  detail (step codes + decided dates) so the panel can list identity/Shahkar/license individually with dates; until
  then the panel shows the credential-type rows + the approval date — honest, served data only.
  These two are **REUSED by [phase 8](ui-phase-8-nurse-business-and-verification.md)'s public-profile preview — build
  them shared**, presentational, caller-fed.
- **Sticky «درخواست رزرو» bottom CTA** (same sticky-bar treatment as 3.2, price-from beside the button) so the CTA
  survives the infinite reviews list. Keep the carried variant/gender/date param handoff to f7 exactly as is.
- **Reviews tab polish**: aggregate header uses phase 1's RatingInput v2 (fractional — kill the `Math.round`
  overstatement at L260 by consuming the v2 API), review cards get the card-kit treatment. Rating-distribution bars
  are (DEFERRED → phase 12) unless trivially derivable from served data.
- Render the already-fetched `latestReview` snippet on the services tab if it improves the dossier — optional.

### 3.6 Empty-results copy — honest relaxation

Replace `empty_suggest_city` in **both** catalogs with honest relaxation suggestions the family can actually act on:
widen to the whole city («منطقه را خالی کنید تا کل شهر جست‌وجو شود» — keep/merge with the existing district line),
try other dates, remove the gender filter. Delete the «مشهد/اصفهان/شیراز» line. Reuse the same relaxation vocabulary
in the C1 zero-count bar (3.2). Final wording sweep is phase 12's; this phase removes the nonsense and lands
plausible copy in both `en.json`/`fa.json`.

**(DEFERRED)**: public/guest storefront and landing page (→ [phase 13](ui-phase-13-public-front-door.md));
save/favorite/share nurses (post-MVP, product decision); collapsing multi-variant nurses into one card (needs the
variant-name REQ served first — note it in the report as a follow-up); C1/C2 Suspense-fallback skeletons beyond what
phase 1's route-level `loading.tsx` already covers.

## 4. Mocks & seams in this phase

**None introduced.** Search and reviews are real (`USE_SEARCH_MOCK = false`); verification stays mock-primary but the
public `trust_badge` read flows through the existing `services/verification` seam either way — this phase only
consumes hooks. Backend gaps become REQ entries appended to
[../../shared-working-context/frontend/requests/for-backend.md](../../shared-working-context/frontend/requests/for-backend.md)
— **REQ-001…038 are taken; check the tracker for the next free number at execution time** (parallel UI phases also
file). Expected filings from this phase:

1. **Free-text search** — `q` param on `GET search/nurses` matching nurse/variant/category names (the home bar's
   upgrade path, 3.1).
2. **Index-row enrichment** — `variantDisplayName` (required) + optional `topReviewTag` on `NurseSearchResultDto`
   (3.4).
3. **`nurseGender` on `NursePublicProfileDto`** (3.5 header chip).
4. **Public verification-step detail** — per-step passed checks + decision dates on (or beside) the `trust_badge`
   payload (3.5 explainer depth).

The UI stays mock-tolerant: every new render is conditional on the field being served; nothing blocks on a REQ.

## 5. Critical rules you must not get wrong

- **Verified-only invariant.** Every returned row is verified by the search-index invariant; the UI **never
  re-filters or re-checks** verification and never fakes a badge state. The explainer *adds* narration to served
  truth — `TrustBadge`'s three honest states (verified/unverified/expired) and their server-driven derivation stay
  exactly as they are.
- **Never render placeholder data as truth.** The C3 profile's stubbed `nurseGender: 'female'` must not reach the
  screen; no invented verification steps or dates in the panel.
- **The filter-object-IS-the-URL-IS-the-query-key architecture stays.** Recap chips, C1 hydration, and the sticky CTA
  all read/write the same `filterParams` (de)serializer; deep-linking and back/forward cache hits must keep working.
- **Money rules**: amounts render only through `PriceDisplay`/the money util (BigInt IRR, Toman at the boundary);
  totals only ever price × sessionCount; never parse money to a float.
- **Same-gender facet care**: never defaulted, hint copy preserved, the chosen value carried into booking as before.
- **Design contract**: i18n keys in **both** catalogs; tokens not hexes (`--bal-*` / palette keys only); RTL logical
  props (`marginInlineStart`, `start`/`end`) — verify at `/fa` first; dark mode via tokens; MUI v9 API only; shared
  components (`VerificationPanel`, extended `TrustBadge`/`GenderToggle`/`NurseResultCard`) keep/get co-located tests;
  `clientFetch`/cookies/services rules untouched — this phase adds **no** fetch code outside existing hooks.
- **Ownership**: phase 0 owns `theme/`/`AppIcon`/`AppButton`; phase 1 owns the shared primitives (Jalali picker,
  RatingInput, state views, skeleton-twin pattern); phase 2 owns `layout/`. If a foundation gap blocks you (e.g. a
  missing icon or sticky-bar primitive), extend the foundation file **minimally** and note it in your report — never
  fork a local variant.

## 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/new tests for `NurseResultCard` (+ its
      Skeleton), `TrustBadge` (interactive mode), `GenderToggle` (`allowAny`), and `VerificationPanel`.
- [ ] `en.json`/`fa.json` in sync; «مشهد/اصفهان/شیراز» is gone from both.
- [ ] The home search affordance routes to C1; a failed patients query shows retry (kill the API to prove it); the
      record nudge no longer renders for a complete record; a customer with past bookings sees the rebook row.
- [ ] C1: Jalali day-chips replace the Gregorian input; the count CTA is sticky and never tappable at count 0; the
      gender facet is the shared `GenderToggle`.
- [ ] C2: recap chips deep-link back to C1 with **all** filters preserved (deep-link a full URL to prove hydration);
      no interactive-looking dead sort; skeleton twins during load.
- [ ] Cards show variant/category label, gender, completed visits; C3 has the sticky CTA, completed visits in the
      header, `VerificationPanel`, and tappable badges opening the explainer; no gender chip on C3 until the REQ lands.
- [ ] Visual verification on the four axes — `/fa` + `/en` × light + dark — and mobile + desktop for home, C1, C2,
      C3 (sticky bars must clear the BottomBar and the home-indicator safe area on mobile).
- [ ] REQs filed in the tracker with the next free numbers; no edits outside `client/` and the tracker/report files.

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

1. **Home**: log in as the seeded customer → the search bar tap opens C1 (no dead `?q=`). Stop the API and reload →
   an error card with «تلاش مجدد», not an eternal spinner. Restart → home recovers; trust strip visible under the
   greeting; a customer with a completed booking sees «رزرو دوباره با …».
2. **C1**: the date filter shows «امروز/فردا» + Shamsi day chips (no Gregorian browser calendar anywhere). Pick
   filters → the count CTA stays pinned at the bottom while scrolling; set filters matching nothing → the bar shows
   the no-results message and is not tappable.
3. **C2**: run a search → recap chips show category/region/gender/price; tap one → C1 opens with every filter
   pre-filled; browser-back returns to identical results with zero network (cache hit). The header reads «مرتب‌شده
   بر اساس امتیاز» as text, not a dropdown.
4. **Cards**: a nurse with multiple variants shows distinguishable cards (service label + price); every card shows
   gender and «N ویزیت موفق»; tapping the ✓ badge opens the verification bottom-sheet.
5. **C3**: open a profile → header shows completed visits + rating; `VerificationPanel` lists the served credential
   types + approval date (Shamsi); open the reviews tab and scroll deep → «درخواست رزرو» stays pinned; a 4.5 average
   renders as a fractional star row, not five full stars. Tap the CTA → the C4 request form receives the same
   nurse/variant/gender/date params as before.
6. Repeat 1–5 on `/en` (LTR) and in dark mode; on a mobile viewport confirm both sticky bars sit above the BottomBar.

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

- Update `client/CLAUDE.md` "Project Structure": the C1/C2/C3 line items (Jalali chips, sticky CTA, recap chips,
  dossier layout) and the new `VerificationPanel` component entry; note `TrustBadge`'s new interactive mode and
  `GenderToggle`'s `allowAny` on their lines.
- Write the report at `dev/shared-working-context/reports/ui-phase-4-report.md`: what changed per screen, the exact
  REQ numbers filed (text search, index-row enrichment, profile gender, public step detail), the home-search-bar
  decision + rationale, the multi-variant-collapse follow-up, and any foundation files you extended.
- Save a memory note per operating-rules §8: phase 4 owns `NurseResultCard`; `VerificationPanel` + the `TrustBadge`
  explainer are the shared trust components phase 8 consumes; the C3 profile DTO still lacks gender (placeholder
  field — never render it) until its REQ lands.