@pharos-ds/charts 0.0.0-stage → 1.0.10

package/dist/ChartAxis.d.ts

@@ -0,0 +1,37 @@
+export interface ChartAxisProps {
+    /** Which edge to render the axis on */
+    position: 'top' | 'right' | 'bottom' | 'left';
+    /** Number of ticks (approximate — d3 decides final count) */
+    tickCount?: number;
+    /** Maximum number of tick labels to show. Labels are evenly skipped when exceeded. */
+    maxTicks?: number;
+    /** Custom tick formatter */
+    tickFormat?: (value: unknown) => string;
+    /** Truncate labels to this many characters (appends "\u2026"). */
+    truncate?: number;
+    /** Enable smooth transitions for streaming (default: true) */
+    animated?: boolean;
+    /**
+     * Show the axis edge line. Defaults to `true` for the category axis
+     * (`position="bottom"`, or `position="left"` in a horizontal chart), `false`
+     * otherwise. Forced to `true` when `showTicks` is enabled.
+     * Pair with `<ChartGrid vertical />` and pass `showAxisLine` on the
+     * corresponding side axis to keep the visual edge grounded.
+     */
+    showAxisLine?: boolean;
+    /** Show perpendicular tick marks at each tick label. Default: `false`. */
+    showTicks?: boolean;
+}
+/**
+ * Chart axis. Always draws tick labels; the axis edge line and tick marks
+ * are independently toggleable. Pair with `<ChartGrid>` for grid lines.
+ *
+ * @example
+ * ```
+ * <ChartAxis position="bottom" />               // edge line + labels
+ * <ChartAxis position="left" />                 // labels only (no edge line)
+ * <ChartAxis position="left" showAxisLine showTicks />
+ * ```
+ */
+export declare function ChartAxis({ position, tickCount, maxTicks, tickFormat, truncate, animated, showAxisLine, showTicks, }: ChartAxisProps): import("react").JSX.Element;
+//# sourceMappingURL=ChartAxis.d.ts.map

package/dist/ChartAxis.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ChartAxis.d.ts","sourceRoot":"","sources":["../src/ChartAxis.tsx"],"names":[],"mappings":"AA+BA,MAAM,WAAW,cAAc;IAC7B,uCAAuC;IACvC,QAAQ,EAAE,KAAK,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,CAAC;IAC9C,6DAA6D;IAC7D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,sFAAsF;IACtF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,4BAA4B;IAC5B,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,MAAM,CAAC;IACxC,kEAAkE;IAClE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,0EAA0E;IAC1E,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAeD;;;;;;;;;;GAUG;AACH,wBAAgB,SAAS,CAAC,EACxB,QAAQ,EACR,SAAa,EACb,QAAQ,EACR,UAAU,EACV,QAAQ,EACR,QAAe,EACf,YAAY,EACZ,SAAiB,GAClB,EAAE,cAAc,+BAuMhB"}

package/dist/ChartAxis.js

