@pharos-ds/charts 0.0.0-stage → 1.0.10

package/dist/ChartTooltip.d.ts

@@ -0,0 +1,46 @@
+import { type ReactNode } from 'react';
+import { type TooltipSeriesValue } from './tooltip';
+import type { SeriesDef } from './types';
+export type ChartTooltipPlacement = 'auto' | 'right' | 'left' | 'top';
+export interface ChartTooltipProps {
+    /**
+     * Series definitions — used to map the hovered datum to per-series rows.
+     * When rendered via `<Chart tooltip />`, Chart injects this automatically.
+     * When composing directly, pass the same `series` array you gave Chart.
+     */
+    series?: readonly SeriesDef[];
+    /**
+     * Custom render function. Receives the x-value and one row per visible series.
+     * Returning `null` hides the card while still rendering the band highlight + dots.
+     */
+    render?: (xValue: unknown, seriesValues: TooltipSeriesValue[]) => ReactNode;
+    /**
+     * Whether to draw a hover indicator at the focused x-position.
+     * Picks the right shape automatically:
+     * - **band-highlight rect** when the chart includes bar series on a band scale
+     * - **vertical crosshair line** for line / area / dot charts
+     *
+     * Default: `true`.
+     */
+    hoverIndicator?: boolean;
+    /**
+     * Whether to draw a hover dot at each series' point (skipped for bars).
+     * Default: `true`.
+     */
+    showHoverDots?: boolean;
+    /**
+     * Card placement relative to the hovered point:
+     * - `'auto'` (default): right of the point, flips to left if it would overflow
+     * - `'right'` / `'left'` / `'top'`: pinned position
+     */
+    placement?: ChartTooltipPlacement;
+}
+/**
+ * Composable grouped tooltip for Chart.
+ *
+ * Subscribes to the chart's pointer event stream and only re-renders when the
+ * hovered data index changes (not on every pointer move). Card position is
+ * updated imperatively via a ref to keep pointer-move cost ~free.
+ */
+export declare function ChartTooltip({ series, render, hoverIndicator, showHoverDots, placement, }: ChartTooltipProps): import("react").JSX.Element;
+//# sourceMappingURL=ChartTooltip.d.ts.map

package/dist/ChartTooltip.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ChartTooltip.d.ts","sourceRoot":"","sources":["../src/ChartTooltip.tsx"],"names":[],"mappings":"AAkCA,OAAO,EAOL,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AAaf,OAAO,EAGL,KAAK,kBAAkB,EACxB,MAAM,WAAW,CAAC;AACnB,OAAO,KAAK,EAAC,SAAS,EAAoB,MAAM,SAAS,CAAC;AAG1D,MAAM,MAAM,qBAAqB,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,KAAK,CAAC;AAEtE,MAAM,WAAW,iBAAiB;IAChC;;;;OAIG;IACH,MAAM,CAAC,EAAE,SAAS,SAAS,EAAE,CAAC;IAC9B;;;OAGG;IACH,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,YAAY,EAAE,kBAAkB,EAAE,KAAK,SAAS,CAAC;IAC5E;;;;;;;OAOG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;;;OAIG;IACH,SAAS,CAAC,EAAE,qBAAqB,CAAC;CACnC;AA2DD;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,EAC3B,MAAW,EACX,MAAM,EACN,cAAqB,EACrB,aAAoB,EACpB,SAAkB,GACnB,EAAE,iBAAiB,+BA0RnB"}

package/dist/ChartTooltip.js

