@pharos-ds/charts 0.0.0-stage → 1.0.10

package/src/marks/band.tsx

@@ -0,0 +1,86 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file marks/band.tsx
+ * @output Band (confidence interval) series — area between upper/lower bounds.
+ *   Non-numeric/NaN bounds break the area into gaps instead of collapsing to a
+ *   false zero baseline.
+ */
+
+import {area as d3Area, curveMonotoneX} from 'd3-shape';
+import {
+  DEFAULT_SERIES_COLOR,
+  type SeriesDef,
+  type ResolvedPoint,
+} from '../types';
+import {xPixel} from '../utils';
+
+export interface BandOptions {
+  upper: string;
+  lower: string;
+  color?: string;
+  opacity?: number;
+}
+
+export function band(options: BandOptions): SeriesDef {
+  const color = options.color ?? DEFAULT_SERIES_COLOR;
+  const opacity = options.opacity ?? 0.15;
+
+  return {
+    type: 'band',
+    key: `band-${options.upper}-${options.lower}`,
+    dataKeys: [options.upper, options.lower],
+    layout: {},
+
+    resolve(ctx) {
+      const {data, xKey, xScale, yScale} = ctx;
+      const points: ResolvedPoint[] = [];
+      for (let i = 0; i < data.length; i++) {
+        const d = data[i];
+        // NaN for missing/non-numeric bounds so render() can gap the area
+        // rather than draw a spike down to the axis.
+        const upperVal = d[options.upper];
+        const lowerVal = d[options.lower];
+        const upper =
+          typeof upperVal === 'number' && Number.isFinite(upperVal)
+            ? upperVal
+            : NaN;
+        const lower =
+          typeof lowerVal === 'number' && Number.isFinite(lowerVal)
+            ? lowerVal
+            : NaN;
+        points.push({
+          px: xPixel(d, xKey, xScale),
+          py: yScale(upper),
+          py0: yScale(lower),
+          dataIndex: i,
+        });
+      }
+      return points;
+    },
+
+    render(resolved) {
+      if (resolved.length === 0) {
+        return null;
+      }
+      const areaGen = d3Area<ResolvedPoint>()
+        .defined(
+          d =>
+            Number.isFinite(d.px) &&
+            Number.isFinite(d.py) &&
+            Number.isFinite(d.py0),
+        )
+        .x(d => d.px)
+        .y0(d => d.py0)
+        .y1(d => d.py)
+        .curve(curveMonotoneX);
+      const pathD = areaGen(resolved) ?? '';
+      if (!pathD) {
+        return null;
+      }
+      return (
+        <path d={pathD} fill={color} fillOpacity={opacity} stroke="none" />
+      );
+    },
+  };
+}

package/src/marks/bar.tsx

