basalt-ui 1.14.0 → 1.16.0

package/dist/charts/primitives/CartesianChart.js

@@ -0,0 +1,359 @@
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import { GridRows } from "@visx/grid";
+import { Group } from "@visx/group";
+import { scaleLinear, scalePoint } from "@visx/scale";
+import { useMemo, useRef, useState } from "react";
+import { VX } from "../../tokens/index.js";
+import { useChartCursor } from "../hooks/useChartCursor.js";
+import { autoMargin, probeAxisLabels } from "../layout/auto-margin.js";
+import { deriveTooltipRows } from "../series.js";
+import { padAutoLower } from "../utils/domain.js";
+import { fmtAxisDate } from "../utils/format.js";
+import { smartTicks, smartTicksEvery } from "../utils/ticks.js";
+import { AxisBottomDate, AxisLeftNumeric, AxisRightNumeric } from "./Axes.js";
+import { ChartFrame, resolveLegend } from "./ChartFrame.js";
+import { ChartTooltipFloat, TooltipBody, TooltipHeader, TooltipRow } from "./ChartTooltip.js";
+import { Crosshair, SeriesDot } from "./Crosshair.js";
+import { HoverOverlay } from "./HoverOverlay.js";
+import { XZoneRects } from "./XZoneRects.js";
+import { ZoneRects } from "./ZoneRects.js";
+const DEFAULT_TICKS = 5;
+const DEFAULT_AUTO_PAD = 1.1;
+function resolveAxisDomain(cfg, data, series, extraBounds = []) {
+  const domain = cfg?.domain ?? "auto";
+  if (Array.isArray(domain)) return domain;
+  if (typeof domain === "function") return domain(data, series);
+  let min = Infinity;
+  let max = -Infinity;
+  for (const d of data) {
+    for (const s of series) {
+      const v = s.getValue(d);
+      if (v === null) continue;
+      if (v < min) min = v;
+      if (v > max) max = v;
+    }
+  }
+  for (const v of extraBounds) {
+    if (!Number.isFinite(v)) continue;
+    if (v < min) min = v;
+    if (v > max) max = v;
+  }
+  if (min === Infinity) return [0, cfg?.autoMaxFloor ?? 1];
+  const pad = cfg?.autoPad ?? DEFAULT_AUTO_PAD;
+  const ceil = cfg?.autoMinCeil ?? 0;
+  const paddedMax = max > 0 ? max * pad : max < 0 ? max / pad : 0;
+  const upper = Math.max(paddedMax, cfg?.autoMaxFloor ?? -Infinity);
+  const lower = padAutoLower(Math.min(min, ceil), pad);
+  if (lower === upper) return [Math.min(lower, 0), upper === 0 ? 1 : upper * pad];
+  return [lower, upper];
+}
+function CartesianChart({
+  data,
+  chartId,
+  getX,
+  series,
+  y,
+  y2,
+  xTicks,
+  formatX = fmtAxisDate,
+  zones,
+  xZones,
+  refLines,
+  height,
+  aspectRatio,
+  fill,
+  legend,
+  tooltip,
+  margin: marginOverride,
+  cursorValue,
+  ariaLabel,
+  isPending,
+  children
+}) {
+  const [highlighted, setHighlighted] = useState(null);
+  return /* @__PURE__ */ jsx(
+    ChartFrame,
+    {
+      series,
+      chartId,
+      ...height !== void 0 && { height },
+      ...aspectRatio !== void 0 && { aspectRatio },
+      ...fill !== void 0 && { fill },
+      ...ariaLabel !== void 0 && { ariaLabel },
+      ...isPending !== void 0 && { isPending },
+      legend: resolveLegend(legend, { highlighted, onHighlight: setHighlighted }),
+      children: (plot) => /* @__PURE__ */ jsx(
+        CartesianPlot,
+        {
+          data,
+          chartId,
+          getX,
+          series,
+          ...y !== void 0 && { y },
+          ...y2 !== void 0 && { y2 },
+          ...xTicks !== void 0 && { xTicks },
+          formatX,
+          ...zones !== void 0 && { zones },
+          ...xZones !== void 0 && { xZones },
+          ...refLines !== void 0 && { refLines },
+          ...tooltip !== void 0 && { tooltip },
+          ...marginOverride !== void 0 && { marginOverride },
+          ...cursorValue !== void 0 && { cursorValue },
+          ...ariaLabel !== void 0 && { ariaLabel },
+          plot,
+          highlighted,
+          children
+        }
+      )
+    }
+  );
+}
+function CartesianPlot({
+  data,
+  chartId,
+  getX,
+  series,
+  y,
+  y2,
+  xTicks,
+  formatX = fmtAxisDate,
+  zones,
+  xZones,
+  refLines,
+  tooltip,
+  marginOverride,
+  cursorValue,
+  ariaLabel,
+  plot,
+  highlighted,
+  children
+}) {
+  const { hidden } = plot;
+  const visible = useMemo(() => series.filter((s) => !hidden.has(s.key)), [series, hidden]);
+  const leftSeries = useMemo(() => visible.filter((s) => s.axis !== "right"), [visible]);
+  const rightSeries = useMemo(() => visible.filter((s) => s.axis === "right"), [visible]);
+  const keys = useMemo(() => data.map(getX), [data, getX]);
+  const [leftBounds, rightBounds] = useMemo(() => {
+    const left = [];
+    const right = [];
+    for (const z of zones ?? []) (z.axisSide === "right" ? right : left).push(z.from, z.to);
+    for (const l of refLines ?? []) (l.axis === "right" ? right : left).push(l.value);
+    return [left, right];
+  }, [zones, refLines]);
+  const leftDomain = useMemo(
+    () => resolveAxisDomain(y, data, leftSeries, leftBounds),
+    [y, data, leftSeries, leftBounds]
+  );
+  const rightDomain = useMemo(
+    () => y2 === void 0 ? null : resolveAxisDomain(y2, data, rightSeries, rightBounds),
+    [y2, data, rightSeries, rightBounds]
+  );
+  const leftTicks = y?.ticks ?? DEFAULT_TICKS;
+  const rightTicks = y2?.ticks ?? DEFAULT_TICKS;
+  const { labels: leftLabels, format: leftFormat } = useMemo(
+    () => probeAxisLabels({
+      domain: leftDomain,
+      ticks: leftTicks,
+      nice: y?.nice ?? false,
+      ...y?.format !== void 0 && { format: y.format }
+    }),
+    [leftDomain, leftTicks, y?.format, y?.nice]
+  );
+  const { labels: rightLabels, format: rightFormat } = useMemo(
+    () => rightDomain === null ? { labels: [], format: (v) => String(v) } : probeAxisLabels({
+      domain: rightDomain,
+      ticks: rightTicks,
+      nice: y2?.nice ?? false,
+      ...y2?.format !== void 0 && { format: y2.format }
+    }),
+    [rightDomain, rightTicks, y2?.format, y2?.nice]
+  );
+  const xLabels = useMemo(() => keys.map(formatX), [keys, formatX]);
+  const margin = useMemo(
+    () => autoMargin({
+      left: leftLabels,
+      right: rightLabels,
+      bottom: xLabels,
+      ...marginOverride !== void 0 && { override: marginOverride }
+    }),
+    [leftLabels, rightLabels, xLabels, marginOverride]
+  );
+  const xMax = Math.max(plot.width - margin.left - margin.right, 0);
+  const yMax = Math.max(plot.height - margin.top - margin.bottom, 0);
+  const xScale = useMemo(
+    () => scalePoint({ domain: keys, range: [0, xMax], padding: 0.5 }),
+    [keys, xMax]
+  );
+  const yScale = useMemo(
+    () => scaleLinear({
+      domain: leftDomain,
+      range: [yMax, 0],
+      ...y?.nice === true && { nice: true }
+    }),
+    [leftDomain, yMax, y?.nice]
+  );
+  const y2Scale = useMemo(
+    () => rightDomain === null ? null : scaleLinear({
+      domain: rightDomain,
+      range: [yMax, 0],
+      ...y2?.nice === true && { nice: true }
+    }),
+    [rightDomain, yMax, y2?.nice]
+  );
+  const tickValues = useMemo(
+    () => xTicks === void 0 ? smartTicks(keys, xMax) : smartTicksEvery(keys, xTicks),
+    [keys, xMax, xTicks]
+  );
+  const cursor = useChartCursor({
+    data,
+    chartId,
+    getKey: getX,
+    xScale,
+    marginLeft: margin.left
+  });
+  const svgRef = useRef(null);
+  const tooltipEnabled = tooltip !== false;
+  const tooltipCfg = tooltip === false ? void 0 : tooltip;
+  const point = cursor.point;
+  const cursorX = point === null ? null : xScale(getX(point)) ?? null;
+  const badge = tooltipCfg?.label === void 0 || point === null ? null : tooltipCfg.label(point);
+  const tooltipSeries = useMemo(
+    () => visible.map(
+      (s) => s.formatValue === void 0 ? { ...s, formatValue: s.axis === "right" ? rightFormat : leftFormat } : s
+    ),
+    [visible, leftFormat, rightFormat]
+  );
+  const rows = tooltipEnabled && point !== null ? deriveTooltipRows(tooltipSeries, point, leftFormat) : [];
+  const anchorX = tooltipCfg?.follow === false && point !== null && cursorX !== null ? cursorX : null;
+  const svgRect = anchorX === null ? void 0 : svgRef.current?.getBoundingClientRect();
+  const tooltipAnchor = svgRect === void 0 || anchorX === null ? cursor.anchor : { x: svgRect.left + margin.left + anchorX, y: svgRect.top + margin.top };
+  const ctx = {
+    data,
+    visible,
+    hidden,
+    xScale,
+    yScale,
+    y2Scale,
+    xMax,
+    yMax,
+    margin,
+    cursorPoint: point,
+    highlighted
+  };
+  return /* @__PURE__ */ jsxs(Fragment, { children: [
+    /* @__PURE__ */ jsx("svg", { ref: svgRef, width: plot.width, height: plot.height, children: /* @__PURE__ */ jsxs(Group, { left: margin.left, top: margin.top, children: [
+      (y?.grid ?? true) && /* @__PURE__ */ jsx(GridRows, { scale: yScale, width: xMax, stroke: VX.grid, numTicks: leftTicks }),
+      xZones !== void 0 && /* @__PURE__ */ jsx(XZoneRects, { zones: xZones, height: yMax, xScale }),
+      zones !== void 0 && /* @__PURE__ */ jsx(ZoneRects, { zones, width: xMax, leftScale: yScale, rightScale: y2Scale }),
+      children(ctx),
+      refLines?.map((line) => {
+        const scale = line.axis === "right" && y2Scale !== null ? y2Scale : yScale;
+        return /* @__PURE__ */ jsx(
+          "line",
+          {
+            x1: 0,
+            x2: xMax,
+            y1: scale(line.value),
+            y2: scale(line.value),
+            stroke: line.color,
+            strokeWidth: 1,
+            strokeDasharray: line.dashed === true ? VX.dashArray : void 0
+          },
+          `${line.axis ?? "left"}-${line.value}`
+        );
+      }),
+      tooltipEnabled && point !== null && cursorX !== null && /* @__PURE__ */ jsxs(Fragment, { children: [
+        /* @__PURE__ */ jsx(Crosshair, { x: cursorX, top: 0, bottom: yMax }),
+        visible.map((s) => {
+          if (s.mark === "bar") return null;
+          const value = cursorValue === void 0 ? s.getValue(point) : cursorValue(point, s, visible);
+          if (value === null) return null;
+          const scale = s.axis === "right" && y2Scale !== null ? y2Scale : yScale;
+          const marker = s.getMarker?.(point);
+          return /* @__PURE__ */ jsx(
+            SeriesDot,
+            {
+              cx: cursorX,
+              cy: scale(value),
+              color: marker?.color ?? s.color,
+              ...marker?.r !== void 0 && { r: marker.r }
+            },
+            s.key
+          );
+        })
+      ] }),
+      /* @__PURE__ */ jsx(
+        AxisLeftNumeric,
+        {
+          scale: yScale,
+          numTicks: leftTicks,
+          tickFormat: (v) => leftFormat(Number(v))
+        }
+      ),
+      y2Scale !== null && /* @__PURE__ */ jsx(
+        AxisRightNumeric,
+        {
+          scale: y2Scale,
+          left: xMax,
+          numTicks: rightTicks,
+          tickFormat: (v) => rightFormat(Number(v))
+        }
+      ),
+      /* @__PURE__ */ jsx(
+        AxisBottomDate,
+        {
+          top: yMax,
+          scale: xScale,
+          tickValues,
+          tickFormat: (v) => formatX(String(v))
+        }
+      ),
+      /* @__PURE__ */ jsx(
+        HoverOverlay,
+        {
+          width: xMax,
+          height: yMax,
+          onMove: cursor.onPointerMove,
+          onLeave: cursor.onPointerLeave,
+          onKeyDown: cursor.onKeyDown,
+          onBlur: cursor.onBlur,
+          valueMax: Math.max(data.length - 1, 0),
+          ...point !== null && {
+            valueNow: data.indexOf(point),
+            valueText: formatX(getX(point))
+          },
+          ...ariaLabel !== void 0 && { ariaLabel }
+        }
+      )
+    ] }) }),
+    tooltipEnabled && cursor.isSource && point !== null && /* @__PURE__ */ jsxs(ChartTooltipFloat, { anchor: tooltipAnchor, children: [
+      /* @__PURE__ */ jsx(
+        TooltipHeader,
+        {
+          date: getX(point),
+          ...badge !== null && { label: badge.text, labelColor: badge.color }
+        }
+      ),
+      /* @__PURE__ */ jsxs(TooltipBody, { children: [
+        tooltipCfg?.prependRows?.(point, { visible, hidden }),
+        rows.map((row) => /* @__PURE__ */ jsx(
+          TooltipRow,
+          {
+            color: row.color,
+            label: row.label,
+            value: row.value,
+            shape: row.shape,
+            dashed: row.dashed,
+            ...row.strokeWidth !== void 0 && { strokeWidth: row.strokeWidth }
+          },
+          row.key
+        )),
+        tooltipCfg?.extraRows?.(point, { visible, hidden })
+      ] })
+    ] })
+  ] });
+}
+export {
+  CartesianChart,
+  resolveAxisDomain
+};

