@cdx-ui/components 0.3.4 → 0.3.6

package/src/components/chart/format.ts

@@ -0,0 +1,95 @@
+import { formatNumber } from '@cdx-ui/formatters';
+import type {
+  ChartLocaleText,
+  ChartSummaryCategory,
+  ChartSummaryValue,
+  ChartTrend,
+  ChartValueFormatter,
+} from './types';
+
+interface HasValueFormatter {
+  readonly valueFormatter?: ChartValueFormatter;
+}
+
+function namedValue(value: ChartSummaryValue): string {
+  return value.label.length > 0 ? `${value.label} ${value.formattedValue}` : value.formattedValue;
+}
+
+function categoryText(category: ChartSummaryCategory): string {
+  return `${category.label} ${category.values.map(namedValue).join(', ')}`;
+}
+
+export const defaultChartLocaleText: ChartLocaleText = {
+  noData: 'No data',
+  noValue: 'No value',
+  defaultSeriesLabel: 'Value',
+  waterfallIncrease: 'Increase',
+  waterfallDecrease: 'Decrease',
+  trend: ({ direction, formattedDelta, comparisonLabel }: ChartTrend) => {
+    const from = comparisonLabel.length > 0 ? ` from ${comparisonLabel}` : '';
+    return direction === 'none' ? `no change${from}` : `${direction} ${formattedDelta}${from}`;
+  },
+  barChartSummary: (categories) =>
+    categories.length === 0
+      ? 'Bar chart. No data.'
+      : `Bar chart. ${categories.map(categoryText).join('; ')}.`,
+  lineChartSummary: (latest) =>
+    latest === null ? 'Line chart. No data.' : `Line chart. ${categoryText(latest)}.`,
+  pieChartSummary: (slices) =>
+    slices.length === 0
+      ? 'Pie chart. No data.'
+      : `Pie chart. ${slices.map(namedValue).join(', ')}.`,
+};
+
+/** Consumer strings over the English defaults. `undefined` entries keep the default. */
+export function resolveChartLocaleText(localeText?: Partial<ChartLocaleText>): ChartLocaleText {
+  if (localeText === undefined) {
+    return defaultChartLocaleText;
+  }
+  const overrides = Object.entries(localeText as Record<string, unknown>).filter(
+    ([, value]) => value !== undefined,
+  );
+  return { ...defaultChartLocaleText, ...Object.fromEntries(overrides) } as ChartLocaleText;
+}
+
+/** Up to two fraction digits, without trailing zeros: `3`, `2.5`, `1,234.56`. */
+export function formatChartNumber(value: number | null, locale?: string): string {
+  if (value === null || !Number.isFinite(value)) {
+    return '';
+  }
+  const hundredths = Math.round(Math.abs(value) * 100);
+  const decimalPlaces = hundredths % 100 === 0 ? 0 : hundredths % 10 === 0 ? 1 : 2;
+  return formatNumber(value, { locale, decimalPlaces });
+}
+
+const percentFormatters = new Map<string, Intl.NumberFormat>();
+
+/** A 0–1 share as a whole percent for `locale`: `0.46` → `46%`. */
+export function formatChartPercent(share: number, locale?: string): string {
+  if (!Number.isFinite(share)) {
+    return '';
+  }
+  // Without a locale, match the `@cdx-ui/formatters` default that numbers use, not the device locale.
+  if (locale === undefined) {
+    return `${formatNumber(Math.round(share * 100), { decimalPlaces: 0 })}%`;
+  }
+  let formatter = percentFormatters.get(locale);
+  if (formatter === undefined) {
+    formatter = new Intl.NumberFormat(locale, { style: 'percent', maximumFractionDigits: 0 });
+    percentFormatters.set(locale, formatter);
+  }
+  return formatter.format(share);
+}
+
+export function defaultChartValueFormatter(locale?: string): ChartValueFormatter {
+  return (value) => formatChartNumber(value, locale);
+}
+
+/** Series formatter, then axis formatter, then the `locale` default. */
+export function resolveValueFormatter(
+  series: HasValueFormatter | null | undefined,
+  axis: HasValueFormatter | null | undefined,
+  locale?: string,
+): ChartValueFormatter {
+  return series?.valueFormatter ?? axis?.valueFormatter ?? defaultChartValueFormatter(locale);
+}

