`gst`

Touch and gesture handling for browser UI - attach touchstart/touchmove/touchend listeners to DOM elements, automatically detect taps (<300 ms, <10 px movement), swipe direction and distance (<500 ms, >50 px), two-finger pinch distance, long press with configurable delay, and pan/drag delta tracking.

Load with: use gst

What this module does

gst wraps the browser Touch Events API in an ergonomic state-object pattern. A gesture state is created for a DOM element with gstne, callbacks are registered with the gstot/gstos/gstop setters, and then gstgo attaches the underlying event listeners. The listener logic recognises taps and swipes automatically based on time and displacement thresholds.

Separate helpers provide long-press detection (gstlp) and pan/drag tracking (gstpa).

Quick example

use gst

# Basic gestures on a DOM element
g = gstne(my_el)
g = gstos(g, \(dir, dist, e) prn("swiped " + dir))
g = gstot(g, \(x, y) prn("tap at " + str(x) + "," + str(y)))
g = gstgo(g)

# Long press
lp = gstlp(my_el)
lp = oset(lp, "onlp", \() prn("long press!"))
lp = oset(lp, "dly", 700)
lp = gstlp(lp)

# Pan / drag
gstpa(my_el,
    \(dx, dy) prn("moving " + str(dx) + "," + str(dy)),
    \(dx, dy) prn("done"))

Functions

Gesture state

gstne(element)

Creates a gesture state for a DOM element. Stores the element and initialises all callbacks to nil.

gstot(state, fn)

Registers callbacks in order: first call sets touchstart (onts), second sets touchstart alias (ontp), third sets touchmove (ontm), fourth sets touchend (onte), fifth sets tap (ontap).

gstos(state, fn)

Registers the swipe callback (onsw). Called with (direction, distance, event) where direction is "left", "right", "up", or "down".

gstop(state, fn)

Registers the pinch callback (onpin). Called with (distance, event) when two fingers are detected on touchmove.

gstgo(state)

Attaches touchstart, touchmove, and touchend listeners to the element. Returns the updated state. Detects taps (time <300 ms, displacement <10 px) and swipes (time <500 ms, displacement >50 px in any direction).

Helpers

gstds(touchA, touchB)

Returns the Euclidean distance between two touch points (objects with pgX and pgY).

gstsw(dx, dy)

Classifies a displacement vector into a swipe direction string: "left", "right", "up", or "down" based on which axis dominates.

Long press

gstlp(element) - create

Creates a long-press state: {el, onlp:nil, t:nil, dly:500}. Set onlp and optionally dly (ms) before calling the activate overload.

gstlp(state) - activate

Attaches touchstart and touchend listeners that fire onlp() if the touch is held for at least dly milliseconds.

Pan / drag

gstpa(element, on_move, on_end)

Attaches pan listeners directly to the element. on_move(dx, dy) is called on every touchmove with the displacement from the starting point. on_end(dx, dy) is called on touchend.

Notes

Requires a browser host environment with a Touch Events API.
Requires trl and tim.