baya-monorepo/archive/post-phase/ui/ui-phase-1-primitives-and-states.md

# UI Phase 1 — Shared primitives & app-wide states

> **Mission:** build the shared component kit the pages keep hand-rolling — state views, page header, confirm
> dialog, card anatomy, `<Money>`, locale formatting, a Jalali date picker, status/timeline/countdown/rating
> upgrades, skeleton twins — give the app real route-level chrome (loading / error / 404 / per-route metadata),
> and fix the error→false-empty defects the missing kit caused. This phase **owns every shared primitive**
> (see the [README ownership rules](README.md)); phases 3–11 only consume what ships here.
>
> **Track:** frontend · **Depends on:** [Phase 0](ui-phase-0-design-language.md) (theme pass, icon family,
> `--bal-money-emphasis` / `--bal-rating*` / elevation / motion / focus tokens) · **Unlocks:** the kit every
> area redesign (phases 3–11) composes from
> **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

Balinyaar's feature layer is disciplined (tokens, RTL, four-state data pattern), but the *page primitives*
were only ever built for the backoffice. Everything user-facing is hand-rolled per page, so the app reads as
a starter and every restyle is a 20-file change. Verified in code:

- **29 hand-rolled dashed-border `Paper` empty/error blocks across 23 files** (grep `border: '1px dashed'`),
  while `AdminEmptyState`/`AdminErrorState` sit unused outside `components/admin/`.
- **24 hand-assembled `formatIrrToToman(x) + t('currency_toman')` sites across 19 files**; `PriceBreakdown.tsx:62`
  colors the grand total terracotta (`--bal-secondary`, ≈2.7:1 on white — a WCAG failure on the most
  trust-critical number), a pattern repeated across five sibling money components.
- **23 copies of the `locale === 'fa' ? 'fa-IR' : 'en-US'` ternary across 15 files**, already drifting
  (`admin/partners/[id]/page.tsx` passes the raw locale); **no relative-time formatting anywhere**; the OTP
  resend clock renders Latin digits (`components/auth/OtpStep.tsx:27`).
- **Zero `loading.tsx` / `error.tsx` / `not-found.tsx` / `global-error.tsx`** under `client/src/app`; the only
  crash UI is the starter `ErrorBoundary` (English `<h2>`, raw `componentStack` dump); one static `<title>`
  serves ~60 routes; **no Jalali date input** — every date input is a native Gregorian `type="date"`.
- **The missing kit caused real defects.** A failed query renders as *success-with-no-data*:
  - `(customer)/page.tsx:57–68` — the page gate destructures only `data` from `usePatients()`; on error it
    returns `<AppLoading />` forever (spinner-hang). The `CategoryGrid` in the same file branches all four
    states correctly — the discipline exists, the gate doesn't.
  - `(customer)/patients/page.tsx:83` (`isEmpty = !isLoading && …length === 0` → error shows «no patients»);
    `nurse/requests/page.tsx:19` (error = empty inbox); `nurse/services/MyServicesList.tsx:37,42` (error =
    «add your first service» CTA).
  - `(customer)/profile/page.tsx:16` — an errored profile renders a **blank form** whose save could overwrite
    server truth; `nurse/services/VariantBuilder.tsx:384` — `optionGroupsQuery` has no error branch, so failed
    option groups are treated as "category has none", letting a nurse skip required options.
- **Silent mutations:** `nurse/profile/page.tsx:44` (avatar upload) and `:54–64` (profile save) pass only
  `onSuccess` — a failure gives zero feedback.

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

- The admin primitives to *promote*, not rewrite (all in `client/src/components/admin/`, all tested):
  `AdminPageHeader` (title/subtitle/actions, caller-owned i18n), `AdminEmptyState`/`AdminErrorState`,
  `ConfirmDialog` (required-reason gating + busy-disable).