package/src/components/chart/index.ts

@@ -0,0 +1,24 @@
+export type {
+  ChartAxis,
+  ChartAxisPosition,
+  ChartGrid,
+  ChartLocaleText,
+  ChartReferenceLine,
+  ChartScaleType,
+  ChartSelectedItem,
+  ChartSeriesBase,
+  ChartSeriesCommon,
+  ChartSize,
+  ChartSizeProps,
+  ChartSummaryCategory,
+  ChartSummaryValue,
+  ChartTooltipContent,
+  ChartTooltipItem,
+  ChartTooltipProps,
+  ChartTrend,
+  ChartTrendDirection,
+  ChartValueFormatter,
+  ChartValueFormatterContext,
+  ChartValueLocation,
+} from './types';
+export type { ChartColor, ChartPalette } from './palette';

package/src/components/chart/motion.ts

@@ -0,0 +1,98 @@
+import { useEffect } from 'react';
+import {
+  Easing,
+  useReducedMotion,
+  useSharedValue,
+  withTiming,
+  type SharedValue,
+} from 'react-native-reanimated';
+import { useCombinedAnimationDisabledState, type AnimationRootDisableAll } from '../../animation';
+
+export const CHART_MOTION_DURATION = 600;
+const CHART_MOTION_EASING = Easing.out(Easing.cubic);
+
+export interface ChartMorph {
+  readonly from: SharedValue<number[]>;
+  readonly to: SharedValue<number[]>;
+  readonly progress: SharedValue<number>;
+}
+
+/** Off for `'disable-all'`, an ancestor or global `disable-all`, and Reduce Motion. */
+export function useChartMotionEnabled(animation: AnimationRootDisableAll | undefined): boolean {
+  const disabled = useCombinedAnimationDisabledState(animation);
+  const reducedMotion = useReducedMotion();
+  return !disabled && !reducedMotion;
+}
+
+/**
+ * Non-finite entries mark gaps: they snap to the target instead of tweening.
+ * Vectors of different lengths cannot be paired, so the target wins outright.
+ */
+export function lerpVector(from: readonly number[], to: readonly number[], t: number): number[] {
+  'worklet';
+  const out: number[] = [];
+  const paired = from.length === to.length;
+  for (let index = 0; index < to.length; index += 1) {
+    const end = to[index];
+    const start = paired ? from[index] : end;
+    out.push(Number.isFinite(start) && Number.isFinite(end) ? start + (end - start) * t : end);
+  }
+  return out;
+}
+
+function parseSignature(signature: string): number[] {
+  return signature.length === 0 ? [] : signature.split(',').map(Number);
+}
+
+/**
+ * Tweens a numeric geometry vector on the UI thread. Mounts at `initial` and runs to
+ * `target`; later targets start from wherever the previous tween currently is. When the
+ * vector changes length (points or slices added/removed) the entry replays from `initial`.
+ */
+export function useChartMorph(
+  target: readonly number[],
+  initial: readonly number[],
+  enabled: boolean,
+): ChartMorph {
+  const from = useSharedValue<number[]>(enabled ? [...initial] : [...target]);
+  const to = useSharedValue<number[]>([...target]);
+  const progress = useSharedValue(enabled ? 0 : 1);
+  const signature = target.join(',');
+  const initialSignature = initial.join(',');
+
+  useEffect(() => {
+    const next = parseSignature(signature);
+    if (!enabled) {
+      from.set(next);
+      to.set(next);
+      progress.set(1);
+      return;
+    }
+    const current = lerpVector(from.get(), to.get(), progress.get());
+    from.set(current.length === next.length ? current : parseSignature(initialSignature));
+    to.set(next);
+    progress.set(0);
+    progress.set(withTiming(1, { duration: CHART_MOTION_DURATION, easing: CHART_MOTION_EASING }));
+  }, [signature, initialSignature, enabled, from, to, progress]);
+
+  return { from, to, progress };
+}
+
+/**
+ * 0 → 1 on mount and whenever `replayKey` changes. Labels sit on animated geometry, so they
+ * stay hidden until the morph is mostly done, then fade in at the final position.
+ */
+export function useChartEntrance(enabled: boolean, replayKey = ''): SharedValue<number> {
+  const progress = useSharedValue(enabled ? 0 : 1);
+
+  useEffect(() => {
+    if (!enabled) {
+      progress.set(1);
+      return;
+    }
+    progress.set(0);
+    progress.set(withTiming(1, { duration: CHART_MOTION_DURATION, easing: CHART_MOTION_EASING }));
+  }, [enabled, replayKey, progress]);
+
+  return progress;
+}

