Documentation / @ripl/charts / CartesianChart

Abstract Class: CartesianChart<TOptions, TData, TEventMap>

Defined in: charts/src/core/cartesian.ts:160

Base class providing shared cartesian component lifecycle and layout.

Extends

• Chart<TOptions, TEventMap>

Extended by

• AreaChart
• BarChart
• BoxPlotChart
• HistogramChart
• LineChart
• ScatterChart

Type Parameters

Type Parameter	Default type
TOptions extends CartesianChartOptions<TData>	-
TData	unknown
TEventMap extends EventMap	EventMap

Constructors

Constructor

new CartesianChart<TOptions, TData, TEventMap>(target, options?): CartesianChart<TOptions, TData, TEventMap>

Defined in: charts/src/core/chart.ts:147

Parameters

Parameter	Type
target	string | Context<Element, Record<string, unknown>> | HTMLElement
options?	TOptions

Returns

CartesianChart<TOptions, TData, TEventMap>

Inherited from

Chart.constructor

Properties

Property	Modifier	Type	Description	Inherited from	Defined in
animationOptions	protected	ChartAnimationOptions	-	Chart.animationOptions	charts/src/core/chart.ts:135
autoRender	protected	boolean	-	Chart.autoRender	charts/src/core/chart.ts:134
colorGenerator	protected	Generator<string, string, any>	-	Chart.colorGenerator	charts/src/core/chart.ts:143
crosshair?	protected	Crosshair	-	-	charts/src/core/cartesian.ts:170
grid?	protected	Grid	-	-	charts/src/core/cartesian.ts:169
legend?	protected	Legend	-	Chart.legend	charts/src/core/chart.ts:138
options	protected	TOptions	-	Chart.options	charts/src/core/chart.ts:142
parent?	public	EventBus<TEventMap>	The parent event bus that emitted events bubble up to, if any.	Chart.parent	core/src/core/event-bus.ts:89
renderer	protected	Renderer	-	Chart.renderer	charts/src/core/chart.ts:133
scene	protected	Scene	-	Chart.scene	charts/src/core/chart.ts:132
title?	protected	ChartTitle	-	Chart.title	charts/src/core/chart.ts:137
titleOptions?	protected	ChartTitleOptions	-	Chart.titleOptions	charts/src/core/chart.ts:136
tooltip?	protected	Tooltip	-	-	charts/src/core/cartesian.ts:168
xAxis	protected	ChartXAxis	-	-	charts/src/core/cartesian.ts:166
yAxis	protected	ChartYAxis	-	-	charts/src/core/cartesian.ts:167
defaultKey	readonly	typeof defaultKey	The key under which resources are retained when no explicit key is provided.	Chart.defaultKey	core/src/core/disposer.ts:11

Accessors

navigator

Get Signature

get navigator(): DOMNavigator | undefined

Defined in: charts/src/core/cartesian.ts:192

The pan/zoom/brush controller for this chart, or undefined when the navigator option is off. Use it for imperative framing (centerOn, fitBounds, reset) and to subscribe to brush/brushend for brush-and-link.

Returns

DOMNavigator | undefined

Methods

addPlotContent()

protected addPlotContent(elements): void

Defined in: charts/src/core/cartesian.ts:446

Adds plotted marks to a persistent, plot-clipped container instead of straight to the scene, so that panning/zooming can't smear marks over the axes, title or legend. Subclasses call this in place of this.scene.add(...) for their data marks (bars, bubbles, lines, …). The container sits just above the grid (z-index 1) and below the axes/title/legend, and its clip only bites while a navigator is active — see clipPlot — so non-navigator rendering is byte-for-byte unchanged.

Parameters

Parameter	Type
elements	OneOrMore<Element<Partial<BaseState>, ElementEventMap>>

Returns

void

---

applyView()

protected applyView(scale, axis): Scale<number>

Defined in: charts/src/core/cartesian.ts:380

Rescales a continuous axis scale to the window currently visible under the navigator's view transform, keeping the same pixel range. Returns the scale unchanged when no navigator is active or the view is at the identity. Subclasses pass their final x/y scales through this so pan/zoom rescales the axis domains (and repositions geometry) without a data rebuild.

Parameters

Parameter	Type
scale	Scale<number>
axis	"x" | "y"

Returns

Scale<number>

---

applyViewToScale()

protected applyViewToScale<TScale>(scale, axis): TScale

Defined in: charts/src/core/cartesian.ts:405

Transforms a scale's pixel output by the current view (k·pos + t) instead of rescaling its domain — for categorical axes (point/band scales) where domain rescaling is meaningless, so the category positions pan and zoom in lock-step with the continuous axis. Returns the scale unchanged when there is no navigator or the view is at rest. Band/point pixel spans (bandwidth/step) scale with the zoom so bars widen as you zoom in.

Type Parameters

Type Parameter
TScale extends Scale<any, number>

Parameters