@@ -0,0 +1,210 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file marks/bar.tsx
+ * @output Bar series — self-contained resolve + render
+ * @position Standalone mark; chart root calls resolve() then render()
+ *
+ * Robust to missing/NaN values (bars with no finite height are skipped rather
+ * than drawn at the baseline) and to degenerate bandwidths (grouped bar widths
+ * are clamped to a non-negative value). Negative values grow downward from zero.
+ */
+
+import type {SeriesDef, ResolvedPoint, ColorAccessor} from '../types';
+import type {ScaleBand} from 'd3-scale';
+import {pointFill} from '../markColor';
+
+export type {ColorAccessor};
+
+export interface BarOptions {
+  color?: ColorAccessor;
+  opacity?: number;
+  radius?: number;
+  stack?: string;
+  group?: string;
+  label?: string;
+}
+
+/** Clamp a user opacity into [0,1], falling back when it isn't a finite number. */
+function clampOpacity(value: number | undefined, fallback: number): number {
+  const n =
+    typeof value === 'number' && Number.isFinite(value) ? value : fallback;
+  return Math.min(1, Math.max(0, n));
+}
+
+/** Coerce a user length (radius/width) to a finite, non-negative number. */
+function nonNegative(value: number | undefined, fallback: number): number {
+  return typeof value === 'number' && Number.isFinite(value)
+    ? Math.max(0, value)
+    : fallback;
+}
+
+/** True when every coordinate is finite — a NaN/Infinity would corrupt the path. */
+function rectIsFinite(x: number, y: number, w: number, h: number): boolean {
+  return (
+    Number.isFinite(x) &&
+    Number.isFinite(y) &&
+    Number.isFinite(w) &&
+    Number.isFinite(h)
+  );
+}
+
+/**
+ * Build an SVG path for a rectangle with only the top corners rounded.
+ * When `r` is 0, produces a simple rect path with no curves. Returns an empty
+ * path (draws nothing) if any coordinate is non-finite.
+ */
+function roundedTopRect(
+  x: number,
+  y: number,
+  w: number,
+  h: number,
+  r: number,
+): string {
+  if (!rectIsFinite(x, y, w, h)) {
+    return '';
+  }
+  // Clamp radius to half the smaller dimension
+  const cr = Math.min(r, w / 2, h / 2);
+  if (!(cr > 0)) {
+    return `M${x},${y + h}V${y}H${x + w}V${y + h}Z`;
+  }
+  return (
+    `M${x},${y + h}` +
+    `V${y + cr}Q${x},${y} ${x + cr},${y}` +
+    `H${x + w - cr}Q${x + w},${y} ${x + w},${y + cr}` +
+    `V${y + h}Z`
+  );
+}
+
+/**
+ * Build an SVG path for a rectangle with only the bottom corners rounded.
+ * Returns an empty path if any coordinate is non-finite.
+ */
+function roundedBottomRect(
+  x: number,
+  y: number,
+  w: number,
+  h: number,
+  r: number,
+): string {
+  if (!rectIsFinite(x, y, w, h)) {
+    return '';
+  }
+  const cr = Math.min(r, w / 2, h / 2);
+  if (!(cr > 0)) {
+    return `M${x},${y}V${y + h}H${x + w}V${y}Z`;
+  }
+  return (
+    `M${x},${y}` +
+    `V${y + h - cr}Q${x},${y + h} ${x + cr},${y + h}` +
+    `H${x + w - cr}Q${x + w},${y + h} ${x + w},${y + h - cr}` +
+    `V${y}Z`
+  );
+}
+
+export function bar(dataKey: string, options: BarOptions = {}): SeriesDef {
+  const color = options.color;
+  const opacity = clampOpacity(options.opacity, 1);
+  const radius = nonNegative(options.radius, 4);
+
+  let barWidth = 0;
+  let barOffset = 0;
+
+  const seriesDef: SeriesDef = {
+    type: 'bar',
+    key: dataKey,
+    dataKeys: [dataKey],
+    color: typeof color === 'string' ? color : undefined,
+    label: options.label ?? dataKey,
+    layout: {
+      stack: options.stack,
+      group: options.group,
+      includeZero: true,
+    },
+
+    resolve(ctx, stackOffsets, groupInfo) {
+      const {data, xKey, xScale, yScale} = ctx;
+      if (!('bandwidth' in xScale)) {
+        return [];
+      }
+
+      const bandScale = xScale as ScaleBand<string>;
+      const bw = bandScale.bandwidth();
+
+      if (groupInfo && groupInfo.count > 0) {
+        const gutter = bw * 0.05;
+        const totalGutters = gutter * (groupInfo.count - 1);
+        // Clamp: with many groups in a narrow band, gutters can exceed the band
+        // and drive the raw width negative — a negative width mirrors the path.
+        barWidth = Math.max(0, (bw - totalGutters) / groupInfo.count);
+        barOffset = groupInfo.index * (barWidth + gutter);
+      } else {
+        barWidth = bw;
+        barOffset = 0;
+      }
+
+      const points: ResolvedPoint[] = [];
+      for (let i = 0; i < data.length; i++) {
+        const d = data[i];
+        // Unknown categories aren't in the band domain → NaN px so render skips
+        // them rather than stacking phantom bars at the origin.
+        const xBase = bandScale(String(d[xKey]));
+        const px = xBase == null ? NaN : xBase + barOffset + barWidth / 2;
+
+        let py: number;
+        let py0: number;
+        if (stackOffsets) {
+          const offset = stackOffsets[i];
+          py = offset ? yScale(offset.y1) : NaN;
+          py0 = offset ? yScale(offset.y0) : NaN;
+        } else {
+          const raw = d[dataKey];
+          const v = typeof raw === 'number' && Number.isFinite(raw) ? raw : NaN;
+          py = yScale(v);
+          py0 = yScale(0);
+        }
+        points.push({px, py, py0, dataIndex: i});
+      }
+      return points;
+    },
+
+    render(resolved, ctx) {
+      const {data} = ctx;
+      const isTop = seriesDef._isTopOfStack !== false;
+      const r = isTop ? radius : 0;
+      if (!(barWidth > 0)) {
+        return null;
+      }
+
+      return (
+        <g opacity={opacity}>
+          {resolved.map(p => {
+            const d = data[p.dataIndex];
+            if (
+              !d ||
+              !Number.isFinite(p.px) ||
+              !Number.isFinite(p.py) ||
+              !Number.isFinite(p.py0)
+            ) {
+              return null;
+            }
+            const fill = pointFill(seriesDef, color, d, p.dataIndex);
+            const x = p.px - barWidth / 2;
+            const y = Math.min(p.py, p.py0);
+            const h = Math.max(0, Math.abs(p.py0 - p.py));
+            const growsUp = p.py <= p.py0;
+
+            const d_attr = growsUp
+              ? roundedTopRect(x, y, barWidth, h, r)
+              : roundedBottomRect(x, y, barWidth, h, r);
+
+            return <path key={p.dataIndex} d={d_attr} fill={fill} />;
+          })}
+        </g>
+      );
+    },
+  };
+
+  return seriesDef;
+}

