@astryxdesign/lab 0.0.0-bootstrap.0 → 0.1.2-canary.04e71b2

package/src/Chart/Chart.tsx

@@ -0,0 +1,312 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Chart.tsx
+ * @output Root chart container — sets up SVG, scales, and context
+ * @position Parent component; all chart marks/axes/interactions are children
+ *
+ * Handles the d3 margin convention: outer SVG at full size, inner <g> translated
+ * by margins. Children receive scales and dimensions via context.
+ */
+
+import {
+  type CSSProperties,
+  type ReactNode,
+  useMemo,
+  useRef,
+  useState,
+  useCallback,
+  useLayoutEffect,
+} from 'react';
+import {scaleLinear, scaleBand} from 'd3-scale';
+import type {ScaleLinear} from 'd3-scale';
+import {isBandScale} from './utils';
+import {ChartProvider} from './ChartContext';
+import type {ChartMargin, ChartScale} from './types';
+
+/**
+ * Controls how the y-axis domain is computed:
+ * - `'auto'` — includes 0 when all values are positive (default, bar-friendly)
+ * - `'zero'` — symmetric range centered on 0 (good for +/- data)
+ * - `'data'` — tight fit to data extent only (no forced zero)
+ */
+export type YBaseline = 'auto' | 'zero' | 'data';
+
+export interface ChartProps {
+  /** The dataset — array of objects with consistent keys */
+  data: Record<string, unknown>[];
+  /**
+   * Key for the x-axis domain values.
+   * String values produce a band scale; numeric values produce a linear scale.
+   */
+  xKey: string;
+  /**
+   * Key(s) for the y-axis domain values.
+   * Used to compute the y-domain across all series.
+   */
+  yKeys: string[];
+  /** Chart height in pixels. Width is responsive (fills container). */
+  height?: number;
+  /** Override default margins */
+  margin?: Partial<ChartMargin>;
+  /**
+   * How the y-axis domain is computed.
+   * - `'auto'` — includes 0 when all values are positive (default)
+   * - `'zero'` — symmetric around 0 (use for profit/loss, sentiment, etc.)
+   * - `'data'` — tight fit to data extent
+   */
+  yBaseline?: YBaseline;
+  /**
+   * Explicit y-axis domain [min, max].
+   * When provided, this is the y-axis range. Data outside it is not clipped
+   * visually but will extend beyond the chart area.
+   */
+  yDomain?: [number, number];
+  /**
+   * Explicit x-axis domain [min, max] for linear/time scales.
+   * When provided, this is the x-axis range — the chart renders exactly
+   * this window. Use for streaming charts where the range shifts over time.
+   * Ignored for band (categorical) scales.
+   */
+  xDomain?: [number, number];
+  /**
+   * Set touch-action on the chart container. Use 'none' when interactive
+   * components (brush, zoom, crosshair) are present to prevent scroll
+   * interference on mobile.
+   */
+  interactive?: boolean;
+  /** Chart contents — axes, marks, tooltips */
+  children: ReactNode;
+}
+
+const DEFAULT_MARGIN: ChartMargin = {top: 16, right: 16, bottom: 32, left: 48};
+
+/**
+ * Root chart container. Computes scales from data and provides them to children.
+ *
+ * @example
+ * ```
+ * <Chart data={data} xKey="month" yKeys={['revenue']} height={300}>
+ *   <ChartAxis position="bottom" />
+ *   <ChartAxis position="left" />
+ *   <ChartBar dataKey="revenue" color={useChartColors().categorical(1)[0]} />
+ * </Chart>
+ * ```
+ */
+export function Chart({
+  data,
+  xKey,
+  yKeys,
+  height = 300,
+  margin: marginOverride,
+  yBaseline = 'auto',
+  yDomain: yDomainProp,
+  xDomain: xDomainProp,
+  interactive = false,
+  children,
+}: ChartProps) {
+  const containerRef = useRef<HTMLDivElement>(null);
+  const svgRef = useRef<SVGSVGElement>(null);
+  const [containerWidth, setContainerWidth] = useState(0);
+
+  useLayoutEffect(() => {
+    if (!containerRef.current) {
+      return;
+    }
+    const observer = new ResizeObserver(entries => {
+      const entry = entries[0];
+      if (entry) {
+        setContainerWidth(entry.contentRect.width);
+      }
+    });
+    observer.observe(containerRef.current);
+    return () => observer.disconnect();
+  }, []);
+
+  // Block scroll/zoom on the container when interactive.
+  // Must be non-passive to actually prevent default on touch events.
+  useLayoutEffect(() => {
+    const el = containerRef.current;
+    if (!el || !interactive) {
+      return;
+    }
+    const prevent = (e: TouchEvent) => e.preventDefault();
+    el.addEventListener('touchstart', prevent, {passive: false});
+    el.addEventListener('touchmove', prevent, {passive: false});
+    return () => {
+      el.removeEventListener('touchstart', prevent);
+      el.removeEventListener('touchmove', prevent);
+    };
+  }, [interactive]);
+
+  const margin = useMemo(
+    () => ({...DEFAULT_MARGIN, ...marginOverride}),
+    [marginOverride],
+  );
+
+  const innerWidth = Math.max(0, containerWidth - margin.left - margin.right);
+  const innerHeight = Math.max(0, height - margin.top - margin.bottom);
+
+  const xScale = useMemo((): ChartScale => {
+    const xValues = data.map(d => d[xKey]);
+    const isNumeric = xValues.every(v => typeof v === 'number');
+
+    if (isNumeric) {
+      if (xDomainProp) {
+        // Explicit domain is authoritative — use as-is
+        return scaleLinear().domain(xDomainProp).range([0, innerWidth]);
+      }
+      // Auto-compute from data
+      const nums = xValues as number[];
+      let min = Infinity;
+      let max = -Infinity;
+      for (const n of nums) {
+        if (n < min) {
+          min = n;
+        }
+        if (n > max) {
+          max = n;
+        }
+      }
+      return scaleLinear().domain([min, max]).range([0, innerWidth]).nice();
+    }
+
+    // Categorical — xDomain doesn't apply to band scales
+    return scaleBand<string>()
+      .domain(xValues.map(String))
+      .range([0, innerWidth])
+      .padding(0.2);
+  }, [data, xKey, innerWidth, xDomainProp]);
+
+  const yScale = useMemo((): ScaleLinear<number, number> => {
+    if (yDomainProp) {
+      // Explicit domain is authoritative — use as-is.
+      // No baseline adjustment, no .nice(). The caller owns the domain
+      // (e.g. zoom/pan controls) and rounding would cause ratcheting.
+      return scaleLinear().domain(yDomainProp).range([innerHeight, 0]);
+    }
+
+    // Auto-compute from data
+    let min = Infinity;
+    let max = -Infinity;
+    for (const d of data) {
+      for (const key of yKeys) {
+        const v = d[key];
+        if (typeof v === 'number') {
+          if (v < min) {
+            min = v;
+          }
+          if (v > max) {
+            max = v;
+          }
+        }
+      }
+    }
+
+    if (yBaseline === 'zero') {
+      const abs = Math.max(Math.abs(min), Math.abs(max));
+      min = -abs;
+      max = abs;
+    } else if (yBaseline === 'auto') {
+      if (min > 0) {
+        min = 0;
+      }
+      if (max < 0) {
+        max = 0;
+      }
+    }
+
+    return scaleLinear().domain([min, max]).range([innerHeight, 0]).nice();
+  }, [data, yKeys, innerHeight, yBaseline, yDomainProp]);
+
+  const pixelToData = useCallback(
+    (px: number, py: number) => {
+      const y = yScale.invert(py);
+      let x: number | string;
+      if (isBandScale(xScale)) {
+        const domain = xScale.domain();
+        const step = xScale.step();
+        const idx = Math.min(
+          domain.length - 1,
+          Math.max(0, Math.floor(px / step)),
+        );
+        x = domain[idx];
+      } else {
+        x = (xScale as ScaleLinear<number, number>).invert(px);
+      }
+      return {x, y, px, py};
+    },
+    [xScale, yScale],
+  );
+
+  const pointerToData = useCallback(
+    (e: React.PointerEvent) => {
+      const svg = svgRef.current;
+      if (!svg) {
+        return {x: null, y: 0, px: 0, py: 0};
+      }
+      const pt = svg.createSVGPoint();
+      pt.x = e.clientX;
+      pt.y = e.clientY;
+      // Transform to the inner <g> coordinate space (accounts for margins)
+      const gEl = svg.querySelector('g');
+      const ctm = gEl?.getScreenCTM?.()?.inverse();
+      const local = ctm ? pt.matrixTransform(ctm) : {x: 0, y: 0};
+      return pixelToData(local.x, local.y);
+    },
+    [pixelToData],
+  );
+
+  const ctx = useMemo(
+    () => ({
+      width: innerWidth,
+      height: innerHeight,
+      margin,
+      xKey,
+      data,
+      xScale,
+      yScale,
+      svgRef,
+      pointerToData,
+      pixelToData,
+    }),
+    [
+      innerWidth,
+      innerHeight,
+      margin,
+      xKey,
+      data,
+      xScale,
+      yScale,
+      pointerToData,
+      pixelToData,
+    ],
+  );
+
+  const containerStyle: CSSProperties = {
+    width: '100%',
+    touchAction: interactive ? 'none' : undefined,
+    userSelect: interactive ? 'none' : undefined,
+  };
+
+  return (
+    <div ref={containerRef} style={containerStyle}>
+      {containerWidth > 0 && (
+        <svg
+          ref={svgRef}
+          width={containerWidth}
+          height={height}
+          style={interactive ? {touchAction: 'none'} : undefined}>
+          <defs>
+            <clipPath id="astryx-chart-plot">
+              <rect x={0} y={0} width={innerWidth} height={innerHeight} />
+            </clipPath>
+          </defs>
+          <g transform={`translate(${margin.left},${margin.top})`}>
+            <ChartProvider value={ctx}>{children}</ChartProvider>
+          </g>
+        </svg>
+      )}
+    </div>
+  );
+}