- `utils/money.ts` (BigInt IRR↔Toman, fa digits) and `utils/date.ts` (Shamsi via `Intl` `fa-IR-u-ca-persian`,
  no date library); `CountdownTimer`'s architecture — server-frozen UTC deadline prop, self-owned 1s tick
  (only it re-renders), single `onElapsed` fire, `dir="ltr"` tabular-nums locale digits (`CountdownTimer.tsx:84`).
- `StatusChip` as the single status color+icon source seven components delegate to; the exhaustive typed
  enum→chip mappings; `TrustBadge`'s honest three states; the four-state pattern itself (~95 `isError`
  branches, ~124 retries) — restyle and fill gaps, don't rebuild; the `dispatchToast → notistack` pipeline.
- Phase 0's output: `theme.components` pass, one icon family, the new tokens. Build on them.

## 2. Required reading (do this first)

- [audit/component-primitives.md](audit/component-primitives.md) (kit inventory, hand-roll counts),
  [audit/feature-components.md](audit/feature-components.md) (card-anatomy drift, rating/terracotta/timeline
  defects), [audit/cross-cutting-ux.md](audit/cross-cutting-ux.md) (route chrome / metadata / formatting) —
  each carries the full evidence and a keep-list.
- [.claude/skills/frontend-designer/SKILL.md](../../../.claude/skills/frontend-designer/SKILL.md) — the design
  contract; and `client/CLAUDE.md` — Golden rules, Project Structure, Unit Testing, Toast Notifications, i18n.
- Code to read before writing: `client/src/components/admin/{AdminPageHeader,AdminEmptyState,AdminErrorState,ConfirmDialog}.tsx`;
  `client/src/components/{StatusChip,CountdownTimer,RatingInput,StepperHeader,RefundStatusCard,PriceBreakdown}/`;
  `client/src/components/booking/BookingStatusTimeline/`; `client/src/utils/{money,date}.ts`;
  `client/src/lib/api/client.ts` (which errors the fetch layer already toasts — 3.14 builds on it);
  `client/src/theme/tokens.css` as phase 0 left it. Product framing: `product/overview/platform-summary.md`
  (money display and Shamsi correctness are product rules, not preferences).

## 3. Scope — build this

New shared components live under `client/src/components/common/<Name>/` (component + `index.tsx` barrel +
co-located `.test.tsx`), exported from `@/components`, presentational with **caller-owned i18n** (already-
translated strings in, like `AdminPageHeader` documents). Strings a component *does* own (route chrome,
default retry labels) go in **both** `messages/en.json` and `messages/fa.json`.

### 3.1 State kit — `EmptyState`, `ErrorState`, `QueryStateGate` + the false-empty fixes

- Promote/generalize `AdminEmptyState`/`AdminErrorState` into shared `EmptyState` and `ErrorState` with a
  branded look (phase 0 surface/radius tokens; registry icon slot; calm — retire the dashed border).
  `EmptyState`: icon, title, body, optional CTA. `ErrorState`: **`onRetry` is required** («تلاش دوباره»).
  `components/admin` keeps thin wrappers or its call sites migrate — either way no duplicated implementation
  remains. (Custom illustration set: DEFERRED → phase 12.)
- Add a small `QueryStateGate` (props: `isLoading`, `isError`, `onRetry`, `isEmpty`, `skeleton`, `empty`,
  `children`) rendering skeleton → error → empty → data in that order, **plus** write the convention into
  `client/CLAUDE.md`: *an errored query must never render as empty; every error branch has a retry.* Pages
  with naturally inline branching (infinite lists) may follow the convention without the component.
- Fix the six defects from §1 with it. The profile fix must render `ErrorState` instead of the blank form;
  VariantBuilder's option-group error must block progression, not pretend "no options".
- Mechanical sweep: replace the 29 dashed-`Paper` blocks in 23 files with `EmptyState`/`ErrorState`. Copy
  stays per-page (existing keys); only the shell unifies.

### 3.2 `PageHeader` + `ConfirmDialog` promotions

