Kappa / Charts

<script setup lang="ts">
import { Chart } from "@dicehub/kappa/components/chart";
import { LineChart } from "echarts/charts";
import { GridComponent, LegendComponent, TooltipComponent } from "echarts/components";
import * as echarts from "echarts/core";
import { CanvasRenderer } from "echarts/renderers";

echarts.use([LineChart, GridComponent, LegendComponent, TooltipComponent, CanvasRenderer]);

const options = {
  tooltip: { trigger: "axis" },
  xAxis: { type: "category", data: ["Mon", "Tue", "Wed", "Thu", "Fri"] },
  yAxis: { type: "value" },
  series: [{ name: "CPU", type: "line", data: [42, 48, 46, 63, 58] }],
};
</script>

<template>
  <Chart
    :engine="echarts"
    :options="options"
    title="Workspace usage"
    aria-label="Workspace CPU usage"
    aria-description="CPU usage peaks at 63 percent on Thursday."
  />
</template>

Choose an Engine

Kappa has three chart components across two engines. Select one from the data shape and required chart type. The components do not switch engines at runtime.

Kappa component	Engine	Use	Data
`Chart`	ECharts	Bar, line, pie, scatter, heatmap, Sankey, maps, and normal dashboards.	Small and medium data sets; large-mode ECharts series where they fit.
`XYPlot`	uPlot	Dense numeric or time X/Y data, solver monitors, and live telemetry.	Aligned columns, typed arrays, and 100,000 or more points.
`TimeseriesChart`	ECharts	Polished dashboard trends with opinionated line, area, bar, legend, and tooltip defaults.	Normal dashboard ranges expressed as timestamp and value pairs.

Installation

The engines are optional peer dependencies. Install only the engine that your application imports. Import each component from its isolated path.

pnpm add echarts uplot

Chart hosts a modular ECharts instance. Register only the chart types, components, and renderer that the application uses. It supports the full ECharts catalogue, including bars, lines, pie charts, scatter plots, heatmaps, Sankey diagrams, and maps.

<script setup lang="ts">
import { Chart } from "@dicehub/kappa/components/chart";
import { LineChart } from "echarts/charts";
import { GridComponent, LegendComponent, TooltipComponent } from "echarts/components";
import * as echarts from "echarts/core";
import { CanvasRenderer } from "echarts/renderers";

echarts.use([LineChart, GridComponent, LegendComponent, TooltipComponent, CanvasRenderer]);

const options = {
  tooltip: { trigger: "axis" },
  xAxis: { type: "category", data: ["Mon", "Tue", "Wed", "Thu", "Fri"] },
  yAxis: { type: "value" },
  series: [{ name: "CPU", type: "line", data: [42, 48, 46, 63, 58] }],
};
</script>

<template>
  <Chart
    :engine="echarts"
    :options="options"
    title="Workspace usage"
    aria-label="Workspace CPU usage"
    aria-description="CPU usage peaks at 63 percent on Thursday."
  />
</template>

XYPlot

XYPlot uses uPlot for aligned numeric or time data. Keep the data in a shallowRef or outside Vue reactivity. Replace the data reference, update revision, or call an exposed method.

For polished dashboard time data, use TimeseriesChart. It composes ECharts with opinionated line, area, bar, axis, legend, tooltip, and motion defaults. Keep XYPlot for dense or sustained technical data.

<script setup lang="ts">
import { shallowRef } from "vue";
import {
  XYPlot,
  type XYPlotData,
  type XYPlotSeries,
} from "@dicehub/kappa/components/xy-plot";

const data = shallowRef<XYPlotData>([
  new Float64Array([0, 1, 2, 3]),
  new Float64Array([0.08, 0.021, 0.006, 0.0014]),
]);
const series: XYPlotSeries[] = [{ label: "p", width: 1.5 }];
</script>

<template>
  <XYPlot
    :data="data"
    :series="series"
    title="Residual monitor"
    aria-label="Pressure residual plot"
    aria-description="Pressure residual decreases across four iterations."
    x-label="Iteration"
    y-label="Residual"
    y-scale="log"
  />
</template>

Examples

Scatter

Use ECharts Canvas and its large mode for a broad scatter plot.

<Chart
  :engine="echarts"
  :options="{
    animation: false,
    xAxis: { type: 'value', name: 'Velocity (m/s)' },
    yAxis: { type: 'value', name: 'Pressure (kPa)' },
    series: [{ type: 'scatter', data: samples, large: true }],
  }"
  aria-label="Pressure field samples"
  aria-description="Pressure samples plotted against velocity."
/>

Heatmap

Use categorical axes and a visual scale for a compact utilization matrix.

<Chart
  :engine="echarts"
  :options="{
    xAxis: { type: 'category', data: hours },
    yAxis: { type: 'category', data: days },
    visualMap: { min: 0, max: 100 },
    series: [{ type: 'heatmap', data: load }],
  }"
  aria-label="Compute load by hour"
  aria-description="Compute load is highest on weekday afternoons."
/>

Sankey

Show flow between stages without changing the Kappa frame or accessibility contract.

<Chart
  :engine="echarts"
  :options="{
    series: [{
      type: 'sankey',
      data: nodes,
      links,
      emphasis: { focus: 'adjacency' },
    }],
  }"
  aria-label="Case processing flow"
  aria-description="Jobs move from geometry through meshing and solving."
/>

100,000-point X/Y Plot

Pass aligned typed arrays directly to uPlot. Kappa does not deep-watch the values.

