# Editable chart annotations

`RangeNavigator`, `EditableReferenceLine`, `EditableReferenceBand`, and
`EditableTrendLine` provide controlled Canvas interactions. Import them from
`@pibbl/core/viz`; keep the application value in a signal or other state and
feed each `onChange` result back through its matching prop.

```tsx
import { signal } from "@pibbl/core";
import { EditableReferenceLine, LinearScale } from "@pibbl/core/viz";

const level = signal(102.5);
const selected = signal(false);
const plotLeft = 20;
const plotRight = 180;

function saveLevel(nextLevel: number) {
  level.set(nextLevel);
}

function PriceReference() {
  return (
    <LinearScale id="price" domain={[95, 110]} range={[160, 20]}>
      <EditableReferenceLine
        scale="price"
        direction="horizontal"
        value={level}
        span={[plotLeft, plotRight]}
        selected={selected}
        keyboardStep={0.25}
        onSelect={() => selected.set(true)}
        onChange={level.set}
        onCommit={saveLevel}
        onCancel={() => selected.set(false)}
        style={{ stroke: "#d97706", handleSize: 8, hitSize: 24 }}
      />
    </LinearScale>
  );
}
```

`RangeNavigator`, `EditableReferenceLine`, and `EditableReferenceBand` require
an invertible numeric continuous scale: linear, UTC, log, or symlog.
`RangeNavigator` pans its interior and resizes from either edge. Reference lines
and bands accept a `direction` and an explicit perpendicular `span`. Their
interior pans; selected bands expose two resize handles. `EditableTrendLine` has
endpoint handles and a whole-line drag. Its y scale is numeric; its x scale may
also be `TradingTimeScale`. With `TradingTimeScale`, x edits snap to supplied
timestamps and whole-line drags preserve the shared observation-slot delta.

RangeNavigator values describe a bounded viewport interval and must remain
inside its numeric scale domain. Reference-line, reference-band, and numeric
trend anchors are annotations: their controlled values may extend beyond the
current visible scale domain. Continuous pointer and keyboard edits extrapolate
those annotations; only the geometry intersecting the visible range is painted.
Trading-time trend x values remain limited to supplied observations.

Changes are synchronous and controlled: pointer movement calls `onChange`, then
the application supplies the next prop. Pointer release calls `onCommit` with
the last emitted draft, including a release before a scheduled render. Escape
and pointer cancellation restore the value present at drag start through
`onChange`, then call `onCancel`. Arrow keys make one finite positive
`keyboardStep` edit and commit it. Trend arrows move x with Left/Right and y
with Up/Down. All handles use Pibbl pointer capture, so a
drag continues outside the painted mark. With `minimumSpan={0}`, RangeNavigator
uses one percent of its numeric domain span as its arrow-key step.

`style` accepts a whole-object signal and field signals for `fill`, `stroke`,
`strokeWidth`, `opacity`, `handleFill`, `handleStroke`, `handleSize`, and
`hitSize`. The first four paint the annotation. Handle colors are independently
painted at full opacity; handle size is visual and hit size is independent.
Values outside a visible range remain controlled values; only their visible
geometry is painted.

