Documentation / @ripl/charts / ChordChart

Class: ChordChart

Defined in: charts/src/charts/chord.ts:289

Chord diagram visualizing inter-relationships in a square matrix.

Outer arcs represent groups (labels) with angular extent proportional to their total flow. Inner ribbons connect pairs of groups with width proportional to the flow value. Supports legend, tooltips, and sequential animation (arcs first, then ribbons).

Extends

• Chart<ChordChartOptions, ChordChartEventMap>

Constructors

Constructor

new ChordChart(target, options): ChordChart

Defined in: charts/src/charts/chord.ts:295

Parameters

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

Returns

ChordChart

Overrides

Chart.constructor

Properties

Property	Modifier	Type	Default value	Description	Inherited from	Defined in
animationOptions	protected	ChartAnimationOptions	undefined	-	Chart.animationOptions	charts/src/core/chart.ts:195
autoRender	protected	boolean	undefined	-	Chart.autoRender	charts/src/core/chart.ts:194
colorGenerator	protected	Generator<string>	undefined	-	Chart.colorGenerator	charts/src/core/chart.ts:208
legend?	protected	Legend	undefined	-	Chart.legend	charts/src/core/chart.ts:198
options	protected	ChordChartOptions	undefined	-	Chart.options	charts/src/core/chart.ts:202
parent?	public	EventBus<ChordChartEventMap>	undefined	The parent event bus that emitted events bubble up to, if any.	Chart.parent	core/src/core/event-bus.ts:107
renderer	readonly	Renderer	undefined	The renderer driving the chart's animation loop. Exposed for inspection and tooling (e.g. devtools binding).	Chart.renderer	charts/src/core/chart.ts:193
scene	readonly	Scene	undefined	The scene the chart renders into. Exposed for inspection and tooling (e.g. devtools binding).	Chart.scene	charts/src/core/chart.ts:191
theme	protected	Theme	undefined	The resolved theme (palette + furniture colors) this chart renders with.	Chart.theme	charts/src/core/chart.ts:204
title?	protected	ChartTitle	undefined	-	Chart.title	charts/src/core/chart.ts:197
titleOptions?	protected	ChartTitleOptions	undefined	-	Chart.titleOptions	charts/src/core/chart.ts:196
tooltipTrigger	protected	ChartTooltipTrigger	'item'	The resolved tooltip trigger mode ('item' per-mark, 'axis' shared), kept in sync by Chart.syncTooltip.	Chart.tooltipTrigger	charts/src/core/chart.ts:207
defaultKey	readonly	typeof defaultKey	undefined	The key under which resources are retained when no explicit key is provided.	Chart.defaultKey	core/src/core/disposer.ts:11

Accessors

$events

Get Signature

get $events(): keyof TEventMap[]

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

The event types this bus can emit. The base returns an empty list; subclasses override it to declare their emittable events (type-checked against their EventMap), so tooling such as the devtools can enumerate them, including events added by custom subclasses.

Returns

keyof TEventMap[]

Inherited from

Chart.$events

---

context

Get Signature

get context(): Context

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

The rendering context the chart's scene draws into.

Returns

Context

Inherited from

Chart.context

Methods

createLayout()

protected createLayout(): ChartLayout

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

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:647

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:185

Emits an event, invoking all matching handlers and bubbling to the parent if applicable. Handlers for the event's own type run first, then EVENT_WILDCARD subscriptions.

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<ChordChartEventMap[TEvent]>

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

Emits an event, invoking all matching handlers and bubbling to the parent if applicable. Handlers for the event's own type run first, then EVENT_WILDCARD subscriptions.

Type Parameters

Type Parameter
TEvent extends keyof ChordChartEventMap

Parameters

Parameter	Type
type	TEvent
data	ChordChartEventMap[TEvent]

Returns

Event<ChordChartEventMap[TEvent]>

Inherited from

Chart.emit

---

export()

export(): ContextExport

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

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

Returns

ContextExport

Inherited from

Chart.export

---

filterActive()

protected filterActive<T>(items, getId?): T[]

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

Filters series or segments down to the ones whose legend item is active. The id defaults to each item's id property; pass an accessor for keyed data items.

Type Parameters

Type Parameter
T

Parameters

Parameter	Type
items	T[]
getId	(item) => string

Returns

T[]

Inherited from

Chart.filterActive

---

getAnimationDuration()

protected getAnimationDuration(referenceDuration?): number

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

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:520

Returns

ChartArea

Inherited from

Chart.getChartArea

---

getPadding()

protected getPadding(): ChartPadding

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

Returns

ChartPadding

Inherited from

Chart.getPadding

---

getSeriesColor()

protected getSeriesColor(seriesId): string

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

Parameters

Parameter	Type
seriesId	string

Returns

string

Inherited from

Chart.getSeriesColor

---

has()

has(type): boolean

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

Returns whether there are any listeners registered for the given event type. Wildcard subscriptions (EVENT_WILDCARD) are not listeners for any concrete type, so a bus observed only through the wildcard still reports false here.