package/src/Chart/ChartArea.doc.mjs

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

package/src/Chart/ChartArea.tsx

@@ -0,0 +1,91 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file ChartArea.tsx
+ * @output Renders a filled area between two y-bounds — confidence intervals, bands, ranges
+ * @position Child of Chart; reads scales from context
+ */
+
+import {useMemo} from 'react';
+import {area, curveMonotoneX} from 'd3-shape';
+import {useChart} from './ChartContext';
+import {xPixel} from './utils';
+
+export interface ChartAreaProps {
+  /** Data key for the upper bound. If omitted, uses `baseline`. */
+  yUpper?: string;
+  /** Data key for the lower bound. If omitted, uses `baseline`. */
+  yLower?: string;
+  /** Fallback data key when only one bound is specified. */
+  baseline?: string;
+  /** Fill color */
+  color: string;
+  /** Fill opacity (default: 0.2) */
+  opacity?: number;
+  /** Optional stroke on the band edges */
+  stroke?: boolean;
+  /** Stroke width when stroke is enabled */
+  strokeWidth?: number;
+}
+
+/**
+ * Area band between two y-values. Use for confidence intervals, error ranges,
+ * or any min/max band around a line.
+ *
+ * @example
+ * ```
+ * <ChartArea yUpper="upper95" yLower="lower95" color={colors[0]} />
+ * <ChartArea yUpper="upper95" baseline="mean" color={colors[0]} />
+ * ```
+ */
+export function ChartArea({
+  yUpper,
+  yLower,
+  baseline,
+  color,
+  opacity = 0.2,
+  stroke = false,
+  strokeWidth = 1,
+}: ChartAreaProps) {
+  const {data, xKey, xScale, yScale} = useChart();
+
+  const upperKey = yUpper ?? baseline;
+  const lowerKey = yLower ?? baseline;
+
+  const pathD = useMemo(() => {
+    if (!upperKey || !lowerKey) {
+      return '';
+    }
+    const generator = area<Record<string, unknown>>()
+      .x(d => xPixel(d, xKey, xScale))
+      .y0(d => {
+        const v = typeof d[lowerKey] === 'number' ? (d[lowerKey] as number) : 0;
+        return yScale(v);
+      })
+      .y1(d => {
+        const v = typeof d[upperKey] === 'number' ? (d[upperKey] as number) : 0;
+        return yScale(v);
+      })
+      .curve(curveMonotoneX);
+    return generator(data) ?? '';
+  }, [data, xKey, xScale, yScale, upperKey, lowerKey]);
+
+  if (!pathD) {
+    return null;
+  }
+
+  return (
+    <g>
+      <path d={pathD} fill={color} fillOpacity={opacity} stroke="none" />
+      {stroke && (
+        <path
+          d={pathD}
+          fill="none"
+          stroke={color}
+          strokeWidth={strokeWidth}
+          strokeOpacity={opacity * 2}
+        />
+      )}
+    </g>
+  );
+}

