Documentation / @ripl/charts / HeatmapChart
Class: HeatmapChart<TData> ​
Defined in: charts/src/charts/heatmap.ts:169
Heatmap chart rendering a grid of colored cells on two categorical axes.
Cell color is interpolated between a configurable low/high color range based on each data point's value. Supports x/y axes, tooltips, and animated fade-in entry transitions with smooth color updates.
Extends ​
Chart<HeatmapChartOptions<TData>,HeatmapChartEventMap>
Type Parameters ​
| Type Parameter | Default type | Description |
|---|---|---|
TData | unknown | The type of each data item in the dataset. |
Constructors ​
Constructor ​
new HeatmapChart<
TData>(target,options):HeatmapChart<TData>
Defined in: charts/src/charts/heatmap.ts:177
Parameters ​
| Parameter | Type |
|---|---|
target | string | HTMLElement | Context<Element, Record<string, unknown>> |
options | HeatmapChartOptions<TData> |
Returns ​
HeatmapChart<TData>
Overrides ​
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 | HeatmapChartOptions | undefined | - | Chart.options | charts/src/core/chart.ts:202 |
parent? | public | EventBus<HeatmapChartEventMap> | 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 ​
context ​
Get Signature ​
get context():
Context
Defined in: charts/src/core/chart.ts:217
The rendering context the chart's scene draws into.
Returns ​
Inherited from ​
Methods ​
createLayout() ​
protectedcreateLayout():ChartLayout
Defined in: charts/src/core/chart.ts:328
Creates a fresh layout for the current canvas size and padding.
Returns ​
Inherited from ​
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 ​
dispose() ​
protecteddispose(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 ​
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 ​
Call Signature ​
emit<
TEvent>(type,data):Event<HeatmapChartEventMap[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 HeatmapChartEventMap |
Parameters ​
| Parameter | Type |
|---|---|
type | TEvent |
data | HeatmapChartEventMap[TEvent] |
Returns ​
Event<HeatmapChartEventMap[TEvent]>
Inherited from ​
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 ​
Inherited from ​
filterActive() ​
protectedfilterActive<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 ​
getAnimationDuration() ​
protectedgetAnimationDuration(referenceDuration?):number
Defined in: charts/src/core/chart.ts:318
Parameters ​
| Parameter | Type | Default value |
|---|---|---|
referenceDuration | number | 1000 |
Returns ​
number
Inherited from ​
getChartArea() ​
protectedgetChartArea():ChartArea
Defined in: charts/src/core/chart.ts:520
Returns ​
Inherited from ​
getPadding() ​
protectedgetPadding():ChartPadding
Defined in: charts/src/core/chart.ts:516
Returns ​
Inherited from ​
getSeriesColor() ​
protectedgetSeriesColor(seriesId):string
Defined in: charts/src/core/chart.ts:547
Parameters ​
| Parameter | Type |
|---|---|
seriesId | string |
Returns ​
string
Inherited from ​
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 HeatmapChartEventMap |
Returns ​
boolean
Inherited from ​
highlightSeries() ​
protectedhighlightSeries(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 ​
init() ​
protectedinit():void
Defined in: charts/src/core/chart.ts:243
Returns ​
void
Inherited from ​
isItemActive() ​
protectedisItemActive(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 ​
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 HeatmapChartEventMap |
Parameters ​
| Parameter | Type |
|---|---|
type | TEvent |
handler | EventHandler<HeatmapChartEventMap[TEvent]> |
Returns ​
void
Inherited from ​
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 HeatmapChartEventMap |
Parameters ​
| Parameter | Type |
|---|---|
type | TEvent |
handler | EventHandler<HeatmapChartEventMap[TEvent]> |
options? | EventSubscriptionOptions |
Returns ​
Inherited from ​
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 HeatmapChartEventMap |
Parameters ​
| Parameter | Type |
|---|---|
type | TEvent |
handler | EventHandler<HeatmapChartEventMap[TEvent]> |
options? | EventSubscriptionOptions |
Returns ​
Inherited from ​
registerHighlightGroups() ​
protectedregisterHighlightGroups(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 ​
render() ​
render():
Promise<void>
Defined in: charts/src/charts/heatmap.ts:199
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 ​
reserveLegend() ​
protectedreserveLegend(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 ​
reserveTitle() ​
protectedreserveTitle(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 ​
resolveAnimation() ​
protectedresolveAnimation(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 ​
Inherited from ​
resolveSeriesColors() ​
protectedresolveSeriesColors(series):void
Defined in: charts/src/core/chart.ts:532
Parameters ​
| Parameter | Type |
|---|---|
series | object[] |
Returns ​
void
Inherited from ​
retain() ​
protectedretain(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 ​
setItemActive() ​
protectedsetItemActive(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 ​
syncTooltip() ​
protectedsyncTooltip(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 ​
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