# plot

> A plot's axes, paths, ticks and handles from @audio-ui/core: values placed on linear or log axes, curves and traces as SVG paths, round tick values, and the controller of a handle dragged on the plot.

```bash
npm install @audio-ui/core
```

```ts
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:

```ts
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 box
```

`curvePath(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](/docs/core/controllers) 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.

**In React**

The [Plot](/docs/components/base/plot) draws these in React.

**In Vue, Svelte and Web**

[`<audio-ui-plot>`](/docs/elements/plot) draws these in your framework.