- Generalize `AdminPageHeader` into a shared `PageHeader`: `title`, `subtitle?`, `actions?`, plus a `backTo?`
  affordance (RTL-flippable chevron via the phase 0 icon family; if phase 0 shipped no `back` icon, extend
  `AppIcon/config.ts` minimally and note it — ownership rule). Adopt it **mechanically** where pages already
  hand-roll the identical h5/h1 + subtitle block (patients, addresses, bookings, earnings, …); per-page header
  design is each area phase's job (DEFERRED → 3–11). `AdminPageHeader` becomes a re-export or its call sites migrate.
- Move `components/admin/ConfirmDialog` to `components/common/ConfirmDialog` **preserving its contract**:
  required-reason gating, busy state disabling both buttons, caller-owns-the-mutation. Migrate the admin
  imports and the hand-rolled confirm flows only where mechanical (patients archive, addresses delete); the
  remaining raw `<Dialog>` confirm sites are area-phase work (DEFERRED → 3–11).

### 3.3 Card kit — `SurfaceCard` + `AccentCard`

Encode the de-facto anatomy once: `SurfaceCard` = flat `Paper` (`elevation={0}`), 1px `divider` border, house
radius, a padding scale (`sm`/`md`/`lg` ≈ today's p:2 / 2.5 / 3); `AccentCard` = `SurfaceCard` + a
`borderInlineStart` accent taking a **semantic token name**, at one standardized width (pick one; end the
3px/4px drift). Migrate the ~12 hand-rollers mechanically — `EarningsRow`, `EarningsBalanceHeader`,
`PayoutHistoryRow`, `PatientCard`, `VariantCard`, `VisitNoteCard`, `InstallmentScheduleRow`, `PriceBreakdown`,
`BankStatusPanel`, `DocumentUpload`'s panels, `BookingRequestSummaryCard`, the customer-home `NudgeCard` —
visual unification only, zero content/behavior change.

### 3.4 `<Money>` primitive

One component for every displayed amount: takes a **served IRR digit-string**, renders Toman + unit label via
`utils/money.ts` (never computes); `size`/`tone` variants with emphasis driven by `--bal-money-emphasis`
(phase 0) — **not terracotta**; deduction rendering (muted/error tone with an explicit visual sign treatment,
never a bare minus inside RTL text); optional strikethrough. Replace the 24 hand-assembled sites in 19 files —
this fixes the `PriceBreakdown` total-contrast defect and the sibling terracotta-money sites (`RefundStatusCard`,
`BnplPlanCard`, `InstallmentScheduleRow`, `CancellationPolicyDisclosure`) in one pass. `PriceDisplay` (catalog
unit rates) stays; refactor it onto `<Money>` internals only if trivial — its contract is tested and correct.

### 3.5 Formatting utils — `utils/number.ts`

- `localeTag(locale)` → `'fa-IR' | 'en-US'` and `formatNumber(value, locale, options?)` — kill the 23
  copy-pasted ternaries in 15 files (including the drifted `admin/partners/[id]/page.tsx` raw-locale call).
- `formatRelativeTime(iso, locale)` via `Intl.RelativeTimeFormat`; **rule (document in JSDoc): relative up to
  ~7 days («۲ ساعت پیش»، «دیروز»), then decay to the absolute Shamsi date** via `formatShamsiDate`. Consumers
  land in phases 10/11; ship the util + tests now.
- `formatClock(totalSeconds, locale)` — locale-digit `mm:ss`/`hh:mm:ss`; migrate `CountdownTimer`'s inline
  `Intl` pad onto it and fix `OtpStep.tsx:27`'s Latin-digit resend clock.

### 3.6 `JalaliDatePicker` + `JalaliDateField`

Shamsi-native date selection that **emits ISO Gregorian** (the wire stays Gregorian; display stays Shamsi):
a month-grid calendar (Persian month/weekday names, today marked, min/max props), a compact **day-chip-strip**
variant for near dates (next N days as tappable chips — the C4 booking form's shape), and `JalaliDateField`
(read-only input + picker popover) to replace native `type="date"` inputs. **Investigate and DECIDE the
arithmetic layer:** prefer `Intl` `fa-IR-u-ca-persian` (already proven in `utils/date.ts`) for display + a
minimal conversion for month math; a tiny, well-maintained jalali lib (e.g. `jalaali-js`, ~2 KB) is acceptable
if `Intl`-only arithmetic gets awkward — document the choice and measured bundle cost in the report; no
heavyweight date library. Locale-aware (`fa` Persian calendar, `en` may show Gregorian — same ISO output),
keyboard-navigable, RTL-correct, both schemes. Consumed by phases 4, 5, 8, 11 — consumer migration is theirs
(DEFERRED → 4/5/8/11).

### 3.7 `StatusChip` v2

Soft-tint default: `-soft` token backgrounds + strong text (extend `tokens.css` + `colors.ts` with any missing
`-soft` pairs, both schemes); solid fill reserved for high-alarm states; a documented status weight hierarchy
(neutral < info < progress < success < warning < alarm). `StatusChip` is the delegation point, so this is
mostly one file; update direct chip consumers mechanically and keep the exhaustive enum→chip mappings intact.

### 3.8 `StatusTimeline`

A designed vertical timeline: node = label + optional timestamp + optional note; states completed / current
(animated within the phase 0 motion tokens, reduced-motion-safe) / pending / terminal-failure. Migrate the
two StepperHeader-as-status-display misuses: `RefundStatusCard.tsx:76` (3-step refund progress) and
`components/booking/BookingStatusTimeline` (7-status booking lifecycle). **StepperHeader remains for real
wizards only** (onboarding, verification, BNPL) — write that into its JSDoc.

### 3.9 `CountdownTimer` v2

Keep the do-not-regress architecture (server-frozen deadline, isolated tick, single `onElapsed`, `dir="ltr"`
tabular digits). Add: a **progress-ring variant** (given `windowStart`); **urgency tiers** — calm teal →
amber → terracotta — with threshold props, replacing the binary `urgent`; **humanized coarse mode** above
~10 minutes («۲۵ دقیقه مانده», minute-grain updates) switching to the ticking clock below it; keep the `label`
slot; `aria-live="polite"` at coarse intervals (never per second). Swap the hourglass `pending` glyph for the
clock; drop the hard-coded `1.5rem` for size variants. Existing consumers (C5 tracker, nurse inbox, checkout,
EarningsRow dispute window) keep working unchanged — new props optional.

### 3.10 `RatingInput` v2

Switch fill colors to phase 0's `--bal-rating` / `--bal-rating-empty`; **fractional fill** (dual-layer or clip)
for read-only averages so 4.5 renders as 4.5 — then remove the `Math.round` workaround at
`search/nurse/[nurseId]/page.tsx:260` (it shows a 4.5 average as 5 stars — an honesty bug on the core trust
surface); size variants; keep the radiogroup/readOnly `role="img"` semantics and `data-*` hooks. Swap the star
color in `NurseResultCard` and `BookingRequestSummaryCard` to the same tokens.

### 3.11 Skeleton twins + `AppLoading` rebrand

Co-located `<X.Skeleton />` statics matching real anatomy (avatar disc, chip row, price line) for
`NurseResultCard`, `EarningsRow`, `PayoutHistoryRow`, `PatientCard`, `VisitNoteCard`, `TicketListCard`; adopt
at the loading branches that hand-guess heights (e.g. `search/results/page.tsx:75`). Rebrand `AppLoading` into
a branded splash (brand mark + subtle motion, reduced-motion-safe) used **only** for true full-page waits
(auth splash, gateway return). Of the 18 screens using it today, switch the ones with a shaped skeleton
available to skeletons; the rest keep the splash until their area phase.

### 3.12 Route chrome — loading / error / 404

Per-route-group `loading.tsx` with shell-shaped skeletons (`(customer)` header + card stack; `nurse`/`admin`/
`partner` sidebar-shell content; `(public-routes)` auth card). Branded `error.tsx` (per `[locale]` segment)
and `not-found.tsx` + the next-intl catch-all 404 pattern — calm Persian-first copy, brand mark, retry
(`reset()`) and «بازگشت به خانه» CTAs, keys in both catalogs. `global-error.tsx` (sits above `[locale]`,
renders its own `<html>` — it cannot use next-intl): minimal static **bilingual** fa+en copy — the one
sanctioned hard-coded-string exception; note it in `client/CLAUDE.md`. Rewrite `components/common/ErrorBoundary`
to the same design: i18n'd, branded, retry affordance, **stack/componentStack rendered only in development**
(logged, never shown, in prod).

### 3.13 Per-route metadata

Title template via one `generateMetadata` in `app/[locale]/layout.tsx`: `'%s | بالین‌یار'` (fa) /
`'%s | Balinyaar'` (en) + localized description. Establish and document the client-page pattern — `page.tsx`
becomes a thin RSC exporting `generateMetadata` and rendering the co-located `'use client'` body — and apply
it to the main landing pages now (customer home, `/login`, `/search`, `/bookings`, `/nurse`, `/admin`,
`/partner`). Full per-page adoption continues in the area phases (DEFERRED → 3–11).

### 3.14 Mutation-error convention

Read `lib/api/client.ts` to confirm exactly which failures the fetch layer already toasts; then: **every
mutation whose failure is not surfaced inline or by the fetch layer gets an `onError` toast.** Fix the two
known silent ones — nurse profile save (`nurse/profile/page.tsx:54–64`) and avatar upload (`:44`) — and write
the convention into `client/CLAUDE.md` (Toast Notifications section).

## 4. Mocks & seams in this phase

None — pure UI over existing `services/{domain}` seams; no new service, mock, or flag. Expected REQ count:
zero. If a genuine backend gap surfaces anyway, append it to
[../../shared-working-context/frontend/requests/for-backend.md](../../shared-working-context/frontend/requests/for-backend.md)
numbered **REQ-039 onward** (001–038 are taken), keep the UI mock-tolerant behind the seams, never touch `server/`.

## 5. Critical rules you must not get wrong

1. **Presentational purity + caller-owned i18n stays.** Shared primitives take already-translated strings and
   stable codes; no data-fetching, no wire-derived labels inside this layer.
2. **Money invariants stay.** Amounts are served IRR digit-strings through `utils/money.ts` (BigInt); `<Money>`
   formats, never computes; `PriceBreakdown`'s dev reconciliation guard survives the card-kit migration.
3. **CountdownTimer architecture stays** — server-frozen deadline, isolated self-tick, single `onElapsed`;
   deadlines never recomputed client-side. **ConfirmDialog's contract stays** through the move. **An error is
   never an empty** — the defect class this phase kills; every error state keeps a retry.
4. **Don't break what delegates.** `StatusChip` is the single status source and the enum→chip mappings are
   exhaustively typed — keep both; `StepperHeader` keeps serving the real wizards untouched; honest-copy
   components (EscrowNotice verbatim fa, RefundStatusCard's no-success-framing-on-failure,
   EarningsBalanceHeader's "owed back") keep their copy and state logic — restyle shells only.
5. **Design contract non-negotiables:** tokens not hexes (extend `tokens.css` + `colors.ts` together, both
   schemes); logical/RTL-safe props only (keep the deliberate `dir="ltr"` islands for clocks/IBANs/phones);
   both message catalogs in sync; MUI v9 API only; co-located tests for every shared component;
   fetch/cookies/toast rules per `client/CLAUDE.md` untouched.
6. **Never add a layout above `[locale]`** — `global-error.tsx` is a special file, not a layout, and is the
   only file allowed static copy.

## 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 (many shared components are touched — run it); every new
      shared component has a co-located `.test.tsx`; `en.json`/`fa.json` in sync.
- [ ] All six error→false-empty/spinner defects from §1 render `ErrorState` with a working retry (verify by
      forcing the query to fail); the profile error never shows an editable blank form.
- [ ] Sweep greps clean: `border: '1px dashed'` under `client/src/app` → zero; `currency_toman` outside
      `utils/money.ts` + `<Money>`/`PriceDisplay` internals → zero; `locale === 'fa' ? 'fa-IR'` → only
      `utils/number.ts`. The checkout total renders in `--bal-money-emphasis`, not terracotta.
- [ ] `loading.tsx`, `error.tsx`, `not-found.tsx`, `global-error.tsx` exist and render branded, localized
      (404/error verified on `/fa` and `/en`); ErrorBoundary shows no stack in a production build; browser
      tab titles differ per section using the `%s | بالین‌یار` template.
- [ ] `JalaliDatePicker`/`JalaliDateField` render Shamsi, emit ISO Gregorian, pass keyboard/RTL tests; the
      arithmetic decision + bundle cost is documented in the report.
- [ ] A 4.5 rating average renders a half-filled fifth star on the nurse profile (no `Math.round`);
      `RefundStatusCard` and the booking timeline render `StatusTimeline` (wizards still use `StepperHeader`).
- [ ] Nurse profile save and avatar upload toast on failure; the convention is in `client/CLAUDE.md`.
- [ ] Visual verification on the four axes — `/fa` + `/en` × light + dark — and mobile + desktop for the state
      kit, card kit, route chrome, and the Jalali picker.

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

1. Stop the backend (or force queries to reject via devtools offline mode) and load `/fa`: customer home shows
   a branded error state with «تلاش دوباره» — not an infinite spinner. Restore, retry → home renders. Repeat on
   `/patients`, `/profile`, `/nurse/requests`, `/nurse/services`: an error state, never «empty» copy or a blank form.
2. Visit a garbage URL (`/fa/xyz`) → branded Persian 404 with a home CTA. Throw inside a page in dev → branded
   error screen with retry; build production and confirm no stack is rendered.
3. Navigate between sections and watch the tab title change («جستجو | بالین‌یار», «رزروها | بالین‌یار», …).
4. Open search results while loading: skeletons match the card anatomy — no layout jump when data lands. Open
   checkout (mock path): the total renders in the money-emphasis color with correct contrast in both schemes;
   a deduction row (earnings commission) reads visually as a deduction.
5. Open the C5 request tracker: progress ring, coarse «X دقیقه مانده» above 10 minutes, ticking Persian-digit
   clock below, escalating tint as thresholds pass; the `/login` OTP resend clock shows Persian digits on `/fa`.
6. Open a nurse profile with a fractional average: stars render the fraction. Open a refund status page:
   vertical timeline with node states, not a form stepper.
7. Mount `JalaliDateField` (the phase's test page or the first consumer): pick «۱۵ مرداد» → the emitted value
   is the correct ISO Gregorian date; keyboard navigation works; `/en` shows the Gregorian view.
8. Kill the network mid-save on the nurse profile → an error toast appears; the form keeps the draft.

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

- Update `client/CLAUDE.md`: Project Structure (new `components/common/*` primitives, route-chrome files,
  `utils/number.ts`), the QueryStateGate/error-never-empty convention, the mutation-error toast convention,
  the metadata pattern, and the `global-error.tsx` exception.
- Write the report at `dev/shared-working-context/reports/ui-phase-1-report.md`: what shipped, the Jalali
  decision + bundle cost, icon-registry additions (if any), the sweep counts, any REQ entries appended to
  [for-backend.md](../../shared-working-context/frontend/requests/for-backend.md) (REQ-039+; expected none),
  and any foundation gaps left for phase 2+.
- Save a memory note per operating-rules §8: the primitives kit now exists and later phases must consume it
  (never fork local variants), the error-never-empty and mutation-toast conventions, and the Jalali decision.