package/src/marks/candlestick.tsx

@@ -0,0 +1,128 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file marks/candlestick.tsx
+ * @output Candlestick (OHLC) series. Renders on both band and linear/time x
+ *   scales; candles missing any OHLC field are skipped rather than drawn to 0.
+ */
+
+import type {SeriesDef, ResolvedPoint, SeriesContext} from '../types';
+import {xPixel, isBandScale} from '../utils';
+
+export interface CandlestickOptions {
+  open: string;
+  high: string;
+  low: string;
+  close: string;
+  upColor?: string;
+  downColor?: string;
+}
+
+/** Read a datum field as a finite number, or NaN when missing/non-numeric. */
+function readNumber(d: Record<string, unknown>, key: string): number {
+  const v = d[key];
+  return typeof v === 'number' && Number.isFinite(v) ? v : NaN;
+}
+
+/**
+ * Pixel width of one candle body. On a band scale this is the bandwidth; on a
+ * linear/time scale it's derived from the smallest gap between adjacent points
+ * (falling back to a modest width when there's only one point).
+ */
+function candleSlot(resolved: ResolvedPoint[], ctx: SeriesContext): number {
+  const {xScale, width} = ctx;
+  if (isBandScale(xScale)) {
+    return xScale.bandwidth();
+  }
+  const xs = resolved
+    .map(p => p.px)
+    .filter(x => Number.isFinite(x))
+    .sort((a, b) => a - b);
+  let minGap = Infinity;
+  for (let i = 1; i < xs.length; i++) {
+    const gap = xs[i] - xs[i - 1];
+    if (gap > 0 && gap < minGap) {
+      minGap = gap;
+    }
+  }
+  return Number.isFinite(minGap) ? minGap : Math.min(width, 40);
+}
+
+export function candlestick(options: CandlestickOptions): SeriesDef {
+  // Emitted core semantic tokens (data-viz --color-data-* tokens aren't CSS vars).
+  const upColor = options.upColor ?? 'var(--color-success)';
+  const downColor = options.downColor ?? 'var(--color-error)';
+
+  return {
+    type: 'candlestick',
+    key: `ohlc-${options.close}`,
+    dataKeys: [options.open, options.high, options.low, options.close],
+    layout: {},
+
+    resolve(ctx) {
+      const {data, xKey, xScale, yScale} = ctx;
+      const points: ResolvedPoint[] = [];
+      for (let i = 0; i < data.length; i++) {
+        const d = data[i];
+        const close = readNumber(d, options.close);
+        points.push({
+          px: xPixel(d, xKey, xScale),
+          py: yScale(close),
+          py0: yScale(0),
+          dataIndex: i,
+        });
+      }
+      return points;
+    },
+
+    render(resolved, ctx) {
+      const {data, yScale} = ctx;
+      const bodyWidth = Math.max(1, candleSlot(resolved, ctx) * 0.6);
+
+      return (
+        <g>
+          {resolved.map(p => {
+            const d = data[p.dataIndex];
+            const o = readNumber(d, options.open);
+            const c = readNumber(d, options.close);
+            const h = readNumber(d, options.high);
+            const l = readNumber(d, options.low);
+            // Drop candles missing any OHLC field (or an unplaceable x) — a gap
+            // reads more honestly than a full-height candle anchored at 0.
+            if (
+              !Number.isFinite(p.px) ||
+              !Number.isFinite(o) ||
+              !Number.isFinite(c) ||
+              !Number.isFinite(h) ||
+              !Number.isFinite(l)
+            ) {
+              return null;
+            }
+            const col = c >= o ? upColor : downColor;
+            const bodyTop = yScale(Math.max(o, c));
+            const bodyHeight = Math.max(1, Math.abs(yScale(o) - yScale(c)));
+            return (
+              <g key={p.dataIndex}>
+                <line
+                  x1={p.px}
+                  x2={p.px}
+                  y1={yScale(h)}
+                  y2={yScale(l)}
+                  stroke={col}
+                  strokeWidth={1}
+                />
+                <rect
+                  x={p.px - bodyWidth / 2}
+                  y={bodyTop}
+                  width={bodyWidth}
+                  height={bodyHeight}
+                  fill={col}
+                />
+              </g>
+            );
+          })}
+        </g>
+      );
+    },
+  };
+}