@@ -0,0 +1,233 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file ChartAxis.tsx (v2)
+ * @output Renders an axis (top, right, bottom, left) using the chart's scales
+ * @position Child of Chart v2; reads scales from chart context
+ *
+ * The axis edge line and tick marks are independently toggleable so callers
+ * can compose: line-only, line + ticks, or line + ticks + grid (paired with
+ * `<ChartGrid>`). To stay consistent with most charts, the bottom axis
+ * draws its edge line by default and other positions don't.
+ *
+ * Labels use d3's native tick formatter for continuous scales by default (clean
+ * numbers/dates) unless a `tickFormat` is supplied, and are auto-thinned to the
+ * available width (horizontal) or height (vertical) to avoid overlap.
+ *
+ * Ticks use CSS transitions for smooth sliding during streaming updates.
+ *
+ * Orientation-aware: in a horizontal chart the context hands over display-space
+ * scales (values on x, categories on y), so `position="bottom"` shows values and
+ * `position="left"` shows categories. The default edge line follows the value
+ * baseline: bottom for vertical charts, left for horizontal ones.
+ */
+
+import { useCallback, useMemo } from 'react';
+import * as stylex from '@stylexjs/stylex';
+import '@pharos-ds/core/theme/tokens.stylex';
+import { colorVars } from '@pharos-ds/core/theme/tokens.stylex';
+import { useChart } from "./ChartContext.js";
+import { isBandScale } from "./utils.js";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+const TICK_SIZE = 6;
+
+/**
+ * Chart axis. Always draws tick labels; the axis edge line and tick marks
+ * are independently toggleable. Pair with `<ChartGrid>` for grid lines.
+ *
+ * @example
+ * ```
+ * <ChartAxis position="bottom" />               // edge line + labels
+ * <ChartAxis position="left" />                 // labels only (no edge line)
+ * <ChartAxis position="left" showAxisLine showTicks />
+ * ```
+ */
+export function ChartAxis({
+  position,
+  tickCount = 5,
+  maxTicks,
+  tickFormat,
+  truncate,
+  animated = true,
+  showAxisLine,
+  showTicks = false
+}) {
+  const {
+    width,
+    height,
+    xScale,
+    yScale,
+    yBandScale,
+    orientation
+  } = useChart();
+  const isHorizontalChart = orientation === 'horizontal';
+  // Tick marks need an axis line to anchor against; force it on when ticks
+  // are enabled so the two visuals stay coherent.
+  const renderAxisLine = (showAxisLine ?? position === (isHorizontalChart ? 'left' : 'bottom')) || showTicks;
+  const isHorizontal = position === 'top' || position === 'bottom';
+  // A categorical y-axis (e.g. heatmap rows) is exposed as `yBandScale`; prefer
+  // it over the linear `yScale` so a left/right axis renders the row categories
+  // (days) aligned to each band instead of meaningless value ticks.
+  const scale = isHorizontal ? xScale : yBandScale ?? yScale;
+
+  // Sanitize the tick count before it reaches d3. `.ticks()` targets ~N ticks
+  // and allocates an array that large, so a huge N throws `RangeError: Invalid
+  // array length` and crashes the render; a non-finite or negative N would
+  // otherwise blank the axis. Clamp to a sane integer (0 still means "no
+  // ticks") and fall back to the default for invalid input. Shared by tick
+  // generation and the auto formatter so the two stay in sync.
+  const safeTickCount = Number.isFinite(tickCount) && tickCount >= 0 ? Math.min(Math.floor(tickCount), 1000) : 5;
+
+  // Default label formatter. For continuous (linear/time) scales, use d3's own
+  // tick formatter so numbers get sensible precision (no floating-point dust
+  // like "0.30000000000000004") and dates render as calendar labels instead of
+  // `String(Date)`. Band scales keep their category strings.
+  const autoFormat = useMemo(() => {
+    if (tickFormat || isBandScale(scale)) {
+      return null;
+    }
+    const continuous = scale;
+    const fmt = continuous.tickFormat(safeTickCount);
+    return v => fmt(v);
+  }, [tickFormat, scale, safeTickCount]);
+  const format = useCallback(value => {
+    const str = (tickFormat ?? autoFormat ?? String)(value);
+    return truncate && str.length > truncate ? str.slice(0, truncate) + '\u2026' : str;
+  }, [tickFormat, autoFormat, truncate]);
+  const ticks = useMemo(() => {
+    let allTicks;
+    if (isBandScale(scale)) {
+      allTicks = scale.domain().map(d => ({
+        value: d,
+        offset: (scale(d) ?? 0) + scale.bandwidth() / 2
+      }));
+    } else {
+      const linearScale = scale;
+      allTicks = linearScale.ticks(safeTickCount).map(d => ({
+        value: d,
+        offset: linearScale(d)
+      }));
+    }
+
+    // Cap label count to avoid overlap. An explicit `maxTicks` always wins.
+    // Otherwise derive a cap from the available space and label size so dense
+    // axes don't smear into an unreadable blur: width ÷ widest-label for
+    // horizontal (e.g. 30 daily categories), height ÷ line-height for vertical
+    // (e.g. a categorical y-axis on a horizontal bar chart). Labels are then
+    // evenly skipped down to the cap.
+    let cap = maxTicks;
+    if (cap == null && allTicks.length > 1) {
+      if (isHorizontal && width > 0) {
+        const widestChars = allTicks.reduce((m, t) => Math.max(m, format(t.value).length), 1);
+        const approxLabelPx = widestChars * 7 + 16;
+        cap = Math.max(1, Math.floor(width / approxLabelPx));
+      } else if (!isHorizontal && height > 0) {
+        // ~12px glyph + breathing room keeps stacked labels from touching.
+        cap = Math.max(1, Math.floor(height / 18));
+      }
+    }
+    if (cap && allTicks.length > cap) {
+      const step = Math.ceil(allTicks.length / cap);
+      allTicks = allTicks.filter((_, i) => i % step === 0);
+    }
+    return allTicks;
+  }, [scale, safeTickCount, maxTicks, isHorizontal, width, height, format]);
+  const transform = position === 'bottom' ? `translate(0,${height})` : position === 'right' ? `translate(${width},0)` : undefined;
+
+  // For the bottom axis, draw the axis line at y=0 when the domain spans
+  // negative values (so the axis line still represents zero, not the chart edge).
+  const axisLineY = (() => {
+    // Categorical y (e.g. heatmap rows): there is no meaningful zero, and the
+    // linear yScale is degenerate — anchor the bottom edge line to the plot edge
+    // so it frames the grid instead of cutting across the cells.
+    if (position !== 'bottom' || yBandScale || isHorizontalChart) {
+      return 0;
+    }
+    const domain = yScale.domain();
+    if (domain[0] < 0 && domain[1] > 0) {
+      return yScale(0) - height;
+    }
+    return 0;
+  })();
+
+  // Horizontal charts: the left edge line marks value zero when the value
+  // domain spans negative values (mirror of `axisLineY` above).
+  const axisLineX = (() => {
+    if (position !== 'left' || !isHorizontalChart || isBandScale(xScale)) {
+      return 0;
+    }
+    const domain = xScale.domain();
+    if (domain[0] < 0 && domain[1] > 0) {
+      return xScale(0);
+    }
+    return 0;
+  })();
+  const tickTransition = animated ? 'transform 150ms linear, opacity 150ms ease' : undefined;
+  return /*#__PURE__*/_jsxs("g", {
+    transform: transform,
+    role: "group",
+    "aria-label": `${position} axis`,
+    children: [renderAxisLine && /*#__PURE__*/_jsx("line", {
+      x1: isHorizontal ? 0 : axisLineX,
+      x2: isHorizontal ? width : axisLineX,
+      y1: isHorizontal ? axisLineY : 0,
+      y2: isHorizontal ? axisLineY : height,
+      ...{
+        className: "x1lo1t26 xnpr05h"
+      }
+    }), ticks.map(({
+      value,
+      offset
+    }) => {
+      const label = format(value);
+      // Key off the raw tick value, not the formatted label: distinct ticks
+      // can format (or truncate) to the same string and would collide as keys.
+      const key = String(value);
+      const isVisible = isHorizontal ? offset >= -10 && offset <= width + 10 : offset >= -10 && offset <= height + 10;
+      if (isHorizontal) {
+        const y = position === 'bottom' ? TICK_SIZE : -TICK_SIZE;
+        return /*#__PURE__*/_jsxs("g", {
+          style: {
+            transform: `translateX(${offset}px)`,
+            transition: tickTransition,
+            opacity: isVisible ? 1 : 0
+          },
+          children: [showTicks && /*#__PURE__*/_jsx("line", {
+            y2: y,
+            ...{
+              className: "x1lo1t26 xnpr05h"
+            }
+          }), /*#__PURE__*/_jsx("text", {
+            y: position === 'bottom' ? TICK_SIZE + 12 : -(TICK_SIZE + 4),
+            textAnchor: "middle",
+            fill: "var(--color-text-secondary)",
+            fontSize: 12,
+            children: label
+          })]
+        }, key);
+      }
+      // Vertical axis
+      const x = position === 'left' ? -TICK_SIZE : TICK_SIZE;
+      return /*#__PURE__*/_jsxs("g", {
+        style: {
+          transform: `translateY(${offset}px)`,
+          transition: tickTransition,
+          opacity: isVisible ? 1 : 0
+        },
+        children: [showTicks && /*#__PURE__*/_jsx("line", {
+          x2: x,
+          ...{
+            className: "x1lo1t26 xnpr05h"
+          }
+        }), /*#__PURE__*/_jsx("text", {
+          x: position === 'left' ? -(TICK_SIZE + 4) : TICK_SIZE + 4,
+          dy: "0.32em",
+          textAnchor: position === 'left' ? 'end' : 'start',
+          fill: "var(--color-text-secondary)",
+          fontSize: 12,
+          children: label
+        })]
+      }, key);
+    })]
+  });
+}

