API Đài phun (Jet d'Eau)

Một biểu đồ, hai chế độ: chiều cao đỉnh tia = giá trị, chùm tia nở rộng = độ bất định. Trục x dạng phân loại (categorical) = ảnh chụp nhanh/so sánh (snapshot/comparison); trục x dạng thời gian hoặc số = xu hướng (trend) - xem demo Đài phun.

Nhập

Web Component

import "@michi-vz/wc/fountain-chart";
// <michi-vz-fountain-chart> is now defined

Vanilla JS

import { mountFountainChart } from "@michi-vz/core";

const chart = mountFountainChart(el, props);

Thuộc tính

Prop	Type	Default	Description
timeline	boolean | TimelinePeriodConfig	-	Opt-in "play through years" (cumulative): the marks draw UP TO the active period and extend as the timeline steps; `interpolate` sweeps smoothly between years, `false` jump-cuts. Headless controller via `chart.timeline()` plus the built-in play button + scrubber. Off by default; wins over `progressiveDraw` when both are set.
progressiveDraw	boolean | ProgressiveDrawConfig	-	Opt-in reveal animation: wipes the marks in left to right on mount (a clip reveal; axes and titles stay put). `true` uses defaults (1200 ms, easeInOutCubic); a config tunes durationMs, easing, autoplay, and replayOnUpdate (`tipLabel` is LineChart-only and ignored here). Off by default; respects prefers-reduced-motion (renders fully drawn instantly) and `replay()` re-runs it.
dataSet*	FountainDataItem[]	-	Array of jets; each item renders one fountain
title	string	-	Optional chart title rendered above the plot
style	"jet" | "plume"	"jet"	Silhouette style: "jet" (default) is the faithful asymmetric Jet d'Eau (vertical column + wind-blown diagonal + a triangular droplet spray curtain); "plume" is the symmetric blooming column.
xAxisDataType	FountainXAxisType	-	How the x-axis is parsed: a temporal/numeric type renders TREND mode; "band" (or omitted) renders SNAPSHOT mode
yAxisDomain	[number, number]	-	Explicit [min, max] for the value (y) axis; overrides the auto domain from value + spread
xAxisFormat	(d: number | string) => string	-	Formats an x tick value into its display label
yAxisFormat	(d: number | string) => string	-	Formats a y tick value into its display label
ticks	number	5	Approximate number of axis ticks to generate
tickValues	Array<number | Date>	-	Explicit tick values, overriding the generated ones (trend mode)
frothLayers	number	14	Number of graduated-opacity froth layers per jet (default 14, max 20); a per-item density overrides it
bloomExponent	number	5	Exponent in the bloom easing w(h)=stemHalf+spread*(h/H)^p; larger = tighter column, sharper crown (default 5)
stemFraction	number	0.045	Stem half-width at the base as a fraction of the jet's slot width (default 0.045)
showDroplets	boolean	true	Draw ballistic droplet arcs above each apex (default true)
showMist	boolean	true	Draw the misty falling skirt around each nozzle (default true)
showTrendLine	boolean	true	Draw a connecting line through the apexes in trend mode (default true)
tooltipFormatter	(d: FountainDataItem) => string	-	Returns custom tooltip HTML for a hovered jet (sanitized before it is inserted)
onHighlightItem	(labels: string[]) => void	-	Called when the hovered/highlighted label(s) change

Common props - shared by every chart (14)

Prop	Type	Default	Description
width	number	900	Chart width in pixels
height	number	480	Chart height in pixels
margin	Margin	{ top: 50, right: 40, bottom: 50, left: 60 }	Inner margins (top/right/bottom/left, in px) reserved for axes, titles, and labels
colors	string[]	-	Categorical palette for series/labels without an explicit colour or colorsMapping entry
colorsMapping	Record<string, string>	-	Explicit label -> colour map; takes precedence over the palette and per-item colours
highlightItems	string[]	-	Labels to emphasise; all other marks dim
disabledItems	string[]	-	Labels to hide and exclude from scales/stacks
renderer	"svg" | "canvas" | "webgpu"	"svg"	Render as inline SVG (default) or to a canvas (faster for large datasets); getContext() is identical either way
locale	string	-	BCP-47 locale used for number and date formatting
skipColorMappingDispatch	boolean	false	External-CSS mode: unmapped labels resolve to transparent and onColorMappingGenerated is not emitted, so mark colours come from your CSS via the data-label-safe contract
enableTransitions	boolean	true	Animate updates with CSS transitions (default true)
onColorMappingGenerated	(mapping: Record<string, string>) => void	-	Called with the resolved label -> colour map after the chart assigns colours
onChartDataProcessed	(context: ChartContext) => void	-	Called with the renderer-agnostic ChartContext whenever the data is (re)processed
onDataWarning	(warnings: DataWarning[]) => void	-	Called with any non-fatal data warnings (duplicate labels, non-finite values, non-monotonic dates, ...)

Hai chế độ, một cấu trúc dữ liệu

Đặt xAxisDataType: "band" (hoặc bỏ qua nó) để dùng chế độ Snapshot (ảnh chụp nhanh) - mỗi mục có dải trục x (x-band) riêng, đặt cạnh nhau. Cung cấp xAxisDataType dạng thời gian hoặc số cùng với một trường date trên mỗi mục để dùng chế độ Trend (xu hướng) - các tia nước được đặt dọc theo trục thời gian và một đường xu hướng nối các đỉnh của chúng. Một mục có predicted: true sẽ được vẽ bằng nét đứt với đỉnh sủi bọt nhiều hơn.

Sự kiện

Web component phát ra (dispatch) các CustomEvent nổi bọt (bubbling) sau đây (engine cũng phơi bày các sự kiện tương tự thông qua các callback on* trong bảng ở trên):

Sự kiện	Chi tiết	Kích hoạt khi
michi-vz:highlight	string[]	trạng thái nổi bật lúc di chuột thay đổi (nhãn tia nước)
michi-vz:colormapping	Record<string, string>	một ánh xạ màu được tạo ra
michi-vz:dataprocessed	ChartContext	dữ liệu được xử lý (lại)
michi-vz:datawarning	DataWarning[]	phát hiện cảnh báo đầu vào (ví dụ: giá trị hoặc độ lệch (spread) không hữu hạn)

getContext()

mountFountainChart(el, props).getContext() trả về FountainChartContext độc lập với renderer:

• mode - "snapshot" khi trục x là dạng phân loại/dải (categorical/band), "trend" khi trục x là dạng thời gian/số.
• jets - một mục cho mỗi tia nước đang hiển thị: { label, code?, color, value, spread, upperBound, spreadRatio, predicted, xPosition }. upperBound = value + spread; spreadRatio = spread / value (độ bất định tương đối); xPosition là giá trị ngày/số gốc trong chế độ trend, hoặc null trong chế độ snapshot.
• stats - đối tượng tổng hợp:
  • jetCount - số lượng tia nước đang hiển thị.
  • tallest - { label, value } của tia nước cao nhất, hoặc null nếu rỗng.
  • frothiest - { label, spreadRatio } của tia nước bất định nhất, hoặc null nếu rỗng.
  • trendSlope - độ dốc của một hồi quy tuyến tính qua các giá trị tia nước theo chỉ số trong chế độ trend; null trong chế độ snapshot.
  • valueRange - [min, max] của các giá trị tia nước, hoặc null nếu rỗng.
  • predictedCount - số lượng tia nước dự báo.

Xem ngữ cảnh LLM để biết cách sử dụng ngữ cảnh này trong prompt và báo cáo.

Nguồn

Các thuộc tính (props) được định kiểu là FountainChartProps trong @michi-vz/core.