106 lines
5.4 KiB
Markdown
106 lines
5.4 KiB
Markdown
---
|
|
phase: 26-pwa-performance
|
|
plan: "02"
|
|
subsystem: ui
|
|
tags: [mobile, pwa, responsive, touch, gestures]
|
|
dependency_graph:
|
|
requires: [26-00]
|
|
provides: [mobile-chat-layout, pull-to-refresh, responsive-breakpoints]
|
|
affects: [ChatPanel, ChatConversationList, ChatInput, MobileChatView]
|
|
tech_stack:
|
|
added: []
|
|
patterns:
|
|
- useMediaQuery hook with SSR-safe window.matchMedia + addEventListener
|
|
- usePullToRefresh with native DOM touch events (mirrors SwipeToArchive pattern)
|
|
- Conditional render in ChatPanel — mobile/desktop branch at function top
|
|
key_files:
|
|
created:
|
|
- ui/src/hooks/useMediaQuery.ts
|
|
- ui/src/hooks/usePullToRefresh.ts
|
|
- ui/src/components/PullToRefresh.tsx
|
|
- ui/src/components/MobileChatView.tsx
|
|
modified:
|
|
- ui/src/components/ChatPanel.tsx
|
|
- ui/src/components/ChatConversationList.tsx
|
|
- ui/src/components/ChatInput.tsx
|
|
- ui/src/components/ChatConversationItem.tsx
|
|
decisions:
|
|
- "[Phase 26-02]: useMediaQuery uses addEventListener('change') not addListener() — addListener is deprecated in modern browsers"
|
|
- "[Phase 26-02]: PullToRefresh wraps ScrollArea in ChatConversationList, not the entire list component — keeps desktop layout unaffected"
|
|
- "[Phase 26-02]: MobileChatView uses useQuery for conversation title lookup (same key as ChatConversationList) — no extra API call due to React Query cache"
|
|
- "[Phase 26-02]: refetch from useChatConversations wrapped in void wrapper to satisfy PullToRefresh onRefresh type (void | Promise<void>)"
|
|
- "[Phase 26-02]: ChatConversationItem gets min-h-[48px] touch target to satisfy UI-SPEC requirement"
|
|
metrics:
|
|
duration: "~20 min"
|
|
completed_date: "2026-04-01"
|
|
tasks_completed: 2
|
|
files_changed: 8
|
|
requirements_satisfied: [PWA-03, PWA-04, PWA-05]
|
|
---
|
|
|
|
# Phase 26 Plan 02: Mobile Responsive Chat Layout Summary
|
|
|
|
Mobile-first chat view with full-screen layout on phones, pull-to-refresh gesture, safe-area insets, and proper 44px/48px touch targets.
|
|
|
|
## Tasks Completed
|
|
|
|
| Task | Name | Commit | Files |
|
|
|------|------|--------|-------|
|
|
| 1 | Create useMediaQuery hook and PullToRefresh component | 3a6adc7f | useMediaQuery.ts, usePullToRefresh.ts, PullToRefresh.tsx |
|
|
| 2 | Create MobileChatView and wire ChatPanel for responsive layout | 78b04217 | MobileChatView.tsx, ChatPanel.tsx, ChatConversationList.tsx, ChatInput.tsx, ChatConversationItem.tsx |
|
|
|
|
## What Was Built
|
|
|
|
**useMediaQuery** (`ui/src/hooks/useMediaQuery.ts`): SSR-safe hook that wraps `window.matchMedia` with `addEventListener("change")` for live updates. Returns boolean for any media query string.
|
|
|
|
**usePullToRefresh** (`ui/src/hooks/usePullToRefresh.ts`): Touch gesture hook with 64px threshold. Mirrors SwipeToArchive.tsx convention (native DOM events, not React synthetic). Fires `navigator.vibrate(10)` for haptic feedback on threshold trigger. Returns `containerRef` to attach to scroll container.
|
|
|
|
**PullToRefresh** (`ui/src/components/PullToRefresh.tsx`): Visual wrapper showing Loader2 spinner with "Pull to refresh" / "Release to refresh" text. Children are translated down by pull distance for visual feedback. Opacity scales with pull distance.
|
|
|
|
**MobileChatView** (`ui/src/components/MobileChatView.tsx`): Full-screen mobile chat at `h-[100dvh]` (not `100vh` — avoids keyboard-shrink issue). Two views:
|
|
- No active conversation: conversation list with PullToRefresh, `pb-16` to clear global MobileBottomNav
|
|
- Active conversation: 48px header with back button + title + agent selector, message list, sticky input bar with `pb-[env(safe-area-inset-bottom)]`
|
|
|
|
**ChatPanel updates**: Imports `useMediaQuery` and `MobileChatView`. Adds `const isDesktop = useMediaQuery("(min-width: 768px)")` at function top and returns `<MobileChatView />` when `!isDesktop`. Desktop layout unchanged.
|
|
|
|
**ChatConversationList updates**: Wraps ScrollArea in `<PullToRefresh onRefresh={() => { void refetch(); }} enabled={isMobile}>`.
|
|
|
|
**ChatInput updates**: `pb-[env(safe-area-inset-bottom)]` on form container. Send button gets `min-h-[44px] min-w-[44px]`.
|
|
|
|
**ChatConversationItem updates**: `min-h-[48px] justify-center` for touch target compliance.
|
|
|
|
## Deviations from Plan
|
|
|
|
### Auto-fixed Issues
|
|
|
|
**1. [Rule 1 - Bug] Type mismatch on PullToRefresh onRefresh prop**
|
|
- **Found during:** Task 2 build
|
|
- **Issue:** `refetch` from `useInfiniteQuery` returns `Promise<QueryObserverResult<...>>`, not `Promise<void>`. TypeScript rejected the direct assignment.
|
|
- **Fix:** Wrapped in `() => { void refetch(); }` to satisfy the `() => void | Promise<void>` interface.
|
|
- **Files modified:** `ui/src/components/ChatConversationList.tsx`
|
|
- **Commit:** 78b04217
|
|
|
|
**2. [Rule 2 - Missing critical functionality] ChatConversationItem touch targets**
|
|
- **Found during:** Task 2 — review of UI-SPEC touch target rule (48px minimum)
|
|
- **Issue:** ChatConversationItem had `py-1.5` resulting in under-48px height on mobile.
|
|
- **Fix:** Added `min-h-[48px] justify-center` to item container.
|
|
- **Files modified:** `ui/src/components/ChatConversationItem.tsx`
|
|
- **Commit:** 78b04217
|
|
|
|
## Known Stubs
|
|
|
|
None — all components are wired with real data (useStreamingChat, useChatMessages, useChatConversations, etc.).
|
|
|
|
## Self-Check: PASSED
|
|
|
|
Files verified present:
|
|
- ui/src/hooks/useMediaQuery.ts: FOUND
|
|
- ui/src/hooks/usePullToRefresh.ts: FOUND
|
|
- ui/src/components/PullToRefresh.tsx: FOUND
|
|
- ui/src/components/MobileChatView.tsx: FOUND
|
|
|
|
Commits verified:
|
|
- 3a6adc7f: FOUND
|
|
- 78b04217: FOUND
|
|
|
|
Build: PASSED (pnpm --filter @paperclipai/ui build succeeds)
|