package/dist/ChartContext.d.ts

@@ -0,0 +1,4 @@
+import type { ChartContext } from './types';
+export declare const ChartProvider: import("react").Provider<ChartContext | null>;
+export declare function useChart(): ChartContext;
+//# sourceMappingURL=ChartContext.d.ts.map

package/dist/ChartContext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ChartContext.d.ts","sourceRoot":"","sources":["../src/ChartContext.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,SAAS,CAAC;AAI1C,eAAO,MAAM,aAAa,+CAAe,CAAC;AAE1C,wBAAgB,QAAQ,IAAI,YAAY,CAMvC"}

package/dist/ChartContext.js

@@ -0,0 +1,15 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import { createContext, useContext } from 'react';
+const Ctx = /*#__PURE__*/createContext(null);
+Ctx.displayName = 'ChartContext';
+export const ChartProvider = Ctx.Provider;
+export function useChart() {
+  const ctx = useContext(Ctx);
+  if (!ctx) {
+    throw new Error('Must be used inside <Chart>');
+  }
+  return ctx;
+}

package/dist/ChartGrid.d.ts

@@ -0,0 +1,26 @@
+export interface ChartGridProps {
+    /** Show horizontal grid lines. Default: `true` (`false` in horizontal charts). */
+    horizontal?: boolean;
+    /** Show vertical grid lines. Default: `false` (`true` in horizontal charts). */
+    vertical?: boolean;
+    /**
+     * Approximate number of grid lines per axis. Match your `<ChartAxis>`
+     * `tickCount` so grid lines and tick labels land on the same values.
+     * Default: `5`.
+     */
+    tickCount?: number;
+}
+/**
+ * Grid lines behind chart marks.
+ *
+ * Pair with `<ChartAxis>` so users always see an axis line beside the
+ * grid — the components are designed to be used together.
+ *
+ * @example
+ * ```
+ * <ChartGrid />                 // horizontal grid lines (default)
+ * <ChartGrid horizontal vertical />
+ * ```
+ */
+export declare function ChartGrid({ horizontal: horizontalProp, vertical: verticalProp, tickCount, }: ChartGridProps): import("react").JSX.Element;
+//# sourceMappingURL=ChartGrid.d.ts.map

