feat(chart): rename formatter to dangerousHtmlFormatter for XSS awareness (#414)

BREAKING CHANGE: The formatter property in KumoChartOption['tooltip'] has been
renamed to dangerousHtmlFormatter. This change makes the security implications
of using HTML formatters more explicit to developers.

- Update EChart.tsx with new property name and warnings
- Update TimeseriesChart.tsx to use dangerousHtmlFormatter
- Add migration examples in documentation
- Include changeset for minor version bump

Author: invisal

.changeset/chart-dangerous-html-formatter.md

@@ -0,0 +1,9 @@
+---
+"@cloudflare/kumo": minor
+---
+
+feat(chart): rename `formatter` to `dangerousHtmlFormatter` for XSS awareness
+
+BREAKING CHANGE: The `formatter` property in `KumoChartOption['tooltip']` has been renamed to `dangerousHtmlFormatter`. This change makes the security implications of using HTML formatters more explicit to developers. The API remains identical—only the name has changed.
+
+Migration: Replace `formatter` with `dangerousHtmlFormatter` in your chart tooltip configurations.

packages/kumo-docs-astro/src/components/demos/Chart/ChartDemo.tsx

@@ -6,7 +6,7 @@ import {
   LayerCard,
 } from "@cloudflare/kumo";
 import * as echarts from "echarts/core";
-import type { EChartsOption } from "echarts";
+import type { KumoChartOption } from "@cloudflare/kumo";
 import { BarChart, LineChart, PieChart } from "echarts/charts";
 import { useEffect, useMemo, useState } from "react";
 import {
@@ -41,8 +41,8 @@ export function PieChartDemo() {
       ({
         animation: true,
         animationDuration: 2000,
-        toolbox: {
-          show: false,
+        tooltip: {
+          show: true,
         },
         series: [
           {
@@ -56,7 +56,7 @@ export function PieChartDemo() {
             ],
           },
         ],
-      }) as EChartsOption,
+      }) satisfies KumoChartOption,
     [],
   );
 
@@ -287,7 +287,7 @@ export function PieChartPreviewDemo() {
             ],
           },
         ],
-      }) as EChartsOption,
+      }) satisfies KumoChartOption,
     [],
   );
 