package/src/components/chart/palette.tsx

@@ -0,0 +1,247 @@
+import { useId } from 'react';
+import { Defs, LinearGradient, Stop } from 'react-native-svg';
+import { useCSSVariable, useResolveClassNames } from 'uniwind';
+
+/** Light-theme chart tokens, used when Uniwind has no CSS context (Jest). */
+const CHART_FALLBACKS = {
+  simple: '#5b91de',
+  simpleSecondary: '#162e49',
+  simpleTertiary: '#3b6399',
+  categorical: ['#155dfc', '#f54900', '#009689', '#e60076', '#9810fa', '#525252'] as const,
+  danger: '#c10007',
+  warning: '#ffb900',
+  success: '#00a63e',
+  info: '#0069a8',
+} as const;
+
+function toColor(value: string | number | undefined, fallback: string): string {
+  if (typeof value === 'string' && value.length > 0) {
+    return value;
+  }
+  return fallback;
+}
+
+export function useChartSimpleColor(): string {
+  const value = useCSSVariable('--color-chart-simple-primary');
+  return toColor(value, CHART_FALLBACKS.simple);
+}
+
+/**
+ * A Forge color token by name: `simple-*` and `categorical-*` resolve
+ * `--color-chart-<name>`, severity names resolve `--color-surface-<name>-strong`.
+ * Overrides take a name, not a CSS color, so FI themes and dark mode recolor every chart.
+ */
+export type ChartColor =
+  | 'danger'
+  | 'warning'
+  | 'success'
+  | 'info'
+  | 'simple-primary'
+  | 'simple-secondary'
+  | 'simple-tertiary'
+  | 'categorical-1'
+  | 'categorical-2'
+  | 'categorical-3'
+  | 'categorical-4'
+  | 'categorical-5'
+  | 'categorical-6';
+
+export type ChartColorPaints = Readonly<Record<ChartColor, string>>;
+
+const warnedChartColors = new Set<string>();
+
+export function resolveChartColor(
+  color: ChartColor | undefined,
+  paints: ChartColorPaints,
+): string | undefined {
+  if (color === undefined) return undefined;
+  const paint = paints[color] as string | undefined;
+  if (paint === undefined && __DEV__ && !warnedChartColors.has(color)) {
+    warnedChartColors.add(color);
+    console.warn(
+      `[Chart] Unknown color "${String(color)}". Pass a ChartColor token name, not a CSS ` +
+        'color; the default series color is used instead.',
+    );
+  }
+  return paint;
+}
+
+export function useChartColorPaints(): ChartColorPaints {
+  const simple = useChartSimpleColor();
+  const secondary = toColor(
+    useCSSVariable('--color-chart-simple-secondary'),
+    CHART_FALLBACKS.simpleSecondary,
+  );
+  const tertiary = toColor(
+    useCSSVariable('--color-chart-simple-tertiary'),
+    CHART_FALLBACKS.simpleTertiary,
+  );
+  const danger = toColor(useCSSVariable('--color-surface-danger-strong'), CHART_FALLBACKS.danger);
+  const warning = toColor(
+    useCSSVariable('--color-surface-warning-strong'),
+    CHART_FALLBACKS.warning,
+  );
+  const success = toColor(
+    useCSSVariable('--color-surface-success-strong'),
+    CHART_FALLBACKS.success,
+  );
+  const info = toColor(useCSSVariable('--color-surface-info-strong'), CHART_FALLBACKS.info);
+  const palette = useChartPalette();
+  return {
+    danger,
+    warning,
+    success,
+    info,
+    'simple-primary': simple,
+    'simple-secondary': secondary,
+    'simple-tertiary': tertiary,
+    'categorical-1': palette[0] ?? CHART_FALLBACKS.categorical[0],
+    'categorical-2': palette[1] ?? CHART_FALLBACKS.categorical[1],
+    'categorical-3': palette[2] ?? CHART_FALLBACKS.categorical[2],
+    'categorical-4': palette[3] ?? CHART_FALLBACKS.categorical[3],
+    'categorical-5': palette[4] ?? CHART_FALLBACKS.categorical[4],
+    'categorical-6': palette[5] ?? CHART_FALLBACKS.categorical[5],
+  };
+}
+
+/**
+ * SVG text cannot take `className`, so typography tokens are resolved here.
+ * `useResolveClassNames` converts rem to px with the consumer's rem base; web
+ * may return rem strings, which fall back to the light-theme pixel size.
+ */
+function toPx(value: string | number | undefined, fallbackPx: number): number {
+  if (typeof value === 'number') {
+    return Number.isFinite(value) ? value : fallbackPx;
+  }
+  if (typeof value !== 'string') return fallbackPx;
+  const trimmed = value.trim();
+  if (!/^-?\d*\.?\d+(px)?$/.test(trimmed)) return fallbackPx;
+  return parseFloat(trimmed);
+}
+
+export interface ChartChrome {
+  readonly grid: string;
+  readonly label: string;
+  readonly surface: string;
+  readonly fontFamily: string;
+  /** `text-xs` — axis ticks and category labels. */
+  readonly labelSize: number;
+  /** `text-2xs` — values, reference and marker captions. */
+  readonly captionSize: number;
+}
+
+export function useChartChrome(): ChartChrome {
+  const grid = useCSSVariable('--color-stroke-secondary');
+  const label = useCSSVariable('--color-content-primary');
+  const surface = useCSSVariable('--color-surface-primary');
+  const fontFamily = useCSSVariable('--font-body');
+  const labelText = useResolveClassNames('text-xs');
+  const captionText = useResolveClassNames('text-2xs');
+  return {
+    grid: toColor(grid, '#e9e9e9'),
+    label: toColor(label, '#1b1c1d'),
+    surface: toColor(surface, '#ffffff'),
+    fontFamily: toColor(fontFamily, 'Inter'),
+    labelSize: toPx(labelText.fontSize, 12),
+    captionSize: toPx(captionText.fontSize, 10),
+  };
+}
+
+/**
+ * Resolved `categorical-1`…`6` paints, in slot order. Pie slices and charts past
+ * three series cycle them.
+ */
+export function useChartPalette(): readonly string[] {
+  const slot1 = useCSSVariable('--color-chart-categorical-1');
+  const slot2 = useCSSVariable('--color-chart-categorical-2');
+  const slot3 = useCSSVariable('--color-chart-categorical-3');
+  const slot4 = useCSSVariable('--color-chart-categorical-4');
+  const slot5 = useCSSVariable('--color-chart-categorical-5');
+  const slot6 = useCSSVariable('--color-chart-categorical-6');
+
+  return [
+    toColor(slot1, CHART_FALLBACKS.categorical[0]),
+    toColor(slot2, CHART_FALLBACKS.categorical[1]),
+    toColor(slot3, CHART_FALLBACKS.categorical[2]),
+    toColor(slot4, CHART_FALLBACKS.categorical[3]),
+    toColor(slot5, CHART_FALLBACKS.categorical[4]),
+    toColor(slot6, CHART_FALLBACKS.categorical[5]),
+  ];
+}
+
+/**
+ * `auto` keeps up to three series in the FI brand family and moves the whole chart to
+ * `categorical-1`…`6` past that, so one chart never mixes the two families.
+ * `categorical` always uses them.
+ */
+export type ChartPalette = 'auto' | 'categorical';
+
+export type ChartSeriesKind = 'bar' | 'line';
+
+/**
+ * Bars alternate light, dark, mid so adjacent bars don't read as a ramp. Lines step
+ * primary → tertiary → secondary so a two-line chart pairs neighboring brand steps.
+ */
+const SIMPLE_SERIES: Record<ChartSeriesKind, readonly ChartColor[]> = {
+  bar: ['simple-primary', 'simple-secondary', 'simple-tertiary'],
+  line: ['simple-primary', 'simple-tertiary', 'simple-secondary'],
+};
+
+const CATEGORICAL_SERIES: readonly ChartColor[] = [
+  'categorical-1',
+  'categorical-2',
+  'categorical-3',
+  'categorical-4',
+  'categorical-5',
+  'categorical-6',
+];
+
+/** Default color for a series. A series `color` still wins. */
+export function chartSeriesColor(
+  seriesIndex: number,
+  seriesCount: number,
+  palette: ChartPalette,
+  kind: ChartSeriesKind,
+): ChartColor {
+  const simple = SIMPLE_SERIES[kind];
+  const ramp = palette === 'auto' && seriesCount <= simple.length ? simple : CATEGORICAL_SERIES;
+  return ramp[seriesIndex % ramp.length] ?? 'simple-primary';
+}
+
+export function useChartGradientId(prefix: string): string {
+  return `${prefix}-${useId().replace(/[^a-zA-Z0-9_-]/g, '')}`;
+}
+
+export function chartFillUrl(idPrefix: string, index: number): string {
+  return `url(#${idPrefix}-${String(index)})`;
+}
+
+export function ChartLinearFills({
+  idPrefix,
+  colors,
+  x2,
+  y2,
+}: {
+  readonly idPrefix: string;
+  readonly colors: readonly string[];
+  readonly x2: string;
+  readonly y2: string;
+}) {
+  return (
+    <Defs>
+      {colors.map((color, index) => (
+        <LinearGradient
+          key={`${idPrefix}-${String(index)}`}
+          id={`${idPrefix}-${String(index)}`}
+          x1="0%"
+          y1="0%"
+          x2={x2}
+          y2={y2}
+        >
+          <Stop offset="0%" stopColor={color} />
+          <Stop offset="100%" stopColor={color} />
+        </LinearGradient>
+      ))}
+    </Defs>
+  );
+}

