@pharos-ds/charts 0.0.0-bootstrap.0 → 1.0.10

package/src/formatters.ts

@@ -0,0 +1,167 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file formatters.ts
+ * @output Built-in, locale-aware tick/value format utilities for common data types
+ * @position Utility; consumed by ChartAxis via tickFormat prop
+ *
+ * Formatters degrade gracefully: non-finite numbers (NaN/±Infinity) and
+ * unparseable values are passed through as-is rather than producing garbage
+ * like "InfinityB", and no input throws. Numeric/date formatting is delegated
+ * to cached `Intl` formatters so output is locale-aware and rounding is correct
+ * across the full magnitude range (K/M/B/T and beyond).
+ */
+
+/** Lazily create a value once and cache it — keeps `Intl` construction off the import path. */
+function once<T>(create: () => T): () => T {
+  let cached: {value: T} | null = null;
+  return () => (cached ??= {value: create()}).value;
+}
+
+const getCompactFormat = once(
+  () =>
+    new Intl.NumberFormat(undefined, {
+      notation: 'compact',
+      maximumFractionDigits: 1,
+    }),
+);
+
+const getPercentFormat = once(
+  () =>
+    new Intl.NumberFormat(undefined, {
+      style: 'percent',
+      maximumFractionDigits: 1,
+    }),
+);
+
+const getShortDateFormat = once(
+  () => new Intl.DateTimeFormat(undefined, {month: 'short', day: 'numeric'}),
+);
+
+const getMonthYearFormat = once(
+  () => new Intl.DateTimeFormat(undefined, {month: 'short', year: 'numeric'}),
+);
+
+/**
+ * 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 function compactNumber(value: unknown): string {
+  const n = Number(value);
+  if (!Number.isFinite(n)) {
+    return String(value);
+  }
+  return getCompactFormat().format(n);
+}
+
+/**
+ * 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 function currency(symbol = '$'): (value: unknown) => string {
+  return (value: unknown) => {
+    const n = Number(value);
+    if (!Number.isFinite(n)) {
+      return String(value);
+    }
+    const sign = n < 0 ? '-' : '';
+    const abs = Math.abs(n);
+    const body =
+      abs >= 1000 ? getCompactFormat().format(abs) : abs.toLocaleString();
+    return `${sign}${symbol}${body}`;
+  };
+}
+
+/**
+ * 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 function percent(value: unknown): string {
+  const n = Number(value);
+  if (!Number.isFinite(n)) {
+    return String(value);
+  }
+  return getPercentFormat().format(n);
+}
+
+/**
+ * Coerce a value into a Date.
+ *
+ * Accepts a `Date`, epoch milliseconds (number or numeric string), or a date
+ * string (ISO 8601, RFC 2822, …). Returns an invalid Date for anything else so
+ * callers can pass the original value through unchanged.
+ *
+ * Date-only ISO strings (`YYYY-MM-DD`) are constructed at local midnight rather
+ * than the spec's UTC midnight, so the calendar day survives local formatting
+ * in negative-offset timezones (`"2024-01-05"` stays "Jan 5", not "Jan 4").
+ */
+function toDate(value: unknown): Date {
+  if (value instanceof Date) {
+    return value;
+  }
+  if (typeof value === 'number') {
+    return new Date(value);
+  }
+  if (typeof value === 'string') {
+    const s = value.trim();
+    if (s === '') {
+      return new Date(NaN);
+    }
+    const dateOnly = /^(\d{4})-(\d{2})-(\d{2})$/.exec(s);
+    if (dateOnly) {
+      const year = Number(dateOnly[1]);
+      const month = Number(dateOnly[2]);
+      const day = Number(dateOnly[3]);
+      const local = new Date(year, month - 1, day);
+      // Reject out-of-range parts (e.g. "2024-02-31") that the Date constructor
+      // would otherwise silently roll into a different day; treat them as
+      // invalid so the raw value passes through unchanged.
+      if (
+        local.getFullYear() !== year ||
+        local.getMonth() !== month - 1 ||
+        local.getDate() !== day
+      ) {
+        return new Date(NaN);
+      }
+      return local;
+    }
+    const asNumber = Number(s);
+    return new Date(Number.isFinite(asNumber) ? asNumber : s);
+  }
+  return new Date(NaN);
+}
+
+/**
+ * Date formatter — short date (e.g. "Jan 5", "Mar 12").
+ */
+export function shortDate(value: unknown): string {
+  const d = toDate(value);
+  if (Number.isNaN(d.getTime())) {
+    return String(value);
+  }
+  return getShortDateFormat().format(d);
+}
+
+/**
+ * Date formatter — month/year (e.g. "Jan 2024", "Mar 2025").
+ */
+export function monthYear(value: unknown): string {
+  const d = toDate(value);
+  if (Number.isNaN(d.getTime())) {
+    return String(value);
+  }
+  return getMonthYearFormat().format(d);
+}