package/dist/ChartGrid.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ChartGrid.d.ts","sourceRoot":"","sources":["../src/ChartGrid.tsx"],"names":[],"mappings":"AAmBA,MAAM,WAAW,cAAc;IAC7B,kFAAkF;IAClF,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,gFAAgF;IAChF,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AASD;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,CAAC,EACxB,UAAU,EAAE,cAAc,EAC1B,QAAQ,EAAE,YAAY,EACtB,SAAa,GACd,EAAE,cAAc,+BAgFhB"}

package/dist/ChartGrid.js

@@ -0,0 +1,118 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file ChartGrid.tsx (v2)
+ * @output Grid lines behind chart marks
+ * @position Child of Chart v2; reads scales from chart context
+ *
+ * Defaults follow the value axis: horizontal lines for vertical charts,
+ * vertical lines for `orientation="horizontal"` charts. In a horizontal chart
+ * with categorical rows, explicit `horizontal` lines sit on the row centers.
+ */
+
+import { useMemo } from 'react';
+import * as stylex from '@stylexjs/stylex';
+import '@pharos-ds/core/theme/tokens.stylex';
+import { colorVars } from '@pharos-ds/core/theme/tokens.stylex';
+import { useChart } from "./ChartContext.js";
+import { isBandScale } from "./utils.js";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * Grid lines behind chart marks.
+ *
+ * Pair with `<ChartAxis>` so users always see an axis line beside the
+ * grid — the components are designed to be used together.
+ *
+ * @example
+ * ```
+ * <ChartGrid />                 // horizontal grid lines (default)
+ * <ChartGrid horizontal vertical />
+ * ```
+ */
+export function ChartGrid({
+  horizontal: horizontalProp,
+  vertical: verticalProp,
+  tickCount = 5
+}) {
+  const {
+    width,
+    height,
+    xScale,
+    yScale,
+    yBandScale,
+    orientation
+  } = useChart();
+  const isHorizontalChart = orientation === 'horizontal';
+  const horizontal = horizontalProp ?? !isHorizontalChart;
+  const vertical = verticalProp ?? isHorizontalChart;
+
+  // Sanitize the tick count before it reaches d3's `.ticks()`: it targets ~N
+  // ticks and allocates an array that large, so a huge N throws `RangeError:
+  // Invalid array length` and crashes the render, while a non-finite or
+  // negative N would misbehave. Clamp to a sane integer (0 still means "no
+  // lines") and fall back to the default for invalid input.
+  const safeTickCount = Number.isFinite(tickCount) && tickCount >= 0 ? Math.min(Math.floor(tickCount), 1000) : 5;
+
+  // Skip the y=0 line when emphasizing it via the axis. Without this we'd
+  // double-draw on top of the axis line. Each line carries its tick `value`,
+  // used as a stable React key — the pixel position can be NaN/duplicated for
+  // degenerate (zero-range / unmeasured) scales and would collide as a key.
+  const hLines = useMemo(() => {
+    if (!horizontal) {
+      return [];
+    }
+    if (isHorizontalChart && yBandScale) {
+      return yBandScale.domain().map(d => ({
+        value: d,
+        pos: (yBandScale(d) ?? 0) + yBandScale.bandwidth() / 2
+      }));
+    }
+    return yScale.ticks(safeTickCount).filter(tick => tick !== 0).map(tick => ({
+      value: tick,
+      pos: yScale(tick)
+    }));
+  }, [horizontal, yScale, yBandScale, isHorizontalChart, safeTickCount]);
+  const vLines = useMemo(() => {
+    if (!vertical) {
+      return [];
+    }
+    if (isBandScale(xScale)) {
+      return xScale.domain().map(d => ({
+        value: d,
+        pos: (xScale(d) ?? 0) + xScale.bandwidth() / 2
+      }));
+    }
+    const linear = xScale;
+    return linear.ticks(safeTickCount)
+    // Horizontal charts draw value zero with the left axis line.
+    .filter(d => !(isHorizontalChart && Number(d) === 0)).map(d => ({
+      value: String(d),
+      pos: linear(d)
+    }));
+  }, [vertical, xScale, safeTickCount, isHorizontalChart]);
+  return /*#__PURE__*/_jsxs("g", {
+    children: [hLines.map(({
+      value,
+      pos
+    }) => /*#__PURE__*/_jsx("line", {
+      x1: 0,
+      x2: width,
+      y1: pos,
+      y2: pos,
+      ...{
+        className: "x113i6qz xnpr05h"
+      }
+    }, `h-${value}`)), vLines.map(({
+      value,
+      pos
+    }) => /*#__PURE__*/_jsx("line", {
+      x1: pos,
+      x2: pos,
+      y1: 0,
+      y2: height,
+      ...{
+        className: "x113i6qz xnpr05h"
+      }
+    }, `v-${value}`))]
+  });
+}