package/src/components/chart/size.ts

@@ -0,0 +1,21 @@
+import type { ChartSize } from './types';
+
+/** Plot boxes. Heights match the spacing scale (`size-40`…`size-64`). */
+export const CHART_DIMENSIONS = {
+  sm: { width: 256, height: 160 },
+  md: { width: 308, height: 192 },
+  lg: { width: 360, height: 224 },
+  xl: { width: 410, height: 256 },
+} as const satisfies Record<ChartSize, { readonly width: number; readonly height: number }>;
+
+export function resolveChartBox(
+  size: ChartSize | undefined,
+  width?: number,
+  height?: number,
+): { readonly width: number; readonly height: number } {
+  const preset = CHART_DIMENSIONS[size ?? 'lg'];
+  return {
+    width: width ?? preset.width,
+    height: height ?? preset.height,
+  };
+}

package/src/components/chart/ticks.ts

@@ -0,0 +1,53 @@
+/** Rounds away float drift at the step's precision, so steps below 0.01 stay distinct. */
+function roundToStep(value: number, step: number): number {
+  const decimals = Math.min(20, Math.max(2, -Math.floor(Math.log10(step)) + 1));
+  const rounded = Number(value.toFixed(decimals));
+  return Object.is(rounded, -0) ? 0 : rounded;
+}
+
+function niceNumber(span: number, round: boolean): number {
+  if (span <= 0 || !Number.isFinite(span)) {
+    return 1;
+  }
+  const exponent = Math.floor(Math.log10(span));
+  const fraction = span / 10 ** exponent;
+  let niceFraction: number;
+  if (round) {
+    if (fraction < 1.5) {
+      niceFraction = 1;
+    } else if (fraction < 3) {
+      niceFraction = 2;
+    } else if (fraction < 7) {
+      niceFraction = 5;
+    } else {
+      niceFraction = 10;
+    }
+  } else if (fraction <= 1) {
+    niceFraction = 1;
+  } else if (fraction <= 2) {
+    niceFraction = 2;
+  } else if (fraction <= 5) {
+    niceFraction = 5;
+  } else {
+    niceFraction = 10;
+  }
+  return niceFraction * 10 ** exponent;
+}
+
+/** Evenly spaced, readable ticks that cover `min`–`max` in about `count` steps. */
+export function niceTicks(min: number, max: number, count: number): number[] {
+  if (!Number.isFinite(min) || !Number.isFinite(max)) {
+    return [];
+  }
+  const tickCount = Math.max(2, count);
+  const span = niceNumber(max - min, false);
+  const step = niceNumber(span / (tickCount - 1), true);
+  const niceMin = Math.floor(min / step) * step;
+  const niceMax = Math.ceil(max / step) * step;
+  const ticks: number[] = [];
+  const last = niceMax + step / 2;
+  for (let value = niceMin; value <= last; value += step) {
+    ticks.push(roundToStep(value, step));
+  }
+  return ticks;
+}