Recognizer

Recognizers: a gesture's state from an Environment's input. hover, press, focus and inView are each a Stream of whether their gesture is on; hoverEvents, pressEvents and inViewEvents tell each start and end with the event behind it. Each has a watch too, watchHover, watchPress, watchFocus and watchInView, which calls you inside each event's dispatch while a Scope is open, with no fiber of its own: a binding's gestures run on these. Drags and pans are DragRecognizer's.

import * as Recognizer from "@wardic/core/Recognizer"

yield* Recognizer.watchPress(button, {
  on: ({ phase }) => {
    if (phase === "tap") submit()
  },
})

Interfaces

Edge

A gesture's start or end, and the event that turned it.

Properties

active

readonly active: boolean;

Whether the gesture is on now.

event

readonly event: PointerLikeEvent;

The event that turned it: its x and y, less its scroll, say where the pointer was on the screen.

FocusOptions

focus's options.

Properties

visible?

readonly visible?: boolean;

true: only a focus the Environment shows counts, a keyboard's, not a click's. Default false.

HoverHandlers

watchHover's handlers: on, each start and end, and onMove, each move between them.

Extends

Handlers<Edge>

Properties

on

readonly on: (value) => void;

Each event or value, inside the event's dispatch.

Parameters

value

Edge

Returns

void

Inherited from

Handlers.on

onDefect?

readonly onDefect?: OnDefect;

A throw from a handler. Without it, the throw goes up the platform's dispatch.

Inherited from

Handlers.onDefect

onEnd?

readonly onEnd?: () => void;

The feed ran out, as a test's script does.

Returns

void

Inherited from

Handlers.onEnd

onMove?

readonly onMove?: (event) => void;

Each move of the pointer over the target while the hover is on, which Motion's hover doesn't have. A touch never hovers, and a held pointer whose leave waits for its release isn't over the target, so neither moves it.

Parameters

event

PointerLikeEvent

Returns

void

onStop?

readonly onStop?: () => void;

Once, when the watch stops: its Scope closed, or its handler done. For a watch that holds something of its own beside the feed.

Returns

void

Inherited from

Handlers.onStop

InViewOptions

inView's options, as Motion's viewport: the Probe's root, margin and amount, and once.

Extends

IntersectionOptions

Properties

amount?

readonly amount?: number;

How much of the target must be in it to count: from 0, any of it, to 1, all of it.

Inherited from

IntersectionOptions.amount

margin?

readonly margin?: unknown;

How far the container's edges are grown, or shrunk, before it counts, in the Environment's own syntax: core passes it on, as it does ScrollOptions.offset.

Inherited from

IntersectionOptions.margin

once?

readonly once?: boolean;

true: settled at its first entry, in view from then on. Default false.

root?

readonly root?: unknown;

The container it's observed against: the viewport when left out.

Inherited from

IntersectionOptions.root

PressOptions

A press's options.

Properties

keys?

readonly keys?: boolean;

false: no key presses it, for a target whose Enter and Space are someone else's: a Reorder item's, which lift it. Default true.

propagate?

readonly propagate?: boolean | LazyArg<boolean>;

Whether its presses reach its pressable ancestors, as Motion's propagate.tap, read at each press's start. false claims the down or the key it starts from, so no ancestor's press starts from it. Default true.

ViewEdge

A target coming into view or leaving it.

Properties

active

readonly active: boolean;

Whether it's in view now.

raw?

readonly raw?: unknown;

The platform's record of it, which core never reads: a binding hands it to an app's callback.

Type Aliases

PressEvent

type PressEvent = 
  | {
  event: PointerLikeEvent;
  input: "pointer";
  phase: PressPhase;
}
  | {
  event:   | KeyboardLikeEvent
     | FocusLikeEvent;
  input: "keyboard";
  phase: PressPhase;
};

A press's start or end, and the event it came with: a pointer's (input: "pointer"), or a key's, or the blur that cancelled a key's press (input: "keyboard").

PressPhase

type PressPhase = "start" | "tap" | "cancel" | "dragged";

How a press began or ended, as Motion's press: "start" at its down; "tap", a release on the target or inside it, or a pressed key coming up; "cancel", a release elsewhere, a cancel, a lost release, or a blur that ends a key's press; "dragged", an end after a drag took over, which Motion tells as neither.

Variables

watchHover