package/src/Chart/ChartAxis.tsx

@@ -0,0 +1,186 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file ChartAxis.tsx
+ * @output Renders an axis (top, right, bottom, left) using the chart's scales
+ * @position Child of Chart; reads scales from context
+ *
+ * Ticks use CSS transitions for smooth sliding during streaming updates.
+ */
+
+import {useMemo} from 'react';
+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;
+}
+
+/**
+ * Chart axis. Renders tick marks and labels for the x or y dimension.
+ * Ticks transition smoothly when the scale domain shifts (e.g. streaming).
+ *
+ * @example
+ * ```
+ * <ChartAxis position="bottom" />
+ * <ChartAxis position="left" tickCount={5} tickFormat={currency} />
+ * <ChartAxis position="bottom" maxTicks={6} truncate={10} />
+ * ```
+ */
+export function ChartAxis({
+  position,
+  tickCount = 5,
+  maxTicks,
+  tickFormat,
+  truncate,
+  animated = true,
+}: ChartAxisProps) {
+  const {width, height, xScale, yScale} = useChart();
+
+  const isHorizontal = position === 'top' || position === 'bottom';
+  const scale = isHorizontal ? xScale : yScale;
+
+  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(tickCount).map(d => ({
+        value: d,
+        offset: linearScale(d as number & Date),
+      }));
+    }
+
+    // Auto-skip: show every Nth label if maxTicks is exceeded
+    if (maxTicks && allTicks.length > maxTicks) {
+      const step = Math.ceil(allTicks.length / maxTicks);
+      allTicks = allTicks.filter((_, i) => i % step === 0);
+    }
+
+    return allTicks;
+  }, [scale, tickCount, maxTicks]);
+
+  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
+  const axisLineY = (() => {
+    if (position !== 'bottom') {
+      return 0;
+    }
+    const domain = yScale.domain();
+    if (domain[0] < 0 && domain[1] > 0) {
+      // The axis line should appear at the zero mark relative to the bottom edge
+      return yScale(0) - height;
+    }
+    return 0;
+  })();
+
+  const baseFormat = tickFormat ?? String;
+  const format = truncate
+    ? (value: unknown) => {
+        const str = baseFormat(value);
+        return str.length > truncate ? str.slice(0, truncate) + '\u2026' : str;
+      }
+    : baseFormat;
+  const tickSize = 6;
+
+  // Transition style for smooth tick movement during streaming
+  const tickTransition = animated
+    ? 'transform 150ms linear, opacity 150ms ease'
+    : undefined;
+
+  return (
+    <g transform={transform}>
+      {/* Axis line — at y=0 for bottom axis when domain spans negative values */}
+      <line
+        x1={isHorizontal ? 0 : 0}
+        x2={isHorizontal ? width : 0}
+        y1={isHorizontal ? axisLineY : 0}
+        y2={isHorizontal ? axisLineY : height}
+        stroke="var(--color-border-emphasized)"
+        strokeWidth={1}
+      />
+      {ticks.map(({value, offset}) => {
+        const label = format(value);
+        // Clip ticks that are outside the visible area
+        const isVisible = isHorizontal
+          ? offset >= -10 && offset <= width + 10
+          : offset >= -10 && offset <= height + 10;
+
+        if (isHorizontal) {
+          const y = position === 'bottom' ? tickSize : -tickSize;
+          return (
+            <g
+              key={label}
+              style={{
+                transform: `translateX(${offset}px)`,
+                transition: tickTransition,
+                opacity: isVisible ? 1 : 0,
+              }}>
+              <line
+                y2={y}
+                stroke="var(--color-border-emphasized)"
+                strokeWidth={1}
+              />
+              <text
+                y={position === 'bottom' ? tickSize + 12 : -(tickSize + 4)}
+                textAnchor="middle"
+                fill="var(--color-text-secondary)"
+                fontSize={12}>
+                {label}
+              </text>
+            </g>
+          );
+        }
+        // Vertical axis
+        const x = position === 'left' ? -tickSize : tickSize;
+        return (
+          <g
+            key={label}
+            style={{
+              transform: `translateY(${offset}px)`,
+              transition: tickTransition,
+              opacity: isVisible ? 1 : 0,
+            }}>
+            <line
+              x2={x}
+              stroke="var(--color-border-emphasized)"
+              strokeWidth={1}
+            />
+            <text
+              x={position === 'left' ? -(tickSize + 4) : tickSize + 4}
+              dy="0.32em"
+              textAnchor={position === 'left' ? 'end' : 'start'}
+              fill="var(--color-text-secondary)"
+              fontSize={12}>
+              {label}
+            </text>
+          </g>
+        );
+      })}
+    </g>
+  );
+}