package/src/getChartColors.test.ts

@@ -0,0 +1,114 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, expect, it} from 'vitest';
+import {
+  getChartColors,
+  getChartColorsFromResolver,
+  type TokenResolver,
+} from './getChartColors';
+import {pharosTheme} from '../../themes/pharos/src/pharosTheme';
+
+// A fake resolver with a hand-picked greyscale ramp so interpolated values are
+// easy to verify by hand: 0x00, 0x40, 0x80, 0xC0, 0xFF from step 5 → 1.
+const RAMP: Record<string, string> = {
+  '--color-data-gray-5': '#000000',
+  '--color-data-gray-4': '#404040',
+  '--color-data-gray-3': '#808080',
+  '--color-data-gray-2': '#C0C0C0',
+  '--color-data-gray-1': '#FFFFFF',
+};
+
+const resolve: TokenResolver = name => RAMP[name] ?? `resolved(${name})`;
+
+describe('getChartColorsFromResolver', () => {
+  it('returns exact token stops when n <= ramp length', () => {
+    const colors = getChartColorsFromResolver(resolve);
+    expect(colors.sequential.gray(5)).toEqual([
+      '#000000',
+      '#404040',
+      '#808080',
+      '#C0C0C0',
+      '#FFFFFF',
+    ]);
+  });
+
+  it('interpolates between stops when n > ramp length', () => {
+    const colors = getChartColorsFromResolver(resolve);
+    // n=9 over 5 stops: odd indices land halfway between adjacent stops.
+    expect(colors.sequential.gray(9)).toEqual([
+      '#000000',
+      '#202020',
+      '#404040',
+      '#606060',
+      '#808080',
+      '#A0A0A0',
+      '#C0C0C0',
+      '#E0E0E0',
+      '#FFFFFF',
+    ]);
+  });
+
+  it('falls back to the nearer endpoint when interpolating non-hex stops', () => {
+    const colors = getChartColorsFromResolver(name =>
+      name === '--color-data-gray-5' ? 'var(--custom)' : (RAMP[name] ?? ''),
+    );
+    const nine = colors.sequential.gray(9);
+    // The unparseable first stop is preserved verbatim at its slot and as the
+    // nearer endpoint of the first interpolated position.
+    expect(nine[0]).toBe('var(--custom)');
+    expect(nine[1]).toBe('#404040');
+  });
+
+  describe('alpha', () => {
+    it('applies opacity to a hex color', () => {
+      const colors = getChartColorsFromResolver(resolve);
+      expect(colors.alpha('#0064E0', 0.2)).toBe('rgba(0, 100, 224, 0.2)');
+    });
+
+    it('applies opacity to bare hex without the leading # (pre-#3739 behavior)', () => {
+      const colors = getChartColorsFromResolver(resolve);
+      expect(colors.alpha('0064E0', 0.2)).toBe('rgba(0, 100, 224, 0.2)');
+    });
+
+    it('applies opacity to rgba() input, overriding its alpha', () => {
+      const colors = getChartColorsFromResolver(resolve);
+      expect(colors.alpha('rgba(0, 100, 224, 0.9)', 0.2)).toBe(
+        'rgba(0, 100, 224, 0.2)',
+      );
+    });
+
+    it('clamps out-of-range opacity and defaults non-finite opacity to 1', () => {
+      const colors = getChartColorsFromResolver(resolve);
+      expect(colors.alpha('#000000', 2)).toBe('#000000');
+      expect(colors.alpha('#000000', -1)).toBe('rgba(0, 0, 0, 0)');
+      expect(colors.alpha('#000000', NaN)).toBe('#000000');
+    });
+
+    it('preserves unparseable input unchanged', () => {
+      const colors = getChartColorsFromResolver(resolve);
+      expect(colors.alpha('var(--color-accent)', 0.5)).toBe(
+        'var(--color-accent)',
+      );
+    });
+  });
+});
+
+describe('getChartColors with the Pharos theme', () => {
+  // Brand order: azul, roxo, laranja, amarelo, chumbo. Dark mode lifts azul,
+  // roxo and chumbo for contrast on the dark surfaces.
+  it.each([
+    ['light', ['#034694', '#7C51A1', '#F26641', '#FAA61A', '#383838']],
+    ['dark', ['#6BA3F5', '#A67BC4', '#F26641', '#FAA61A', '#D4D4D4']],
+  ] as const)('follows the brand categorical order (%s)', (mode, expected) => {
+    const colors = getChartColors(pharosTheme, mode);
+    expect(colors.categorical(5).map(c => c.toUpperCase())).toEqual(expected);
+  });
+
+  it('only reaches the core extra slots after the five brand series', () => {
+    const light = getChartColors(pharosTheme, 'light').categorical(6);
+    expect(light[5]).not.toBe(light[0]);
+    expect(light.slice(0, 5).map(c => c.toUpperCase())).not.toContain(
+      light[5].toUpperCase(),
+    );
+  });
+});

