some ui phase improvement planning

dev/post-phase/ui/ui-phase-2-shells-and-navigation.md

@@ -0,0 +1,296 @@
+# UI Phase 2 — Shells & navigation
+
+> **Mission:** replace the starter chrome with per-actor shells — consumer-app chrome for customers, a
+> workspace for nurses, a dense console for admin/partner — and fix the navigation-correctness defects the
+> audit verified: the sidebar active state that never fires, the middleware redirect hop on every sidebar
+> click, the fragile RTL anchoring, and the desktop SSR mobile-first flash. Phases 0–1 gave the app a design
+> language and primitives; this phase is where every actor finally gets chrome that *looks like Balinyaar and
+> navigates correctly*. **This phase owns `client/src/layout/`.**
+>
+> **Track:** frontend · **Depends on:** [Phase 0](ui-phase-0-design-language.md),
+> [Phase 1](ui-phase-1-primitives-and-states.md) · **Unlocks:** every actor gets branded, correct chrome —
+> the area redesigns (phases 3–11) compose inside these shells
+> **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 feature layer is disciplined, but the chrome around it is the untouched react-starter-kit. Diagnosed
+current state (all verified in code):
+
+1. **The sidebar active highlight never fires.** `SideBarNavItem.tsx:28` compares
+   `pathname.startsWith(path)` where `pathname` (from `next/navigation`) is locale-prefixed
+   (`/fa/nurse/requests`) and `path` is unprefixed (`/nurse/requests`) — `defineRouting` uses
+   `localePrefix: 'always'`, so the comparison always fails. Nurse/admin/partner users get zero "where am I"
+   signal. `AppLink`'s `activeClassName` (`AppLinkNextNavigation.tsx:95`, `pathname == currentPath`) has the
+   same bug.
+2. **Three locale strategies coexist in the chrome.** Sidebar links push unprefixed hrefs through raw
+   `next/link` (`SideBarNavItem.tsx:34` via `AppLink`) — a middleware redirect hop on every click and a
+   locale-flip risk for `/en` users; `BottomBar.tsx:14` and `NotificationBell` manually prefix with
+   `/${locale}`; `CustomerLayout.tsx:52` does the same inline. There is no `createNavigation` wrapper —
+   `src/i18n/` holds only `routing.ts` + `request.ts`.
+3. **The chrome is starter junk on a trust-first product.** `PublicLayout.tsx:9` titles the login screen
+   `'Unauthorized - Balinyaar'` in English; `SideBar.tsx:56` renders `<UserInfo showAvatar />` with no user —
+   an eternal English "Current User" / "Loading..." (`UserInfo.tsx:34-36`, prop typed `user?: any`);
+   `TopBarAndSideBarLayout.tsx:71` tooltips `'Open Sidebar'`; `SideBar.tsx:76` says `'Logout Current User'`.
+4. **Structural defects:** `SERVER_SIDE_MOBILE_FIRST = true` (`hooks/layout.ts:8`) makes every desktop SSR
+   paint the mobile shell, then content jumps 240px after hydration; content offset uses physical
+   `paddingLeft/Right` keyed to anchor strings (`TopBarAndSideBarLayout.tsx:53-60`) — RTL correctness by
+   double-flip coincidence; the drawer-close handler sits on the whole content `Stack` (`SideBar.tsx:52`) so
+   any tap inside closes it; `BottomBar` has no safe-area padding and renders unconditionally on desktop
+   (`CustomerLayout.tsx:81`); the customer shell has **no sign-out, no back affordance, no contextual
+   title**; no shell has a locale switcher or an actor switcher for dual-role sessions.
+
+**What already exists (do not rebuild):**
+
+- **[Phase 0](ui-phase-0-design-language.md):** the brand mark (registered as `logo`), the
+  `theme.components` pass (AppBar/Drawer/ListItemButton/BottomNavigation already restyled), the single icon
+  family incl. a direction-aware back chevron, elevation/motion/focus tokens.
+- **[Phase 1](ui-phase-1-primitives-and-states.md):** PageHeader, state views, route-level
+  `loading.tsx`/`error.tsx`/`not-found.tsx`, per-route metadata, formatting utils.
+- **RoleGuard + role hydration** (refinement phase 2): `RoleGuard` wraps all four shells with
+  resolved-vs-pending `/me` hydration, error recovery, and mismatch redirects. Chrome only here — never touch it.
+- **The per-actor shell split:** `CustomerLayout` / `NurseLayout` / `AdminLayout` / `PartnerLayout` mapped
+  1:1 to route groups. Restyle and restructure the chrome *inside* this architecture; keep the split.
+- **`BottomBar`'s longest-prefix active matching** (`BottomBar.tsx:31-41`) — the one nav component that
+  matches correctly today. Keep its semantics; generalize them.
+- **Performance-conscious composition:** `DarkModeToggleButton`/`DarkModeFormSwitch` are the only
+  `useColorScheme` subscribers; `NotificationBell` isolates the polling unread count. Shells never re-render
+  on theme flips or bell updates — preserve this.
+- **`AdminLayout`'s capability-gated nav** via `useAdminCapabilities()` (`AdminLayout.tsx:21-37`).
+
+## 2. Required reading (do this first)
+
+- [audit/shell-and-navigation.md](audit/shell-and-navigation.md) — the full 20-problem inventory with
+  file/line evidence and the keep-list. This is your problem spec.
+- [audit/cross-cutting-ux.md](audit/cross-cutting-ux.md) — the chrome-adjacent items (English chrome
+  strings, `UserInfo`, `hooks/layout.ts`, metadata) and its keep-list.
+- The `frontend-designer` skill (`.claude/skills/frontend-designer/SKILL.md`) — the design contract; phase 0
+  will have updated it with the new tokens/icons.
+- Code, in this order: `client/src/layout/` (all files — you own this folder), `client/src/i18n/routing.ts`,
+  `client/src/components/common/AppLink/`, `client/src/components/UserInfo/UserInfo.tsx` (you will delete
+  it), `client/src/components/auth/RoleGuard.tsx` (do not touch — know why), `client/src/hooks/layout.ts`,
+  `client/src/hooks/auth.ts` (`useActorRole`, `useAdminCapabilities`), `client/src/context/auth/types.ts`
+  (`SessionUser.roles` — feeds the actor switcher), `client/src/constants/routes.ts`,
+  `client/src/components/TrustBadge/`, `client/src/services/profiles/` + `client/src/services/auth/hooks/useMe.ts`
+  (feed the identity card), `client/src/components/notifications/NotificationBell.tsx`.
+- `client/CLAUDE.md` — "Golden rules", "Direction (RTL/LTR)", the theme system, and the Project Structure
+  layout section you must update at close.
+- next-intl v4 docs for `createNavigation` (routing-aware `Link`/`usePathname`/`useRouter`/`redirect`).
+
+## 3. Scope — build this
+
+### 3.1 Locale-aware navigation — one wrapper, two bugs fixed
+
+Create **`src/i18n/navigation.ts`**: `createNavigation(routing)` from `next-intl/navigation`, exporting
+`Link`, `usePathname`, `useRouter`, `redirect`, `getPathname`. Then route **all chrome navigation** through it:
+
+- `SideBarNavItem` / `SideBarNavList`: link via the new `Link`; compute active state against the new
+  `usePathname()` (which strips the locale prefix, so unprefixed `ROUTES.*` compare directly). This makes the
+  active highlight fire for the first time **and** removes the middleware redirect hop + locale-flip risk in
+  one move.
+- Active matching must be **longest-prefix winner-takes-all** (the `BottomBar` semantics): extract a small
+  shared helper (e.g. `src/layout/matchActivePath.ts`, unit-tested) used by both the sidebar and the bottom
+  bars — plain `startsWith` would keep `/nurse` (dashboard) lit on every nurse route.
+- `BottomBar`: drop the manual `withLocale` prefixing in favor of the wrapper's router; keep its matching via
+  the shared helper.
+- `AppLink`'s `activeClassName` comparison, `NotificationBell`'s `router.push`, and `CustomerLayout`'s inline
+  `` `/${locale}${…}` `` all migrate to the wrapper. After this, `grep -r '/${locale}' src/` inside chrome
+  code should return nothing.
+
+### 3.2 Customer shell — contextual header + deliberate desktop
+
+Rework `CustomerLayout`:
+
+- **Contextual header.** On the 5 root tabs (`/`, `/bookings`, `/patients`, `/wallet`, `/profile` — the
+  `(customer)` group has no URL segment): the phase-0 **brand lockup** (mark + wordmark). On pushed routes
+  (nurse profile, booking detail, checkout, ticket thread…): **page title + back chevron** (the phase-0
+  auto-mirrored icon) that calls `router.back()`. Drive it with a route→title map in `src/layout/`
+  (longest-prefix over `ROUTES.*`, titles from the existing `nav`/`shell` namespaces) plus a lightweight
+  per-page override slot (React context) for dynamic titles — the area phases (4–6, 9) will feed nurse/booking
+  names into it later; ship static titles now. **Kill the static «اپلیکیشن خانواده» label**
+  (`tShell('customer_app')` today).
+- Keep the support entry, `NotificationBell`, and dark toggle in the header (badge/popover upgrades belong to
+  phase 10 — leave slots, don't build them).
+- **BottomBar:** add `paddingBottom: 'env(safe-area-inset-bottom)'` on the Paper (the home-indicator overlap
+  is on the primary mobile nav); refine the active state on top of the phase-0 BottomNavigation override
+  (selected color + label weight — tokens, not hexes).
+- **Desktop treatment — decide and implement deliberately.** Recommended: a constrained app frame — the
+  content column keeps `CONTENT_MAX_WIDTH`, gains side gutters on a `background.default` canvas — and above
+  the `md` breakpoint **hide the mobile tab bar** in favor of a top-nav variant (the same 5 items as inline
+  header tabs). Implement with CSS breakpoints (`sx` `display` keys), not `useIsMobile` branching (see 3.6).
+
+### 3.3 Nurse shell — a workspace, not a starter drawer
+
+Rework `NurseLayout` (still on the shared engine, which you are also refitting in 3.6):
+
+- **Grouped sidebar** with subheaders + dividers, replacing the flat 10-item array (`NurseLayout.tsx:19-33`):
+  **امروز** (dashboard, requests, visits) · **حرفهٔ من** (services, coverage, verification) · **مالی**
+  (earnings, bank) · **پشتیبانی** (support). Extend the nav-item model with a group key; the engine renders
+  `ListSubheader`-style sections. Group labels are i18n keys in both catalogs.
+- **A real identity card:** new typed **`ProfileSummary`** shared component
+  (`src/components/ProfileSummary/`, co-located test): avatar, display name, masked phone in Persian digits,
+  role label, and `TrustBadge` when the actor is a nurse. Feed it from the `/me` session (`useMe` — phone,
+  roles) plus the profiles domain for name/avatar where hydrated; render graceful skeleton/fallback states —
+  never English literals. **DELETE `src/components/UserInfo/`** (the starter `user?: any` card) and every
+  import/test of it.
+- **Mobile: a 5-tab nurse bottom nav** so field nurses stop digging through a drawer: امروز (dashboard) ·
+  درخواست‌ها · ویزیت‌ها · درآمد · بیشتر — «بیشتر» opens the drawer with the remaining items (profile,
+  services, coverage, bank, verification, support, sign-out). Reuse `BottomBar`.
+- **TopBar shows the current page title** via the same route→title engine as 3.2 (kill the static «نمای
+  پرستار»).
+
+### 3.4 Admin + partner shells — a dense console
+
+- **Slim top bar:** current page title (route→title map) as a start-anchored breadcrumb-style label — not the
+  centered static console name — plus a **bell** (widen `NotificationBell`'s `role` union to include
+  `'admin'`; the `/admin/notifications` center already exists — note this minimal foundation extension in
+  your report) and an **identity chip** (`ProfileSummary` compact variant or a chip: name/phone + the
+  fine-grained role label off `roleCodes` — a `finance` admin should *see* they're finance).
+- **Sectioned sidebar** with the now-working active state: **اعتماد** (verification, reviews) · **مالی**
+  (payouts; refunds are worked *via tickets* — do not invent a refunds nav item) · **پشتیبانی** (tickets,
+  alerts) · **سیستم** (config, holidays, audit, roles, partners, users). Add the missing `/admin/users` entry
+  (`ROUTES.ADMIN_USERS` exists; gate it like roles on `caps.canManageRoles` — display convenience, server is
+  the authority). The notifications sidebar item is replaced by the header bell. **Keep every
+  `useAdminCapabilities` gate exactly as is** — grouping must not change what a role sees.
+- **Partner shell:** same engine + its own 4-item nav; identity area shows the **center name** from
+  `useMyPartnerCenter` (fallback skeleton while resolving — the page-level access-denied handling stays where
+  it is).
+
+### 3.5 Public shell — strip it to a brand frame
+
+`PublicLayout` today wraps login in starter dashboard chrome: the hard-coded English `'Unauthorized -
+Balinyaar'` title (`PublicLayout.tsx:9`), a pencil button opening a drawer containing only a dark-mode
+switch, and an **empty** `BottomBar` strip on mobile (`PublicLayout.tsx:34`, `BOTTOM_BAR_ITEMS = []`).
+Replace it with a minimal centered brand shell: the phase-0 logo, a locale switcher, and the dark toggle — no
+sidebar, no bottom bar, no `TopBarAndSideBarLayout`. Delete the dead `BOTTOM_BAR_DESKTOP_VISIBLE` flag from
+`layout/config.ts` with it. (The login screen itself — hero, trust presence — is **DEFERRED → phase 3**.)
+
+### 3.6 Cross-cutting engine fixes (`TopBarAndSideBarLayout` + `SideBar` + `TopBar`)
+
+- **Drawer close scoping:** move the close handler off the content `Stack` (`SideBar.tsx:52`) onto the nav
+  links themselves — toggling dark mode or mis-tapping a divider must not close the drawer.
+- **Kill the desktop SSR flash:** stop deriving shell *structure* from `useIsMobile`
+  (`SERVER_SIDE_MOBILE_FIRST` renders the mobile shell, then jumps 240px). Render responsively with CSS:
+  breakpoint-keyed `sx` values (paddings, drawer variant/visibility via `display`) so the desktop first paint
+  already includes the persistent sidebar. `hooks/layout.ts` stays for non-structural consumers; the shells
+  stop depending on it for layout.
+- **Logical properties:** replace the physical `paddingLeft/Right` + `anchor?.includes('left')` logic
+  (`TopBarAndSideBarLayout.tsx:53-60, 89-91`) with `paddingInlineStart` / start-anchored drawer semantics —
+  RTL correctness by construction, not by the stylis double-flip coincidence.
+- **Chrome strings → both catalogs:** `'Open Sidebar'` (`TopBarAndSideBarLayout.tsx:71`), `'Logout Current
+  User'` (`SideBar.tsx:76`); the `UserInfo` literals die with the component. Zero English chrome remains on `/fa`.
+- **TopBar:** fix the `whiteSpace: 'nowrap'` overflow risk (ellipsis + `minWidth: 0`); delete the starter
+  comment residue (`TopBar.tsx:20`); title alignment becomes start-anchored for the console shells per 3.4.
+- **`layout/config.ts`:** delete the commented-out anchor alternates (lines 8-9) and dead flags; keep the
+  constants authoritative — update them, never bypass them.
+
+### 3.7 Session affordances — sign-out, actor switch, locale switch
+
+- **Sign-out reachable in EVERY shell.** The customer shell currently has **none** — add a sign-out row to
+  the profile-tab hub (`/profile`) now (the full hub redesign is **DEFERRED → phase 9**; one labeled row, not
+  a redesign). Sidebar shells keep sign-out in the drawer footer — now labeled and translated.
+- **Actor switcher for dual-role sessions:** `SessionUser.roles` already lives in AuthContext. When a session
+  holds both `customer` and `nurse`, show «نمای پرستار ⇄ اپلیکیشن خانواده» in the nurse sidebar and on the
+  customer profile hub. Navigation only — `RoleGuard` and `resolveRoleDestination` stay the "which app"
+  authority.
+- **Locale switcher (fa/en) in all shells** (sidebar footer / customer profile hub / public shell): switch
+  locale **preserving the current path** via the 3.1 wrapper (`router.replace(pathname, { locale })`).
+- **Keep `DarkModeToggleButton`/`DarkModeFormSwitch` as the only `useColorScheme` subscribers** — the
+  switchers must not add scheme subscriptions to the shells.
+
+## 4. Mocks & seams in this phase
+
+**None introduced.** This phase is chrome over data that already flows (`useMe`, profiles,
+`useMyPartnerCenter`, the notifications unread count) behind the existing `services/{domain}` seams — UI
+stays mock-tolerant regardless of each domain's mock flag. **REQ posture:** if a backend gap surfaces (the
+likely one: `/me` lacking a display name for `ProfileSummary`, forcing a second profile fetch per shell),
+append a REQ to
+[../../shared-working-context/frontend/requests/for-backend.md](../../shared-working-context/frontend/requests/for-backend.md)
+— REQ-001…038 are taken; number from **REQ-039**. Never edit `server/`.
+
+## 5. Critical rules you must not get wrong
+
+1. **RoleGuard and role/redirect logic untouched.** Refinement phase 2 built resolved-vs-pending hydration;
+   this phase is chrome, not security or routing policy. The actor switcher navigates; it never re-derives roles.
+2. **`useAdminCapabilities` gating stays exactly as is** — sectioning the admin nav must not add, remove, or
+   loosen a single capability gate.
+3. **Do not regress the keep-lists** ([audit](audit/shell-and-navigation.md)): the root `[locale]` layout
+   (lang/dir, conditional Mikhak, cookie-seeded scheme, RTL Emotion cache) is untouchable; the per-actor
+   shell split stays; the customer 5-tab IA (Home/Bookings/Patients/Wallet/Profile) stays; longest-prefix
+   active matching stays; `DarkModeButton` remains the sole `useColorScheme` subscriber; `NotificationBell`
+   keeps isolating the poll; `CONTENT_MAX_WIDTH` reading column stays for text-heavy views;
+   `ErrorBoundary` keeps wrapping every shell's main content.
+4. **Design contract non-negotiables:** every new string in **both** `en.json`/`fa.json` (fa is the product's
+   voice — write it first); tokens/palette keys, never hexes; logical/RTL-safe props only (this phase exists
+   partly to *remove* physical ones — do not add new ones); verify dark mode on every surface you touch;
+   MUI v9 API only (no `useFlexGap`/`flexWrap` as Stack props); new shared components (`ProfileSummary`, the
+   active-path helper, any header context) get co-located tests.
+5. **Fetch/cookies/provider rules untouched:** no raw `fetch`, no `document.cookie`, no layout above
+   `[locale]`, no `createTheme()` in components. `ProfileSummary` consumes existing hooks — it does not add
+   API calls of its own design.
+6. **Deleting `UserInfo` is a removal, not a rename** — check `src/**/*.test.{ts,tsx}` and the
+   `@/components` barrel for imports, and update the frontend-designer skill's component table (it lists
+   `UserInfo`) to point at `ProfileSummary`.
+
+## 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 (new tests for `ProfileSummary`, the active-path
+      helper, and any touched shared component); `en.json`/`fa.json` in sync.
+- [ ] `src/i18n/navigation.ts` exists and **all** chrome navigation flows through it — no raw `next/link`
+      and no manual `/${locale}` prefixing left in `src/layout/` or chrome components.
+- [ ] The sidebar highlights the active item on every nurse/admin/partner route (first time ever), and
+      clicking a sidebar link produces **one** navigation in the Network tab — no 307 middleware hop, no
+      locale flip on `/en`.
+- [ ] Customer shell: brand lockup on the 5 root tabs; title + mirrored back chevron on pushed routes;
+      safe-area padding on the bottom bar; on ≥`md` the mobile tab bar is hidden in favor of the desktop
+      treatment.
+- [ ] Nurse shell: grouped sidebar (امروز/حرفهٔ من/مالی/پشتیبانی), `ProfileSummary` identity card with
+      TrustBadge, 5-tab mobile bottom nav; `UserInfo` deleted repo-wide.
+- [ ] Admin/partner shells: sectioned capability-gated sidebar, page-title top bar, bell + identity chip
+      (admin), center-name identity (partner).
+- [ ] Public shell: no English title, no pencil, no empty drawer or bottom strip — logo + locale switcher +
+      dark toggle only.
+- [ ] Desktop first paint of a sidebar shell includes the persistent sidebar — no 240px post-hydration jump
+      (verify with a hard reload, network throttled).
+- [ ] Sign-out is reachable in all four shells; a dual-role session sees the actor switcher; every shell has
+      a locale switcher that preserves the current path.
+- [ ] Visual verification on the four axes — `/fa` + `/en` × light + dark — and mobile + desktop for every
+      shell (fa first).
+
+## 7. How to test (what a human can verify after this phase)
+
+1. Log in as the seeded nurse → `/nurse`. The sidebar shows four labeled groups and your name/phone/TrustBadge
+   — not "Current User". Click «ویزیت‌ها»: the item highlights, the top bar reads the page title, and the
+   Network tab shows a single navigation (no 307).
+2. Resize to mobile (or open devtools device mode): the nurse shell shows a 5-tab bottom nav; tab «بیشتر»
+   opens the drawer; toggling dark mode inside the drawer does **not** close it; tapping a nav link does.
+3. As a customer on `/`: the header shows the brand lockup. Open a nurse profile from search → the header
+   flips to title + back chevron; the chevron returns to results. On `/en` the chevron mirrors correctly.
+4. On desktop ≥900px as a customer: no mobile tab bar pinned to the bottom; the desktop nav variant is
+   present; content sits in the framed column.
+5. Go to `/profile` as a customer: a sign-out row exists and works. With a dual customer+nurse session, the
+   actor switcher appears here and in the nurse sidebar, and lands on the other shell (RoleGuard permitting).
+6. Log in as the seeded admin: top bar shows the page title, the bell, and your role chip (e.g. «مالی» for a
+   finance admin); the sidebar is sectioned and still shows only capability-permitted consoles. As the
+   finance-only admin, confirm no new items appeared.
+7. Open `/login` logged-out on `/fa`: no English anywhere, no drawer, no bottom strip — brand mark, locale
+   switcher, dark toggle.
+8. Hard-reload `/nurse` on desktop: the sidebar is present at first paint; no sideways content jump.
+9. Switch locale from any shell's switcher on a deep route (e.g. `/fa/nurse/earnings`): you land on
+   `/en/nurse/earnings`, same page.
+
+## 8. Hand off & document (close the phase)
+
+- Update **`client/CLAUDE.md` → Project Structure**: the `layout/` section (new shell composition,
+  route→title map, removed starter engine parts), `i18n/navigation.ts`, `components/ProfileSummary/`, and
+  the `UserInfo` deletion. Update the frontend-designer skill's §4 component table (`UserInfo` →
+  `ProfileSummary`) and §5 layout description if shell variants changed.
+- Write the report at `dev/shared-working-context/reports/ui-phase-2-report.md`: what changed per shell, the
+  navigation-wrapper migration list, the desktop-treatment decision you made, any foundation files you
+  extended minimally (e.g. `NotificationBell` role union), and screenshots/notes from the four-axes check.
+- List any REQs filed (REQ-039+) with one-line rationales; "none" is an acceptable outcome.
+- Save a memory note per operating-rules §8: the shells are now the branded per-actor chrome, chrome
+  navigation is `createNavigation`-based (active state + no redirect hop), `UserInfo` is gone, and
+  phases 3–11 must route new chrome strings/titles through the route→title map rather than static labels.