Skip to content

Gestures enhancer

Add swipe, pan, tap and pinch gestures to the reader with @prose-reader/enhancer-gestures, configure them, and react to each gesture through gestures$.

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

Terminal window
npm install @prose-reader/enhancer-gestures @prose-reader/core gesturx rxjs

All three are peer dependencies. The enhancer runs against the reader your app creates, so it shares that reader's @prose-reader/core rather than bringing its own. It needs the core it was released with or a later one of the same major, gesturx 8 (^8.0.0), and rxjs 7.5.5 or any later 7.x (^7.5.5).

Connect the enhancer to your reader:

import { gesturesEnhancer } from "@prose-reader/enhancer-gestures"
const createAppReader = gesturesEnhancer(createReader)
/**
* There is no required configuration for this
* enhancer.
*/
const reader = createAppReader({ manifest })

Gesture recognitions are done relative to the reader container by default. This is to ensure consistency in behaviors no matter how your reader is being integrated.

For example, we detect taps on edge of screen to navigate pages. If we were using window object as reference, tapping on the side of the book would not work in this situation:

A reader in the middle of a wider page: the edge of the book, where a tap turns the page, is far from the edge of the window

In this situation the user is using the reader in only a certain part of the web page and therefore the gestures should work relative to the reader container.

While the reader is mounted, the enhancer's stylesheet gives its container touch-action: none !important, and every element in it inherits that value. So the browser neither scrolls nor zooms on a touch screen, and the gestures keep their pointer events. The stylesheet goes into the reader's document, wins over a touch-action that your app sets on the container without !important, and goes away when the reader is destroyed.

  • Swipe to turn pages
  • Pan to turn pages
  • Tap to turn pages

Gestures start on a press of the primary button: a left click, a finger or a pen's tip. A right click, which opens the context menu, and a middle click start none: they tap, pan and swipe nothing, turn no page and are not reported on gestures$.

  • Pinch to start zooming
  • Pan to move zoom position (When zooming)

The API is under the gestures namespace.

type Options = {
panNavigation?: "pan" | "swipe" | false
/**
* The highest scale a pinch zooms to, `Infinity` by default.
* At `1` or less, a pinch never zooms in.
*/
zoomMaxScale?: number
pinchCancelPan?: boolean
/**
* List of selectors that will be tested to ignore gestures.
* eg: preventing gestures on a bookmark button.
*/
ignore?: string[]
}

With react-reader, set zoomMaxScale with the zoomMaxScale prop of ReactReaderProvider instead, 5 by default: react-reader writes it over this setting.

Read or update the enhancer settings.

type PageContext = undefined | {
spineItem: SpineItem
spineItemPageIndex: number
spineItemPagePosition: UnsafeSpineItemPagePosition
pageSize: {
width: number
height: number
}
}
type Hook = {
/**
* Use this hook to control whether a gesture should be recognized or not.
* eg: You can check whether a gesture is on a bookmark button and cancel it.
*/
name: "beforeTapGesture"
runFn: (
params: { event$: Observable<{ event: GestureEvent; page: PageContext }> }
) => Observable<boolean>
}

page describes the page under the tap, or is undefined when no spine item is under it:

  • spineItemPagePosition: where the tap is, from the top-left corner of that page.
  • pageSize: the size of that page, usually reader.viewport.pageSize. In a spread, a chapter in vertical writing does not show two pages side by side: it shows one page across the whole view, so its pageSize is as wide as the view.

In a book that scrolls, a chapter is not cut into pages: it is one long page. A tap far down a chapter is then on its page 0, with a large spineItemPagePosition.y, while pageSize stays reader.viewport.pageSize, not the size of the chapter. The position can be outside pageSize.

The first value of each beforeTapGesture hook is its verdict, and later values change nothing. The tap waits for the verdict of every hook, so a hook that neither emits nor completes holds the tap until the next tap. A verdict of false from any hook drops the tap: it turns no page, and gestures$ does not report it. Anything else from a hook lets the tap go on:

  • a verdict of true;
  • a completion with no verdict;
  • an error, emitted or thrown as the hook is called. The enhancer reports the error, the other hooks still give their verdicts, and the gestures that follow are recognized as before.
Observable<{
type: "tap";
gestureEvent: TapEvent;
handled: boolean;
} | {
type: "pan";
gestureEvent: PanEvent;
} | {
type: "swipe";
gestureEvent: SwipeEvent;
} | {
type: "pinch";
gestureEvent: PinchEvent;
}>

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).

It completes when the reader is destroyed.

Imagine you want to show/hide a menu when the user clicks on the screen. The enhancer will trigger a navigation when the user taps 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) => {
if (event.type === "tap" && !event.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.

A pinch zooms. To have it resize the text instead, keep it from zooming with a zoomMaxScale of 1, and update fontScale from the pinch events of gestures$:

import {
asyncScheduler,
filter,
map,
switchMap,
takeWhile,
throttleTime,
} from "rxjs"
const reader = createAppReader({ manifest, gestures: { zoomMaxScale: 1 } })
const pinchEvents$ = reader.gestures.gestures$.pipe(
filter((gesture) => gesture.type === "pinch"),
map(({ gestureEvent }) => gestureEvent),
)
pinchEvents$
.pipe(
filter((event) => event.type === "pinchStart"),
switchMap(() => {
const fontScaleAtPinchStart = reader.settings.values.fontScale
return pinchEvents$.pipe(
takeWhile((event) => event.type !== "pinchEnd", true),
// Each change of font scale lays the book out again
throttleTime(500, asyncScheduler, { leading: true, trailing: true }),
// `scale` counts from the start of the pinch
map((event) =>
Math.min(Math.max(fontScaleAtPinchStart * event.scale, 0.5), 3),
),
)
}),
)
.subscribe((fontScale) => {
reader.settings.update({ fontScale })
})

The text follows the pinch from the font scale it had when the pinch started, between 0.5 and 3 here, and ends at the scale of the pinch's last move.