feat(reader): Add support for touch screen swipe navigation

Author: lgarbarini

apps/reader/locales/en-US.ts

@@ -38,6 +38,7 @@ export default {
   'typography.font_weight': 'Font Weight',
   'typography.line_height': 'Line Height',
   'typography.zoom': 'Zoom',
+  'typography.swipe_navigation': 'Swipe Navigation',
 
   'theme.title': 'Theme',
   'theme.source_color': 'Source Color',
@@ -49,6 +50,8 @@ export default {
   'settings.color_scheme.system': 'System',
   'settings.color_scheme.light': 'Light',
   'settings.color_scheme.dark': 'Dark',
+  'settings.navigation': 'Navigation',
+  'settings.swipe_navigation': 'Swipe Navigation',
   'settings.synchronization.title': 'Synchronization',
   'settings.synchronization.authorize': 'Authorize',
   'settings.synchronization.unauthorize': 'Unauthorize',

apps/reader/src/components/Reader.tsx

@@ -15,12 +15,11 @@ import useTilg from 'tilg'
 import { useSnapshot } from 'valtio'
 
 import { RenditionSpread } from '@flow/epubjs/types/rendition'
-import { navbarState } from '@flow/reader/state'
+import { navbarState, useSettings } from '@flow/reader/state'
 
 import { db } from '../db'
 import { handleFiles } from '../file'
 import {
-  hasSelection,
   useBackground,
   useColorScheme,
   useDisablePinchZooming,
@@ -181,7 +180,11 @@ function ReaderGroup({ index }: ReaderGroupProps) {
         {group.tabs.map((tab, i) => (
           <PaneContainer active={i === selectedIndex} key={tab.id}>
             {tab instanceof BookTab ? (
-              <BookPane tab={tab} onMouseDown={handleMouseDown} />
+              <BookPane
+                tab={tab}
+                onMouseDown={handleMouseDown}
+                swipeThreshold={60}
+              />
             ) : (
               <tab.Component />
             )}
@@ -202,17 +205,60 @@ const PaneContainer: React.FC<PaneContainerProps> = ({ active, children }) => {
 interface BookPaneProps {
   tab: BookTab
   onMouseDown: () => void
+  swipeThreshold?: number
 }
 
-function BookPane({ tab, onMouseDown }: BookPaneProps) {
+function BookPane({ tab, onMouseDown, swipeThreshold = 60 }: BookPaneProps) {
+  // Constants for swipe behavior
+  const SWIPE_DETECTION_THRESHOLD = 15
+  const SWIPE_DAMPING_FACTOR = 0.4
+  const MAX_SWIPE_OFFSET = 150
+  const SWIPE_RESISTANCE_THRESHOLD = 0.7
+  const SWIPE_TIME_LIMIT = 400
+  const GRADIENT_WIDTH = 60
+
   const ref = useRef<HTMLDivElement>(null)
   const prevSize = useRef(0)
   const typography = useTypography(tab)
   const { dark } = useColorScheme()
   const [background] = useBackground()
+  const [swipeOffset, setSwipeOffset] = useState(0)
+  const [isSwiping, setIsSwiping] = useState(false)
+  const [swipeDirection, setSwipeDirection] = useState<'left' | 'right' | null>(
+    null,
+  )
+  const [showPageTurnGradient, setShowPageTurnGradient] = useState(false)
+  const [settings] = useSettings()
 
   const { iframe, rendition, rendered, container } = useSnapshot(tab)
 
+  // Helper function to generate theme-aware gradient
+  const generateGradient = (direction: 'left' | 'right', isDark: boolean) => {
+    const position = direction === 'right' ? 'left center' : 'right center'
+    const opacity = isDark
+      ? { start: 0.1, mid: 0.05 }
+      : { start: 0.03, mid: 0.015 }
+
+    return `radial-gradient(ellipse 120px 100% at ${position}, rgba(0,0,0,${opacity.start}) 0%, rgba(0,0,0,${opacity.mid}) 40%, transparent 70%)`
+  }
+
+  // Helper function to apply damping to swipe offset
+  const applySwipeDamping = (deltaX: number) => {
+    let dampedOffset = deltaX * SWIPE_DAMPING_FACTOR
+
+    // Add resistance when approaching maximum offset
+    if (
+      Math.abs(dampedOffset) >
+      MAX_SWIPE_OFFSET * SWIPE_RESISTANCE_THRESHOLD
+    ) {
+      const resistance = Math.abs(dampedOffset) / MAX_SWIPE_OFFSET
+      dampedOffset = dampedOffset * (1 - resistance * 0.5)
+    }
+
+    // Clamp to maximum offset
+    return Math.max(-MAX_SWIPE_OFFSET, Math.min(MAX_SWIPE_OFFSET, dampedOffset))
+  }
+
   useTilg()
 
   useEffect(() => {
@@ -341,47 +387,88 @@ function BookPane({ tab, onMouseDown }: BookPaneProps) {
   useEventListener(iframe, 'keydown', handleKeyDown(tab))
 
   useEventListener(iframe, 'touchstart', (e) => {
-    const x0 = e.targetTouches[0]?.clientX ?? 0
-    const y0 = e.targetTouches[0]?.clientY ?? 0
-    const t0 = Date.now()
+    // Early return if swipes are disabled
+    if (!settings.swipeEnabled) return
 
-    if (!iframe) return
-
-    // When selecting text with long tap, `touchend` is not fired,
-    // so instead of use `addEventlistener`, we should use `on*`
-    // to remove the previous listener.
-    iframe.ontouchend = function handleTouchEnd(e: TouchEvent) {
-      iframe.ontouchend = undefined
-      const selection = iframe.getSelection()
-      if (hasSelection(selection)) return
+    const startX = e.targetTouches[0]?.clientX ?? 0
+    const startY = e.targetTouches[0]?.clientY ?? 0
+    const startTime = Date.now()
 
-      const x1 = e.changedTouches[0]?.clientX ?? 0
-      const y1 = e.changedTouches[0]?.clientY ?? 0
-      const t1 = Date.now()
+    if (!iframe) return
 
-      const deltaX = x1 - x0
-      const deltaY = y1 - y0
-      const deltaT = t1 - t0
+    let hasShownGradient = false
 
+    const touchMoveHandler: (e: TouchEvent) => void = (e: TouchEvent) => {
+      const currentX = e.touches[0]?.clientX ?? 0
+      const currentY = e.touches[0]?.clientY ?? 0
+      const deltaX = currentX - startX
+      const deltaY = currentY - startY
       const absX = Math.abs(deltaX)
       const absY = Math.abs(deltaY)
 
-      if (absX < 10) return
+      // Only handle horizontal swipes above detection threshold
+      if (absX > absY && absX > SWIPE_DETECTION_THRESHOLD) {
+        e.preventDefault()
+        setIsSwiping(true)
+
+        // Apply damping for smooth movement
+        const dampedOffset = applySwipeDamping(deltaX)
+        setSwipeOffset(dampedOffset)
 
-      if (absY / absX > 2) {
-        if (deltaT > 100 || absX < 30) {
-          return
+        // Determine swipe direction
+        const direction = deltaX > 0 ? 'right' : 'left'
+        setSwipeDirection(direction)
+
+        // Show gradient when swipe threshold is met
+        const shouldShowGradient = absX > absY && absX > swipeThreshold
+        setShowPageTurnGradient(shouldShowGradient)
+
+        // Track gradient state for page turn commitment
+        if (shouldShowGradient) {
+          hasShownGradient = true
         }
       }
+    }
 
-      if (deltaX > 0) {
-        tab.prev()
-      }
+    const touchEndHandler: (e: TouchEvent) => void = (e: TouchEvent) => {
+      if (!touchMoveHandler || !touchEndHandler) return
 
-      if (deltaX < 0) {
-        tab.next()
+      // Clean up event listeners
+      iframe.removeEventListener('touchmove', touchMoveHandler)
+      iframe.removeEventListener('touchend', touchEndHandler)
+
+      const endX = e.changedTouches[0]?.clientX ?? 0
+      const endY = e.changedTouches[0]?.clientY ?? 0
+      const endTime = Date.now()
+
+      const deltaX = endX - startX
+      const deltaY = endY - startY
+      const deltaTime = endTime - startTime
+      const absX = Math.abs(deltaX)
+      const absY = Math.abs(deltaY)
+
+      // Page turn logic: gradient shown OR fast swipe criteria met
+      const fastSwipeCondition =
+        absX > absY && absX > swipeThreshold && deltaTime < SWIPE_TIME_LIMIT
+      const shouldTurnPage = hasShownGradient || fastSwipeCondition
+
+      if (shouldTurnPage && absX > absY) {
+        if (deltaX > 0) {
+          tab.prev()
+        } else {
+          tab.next()
+        }
       }
+
+      // Reset swipe state
+      setIsSwiping(false)
+      setSwipeOffset(0)
+      setSwipeDirection(null)
+      setShowPageTurnGradient(false)
     }
+
+    iframe.addEventListener('touchmove', touchMoveHandler)
+    iframe.addEventListener('touchend', touchEndHandler)
   })
 
   useDisablePinchZooming(iframe)
@@ -399,18 +486,38 @@ function BookPane({ tab, onMouseDown }: BookPaneProps) {
       <div
         ref={ref}
         className={clsx('relative flex-1', isTouchScreen || 'h-0')}
-        // `color-scheme: dark` will make iframe background white
-        style={{ colorScheme: 'auto' }}
+        style={{
+          colorScheme: 'auto',
+          transform: isSwiping ? `translateX(${swipeOffset}px)` : undefined,
+          transition: isSwiping
+            ? 'none'
+            : 'transform 0.3s cubic-bezier(0.25, 0.46, 0.45, 0.94)',
+        }}
       >
         <div
           className={clsx(
             'absolute inset-0',
-            // do not cover `sash`
             'z-20',
             rendered && 'hidden',
             background,
           )}
         />
+
+        {/* Page turn gradient - provides visual feedback for swipe threshold */}
+        {showPageTurnGradient && swipeDirection && (
+          <div
+            className={clsx(
+              'pointer-events-none absolute inset-y-0 z-30',
+              'transition-opacity duration-150 ease-out',
+              swipeDirection === 'right' ? 'left-0' : 'right-0',
+            )}
+            style={{
+              width: `${GRADIENT_WIDTH}px`,
+              background: generateGradient(swipeDirection, dark ?? false),
+            }}
+          />
+        )}
+
         <TextSelectionMenu tab={tab} />
         <Annotations tab={tab} />
       </div>

apps/reader/src/components/pages/settings.tsx

@@ -9,6 +9,7 @@ import {
   useForceRender,
   useTranslation,
 } from '@flow/reader/hooks'
+import { useSettings } from '@flow/reader/state'
 import { dbx, mapToToken, OAUTH_SUCCESS_MESSAGE } from '@flow/reader/sync'
 
 import { Button } from '../Button'
@@ -19,6 +20,7 @@ export const Settings: React.FC = () => {
   const { scheme, setScheme } = useColorScheme()
   const { asPath, push, locale } = useRouter()
   const t = useTranslation('settings')
+  const [settings, setSettings] = useSettings()
 
   return (
     <Page headline={t('title')}>
@@ -47,6 +49,23 @@ export const Settings: React.FC = () => {
             <option value="dark">{t('color_scheme.dark')}</option>
           </Select>
         </Item>
+        <Item title={t('navigation')}>
+          <div className="flex items-center gap-2">
+            <input
+              type="checkbox"
+              checked={settings.swipeEnabled ?? false}
+              onChange={(e) => {
+                setSettings((prev) => ({
+                  ...prev,
+                  swipeEnabled: e.target.checked,
+                }))
+              }}
+            />
+            <span className="typescale-body-medium">
+              {t('swipe_navigation')}
+            </span>
+          </div>
+        </Item>
         <Synchronization />
         <Item title={t('cache')}>
           <Button

apps/reader/src/state.ts

@@ -29,6 +29,7 @@ export const navbarState = atom<boolean>({
 
 export interface Settings extends TypographyConfiguration {
   theme?: ThemeConfiguration
+  swipeEnabled?: boolean
 }
 
 export interface TypographyConfiguration {
@@ -45,7 +46,9 @@ interface ThemeConfiguration {
   background?: number
 }
 
-export const defaultSettings: Settings = {}
+export const defaultSettings: Settings = {
+  swipeEnabled: false,
+}
 
 const settingsState = atom<Settings>({
   key: 'settings',