package/src/getChartColors.ts

@@ -0,0 +1,282 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file getChartColors.ts
+ * @output Pure function to resolve chart colors from a theme — no React required
+ * @position Foundation utility; consumed by useChartColors and non-React contexts
+ *
+ * Takes a token resolver function (or a defined theme + mode) and returns
+ * the full chart colors API. The useChartColors hook wraps this.
+ *
+ * Palettes degrade gracefully for any count: the categorical scale wraps
+ * around its slots, and the sequential/diverging scales pick hand-tuned token
+ * stops when enough exist and interpolate across the ramp when more are asked
+ * for. The theme entry point resolves through the canonical token resolver, so
+ * data tokens fall back to their defaults even when a theme doesn't override
+ * them.
+ */
+
+import {resolveThemeTokens, type DefinedTheme} from '@pharos-ds/core/theme';
+import {
+  parseHex,
+  parseColor,
+  formatHex,
+  formatColor,
+} from '@pharos-ds/core/utils';
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/** Hue names available in the sequential ramps */
+export type SequentialHue =
+  | 'blue'
+  | 'shamrock'
+  | 'orange'
+  | 'pink'
+  | 'purple'
+  | 'red'
+  | 'teal'
+  | 'yellow'
+  | 'gray';
+
+/** The chart colors API returned by both getChartColors and useChartColors */
+export interface ChartColorsAPI {
+  categorical(n: number): string[];
+  sequential: Record<SequentialHue, (n: number) => string[]>;
+  diverging: {
+    positiveNegative(n: number): string[];
+    coldHot(n: number): string[];
+    custom(
+      neg: SequentialHue,
+      pos: SequentialHue,
+      n: number,
+      midpoint?: string,
+    ): string[];
+  };
+  semantic: {
+    positive: string;
+    negative: string;
+    warning: string;
+    neutral: string;
+  };
+  /** Structural colors for chart chrome — axes, grid, ticks, labels */
+  structural: {
+    axis: string;
+    grid: string;
+    tick: string;
+    label: string;
+  };
+  alpha(hex: string, opacity: number): string;
+}
+
+/** A function that resolves a token name to its current value */
+export type TokenResolver = (name: string) => string;
+
+// =============================================================================
+// Internals
+// =============================================================================
+
+const CATEGORICAL_TOKENS = [
+  '--color-data-categorical-blue',
+  '--color-data-categorical-purple',
+  '--color-data-categorical-orange',
+  '--color-data-categorical-yellow',
+  '--color-data-categorical-gray',
+  '--color-data-categorical-green',
+  '--color-data-categorical-pink',
+  '--color-data-categorical-cyan',
+  '--color-data-categorical-red',
+  '--color-data-categorical-teal',
+  '--color-data-categorical-brown',
+  '--color-data-categorical-indigo',
+] as const;
+
+const SEQUENTIAL_HUES: SequentialHue[] = [
+  'blue',
+  'shamrock',
+  'orange',
+  'pink',
+  'purple',
+  'red',
+  'teal',
+  'yellow',
+  'gray',
+];
+
+/** Interpolate between two hex colors in sRGB. Non-hex input falls back to the nearer endpoint. */
+function lerpHex(a: string, b: string, t: number): string {
+  const ca = parseHex(a);
+  const cb = parseHex(b);
+  if (ca === null || cb === null) {
+    return t < 0.5 ? a : b;
+  }
+  const mix = (x: number, y: number): number => x + (y - x) * t;
+  return formatHex(mix(ca.r, cb.r), mix(ca.g, cb.g), mix(ca.b, cb.b));
+}
+
+/**
+ * Sample `n` colors from an ordered ramp of stops.
+ * - `n <= stops.length` → picks the nearest exact stops, preserving the
+ *   hand-tuned design-token values.
+ * - `n > stops.length` → interpolates across the ramp so any count is supported
+ *   instead of silently capping at the number of stops.
+ * - `n === 1` → the middle stop, a single representative tone.
+ */
+function sampleRamp(stops: string[], n: number): string[] {
+  const len = stops.length;
+  // A non-finite count (e.g. Infinity) would make the Array.from calls below
+  // attempt a ~2**53 element allocation and hang, so treat it as empty.
+  if (!Number.isFinite(n) || n <= 0 || len === 0) {
+    return [];
+  }
+  if (n === 1) {
+    return [stops[Math.floor((len - 1) / 2)]];
+  }
+  if (len === 1) {
+    return Array.from({length: n}, () => stops[0]);
+  }
+  if (n <= len) {
+    return Array.from(
+      {length: n},
+      (_, i) => stops[Math.round((i * (len - 1)) / (n - 1))],
+    );
+  }
+  return Array.from({length: n}, (_, i) => {
+    const t = (i * (len - 1)) / (n - 1);
+    const lo = Math.floor(t);
+    const frac = t - lo;
+    return frac === 0 ? stops[lo] : lerpHex(stops[lo], stops[lo + 1], frac);
+  });
+}
+
+/**
+ * Apply an opacity to a concrete CSS color (hex — with or without the leading
+ * `#` — `rgb()`/`rgba()`, named). The `opacity` argument always wins over any
+ * alpha already in the color. Unparseable input (e.g. `var()`) is returned
+ * unchanged.
+ */
+function hexAlpha(hex: string, opacity: number): string {
+  // parseColor requires the `#` for hex; fall back to parseHex so bare hex
+  // strings (`0064E0`) keep working as they did before #3739.
+  const rgba = parseColor(hex) ?? parseHex(hex);
+  if (rgba === null) {
+    return hex;
+  }
+  const a = Number.isFinite(opacity) ? Math.max(0, Math.min(1, opacity)) : 1;
+  return formatColor({...rgba, a});
+}
+
+// =============================================================================
+// Public API
+// =============================================================================
+
+/**
+ * Build chart colors from a token resolver function.
+ * This is the lowest-level API — pass any function that maps token names to values.
+ */
+export function getChartColorsFromResolver(
+  resolve: TokenResolver,
+): ChartColorsAPI {
+  const categorical = CATEGORICAL_TOKENS.map(t => resolve(t));
+
+  const ramp = (hue: SequentialHue): string[] =>
+    [5, 4, 3, 2, 1].map(step => resolve(`--color-data-${hue}-${step}`));
+
+  const gray1 = resolve('--color-data-gray-1');
+
+  function buildDiverging(
+    negHue: SequentialHue,
+    posHue: SequentialHue,
+    n: number,
+    midpoint: string = gray1,
+  ): string[] {
+    if (n <= 0) {
+      return [];
+    }
+    if (n === 1) {
+      return [midpoint];
+    }
+    const half = Math.floor(n / 2);
+    const hasCenter = n % 2 === 1;
+    const negSide = sampleRamp(ramp(negHue), half);
+    const posSide = sampleRamp(ramp(posHue), half).reverse();
+    if (hasCenter) {
+      return [...negSide, midpoint, ...posSide];
+    }
+    return [...negSide, ...posSide];
+  }
+
+  return {
+    categorical(n: number): string[] {
+      // A non-finite count (e.g. Infinity) would make the wrap-around Array.from
+      // below attempt a ~2**53 element allocation and hang, so treat it as empty.
+      if (!Number.isFinite(n) || n <= 0 || categorical.length === 0) {
+        return [];
+      }
+      // Wrap around the palette so any series count gets a deterministic color.
+      return Array.from(
+        {length: n},
+        (_, i) => categorical[i % categorical.length],
+      );
+    },
+
+    sequential: Object.fromEntries(
+      SEQUENTIAL_HUES.map(hue => [
+        hue,
+        (n: number): string[] => sampleRamp(ramp(hue), n),
+      ]),
+    ) as Record<SequentialHue, (n: number) => string[]>,
+
+    diverging: {
+      positiveNegative: (n: number) => buildDiverging('shamrock', 'red', n),
+      coldHot: (n: number) => buildDiverging('blue', 'red', n),
+      custom: (
+        neg: SequentialHue,
+        pos: SequentialHue,
+        n: number,
+        mid?: string,
+      ) => buildDiverging(neg, pos, n, mid),
+    },
+
+    semantic: {
+      positive: resolve('--color-data-categorical-green'),
+      negative: resolve('--color-data-categorical-red'),
+      warning: resolve('--color-data-categorical-orange'),
+      neutral: resolve('--color-data-neutral'),
+    },
+
+    structural: {
+      axis: resolve('--color-border-emphasized'),
+      grid: resolve('--color-border'),
+      tick: resolve('--color-border-emphasized'),
+      label: resolve('--color-text-secondary'),
+    },
+
+    alpha: hexAlpha,
+  };
+}
+
+/**
+ * Build chart colors from a defined theme and color mode.
+ *
+ * Use this in non-React contexts — WebGL setup, SSR, tests, Node scripts.
+ *
+ * Resolves through the canonical theme token resolver, so data tokens fall back
+ * to their defaults when the theme doesn't override them, and both
+ * `light-dark()` strings and `[light, dark]` tuples are handled for `mode`.
+ *
+ * @example
+ * ```
+ * import { neutralTheme } from '@pharos-ds/theme-neutral';
+ * const colors = getChartColors(neutralTheme, 'light');
+ * colors.categorical(5)
+ * ```
+ */
+export function getChartColors(
+  theme: DefinedTheme,
+  mode: 'light' | 'dark' = 'light',
+): ChartColorsAPI {
+  const tokens = resolveThemeTokens(theme, {mode});
+  return getChartColorsFromResolver(name => tokens[name] ?? '');
+}