package/src/Chart/ChartBar.doc.mjs

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

package/src/Chart/ChartBar.tsx

@@ -0,0 +1,71 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file ChartBar.tsx
+ * @output Renders vertical bars for a data key
+ * @position Child of Chart; reads scales from context
+ */
+
+import {useChart} from './ChartContext';
+import {isBandScale} from './utils';
+
+export interface ChartBarProps {
+  /** Which data key to visualize */
+  dataKey: string;
+  /** Bar fill color (hex string, CSS var, etc.) */
+  color: string;
+  /** Corner radius on bar tops */
+  radius?: number;
+}
+
+/**
+ * Bar marks. Requires a band xScale (categorical x-axis).
+ * Bars grow from the zero line — handles both positive and negative values.
+ *
+ * @example
+ * ```
+ * <ChartBar dataKey="revenue" color={useChartColors().categorical(1)[0]} />
+ * ```
+ */
+export function ChartBar({dataKey, color, radius = 4}: ChartBarProps) {
+  const {data, xKey, xScale, yScale} = useChart();
+
+  if (!isBandScale(xScale)) {
+    return null;
+  }
+
+  // Zero line position — bars grow from here
+  const zeroY = yScale(0);
+
+  return (
+    <g>
+      {data.map((d, i) => {
+        const xVal = xScale(String(d[xKey]));
+        if (xVal == null) {
+          return null;
+        }
+
+        const yVal =
+          typeof d[dataKey] === 'number' ? (d[dataKey] as number) : 0;
+        const yPos = yScale(yVal);
+
+        // Bar grows from zero line toward the value
+        const barY = Math.min(yPos, zeroY);
+        const barHeight = Math.abs(yPos - zeroY);
+
+        return (
+          <rect
+            key={i}
+            x={xVal}
+            y={barY}
+            width={xScale.bandwidth()}
+            height={Math.max(0, barHeight)}
+            fill={color}
+            rx={radius}
+            ry={radius}
+          />
+        );
+      })}
+    </g>
+  );
+}