@@ -0,0 +1,330 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file ChartTooltip.tsx
+ * @output Grouped chart tooltip — shows all series values at the hovered x-position.
+ *         Composable: drop into `<Chart tooltip>` or render directly inside a chart
+ *         to take full control of props.
+ * @position Reads from ChartContext — must render inside an <Chart>.
+ *
+ * Pointer-only: the card is portaled with `pointer-events: none` and holds no
+ * focusable content, so it never traps keyboard focus. Keyboard/screen-reader
+ * users get the same values from the chart's hidden data table instead.
+ *
+ * In a horizontal chart the tooltip renders in the vertical plot space (Chart
+ * wraps it in the same transpose as the marks), so only the screen position of
+ * the card needs to know about `orientation`.
+ *
+ * @example
+ * ```
+ * // Default — declarative on Chart
+ * <Chart tooltip />
+ *
+ * // Custom render function via Chart prop
+ * <Chart tooltip={{render: (x, rows) => <MyCard x={x} rows={rows} />}} />
+ *
+ * // Composable — drop into the chart's children for full control
+ * <Chart>
+ *   <ChartTooltip hoverIndicator={false} placement="top" />
+ * </Chart>
+ * ```
+ */
+
+'use client';
+
+import { memo, useState, useEffect, useMemo, useRef, useCallback } from 'react';
+import { createPortal } from 'react-dom';
+import * as stylex from '@stylexjs/stylex';
+import '@pharos-ds/core/theme/tokens.stylex';
+import { colorVars, radiusVars, shadowVars, spacingVars } from '@pharos-ds/core/theme/tokens.stylex';
+import { Text } from '@pharos-ds/core';
+import { VStack, HStack } from '@pharos-ds/core';
+import { useChart } from "./ChartContext.js";
+import { ChartSwatch, swatchVariantForType } from "./ChartSwatch.js";
+import { deriveTooltipSeriesValues, shouldRenderHoverDot } from "./tooltip.js";
+import { isBandScale, xPixel } from "./utils.js";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+/** Default tooltip body — used when `render` is not provided. */
+const DefaultTooltipContent = /*#__PURE__*/memo(function DefaultTooltipContent({
+  xValue,
+  rows
+}) {
+  return /*#__PURE__*/_jsxs(VStack, {
+    gap: 1,
+    children: [/*#__PURE__*/_jsx(Text, {
+      type: "body",
+      weight: "semibold",
+      children: String(xValue)
+    }), rows.length === 1 ? /*#__PURE__*/_jsx(Text, {
+      type: "supporting",
+      children: String(rows[0].value)
+    }) : /*#__PURE__*/_jsx(VStack, {
+      gap: 1,
+      children: rows.map((row, i) => /*#__PURE__*/_jsxs(HStack, {
+        gap: 2,
+        vAlign: "center",
+        children: [/*#__PURE__*/_jsx(ChartSwatch, {
+          color: row.color,
+          variant: swatchVariantForType(row.type)
+        }), /*#__PURE__*/_jsx(Text, {
+          type: "supporting",
+          children: row.label
+        }), /*#__PURE__*/_jsx(Text, {
+          type: "supporting",
+          weight: "semibold",
+          children: String(row.value)
+        })]
+      }, `${row.key}-${i}`))
+    })]
+  });
+});
+
+/**
+ * Composable grouped tooltip for Chart.
+ *
+ * Subscribes to the chart's pointer event stream and only re-renders when the
+ * hovered data index changes (not on every pointer move). Card position is
+ * updated imperatively via a ref to keep pointer-move cost ~free.
+ */
+export function ChartTooltip({
+  series = [],
+  render,
+  hoverIndicator = true,
+  showHoverDots = true,
+  placement = 'auto'
+}) {
+  const {
+    data,
+    xKey,
+    resolved,
+    onPointer,
+    svgRef,
+    margin,
+    xScale,
+    width,
+    height,
+    orientation
+  } = useChart();
+  const isHorizontal = orientation === 'horizontal';
+  const [hoveredIndex, setHoveredIndex] = useState(null);
+  const cardRef = useRef(null);
+  // Whether the card is currently suppressed (no content, or a custom `render`
+  // opted out by returning null). positionCard reads this so a same-index
+  // pointer move — which repositions the card without a React commit — can't
+  // re-reveal a card the visibility effect below has hidden.
+  const cardHiddenRef = useRef(false);
+
+  // Stable Set of resolved series keys — used by deriveTooltipSeriesValues.
+  // Recomputed only when the resolved map identity changes (per layout pass).
+  const resolvedKeys = useMemo(() => new Set(resolved.keys()), [resolved]);
+
+  // ─── Card positioning ──────────────────────────────────────────────────
+  // Imperative — the card is portaled, and we don't want pointer-move to
+  // trigger React renders.
+  const positionCard = useCallback(e => {
+    const card = cardRef.current;
+    const svg = svgRef.current;
+    if (!card) {
+      return;
+    }
+    if (!svg || !e.nearest || cardHiddenRef.current) {
+      card.style.display = 'none';
+      return;
+    }
+    const svgRect = svg.getBoundingClientRect();
+    const cardWidth = card.offsetWidth;
+    const cardHeight = card.offsetHeight;
+    // Plot space → screen. Horizontal charts are transposed: the category
+    // (px) runs down the y-axis and the value end of the mark (py) maps to
+    // x = plot height − py, so the card sits beside the hovered row.
+    const screenX = isHorizontal ? svgRect.left + margin.left + (Number.isFinite(e.nearest.py) ? height - e.nearest.py : 0) : svgRect.left + margin.left + e.nearest.px;
+    const screenY = isHorizontal ? svgRect.top + margin.top + e.nearest.px - cardHeight / 2 : svgRect.top + margin.top;
+    const viewportWidth = window.innerWidth;
+    const viewportHeight = window.innerHeight;
+    const gap = 8;
+    let x;
+    let y = screenY;
+    switch (placement) {
+      case 'left':
+        x = screenX - cardWidth - gap;
+        break;
+      case 'right':
+        x = screenX + gap;
+        break;
+      case 'top':
+        x = screenX - cardWidth / 2;
+        y = screenY - cardHeight - gap;
+        break;
+      case 'auto':
+      default:
+        {
+          const rightX = screenX + gap;
+          x = rightX + cardWidth > viewportWidth ? screenX - cardWidth - gap : rightX;
+        }
+    }
+
+    // Clamp to the viewport so the card never clips off-screen — it's
+    // portaled and position:fixed, so this keeps it fully visible for every
+    // placement (pinned placements and the near-edge `auto` flip alike).
+    x = Math.max(gap, Math.min(x, viewportWidth - cardWidth - gap));
+    y = Math.max(gap, Math.min(y, viewportHeight - cardHeight - gap));
+    card.style.left = `${x}px`;
+    card.style.top = `${y}px`;
+    card.style.display = 'block';
+  }, [svgRef, margin, placement, isHorizontal, height]);
+
+  // ─── Subscribe to pointer events ───────────────────────────────────────
+  useEffect(() => {
+    let currentIndex = null;
+    const unsub = onPointer(e => {
+      const newIndex = e.nearest?.dataIndex ?? null;
+      if (newIndex !== currentIndex) {
+        currentIndex = newIndex;
+        // Optimistically treat the new index as showable; the visibility effect
+        // re-hides it after commit if there's no content (e.g. custom `render`
+        // returned null). This keeps the card appearing on the first move.
+        cardHiddenRef.current = false;
+        setHoveredIndex(newIndex);
+      }
+      positionCard(e);
+    });
+    return unsub;
+  }, [onPointer, positionCard]);
+
+  // ─── Derived data ──────────────────────────────────────────────────────
+  const datum = hoveredIndex != null ? data[hoveredIndex] : undefined;
+  const xValue = datum?.[xKey];
+  const seriesValues = useMemo(() => deriveTooltipSeriesValues(series, datum, resolvedKeys), [series, datum, resolvedKeys]);
+
+  // Hover dots — read from the resolved map at the hovered index.
+  const dots = useMemo(() => {
+    if (!showHoverDots || hoveredIndex == null) {
+      return null;
+    }
+    const elements = [];
+    for (const s of series) {
+      if (!shouldRenderHoverDot(s.type)) {
+        continue;
+      }
+      const points = s._uid ? resolved.get(s._uid) : undefined;
+      const point = points?.find(p => p.dataIndex === hoveredIndex);
+      // A resolved point exists at every index, but its coordinates are NaN when
+      // this series' value here is missing/non-finite (the mark itself filters
+      // these at render time — mirror that so we never emit cx/cy="NaN").
+      if (!point || !Number.isFinite(point.px) || !Number.isFinite(point.py)) {
+        continue;
+      }
+      elements.push(/*#__PURE__*/_jsx("circle", {
+        cx: point.px,
+        cy: point.py,
+        r: 4,
+        fill: "var(--color-background-surface)",
+        stroke: s.color ?? s._resolvedColor ?? 'var(--color-border-emphasized)',
+        strokeWidth: 2,
+        pointerEvents: "none"
+      }, s._uid));
+    }
+    return elements;
+  }, [showHoverDots, hoveredIndex, series, resolved]);
+
+  // Hover indicator — band-highlight rect for bar charts, vertical crosshair
+  // line for line/area charts. Same source-of-truth (hoveredIndex), distinct
+  // visual idioms picked automatically based on the series mix.
+  const hoverIndicatorElement = useMemo(() => {
+    if (!hoverIndicator || hoveredIndex == null) {
+      return null;
+    }
+    const hoveredDatum = data[hoveredIndex];
+    const xv = hoveredDatum?.[xKey];
+    if (hoveredDatum == null || xv == null) {
+      return null;
+    }
+    const hasBars = series.some(s => s.type === 'bar');
+
+    // Bar charts on a band scale → soft column highlight.
+    if (hasBars && isBandScale(xScale)) {
+      const x = xScale(String(xv)) ?? 0;
+      const bw = xScale.bandwidth();
+      const pad = 8;
+      const rectX = Math.max(0, x - pad);
+      const rectRight = Math.min(width, x + bw + pad);
+      const rectWidth = rectRight - rectX;
+      // Plot-space "top" is the display's right edge when horizontal.
+      const topPad = Math.min(pad, isHorizontal ? margin.right : margin.top);
+      return /*#__PURE__*/_jsx("rect", {
+        x: rectX,
+        y: -topPad,
+        width: rectWidth,
+        height: height + topPad,
+        fill: "currentColor",
+        opacity: 0.06,
+        rx: 4,
+        pointerEvents: "none"
+      });
+    }
+
+    // Line / area / dot charts → vertical crosshair through the point
+    // (band-center or linear position, resolved by the shared helper).
+    const px = xPixel(hoveredDatum, xKey, xScale);
+    // xPixel returns NaN for a non-finite x on a linear scale; skip rather than
+    // emit x1/x2="NaN". (The band branch above is always finite via `?? 0`.)
+    if (!Number.isFinite(px)) {
+      return null;
+    }
+    return /*#__PURE__*/_jsx("line", {
+      x1: px,
+      x2: px,
+      y1: 0,
+      y2: height,
+      ...{
+        className: "x1lo1t26 xnpr05h"
+      },
+      pointerEvents: "none"
+    });
+  }, [hoverIndicator, hoveredIndex, series, xScale, data, xKey, width, height, margin.top, margin.right, isHorizontal]);
+
+  // Single source of truth for whether the card has anything to show. It's
+  // hidden when there's no hover, when the hovered index is stale/out-of-range
+  // (e.g. `data` shrank while hovering, so `datum` is undefined), or when a
+  // custom `render` opts out by returning null — the documented contract, which
+  // still shows the band highlight + dots. The decision is stored in a ref so
+  // the imperative positionCard honors it on subsequent same-index moves
+  // (otherwise it would re-reveal an empty bordered box). Runs after commit, so
+  // `render` (which may return null, or throw) never executes on the SSR path.
+  useEffect(() => {
+    const hidden = hoveredIndex == null || datum == null || render != null && render(xValue, seriesValues) == null;
+    cardHiddenRef.current = hidden;
+    if (hidden) {
+      const card = cardRef.current;
+      if (card) {
+        card.style.display = 'none';
+      }
+    }
+  }, [render, hoveredIndex, datum, xValue, seriesValues]);
+
+  // ─── Render ────────────────────────────────────────────────────────────
+  if (typeof document === 'undefined') {
+    // SSR: no DOM portal target; band highlight + dots still render in SVG.
+    return /*#__PURE__*/_jsxs(_Fragment, {
+      children: [hoverIndicatorElement, dots]
+    });
+  }
+
+  // Mirrors the visibility effect's first two conditions: no card when there's
+  // no hover or the hovered datum is stale/out-of-range (so `render` and the
+  // default body are never called with an undefined x-value + empty rows).
+  const cardContent = hoveredIndex == null || datum == null ? null : render ? render(xValue, seriesValues) : /*#__PURE__*/_jsx(DefaultTooltipContent, {
+    xValue: xValue,
+    rows: seriesValues
+  });
+  return /*#__PURE__*/_jsxs(_Fragment, {
+    children: [hoverIndicatorElement, dots, /*#__PURE__*/createPortal(/*#__PURE__*/_jsx("div", {
+      ref: cardRef,
+      role: "tooltip",
+      ...{
+        className: "xixxii4 x1prclbq x1hviunn xce4md1 xrrkdod x14hfi27 x47corl xuxw1ft x1q2oy4v x1s85apg"
+      },
+      children: cardContent
+    }), document.body)]
+  });
+}