Parameters

Parameter	Type
type	keyof ChordChartEventMap

Returns

boolean

Inherited from

Chart.has

---

highlightSeries()

protected highlightSeries(id): void

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

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 remembered on the element (via a Symbol slot, like applyHoverHighlight), tracking the target a render stashed on .data where there is one, so hidden elements stay hidden, an element caught mid-fade-in still restores to full, 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:243

Returns

void

Inherited from

Chart.init

---

isItemActive()

protected isItemActive(id): boolean

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

Whether the series or segment behind a legend item id is currently shown. Legend clicks toggle this via Chart.setItemActive; charts read it when building legend items and filtering their rendered series.

Parameters

Parameter	Type
id	string

Returns

boolean

Inherited from

Chart.isItemActive

---

off()

off<TEvent>(type, handler): void

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

Removes a previously registered handler for the given event type.

Type Parameters

Type Parameter
TEvent extends keyof ChordChartEventMap

Parameters

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

Returns

void

Inherited from

Chart.off

---

on()

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

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

Subscribes a handler to the given event type and returns a disposable for cleanup. Pass EVENT_WILDCARD to receive every event emitted on the bus regardless of type.

Type Parameters

Type Parameter
TEvent extends keyof ChordChartEventMap

Parameters

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

Returns

Disposable

Inherited from

Chart.on

---

once()

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

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

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

Type Parameters

Type Parameter
TEvent extends keyof ChordChartEventMap

Parameters

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

Returns

Disposable

Inherited from

Chart.once

---

registerHighlightGroups()

protected registerHighlightGroups(groups, resolveId?): void

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

Registers the groups that highlightSeries dims when a legend entry is hovered. Charts call this each render. By default a group belongs to the legend item whose id equals its group.id (one-to-one). Pass resolveId when a group belongs to a different legend item, or to several, e.g. a cluster legend (many node groups per legend item) or a connector that is incident to two legend items (return an array of owner ids). Replaces any previous set.

Parameters

Parameter	Type	Description
groups	Group<ElementEventMap>[]	The element groups eligible for dimming.
resolveId	(group) => string | string[]	Maps a group to the legend item id(s) it belongs to. Defaults to group.id.

Returns

void

Inherited from

Chart.registerHighlightGroups

---

render()

render(): Promise<void>

Defined in: charts/src/charts/chord.ts:307

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.

Returns

Promise<void>

Overrides

Chart.render

---

reserveLegend()

protected reserveLegend(layout, items, input?): void

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

Reserves a band for the legend (when visible and given items) at its configured position and renders it into that band, reconciling against the previous render.

Parameters

Parameter	Type
layout	ChartLayout
items	LegendItem[]
input?	ChartLegendInput

Returns

void

Inherited from

Chart.reserveLegend

---

reserveTitle()

protected reserveTitle(layout): void

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

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/chart.ts:323

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

Inherited from

Chart.resolveAnimation

---

resolveSeriesColors()

protected resolveSeriesColors(series): void

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

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

---

setItemActive()

protected setItemActive(id, active): void

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

Shows or hides the series/segment behind a legend item and re-renders, so the existing enter/exit joins animate it out of or back into the chart.

Parameters

Parameter	Type
id	string
active	boolean

Returns

void

Inherited from

Chart.setItemActive

---

syncTooltip()

protected syncTooltip(tooltip, input?, placement?): Tooltip | undefined

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

Reconciles a hover tooltip against the chart's current tooltip option so it can be reconfigured (or toggled) at runtime. Call once per render with the previous instance and keep the returned one: the tooltip is created when it should be visible and none exists, destroyed (returning undefined) when hidden, and restyled in place otherwise.

Parameters

Parameter	Type	Description
tooltip	Tooltip | undefined	The chart's current tooltip instance, if any.
input?	ChartTooltipInput	The chart's raw tooltip option.
placement?	TooltipPlacement	Where the tooltip box sits relative to its anchor (see Tooltip).

Returns

Tooltip | undefined

The tooltip to use for this render, or undefined when tooltips are disabled.

Inherited from

Chart.syncTooltip

---

update()

update(options): void

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

Merges partial options into the current options and re-renders if autoRender is enabled.

The merge is a shallow, top-level merge: passing a key replaces that option wholesale (it is then re-normalized against the chart defaults), so e.g. update({ axis: { y: { ticks: 5 } } }) replaces the whole axis option rather than deep-merging into the previous one. Furniture options (axis, grid, tooltip, crosshair, legend, title) are re-applied to the live components on the next render, so they can be reconfigured at runtime without recreating the chart.

Passing theme re-resolves the chart theme: the series palette generator is re-seeded and generated series colors are re-assigned from the new palette on the next render (explicit per-series colors are kept), and furniture colors follow the new theme automatically.

Parameters

Parameter	Type
options	Partial<TOptions>

Returns

void

Inherited from

Chart.update