refactor: revise iOS keyboard handling and caret visibility in editor

HMarzban · HMarzban · commit c7395d6f777c · 2025-11-28T13:54:21.000+03:30
- Enhanced caret visibility by ensuring it scrolls into view after keyboard animation.
- Implemented multiple scroll attempts for reliability during keyboard transitions.
- Updated viewport height management in _app.tsx to address iOS auto-scroll issues.
- Refined mobile layout styles to prevent scroll glitches and improve user experience.
diff --git a/packages/webapp/src/components/TipTap/plugins/scrollCaretIntoViewPlugin.ts b/packages/webapp/src/components/TipTap/plugins/scrollCaretIntoViewPlugin.ts
@@ -5,32 +5,84 @@ import type { EditorView } from '@tiptap/pm/view'
 /**
  * iOS Safari Caret Visibility Plugin
  *
- * Simplified version - the CSS layout now handles keyboard viewport changes.
- * This plugin only ensures the caret is scrolled into view within the editor
- * container after keyboard animation completes.
+ * Ensures the caret is scrolled into view within the editor container
+ * after keyboard animation completes. Handles the case where tapping
+ * on the bottom half of the screen causes the caret to be hidden.
  */
 
 const MOBILE_BREAKPOINT = 768
-const KEYBOARD_ANIMATION_DELAY = 400 // Wait for iOS keyboard animation
+// Timing for iOS keyboard animation + layout settling
+const SCROLL_DELAYS = [100, 300, 400] // Multiple attempts for reliability
+const SCROLL_MARGIN = 100 // Extra margin above caret for better visibility
 
 const isMobile = (): boolean => {
   if (typeof window === 'undefined') return false
   return window.innerWidth <= MOBILE_BREAKPOINT
 }
 
