Press

Headless Press; covers React Aria usePress, Pointer Events activation.

API

createPress

Create an SSR-safe press normalizer for one host element. Spread the returned pressProps onto the host and call dispose when using this factory outside a Vue effect scope. No DOM global is read at setup.

function createPress(options: PressOptions = {}): PressController

usePress

Create a press normalizer disposed with the current Vue effect scope.

function usePress(options: PressOptions = {}): PressController

PressActivationMemory

Own short-lived tokens that associate release, cancellation, and click.

class PressActivationMemory

readBooleanOption

Resolve and validate a reactive boolean option for JavaScript consumers.

function readBooleanOption( value: PressOptions[keyof Pick< PressOptions, "allowTextSelectionOnPress" | "isDisabled" | "preventFocusOnPress" | "shouldCancelOnPointerExit" >], name: string, ): boolean

readKeyboardBehavior

Resolve the closed keyboard behavior union without accepting mistyped JS.

function readKeyboardBehavior( value: PressOptions["keyboardBehavior"], ): PressKeyboardBehavior

eventElement

Resolve a cross-realm event currentTarget without instanceof assumptions.

function eventElement(event: Event): Element | null

pointerTypeOf

Map Pointer Events' extensible device string to the stable public union.

function pointerTypeOf(event: PointerEvent): PressPointerType

isPrimaryPointer

Only a primary contact and its primary button can activate a control.

function isPrimaryPointer(event: PointerEvent): boolean

createPressEvent

Build a frozen snapshot so later browser mutation cannot change callbacks' data.

function createPressEvent( type: PressEventType, target: Element, pointerType: PressPointerType, originalEvent: Event | null, isCanceled = false, touchIdentifier: number | null = null, ): PressEvent

keyboardActivation

Native elements retain their own activation timing and default actions.

function keyboardActivation( target: Element, key: string, behavior: PressKeyboardBehavior, ): "custom" | "native" | null

isEventInside

Determine pointer containment without assuming events originate in one realm.

function isEventInside( event: Event, target: Element, touchIdentifier: number | null = null, ): boolean

disableTextSelection

Apply a transient selection guard and return an exact, idempotent restore.

function disableTextSelection(target: Element): () => void

validatePressOptions

Validate callback slots eagerly so setup failures never install listeners.

function validatePressOptions(options: PressOptions): void

createPressHandlers

Adapt Pointer Events plus legacy mouse/touch and keyboard events to one lifecycle.

function createPressHandlers(lifecycle: PressLifecycle): PressHandlers

PressLifecycle

Internal press state machine shared by all native-event adapters.

class PressLifecycle

Behavior

Normative state × input → outcome table for @vizejs/ui/press. Every row is exercised by src/families/interaction/press/press*.test.ts; compile-only API assertions live in src/families/interaction/press/press.types.test-d.ts.

Accessibility and native behavior

• click is the activation authority. Pointer release produces pressup and pressend, while the browser's following click produces press. This keeps link navigation, form submission, label forwarding, and assistive-technology activation intact without double invocation.
• Native buttons, relevant input types, links with href, and summaries retain browser keyboard timing and default actions. Custom button-like hosts receive Enter and Space behavior; custom link-like hosts receive Enter only. An <a> or <area> without href has no native activation, so it follows keyboardBehavior like any other custom host.
• Space scrolling is canceled only for custom button semantics. The primitive does not cancel native key events whose default action creates the click.
• Disabled state is evaluated at every phase. If it changes during an active gesture, the gesture and its compatibility click are both canceled.
• Events from focused descendants never invent an activation on the bound ancestor. Composite widgets remain responsible for their own key routing.

Pointer ownership and cancellation

• Only the primary contact and primary button can own a press. An active interaction ignores additional contacts until it ends.
• Pointer Events are preferred. Legacy mouse and touch handlers are present for older engines, including the compatibility-mouse suppression window after a touch contact.
• Leaving the target pauses pressed feedback and re-entry resumes it. Set shouldCancelOnPointerExit to make the first exit terminal.
• Window blur, hidden documents, pointer cancellation, drag start, manual cancellation, scope disposal, and disabled transitions all release document listeners and restore transient text-selection state. Only a blur of the window itself cancels; focus moving between elements during a press does not.
• preventFocusOnPress suppresses the mousedown focus default only for an enabled host and a primary button, including in Pointer Events engines where mousedown still owns that default.

SSR, Vapor, styling, and tree shaking

• Module evaluation and createPress() perform no DOM read, native listener installation, timer scheduling, style injection, or request-global mutation. Listeners and timers exist only during a client interaction.
• usePress() only requires an active Vue effect scope; its plain handler props are compatible with DOM rendering, standard SSR/hydration, and Vapor-compiled consumers. No renderer-specific VNode or component instance is captured.
• This entry emits zero CSS and no attributes. Consumers map readonly isPressed to any classes, data attributes, utility system, CSS variables, or preset package they choose.
• @vizejs/ui/press is an exact ESM subpath. The production consumer gate requires root/subpath byte parity, zero CSS, unused-family elimination, and a hard gzip budget.

Normative references

• Pointer Events Level 4 — primary pointer, buttons, capture, and click
• UI Events — accessible activation through click
• WAI-ARIA APG — Button Pattern
• WAI-ARIA APG — Link Pattern
• WAI-ARIA APG — Developing a Keyboard Interface