const watchHover: (target, handlers) => Effect.Effect<void, never, Scope.Scope | InputSource>;

Watches hover on target while the Scope is open: handlers.on hears each start and end, as hoverEvents tells them, and handlers.onMove each move over it while the hover is on, inside the pointer event's dispatch. A throw from either goes to handlers.onDefect.

Parameters

target

unknown

handlers

HoverHandlers

Returns

Effect.Effect<void, never, Scope.Scope | InputSource>

Example

yield* Recognizer.watchHover(card, {
  on: ({ active }) => setHovered(active),
  onMove: (event) => follow(event.x, event.y),
})

watchPress

const watchPress: (target, handlers, options?) => Effect.Effect<void, never, Scope.Scope | InputSource>;

Watches presses on target while the Scope is open: handlers.on hears each start and end, as pressEvents tells them, inside the event's dispatch, as watchHover's. A pointer presses it, or a key. handlers.onEnd is told once every feed it watches has run out.

Where the Environment says where focus is, its keys are watched only while focus is within the target, as Motion's press listens for keys once its element has focus: an element at rest holds only its focus feed.

Parameters

target

unknown

handlers

Handlers<PressEvent>

options?

PressOptions

Returns

Effect.Effect<void, never, Scope.Scope | InputSource>

Functions

focus()

function focus(target, options?): Stream<boolean, never, InputSource>;

Whether target has focus: true at its focus, false at its blur, each change once. A focus or blur inside it changes nothing. With visible: true, as Motion's whileFocus, only a focus the Environment shows counts: a keyboard's, not a click's.

Parameters

target

unknown

options?

FocusOptions = {}

Returns

Stream<boolean, never, InputSource>

hover()

function hover(target): Stream<boolean, never, InputSource>;

Whether the pointer is over target: true once it comes over, false once it leaves, each change once. A leave while a pointer that pressed target is still held waits for its release. A touch never hovers, and no hover starts while a drag is active.

Parameters

target

unknown

Returns

Stream<boolean, never, InputSource>

hoverEvents()

function hoverEvents(target): Stream<Edge, never, InputSource>;

hover's starts and ends with the event that turned each, as Motion's onHoverStart and onHoverEnd.

Parameters

target

unknown

Returns

Stream<Edge, never, InputSource>

inView()

function inView(target, options?): Stream<boolean, never, Probe>;

Whether target is in view, by the Probe: its first report, then each change, against options' root, margin and amount. With once: true the Stream ends at its first true, and its observer with it, so a target seen once never goes back to false.

Parameters

target

unknown

options?

InViewOptions = {}

Returns

Stream<boolean, never, Probe>

Example

Recognizer.inView(section, { amount: 0.5, once: true })

inViewEvents()

function inViewEvents(target, options?): Stream<ViewEdge, never, Probe>;

inView's entries and leaves, with the platform's record of each, as Motion's onViewportEnter and onViewportLeave: a target that starts out of view tells nothing until it enters. With once: true it ends at its first entry, with no leave.

Parameters

target

unknown

options?

InViewOptions = {}

Returns

Stream<ViewEdge, never, Probe>

press()

function press(target, options?): Stream<boolean, never, InputSource>;

Whether target is pressed: true once the primary pointer goes down on it, false once it's released or cancelled, wherever that happens, or at its first move with no button after a lost release. A key presses it too, Enter or Space, held while the key is down. No press starts while a drag is active. Each change once.

Parameters

target

unknown

options?

PressOptions

Returns

Stream<boolean, never, InputSource>

pressEvents()

function pressEvents(target, options?): Stream<PressEvent, never, InputSource>;

press's starts and ends with how each began or ended, as Motion's onTapStart, onTap and onTapCancel, and a press a drag took over, which Motion tells as neither.

Parameters

target

unknown

options?

PressOptions

Returns

Stream<PressEvent, never, InputSource>

watchFocus()

function watchFocus(
   target, 
   options, 
   handlers
): Effect<void, never, Scope | InputSource>;

Watches focus on target while the Scope is open: handlers.on hears whether it has focus at first, then each change, as focus tells them, inside the focus event's dispatch.

function watchInView(
   target, 
   options, 
   handlers
): Effect<void, never, Scope | Probe>;

Watches target's view while the Scope is open: handlers.on hears each entry and leave, as inViewEvents tells them; with once, the first entry only, and then its observer goes.