+/**
+ * Get the scroll container (editorWrapper)
+ */
+const getScrollContainer = (view: EditorView): HTMLElement | null => {
+  // Find the editorWrapper - it's the scrollable parent of the editor
+  let el: HTMLElement | null = view.dom as HTMLElement
+  while (el) {
+    if (el.classList.contains('editorWrapper')) {
+      return el
+    }
+    el = el.parentElement
+  }
+  return null
+}
+
+/**
+ * Scroll the caret into view within the editor container
+ */
 const scrollCaretIntoView = (view: EditorView): void => {
-  // Only scroll within the editor container, not the window
-  // The editorWrapper handles its own scrolling
-  view.dispatch(view.state.tr.scrollIntoView())
+  try {
+    // First, use ProseMirror's built-in scroll
+    view.dispatch(view.state.tr.scrollIntoView())
+
+    // Then, ensure the caret is actually visible in the scroll container
+    const scrollContainer = getScrollContainer(view)
+    if (!scrollContainer) return
+
+    // Get caret position from selection
+    const { from } = view.state.selection
+    const coords = view.coordsAtPos(from)
+    if (!coords) return
+
+    const containerRect = scrollContainer.getBoundingClientRect()
+    const caretTop = coords.top
+    const caretBottom = coords.bottom
+
+    // Check if caret is below visible area
+    if (caretBottom > containerRect.bottom - SCROLL_MARGIN) {
+      // Scroll down to show caret with margin
+      const scrollAmount = caretBottom - containerRect.bottom + SCROLL_MARGIN
+      scrollContainer.scrollBy({ top: scrollAmount, behavior: 'smooth' })
+    }
+    // Check if caret is above visible area
+    else if (caretTop < containerRect.top + SCROLL_MARGIN) {
+      // Scroll up to show caret with margin
+      const scrollAmount = caretTop - containerRect.top - SCROLL_MARGIN
+      scrollContainer.scrollBy({ top: scrollAmount, behavior: 'smooth' })
+    }
+  } catch {
+    // View might be destroyed, ignore
+  }
 }
 
 const handleFocus = (view: EditorView): void => {
   if (!isMobile()) return
 
-  // Wait for keyboard animation to complete, then scroll caret into view
-  setTimeout(() => {
-    scrollCaretIntoView(view)
-  }, KEYBOARD_ANIMATION_DELAY)
+  // Multiple scroll attempts at different timings for reliability
+  // This handles various iOS keyboard animation timings
+  SCROLL_DELAYS.forEach((delay) => {
+    setTimeout(() => {
+      scrollCaretIntoView(view)
+    }, delay)
+  })
 }
 
 export const createScrollCaretIntoViewPlugin = () => {
diff --git a/packages/webapp/src/hooks/useVirtualKeyboard.ts b/packages/webapp/src/hooks/useVirtualKeyboard.ts
@@ -1,87 +1,63 @@
 import { useEffect, useRef } from 'react'
 import { useStore } from '@stores'
 
+/**
+ * Tracks virtual keyboard state for mobile devices.
+ * Uses 300ms debounce to wait for full iOS keyboard animation completion.
+ *
+ * CRITICAL: This hook only tracks state - layout is handled by CSS + _app.tsx
+ */
 const useVirtualKeyboard = () => {
   const { setKeyboardOpen, setKeyboardHeight, setVirtualKeyboardState } = useStore((state) => state)
   const previousIsOpenRef = useRef<boolean | null>(null)
-  const previousKeyboardHeightRef = useRef<number>(0)
-  const transitionTimeoutRef = useRef<NodeJS.Timeout | undefined>(undefined)
+  const debounceTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null)
 
   useEffect(() => {
     const visualViewport = window.visualViewport
-
     if (!visualViewport) return
 
+    // Threshold to consider keyboard "open" (accounts for browser chrome variations)
+    const KEYBOARD_THRESHOLD = 100
+    // iOS keyboard animation takes ~300-400ms
+    const DEBOUNCE_MS = 300
+
     const handleViewportChange = () => {
       const windowHeight = window.innerHeight
       const viewportHeight = visualViewport.height
-      const keyboardHeight = windowHeight - viewportHeight
-      const isKeyboardOpen = keyboardHeight > 0
-      const previousIsOpen = previousIsOpenRef.current
-      const previousKeyboardHeight = previousKeyboardHeightRef.current
-
-      setKeyboardOpen(isKeyboardOpen)
-      setKeyboardHeight(keyboardHeight)
-
-      // Clear any existing transition timeout
-      if (transitionTimeoutRef.current) {
-        clearTimeout(transitionTimeoutRef.current)
-      }
+      const keyboardHeight = Math.max(0, windowHeight - viewportHeight)
+      const isKeyboardOpen = keyboardHeight > KEYBOARD_THRESHOLD
 
-      // Determine state based on current vs previous
-      if (previousIsOpen === null) {
-        // Initial state - no transition
-        setVirtualKeyboardState(isKeyboardOpen ? 'open' : 'closed')
-      } else if (previousIsOpen === false && isKeyboardOpen === true) {
-        // Keyboard is opening
-        setVirtualKeyboardState('opening')
-        transitionTimeoutRef.current = setTimeout(() => {
-          setVirtualKeyboardState('open')
-        }, 300) // Typical keyboard animation duration
-      } else if (
-        previousIsOpen === true &&
-        keyboardHeight < previousKeyboardHeight &&
-        keyboardHeight > 50
-      ) {
-        // Keyboard is starting to close (height decreasing but still substantial)
-        setVirtualKeyboardState('closing')
-        transitionTimeoutRef.current = setTimeout(() => {
-          setVirtualKeyboardState('closed')
-        }, 300)
-      } else if (previousIsOpen === true && isKeyboardOpen === false) {
-        // Keyboard has fully closed (fallback case)
-        setVirtualKeyboardState('closed')
-      } else if (
-        isKeyboardOpen &&
-        previousKeyboardHeight > 0 &&
-        keyboardHeight > previousKeyboardHeight
-      ) {
-        // Keyboard height is increasing while already open - ensure we're in 'open' state
-        setVirtualKeyboardState('open')
-      } else if (!isKeyboardOpen && previousIsOpen === true) {
-        // Keyboard is fully closed
-        setVirtualKeyboardState('closed')
+      // Debounce ALL state changes to prevent rapid updates during animation
+      if (debounceTimerRef.current) {
+        clearTimeout(debounceTimerRef.current)
       }
 
-      previousIsOpenRef.current = isKeyboardOpen
-      previousKeyboardHeightRef.current = keyboardHeight
+      debounceTimerRef.current = setTimeout(() => {
+        const previousIsOpen = previousIsOpenRef.current
+
+        // Only update if state actually changed
+        if (previousIsOpen !== isKeyboardOpen) {
+          setKeyboardHeight(keyboardHeight)
+          setKeyboardOpen(isKeyboardOpen)
+          setVirtualKeyboardState(isKeyboardOpen ? 'open' : 'closed')
+          previousIsOpenRef.current = isKeyboardOpen
+        }
+      }, DEBOUNCE_MS)
     }
 
     // Initial check
     handleViewportChange()
 
-    // Listen for viewport changes
+    // Only listen to resize events - scroll events cause glitches!
     visualViewport.addEventListener('resize', handleViewportChange)
-    visualViewport.addEventListener('scroll', handleViewportChange)
 
     return () => {
       visualViewport.removeEventListener('resize', handleViewportChange)
-      visualViewport.removeEventListener('scroll', handleViewportChange)
-      if (transitionTimeoutRef.current) {
-        clearTimeout(transitionTimeoutRef.current)
+      if (debounceTimerRef.current) {
+        clearTimeout(debounceTimerRef.current)
       }
     }
-  }, [])
+  }, [setKeyboardOpen, setKeyboardHeight, setVirtualKeyboardState])
 }
 
 export default useVirtualKeyboard