package/dist/ChartLegend.d.ts

@@ -0,0 +1,14 @@
+import type { LegendItem } from './legend';
+export type { LegendItem };
+export type LegendPosition = 'top' | 'bottom' | 'start' | 'end';
+export type LegendAlignment = 'start' | 'center' | 'end';
+export interface ChartLegendProps {
+    /** Legend items to display */
+    items?: LegendItem[];
+    /** Position of the legend relative to the chart. Default: 'bottom' */
+    position?: LegendPosition;
+    /** Alignment of the legend within its position. Default: 'start' */
+    alignment?: LegendAlignment;
+}
+export declare function ChartLegend({ items, position, alignment, }: ChartLegendProps): import("react").JSX.Element | null;
+//# sourceMappingURL=ChartLegend.d.ts.map

package/dist/ChartLegend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ChartLegend.d.ts","sourceRoot":"","sources":["../src/ChartLegend.tsx"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,UAAU,CAAC;AAEzC,YAAY,EAAC,UAAU,EAAC,CAAC;AAEzB,MAAM,MAAM,cAAc,GAAG,KAAK,GAAG,QAAQ,GAAG,OAAO,GAAG,KAAK,CAAC;AAChE,MAAM,MAAM,eAAe,GAAG,OAAO,GAAG,QAAQ,GAAG,KAAK,CAAC;AAEzD,MAAM,WAAW,gBAAgB;IAC/B,8BAA8B;IAC9B,KAAK,CAAC,EAAE,UAAU,EAAE,CAAC;IACrB,sEAAsE;IACtE,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B,oEAAoE;IACpE,SAAS,CAAC,EAAE,eAAe,CAAC;CAC7B;AAED,wBAAgB,WAAW,CAAC,EAC1B,KAAU,EACV,QAAmB,EACnB,SAAmB,GACpB,EAAE,gBAAgB,sCAsClB"}