package/src/index.ts

@@ -0,0 +1,88 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+export {Chart, type ChartProps} from './Chart';
+export {ChartAxis, type ChartAxisProps} from './ChartAxis';
+export {ChartGrid, type ChartGridProps} from './ChartGrid';
+export {
+  ChartLegend,
+  type ChartLegendProps,
+  type LegendPosition,
+  type LegendAlignment,
+} from './ChartLegend';
+export {type LegendItem} from './legend';
+export {
+  ChartSwatch,
+  swatchVariantForType,
+  type ChartSwatchProps,
+  type ChartSwatchVariant,
+} from './ChartSwatch';
+export {
+  ChartTooltip,
+  type ChartTooltipProps,
+  type ChartTooltipPlacement,
+} from './ChartTooltip';
+export {type TooltipSeriesValue} from './tooltip';
+export {
+  bar,
+  line,
+  dot,
+  area,
+  band,
+  candlestick,
+  errorBar,
+  referenceLine,
+  dotGL,
+  dotGLInteractive,
+  heatmapGL,
+  streamGL,
+} from './marks';
+export type {
+  BarOptions,
+  LineOptions,
+  DotOptions,
+  AreaOptions,
+  BandOptions,
+  CandlestickOptions,
+  ErrorBarOptions,
+  ReferenceLineOptions,
+  DotGLOptions,
+  DotGLInteractiveOptions,
+  HeatmapGLOptions,
+  StreamGLOptions,
+  StreamGLHandle,
+} from './marks';
+export {useChart} from './ChartContext';
+export type {
+  SeriesDef,
+  ChartContext,
+  ChartPointerEvent,
+  ResolvedPoint,
+  ResolvedPositions,
+  SeriesContext,
+  ChartMargin,
+  ChartScale,
+  YBaseline,
+  ColorAccessor,
+} from './types';
+
+// Color palette — theme-aware data-visualization colors
+export {useChartColors} from './useChartColors';
+export {
+  getChartColors,
+  getChartColorsFromResolver,
+  type ChartColorsAPI,
+  type SequentialHue,
+  type TokenResolver,
+} from './getChartColors';
+
+// Tick / value formatters
+export {
+  compactNumber,
+  currency,
+  percent,
+  shortDate,
+  monthYear,
+} from './formatters';
+
+// Scale utilities
+export {isBandScale, xPixel} from './utils';