Parameter	Type
scale	TScale
axis	"x" | "y"

Returns

TScale

---

clipPlot()

protected clipPlot(area): void

Defined in: charts/src/core/cartesian.ts:484

Points the plot-content clip at the current plot rectangle and enables it only while a navigator is active. Subclasses call this once per render after they know their plot area. With no navigator the clip stays inert, preserving the exact un-clipped rendering.

Parameters

Parameter	Type
area	ChartArea

Returns

void

---

createLayout()

protected createLayout(): ChartLayout

Defined in: charts/src/core/chart.ts:208

Creates a fresh layout for the current canvas size and padding.

Returns

ChartLayout

Inherited from

Chart.createLayout

---

destroy()

destroy(): void

Defined in: charts/src/core/chart.ts:399

Destroys the chart, its scene, context, and cleans up all event subscriptions.

Returns

void

Inherited from

Chart.destroy

---

dispose()

protected dispose(key?): void

Defined in: core/src/core/disposer.ts:25

Disposes all resources under the given key, or all resources if no key is provided.

Parameters

Parameter	Type
key?	PropertyKey

Returns

void

Inherited from

Chart.dispose

---

emit()

Call Signature

emit<TEvent>(event): TEvent

Defined in: core/src/core/event-bus.ts:137

Emits an event, invoking all matching handlers and bubbling to the parent if applicable.

Type Parameters

Type Parameter	Default type
TEvent extends Event<undefined>	Event<undefined>

Parameters

Parameter	Type
event	TEvent

Returns

TEvent

Inherited from

Chart.emit

Call Signature

emit<TEvent>(type, data): Event<TEventMap[TEvent]>

Defined in: core/src/core/event-bus.ts:138

Emits an event, invoking all matching handlers and bubbling to the parent if applicable.

Type Parameters

Type Parameter
TEvent extends string | number | symbol

Parameters

Parameter	Type
type	TEvent
data	TEventMap[TEvent]

Returns

Event<TEventMap[TEvent]>

Inherited from

Chart.emit

---

export()

export(): ContextExport

Defined in: charts/src/core/chart.ts:394

Exports a snapshot of the chart's rendered context (image, url, or string). See Context.export.

Returns

ContextExport

Inherited from

Chart.export

---

getAnimationDuration()

protected getAnimationDuration(referenceDuration?): number

Defined in: charts/src/core/chart.ts:198

Parameters

Parameter	Type	Default value
referenceDuration	number	1000

Returns

number

Inherited from

Chart.getAnimationDuration

---

getChartArea()

protected getChartArea(): ChartArea

Defined in: charts/src/core/chart.ts:309

Returns

ChartArea

Inherited from

Chart.getChartArea

---

getPadding()

protected getPadding(): ChartPadding

Defined in: charts/src/core/chart.ts:299

Returns

ChartPadding

Inherited from

Chart.getPadding

---

getSeriesColor()

protected getSeriesColor(seriesId): string

Defined in: charts/src/core/chart.ts:336

Parameters

Parameter	Type
seriesId	string

Returns

string

Inherited from

Chart.getSeriesColor

---

has()

has(type): boolean

Defined in: core/src/core/event-bus.ts:94

Returns whether there are any listeners registered for the given event type.

Parameters

Parameter	Type
type	keyof TEventMap

Returns

boolean

Inherited from

Chart.has

---

highlightSeries()

protected highlightSeries(id): void

Defined in: charts/src/core/chart.ts:360

Highlights a single series/segment by id (dimming the others), or restores all when null. Wired to legend hover via reserveLegend. No-ops for charts that never registered highlight groups.

Dims the leaf elements of each group rather than the group itself: a group's opacity does not cascade multiplicatively, and the leaves carry no explicit opacity (so a group-level tween is a no-op — element.interpolate skips nil current values). Each leaf's rest opacity is captured once on the element (via a Symbol slot, like applyHoverHighlight), so hidden elements stay hidden and restoring returns to the true value.

Parameters

Parameter	Type
id	string | null

Returns

void

Inherited from

Chart.highlightSeries

---

init()

protected init(): void

Defined in: charts/src/core/chart.ts:166

Returns

void

Inherited from

Chart.init

---

off()

off<TEvent>(type, handler): void

Defined in: core/src/core/event-bus.ts:112

Removes a previously registered handler for the given event type.

Type Parameters

Type Parameter
TEvent extends string | number | symbol

Parameters

Parameter	Type
type	TEvent
handler	EventHandler<TEventMap[TEvent]>

Returns

void

Inherited from

Chart.off

---

on()

on<TEvent>(type, handler, options?): Disposable

Defined in: core/src/core/event-bus.ts:99

Subscribes a handler to the given event type and returns a disposable for cleanup.

Type Parameters

Type Parameter
TEvent extends string | number | symbol

Parameters

Parameter	Type
type	TEvent
handler	EventHandler<TEventMap[TEvent]>
options?	EventSubscriptionOptions