package/dist/charts.css

@@ -0,0 +1,33 @@
+/* Pharos Charts Pre-compiled StyleX CSS — data visualization components */
+/* Auto-generated. Do not edit manually. */
+
+@layer pharos-base {
+  @property --x-backgroundColor { syntax: "*"; inherits: false;}
+  .xbvija:not(#\#){border-radius:1.5px}
+  .x1cum3z5:not(#\#){border-radius:2px}
+  .x1hviunn:not(#\#){border-radius:var(--radius-container)}
+  .x98rzlu:not(#\#){flex:1}
+  .xckhbgb:not(#\#){margin-inline:1px}
+  .xb3r6kr:not(#\#){overflow:hidden}
+  .xce4md1:not(#\#){padding-block:var(--spacing-2)}
+  .xrrkdod:not(#\#){padding-inline:var(--spacing-3)}
+  .x1prclbq:not(#\#):not(#\#){background-color:var(--color-background-popover)}
+  .xl8spv7:not(#\#):not(#\#){background-color:var(--x-backgroundColor)}
+  .x14hfi27:not(#\#):not(#\#){box-shadow:var(--shadow-med)}
+  .x1s85apg:not(#\#):not(#\#){display:none}
+  .x2lah0s:not(#\#):not(#\#){flex-shrink:0}
+  .x47corl:not(#\#):not(#\#){pointer-events:none}
+  .xixxii4:not(#\#):not(#\#){position:fixed}
+  .xnpr05h:not(#\#):not(#\#){stroke-width:1}
+  .x113i6qz:not(#\#):not(#\#){stroke:var(--color-border-emphasized)}
+  .x1lo1t26:not(#\#):not(#\#){stroke:var(--color-text-primary)}
+  .xuxw1ft:not(#\#):not(#\#){white-space:nowrap}
+  .x1q2oy4v:not(#\#):not(#\#){z-index:9999}
+  .xuoj239:not(#\#):not(#\#):not(#\#){height:3px}
+  .xdk7pt:not(#\#):not(#\#):not(#\#){height:8px}
+  .x1yztbdb:not(#\#):not(#\#):not(#\#){margin-bottom:16px}
+  .xeuugli:not(#\#):not(#\#):not(#\#){min-width:0}
+  .xh8yej3:not(#\#):not(#\#):not(#\#){width:100%}
+  .x1fsd2vl:not(#\#):not(#\#):not(#\#){width:10px}
+  .x1xc55vz:not(#\#):not(#\#):not(#\#){width:8px}
+}

package/dist/dataTable.d.ts

@@ -0,0 +1,56 @@
+/**
+ * @file dataTable.ts
+ * @output Pure builder for the chart's text alternative (WCAG 1.1.1): turns
+ *   `data` + `xKey` + `series` into a header row and one row per x value.
+ * @position Used by Chart to render the visually hidden `<table>` that sits
+ *   next to the `role="img"` SVG. Mirrors legend.ts / tooltip.ts: data shaping
+ *   lives here, presentation lives in Chart.tsx.
+ *
+ * Utility marks (band, errorBar, referenceLine) are annotations, not data the
+ * reader compares, so they get no column — same rule as the legend and the
+ * tooltip. A mark that reads several keys (candlestick: open/high/low/close)
+ * gets one column per key.
+ *
+ * SYNC: When modified, update /packages/charts/src/Chart.doc.mjs
+ */
+import { type SeriesDef } from './types';
+/** Options for the hidden data table rendered by `<Chart>`. */
+export interface ChartDataTableOptions {
+    /** Header of the first column (the x values). Default: the chart's `xKey`. */
+    xLabel?: string;
+    /** Formats an x value for its row header cell. Default: `String(value)`. */
+    formatX?: (value: unknown) => string;
+    /**
+     * Formats one value cell. Receives the raw value, the series and the data key
+     * being read. Default: locale-formatted numbers, `String()` otherwise and an
+     * empty cell for missing values.
+     */
+    formatValue?: (value: unknown, series: SeriesDef, dataKey: string) => string;
+    /**
+     * Largest `data.length` that still renders a table. Above it the table is
+     * omitted (streaming/WebGL charts with thousands of points) and the chart
+     * relies on its accessible name and `description`. Default: `1000`.
+     */
+    maxRows?: number;
+}
+export interface ChartDataTableModel {
+    headers: string[];
+    rows: {
+        key: string;
+        header: string;
+        cells: string[];
+    }[];
+}
+/** Default row cap — see `ChartDataTableOptions.maxRows`. */
+export declare const DATA_TABLE_MAX_ROWS = 1000;
+/**
+ * Build the table model, or `null` when there is nothing to tabulate (no data,
+ * no data series) or `data` exceeds `maxRows`.
+ */
+export declare function buildDataTable(data: readonly Record<string, unknown>[], xKey: string, series: readonly SeriesDef[], options?: ChartDataTableOptions): ChartDataTableModel | null;
+/**
+ * Accessible name fallback when the chart has neither `aria-label` nor
+ * `title`: the data series labels, so the name is never empty.
+ */
+export declare function fallbackChartLabel(series: readonly SeriesDef[]): string;
+//# sourceMappingURL=dataTable.d.ts.map

package/dist/dataTable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dataTable.d.ts","sourceRoot":"","sources":["../src/dataTable.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAoB,KAAK,SAAS,EAAC,MAAM,SAAS,CAAC;AAE1D,+DAA+D;AAC/D,MAAM,WAAW,qBAAqB;IACpC,8EAA8E;IAC9E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,4EAA4E;IAC5E,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,MAAM,CAAC;IACrC;;;;OAIG;IACH,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,KAAK,MAAM,CAAC;IAC7E;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,IAAI,EAAE;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,EAAE,CAAA;KAAC,EAAE,CAAC;CACxD;AAED,6DAA6D;AAC7D,eAAO,MAAM,mBAAmB,OAAO,CAAC;AAsBxC;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,EACxC,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,SAAS,SAAS,EAAE,EAC5B,OAAO,GAAE,qBAA0B,GAClC,mBAAmB,GAAG,IAAI,CAmC5B;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,SAAS,SAAS,EAAE,GAAG,MAAM,CAKvE"}

package/dist/dataTable.js

@@ -0,0 +1,88 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file dataTable.ts
+ * @output Pure builder for the chart's text alternative (WCAG 1.1.1): turns
+ *   `data` + `xKey` + `series` into a header row and one row per x value.
+ * @position Used by Chart to render the visually hidden `<table>` that sits
+ *   next to the `role="img"` SVG. Mirrors legend.ts / tooltip.ts: data shaping
+ *   lives here, presentation lives in Chart.tsx.
+ *
+ * Utility marks (band, errorBar, referenceLine) are annotations, not data the
+ * reader compares, so they get no column — same rule as the legend and the
+ * tooltip. A mark that reads several keys (candlestick: open/high/low/close)
+ * gets one column per key.
+ *
+ * SYNC: When modified, update /packages/charts/src/Chart.doc.mjs
+ */
+
+import { isUtilityMarkType } from "./types.js";
+
+/** Options for the hidden data table rendered by `<Chart>`. */
+
+/** Default row cap — see `ChartDataTableOptions.maxRows`. */
+export const DATA_TABLE_MAX_ROWS = 1000;
+function defaultFormatValue(value) {
+  if (value == null) {
+    return '';
+  }
+  if (typeof value === 'number') {
+    return Number.isFinite(value) ? value.toLocaleString() : '';
+  }
+  if (value instanceof Date) {
+    return value.toLocaleDateString();
+  }
+  return String(value);
+}
+function defaultFormatX(value) {
+  if (value instanceof Date) {
+    return value.toLocaleDateString();
+  }
+  return value == null ? '' : String(value);
+}
+
+/**
+ * Build the table model, or `null` when there is nothing to tabulate (no data,
+ * no data series) or `data` exceeds `maxRows`.
+ */
+export function buildDataTable(data, xKey, series, options = {}) {
+  const maxRows = options.maxRows ?? DATA_TABLE_MAX_ROWS;
+  if (data.length === 0 || data.length > maxRows) {
+    return null;
+  }
+  const columns = [];
+  for (const s of series) {
+    if (isUtilityMarkType(s.type)) {
+      continue;
+    }
+    const label = s.label ?? s.key;
+    for (const dataKey of s.dataKeys) {
+      columns.push({
+        series: s,
+        dataKey,
+        header: s.dataKeys.length > 1 ? `${label} (${dataKey})` : label
+      });
+    }
+  }
+  if (columns.length === 0) {
+    return null;
+  }
+  const formatX = options.formatX ?? defaultFormatX;
+  const formatValue = options.formatValue ?? defaultFormatValue;
+  return {
+    headers: [options.xLabel ?? xKey, ...columns.map(c => c.header)],
+    rows: data.map((d, i) => ({
+      key: String(i),
+      header: formatX(d[xKey]),
+      cells: columns.map(c => formatValue(d[c.dataKey], c.series, c.dataKey))
+    }))
+  };
+}
+
+/**
+ * Accessible name fallback when the chart has neither `aria-label` nor
+ * `title`: the data series labels, so the name is never empty.
+ */
+export function fallbackChartLabel(series) {
+  return series.filter(s => !isUtilityMarkType(s.type)).map(s => s.label ?? s.key).join(', ');
+}

package/dist/formatters.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Compact number formatter (e.g. 1200 → "1.2K", 1500000 → "1.5M", 1e12 → "1T").
+ *
+ * Non-numeric values (e.g. category labels) and non-finite numbers pass through
+ * unchanged, so it is safe to use as a general-purpose tick formatter.
+ */
+export declare function compactNumber(value: unknown): string;
+/**
+ * Currency formatter factory. Returns a tick format function.
+ *
+ * The symbol prefixes the magnitude and the sign leads the symbol, so negatives
+ * read as "-$1.5K" rather than "$-1.5K". Large values use compact notation.
+ *
+ * @example
+ * ```
+ * <ChartAxis tickFormat={currency()} />       // $1.5K
+ * <ChartAxis tickFormat={currency('€')} />    // €1.5K
+ * <ChartAxis tickFormat={currency('¥')} />    // ¥1.5K
+ * ```
+ */
+export declare function currency(symbol?: string): (value: unknown) => string;
+/**
+ * Percent formatter (e.g. 0.45 → "45%", 1.2 → "120%", 0.005 → "0.5%").
+ *
+ * The input is a ratio; it is multiplied by 100 and localized. Whole percents
+ * render without a decimal, and up to one fractional digit is shown otherwise.
+ */
+export declare function percent(value: unknown): string;
+/**
+ * Date formatter — short date (e.g. "Jan 5", "Mar 12").
+ */
+export declare function shortDate(value: unknown): string;
+/**
+ * Date formatter — month/year (e.g. "Jan 2024", "Mar 2025").
+ */
+export declare function monthYear(value: unknown): string;
+//# sourceMappingURL=formatters.d.ts.map

package/dist/formatters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"formatters.d.ts","sourceRoot":"","sources":["../src/formatters.ts"],"names":[],"mappings":"AA4CA;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAMpD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,QAAQ,CAAC,MAAM,SAAM,GAAG,CAAC,KAAK,EAAE,OAAO,KAAK,MAAM,CAYjE;AAED;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAM9C;AAiDD;;GAEG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAMhD;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAMhD"}