pnpm add @audio-ui/core
import { positionOn, valueOn, createPlotHandleController, curvePath, tracePath, /* … */ } from "@audio-ui/core/plot";| Adapters | @audio-ui/react/plot, @audio-ui/elements/plot |
|---|
| Export | Kind | What it is |
|---|---|---|
PlotAxis | interface | One of the plot's two axes: its range and how values spread along it. |
positionOn | function | Where value sits along axis, 0 at its min to 1 at its max. |
valueOn | function | The value at position (0…1) along axis. |
createPlotHandleController | function | A handle's behavior with no view attached: its value, held or controlled, every way of moving it, and what it looks like as a snapshot. |
PlotHandleAxis | type | The axes a handle moves along; the other keeps its value. |
PlotHandleChangeEventDetails | type | What onValueChange receives with each change: the reason, the event behind it, and cancel() to refuse the change. |
PlotHandleChangeEventReason | type | Why the value changed: "drag", "keyboard", "input-change" (a typed value) or "reset". |
PlotHandleCommitEventDetails | type | What onValueCommitted receives once a gesture ends: the reason and the event behind it. |
PlotHandleCommitEventReason | type | Why the value was committed: the same reasons as a change. |
PlotHandleController | interface | What createPlotHandleController returns: the snapshot to draw from, and the press, keys, typed values and reset that move the handle. |
PlotHandleOptions | interface | The options of createPlotHandleController: the value, held or controlled, the axes it moves along, how to measure the plot, and the callbacks. |
PlotHandleSnapshot | interface | What a view draws a handle from. |
PlotPoint | interface | A point on the plot, in the axes' units. |
curvePath | function | An SVG path drawing y = fn(x) across the whole x axis, in a 1 × 1 box with y going up. |
tracePath | function | An SVG path through values spread evenly across the whole x axis, in the same 1 × 1 box with y going up: a spectrum, a level history, anything that arrives as a list. |
axisTicks | function | Round, evenly-spread tick values for axis: by power of ten when it is logarithmic. |
DEFAULT_TICK_COUNT | const | How many ticks an axis gets unless asked for another number. |
formatTick | function | A tick as short text: 1000 as "1k", 0.5 as "0.5", -12 as "-12". |
Usage
A plot draws curves, such as an equalizer's response, and traces, such as a spectrum, on two axes. A PlotAxis is a range and a scale, and every function here places values on it:
import { LINEAR_SCALE, LOGARITHMIC_SCALE } from "@audio-ui/core";
import { axisTicks, curvePath, formatTick, positionOn } from "@audio-ui/core/plot";
const frequency = { min: 20, max: 20000, scale: LOGARITHMIC_SCALE };
const gain = { min: -24, max: 24, scale: LINEAR_SCALE };
positionOn(frequency, 632.5); // 0.5: the middle of a log axis
axisTicks(frequency); // [100, 1000, 10000]: by powers of ten on a log axis
formatTick(1000); // "1k"
const d = curvePath((hz) => eq(hz), frequency, gain, 256); // an SVG path in a 1 by 1 boxcurvePath(fn, x, y, samples) samples a function across the x axis into an SVG path, adding points where the curve bends tighter than samples shows, such as a knee, and tracePath(values, y) draws values spread evenly across it, both in a 1 by 1 box with y going up, so one viewBox and a transform fit them to any size. fillTo closes a path down to a level, to fill under it. valueOn is the inverse of positionOn.
Handles
createPlotHandleController drives a handle on the plot, such as an equalizer band's, and follows the contract every controller shares. Its options are axis ("both" by default, or one axis), defaultValue, disabled, the measure(fresh) function that returns the plot's box in the viewport, and the change and commit callbacks. press(event, element) follows the drag, keyDown(event) moves the handle by a step, typeAt(along, position, event) sets it on one axis from a typed value, and reset(event) returns it to its default.
The Plot draws these in React.