package/dist/ChartLegend.js

@@ -0,0 +1,62 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file ChartLegend.tsx
+ * @output Standalone chart legend component
+ * @position Can be used inside Chart via the `legend` prop, or independently
+ *
+ * @example
+ * // Via Chart
+ * <Chart legend={{position: 'top', alignment: 'start'}} ... />
+ *
+ * // Standalone
+ * <ChartLegend items={[{label: 'Revenue', color: '#3b82f6'}]} />
+ */
+
+import { Text } from '@pharos-ds/core';
+import { VStack, HStack } from '@pharos-ds/core';
+import { ChartSwatch, swatchVariantForType } from "./ChartSwatch.js";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+export function ChartLegend({
+  items = [],
+  position = 'bottom',
+  alignment = 'start'
+}) {
+  if (items.length === 0) {
+    return null;
+  }
+  const isVertical = position === 'start' || position === 'end';
+
+  // Rows are stateless, but labels aren't guaranteed unique (two series can
+  // share a label), so disambiguate with the index to keep keys collision-free.
+  const legendItems = items.map((item, i) => /*#__PURE__*/_jsxs(HStack, {
+    gap: 2,
+    vAlign: "center",
+    role: "listitem",
+    children: [/*#__PURE__*/_jsx(ChartSwatch, {
+      color: item.color,
+      variant: swatchVariantForType(item.type)
+    }), /*#__PURE__*/_jsx(Text, {
+      type: "supporting",
+      children: item.label
+    })]
+  }, `${item.label}-${i}`));
+  if (isVertical) {
+    return /*#__PURE__*/_jsx(VStack, {
+      gap: 2,
+      hAlign: alignment,
+      role: "list",
+      "aria-label": "Chart legend",
+      children: legendItems
+    });
+  }
+  return /*#__PURE__*/_jsx(HStack, {
+    gap: 4,
+    justify: alignment,
+    vAlign: "center",
+    wrap: "wrap",
+    role: "list",
+    "aria-label": "Chart legend",
+    children: legendItems
+  });
+}

package/dist/ChartSwatch.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Visual variant — drives shape.
+ * - `'square'` — square chip (bar series)
+ * - `'line'` — short stroke (line, dot, area, and other non-bar series)
+ */
+export type ChartSwatchVariant = 'square' | 'line';
+export interface ChartSwatchProps {
+    /** Fill color — typically a series color token */
+    color: string;
+    /** Visual variant. Default: `'square'`. */
+    variant?: ChartSwatchVariant;
+}
+/**
+ * Color swatch primitive.
+ *
+ * Used by ChartLegend (and ChartTooltip) to render the colored
+ * indicator next to a series label. Exported as a primitive so consumers
+ * can build their own custom legend/tooltip layouts while keeping visuals
+ * consistent.
+ */
+declare function ChartSwatchImpl({ color, variant }: ChartSwatchProps): import("react").JSX.Element;
+/**
+ * Memoized — swatches are static for a given (color, variant) tuple
+ * and can render many times in a tooltip/legend with several series.
+ */
+export declare const ChartSwatch: import("react").MemoExoticComponent<typeof ChartSwatchImpl>;
+/**
+ * Map a SeriesDef.type string to its swatch variant.
+ *
+ * Bar series get a square chip; everything else (line, dot, area, and any
+ * other non-bar mark) gets a short stroke. Centralized so legend, tooltip,
+ * and any custom chrome stay consistent.
+ */
+export declare function swatchVariantForType(type: string | undefined): ChartSwatchVariant;
+export {};
+//# sourceMappingURL=ChartSwatch.d.ts.map