diff --git a/packages/webapp/src/pages/_app.tsx b/packages/webapp/src/pages/_app.tsx
@@ -66,39 +66,70 @@ export default function MyApp({ Component, pageProps }: any) {
         // Silently fail - cleanup is best-effort
       })
 
-      // Viewport height correction for iOS Safari keyboard handling
-      let prevHeight: number | undefined
-      let prevOffsetTop: number | undefined
+      // iOS Safari keyboard viewport fix
+      // Two key behaviors to handle:
+      // 1. Height changes when keyboard opens/closes
+      // 2. iOS auto-scrolls when focusing elements in bottom half of screen
       const doc = document.documentElement
+      let lastHeight = window.visualViewport?.height ?? window.innerHeight
+      let rafId: number | null = null
+
+      // Set initial height
+      const vv = window.visualViewport
+      if (vv) {
+        doc.style.setProperty('--visual-viewport-height', `${vv.height}px`)
+        doc.style.setProperty('--vh', `${vv.height * 0.01}px`)
+      }
 
-      function updateViewportHeight() {
-        const vv = window.visualViewport
-        // Get visual viewport height (excludes keyboard on iOS/Android)
-        const height = vv?.height ?? window.innerHeight
-        // On iOS, visual viewport can scroll when keyboard opens
-        const offsetTop = vv?.offsetTop ?? 0
+      // Update height immediately using rAF for smooth rendering
+      function handleViewportResize() {
+        if (rafId) cancelAnimationFrame(rafId)
+
+        rafId = requestAnimationFrame(() => {
+          const vv = window.visualViewport
+          if (!vv) return
 
-        if (height === prevHeight && offsetTop === prevOffsetTop) return
-        prevHeight = height
-        prevOffsetTop = offsetTop
+          const height = vv.height
 
-        requestAnimationFrame(() => {
-          // --visual-viewport-height: actual pixel value for mobile layouts
+          // Skip micro-updates (less than 50px change might be just toolbar hiding)
+          if (Math.abs(height - lastHeight) < 50) return
+
+          lastHeight = height
           doc.style.setProperty('--visual-viewport-height', `${height}px`)
-          // --visual-viewport-offset-top: how much visual viewport has scrolled
-          doc.style.setProperty('--visual-viewport-offset-top', `${offsetTop}px`)
-          // --vh: 1% of viewport for calc() usage (legacy)
           doc.style.setProperty('--vh', `${height * 0.01}px`)
         })
       }
 
-      // Initial set
-      updateViewportHeight()
+      // CRITICAL: When iOS auto-scrolls to show focused element, reset scroll
+      // This prevents the "off-screen" issue when tapping bottom half
+      let scrollResetTimeout: ReturnType<typeof setTimeout> | null = null
 
-      // Listen for changes
-      window.addEventListener('resize', updateViewportHeight)
-      window.visualViewport?.addEventListener('resize', updateViewportHeight)
-      window.visualViewport?.addEventListener('scroll', updateViewportHeight)
+      function handleViewportScroll() {
+        const vv = window.visualViewport
+        if (!vv || vv.offsetTop === 0) return
+
+        // Clear any pending reset
+        if (scrollResetTimeout) clearTimeout(scrollResetTimeout)
+
+        // Debounce the scroll reset to let iOS finish its animation
+        scrollResetTimeout = setTimeout(() => {
+          // Double-check offsetTop is still non-zero
+          if (window.visualViewport && window.visualViewport.offsetTop > 0) {
+            // Reset window scroll - our fixed container will realign
+            window.scrollTo(0, 0)
+          }
+        }, 100)
+      }
+
+      window.visualViewport?.addEventListener('resize', handleViewportResize)
+      window.visualViewport?.addEventListener('scroll', handleViewportScroll)
+
+      return () => {
+        if (rafId) cancelAnimationFrame(rafId)
+        if (scrollResetTimeout) clearTimeout(scrollResetTimeout)
+        window.visualViewport?.removeEventListener('resize', handleViewportResize)
+        window.visualViewport?.removeEventListener('scroll', handleViewportScroll)
+      }
     }
   }, [])
 
diff --git a/packages/webapp/src/styles/_mobile.scss b/packages/webapp/src/styles/_mobile.scss
