Components/Custom Chart

Custom Chart

The composable escape hatch: lines, areas, bars, scatter and donuts from primitives.

VerifiedSince 0.1.0

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.

Loading demo...

Donut

TxArcSeries

Axis-free mode: TxChart acts as a sized surface and the arc series lays itself out.

Loading demo...

Custom tooltip

Overlay slot + TxChartTooltip

With follow='x' the tooltip pins vertically and only tracks horizontally.

Loading demo...

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

PropTypeDefaultDescription
heightnumber350Pixel height; ignored when aspectRatio is set.
aspectRationumber | string—Container aspect ratio.
widthnumbermeasuredExplicit width (SSR/tests).
paddingnumber | Partial<ChartPadding>24Inner 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 / yDomainarraysauto unionExplicit domains.
yNicebooleantrueRound the derived y domain.
ariaDescriptionstring—Accessible name, falling back to labels.chart; a chart that cannot take focus reads it as role="img".
interactivebooleantrueReads 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) => stringFormatted like the x-axis ticksWhat a keyboard reading at an x value says.
labelsPartial<ChartLabels>EnglishAccessible name and key instructions: chart, instructions, and zoomInstructions, read instead on a chart that zooms.

Series Props (shared)

PropTypeDescription
dataT[]Data rows.
x / ykeyof T | (d, i) => vAccessors.
colorstringDefaults to categorical slots in mount order.

Series-specific Props

PropTypeDefaultDescription
curve'linear' | 'monotone' | 'natural' | 'step''linear'Curve interpolation for TxLineSeries and TxAreaSeries.
strokeWidthnumber2Stroke width in pixels for TxLineSeries and TxAreaSeries; 0 hides an area's top line.
showSymbolbooleanfalseTxLineSeries: draws a dot at each data point.
dashedbooleanfalseTxLineSeries: 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.
gradientbooleantrueTxAreaSeries: vertical gradient fill.
fillOpacitynumber0.2TxAreaSeries fill opacity when gradient is off; TxScatterSeries dots default to 0.9.
stackstring—TxBarSeries: series sharing a key stack; without one they sit side by side.
barWidthnumber—TxBarSeries: explicit bar width in pixels, derived from the scale by default.
radiusnumber0TxBarSeries: corner radius of bars.
rnumber | accessor3TxScatterSeries: dot radius in pixels, constant or per datum.
valueaccessor—TxArcSeries: accessor that sets each slice's angle.
nameaccessor—TxArcSeries: optional name accessor, exposed on slice events.
coloraccessorcategoricalTxArcSeries: per-slice color.
innerRadiusnumber0.6TxArcSeries: inner radius as a fraction of the outer radius; 0 draws a pie.
padAnglenumber0.015TxArcSeries: angular gap between slices, in radians.
cornerRadiusnumber2TxArcSeries: slice corner radius in pixels.
announce(slice) => stringname: valueTxArcSeries: 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

PropTypeDefaultDescription
openboolean | 'auto''auto''auto' shows while the pointer is inside; a boolean is controlled mode.
follow'both' | 'x''both'x pins the vertical position.
offsetnumber12Gap between pointer and tooltip.
fixedYnumber0Vertical position in pixels when follow is x.
footerstring—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 moreFooter 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 / y are container pixels, inside means a reading is showing, pressed means a press-drag holds the pointer, and source is '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 with registerKeyLayer({ key, clear }) gets keys before the datum-by-datum reading and returns true once it handled one — that is how TxArcSeries reads 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: without stack they lay out side by side; sharing a stack key stacks them, and the y domain covers stacked totals automatically.
  • TxArcSeries needs no coordinate system and works in an axis-free TxChart.
  • The #overlay slot 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 the context exposed on the TxChart instance.