@fluixi-ui/interactions

Headless press & hover primitives for Fluixi UI. Normalizes mouse, touch, pen and keyboard into one interaction API, tracks pressed / hovered / focus state, and attaches directly to whatever element you render — no wrapper, no styling.

They are the interaction layer other widgets are built on: Button, ToggleButton, MenuItem, ListItem, Card, Link, tab/accordion headers, tooltip and dialog triggers, navigation items — all of them are "a thing you press and/or hover", so all of them compose these two.

npm i @fluixi-ui/interactions

Pressable

import { Pressable } from '@fluixi-ui/interactions';

<Pressable as="button" onPress={() => save()}>
  Save
</Pressable>

Every press source is normalized into the same callbacks:

<Pressable
  onPressStart={(e) => …}   // pointer down / key down
  onPressMove={(e) => …}    // e.dx / e.dy since start
  onPressEnd={(e) => …}     // released (whether or not it counted)
  onPress={(e) => …}        // released *on* the target — the "click"
  onLongPress={(e) => …}    // held past longPressDelay (default 500ms)
  onPressCancel={(e) => …}  // dragged off, scrolled away, or blurred
/>

State via render prop

State is exposed as accessors, so reads stay fine-grained — call them:

<Pressable>
  {(state) => (
    <div class={{ active: state.pressed(), hovered: state.hovered() }}>…</div>
  )}
</Pressable>

State via data attributes (preferred for styling)

The rendered element automatically carries the current state, so you can style it in plain CSS with zero JS:

[data-pressed] { opacity: 0.7; }
[data-hovered] { background: var(--hover); }
[data-focus-visible] { outline: 2px solid var(--ring); }
[data-disabled] { opacity: 0.5; pointer-events: none; }

Attributes set: data-pressed, data-hovered, data-focused, data-focus-visible, data-disabled.

Props

| Prop | Default | Notes | | --- | --- | --- | | as | "div" | Element or component to render (see Polymorphic). | | disabled | false | Inert + aria-disabled; removes non-native elements from the tab order. | | tabIndex | 0* | *Only injected for non-native elements. | | role | "button"* | *Only injected for non-native elements. | | longPressDelay | 500 | ms before onLongPress fires (and the release stops counting as a press). | | hitSlop | 0 | Extra px around the element that still counts as "inside". Number or per-side. | | pressRetentionOffset | 16 | How far the pointer may drift past the element before the press cancels. | | preventFocusOnPress | false | Keep focus where it is (e.g. a toolbar button beside an input). |

Hoverable

Pointer-only — it never activates on touch, so a tap never leaves an element stuck in a hovered state.

import { Hoverable } from '@fluixi-ui/interactions';

<Hoverable as="a" href="/pricing" onHoverStart={prefetch}>
  {(state) => <>Pricing {state.hovered() && <Arrow />}</>}
</Hoverable>

Callbacks: onHoverStart, onHoverMove, onHoverEnd. Attribute: data-hovered.

Composition

They never touch each other's state, so nest them either way:

<Hoverable>
  {(hover) => (
    <Pressable>{(press) => <Card raised={hover.hovered()} down={press.pressed()} />}</Pressable>
  )}
</Hoverable>

As child

as renders any tag or component and attaches the interaction logic to it directly — no extra DOM node. Props are inferred from as:

<Pressable as="button" type="submit">…</Pressable>   {/* button props */}
<Pressable as="a" href="/home">…</Pressable>          {/* anchor props */}
<Pressable as={Card} elevation={2}>…</Pressable>      {/* Card props */}

When wrapping a component or element, props are merged, never clobbered: refs are combined, class concatenated, style merged, and your event handlers run after the internal ones (which never call preventDefault on your behalf).

Headless hooks

The components are thin shells over the reactive engines, which you can use directly when you need the behavior without the element wiring:

import { createPressable, createHoverable } from '@fluixi-ui/interactions';

const state = createPressable(() => el(), { onPress, longPressDelay: 400 });
state.pressed(); // Accessor<boolean>
state.cancel();  // abort an in-flight press

Accessibility

• Non-native elements get role="button" + tabindex="0" so they focus and activate from the keyboard like a real button; native <button>/<a> are left alone.
• Enter and Space activate; Space's page-scroll is suppressed.
• disabled sets aria-disabled="true", blocks all interaction, and drops non-native elements out of the tab order.
• focus-visible follows the browser's own heuristic (:focus-visible), so a ring shows for keyboard focus but not a mouse press.

Design decisions

• Pointer Events as the single source. One event model covers mouse, touch and pen, so there is no mouse/touch double-firing to de-dupe and no touch-action guesswork.
• Global listeners only while pressing. On pointer-down the engine adds pointermove/pointerup on the document so a release or drag outside the element is still handled, then removes them on release. Idle, nothing is bound globally.
• State is accessors, not a snapshot object. Reading state.pressed() inside a binding subscribes just that binding, so a press re-styles only what depends on it — no component re-render.
• Data attributes are the primary styling API. They need no JS in the consumer and work with any CSS methodology, matching the rest of Fluixi UI's role/data-* styling model.
• Long press consumes the click. Once onLongPress fires, the following release does not also fire onPress, so the two never both trigger.

Performance

• One reactive effect per component, re-run only when the target element changes.
• Four signals for Pressable (pressed/hovered/focused/focus-visible), one for Hoverable. disabled is derived from your accessor — no extra signal.
• No polling and no requestAnimationFrame; move events are delivered by the browser at pointer cadence.
• Per-press scratch state is plain locals, reused across presses; only fired callbacks allocate an event object.
• Tree-shakeable: import only Hoverable (or only a hook) and the rest is dropped.
• SSR-safe: all listeners are bound inside an effect that never runs on the server.