The [financial research workspace](/playground/#/examples/composition/financial-research-workspace)
combines all four controls with a trading-time price chart.

## API details from source

<span id="api-RangeNavigator"></span>

### RangeNavigator

Renders a controlled overview interval with pan and edge-resize handles.

```ts
RangeNavigator: (props: RangeNavigatorProps) => JSX.Element | null
```

Related API: [RangeNavigator](/reference/components/chart-editing/), [RangeNavigatorProps](/reference/components/chart-editing/), [JSX](/reference/overview/).

#### Parameters

- **`props`** — Controlled range inputs and callbacks; see [RangeNavigatorProps](/reference/components/chart-editing/).

#### Returns

Navigator geometry, handles, or no geometry when outside the visible scale range.

#### See also

[EditableReferenceBand](/reference/components/chart-editing/) for a directional plot interval.

[View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:561](/source/packages/core/src/features/viz/lib/editable-chart-elements-tsx/#L561)

<span id="api-EditableReferenceLine"></span>

### EditableReferenceLine

Renders one controlled numeric-domain reference line.

```ts
EditableReferenceLine: (props: EditableReferenceLineProps) => JSX.Element | null
```

Related API: [EditableReferenceLine](/reference/components/chart-editing/), [EditableReferenceLineProps](/reference/components/chart-editing/), [JSX](/reference/overview/).

#### Parameters

- **`props`** — Controlled line inputs and callbacks; see [EditableReferenceLineProps](/reference/components/chart-editing/).

#### Returns

The line and its selected handle, or no geometry when it is outside the visible range.

#### See also

[EditableReferenceBand](/reference/components/chart-editing/) for an editable interval.

[View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:679](/source/packages/core/src/features/viz/lib/editable-chart-elements-tsx/#L679)

<span id="api-EditableReferenceBand"></span>

### EditableReferenceBand

Renders a controlled numeric-domain interval with pan and edge-resize handles.

```ts
EditableReferenceBand: (props: EditableReferenceBandProps) => JSX.Element | null
```

Related API: [EditableReferenceBand](/reference/components/chart-editing/), [EditableReferenceBandProps](/reference/components/chart-editing/), [JSX](/reference/overview/).

#### Parameters

- **`props`** — Controlled band inputs and callbacks; see [EditableReferenceBandProps](/reference/components/chart-editing/).

#### Returns

Band geometry and selected handles, or no geometry when outside the visible range.

#### See also

[RangeNavigator](/reference/components/chart-editing/) for an overview-strip interval.

[View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:786](/source/packages/core/src/features/viz/lib/editable-chart-elements-tsx/#L786)

<span id="api-EditableTrendLine"></span>

### EditableTrendLine

Renders two controlled anchors as an editable trend line.

Trading-time x values snap to supplied observations during pointer and keyboard edits.

```ts
EditableTrendLine: (props: EditableTrendLineProps) => JSX.Element
```

Related API: [EditableTrendLine](/reference/components/chart-editing/), [EditableTrendLineProps](/reference/components/chart-editing/), [JSX](/reference/overview/).

#### Parameters

- **`props`** — Controlled anchor inputs and callbacks; see [EditableTrendLineProps](/reference/components/chart-editing/).

#### Returns

Line geometry and selected endpoint handles.

#### See also

[ChartAnchor](/reference/components/chart-editing/) for the controlled anchor shape.

[View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:986](/source/packages/core/src/features/viz/lib/editable-chart-elements-tsx/#L986)

<span id="api-ChartAnchor"></span>

### ChartAnchor

One numeric x/y domain anchor for EditableTrendLine.

```ts
interface ChartAnchor
```

Related API: [ChartAnchor](/reference/components/chart-editing/).

[View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:25](/source/packages/core/src/features/viz/lib/editable-chart-elements-tsx/#L25)

#### Properties and methods

<span id="api-ChartAnchor-x"></span>
<details>
<summary>x</summary>


```ts
readonly x: number
```

X-scale domain value; an exact supplied timestamp for a trading-time x scale.

[View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:27](/source/packages/core/src/features/viz/lib/editable-chart-elements-tsx/#L27)

</details>

<span id="api-ChartAnchor-y"></span>
<details>
<summary>y</summary>


```ts
readonly y: number
```

Y-scale numeric domain value.

[View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:29](/source/packages/core/src/features/viz/lib/editable-chart-elements-tsx/#L29)

</details>

<span id="api-RangeNavigatorProps"></span>

### RangeNavigatorProps

Controlled inputs and callbacks for RangeNavigator.

```ts
interface RangeNavigatorProps
```

Related API: [RangeNavigatorProps](/reference/components/chart-editing/).

[View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:62](/source/packages/core/src/features/viz/lib/editable-chart-elements-tsx/#L62)

#### Properties and methods

<span id="api-RangeNavigatorProps-scale"></span>
<details>
<summary>scale</summary>


```ts
readonly scale: ScaleId
```

Related API: [ScaleId](/reference/components/scale/).

ID of an ancestor invertible numeric continuous scale.

[View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:64](/source/packages/core/src/features/viz/lib/editable-chart-elements-tsx/#L64)

</details>

<span id="api-RangeNavigatorProps-values"></span>
<details>
<summary>values</summary>


```ts
readonly values: SignalValue<Pair>
```

Related API: [SignalValue](/reference/types/signal-inputs/#signalvalue).

Controlled numeric interval in the scale domain.

[View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:66](/source/packages/core/src/features/viz/lib/editable-chart-elements-tsx/#L66)

</details>

<span id="api-RangeNavigatorProps-span"></span>
<details>
<summary>span</summary>


```ts
readonly span: SignalValue<Pair>
```

Related API: [SignalValue](/reference/types/signal-inputs/#signalvalue).

Perpendicular local-coordinate start and end for the navigator strip.

[View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:68](/source/packages/core/src/features/viz/lib/editable-chart-elements-tsx/#L68)

</details>

<span id="api-RangeNavigatorProps-minimumSpan"></span>
<details>
<summary>minimumSpan (optional)</summary>


```ts
readonly minimumSpan?: number | undefined
```

Minimum numeric distance between interval endpoints; defaults to zero.

[View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:70](/source/packages/core/src/features/viz/lib/editable-chart-elements-tsx/#L70)

</details>

<span id="api-RangeNavigatorProps-onChange"></span>
<details>
<summary>onChange</summary>


```ts
readonly onChange: Change<Pair>
```

Receives each synchronous controlled drag or keyboard interval.

[View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:72](/source/packages/core/src/features/viz/lib/editable-chart-elements-tsx/#L72)

</details>

<span id="api-RangeNavigatorProps-onCommit"></span>
<details>
<summary>onCommit (optional)</summary>


```ts
readonly onCommit?: Change<Pair> | undefined
```

Receives the final interval after a completed pointer or keyboard edit.

[View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:74](/source/packages/core/src/features/viz/lib/editable-chart-elements-tsx/#L74)

</details>

<span id="api-RangeNavigatorProps-onCancel"></span>
<details>
<summary>onCancel (optional)</summary>


```ts
readonly onCancel?: (() => void) | undefined
```

Runs after a cancelled interaction restores its starting interval.

[View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:76](/source/packages/core/src/features/viz/lib/editable-chart-elements-tsx/#L76)

</details>

<span id="api-RangeNavigatorProps-style"></span>
<details>
<summary>style (optional)</summary>


```ts
readonly style?: StyleInput<RangeNavigatorStyle> | undefined
```

Related API: [RangeNavigatorStyle](/reference/components/chart-editing/).

Optional annotation and handle paint inputs.

[View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:78](/source/packages/core/src/features/viz/lib/editable-chart-elements-tsx/#L78)

</details>

<span id="api-RangeNavigatorStyle"></span>

### RangeNavigatorStyle

EditableChartStyle accepted by RangeNavigator.

```ts
interface RangeNavigatorStyle extends EditableChartStyle
```

Related API: [RangeNavigatorStyle](/reference/components/chart-editing/).

[View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:51](/source/packages/core/src/features/viz/lib/editable-chart-elements-tsx/#L51)

#### Properties and methods

<span id="api-RangeNavigatorStyle-fill"></span>
<details>
<summary>fill (optional)</summary>


```ts
readonly fill?: string | undefined
```

Fill for navigator and reference-band interiors.

[View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:34](/source/packages/core/src/features/viz/lib/editable-chart-elements-tsx/#L34)

</details>

<span id="api-RangeNavigatorStyle-stroke"></span>
<details>
<summary>stroke (optional)</summary>


```ts
readonly stroke?: string | undefined
```

Stroke color for visible annotation geometry.

[View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:36](/source/packages/core/src/features/viz/lib/editable-chart-elements-tsx/#L36)

</details>

<span id="api-RangeNavigatorStyle-strokeWidth"></span>
<details>
<summary>strokeWidth (optional)</summary>


```ts
readonly strokeWidth?: number | undefined
```

Positive width of visible strokes.

[View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:38](/source/packages/core/src/features/viz/lib/editable-chart-elements-tsx/#L38)

</details>

<span id="api-RangeNavigatorStyle-opacity"></span>
<details>
<summary>opacity (optional)</summary>


```ts
readonly opacity?: number | undefined
```

Related API: [opacity](/reference/types/filters/#opacity).

Annotation opacity from zero through one; handles remain fully opaque.

[View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:40](/source/packages/core/src/features/viz/lib/editable-chart-elements-tsx/#L40)

</details>

<span id="api-RangeNavigatorStyle-handleFill"></span>
<details>
<summary>handleFill (optional)</summary>


```ts
readonly handleFill?: string | undefined
```

Fill color for visible drag handles.

[View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:42](/source/packages/core/src/features/viz/lib/editable-chart-elements-tsx/#L42)

</details>

<span id="api-RangeNavigatorStyle-handleStroke"></span>
<details>
<summary>handleStroke (optional)</summary>


```ts
readonly handleStroke?: string | undefined
```

Stroke color for visible drag handles.

[View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:44](/source/packages/core/src/features/viz/lib/editable-chart-elements-tsx/#L44)

</details>

<span id="api-RangeNavigatorStyle-handleSize"></span>
<details>
<summary>handleSize (optional)</summary>


```ts
readonly handleSize?: number | undefined
```

Positive square size of the painted handle.

[View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:46](/source/packages/core/src/features/viz/lib/editable-chart-elements-tsx/#L46)

</details>

<span id="api-RangeNavigatorStyle-hitSize"></span>
<details>
<summary>hitSize (optional)</summary>


```ts
readonly hitSize?: number | undefined
```

Positive width and height of each invisible pointer hit region.

[View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:48](/source/packages/core/src/features/viz/lib/editable-chart-elements-tsx/#L48)

</details>

<span id="api-EditableReferenceLineProps"></span>

### EditableReferenceLineProps

Controlled inputs and callbacks for EditableReferenceLine.

```ts
interface EditableReferenceLineProps
```

Related API: [EditableReferenceLineProps](/reference/components/chart-editing/).

[View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:81](/source/packages/core/src/features/viz/lib/editable-chart-elements-tsx/#L81)

#### Properties and methods

<span id="api-EditableReferenceLineProps-scale"></span>
<details>
<summary>scale</summary>


```ts
readonly scale: ScaleId
```

Related API: [ScaleId](/reference/components/scale/).

ID of an ancestor invertible numeric continuous scale.

[View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:83](/source/packages/core/src/features/viz/lib/editable-chart-elements-tsx/#L83)

</details>

<span id="api-EditableReferenceLineProps-direction"></span>
<details>
<summary>direction</summary>


```ts
readonly direction: "horizontal" | "vertical"
```

Axis perpendicular to the drawn line and edited value.

[View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:85](/source/packages/core/src/features/viz/lib/editable-chart-elements-tsx/#L85)

</details>

<span id="api-EditableReferenceLineProps-value"></span>
<details>
<summary>value</summary>


```ts
readonly value: SignalValue<number>
```

Related API: [SignalValue](/reference/types/signal-inputs/#signalvalue).

Controlled numeric value in the scale domain.

[View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:87](/source/packages/core/src/features/viz/lib/editable-chart-elements-tsx/#L87)

</details>

<span id="api-EditableReferenceLineProps-span"></span>
<details>
<summary>span</summary>


```ts
readonly span: SignalValue<Pair>
```

Related API: [SignalValue](/reference/types/signal-inputs/#signalvalue).

Local-coordinate extent of the line along its non-edited axis.

[View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:89](/source/packages/core/src/features/viz/lib/editable-chart-elements-tsx/#L89)

</details>

<span id="api-EditableReferenceLineProps-selected"></span>
<details>
<summary>selected (optional)</summary>


```ts
readonly selected?: SignalValue<boolean> | undefined
```

Related API: [SignalValue](/reference/types/signal-inputs/#signalvalue).

Whether endpoint-independent handle geometry is drawn; defaults to true.

[View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:91](/source/packages/core/src/features/viz/lib/editable-chart-elements-tsx/#L91)

</details>

<span id="api-EditableReferenceLineProps-keyboardStep"></span>
<details>
<summary>keyboardStep</summary>


```ts
readonly keyboardStep: number
```

Finite positive numeric domain increment for arrow-key edits.

[View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:93](/source/packages/core/src/features/viz/lib/editable-chart-elements-tsx/#L93)

</details>

<span id="api-EditableReferenceLineProps-onSelect"></span>
<details>
<summary>onSelect (optional)</summary>


```ts
readonly onSelect?: (() => void) | undefined
```

Runs when a pointer or keyboard interaction selects the line.

[View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:95](/source/packages/core/src/features/viz/lib/editable-chart-elements-tsx/#L95)

</details>

<span id="api-EditableReferenceLineProps-onChange"></span>
<details>
<summary>onChange</summary>


```ts
readonly onChange: Change<number>
```

Receives each synchronous controlled drag or keyboard value.

[View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:97](/source/packages/core/src/features/viz/lib/editable-chart-elements-tsx/#L97)

</details>

<span id="api-EditableReferenceLineProps-onCommit"></span>
<details>
<summary>onCommit (optional)</summary>


```ts
readonly onCommit?: Change<number> | undefined
```

Receives the final value after a completed pointer or keyboard edit.

[View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:99](/source/packages/core/src/features/viz/lib/editable-chart-elements-tsx/#L99)

</details>

<span id="api-EditableReferenceLineProps-onCancel"></span>
<details>
<summary>onCancel (optional)</summary>


```ts
readonly onCancel?: (() => void) | undefined
```

Runs after a cancelled interaction restores its starting value.

[View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:101](/source/packages/core/src/features/viz/lib/editable-chart-elements-tsx/#L101)

</details>

<span id="api-EditableReferenceLineProps-style"></span>
<details>
<summary>style (optional)</summary>


```ts
readonly style?: StyleInput<EditableReferenceLineStyle> | undefined
```

Related API: [EditableReferenceLineStyle](/reference/components/chart-editing/).

Optional line and handle paint inputs.

[View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:103](/source/packages/core/src/features/viz/lib/editable-chart-elements-tsx/#L103)

</details>

<span id="api-EditableReferenceLineStyle"></span>

### EditableReferenceLineStyle

EditableChartStyle accepted by EditableReferenceLine.

```ts
interface EditableReferenceLineStyle extends EditableChartStyle
```

Related API: [EditableReferenceLineStyle](/reference/components/chart-editing/).

[View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:53](/source/packages/core/src/features/viz/lib/editable-chart-elements-tsx/#L53)

#### Properties and methods

<span id="api-EditableReferenceLineStyle-fill"></span>
<details>
<summary>fill (optional)</summary>


```ts
readonly fill?: string | undefined
```

Fill for navigator and reference-band interiors.

[View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:34](/source/packages/core/src/features/viz/lib/editable-chart-elements-tsx/#L34)

</details>

<span id="api-EditableReferenceLineStyle-stroke"></span>
<details>
<summary>stroke (optional)</summary>


```ts
readonly stroke?: string | undefined
```

Stroke color for visible annotation geometry.

[View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:36](/source/packages/core/src/features/viz/lib/editable-chart-elements-tsx/#L36)

</details>

<span id="api-EditableReferenceLineStyle-strokeWidth"></span>
<details>
<summary>strokeWidth (optional)</summary>


```ts
readonly strokeWidth?: number | undefined
```

Positive width of visible strokes.

[View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:38](/source/packages/core/src/features/viz/lib/editable-chart-elements-tsx/#L38)

</details>

<span id="api-EditableReferenceLineStyle-opacity"></span>
<details>
<summary>opacity (optional)</summary>


```ts
readonly opacity?: number | undefined
```

Related API: [opacity](/reference/types/filters/#opacity).

Annotation opacity from zero through one; handles remain fully opaque.

[View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:40](/source/packages/core/src/features/viz/lib/editable-chart-elements-tsx/#L40)

</details>

<span id="api-EditableReferenceLineStyle-handleFill"></span>
<details>
<summary>handleFill (optional)</summary>


```ts
readonly handleFill?: string | undefined
```

Fill color for visible drag handles.

[View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:42](/source/packages/core/src/features/viz/lib/editable-chart-elements-tsx/#L42)

</details>

<span id="api-EditableReferenceLineStyle-handleStroke"></span>
<details>
<summary>handleStroke (optional)</summary>


```ts
readonly handleStroke?: string | undefined
```

Stroke color for visible drag handles.

[View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:44](/source/packages/core/src/features/viz/lib/editable-chart-elements-tsx/#L44)

</details>

<span id="api-EditableReferenceLineStyle-handleSize"></span>
<details>
<summary>handleSize (optional)</summary>


```ts
readonly handleSize?: number | undefined
```

Positive square size of the painted handle.

[View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:46](/source/packages/core/src/features/viz/lib/editable-chart-elements-tsx/#L46)

</details>

<span id="api-EditableReferenceLineStyle-hitSize"></span>
<details>
<summary>hitSize (optional)</summary>


```ts
readonly hitSize?: number | undefined
```

Positive width and height of each invisible pointer hit region.

[View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:48](/source/packages/core/src/features/viz/lib/editable-chart-elements-tsx/#L48)

</details>

<span id="api-EditableReferenceBandProps"></span>

### EditableReferenceBandProps

Controlled inputs and callbacks for EditableReferenceBand.

```ts
interface EditableReferenceBandProps
```

Related API: [EditableReferenceBandProps](/reference/components/chart-editing/).

[View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:106](/source/packages/core/src/features/viz/lib/editable-chart-elements-tsx/#L106)

#### Properties and methods

<span id="api-EditableReferenceBandProps-scale"></span>
<details>
<summary>scale</summary>


```ts
readonly scale: ScaleId
```

Related API: [ScaleId](/reference/components/scale/).

ID of an ancestor invertible numeric continuous scale.

[View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:108](/source/packages/core/src/features/viz/lib/editable-chart-elements-tsx/#L108)

</details>

<span id="api-EditableReferenceBandProps-direction"></span>
<details>
<summary>direction</summary>


```ts
readonly direction: "horizontal" | "vertical"
```

Axis perpendicular to the band and edited interval.

[View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:110](/source/packages/core/src/features/viz/lib/editable-chart-elements-tsx/#L110)

</details>

<span id="api-EditableReferenceBandProps-values"></span>
<details>
<summary>values</summary>


```ts
readonly values: SignalValue<Pair>
```

Related API: [SignalValue](/reference/types/signal-inputs/#signalvalue).

Controlled numeric interval in the scale domain.

[View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:112](/source/packages/core/src/features/viz/lib/editable-chart-elements-tsx/#L112)

</details>

<span id="api-EditableReferenceBandProps-span"></span>
<details>
<summary>span</summary>


```ts
readonly span: SignalValue<Pair>
```

Related API: [SignalValue](/reference/types/signal-inputs/#signalvalue).

Local-coordinate extent of the band along its non-edited axis.

[View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:114](/source/packages/core/src/features/viz/lib/editable-chart-elements-tsx/#L114)

</details>

<span id="api-EditableReferenceBandProps-selected"></span>
<details>
<summary>selected (optional)</summary>


```ts
readonly selected?: SignalValue<boolean> | undefined
```

Related API: [SignalValue](/reference/types/signal-inputs/#signalvalue).

Whether resize handles are drawn; defaults to true.

[View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:116](/source/packages/core/src/features/viz/lib/editable-chart-elements-tsx/#L116)

</details>

<span id="api-EditableReferenceBandProps-keyboardStep"></span>
<details>
<summary>keyboardStep</summary>


```ts
readonly keyboardStep: number
```

Finite positive numeric domain increment for arrow-key panning.

[View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:118](/source/packages/core/src/features/viz/lib/editable-chart-elements-tsx/#L118)

</details>

<span id="api-EditableReferenceBandProps-minimumSpan"></span>
<details>
<summary>minimumSpan (optional)</summary>


```ts
readonly minimumSpan?: number | undefined
```

Minimum numeric distance between interval endpoints; defaults to zero.

[View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:120](/source/packages/core/src/features/viz/lib/editable-chart-elements-tsx/#L120)

</details>

<span id="api-EditableReferenceBandProps-onSelect"></span>
<details>
<summary>onSelect (optional)</summary>


```ts
readonly onSelect?: (() => void) | undefined
```

Runs when a pointer or keyboard interaction selects the band.

[View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:122](/source/packages/core/src/features/viz/lib/editable-chart-elements-tsx/#L122)

</details>

<span id="api-EditableReferenceBandProps-onChange"></span>
<details>
<summary>onChange</summary>


```ts
readonly onChange: Change<Pair>
```

Receives each synchronous controlled drag or keyboard interval.

[View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:124](/source/packages/core/src/features/viz/lib/editable-chart-elements-tsx/#L124)

</details>

<span id="api-EditableReferenceBandProps-onCommit"></span>
<details>
<summary>onCommit (optional)</summary>


```ts
readonly onCommit?: Change<Pair> | undefined
```

Receives the final interval after a completed pointer or keyboard edit.

[View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:126](/source/packages/core/src/features/viz/lib/editable-chart-elements-tsx/#L126)

</details>

<span id="api-EditableReferenceBandProps-onCancel"></span>
<details>
<summary>onCancel (optional)</summary>


```ts
readonly onCancel?: (() => void) | undefined
```

Runs after a cancelled interaction restores its starting interval.

[View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:128](/source/packages/core/src/features/viz/lib/editable-chart-elements-tsx/#L128)

</details>

<span id="api-EditableReferenceBandProps-style"></span>
<details>
<summary>style (optional)</summary>


```ts
readonly style?: StyleInput<EditableReferenceBandStyle> | undefined
```

Related API: [EditableReferenceBandStyle](/reference/components/chart-editing/).

Optional band and handle paint inputs.

[View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:130](/source/packages/core/src/features/viz/lib/editable-chart-elements-tsx/#L130)

</details>

<span id="api-EditableReferenceBandStyle"></span>

### EditableReferenceBandStyle

EditableChartStyle accepted by EditableReferenceBand.

```ts
interface EditableReferenceBandStyle extends EditableChartStyle
```

Related API: [EditableReferenceBandStyle](/reference/components/chart-editing/).

[View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:55](/source/packages/core/src/features/viz/lib/editable-chart-elements-tsx/#L55)

#### Properties and methods

<span id="api-EditableReferenceBandStyle-fill"></span>
<details>
<summary>fill (optional)</summary>


```ts
readonly fill?: string | undefined
```

Fill for navigator and reference-band interiors.

[View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:34](/source/packages/core/src/features/viz/lib/editable-chart-elements-tsx/#L34)

</details>

<span id="api-EditableReferenceBandStyle-stroke"></span>
<details>
<summary>stroke (optional)</summary>


```ts
readonly stroke?: string | undefined
```

Stroke color for visible annotation geometry.

[View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:36](/source/packages/core/src/features/viz/lib/editable-chart-elements-tsx/#L36)

</details>

<span id="api-EditableReferenceBandStyle-strokeWidth"></span>
<details>
<summary>strokeWidth (optional)</summary>


```ts
readonly strokeWidth?: number | undefined
```

Positive width of visible strokes.

[View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:38](/source/packages/core/src/features/viz/lib/editable-chart-elements-tsx/#L38)

</details>

<span id="api-EditableReferenceBandStyle-opacity"></span>
<details>
<summary>opacity (optional)</summary>


```ts
readonly opacity?: number | undefined
```

Related API: [opacity](/reference/types/filters/#opacity).

Annotation opacity from zero through one; handles remain fully opaque.

[View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:40](/source/packages/core/src/features/viz/lib/editable-chart-elements-tsx/#L40)

</details>

<span id="api-EditableReferenceBandStyle-handleFill"></span>
<details>
<summary>handleFill (optional)</summary>


```ts
readonly handleFill?: string | undefined
```

Fill color for visible drag handles.

[View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:42](/source/packages/core/src/features/viz/lib/editable-chart-elements-tsx/#L42)

</details>

<span id="api-EditableReferenceBandStyle-handleStroke"></span>
<details>
<summary>handleStroke (optional)</summary>


```ts
readonly handleStroke?: string | undefined
```

Stroke color for visible drag handles.

[View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:44](/source/packages/core/src/features/viz/lib/editable-chart-elements-tsx/#L44)

</details>

<span id="api-EditableReferenceBandStyle-handleSize"></span>
<details>
<summary>handleSize (optional)</summary>


```ts
readonly handleSize?: number | undefined
```

Positive square size of the painted handle.

[View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:46](/source/packages/core/src/features/viz/lib/editable-chart-elements-tsx/#L46)

</details>

<span id="api-EditableReferenceBandStyle-hitSize"></span>
<details>
<summary>hitSize (optional)</summary>


```ts
readonly hitSize?: number | undefined
```

Positive width and height of each invisible pointer hit region.

[View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:48](/source/packages/core/src/features/viz/lib/editable-chart-elements-tsx/#L48)

</details>

<span id="api-EditableTrendLineProps"></span>

### EditableTrendLineProps

Controlled inputs and callbacks for EditableTrendLine.

```ts
interface EditableTrendLineProps
```

Related API: [EditableTrendLineProps](/reference/components/chart-editing/).

[View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:133](/source/packages/core/src/features/viz/lib/editable-chart-elements-tsx/#L133)

#### Properties and methods

<span id="api-EditableTrendLineProps-xScale"></span>
<details>
<summary>xScale</summary>


```ts
readonly xScale: ScaleId
```

Related API: [ScaleId](/reference/components/scale/).

ID of an ancestor numeric or TradingTimeScale x mapping.

[View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:135](/source/packages/core/src/features/viz/lib/editable-chart-elements-tsx/#L135)

</details>

<span id="api-EditableTrendLineProps-yScale"></span>
<details>
<summary>yScale</summary>


```ts
readonly yScale: ScaleId
```

Related API: [ScaleId](/reference/components/scale/).

ID of an ancestor invertible numeric y mapping.

[View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:137](/source/packages/core/src/features/viz/lib/editable-chart-elements-tsx/#L137)

</details>

<span id="api-EditableTrendLineProps-anchors"></span>
<details>
<summary>anchors</summary>


```ts
readonly anchors: SignalValue<readonly [ChartAnchor, ChartAnchor]>
```

Related API: [SignalValue](/reference/types/signal-inputs/#signalvalue), [ChartAnchor](/reference/components/chart-editing/).

Controlled pair of domain anchors forming the line.

[View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:139](/source/packages/core/src/features/viz/lib/editable-chart-elements-tsx/#L139)

</details>

<span id="api-EditableTrendLineProps-selected"></span>
<details>
<summary>selected (optional)</summary>


```ts
readonly selected?: SignalValue<boolean> | undefined
```

Related API: [SignalValue](/reference/types/signal-inputs/#signalvalue).

Whether endpoint handles are drawn; defaults to true.

[View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:141](/source/packages/core/src/features/viz/lib/editable-chart-elements-tsx/#L141)

</details>

<span id="api-EditableTrendLineProps-keyboardStep"></span>
<details>
<summary>keyboardStep</summary>


```ts
readonly keyboardStep: { readonly x: number; readonly y: number; }
```

Finite positive x and y increments for arrow-key translation.

[View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:143](/source/packages/core/src/features/viz/lib/editable-chart-elements-tsx/#L143)

</details>

<span id="api-EditableTrendLineProps-onSelect"></span>
<details>
<summary>onSelect (optional)</summary>


```ts
readonly onSelect?: (() => void) | undefined
```

Runs when a pointer or keyboard interaction selects the trend line.

[View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:150](/source/packages/core/src/features/viz/lib/editable-chart-elements-tsx/#L150)

</details>

<span id="api-EditableTrendLineProps-onChange"></span>
<details>
<summary>onChange</summary>


```ts
readonly onChange: Change<readonly [ChartAnchor, ChartAnchor]>
```

Related API: [ChartAnchor](/reference/components/chart-editing/).

Receives each synchronous controlled drag or keyboard anchor pair.

[View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:152](/source/packages/core/src/features/viz/lib/editable-chart-elements-tsx/#L152)

</details>

<span id="api-EditableTrendLineProps-onCommit"></span>
<details>
<summary>onCommit (optional)</summary>


```ts
readonly onCommit?: Change<readonly [ChartAnchor, ChartAnchor]> | undefined
```

Related API: [ChartAnchor](/reference/components/chart-editing/).

Receives final anchors after a completed pointer or keyboard edit.

[View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:154](/source/packages/core/src/features/viz/lib/editable-chart-elements-tsx/#L154)

</details>

<span id="api-EditableTrendLineProps-onCancel"></span>
<details>
<summary>onCancel (optional)</summary>


```ts
readonly onCancel?: (() => void) | undefined
```

Runs after a cancelled interaction restores its starting anchors.

[View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:156](/source/packages/core/src/features/viz/lib/editable-chart-elements-tsx/#L156)

</details>

<span id="api-EditableTrendLineProps-style"></span>
<details>
<summary>style (optional)</summary>


```ts
readonly style?: StyleInput<EditableTrendLineStyle> | undefined
```

Related API: [EditableTrendLineStyle](/reference/components/chart-editing/).

Optional line and handle paint inputs.

[View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:158](/source/packages/core/src/features/viz/lib/editable-chart-elements-tsx/#L158)

</details>

<span id="api-EditableTrendLineStyle"></span>

### EditableTrendLineStyle

EditableChartStyle accepted by EditableTrendLine.

```ts
interface EditableTrendLineStyle extends EditableChartStyle
```

Related API: [EditableTrendLineStyle](/reference/components/chart-editing/).

[View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:57](/source/packages/core/src/features/viz/lib/editable-chart-elements-tsx/#L57)

#### Properties and methods

<span id="api-EditableTrendLineStyle-fill"></span>
<details>
<summary>fill (optional)</summary>


```ts
readonly fill?: string | undefined
```

Fill for navigator and reference-band interiors.

[View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:34](/source/packages/core/src/features/viz/lib/editable-chart-elements-tsx/#L34)

</details>

<span id="api-EditableTrendLineStyle-stroke"></span>
<details>
<summary>stroke (optional)</summary>


```ts
readonly stroke?: string | undefined
```

Stroke color for visible annotation geometry.

[View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:36](/source/packages/core/src/features/viz/lib/editable-chart-elements-tsx/#L36)

</details>

<span id="api-EditableTrendLineStyle-strokeWidth"></span>
<details>
<summary>strokeWidth (optional)</summary>


```ts
readonly strokeWidth?: number | undefined
```

Positive width of visible strokes.

[View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:38](/source/packages/core/src/features/viz/lib/editable-chart-elements-tsx/#L38)

</details>

<span id="api-EditableTrendLineStyle-opacity"></span>
<details>
<summary>opacity (optional)</summary>


```ts
readonly opacity?: number | undefined
```

Related API: [opacity](/reference/types/filters/#opacity).

Annotation opacity from zero through one; handles remain fully opaque.

[View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:40](/source/packages/core/src/features/viz/lib/editable-chart-elements-tsx/#L40)

</details>

<span id="api-EditableTrendLineStyle-handleFill"></span>
<details>
<summary>handleFill (optional)</summary>


```ts
readonly handleFill?: string | undefined
```

Fill color for visible drag handles.

[View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:42](/source/packages/core/src/features/viz/lib/editable-chart-elements-tsx/#L42)

</details>

<span id="api-EditableTrendLineStyle-handleStroke"></span>
<details>
<summary>handleStroke (optional)</summary>


```ts
readonly handleStroke?: string | undefined
```

Stroke color for visible drag handles.

[View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:44](/source/packages/core/src/features/viz/lib/editable-chart-elements-tsx/#L44)

</details>

<span id="api-EditableTrendLineStyle-handleSize"></span>
<details>
<summary>handleSize (optional)</summary>


```ts
readonly handleSize?: number | undefined
```

Positive square size of the painted handle.

[View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:46](/source/packages/core/src/features/viz/lib/editable-chart-elements-tsx/#L46)

</details>

<span id="api-EditableTrendLineStyle-hitSize"></span>
<details>
<summary>hitSize (optional)</summary>


```ts
readonly hitSize?: number | undefined
```

Positive width and height of each invisible pointer hit region.

[View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:48](/source/packages/core/src/features/viz/lib/editable-chart-elements-tsx/#L48)

</details>

## Implementation guidance for agents

Read the [Data visualization companion](/agents/topics/visualization/) for ownership, adaptation, failure modes, and verification. [Agent start](/agents/) provides the version-selection workflow.

## Complete minimal examples

- [Controlled chart editing](/minimal-examples/viz/chart-editing/): Edit a range window, reference line, reference band, and trading-time trend anchors through controlled callbacks. [Plain source](/minimal/viz/chart-editing.tsx)
## Documentation version

Documentation built with @pibbl/core 0.0.2, revision dd39ce2. ALPHA — NOT FOR PRODUCTION USE.