@@ -424,7 +424,7 @@ export function BarChartDemo() {
   const data = useMemo(
     () => [
       {
-        name: "Requests",
+        name: "Requests where age > 10",
         data: buildSeriesData(0, 20, 3_600_000, 1),
         color: ChartPalette.semantic("Neutral", isDarkMode),
       },
@@ -445,6 +445,7 @@ export function BarChartDemo() {
       data={data}
       xAxisName="Time (UTC)"
       yAxisName="Count"
+      tooltipValueFormat={(r) => r.toFixed(2)}
     />
   );
 }
@@ -540,6 +541,72 @@ export function ChartExampleDemo() {
   );
 }
 
+/**
+ * Custom chart with HTML tooltip using dangerousHtmlFormatter.
+ * USE WITH CAUTION: Only use dangerousHtmlFormatter for trusted HTML content.
+ * Always sanitize any user-provided data using echarts.format.encodeHTML
+ * or similar utilities to prevent XSS vulnerabilities.
+ */
+export function CustomTooltipChartDemo() {
+  const isDarkMode = useIsDarkMode();
+
+  const options = useMemo<KumoChartOption>(
+    () => ({
+      tooltip: {
+        trigger: "item",
+        // Use dangerousHtmlFormatter instead of formatter to make the
+        // security implications explicit. Only use with trusted content.
+        dangerousHtmlFormatter: (params: any) => {
+          // IMPORTANT: Always escape ALL dynamic values using encodeHTML
+          // from echarts/format before including in HTML. This prevents
+          // XSS attacks from malicious data like:
+          // { name: "<img src=x onerror=alert('xss')>", value: "..." }
+          const safeName = echarts.format.encodeHTML(params.name);
+          const safeValue = echarts.format.encodeHTML(String(params.value));
+          const safePercent = echarts.format.encodeHTML(
+            String(Math.round(params.percent)),
+          );
+
+          return `
+            <div style="padding: 8px;">
+              <div style="font-weight: 600; margin-bottom: 4px;">${safeName}</div>
+              <div>Value: <strong>${safeValue}</strong></div>
+              <div style="font-size: 12px; opacity: 0.7; margin-top: 4px;">
+                ${safePercent}% of total
+              </div>
+            </div>
+          `;
+        },
+      },
+      series: [
+        {
+          type: "pie",
+          data: [
+            { value: 101, name: "Series A" },
+            { value: 202, name: "Series B" },
+            // Malicious series name to demonstrate XSS protection via encodeHTML.
+            // Without encoding, this would render an alert popup. With encodeHTML,
+            // it safely displays as plain text.
+            { value: 150, name: "<img src=x onerror=alert('XSS')>" },
+            { value: 303, name: "Series C" },
+            { value: 404, name: "Series D" },
+          ],
+        },
+      ],
+    }),
+    [],
+  );
+
+  return (
+    <Chart
+      echarts={echarts}
+      options={options}
+      height={400}
+      isDarkMode={isDarkMode}
+    />
+  );
+}
+
 function buildSeriesData(
   seed = 0,
   points = 50,

packages/kumo-docs-astro/src/pages/charts/custom.mdx

@@ -6,7 +6,10 @@ sourceFile: "components/chart"
 ---
 
 import ComponentSection from "~/components/docs/ComponentSection.astro";
-import { PieChartDemo } from "~/components/demos/Chart/ChartDemo";
+import {
+  PieChartDemo,
+  CustomTooltipChartDemo,
+} from "~/components/demos/Chart/ChartDemo";
 import ComponentExample from "~/components/docs/ComponentExample.astro";
 import Heading from "~/components/docs/Heading.astro";
 
@@ -17,3 +20,15 @@ import Heading from "~/components/docs/Heading.astro";
     <PieChartDemo client:visible />
   </ComponentExample>
 </ComponentSection>
+
+<ComponentSection>
+  <Heading level={2}>Custom Tooltip with HTML</Heading>
+
+For tooltips that require custom HTML formatting, use the `dangerousHtmlFormatter` property instead of the standard `formatter`. This makes the security implications more explicit.
+
+When using `dangerousHtmlFormatter`, it is **strongly recommended** to sanitize any user-provided content using `echarts.format.encodeHTML` to prevent XSS vulnerabilities.
+
+  <ComponentExample demo="CustomTooltipChartDemo">
+    <CustomTooltipChartDemo client:visible />
+  </ComponentExample>
+</ComponentSection>

packages/kumo/src/components/chart/EChart.tsx

@@ -1,5 +1,9 @@
 import type * as echarts from "echarts/core";
-import type { EChartsOption, SetOptionOpts } from "echarts";
+import type {
+  EChartsOption,
+  SetOptionOpts,
+  TooltipComponentOption,
+} from "echarts";
 import { forwardRef, useEffect, useRef } from "react";
 import { cn } from "../../utils";
 import { CHART_DARK_COLORS, CHART_LIGHT_COLORS } from "./Color";
@@ -28,6 +32,26 @@ type EChartsMouseEventParams = {
   color?: string;
 };
 
+/**
+ * Tooltip options with the `formatter` property removed and replaced with
+ * `dangerousHtmlFormatter` to make the security implications more explicit.
+ */
+export type SafeTooltipOption = Omit<TooltipComponentOption, "formatter"> & {
+  /**
+   * USE WITH CAUTION: Use this only for trusted HTML content.
+   * When building tooltip HTML with user-provided data, always sanitize
+   * the input to prevent XSS vulnerabilities. Recommended: use
+   * `encodeHTML` from `echarts/format` to escape HTML special characters.
+   */
+  dangerousHtmlFormatter?: TooltipComponentOption["formatter"];
+};
+
+export type KumoChartOption = {
+  [K in keyof EChartsOption]: K extends "tooltip"
+    ? SafeTooltipOption | SafeTooltipOption[] | undefined
+    : EChartsOption[K];
+};
+
 /**
  * ECharts event handlers that can be attached to a `Chart`.
  * Pass a subset via the `onEvents` prop; handlers are registered lazily and
@@ -107,7 +131,7 @@ export interface ChartProps {
    */
   echarts: typeof echarts;
   /** ECharts option object — passed through to `chart.setOption()` */
-  options: EChartsOption;
+  options: KumoChartOption;
   /**
    * Additional options passed as the second argument to `chart.setOption()`.
    * Defaults to `{ notMerge: false, lazyUpdate: true }`.
@@ -126,6 +150,25 @@ export interface ChartProps {
   onEvents?: Partial<ChartEvents>;
 }
 
+const transformTooltip = (tooltipObj: SafeTooltipOption) => {
+  const { dangerousHtmlFormatter, ...restOfTooltip } = tooltipObj;
+  return {
+    ...restOfTooltip,
+    formatter: dangerousHtmlFormatter,
+  };
+};
+
+const prepareChartOptions = (options: KumoChartOption): EChartsOption => {
+  if (!options.tooltip) return options;
+
+  return {
+    ...options,
+    tooltip: Array.isArray(options.tooltip)
+      ? options.tooltip.map(transformTooltip)
+      : transformTooltip(options.tooltip),
+  };
+};
+
 /**
  * Chart — a low-level wrapper around [Apache ECharts](https://echarts.apache.org).
  *
@@ -209,7 +252,7 @@ export const Chart = forwardRef<echarts.ECharts, ChartProps>(function Chart(
     const chart = chartRef.current;
     if (!chart) return;
 
-    chart.setOption(options, {
+    chart.setOption(prepareChartOptions(options), {
       notMerge: false,
       lazyUpdate: true,
       ...optionUpdateBehavior,

packages/kumo/src/components/chart/TimeseriesChart.tsx

@@ -1,8 +1,8 @@
 import type * as echarts from "echarts/core";
 import type { LineSeriesOption, BarSeriesOption } from "echarts/charts";
-import type { EChartsOption } from "echarts";
+import type { EChartsOption, SeriesOption } from "echarts";
 import { useEffect, useMemo, useRef } from "react";
-import { Chart, ChartEvents } from "./EChart";
+import { Chart, ChartEvents, KumoChartOption } from "./EChart";
 
 /** A single data series rendered on a `TimeseriesChart` */
 export interface TimeseriesData {
@@ -221,7 +221,6 @@ export function TimeseriesChart({
         ...(ariaDescription && { label: { description: ariaDescription } }),
       },
       brush: {
-        snapToData: true,
         xAxisIndex: "all" as const,
         brushType: "lineX" as const,
         brushMode: "single" as const,
@@ -236,8 +235,9 @@ export function TimeseriesChart({
       },
       tooltip: {
         trigger: "axis" as const,
+        appendTo: "body",
         axisPointer: { type: "shadow" as const },
-        formatter: (params: any) => {
+        dangerousHtmlFormatter: (params) => {
           const items = Array.isArray(params) ? params : [params];
 
           // Track seen series names to avoid duplicates in tooltip
@@ -250,21 +250,27 @@ export function TimeseriesChart({
             return true;
           });
 
-          const first = filteredParams[0];
+          const first = filteredParams[0] as {
+            value?: [number, number];
+            axisValue?: number;
+          };
+
           const ts = first?.value?.[0] ?? first?.axisValue;
+
           const header =
             ts != null
-              ? `<div style="font-weight:600;margin-bottom:4px;">${formatTimestamp(ts)}</div>`
+              ? `<div style="font-weight:600;margin-bottom:4px;">${echarts.format.encodeHTML(formatTimestamp(ts))}</div>`
               : "";
 
           const rows = filteredParams
             .map((param: any) => {
               const value = param?.value?.[1];
               const formatFn = tooltipValueFormat ?? yAxisTickLabelFormat;
               const formattedValue = formatFn
-                ? escapeHtml(String(formatFn(value)))
-                : escapeHtml(String(value));
-              return `${param.marker} ${escapeHtml(String(param.seriesName))}: <strong>${formattedValue}</strong>`;
+                ? echarts.format.encodeHTML(String(formatFn(value)))
+                : echarts.format.encodeHTML(String(value));
+
+              return `${param.marker} ${echarts.format.encodeHTML(param.seriesName)}: <strong>${formattedValue}</strong>`;
             })
             .join("<br/>");
 
@@ -313,8 +319,8 @@ export function TimeseriesChart({
         top: 24,
         bottom: xAxisName ? 30 : 24,
       },
-      series: transformSeries,
-    };
+      series: transformSeries as SeriesOption[],
+    } satisfies KumoChartOption;
   }, [
     data,
     xAxisName,
@@ -494,12 +500,6 @@ function pad(n: number) {
   return n.toString().padStart(2, "0");
 }
 
-function escapeHtml(str: string): string {
-  const div = document.createElement("div");
-  div.textContent = str;
-  return div.innerHTML;
-}
-
 /**
  * Formats a timestamp as `"YYYY-MM-DD HH:mm:ss"` for use in chart tooltips.
  * Accepts a Unix timestamp in milliseconds, an ISO date string, or a `Date` object.

packages/kumo/src/components/chart/index.ts

@@ -3,7 +3,14 @@ export {
   type TimeseriesChartProps,
   type TimeseriesData,
 } from "./TimeseriesChart";
-export { Chart, type ChartEvents, type ChartProps } from "./EChart";
+
+export {
+  Chart,
+  type ChartEvents,
+  type ChartProps,
+  type KumoChartOption,
+} from "./EChart";
+
 export { ChartLegend } from "./Legend";
 // Re-export color utilities for consumers who need to match chart colors outside of a chart instance
 export { ChartPalette } from "./Color";

packages/kumo/src/index.ts

@@ -215,6 +215,7 @@ export {
   ChartPalette,
   TimeseriesChart,
   ChartLegend,
+  type KumoChartOption,
 } from "./components/chart";
 
 // Sidebar