Gestures

This enhancer implement common gesture patterns using https://github.com/mbret/gesturx. Tap on edge or swipe to turn pages, pinch to change font scale, etc. It implements the most common gestures while trying to stay generic and configurable.

Getting Started

npm install @prose-reader/enhancer-gestures

Connect the enhancer to your reader:

import { gesturesEnhancer } from "@prose-reader/enhancer-gestures"

const createAppReader = gesturesEnhancer(createReader)

/**
 * There are no required configuration for this
 * enhancer.
 */
const reader = createAppReader({})

API

The API is under the gestures namespace.

type Options = {
  panNavigation?: "pan" | "swipe" | false
  fontScalePinchEnabled?: boolean
  fontScaleMaxScale?: number
  fontScaleMinScale?: number
  fontScalePinchThrottleTime?: number
  pinchCancelPan?: boolean
  /**
   * List of selectors that will be tested to ignore gestures.
   * eg: preventing gestures on a bookmark button.
   */
  ignore?: string[]
}

.settings

Read or update the enhancer settings.

.hooks

type Hook = {
  /**
   * Use this hook to control whether a gesture should be recognized or not.
   * eg: You can check wheter a gesture is on a bookmark button and cancel it.
   */
  name: "beforeGesture"
  runFn: (params: { event$: Observable<GestureEvent> }) => Observable<boolean>
}

.gestures$

Observable<{ event: GestureEvent; handled: boolean }>

Emits all gesture events that are recognized and processed by the enhancer. It will attach a boolean to let you know whether the gesture has been handled or not. Typically whether an action happened following this gesture (like a passthrough).

Imagine you want to show/hide a menu when the user click on the screen. The enhancer will trigger a navigation when the user tap on the left or right edge so you likely don't want to show the menu at the moment. However clicking outside of this range will have no effect. This is where you can intercept the gesture and show your menu.

/**
 * Here we have a tap event that does not trigger any effects.
 * We can fallback to trigger the menu.
 */
reader?.gestures.gestures$.pipe(
  tap(({ event, handled }) => {
    if (event?.type === "tap" && !handled) {
      toggleMenu()
    }
  })
)

Basically if you want to do something based on a gesture and make sure it does not happen with another effect this observable is a good candidate.