package/src/marks/dot.tsx

@@ -0,0 +1,119 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file marks/dot.tsx
+ * @output Dot/scatter series — self-contained resolve + render
+ *
+ * Points with missing / non-finite values are skipped rather than plotted at the
+ * baseline. Optional `dodge` spreads coincident points horizontally, ignoring
+ * non-finite ones so a single missing value can't collapse a whole dodge group.
+ */
+
+import type {SeriesDef, ResolvedPoint, ColorAccessor} from '../types';
+import {pointFill} from '../markColor';
+import {xPixel} from '../utils';
+
+export type {ColorAccessor};
+
+export interface DotOptions {
+  color?: ColorAccessor;
+  radius?: number;
+  opacity?: number;
+  dodge?: boolean;
+  label?: string;
+}
+
+export function dot(dataKey: string, options: DotOptions = {}): SeriesDef {
+  const color = options.color;
+  const radius =
+    typeof options.radius === 'number' && Number.isFinite(options.radius)
+      ? Math.max(0, options.radius)
+      : 4;
+  const opacity =
+    typeof options.opacity === 'number' && Number.isFinite(options.opacity)
+      ? Math.min(1, Math.max(0, options.opacity))
+      : 0.8;
+  const dodge = options.dodge ?? false;
+
+  const seriesDef: SeriesDef = {
+    type: 'dot',
+    key: dataKey,
+    dataKeys: [dataKey],
+    color: typeof color === 'string' ? color : undefined,
+    label: options.label ?? dataKey,
+    layout: {},
+
+    resolve(ctx) {
+      const {data, xKey, xScale, yScale} = ctx;
+      const points: ResolvedPoint[] = [];
+      for (let i = 0; i < data.length; i++) {
+        const d = data[i];
+        const raw = d[dataKey];
+        const v = typeof raw === 'number' && Number.isFinite(raw) ? raw : NaN;
+        points.push({
+          px: xPixel(d, xKey, xScale),
+          py: yScale(v),
+          py0: yScale(0),
+          dataIndex: i,
+        });
+      }
+
+      if (dodge) {
+        // Spread points that land on the same x (e.g. dots over band categories)
+        // horizontally so they don't overlap, centered on the original x.
+        const groups = new Map<number, ResolvedPoint[]>();
+        for (const p of points) {
+          // Only points render() will actually draw (finite px AND py) join a
+          // dodge group; a missing y-value must not reserve a slot and knock the
+          // visible points off-center.
+          if (!Number.isFinite(p.px) || !Number.isFinite(p.py)) {
+            continue;
+          }
+          const key = Math.round(p.px);
+          const group = groups.get(key) ?? [];
+          group.push(p);
+          groups.set(key, group);
+        }
+        const spacing = radius * 2 + 1;
+        for (const group of groups.values()) {
+          if (group.length < 2) {
+            continue;
+          }
+          const mid = (group.length - 1) / 2;
+          group.forEach((p, idx) => {
+            p.px += (idx - mid) * spacing;
+          });
+        }
+      }
+
+      return points;
+    },
+
+    render(resolved, ctx) {
+      const {data} = ctx;
+      return (
+        <g>
+          {resolved.map(p => {
+            const d = data[p.dataIndex];
+            if (!d || !Number.isFinite(p.px) || !Number.isFinite(p.py)) {
+              return null;
+            }
+            const fill = pointFill(seriesDef, color, d, p.dataIndex);
+            return (
+              <circle
+                key={p.dataIndex}
+                cx={p.px}
+                cy={p.py}
+                r={radius}
+                fill={fill}
+                opacity={opacity}
+              />
+            );
+          })}
+        </g>
+      );
+    },
+  };
+
+  return seriesDef;
+}