pnpm add @audio-ui/core
import { createXYPadController, LARGE_STEP_MULTIPLIER, STATE_ATTRIBUTES_MAPPING, toPercent } from "@audio-ui/core/xypad";| Adapters | @audio-ui/react/xypad, @audio-ui/elements/xypad |
|---|
| Export | Kind | What it is |
|---|---|---|
createXYPadController | function | A pad's behavior with no view attached: its point, held or controlled, every way of moving it, and what it looks like as a snapshot. |
XYPadChangeEventDetails | type | What onValueChange receives with each change: the reason, the event behind it, and cancel() to refuse the change. |
XYPadChangeEventReason | type | Why the value changed: "press", "drag", "keyboard", "wheel", "input-change" (a typed value) or "reset". |
XYPadCommitEventDetails | type | What onValueCommitted receives once a gesture ends: the reason and the event behind it. |
XYPadCommitEventReason | type | Why the value was committed: the same reasons as a change. |
XYPadController | interface | What createXYPadController returns: the snapshot to draw from, and the press, keys, wheel, typed values and reset that move the point. |
XYPadOptions | interface | The options of createXYPadController: the point, held or controlled, each axis's range and step, the formatting and the callbacks. |
XYPadPoint | interface | A point on the pad, in the units of each axis. |
XYPadSnapshot | interface | What a view draws a pad from. |
Axis | type | One of the pad's two axes. |
LARGE_STEP_MULTIPLIER | const | Shift + arrows and Page Up/Down move this many steps at once. |
STATE_ATTRIBUTES_MAPPING | const | Only disabled and dragging become data attributes; the numbers stay in state. |
toPercent | function | Where value sits between min and max, from 0 to 1. |
Usage
The controller follows the contract every controller shares: create it once, draw from its snapshot, send it the input.
import { createXYPadController } from "@audio-ui/core/xypad";
const pad = createXYPadController({ minX: 0, maxX: 1, minY: 0, maxY: 1, value: { x: 0.5, y: 0.5 }, stepX: 0.01, stepY: 0.01 });| Option | Meaning |
|---|---|
value, defaultValue | A point, { x, y } |
minX, maxX, stepX, minY, maxY, stepY | Each axis's range and grid |
format, locale, disabled | Formats each axis separately, as formatted.x and formatted.y |
A pad has two parameters on one gesture. type(axis, value, event) takes the axis first, because a text input is per axis. Shift with the arrows, and Page Up and Page Down, move ten steps at once (LARGE_STEP_MULTIPLIER). reset(event) returns both axes to their defaults: the element calls it on a double-click, and the controller itself resets on Alt with a press and on Delete or Backspace. A double tap is not a reset here, since a tap on a pad places the point, so two quick taps are two points and not a request to go back.
The XY Pad draws this controller in React.