package/dist/charts/primitives/CartesianChart.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=CartesianChart.test.d.ts.map

package/dist/charts/primitives/CartesianChart.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CartesianChart.test.d.ts","sourceRoot":"","sources":["../../../src/charts/primitives/CartesianChart.test.tsx"],"names":[],"mappings":""}

package/dist/charts/primitives/ChartFrame.d.ts

@@ -12,6 +12,13 @@ export type ChartFrameLegend = {
     /** Hover-dim wiring lifted from the kind — optional. */
     highlighted?: string | null;
     onHighlight?: (key: string | null) => void;
+    /**
+     * Clicking a legend entry hides that series. Defaults to true whenever there is more than one
+     * entry to toggle between — hiding the only series a chart draws is never useful. The hidden
+     * key set reaches the marks through the `children` render prop, so a hidden series leaves the
+     * plot, the tooltip, and the auto domain together (`docs/CHARTS-SPEC.md` §5).
+     */
+    toggle?: boolean;
 };
 export type ChartFrameProps = {
     /** Series identity — drives the derived legend. Pass the SAME array the kind draws + tooltips from. */
@@ -41,11 +48,15 @@ export type ChartFrameProps = {
      * kind composing `ChartFrame` should accept and forward this from its own props.
      */
     ariaLabel?: string;
-    /** Draw the SVG marks given the plot rect that already excludes the legend band. */
-    children: (plot: {
-        width: number;
-        height: number;
-    }) => ReactNode;
+    /** Draw the SVG marks given the plot rect that already excludes the legend band, plus the set
+     * of series keys the legend has toggled off. */
+    children: (plot: PlotRect) => ReactNode;
+};
+/** What `ChartFrame` hands its child: the resolved plot rect plus legend-toggle state. */
+export type PlotRect = {
+    width: number;
+    height: number;
+    hidden: ReadonlySet<string>;
 };
 /** A kind's own hover-dim wiring, merged into the resolved `ChartFrameLegend`. Kinds without
  * per-series highlight state (single-series `ZonedLine`, `DualPanel`) omit this. */

package/dist/charts/primitives/ChartFrame.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ChartFrame.d.ts","sourceRoot":"","sources":["../../../src/charts/primitives/ChartFrame.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAiB,SAAS,EAAE,MAAM,OAAO,CAAA;AAGrD,OAAO,KAAK,EAAE,iBAAiB,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,WAAW,CAAA;AAOhF;0EAC0E;AAC1E,MAAM,MAAM,gBAAgB,GAAG;IAC7B,wBAAwB;IACxB,SAAS,CAAC,EAAE,eAAe,CAAA;IAC3B,uDAAuD;IACvD,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,4DAA4D;IAC5D,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,wDAAwD;IACxD,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC3B,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,CAAA;CAC3C,CAAA;AAED,MAAM,MAAM,eAAe,GAAG;IAC5B,uGAAuG;IACvG,MAAM,EAAE,SAAS,WAAW,EAAE,CAAA;IAC9B,8FAA8F;IAC9F,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,qFAAqF;IACrF,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,uFAAuF;IACvF,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,iGAAiG;IACjG,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,6FAA6F;IAC7F,MAAM,CAAC,EAAE,gBAAgB,GAAG,KAAK,CAAA;IACjC;;;;;OAKG;IACH,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,oFAAoF;IACpF,QAAQ,EAAE,CAAC,IAAI,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,KAAK,SAAS,CAAA;CACjE,CAAA;AAcD;oFACoF;AACpF,MAAM,MAAM,qBAAqB,GAAG;IAClC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;IAC1B,WAAW,EAAE,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,CAAA;CAC1C,CAAA;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,iBAAiB,GAAG,KAAK,GAAG,SAAS,EAC7C,KAAK,CAAC,EAAE,qBAAqB,GAC5B,gBAAgB,GAAG,KAAK,CAQ1B;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,UAAU,CAAC,EACzB,MAAM,EACN,MAAM,EACN,WAAW,EACX,IAAY,EACZ,QAA4B,EAC5B,OAAO,EACP,MAAW,EACX,SAAS,EACT,SAAiB,EACjB,QAAQ,GACT,EAAE,eAAe,GAAG,SAAS,CAmD7B"}
+{"version":3,"file":"ChartFrame.d.ts","sourceRoot":"","sources":["../../../src/charts/primitives/ChartFrame.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAiB,SAAS,EAAE,MAAM,OAAO,CAAA;AAIrD,OAAO,KAAK,EAAE,iBAAiB,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,WAAW,CAAA;AAOhF;0EAC0E;AAC1E,MAAM,MAAM,gBAAgB,GAAG;IAC7B,wBAAwB;IACxB,SAAS,CAAC,EAAE,eAAe,CAAA;IAC3B,uDAAuD;IACvD,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,4DAA4D;IAC5D,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,wDAAwD;IACxD,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC3B,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,CAAA;IAC1C;;;;;OAKG;IACH,MAAM,CAAC,EAAE,OAAO,CAAA;CACjB,CAAA;AAED,MAAM,MAAM,eAAe,GAAG;IAC5B,uGAAuG;IACvG,MAAM,EAAE,SAAS,WAAW,EAAE,CAAA;IAC9B,8FAA8F;IAC9F,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,qFAAqF;IACrF,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,uFAAuF;IACvF,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,iGAAiG;IACjG,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,6FAA6F;IAC7F,MAAM,CAAC,EAAE,gBAAgB,GAAG,KAAK,CAAA;IACjC;;;;;OAKG;IACH,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB;oDACgD;IAChD,QAAQ,EAAE,CAAC,IAAI,EAAE,QAAQ,KAAK,SAAS,CAAA;CACxC,CAAA;AAED,0FAA0F;AAC1F,MAAM,MAAM,QAAQ,GAAG;IACrB,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,WAAW,CAAC,MAAM,CAAC,CAAA;CAC5B,CAAA;AAcD;oFACoF;AACpF,MAAM,MAAM,qBAAqB,GAAG;IAClC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;IAC1B,WAAW,EAAE,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,CAAA;CAC1C,CAAA;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,iBAAiB,GAAG,KAAK,GAAG,SAAS,EAC7C,KAAK,CAAC,EAAE,qBAAqB,GAC5B,gBAAgB,GAAG,KAAK,CAS1B;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,UAAU,CAAC,EACzB,MAAM,EACN,MAAM,EACN,WAAW,EACX,IAAY,EACZ,QAA4B,EAC5B,OAAO,EACP,MAAW,EACX,SAAS,EACT,SAAiB,EACjB,QAAQ,GACT,EAAE,eAAe,GAAG,SAAS,CAsE7B"}

package/dist/charts/primitives/ChartFrame.js

@@ -1,4 +1,5 @@
 import { jsx, jsxs } from "react/jsx-runtime";
+import { useCallback, useState } from "react";
 import { useChartSize } from "../hooks/useChartSize.js";
 import { deriveLegend } from "../series.js";
 import { ChartLegend } from "./ChartLegend.js";
@@ -21,6 +22,7 @@ function resolveLegend(config, hover) {
     placement: config?.placement ?? "bottom",
     ...config?.groups !== void 0 && { groups: config.groups },
     ...config?.maxRows !== void 0 && { maxRows: config.maxRows },
+    ...config?.toggle !== void 0 && { toggle: config.toggle },
     ...hover !== void 0 && { highlighted: hover.highlighted, onHighlight: hover.onHighlight }
   };
 }
@@ -38,6 +40,15 @@ function ChartFrame({
 }) {
   const { ref: containerRef, width: containerW, height: containerH } = useChartSize();
   const { ref: legendRef, width: legendW, height: legendH } = useChartSize();
+  const [hidden, setHidden] = useState(() => /* @__PURE__ */ new Set());
+  const toggleKey = useCallback((key) => {
+    setHidden((prev) => {
+      const next = new Set(prev);
+      if (next.has(key)) next.delete(key);
+      else next.add(key);
+      return next;
+    });
+  }, []);
   const placement = legend === false ? "bottom" : legend.placement ?? "bottom";
   const vertical = placement === "left" || placement === "right";
   const legendVisible = legend !== false && !isPending;
@@ -48,11 +59,15 @@ function ChartFrame({
     width: Math.max(containerW - sideLegendWidth, minWidth),
     height: resolvedHeight - topBottomLegendHeight
   };
+  const legendItems = legend === false ? [] : deriveLegend(series);
+  const togglable = legend !== false && (legend.toggle ?? legendItems.length > 1);
   const legendNode = legend === false || isPending ? null : /* @__PURE__ */ jsx("div", { ref: legendRef, style: legendWrapperStyle(vertical), children: /* @__PURE__ */ jsx(
     ChartLegend,
     {
-      items: deriveLegend(series),
+      items: legendItems,
       placement,
+      hidden,
+      ...togglable && { onToggle: toggleKey },
       ...chartId !== void 0 && { chartId },
       ...legend.groups !== void 0 && { groups: legend.groups },
       ...legend.maxRows !== void 0 && { maxRows: legend.maxRows },
@@ -69,7 +84,7 @@ function ChartFrame({
       ...isPending && { "aria-busy": "true" },
       children: [
         legendNode !== null && (placement === "top" || placement === "left") && legendNode,
-        plot.width > 0 && plot.height > 0 && (isPending ? /* @__PURE__ */ jsx(ChartPending, { width: plot.width, height: plot.height }) : children(plot)),
+        plot.width > 0 && plot.height > 0 && (isPending ? /* @__PURE__ */ jsx(ChartPending, { width: plot.width, height: plot.height }) : children({ ...plot, hidden })),
         legendNode !== null && (placement === "bottom" || placement === "right") && legendNode
       ]
     }

package/dist/charts/primitives/ChartLegend.d.ts

@@ -10,11 +10,17 @@ export type LegendEntry = {
     dashed?: boolean;
     /** bar swatch opacity — honored instead of a hardcoded value, so it cannot lie about the fill. */
     fillOpacity?: number;
+    /** line/splitLine swatch stroke opacity — parity with `fillOpacity` above, so a dimmed
+     * companion line's swatch cannot lie about its own opacity either. */
+    strokeOpacity?: number;
     /** Drives `groups` rendering (series → hairline divider → overlay → reference). */
     role?: SeriesRole;
     /** Companions folded under this entry via `parent` (`deriveLegend`) — rendered as compact,
      * subordinate sub-entries beside the parent's label instead of vanishing. */
     children?: LegendEntry[];
+    /** Short qualifier rendered after the label in muted text — e.g. a flat-at-zero series that is
+     * invisible in the plot. */
+    note?: string;
 };
 /**
  * Shared legend for all non-sparkline charts. `highlighted`/`onHighlight` are optional — omit for
@@ -23,11 +29,19 @@ export type LegendEntry = {
  * reference bands instead of one flat smear. `maxRows` caps the number of rendered entries and
  * rolls the remainder into a `+N more` chip (row-accurate wrap measurement is `ChartFrame`'s job —
  * this is an entry-count cap, a deliberate simplification until that primitive lands).
+ *
+ * `onToggle` makes an entry a real toggle: clicking it hides the series in the plot, the tooltip,
+ * and the auto y-domain together (`ChartFrame` owns the `hidden` set — see `docs/CHARTS-SPEC.md`
+ * §5). Omit it for a static legend; a hidden entry is announced via `aria-pressed`.
  */
-export declare function ChartLegend({ items, highlighted, onHighlight, chartId, placement, groups, maxRows, }: {
+export declare function ChartLegend({ items, highlighted, onHighlight, hidden, onToggle, chartId, placement, groups, maxRows, }: {
     items: LegendEntry[];
     highlighted?: string | null;
     onHighlight?: (key: string | null) => void;
+    /** Keys currently toggled off. */
+    hidden?: ReadonlySet<string>;
+    /** Present = entries are clickable toggles. */
+    onToggle?: (key: string) => void;
     chartId?: string;
     placement?: LegendPlacement;
     groups?: boolean;

package/dist/charts/primitives/ChartLegend.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ChartLegend.d.ts","sourceRoot":"","sources":["../../../src/charts/primitives/ChartLegend.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,WAAW,CAAA;AAE5D,MAAM,MAAM,WAAW,GAAG;IACxB,GAAG,EAAE,MAAM,CAAA;IACX,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,MAAM,CAAA;IACb,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,KAAK,CAAC,EAAE,MAAM,GAAG,KAAK,GAAG,OAAO,GAAG,WAAW,CAAA;IAC9C,mFAAmF;IACnF,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,kGAAkG;IAClG,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,mFAAmF;IACnF,IAAI,CAAC,EAAE,UAAU,CAAA;IACjB;iFAC6E;IAC7E,QAAQ,CAAC,EAAE,WAAW,EAAE,CAAA;CACzB,CAAA;AA+MD;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,EAC1B,KAAK,EACL,WAAkB,EAClB,WAAW,EACX,OAAY,EACZ,SAAoB,EACpB,MAAc,EACd,OAAO,GACR,EAAE;IACD,KAAK,EAAE,WAAW,EAAE,CAAA;IACpB,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC3B,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,CAAA;IAC1C,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,SAAS,CAAC,EAAE,eAAe,CAAA;IAC3B,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB,+BAkDA"}
+{"version":3,"file":"ChartLegend.d.ts","sourceRoot":"","sources":["../../../src/charts/primitives/ChartLegend.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,WAAW,CAAA;AAE5D,MAAM,MAAM,WAAW,GAAG;IACxB,GAAG,EAAE,MAAM,CAAA;IACX,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,MAAM,CAAA;IACb,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,KAAK,CAAC,EAAE,MAAM,GAAG,KAAK,GAAG,OAAO,GAAG,WAAW,CAAA;IAC9C,mFAAmF;IACnF,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,kGAAkG;IAClG,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;0EACsE;IACtE,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,mFAAmF;IACnF,IAAI,CAAC,EAAE,UAAU,CAAA;IACjB;iFAC6E;IAC7E,QAAQ,CAAC,EAAE,WAAW,EAAE,CAAA;IACxB;gCAC4B;IAC5B,IAAI,CAAC,EAAE,MAAM,CAAA;CACd,CAAA;AAgOD;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,EAC1B,KAAK,EACL,WAAkB,EAClB,WAAW,EACX,MAAkB,EAClB,QAAQ,EACR,OAAY,EACZ,SAAoB,EACpB,MAAc,EACd,OAAO,GACR,EAAE;IACD,KAAK,EAAE,WAAW,EAAE,CAAA;IACpB,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC3B,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,CAAA;IAC1C,kCAAkC;IAClC,MAAM,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAA;IAC5B,+CAA+C;IAC/C,QAAQ,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAA;IAChC,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,SAAS,CAAC,EAAE,eAAe,CAAA;IAC3B,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB,+BAmEA"}

package/dist/charts/primitives/ChartLegend.js

@@ -19,6 +19,7 @@ const LEGEND_ITEM_BUTTON = {
   textAlign: "inherit"
 };
 const GROUP_ORDER = ["series", "overlay", "reference"];
+const NO_HIDDEN = /* @__PURE__ */ new Set();
 const roleOf = (item) => item.role ?? "series";
 function orderEntries(items, groups) {
   if (!groups) return { entries: items, dividerAfter: /* @__PURE__ */ new Set() };
@@ -69,6 +70,7 @@ function LegendSwatch({ item, idPrefix }) {
           y2: 7,
           stroke: item.color,
           strokeWidth: item.strokeWidth ?? 2.5,
+          strokeOpacity: item.strokeOpacity ?? 1,
           strokeDasharray: item.dashed ? VX.dashArray : void 0
         }
       ),
@@ -81,6 +83,7 @@ function LegendSwatch({ item, idPrefix }) {
           y2: 7,
           stroke: item.secondColor,
           strokeWidth: item.strokeWidth ?? 2.5,
+          strokeOpacity: item.strokeOpacity ?? 1,
           strokeDasharray: item.dashed ? VX.dashArray : void 0
         }
       )
@@ -123,11 +126,15 @@ function LegendSwatch({ item, idPrefix }) {
       y2: 3,
       stroke: item.color,
       strokeWidth: item.strokeWidth ?? 3,
+      strokeOpacity: item.strokeOpacity ?? 1,
       strokeLinecap: "round",
       strokeDasharray: item.dashed ? VX.dashArray : void 0
     }
   ) });
 }
+const LEGEND_NOTE_STYLE = {
+  opacity: 0.75
+};
 const LEGEND_CHILD_STYLE = {
   display: "flex",
   alignItems: "center",
@@ -162,6 +169,7 @@ function LegendChildSwatch({ item }) {
       y2: 5,
       stroke: item.color,
       strokeWidth: item.strokeWidth ?? 2,
+      strokeOpacity: item.strokeOpacity ?? 1,
       strokeDasharray: item.dashed ? VX.dashArray : void 0
     }
   ) });
@@ -169,13 +177,16 @@ function LegendChildSwatch({ item }) {
 function LegendChild({ item }) {
   return /* @__PURE__ */ jsxs("span", { style: LEGEND_CHILD_STYLE, children: [
     /* @__PURE__ */ jsx(LegendChildSwatch, { item }),
-    /* @__PURE__ */ jsx("span", { children: item.label })
+    /* @__PURE__ */ jsx("span", { children: item.label }),
+    item.note ? /* @__PURE__ */ jsx("span", { children: item.note }) : null
   ] });
 }
 function ChartLegend({
   items,
   highlighted = null,
   onHighlight,
+  hidden = NO_HIDDEN,
+  onToggle,
   chartId = "",
   placement = "bottom",
   groups = false,
@@ -186,6 +197,10 @@ function ChartLegend({
     if (key !== void 0) onHighlight?.(key);
   };
   const handleLeave = () => onHighlight?.(null);
+  const handleToggle = (e) => {
+    const key = e.currentTarget.dataset["legendKey"];
+    if (key !== void 0) onToggle?.(key);
+  };
   const idPrefix = chartId ? `${chartId}-` : "";
   const vertical = placement === "left" || placement === "right";
   const { entries, dividerAfter } = orderEntries(items, groups);
@@ -199,11 +214,17 @@ function ChartLegend({
         {
           type: "button",
           "data-legend-key": item.key,
-          "aria-label": item.label,
+          "aria-label": item.note ? `${item.label} \u2014 ${item.note}` : item.label,
+          ...onToggle !== void 0 && { "aria-pressed": !hidden.has(item.key) },
           style: {
             ...LEGEND_ITEM_BUTTON,
-            opacity: highlighted === null || highlighted === item.key ? 1 : 0.3
+            cursor: onToggle === void 0 ? "default" : "pointer",
+            // Toggled-off wins over hover-dimming: a hidden series must read as hidden even while
+            // it is the one being hovered.
+            opacity: hidden.has(item.key) ? 0.35 : highlighted === null || highlighted === item.key ? 1 : 0.3,
+            textDecoration: hidden.has(item.key) ? "line-through" : "none"
           },
+          ...onToggle !== void 0 && { onClick: handleToggle },
           onMouseEnter: handleEnter,
           onMouseLeave: handleLeave,
           onFocus: handleEnter,
@@ -211,6 +232,7 @@ function ChartLegend({
           children: [
             /* @__PURE__ */ jsx(LegendSwatch, { item, idPrefix }),
             /* @__PURE__ */ jsx("span", { children: item.label }),
+            item.note ? /* @__PURE__ */ jsx("span", { style: LEGEND_NOTE_STYLE, children: item.note }) : null,
             item.children?.map((child) => /* @__PURE__ */ jsx(LegendChild, { item: child }, child.key))
           ]
         },

package/dist/charts/primitives/ChartLegend.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=ChartLegend.test.d.ts.map

package/dist/charts/primitives/ChartLegend.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ChartLegend.test.d.ts","sourceRoot":"","sources":["../../../src/charts/primitives/ChartLegend.test.tsx"],"names":[],"mappings":""}

package/dist/charts/primitives/ChartTooltip.d.ts

@@ -1,19 +1,4 @@
-import type { CSSProperties, ReactNode, RefObject } from 'react';
-/** Theme-aware tooltip container styles — use with useChartTooltip(). */
-export declare function useTooltipStyles(): CSSProperties;
-/**
- * Outer tooltip shell. Renders nothing when tip is null. Renders to `document.body` via a
- * portal, so it may be authored anywhere in the tree, including inside `<svg>`.
- */
-export declare function ChartTooltip({ tip, tooltipRef, styles, children, }: {
-    tip: {
-        x: number;
-        y: number;
-    } | null;
-    tooltipRef?: RefObject<HTMLDivElement | null>;
-    styles: CSSProperties;
-    children: ReactNode;
-}): import("react").ReactPortal | null;
+import type { ReactNode } from 'react';
 /** Tooltip header — shows formatted date + optional right-aligned label with color. */
 export declare function TooltipHeader({ date, label, labelColor, }: {
     date: string;
@@ -34,4 +19,19 @@ export declare function TooltipRow({ color, label, value, valueColor, shape, str
 export declare function TooltipBody({ children }: {
     children: ReactNode;
 }): import("react").JSX.Element;
+/**
+ * Floating tooltip positioned against a viewport-space anchor, with flip + clamp handled once for
+ * every chart instead of per call site (this used to be recomputed inside each chart's own `useChartTooltip`, and only for
+ * charts that remembered to use it).
+ *
+ * The box is measured after mount via `useLayoutEffect`, so the first paint of a given tooltip is
+ * hidden rather than misplaced — a tooltip that flashes at the wrong corner reads as a bug.
+ */
+export declare function ChartTooltipFloat({ anchor, children, }: {
+    anchor: {
+        x: number;
+        y: number;
+    } | null;
+    children: ReactNode;
+}): import("react").ReactPortal | null;
 //# sourceMappingURL=ChartTooltip.d.ts.map

package/dist/charts/primitives/ChartTooltip.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ChartTooltip.d.ts","sourceRoot":"","sources":["../../../src/charts/primitives/ChartTooltip.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAsBhE,yEAAyE;AACzE,wBAAgB,gBAAgB,IAAI,aAAa,CAEhD;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,EAC3B,GAAG,EACH,UAAU,EACV,MAAM,EACN,QAAQ,GACT,EAAE;IACD,GAAG,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAA;IACpC,UAAU,CAAC,EAAE,SAAS,CAAC,cAAc,GAAG,IAAI,CAAC,CAAA;IAC7C,MAAM,EAAE,aAAa,CAAA;IACrB,QAAQ,EAAE,SAAS,CAAA;CACpB,sCAeA;AAED,uFAAuF;AACvF,wBAAgB,aAAa,CAAC,EAC5B,IAAI,EACJ,KAAK,EACL,UAAU,GACX,EAAE;IACD,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB,+BAoCA;AAED,4CAA4C;AAC5C,wBAAgB,UAAU,CAAC,EACzB,KAAK,EACL,KAAK,EACL,KAAK,EACL,UAAU,EACV,KAAK,EACL,WAAW,EACX,MAAM,GACP,EAAE;IACD,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,MAAM,CAAA;IACb,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,KAAK,CAAC,EAAE,KAAK,GAAG,MAAM,GAAG,KAAK,CAAA;IAC9B,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,uEAAuE;IACvE,MAAM,CAAC,EAAE,OAAO,CAAA;CACjB,+BA0CA;AAED,wBAAgB,WAAW,CAAC,EAAE,QAAQ,EAAE,EAAE;IAAE,QAAQ,EAAE,SAAS,CAAA;CAAE,+BAEhE"}
+{"version":3,"file":"ChartTooltip.d.ts","sourceRoot":"","sources":["../../../src/charts/primitives/ChartTooltip.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAiB,SAAS,EAAE,MAAM,OAAO,CAAA;AAuBrD,uFAAuF;AACvF,wBAAgB,aAAa,CAAC,EAC5B,IAAI,EACJ,KAAK,EACL,UAAU,GACX,EAAE;IACD,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB,+BAoCA;AAED,4CAA4C;AAC5C,wBAAgB,UAAU,CAAC,EACzB,KAAK,EACL,KAAK,EACL,KAAK,EACL,UAAU,EACV,KAAK,EACL,WAAW,EACX,MAAM,GACP,EAAE;IACD,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,MAAM,CAAA;IACb,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,KAAK,CAAC,EAAE,KAAK,GAAG,MAAM,GAAG,KAAK,CAAA;IAC9B,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,uEAAuE;IACvE,MAAM,CAAC,EAAE,OAAO,CAAA;CACjB,+BA0CA;AAED,wBAAgB,WAAW,CAAC,EAAE,QAAQ,EAAE,EAAE;IAAE,QAAQ,EAAE,SAAS,CAAA;CAAE,+BAEhE;AAOD;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,EAChC,MAAM,EACN,QAAQ,GACT,EAAE;IACD,MAAM,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAA;IACvC,QAAQ,EAAE,SAAS,CAAA;CACpB,sCA4CA"}