@pharos-ds/charts 0.0.0-stage → 1.0.10

package/src/ChartAxis.tsx

@@ -0,0 +1,289 @@
+// 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 {colorVars} from '@pharos-ds/core/theme/tokens.stylex';
+import {useChart} from './ChartContext';
+import {isBandScale} from './utils';
+import type {ScaleLinear, ScaleTime} from 'd3-scale';
+
+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;
+}
+
+const styles = stylex.create({
+  axisLine: {
+    stroke: colorVars['--color-text-primary'],
+    strokeWidth: 1,
+  },
+  tickMark: {
+    stroke: colorVars['--color-text-primary'],
+    strokeWidth: 1,
+  },
+});
+
+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,
+}: ChartAxisProps) {
+  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<((v: unknown) => string) | null>(() => {
+    if (tickFormat || isBandScale(scale)) {
+      return null;
+    }
+    const continuous = scale as
+      ScaleLinear<number, number> | ScaleTime<number, number>;
+    const fmt = continuous.tickFormat(safeTickCount);
+    return (v: unknown) => fmt(v as number & Date);
+  }, [tickFormat, scale, safeTickCount]);
+
+  const format = useCallback(
+    (value: unknown): string => {
+      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: {value: unknown; offset: number}[];
+    if (isBandScale(scale)) {
+      allTicks = scale.domain().map(d => ({
+        value: d,
+        offset: (scale(d) ?? 0) + scale.bandwidth() / 2,
+      }));
+    } else {
+      const linearScale = scale as
+        ScaleLinear<number, number> | ScaleTime<number, number>;
+      allTicks = linearScale.ticks(safeTickCount).map(d => ({
+        value: d,
+        offset: linearScale(d as number & Date),
+      }));
+    }
+
+    // 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 as ScaleLinear<number, number>).domain();
+    if (domain[0] < 0 && domain[1] > 0) {
+      return (xScale as ScaleLinear<number, number>)(0);
+    }
+    return 0;
+  })();
+
+  const tickTransition = animated
+    ? 'transform 150ms linear, opacity 150ms ease'
+    : undefined;
+
+  return (
+    <g transform={transform} role="group" aria-label={`${position} axis`}>
+      {renderAxisLine && (
+        <line
+          x1={isHorizontal ? 0 : axisLineX}
+          x2={isHorizontal ? width : axisLineX}
+          y1={isHorizontal ? axisLineY : 0}
+          y2={isHorizontal ? axisLineY : height}
+          {...stylex.props(styles.axisLine)}
+        />
+      )}
+      {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 (
+            <g
+              key={key}
+              style={{
+                transform: `translateX(${offset}px)`,
+                transition: tickTransition,
+                opacity: isVisible ? 1 : 0,
+              }}>
+              {showTicks && <line y2={y} {...stylex.props(styles.tickMark)} />}
+              <text
+                y={position === 'bottom' ? TICK_SIZE + 12 : -(TICK_SIZE + 4)}
+                textAnchor="middle"
+                fill="var(--color-text-secondary)"
+                fontSize={12}>
+                {label}
+              </text>
+            </g>
+          );
+        }
+        // Vertical axis
+        const x = position === 'left' ? -TICK_SIZE : TICK_SIZE;
+        return (
+          <g
+            key={key}
+            style={{
+              transform: `translateY(${offset}px)`,
+              transition: tickTransition,
+              opacity: isVisible ? 1 : 0,
+            }}>
+            {showTicks && <line x2={x} {...stylex.props(styles.tickMark)} />}
+            <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}>
+              {label}
+            </text>
+          </g>
+        );
+      })}
+    </g>
+  );
+}

package/src/ChartContext.ts

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

package/src/ChartGrid.tsx

@@ -0,0 +1,136 @@
+// 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 {colorVars} from '@pharos-ds/core/theme/tokens.stylex';
+import {useChart} from './ChartContext';
+import {isBandScale} from './utils';
+import type {ScaleLinear, ScaleTime} from 'd3-scale';
+
+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;
+}
+
+const styles = stylex.create({
+  gridLine: {
+    stroke: colorVars['--color-border-emphasized'],
+    strokeWidth: 1,
+  },
+});
+
+/**
+ * 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,
+}: ChartGridProps) {
+  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 as
+      ScaleLinear<number, number> | ScaleTime<number, number>;
+    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 as number & Date)}))
+    );
+  }, [vertical, xScale, safeTickCount, isHorizontalChart]);
+
+  return (
+    <g>
+      {hLines.map(({value, pos}) => (
+        <line
+          key={`h-${value}`}
+          x1={0}
+          x2={width}
+          y1={pos}
+          y2={pos}
+          {...stylex.props(styles.gridLine)}
+        />
+      ))}
+      {vLines.map(({value, pos}) => (
+        <line
+          key={`v-${value}`}
+          x1={pos}
+          x2={pos}
+          y1={0}
+          y2={height}
+          {...stylex.props(styles.gridLine)}
+        />
+      ))}
+    </g>
+  );
+}

package/src/ChartLegend.tsx

@@ -0,0 +1,77 @@
+// 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';
+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 function ChartLegend({
+  items = [],
+  position = 'bottom',
+  alignment = 'start',
+}: ChartLegendProps) {
+  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) => (
+    <HStack key={`${item.label}-${i}`} gap={2} vAlign="center" role="listitem">
+      <ChartSwatch
+        color={item.color}
+        variant={swatchVariantForType(item.type)}
+      />
+      <Text type="supporting">{item.label}</Text>
+    </HStack>
+  ));
+
+  if (isVertical) {
+    return (
+      <VStack gap={2} hAlign={alignment} role="list" aria-label="Chart legend">
+        {legendItems}
+      </VStack>
+    );
+  }
+
+  return (
+    <HStack
+      gap={4}
+      justify={alignment}
+      vAlign="center"
+      wrap="wrap"
+      role="list"
+      aria-label="Chart legend">
+      {legendItems}
+    </HStack>
+  );
+}

package/src/ChartSwatch.doc.mjs

@@ -0,0 +1,17 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../../core/src/docs-types').ComponentDoc} */
+
+export const docs = {
+  name: 'ChartSwatch',
+  displayName: 'Chart Swatch',
+  group: 'Charts',
+  category: 'Data Visualization',
+  isHiddenFromOverview: true,
+
+  usage: {
+    description: '',
+  },
+
+  props: [],
+};

package/src/ChartSwatch.tsx

@@ -0,0 +1,89 @@
+// 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)
+ */
+export type ChartSwatchVariant = 'square' | 'line';
+
+export interface ChartSwatchProps {
+  /** Fill color — typically a series color token */
+  color: string;
+  /** Visual variant. Default: `'square'`. */
+  variant?: ChartSwatchVariant;
+}
+
+const styles = stylex.create({
+  base: {
+    flexShrink: 0,
+  },
+  square: {
+    width: 8,
+    height: 8,
+    borderRadius: 2,
+    marginInline: 1,
+  },
+  line: {
+    width: 10,
+    height: 3,
+    borderRadius: 1.5,
+  },
+  // Runtime color → dynamic StyleX (not an inline style), per repo convention.
+  fill: (color: string) => ({
+    backgroundColor: color,
+  }),
+});
+
+/**
+ * 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'}: ChartSwatchProps) {
+  return (
+    <div
+      aria-hidden
+      {...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 = 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: string | undefined,
+): ChartSwatchVariant {
+  return type === 'bar' ? 'square' : 'line';
+}