Returns

Disposable

Inherited from

Chart.on

---

once()

once<TEvent>(type, handler, options?): Disposable

Defined in: core/src/core/event-bus.ts:127

Subscribes a handler that is automatically removed after it fires once.

Type Parameters

Type Parameter
TEvent extends string | number | symbol

Parameters

Parameter	Type
type	TEvent
handler	EventHandler<TEventMap[TEvent]>
options?	EventSubscriptionOptions

Returns

Disposable

Inherited from

Chart.once

---

pointScale()

protected pointScale(keys, left, right): Scale<string>

Defined in: charts/src/core/cartesian.ts:540

Builds an evenly-spaced point scale mapping category keys to x positions across [left, right]. Shared by line and area charts.

Parameters

Parameter	Type
keys	string[]
left	number
right	number

Returns

Scale<string>

---

prepareAxes()

protected prepareAxes(): void

Defined in: charts/src/core/cartesian.ts:515

Applies the chart's resolved animation to both axes ahead of rendering.

Returns

void

---

registerHighlightGroups()

protected registerHighlightGroups(groups): void

Defined in: charts/src/core/chart.ts:345

Registers the top-level series/segment groups that map one-to-one to legend items (by matching group.id to the legend item id). Charts call this each render so highlightSeries can dim the other series when a legend entry is hovered. Replaces any previously registered set.

Parameters

Parameter	Type
groups	Group<ElementEventMap>[]

Returns

void

Inherited from

Chart.registerHighlightGroups

---

render()

render(callback?): Promise<void>

Defined in: charts/src/core/chart.ts:288

Runs a render pass, invoking callback to draw into the scene and marking the chart as rendered. Concrete charts override this and delegate to super.render(async () => { ... }); any error thrown by the callback is caught and the context cleared, so a failed render never leaves a partially-drawn chart.

Parameters

Parameter	Type
callback?	(scene, renderer) => Promise<any>

Returns

Promise<void>

Inherited from

Chart.render

---

renderGrid()

protected renderGrid(xTicks, yTicks, area): void

Defined in: charts/src/core/cartesian.ts:527

Renders the grid within the given plot area at the supplied tick positions.

Parameters

Parameter	Type
xTicks	number[]
yTicks	number[]
area	ChartArea

Returns

void

---

reserveLegend()

protected reserveLegend(layout, items): void

Defined in: charts/src/core/cartesian.ts:522

Reserves and renders the legend using the chart's legend option.

Parameters

Parameter	Type
layout	ChartLayout
items	LegendItem[]

Returns

void

Overrides

Chart.reserveLegend

---

reserveTitle()

protected reserveTitle(layout): void

Defined in: charts/src/core/chart.ts:218

Reserves a band for the chart title (if configured) and renders it. Returns the remaining area unchanged when there is no title. Call this first in a chart's layout pass so the title sits outermost.

Parameters

Parameter	Type
layout	ChartLayout

Returns

void

Inherited from

Chart.reserveTitle

---

resolveAnimation()

protected resolveAnimation(referenceDuration?): ResolvedAnimation

Defined in: charts/src/core/cartesian.ts:506

Resolves the chart's animation options for a given reference duration (duration + easing + enabled).

Parameters

Parameter	Type	Default value
referenceDuration	number	ANIMATION_REFERENCE.update

Returns

ResolvedAnimation

Overrides

Chart.resolveAnimation

---

resolveSeriesColors()

protected resolveSeriesColors(series): void

Defined in: charts/src/core/chart.ts:321

Parameters

Parameter	Type
series	object[]

Returns

void

Inherited from

Chart.resolveSeriesColors

---

retain()

protected retain(value, key?): void

Defined in: core/src/core/disposer.ts:14

Registers a disposable resource under an optional key for later cleanup.

Parameters

Parameter	Type	Default value
value	Disposable	undefined
key	PropertyKey	Disposer.defaultKey

Returns

void

Inherited from

Chart.retain

---

setupCartesian()

protected setupCartesian(setup?): void

Defined in: charts/src/core/cartesian.ts:218

Builds the cartesian components from the chart options. Call this from a subclass constructor (after super(...)) and before init().

Parameters

Parameter	Type
setup	CartesianSetup

Returns

void

---

setupCrosshair()

protected setupCrosshair(area): void

Defined in: charts/src/core/cartesian.ts:532

Sets up the crosshair to track within the given plot area.

Parameters

Parameter	Type
area	ChartArea

Returns

void

---

update()

update(options): void

Defined in: charts/src/core/cartesian.ts:201

Merges options and re-renders (see Chart.update), additionally creating or destroying the navigator when the navigator option is toggled. The controller is otherwise a construction-time concern, so reconciling here keeps chart.update({ navigator }) working at runtime.

Parameters

Parameter	Type
options	Partial<TOptions>

Returns

void

Overrides

Chart.update