Custom Chart
The composable escape hatch: lines, areas, bars, scatter and donuts from primitives.
Usage
kumo's escape hatch pipes raw echarts options into a low-level Chart; here that job belongs to the ECharts Family (TxEChart plus typed wrappers), and this page is the composition hatch: TxChart establishes the coordinate system (measures the container, derives scales, allocates palette slots) and axes/grid/series mount as children in its default slot. Series read data through accessors (a key or (d, i) => v); without color they take categorical slots in mount order. The x/y domains derive from the union of all series data, and xDomain/yDomain override explicitly.
Bars + line composed
Band axis + bars + line
Bars and a line share one coordinate system; band values map to band centers.
Donut
TxArcSeries
Axis-free mode: TxChart acts as a sized surface and the arc series lays itself out.
Custom tooltip
Overlay slot + TxChartTooltip
With follow='x' the tooltip pins vertically and only tracks horizontally.
A custom layer does not animate on its own: use useEnterProgress() for the first render and useTweenedNumbers() for data updates, with the exported durations and threshold; reduced motion lands on the final frame.
<script setup lang="ts">
import { ANIMATION_THRESHOLD, ENTER_DURATION, easings, useChartContext, useEnterProgress } from '@talex-touch/tuffex/charts'
import { computed } from 'vue'
const props = defineProps<{ pointCount: number }>()
const ctx = useChartContext('MyLayer')
const plot = computed(() => ctx.plot.value)
// 0 → 1 while the enter reveal runs; stays at 1 above the threshold or under reduced motion
const enter = useEnterProgress({
duration: ENTER_DURATION,
easing: easings.linear,
enabled: () => props.pointCount <= ANIMATION_THRESHOLD,
})
const enterWidth = computed(() => plot.value.width * enter.value)
</script>
<template>
<defs>
<clipPath id="my-layer-enter">
<rect :x="plot.x" :y="plot.y" :width="enterWidth" :height="plot.height" />
</clipPath>
</defs>
<g :clip-path="'url(#my-layer-enter)'">
<slot />
</g>
</template>
API Reference
Chart Props
| Prop | Type | Default | Description |
|---|---|---|---|
height | number | 350 | Pixel height; ignored when aspectRatio is set. |
aspectRatio | number | string | — | Container aspect ratio. |
width | number | measured | Explicit width (SSR/tests). |
padding | number | Partial<ChartPadding> | 24 | Inner padding reserved for axes and labels. |
xType | 'linear' | 'log' | 'time' | 'band' | 'linear' | Kind of x scale; a log axis leaves out data at x ≤ 0. |
xDomain / yDomain | arrays | auto union | Explicit domains. |
yNice | boolean | true | Round the derived y domain. |
ariaDescription | string | — | Accessible name, falling back to labels.chart; a chart that cannot take focus reads it as role="img". |
interactive | boolean | true | Reads values on hover, press-drag and the arrow keys; false leaves a static picture with no focus stop and no reading. |
announce | (x: string | number) => string | Formatted like the x-axis ticks | What a keyboard reading at an x value says. |
labels | Partial<ChartLabels> | English | Accessible name and key instructions: chart, instructions, and zoomInstructions, read instead on a chart that zooms. |
Series Props (shared)
| Prop | Type | Description |
|---|---|---|
data | T[] | Data rows. |
x / y | keyof T | (d, i) => v | Accessors. |
color | string | Defaults to categorical slots in mount order. |
Series-specific Props
| Prop | Type | Default | Description |
|---|---|---|---|
curve | 'linear' | 'monotone' | 'natural' | 'step' | 'linear' | Curve interpolation for TxLineSeries and TxAreaSeries. |
strokeWidth | number | 2 | Stroke width in pixels for TxLineSeries and TxAreaSeries; 0 hides an area's top line. |
showSymbol | boolean | false | TxLineSeries: draws a dot at each data point. |
dashed | boolean | false | TxLineSeries: dashes the stroke, for incomplete data. |
enter | 'clip' | 'draw' | 'clip' | TxLineSeries first-render reveal: clip wipes open left to right, draw traces the stroke; a dashed stroke always clips. |
gradient | boolean | true | TxAreaSeries: vertical gradient fill. |
fillOpacity | number | 0.2 | TxAreaSeries fill opacity when gradient is off; TxScatterSeries dots default to 0.9. |
stack | string | — | TxBarSeries: series sharing a key stack; without one they sit side by side. |
barWidth | number | — | TxBarSeries: explicit bar width in pixels, derived from the scale by default. |
radius | number | 0 | TxBarSeries: corner radius of bars. |
r | number | accessor | 3 | TxScatterSeries: dot radius in pixels, constant or per datum. |
value | accessor | — | TxArcSeries: accessor that sets each slice's angle. |
name | accessor | — | TxArcSeries: optional name accessor, exposed on slice events. |
color | accessor | categorical | TxArcSeries: per-slice color. |
innerRadius | number | 0.6 | TxArcSeries: inner radius as a fraction of the outer radius; 0 draws a pie. |
padAngle | number | 0.015 | TxArcSeries: angular gap between slices, in radians. |
cornerRadius | number | 2 | TxArcSeries: slice corner radius in pixels. |
announce | (slice) => string | name: value | TxArcSeries: text spoken for a keyboard reading. |
TxArcSeries emits slice-click when a slice is clicked and slice-hover with the hovered slice, or null once the pointer leaves the arc. The axis-free arc has no chart context to read, so an #overlay <TxChartTooltip> takes its values from slice-hover. A press-drag reads the ring like a dial, slice by slice by angle, and its release does not fire slice-click; with the chart focused, ← / → read slice by slice, Home / End jump to either end and Escape clears.
TxChartTooltip Props
| Prop | Type | Default | Description |
|---|---|---|---|
open | boolean | 'auto' | 'auto' | 'auto' shows while the pointer is inside; a boolean is controlled mode. |
follow | 'both' | 'x' | 'both' | x pins the vertical position. |
offset | number | 12 | Gap between pointer and tooltip. |
fixedY | number | 0 | Vertical position in pixels when follow is x. |
footer | string | — | Extra line below the row list (kumo's tooltipFooter). |
boundary | 'clipping-ancestors' | Element | Element[] | 'clipping-ancestors' | Collision boundary (ECharts confine): by default intersects the clipping ancestors with the viewport and flips. |
title / rows / hiddenCount | — | — | Default content; the slot replaces it entirely. |
moreLabel | (count: number) => string | +N more | Footer text for the rows folded by hiddenCount. |
The tooltip keeps ECharts' cadence as well: it waits out a 100ms hideDelay before the 200ms fade-out and DOM removal, so a brief pointer excursion does not flicker it; movement is handed to the browser as a 400ms transform: translate3d() transition; and pointer tracking is throttled to 50ms, sampling once on entry and once on exit.
Reading Values
TxChart reads values itself; a custom layer only reads pointer:
- A hovering mouse places the reading at the pointer; a press-drag (mouse, touch or pen) keeps reading past a 4px slop and stays on the plot's edge when it leaves the plot. The click a drag's release produces is swallowed, so it reaches neither the chart nor anything around it.
- One finger reads on touch from the press; the chart sets
touch-action: pan-y, so a vertical swipe still scrolls the page. - With the chart focused, ← / → read datum by datum along x, Home / End jump to either end and Escape clears; readings go to a polite live region, worded by
announce. - On
useChartContext().pointer,x/yare container pixels,insidemeans a reading is showing,pressedmeans a press-drag holds the pointer, andsourceis'keyboard'for a reading the keys placed: at the datum's x, vertically centered, with no pointer height. nearestXStop(px)returns the data x drawn nearest a pixel, which is how a crosshair snaps to data; a layer added withregisterKeyLayer({ key, clear })gets keys before the datum-by-datum reading and returnstrueonce it handled one — that is howTxArcSeriesreads slices.
Composition Rules
- Series/axes/grid must be descendants of
<TxChart>— they read scales from the injected chart context and throw when used standalone. - Multiple
TxBarSeries: withoutstackthey lay out side by side; sharing astackkey stacks them, and the y domain covers stacked totals automatically. TxArcSeriesneeds no coordinate system and works in an axis-freeTxChart.- The
#overlayslot is a DOM layer above the SVG (pointer-events: none) for tooltips and annotations. - For deep customization, call
useChartContext()in your own layer, or read scales from thecontextexposed on theTxChartinstance.