package/dist/ChartSwatch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ChartSwatch.d.ts","sourceRoot":"","sources":["../src/ChartSwatch.tsx"],"names":[],"mappings":"AAmBA;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAAG,QAAQ,GAAG,MAAM,CAAC;AAEnD,MAAM,WAAW,gBAAgB;IAC/B,kDAAkD;IAClD,KAAK,EAAE,MAAM,CAAC;IACd,2CAA2C;IAC3C,OAAO,CAAC,EAAE,kBAAkB,CAAC;CAC9B;AAuBD;;;;;;;GAOG;AACH,iBAAS,eAAe,CAAC,EAAC,KAAK,EAAE,OAAkB,EAAC,EAAE,gBAAgB,+BAOrE;AAED;;;GAGG;AACH,eAAO,MAAM,WAAW,6DAAwB,CAAC;AAEjD;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,MAAM,GAAG,SAAS,GACvB,kBAAkB,CAEpB"}

package/dist/ChartSwatch.js

@@ -0,0 +1,85 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file ChartSwatch.tsx
+ * @output Color swatch primitive for legends, tooltips, and standalone use
+ * @position Composable primitive — used by ChartLegend (and future
+ *           ChartTooltip), or independently anywhere a series indicator
+ *           is needed.
+ *
+ * @example
+ * ```
+ * <ChartSwatch color="#3b82f6" variant="square" />
+ * <ChartSwatch color="#f59e0b" variant="line" />
+ * ```
+ */
+
+import { memo } from 'react';
+import * as stylex from '@stylexjs/stylex';
+
+/**
+ * Visual variant — drives shape.
+ * - `'square'` — square chip (bar series)
+ * - `'line'` — short stroke (line, dot, area, and other non-bar series)
+ */
+import { jsx as _jsx } from "react/jsx-runtime";
+const styles = {
+  base: {
+    kmuXW: "x2lah0s",
+    $$css: true
+  },
+  square: {
+    kzqmXN: "x1xc55vz",
+    kZKoxP: "xdk7pt",
+    kaIpWk: "x1cum3z5",
+    kUOVxO: "xckhbgb",
+    $$css: true
+  },
+  line: {
+    kzqmXN: "x1fsd2vl",
+    kZKoxP: "xuoj239",
+    kaIpWk: "xbvija",
+    $$css: true
+  },
+  fill: color => [{
+    kWkggS: color != null ? "xl8spv7" : color,
+    $$css: true
+  }, {
+    "--x-backgroundColor": color != null ? color : undefined
+  }]
+};
+
+/**
+ * Color swatch primitive.
+ *
+ * Used by ChartLegend (and ChartTooltip) to render the colored
+ * indicator next to a series label. Exported as a primitive so consumers
+ * can build their own custom legend/tooltip layouts while keeping visuals
+ * consistent.
+ */
+function ChartSwatchImpl({
+  color,
+  variant = 'square'
+}) {
+  return /*#__PURE__*/_jsx("div", {
+    "aria-hidden": true,
+    ...stylex.props(styles.base, styles[variant], styles.fill(color))
+  });
+}
+
+/**
+ * Memoized — swatches are static for a given (color, variant) tuple
+ * and can render many times in a tooltip/legend with several series.
+ */
+export const ChartSwatch = /*#__PURE__*/memo(ChartSwatchImpl);
+
+/**
+ * Map a SeriesDef.type string to its swatch variant.
+ *
+ * Bar series get a square chip; everything else (line, dot, area, and any
+ * other non-bar mark) gets a short stroke. Centralized so legend, tooltip,
+ * and any custom chrome stay consistent.
+ */
+export function swatchVariantForType(type) {
+  return type === 'bar' ? 'square' : 'line';
+}