Editable chart annotations

Read as Markdown

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.

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 combines all four controls with a trading-time price chart.

API details from source

RangeNavigator

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

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

Related API: RangeNavigator, RangeNavigatorProps, JSX.

Parameters

• props — Controlled range inputs and callbacks; see RangeNavigatorProps.

Returns

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

See also

EditableReferenceBand for a directional plot interval.

View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:561

EditableReferenceLine

Renders one controlled numeric-domain reference line.

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

Related API: EditableReferenceLine, EditableReferenceLineProps, JSX.

Parameters

• props — Controlled line inputs and callbacks; see EditableReferenceLineProps.

Returns

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

See also

EditableReferenceBand for an editable interval.

View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:679

EditableReferenceBand

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

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

Related API: EditableReferenceBand, EditableReferenceBandProps, JSX.

Parameters

• props — Controlled band inputs and callbacks; see EditableReferenceBandProps.

Returns

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

See also

RangeNavigator for an overview-strip interval.

View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:786

EditableTrendLine

Renders two controlled anchors as an editable trend line.

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

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

Related API: EditableTrendLine, EditableTrendLineProps, JSX.

Parameters

• props — Controlled anchor inputs and callbacks; see EditableTrendLineProps.

Returns

Line geometry and selected endpoint handles.

See also

ChartAnchor for the controlled anchor shape.

View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:986

ChartAnchor

One numeric x/y domain anchor for EditableTrendLine.

interface ChartAnchor

Related API: ChartAnchor.

View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:25

Properties and methods

x

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

y

readonly y: number

Y-scale numeric domain value.

View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:29

RangeNavigatorProps

Controlled inputs and callbacks for RangeNavigator.

interface RangeNavigatorProps

Related API: RangeNavigatorProps.

View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:62

Properties and methods

scale

readonly scale: ScaleId

Related API: ScaleId.

ID of an ancestor invertible numeric continuous scale.

View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:64

values

readonly values: SignalValue<Pair>

Related API: SignalValue.

Controlled numeric interval in the scale domain.

View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:66

span

readonly span: SignalValue<Pair>

Related API: SignalValue.

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

View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:68

minimumSpan (optional)

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

onChange

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

onCommit (optional)

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

onCancel (optional)

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

style (optional)

readonly style?: StyleInput<RangeNavigatorStyle> | undefined

Related API: RangeNavigatorStyle.

Optional annotation and handle paint inputs.

View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:78

RangeNavigatorStyle

EditableChartStyle accepted by RangeNavigator.

interface RangeNavigatorStyle extends EditableChartStyle

Related API: RangeNavigatorStyle.

View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:51

Properties and methods

fill (optional)

readonly fill?: string | undefined

Fill for navigator and reference-band interiors.

View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:34

stroke (optional)

readonly stroke?: string | undefined

Stroke color for visible annotation geometry.

View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:36

strokeWidth (optional)

readonly strokeWidth?: number | undefined

Positive width of visible strokes.

View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:38

opacity (optional)

readonly opacity?: number | undefined

Related API: opacity.

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

View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:40

handleFill (optional)

readonly handleFill?: string | undefined

Fill color for visible drag handles.

View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:42

handleStroke (optional)

readonly handleStroke?: string | undefined

Stroke color for visible drag handles.

View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:44

handleSize (optional)

readonly handleSize?: number | undefined

Positive square size of the painted handle.

View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:46

hitSize (optional)

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

EditableReferenceLineProps

Controlled inputs and callbacks for EditableReferenceLine.

interface EditableReferenceLineProps

Related API: EditableReferenceLineProps.

View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:81

Properties and methods

scale

readonly scale: ScaleId

Related API: ScaleId.

ID of an ancestor invertible numeric continuous scale.

View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:83

direction

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

value

readonly value: SignalValue<number>

Related API: SignalValue.

Controlled numeric value in the scale domain.

View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:87

span

readonly span: SignalValue<Pair>

Related API: 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

selected (optional)

readonly selected?: SignalValue<boolean> | undefined

Related API: SignalValue.

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

View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:91

keyboardStep

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

onSelect (optional)

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

onChange

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

onCommit (optional)

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

onCancel (optional)

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

style (optional)

readonly style?: StyleInput<EditableReferenceLineStyle> | undefined

Related API: EditableReferenceLineStyle.

Optional line and handle paint inputs.

View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:103

EditableReferenceLineStyle

EditableChartStyle accepted by EditableReferenceLine.

interface EditableReferenceLineStyle extends EditableChartStyle

Related API: EditableReferenceLineStyle.

View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:53

Properties and methods

fill (optional)

readonly fill?: string | undefined

Fill for navigator and reference-band interiors.

View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:34

stroke (optional)

readonly stroke?: string | undefined

Stroke color for visible annotation geometry.

View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:36

strokeWidth (optional)

readonly strokeWidth?: number | undefined

Positive width of visible strokes.

View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:38

opacity (optional)

readonly opacity?: number | undefined

Related API: opacity.

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

View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:40

