Pointer gesture
Generated by website/scripts/generate-api.ts from packages/gridla/src. Do not edit by hand; run bun run generate in website/.
The pointer and keyboard state machine over a minimal event shape: drag threshold, click versus drag, axis lock, snap bypass, resize edges, pointer capture, keyboard nudges. bindPointer and bindKeyboard attach native listeners.
import { createPointerGesture, GRID_DATA } from 'gridla/interaction'
import type { GridKeyboardEventLike, GridPointerEventLike, GridPointerGesture, GridPointerGestureDeps, GridPointerGestureOptions } from 'gridla/interaction'
Functions
createPointerGesture
function · interaction/gesture.ts:132
Create the pointer and keyboard state machine for controller. Mark items
with data-gridla-item, drag surfaces with data-gridla-drag-handle, and
resize handles with data-gridla-resize-handle + data-gridla-edge
(see GRID_DATA).
Behavior:
- press on a drag handle selects the item; moving past the threshold starts a move;
- press on a resize handle starts a resize immediately;
- Shift locks a move to the dominant axis; Ctrl/Cmd bypasses alignment snapping;
- Escape cancels; arrow keys nudge the selected item (Alt resizes, Shift x4).
export function createPointerGesture<TData = unknown>(
controller: GridController<TData>,
deps: GridPointerGestureDeps = {},
): GridPointerGesture
Constants
GRID_DATA
const · interaction/attributes.ts:6
Data attributes the pointer gesture looks for on pointer down. Adapters emit
them on their elements: item carries the item id, dragHandle marks a
surface that starts a move, resizeHandle plus edge mark a resize handle.
export const GRID_DATA: { readonly item: "data-gridla-item"; readonly dragHandle: "data-gridla-drag-handle"; readonly resizeHandle: "data-gridla-resize-handle"; readonly edge: "data-gridla-edge"; }
Types
GridKeyboardEventLike
type · interaction/gesture.ts:29
The subset of a keyboard event the gesture reads. Native KeyboardEvents
and React's synthetic keyboard events both satisfy it.
export type GridKeyboardEventLike = {
key: string
shiftKey?: boolean
altKey?: boolean
preventDefault: () => void
}
GridPointerEventLike
type · interaction/gesture.ts:12
The subset of a pointer event the gesture reads. Native PointerEvents and
React's synthetic pointer events both satisfy it.
export type GridPointerEventLike = {
pointerId: number
clientX: number
clientY: number
button?: number
pointerType?: string
shiftKey?: boolean
ctrlKey?: boolean
metaKey?: boolean
target: unknown
preventDefault: () => void
}
GridPointerGesture
type · interaction/gesture.ts:68
Pointer and keyboard state machine for one canvas. Feed it events (or let
bindPointer/bindKeyboard attach native listeners) and it drives the
controller's gesture API.
export type GridPointerGesture = {
/** Press: selects the item under a drag handle, or starts a resize on a resize handle. */
pointerDown: (event: GridPointerEventLike) => void
/** Move: turns a press into a drag past the threshold, then tracks the gesture. */
pointerMove: (event: GridPointerEventLike) => void
/** Release: reports a click for an unmoved press, otherwise commits the gesture. */
pointerUp: (event: GridPointerEventLike) => void
/** Cancel: abandons the gesture without committing. */
pointerCancel: (event: GridPointerEventLike) => void
/** Escape cancels; arrows nudge the selected item (Alt resizes, Shift x4); Delete reports. */
keyDown: (event: GridKeyboardEventLike) => void
/** Replace the callbacks and the `enabled` switch. */
setOptions: (options: GridPointerGestureOptions) => void
/**
* Attach `pointerdown`/`pointermove`/`pointerup`/`pointercancel` listeners to
* `element`. Returns a function that removes them.
*/
bindPointer: (element: HTMLElement) => () => void
/** Attach a `keydown` listener to `element`. Returns a function that removes it. */
bindKeyboard: (element: HTMLElement) => () => void
/** Abandon any gesture in progress and release pointer capture. */
destroy: () => void
}
GridPointerGestureDeps
type · interaction/gesture.ts:54
Dependencies of createPointerGesture beyond the controller. Everything is
optional: by default the canvas element is the one registered on the
controller's gesture API, and no transfer scope is consulted.
export type GridPointerGestureDeps = GridPointerGestureOptions & {
/** The canvas element; used for pointer capture and coordinate conversion. */
getElement?: () => HTMLElement | null
/** Convert client coordinates to canvas pixels. Defaults to subtracting the element's rect. */
toLocal?: (client: GridPoint) => GridPoint | null
/** Transfer scope the controller is registered in, for cross-canvas drags. */
scope?: TransferScope | null
}
GridPointerGestureOptions
type · interaction/gesture.ts:37
Per-gesture callbacks and switches. Change them at any time with setOptions.
export type GridPointerGestureOptions = {
/**
* Called with the item id when a press does not turn into a drag (a click).
* Selection already happened on pointer down.
*/
onItemClick?: (itemId: string) => void
/** Called when Delete or Backspace is pressed with an item selected. */
onDeleteKey?: (itemId: string) => void
/** Set `false` to disable pointer-driven gestures. Default `true`. */
enabled?: boolean
}