<script setup lang="ts">
import { XYPlot, type XYPlotData } from "@dicehub/kappa/components/xy-plot";

const pointCount = 100_000;
const x = new Float64Array(pointCount);
const pressure = new Float64Array(pointCount);
for (let index = 0; index < pointCount; index += 1) {
  x[index] = index * 0.005;
  pressure[index] = 1.2 + Math.sin(index * 0.007) * 0.18;
}
const data: XYPlotData = [x, pressure];
</script>

<template>
  <XYPlot
    :data="data"
    :series="[{ label: 'Pressure', width: 1 }]"
    aria-label="Dense pressure signal"
    aria-description="100,000 pressure samples across 500 seconds."
    x-label="Time (s)"
    y-label="Pressure"
  />
</template>

Streaming

Append bounded chunks. Calls in one animation frame become one draw.

const plot = useTemplateRef("plot");

function receiveSamples(chunk: XYPlotData) {
  // Calls within one frame become one uPlot update.
  // The oldest samples are removed at the limit.
  plot.value?.append(chunk, { maxPoints: 2_000 });
}

<XYPlot
  ref="plot"
  :data="initialData"
  :series="series"
  aria-label="Live residual plot"
  aria-description="Three residuals decrease over the solver iterations."
/>

Data States

The same frame provides loading, empty, and error states for both engines.

<Chart loading ... />
<Chart empty empty-label="No samples in this range" ... />
<Chart error="The data query failed." ... />

Performance

Use ECharts Canvas for normal dashboards and broad chart types.
Use XYPlot for dense aligned numeric series and sustained updates.
Use typed arrays for large static series. Do not put million-point arrays in deep Vue reactivity.
Aggregate and window million-point history before it reaches the browser. A renderer cannot remove transfer, parsing, and memory costs.
Batch live updates and keep a fixed point window. Stop subscriptions when the component unmounts or the view becomes inactive.

Accessibility

ariaLabel names the chart. ariaDescription states the visible range, units, series, and main trend.
Do not use color as the only series identifier. Keep labels or a linked data table available.
XYPlot supports drag, wheel, keyboard zoom, double-click reset, and a visible reset button.
Press plus or minus to zoom X. Hold Shift to zoom Y. Press 0 or Home to reset.
Loading, empty, and error messages use live status semantics.

Security

Treat engine options and callbacks as application code. Never pass serialized user configuration directly. Kappa removes ECharts HTML tooltip formatters, extra tooltip CSS, data view, and built-in image download from the standard option path. Use parsed and validated GeoJSON objects for maps.

API Reference

Chart

Prop	Type	Default	Description
`engine`	`ChartEngine`	`required`	Configured modular ECharts namespace.
`options`	`ChartOptions`	`required`	Trusted ECharts options with safe standard tooltips.
`ariaLabel`	`string`	`required`	Accessible name for the rendered chart.
`ariaDescription`	`string`	`required`	Plain-language data summary or interaction instructions.
`title / description`	`string`	`—`	Compact visible heading and context.
`height`	`CSS height \| number`	`"20rem"`	Stable plot body height. Numbers use pixels.
`renderer`	`"canvas" \| "svg"`	`"canvas"`	Registered ECharts renderer.
`loading / empty / error`	`boolean / boolean / string`	`false / false / —`	Complete data states.
`events`	`ChartEvents`	`—`	Stable event-to-handler map.
`revision`	`string \| number`	`0`	Reapplies options after controlled in-place mutation.
`updateOptions`	`SetOptionOpts`	`—`	ECharts setOption update behavior.

XYPlot

Prop	Type	Default	Description
`data`	`XYPlotData`	`required`	Aligned X and Y columns. Typed arrays are supported.
`series`	`XYPlotSeries[]`	`required`	One definition for each Y column.
`ariaLabel / ariaDescription`	`string`	`required`	Accessible chart name and data summary.
`xScale`	`"linear" \| "time"`	`"linear"`	X-axis scale.
`yScale`	`"linear" \| "log"`	`"linear"`	Y-axis scale.
`zoom`	`"none" \| "x" \| "xy"`	`"xy"`	Drag and keyboard zoom axes.
`wheelZoom`	`boolean`	`true`	Wheel zooms X. Shift plus wheel zooms Y.
`showLegend / showReset`	`boolean`	`true`	Built-in live legend and reset action.
`nativeOptions`	`XYPlotNativeOptions`	`—`	Trusted uPlot options for advanced composition.
`revision`	`string \| number`	`0`	Applies an in-place data mutation without a deep watcher.

Exposed Methods

Component	Method	Description
`Chart`	`getInstance / resize / setOption / dispatchAction`	Access the ECharts instance and imperative engine operations.
`TimeseriesChart`	`getInstance / resize / setOption / dispatchAction`	Access advanced ECharts operations when the opinionated API is not enough.
`XYPlot`	`getInstance / resize / resetZoom / setData / setScale`	Control the uPlot instance without deep Vue reactivity.
`XYPlot`	`append / flush`	Batch bounded stream chunks into one animation-frame update.
`XYPlot`	`batch`	Run multiple uPlot operations in one engine batch.

Exports

Path	Exports
`@dicehub/kappa/components/chart`	`Chart, ChartProps, ChartOptions, ChartEngine, ChartInstance`
`@dicehub/kappa/components/xy-plot`	`XYPlot, XYPlotProps, XYPlotData, XYPlotSeries, appendXYPlotData`
`@dicehub/kappa/components/timeseries-chart`	`TimeseriesChart, TimeseriesChartProps, TimeseriesChartSeries, TimeseriesChartApi`