# Mobile UX Improvements for EveAI Chat Client This document explains the changes we made to improve the mobile user experience and how to verify or tweak them. ## Summary of Issues Addressed - Unwanted white margins and page scroll on mobile due to default body margin and mixed vh/dvh usage. - Layout jitter and incorrect heights when the browser address bar or the on-screen keyboard appears. - Chat input potentially being obscured by the keyboard. - Differences between DevTools emulation and real devices. ## Key Changes 1. CSS base reset and layout fixes - Remove default white margins and prevent double scroll. - Ensure outer containers don’t create conflicting scrollbars. - Respect device safe-area insets (bottom notch, etc.). Files: - eveai_chat_client/templates/base.html - Added a CSS custom property fallback: `--vvh: 1vh;` on `:root`. - eveai_chat_client/static/assets/css/chat.css - `.app-container` now uses `height: calc(var(--vvh, 1vh) * 100);`. - Added base reset: `body { margin: 0; overflow: hidden; }` and global `box-sizing: border-box`. - Mobile `.content-area` no longer uses `calc(100vh - header)`; we rely on flex with `min-height: 0`. - eveai_chat_client/static/assets/css/chat-components.css - Added `padding-bottom: env(safe-area-inset-bottom)` for the chat input area on mobile. - When keyboard is open (detected via JS), we slightly increase bottom padding. 2. VisualViewport utility and debug overlay - We introduced a small utility that: - Sets a CSS variable `--vvh` equal to 1% of the current visual viewport height. - Toggles a `keyboard-open` class on `` when the keyboard is likely visible. - Optionally shows a debug overlay with real-time viewport metrics. Files: - frontend_src/js/utils/viewport.js (new) - Exports `initViewportFix({ enableDebug })`. - Updates `--vvh` on resize/scroll/orientation changes. - Optional debug overlay via `enableDebug`. - frontend_src/js/chat-client.js - Imports and initializes the util on DOMContentLoaded. - Enable overlay via query parameter: `?debug=viewport`. ## How It Works - CSS reads `--vvh` to size the vertical layout. This follows the visual viewport, so when the URL bar or keyboard affects the viewport, the chat layout adapts without extra page scroll. - The `keyboard-open` body class allows us to slightly increase bottom padding for the input to avoid edge cases where the input is near the keyboard. - On mobile, `.app-container` spans the full visual viewport height, and `.content-area` flexes to take remaining space under the mobile header without relying on height calculations. ## Testing Checklist 1. Open the chat on real devices (iOS Safari, Android Chrome). 2. Verify there are no white margins around the app; the overall page should not scroll. 3. Focus the message input: - Keyboard appears; the message list should stay usable and the input should remain visible. - The page should not jump in height unexpectedly. 4. Rotate device (portrait/landscape) and ensure the layout adapts. 5. Try with/without the browser UI (scroll a bit to collapse the address bar on Android Chrome). 6. Optional: enable overlay with `?debug=viewport` and verify reported values look sane. ## Tuning and Fallbacks - If you need to support extremely old iOS versions that lack VisualViewport, we still fall back to `1vh` for `--vvh`. You can increase robustness by setting `--vvh` via a simple `window.innerHeight` measurement on load. - Keyboard detection is heuristic-based (drop > 120px). Adjust the threshold in `viewport.js` if needed for specific device groups. - Avoid adding fixed `height: 100vh` or `calc(100vh - X)` to new containers; prefer flex layouts with `min-height: 0` for scrollable children. ## Known Limitations - On some embedded browsers (in-app webviews), viewport behavior can deviate; test with your target apps. - The safe-area env variables require modern browsers; most iOS/Android are fine, but always test. ## Enabling/Disabling Debug Overlay - Append `?debug=viewport` to the URL to enable. - The overlay displays: `innerHeight`, `clientHeight`, `visualViewport.height`, `visualViewport.pageTop`, header height, current `--vvh`, and keyboard state. ## Next Steps (Optional Enhancements) - PWA manifest with `display: standalone` to reduce address bar effects. - Add smooth scroll-into-view on input focus for edge cases on particular webviews. - Add E2E tests using BrowserStack for a small device matrix. ## Focus Zoom Prevention (2025-09-24) Some mobile browsers (notably iOS Safari) auto-zoom when focusing inputs with small font sizes. To prevent this: - We enforce font-size: 16px for inputs, selects, textareas, and buttons on mobile in chat-components.css. - We stabilize text scaling via `-webkit-text-size-adjust: 100%`. - We extended the meta viewport with `viewport-fit=cover`. - The debug overlay now also shows `visualViewport.scale` to confirm no zoom is happening (expect 1.00 during focus). Files: - eveai_chat_client/static/assets/css/chat-components.css (mobile form control font-size) - eveai_chat_client/static/assets/css/chat.css (text-size-adjust) - eveai_chat_client/templates/base.html (viewport meta) - frontend_src/js/utils/viewport.js (overlay shows vv.scale) Validation checklist: - Focus the chat input and language select on iOS Safari and Android Chrome; the UI should not scale up. - Overlay shows `vv.scale: 1.00` with `?debug=viewport`. ## Mobile Header Overflow Fix (2025-09-24) We observed that the mobile header could push the layout wider than the viewport on small devices, causing horizontal page scroll. We addressed this by: - Allowing the header row to wrap: `.mobile-header { flex-wrap: wrap; }`. - Ensuring children can shrink within the container: `min-width: 0` on `.mobile-logo` and `.mobile-language-selector`. - Constraining controls: `:deep(.language-select)` uses `max-width: 100%` and on very small screens `max-width: 60vw`. - Preventing accidental bleed: `.mobile-header { max-width: 100%; overflow: hidden; }`. - Added `html { overflow-x: hidden; }` as a light global failsafe. Files: - eveai_chat_client/static/assets/vue-components/MobileHeader.vue (scoped styles updated) - eveai_chat_client/static/assets/css/chat.css (added html { overflow-x: hidden; }) Validation checklist: - On 320px width devices, header may wrap to 2 lines without horizontal scroll. - Long tenant names and multiple languages do not cause page-wide overflow; content remains within viewport width.