handleFill (optional)

readonly handleFill?: string | undefined

Fill color for visible drag handles.

View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:42

handleStroke (optional)

readonly handleStroke?: string | undefined

Stroke color for visible drag handles.

View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:44

handleSize (optional)

readonly handleSize?: number | undefined

Positive square size of the painted handle.

View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:46

hitSize (optional)

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

EditableReferenceBandProps

Controlled inputs and callbacks for EditableReferenceBand.

interface EditableReferenceBandProps

Related API: EditableReferenceBandProps.

View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:106

Properties and methods

scale

readonly scale: ScaleId

Related API: ScaleId.

ID of an ancestor invertible numeric continuous scale.

View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:108

direction

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

values

readonly values: SignalValue<Pair>

Related API: SignalValue.

Controlled numeric interval in the scale domain.

View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:112

span

readonly span: SignalValue<Pair>

Related API: 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

selected (optional)

readonly selected?: SignalValue<boolean> | undefined

Related API: SignalValue.

Whether resize handles are drawn; defaults to true.

View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:116

keyboardStep

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

minimumSpan (optional)

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

onSelect (optional)

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

onChange

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

onCommit (optional)

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

onCancel (optional)

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

style (optional)

readonly style?: StyleInput<EditableReferenceBandStyle> | undefined

Related API: EditableReferenceBandStyle.

Optional band and handle paint inputs.

View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:130

EditableReferenceBandStyle

EditableChartStyle accepted by EditableReferenceBand.

interface EditableReferenceBandStyle extends EditableChartStyle

Related API: EditableReferenceBandStyle.

View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:55

Properties and methods

fill (optional)

readonly fill?: string | undefined

Fill for navigator and reference-band interiors.

View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:34

stroke (optional)

readonly stroke?: string | undefined

Stroke color for visible annotation geometry.

View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:36

strokeWidth (optional)

readonly strokeWidth?: number | undefined

Positive width of visible strokes.

View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:38

opacity (optional)

readonly opacity?: number | undefined

Related API: opacity.

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

View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:40

handleFill (optional)

readonly handleFill?: string | undefined

Fill color for visible drag handles.

View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:42

handleStroke (optional)

readonly handleStroke?: string | undefined

Stroke color for visible drag handles.

View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:44

handleSize (optional)

readonly handleSize?: number | undefined

Positive square size of the painted handle.

View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:46

hitSize (optional)

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

EditableTrendLineProps

Controlled inputs and callbacks for EditableTrendLine.

interface EditableTrendLineProps

Related API: EditableTrendLineProps.

View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:133

Properties and methods

xScale

readonly xScale: ScaleId

Related API: ScaleId.

ID of an ancestor numeric or TradingTimeScale x mapping.

View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:135

yScale

readonly yScale: ScaleId

Related API: ScaleId.

ID of an ancestor invertible numeric y mapping.

View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:137

anchors

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

Related API: SignalValue, ChartAnchor.

Controlled pair of domain anchors forming the line.

View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:139

selected (optional)

readonly selected?: SignalValue<boolean> | undefined

Related API: SignalValue.

Whether endpoint handles are drawn; defaults to true.

View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:141

keyboardStep

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

onSelect (optional)

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

onChange

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

Related API: ChartAnchor.

Receives each synchronous controlled drag or keyboard anchor pair.

View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:152

onCommit (optional)

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

Related API: ChartAnchor.

Receives final anchors after a completed pointer or keyboard edit.

View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:154

onCancel (optional)

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

style (optional)

readonly style?: StyleInput<EditableTrendLineStyle> | undefined

Related API: EditableTrendLineStyle.

Optional line and handle paint inputs.

View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:158

EditableTrendLineStyle

EditableChartStyle accepted by EditableTrendLine.

interface EditableTrendLineStyle extends EditableChartStyle

Related API: EditableTrendLineStyle.

View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:57

Properties and methods

fill (optional)

readonly fill?: string | undefined

Fill for navigator and reference-band interiors.

View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:34

stroke (optional)

readonly stroke?: string | undefined

Stroke color for visible annotation geometry.

View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:36

strokeWidth (optional)

readonly strokeWidth?: number | undefined

Positive width of visible strokes.

View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:38

opacity (optional)

readonly opacity?: number | undefined

Related API: opacity.

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

View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:40

handleFill (optional)

readonly handleFill?: string | undefined

Fill color for visible drag handles.

View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:42

handleStroke (optional)

readonly handleStroke?: string | undefined

Stroke color for visible drag handles.

View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:44

handleSize (optional)

readonly handleSize?: number | undefined

Positive square size of the painted handle.

View source — packages/core/src/features/viz/lib/editable-chart-elements.tsx:46

hitSize (optional)

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

Implementation guidance for agents

Read the Data visualization companion for ownership, adaptation, failure modes, and verification. Agent start provides the version-selection workflow.

Complete minimal examples

• Controlled chart editing: Edit a range window, reference line, reference band, and trading-time trend anchors through controlled callbacks. Plain source

Documentation version

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