@cdx-ui/components 0.3.5 → 0.3.7

package/src/components/BarChart/index.tsx

@@ -0,0 +1,1417 @@
+/* SVG `x`/`y` are paint coordinates. RN View `x`/`y` layout props are deprecated and share the name. */
+/* eslint-disable @typescript-eslint/no-deprecated */
+import {
+  forwardRef,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  type ForwardedRef,
+  type ReactElement,
+  type ReactNode,
+} from 'react';
+import {
+  ScrollView,
+  Text,
+  View,
+  type NativeScrollEvent,
+  type NativeSyntheticEvent,
+  type ViewProps,
+} from 'react-native';
+import Animated, { useAnimatedProps } from 'react-native-reanimated';
+import { G, Line, Path, Svg, Text as SvgText } from 'react-native-svg';
+import { dataAttributes, mergeDataAttributes } from '@cdx-ui/primitives';
+import { cn, useControllableState } from '@cdx-ui/utils';
+import type { AnimationRootDisableAll } from '../../animation';
+import {
+  ChartInspector,
+  ChartTooltipLayer,
+  expandHitBox,
+  type ChartInspectorTarget,
+} from '../chart/ChartInspector';
+import {
+  defaultChartValueFormatter,
+  formatChartPercent,
+  resolveChartLocaleText,
+  resolveValueFormatter,
+} from '../chart/format';
+import { HIDDEN_SVG_PROPS } from '../chart/hiddenSvgProps';
+import type {
+  ChartAxis,
+  ChartGrid,
+  ChartLocaleText,
+  ChartReferenceLine,
+  ChartSelectedItem,
+  ChartSeriesBase,
+  ChartSizeProps,
+  ChartSummaryCategory,
+  ChartTooltipContent,
+  ChartTooltipProps,
+  ChartValueFormatter,
+  ChartValueLocation,
+} from '../chart/types';
+import { useChartHostWidth } from '../chart/useChartHostWidth';
+import {
+  CHART_MOTION_DURATION,
+  useChartMorph,
+  useChartMotionEnabled,
+  lerpVector,
+} from '../chart/motion';
+import {
+  ChartLinearFills,
+  chartFillUrl,
+  chartSeriesColor,
+  resolveChartColor,
+  useChartChrome,
+  useChartColorPaints,
+  useChartGradientId,
+  useChartPalette,
+  useChartSimpleColor,
+  type ChartChrome,
+  type ChartPalette,
+} from '../chart/palette';
+import {
+  BAR_GAP_RATIO,
+  CATEGORY_GAP_RATIO,
+  barKeyboardNeighbor,
+  barPath,
+  barValueAnchor,
+  DEFAULT_STACK_GAP,
+  formatWaterfallBarValue,
+  isExpandAxis,
+  layoutBarChart,
+  overlayDelta,
+  readBarValue,
+  resolveBarChartContentSize,
+  resolveBarChartGutters,
+  resolveBarGroups,
+  stackedTotalAnchors,
+  waterfallValueAnchor,
+  type BarChartKind,
+  type BarChartLayout,
+  type BarChartOrientation,
+  type BarGeometrySeries,
+  type BarRect,
+  type BarStackOffset,
+} from './geometry';
+import {
+  BAR_RADIUS,
+  barChartLegendItemVariants,
+  barChartLegendLabelVariants,
+  barChartLegendVariants,
+  barChartRootVariants,
+  resolveBarChartBox,
+  type BarChartSize,
+} from './styles';
+
+const INACTIVE_OPACITY = 0.4;
+const DASH = '6 4';
+const SVG_OVERFLOW_VISIBLE = { overflow: 'visible' } as const;
+const LABEL_FADE_DURATION = 220;
+
+const AnimatedPath = Animated.createAnimatedComponent(Path);
+
+export type * from '../chart';
+export type { BarChartSize, BarStackOffset };
+
+/** Keys of `TRow` whose value is a boolean. */
+export type BarChartBooleanKey<TRow> = {
+  [K in keyof TRow]-?: TRow[K] extends boolean | undefined ? K : never;
+}[keyof TRow] &
+  string;
+
+/** Running-total series. Each row is a change, except rows flagged as totals. */
+export interface BarChartWaterfall<TRow> {
+  /**
+   * Row key whose `true` value marks a total bar, drawn from zero to the running total. A total
+   * row with a value on the first row sets the starting total; otherwise its value is ignored.
+   */
+  totalKey: BarChartBooleanKey<TRow>;
+}
+
+/** Draws this series as a thinner comparison bar beside another series' bar. */
+export interface BarChartOverlay {
+  /** `id` of the series this one is compared against. */
+  seriesId: string;
+}
+
+export interface BarChartSeries<TRow> extends ChartSeriesBase<TRow> {
+  /** Series type. Reserved for mixed charts; bar is the only type today. */
+  type?: 'bar';
+  /**
+   * Stack group id. Series with the same `stack` draw as one bar per category; different ids
+   * draw side by side. Omit to draw the series on its own.
+   */
+  stack?: string;
+  /**
+   * How the stack group piles its values. Set it on any one series in the group.
+   * `expand` scales each category to 100%.
+   * @default 'diverging'
+   */
+  stackOffset?: BarStackOffset;
+  /**
+   * Draws the series as a waterfall (running total). A waterfall series draws alone: other
+   * series are not plotted.
+   */
+  waterfall?: BarChartWaterfall<TRow>;
+  /**
+   * Draws the series as a thin comparison bar beside the series it names (this month versus last
+   * month). The pair draws alone, and the named series is announced with the change.
+   */
+  overlay?: BarChartOverlay;
+}
+
+export interface BarChartProps<TRow extends object = object> extends ViewProps, ChartSizeProps {
+  /** One object per category. Series and axes read it through `dataKey`. */
+  dataset: readonly TRow[];
+  /** Bars to draw. Each reads one numeric column through `dataKey`. */
+  series: readonly BarChartSeries<TRow>[];
+  /**
+   * Horizontal axis. In `vertical` layout it is the category (band) axis: `dataKey` names the
+   * category column, `position` (`'bottom'`, `'top'`, `'none'`) places its labels, and
+   * `tickLabelInterval` picks which labels draw. In `horizontal` layout it is the value axis.
+   * Only the first axis is used.
+   */
+  xAxis?: readonly ChartAxis<TRow>[];
+  /**
+   * Vertical axis. In `vertical` layout it is the value axis (`min`, `max`, `tickNumber`,
+   * `valueFormatter`; `position: 'none'` hides its ticks). In `horizontal` layout it is the
+   * category axis (`position` `'left'`, `'right'`, or `'none'`). Only the first axis is used.
+   */
+  yAxis?: readonly ChartAxis<TRow>[];
+  /**
+   * `vertical` grows bars up from the baseline. `horizontal` grows them to the right.
+   * @default 'vertical'
+   */
+  layout?: BarChartOrientation;
+  /**
+   * Hides the series legend under the chart. Waterfall charts never show one.
+   * @default false
+   */
+  hideLegend?: boolean;
+  /**
+   * Grid lines along the value axis: `horizontal` in `vertical` layout, `vertical` in
+   * `horizontal` layout. The other direction is not drawn. Omit to draw the value-axis lines;
+   * pass an object without that key set to `true` to hide them and keep only the baseline.
+   * @default { horizontal: true } (vertical layout), { vertical: true } (horizontal layout)
+   */
+  grid?: ChartGrid;
+  /**
+   * Default series colors. `auto` uses the FI brand family (`simple-primary`, `-secondary`,
+   * `-tertiary`) for up to three series and switches the whole chart to `categorical-1`…`6`
+   * past that. `categorical` always uses the categorical slots. A series `color` wins.
+   * @default 'auto'
+   */
+  palette?: ChartPalette;
+  /**
+   * Dashed guides at a value: horizontal on a vertical chart, vertical on a horizontal chart.
+   */
+  referenceLines?: readonly ChartReferenceLine[];
+  /**
+   * Keeps this `dataset` row full color and mutes the rest. Use with `barLabel` to label only
+   * that bar, like "this week" in a spending insight.
+   */
+  emphasizedIndex?: number;
+  /**
+   * Draws formatted values at the end of each bar (each stack's total when stacked).
+   * @default false
+   */
+  barLabel?: boolean;
+  /**
+   * Corner radius in pixels. `0` draws square bars.
+   * @default 6
+   */
+  borderRadius?: number;
+  /**
+   * Pixel gap between stacked segments. With a gap every segment is rounded; `0` joins them and
+   * rounds only the outer cap.
+   * @default 3
+   */
+  stackGap?: number;
+  /**
+   * Share of each category slot left empty around its bars, from `0` to `0.95`. Higher is
+   * thinner bars with more space between categories.
+   * @default 0.36
+   */
+  categoryGapRatio?: number;
+  /**
+   * Gap between side-by-side bars in one category, as a share of one bar's thickness.
+   * @default 0.5
+   */
+  barGapRatio?: number;
+  /**
+   * When the categories need more room than the visible box, scroll instead of
+   * squeezing bars. Vertical charts scroll sideways; horizontal charts scroll vertically.
+   * The value axis stays pinned. Turn off to pack every category into `width` / `height`.
+   * @default true
+   */
+  scrollable?: boolean;
+  /**
+   * How many categories fit in the viewport when `scrollable` is on. Omit to use a
+   * readable minimum band (~48px).
+   */
+  visiblePoints?: number;
+  /**
+   * Controlled selected bar: `seriesId` and the `dataset` row. `null` clears the selection while
+   * staying controlled.
+   */
+  selectedItem?: ChartSelectedItem;
+  /**
+   * Initial selected bar when `selectedItem` is omitted.
+   */
+  defaultSelectedItem?: ChartSelectedItem;
+  /**
+   * Called when a bar is pressed, with that bar, or with `null` when the selected bar is pressed
+   * again. Providing this, `selectedItem`, or `defaultSelectedItem` makes the chart selectable.
+   */
+  onSelectedItemChange?: (item: ChartSelectedItem) => void;
+  /**
+   * Tooltip on hover, keyboard focus, or tap. `axis` lists every series in the category, `item`
+   * only the bar under the pointer, `none` hides it. On web the plot is one tab stop. Tab /
+   * Shift+Tab move between categories and leave the chart after the last (or before the first)
+   * group. Arrow keys move along the category axis (and between series). Home and End jump to
+   * the first or last category. Enter or Space selects. Escape hides the tooltip. Each bar is
+   * announced to screen readers.
+   * @default { trigger: 'axis' }
+   */
+  tooltip?: ChartTooltipProps;
+  /** BCP 47 locale for default number and percent formatting. */
+  locale?: string;
+  /**
+   * Overrides for generated strings: summary, trend, waterfall step names, legend fallback, and
+   * no-value text. Keys you omit keep the English defaults.
+   */
+  localeText?: Partial<ChartLocaleText>;
+  /**
+   * Bars grow from the baseline on mount and tween to new values when `dataset` changes. Pass
+   * `'disable-all'` to draw the final state. Reduce Motion and `GlobalAnimationSettingsProvider`
+   * `disable-all` also turn it off.
+   */
+  animation?: AnimationRootDisableAll;
+  /**
+   * Accessible summary. Defaults to `localeText.barChartSummary` over every category.
+   */
+  accessibilityLabel?: string;
+  /** Additional Uniwind/Tailwind classes, merged after the root's own styles. */
+  className?: string;
+}
+
+interface BarSelection {
+  readonly seriesId: string;
+  readonly dataIndex: number;
+}
+
+interface BarPlan<TRow> {
+  readonly kind: BarChartKind;
+  readonly series: readonly BarChartSeries<TRow>[];
+  readonly geometry: readonly BarGeometrySeries[];
+  readonly totalKey: string | undefined;
+}
+
+function resolveBarPlan<TRow>(series: readonly BarChartSeries<TRow>[]): BarPlan<TRow> {
+  const toGeometry = (item: BarChartSeries<TRow>): BarGeometrySeries => ({
+    id: item.id,
+    dataKey: item.dataKey,
+    label: item.label ?? '',
+    stack: item.stack,
+    stackOffset: item.stackOffset,
+  });
+  const waterfall = series.find((item) => item.waterfall !== undefined);
+  if (waterfall !== undefined) {
+    return {
+      kind: 'waterfall',
+      series: [waterfall],
+      geometry: [toGeometry(waterfall)],
+      totalKey: waterfall.waterfall?.totalKey,
+    };
+  }
+  for (const comparison of series) {
+    const primary =
+      comparison.overlay === undefined
+        ? undefined
+        : series.find((item) => item.id === comparison.overlay?.seriesId && item !== comparison);
+    if (primary !== undefined) {
+      const pair = [primary, comparison];
+      return {
+        kind: 'overlay',
+        series: pair,
+        geometry: pair.map((item) => ({ ...toGeometry(item), stack: undefined })),
+        totalKey: undefined,
+      };
+    }
+  }
+  return { kind: 'bars', series, geometry: series.map(toGeometry), totalKey: undefined };
+}
+
+function sameItem(a: ChartSelectedItem | undefined, b: BarSelection): boolean {
+  return a?.seriesId === b.seriesId && a.dataIndex === b.dataIndex;
+}
+
+function barSelection(bar: BarRect): BarSelection {
+  return { seriesId: bar.seriesId, dataIndex: bar.index };
+}
+
+function barAccessibilityName(
+  label: string,
+  seriesLabel: string,
+  formatted: string,
+  change: string | null = null,
+): string {
+  const base =
+    seriesLabel.length > 0 ? `${label}, ${seriesLabel}, ${formatted}` : `${label}, ${formatted}`;
+  return change === null ? base : `${base}, ${change}`;
+}
+
+type BarFormatter = (bar: BarRect, location: ChartValueLocation) => string;
+
+function BarChartInner<TRow extends object>(
+  {
+    dataset,
+    series: seriesProp,
+    xAxis,
+    yAxis,
+    size = 'lg',
+    width: widthProp,
+    height: heightProp,
+    layout: orientation = 'vertical',
+    hideLegend = false,
+    grid,
+    palette: paletteProp = 'auto',
+    barLabel = false,
+    borderRadius = BAR_RADIUS,
+    stackGap = DEFAULT_STACK_GAP,
+    categoryGapRatio = CATEGORY_GAP_RATIO,
+    barGapRatio = BAR_GAP_RATIO,
+    referenceLines,
+    emphasizedIndex,
+    scrollable = true,
+    visiblePoints,
+    selectedItem,
+    defaultSelectedItem,
+    onSelectedItemChange,
+    tooltip: tooltipProp,
+    locale,
+    localeText: localeTextProp,
+    animation,
+    accessibilityLabel,
+    className,
+    style,
+    onLayout,
+    ...props
+  }: BarChartProps<TRow>,
+  ref: ForwardedRef<View>,
+) {
+  const animated = useChartMotionEnabled(animation);
+  const simpleColor = useChartSimpleColor();
+  const gradientId = useChartGradientId('bar-fill');
+  const chrome = useChartChrome();
+  const palette = useChartPalette();
+  const paints = useChartColorPaints();
+  const localeText = useMemo(() => resolveChartLocaleText(localeTextProp), [localeTextProp]);
+  const plan = useMemo(() => resolveBarPlan(seriesProp), [seriesProp]);
+  const { kind, geometry } = plan;
+  const overlay = kind === 'overlay';
+  const waterfall = kind === 'waterfall';
+  const expandAxis = useMemo(
+    () => isExpandAxis(kind, resolveBarGroups(geometry)),
+    [kind, geometry],
+  );
+  const categoryAxis = (orientation === 'vertical' ? xAxis : yAxis)?.[0];
+  const valueAxis = (orientation === 'vertical' ? yAxis : xAxis)?.[0];
+  const categoryKey = categoryAxis?.dataKey;
+  const categoryLabelPosition = categoryAxis?.position;
+  const showTicks = valueAxis?.position !== 'none';
+  const showGrid =
+    grid === undefined
+      ? true
+      : (orientation === 'vertical' ? grid.horizontal : grid.vertical) === true;
+  const tickLabelInterval = categoryAxis?.tickLabelInterval;
+  const categories = useMemo(
+    () =>
+      dataset.map((row, index) => {
+        if (categoryKey === undefined) {
+          return String(index);
+        }
+        const raw: unknown = row[categoryKey];
+        return raw === null || raw === undefined ? '' : String(raw as string | number | boolean);
+      }),
+    [dataset, categoryKey],
+  );
+  const hasNegative = useMemo(
+    () =>
+      dataset.some((row) => geometry.some((item) => (readBarValue(row, item.dataKey) ?? 0) < 0)),
+    [dataset, geometry],
+  );
+  const sourceById = useMemo(
+    () => new Map(plan.series.map((item) => [item.id, item] as const)),
+    [plan.series],
+  );
+  const valueAxisMin = valueAxis?.min;
+  const valueAxisMax = valueAxis?.max;
+  const valueAxisTicks = valueAxis?.tickNumber;
+  const valueAxisFormatter = valueAxis?.valueFormatter;
+  const valueAxisConfig = useMemo(
+    () => ({ min: valueAxisMin, max: valueAxisMax, tickNumber: valueAxisTicks }),
+    [valueAxisMin, valueAxisMax, valueAxisTicks],
+  );
+  const percentFormatter: ChartValueFormatter = useMemo(
+    () => (value) => (value === null ? '' : formatChartPercent(value, locale)),
+    [locale],
+  );
+  const formatTick = useMemo(() => {
+    const formatter =
+      valueAxisFormatter ?? (expandAxis ? percentFormatter : defaultChartValueFormatter(locale));
+    return (value: number) => formatter(value, { location: 'tick' });
+  }, [valueAxisFormatter, expandAxis, percentFormatter, locale]);
+  const formatBar: BarFormatter = (bar, location) => {
+    const source = sourceById.get(bar.seriesId);
+    const context = { location, seriesId: bar.seriesId, dataIndex: bar.index };
+    if (bar.expand === true && source?.valueFormatter === undefined) {
+      return (valueAxisFormatter ?? percentFormatter)(bar.plotValue / 100, context);
+    }
+    const formatter = resolveValueFormatter(source, valueAxis, locale);
+    const format = (value: number) => formatter(value, context);
+    return bar.waterfallRole === undefined
+      ? format(bar.value)
+      : formatWaterfallBarValue(bar, format);
+  };
+  const seriesLabelOf = (bar: BarRect): string => {
+    if (bar.waterfallRole === 'increase') {
+      return localeText.waterfallIncrease;
+    }
+    if (bar.waterfallRole === 'decrease') {
+      return localeText.waterfallDecrease;
+    }
+    return bar.seriesLabel;
+  };
+
+  const box = resolveBarChartBox(size, widthProp, heightProp);
+  const [hostWidth, handleHostLayout] = useChartHostWidth(onLayout);
+  const viewportWidth = hostWidth > 0 ? Math.min(hostWidth, box.width) : box.width;
+  const viewportHeight = box.height;
+  const gutters = useMemo(
+    () =>
+      resolveBarChartGutters({
+        categories,
+        hasNegative,
+        orientation,
+        barLabel,
+        categoryLabelPosition,
+        showTicks,
+        overlay,
+      }),
+    [categories, hasNegative, orientation, barLabel, categoryLabelPosition, showTicks, overlay],
+  );
+  const content = useMemo(
+    () =>
+      resolveBarChartContentSize({
+        viewportWidth,
+        viewportHeight,
+        categoryCount: dataset.length,
+        orientation,
+        gutters,
+        scrollable,
+        visiblePoints,
+      }),
+    [
+      viewportWidth,
+      viewportHeight,
+      dataset.length,
+      orientation,
+      gutters,
+      scrollable,
+      visiblePoints,
+    ],
+  );
+  const showCategoryLabel = useMemo(() => {
+    if (typeof tickLabelInterval !== 'function') {
+      return undefined;
+    }
+    return (index: number) => {
+      const row = dataset.at(index);
+      const value: unknown =
+        row === undefined || categoryKey === undefined ? index : row[categoryKey];
+      return tickLabelInterval(value, index);
+    };
+  }, [tickLabelInterval, dataset, categoryKey]);
+  const layout = useMemo(
+    () =>
+      layoutBarChart({
+        dataset,
+        categories,
+        series: geometry,
+        kind,
+        waterfallTotalKey: plan.totalKey,
+        width: content.width,
+        height: content.height,
+        orientation,
+        barLabel,
+        categoryLabelPosition,
+        showTicks,
+        referenceLines,
+        valueAxis: valueAxisConfig,
+        formatTick,
+        stackGap,
+        categoryGapRatio,
+        barGapRatio,
+        showCategoryLabel,
+      }),
+    [
+      dataset,
+      categories,
+      geometry,
+      kind,
+      plan.totalKey,
+      content.width,
+      content.height,
+      orientation,
+      barLabel,
+      categoryLabelPosition,
+      showTicks,
+      referenceLines,
+      valueAxisConfig,
+      formatTick,
+      stackGap,
+      categoryGapRatio,
+      barGapRatio,
+      showCategoryLabel,
+    ],
+  );
+  const overflowsX = content.width > viewportWidth + 0.5;
+  const overflowsY = content.height > viewportHeight + 0.5;
+  const fills = waterfall
+    ? dataset.map((_, index) => palette[index % palette.length] ?? simpleColor)
+    : plan.series.map((item, seriesIndex) => {
+        const custom = resolveChartColor(item.color, paints);
+        if (custom !== undefined) {
+          return custom;
+        }
+        if (overlay) {
+          return seriesIndex === 0 ? simpleColor : chrome.grid;
+        }
+        return paints[chartSeriesColor(seriesIndex, plan.series.length, paletteProp, 'bar')];
+      });
+  const summaryCategories: ChartSummaryCategory[] = dataset.map((row, dataIndex) => ({
+    label: categories[dataIndex] ?? '',
+    values: plan.series.flatMap((item) => {
+      const value = readBarValue(row, item.dataKey);
+      if (value === null) {
+        return [];
+      }
+      // An expand axis formats 0–1 shares; the summary reads raw values.
+      const formatter = resolveValueFormatter(item, expandAxis ? null : valueAxis, locale);
+      return [
+        {
+          label: item.label ?? '',
+          formattedValue: formatter(value, { location: 'a11y', seriesId: item.id, dataIndex }),
+        },
+      ];
+    }),
+  }));
+  const summary = accessibilityLabel ?? localeText.barChartSummary(summaryCategories);
+  const trigger = tooltipProp?.trigger ?? 'axis';
+  const tooltip = trigger !== 'none';
+  const interactive =
+    onSelectedItemChange !== undefined ||
+    selectedItem !== undefined ||
+    defaultSelectedItem !== undefined;
+  const [selectedState, setSelectedItem] = useControllableState<ChartSelectedItem>({
+    prop: selectedItem,
+    defaultProp: defaultSelectedItem ?? null,
+    onChange: onSelectedItemChange,
+  });
+  const selected = selectedState ?? null;
+  const visibleBars = layout.bars.filter((bar) =>
+    bar.stackId !== undefined
+      ? bar.width > 0 && bar.height > 0
+      : orientation === 'vertical'
+        ? bar.width > 0
+        : bar.height > 0,
+  );
+  const inspectable = (interactive || tooltip) && visibleBars.length > 0;
+  const [activeIndex, setActiveIndex] = useState<number | null>(null);
+  const [dismissed, setDismissed] = useState(false);
+  const [scrubbing, setScrubbing] = useState(false);
+  const scrollOffset = useRef({ x: 0, y: 0 });
+  const selectedIndex = selected
+    ? visibleBars.findIndex((bar) => sameItem(selected, barSelection(bar)))
+    : -1;
+  const activeBar = activeIndex === null ? undefined : visibleBars.at(activeIndex);
+  const highlightBar: BarSelection | null = activeBar
+    ? barSelection(activeBar)
+    : selectedIndex >= 0 && selected !== null
+      ? selected
+      : null;
+  const tooltipIndex = tooltip && !dismissed && activeIndex !== null ? activeIndex : null;
+  const activate = (index: number) => {
+    setDismissed(false);
+    setActiveIndex((prev) => (prev === index ? prev : index));
+  };
+  const deactivate = (index: number) => {
+    setActiveIndex((prev) => (prev === index ? null : prev));
+  };
+
+  const showLegend = !waterfall && plan.series.length > 0 && !hideLegend;
+
+  const plot = (
+    <BarPlot
+      layout={layout}
+      orientation={orientation}
+      overlay={overlay}
+      waterfall={waterfall}
+      showGrid={showGrid}
+      barLabel={barLabel}
+      formatBar={formatBar}
+      formatStackTotal={(anchor) => {
+        const context = { location: 'label' as const, dataIndex: anchor.index };
+        if (anchor.expand) {
+          return (valueAxisFormatter ?? percentFormatter)(anchor.total / 100, context);
+        }
+        return resolveValueFormatter(
+          sourceById.get(anchor.seriesId),
+          valueAxis,
+          locale,
+        )(anchor.total, context);
+      }}
+      fills={fills}
+      gradientId={gradientId}
+      chrome={chrome}
+      accent={simpleColor}
+      borderRadius={Math.max(borderRadius, 0)}
+      animated={animated}
+      highlightBar={highlightBar}
+      emphasizedIndex={emphasizedIndex}
+    />
+  );
+
+  const vertical = orientation === 'vertical';
+  const targets = inspectable
+    ? barInspectorTargets({
+        bars: visibleBars,
+        layout,
+        orientation,
+        overlay,
+        waterfall,
+        trigger,
+        offsetX: vertical ? layout.plot.x : 0,
+        fills,
+        fallbackFill: chrome.grid,
+        formatBar,
+        seriesLabelOf,
+        localeText,
+        selectedIndex: selectedIndex >= 0 ? selectedIndex : null,
+      })
+    : [];
+  const tip = tooltipIndex === null ? undefined : targets.at(tooltipIndex);
+  const dismissOnScroll = (event: NativeSyntheticEvent<NativeScrollEvent>) => {
+    scrollOffset.current = event.nativeEvent.contentOffset;
+    if (tooltipIndex !== null) {
+      setDismissed(true);
+    }
+  };
+
+  const inspector = inspectable ? (
+    <BarInspector
+      bars={visibleBars}
+      targets={targets}
+      orientation={orientation}
+      summary={summary}
+      selectable={interactive}
+      activeIndex={activeIndex}
+      selectedIndex={selectedIndex >= 0 ? selectedIndex : null}
+      holdToScrub={overflowsX || overflowsY}
+      onScrubLockChange={setScrubbing}
+      onActivate={activate}
+      onDeactivate={deactivate}
+      onDismiss={() => {
+        setDismissed(true);
+      }}
+      onSelectIndex={(index) => {
+        const bar = visibleBars.at(index);
+        if (bar) {
+          setDismissed(false);
+          const next = barSelection(bar);
+          setSelectedItem(sameItem(selected, next) ? null : next);
+        }
+      }}
+    />
+  ) : null;
+  const tooltipLayer =
+    tip !== undefined ? (
+      <ChartTooltipLayer
+        content={tip.tooltip}
+        noValueText={localeText.noValue}
+        slot="bar-chart"
+        anchorX={vertical ? layout.plot.x + tip.anchorX - scrollOffset.current.x : tip.anchorX}
+        anchorY={vertical ? tip.anchorY : tip.anchorY - scrollOffset.current.y}
+        anchorRadius={tip.anchorRadius}
+        width={viewportWidth}
+        height={viewportHeight}
+      />
+    ) : null;
+
+  const ticks = showTicks ? (
+    <>
+      {layout.valueTicks.map((tick) => (
+        <SvgText
+          key={`tick-${String(tick.value)}`}
+          x={tick.x}
+          y={tick.y}
+          fill={chrome.label}
+          fontFamily={chrome.fontFamily}
+          fontSize={chrome.labelSize}
+          textAnchor={orientation === 'vertical' ? 'end' : 'middle'}
+          alignmentBaseline="middle"
+        >
+          {tick.text}
+        </SvgText>
+      ))}
+    </>
+  ) : null;
+
+  const chart = (
+    <View
+      style={{ width: '100%', maxWidth: viewportWidth, height: viewportHeight }}
+      {...dataAttributes({ slot: 'bar-chart-plot' })}
+    >
+      {orientation === 'vertical' ? (
+        <View className="w-full flex-row" style={{ height: viewportHeight }}>
+          <Svg
+            width={layout.plot.x}
+            height={viewportHeight}
+            viewBox={`0 0 ${String(layout.plot.x)} ${String(content.height)}`}
+            {...HIDDEN_SVG_PROPS}
+          >
+            {ticks}
+          </Svg>
+          <ScrollView
+            horizontal
+            nestedScrollEnabled
+            scrollEnabled={overflowsX && !scrubbing}
+            showsHorizontalScrollIndicator={overflowsX}
+            scrollEventThrottle={16}
+            onScroll={dismissOnScroll}
+            className="flex-1"
+            style={{ height: viewportHeight }}
+          >
+            <View style={{ width: content.width - layout.plot.x, height: viewportHeight }}>
+              <Svg
+                width={content.width - layout.plot.x}
+                height={viewportHeight}
+                viewBox={`0 0 ${String(content.width - layout.plot.x)} ${String(content.height)}`}
+                style={SVG_OVERFLOW_VISIBLE}
+                pointerEvents="none"
+                {...HIDDEN_SVG_PROPS}
+              >
+                <G transform={`translate(${String(-layout.plot.x)}, 0)`}>{plot}</G>
+              </Svg>
+              {inspector}
+            </View>
+          </ScrollView>
+        </View>
+      ) : (
+        <View style={{ width: viewportWidth, height: viewportHeight }}>
+          <ScrollView
+            nestedScrollEnabled
+            scrollEnabled={overflowsY && !scrubbing}
+            showsVerticalScrollIndicator={overflowsY}
+            scrollEventThrottle={16}
+            onScroll={dismissOnScroll}
+            style={{ height: viewportHeight - gutters.paddingBottom }}
+          >
+            <View style={{ width: viewportWidth, height: content.height - gutters.paddingBottom }}>
+              <Svg
+                width={viewportWidth}
+                height={content.height - gutters.paddingBottom}
+                viewBox={`0 0 ${String(content.width)} ${String(content.height - gutters.paddingBottom)}`}
+                pointerEvents="none"
+                {...HIDDEN_SVG_PROPS}
+              >
+                {plot}
+              </Svg>
+              {inspector}
+            </View>
+          </ScrollView>
+          <Svg
+            width={viewportWidth}
+            height={gutters.paddingBottom}
+            viewBox={`0 0 ${String(content.width)} ${String(gutters.paddingBottom)}`}
+            {...HIDDEN_SVG_PROPS}
+          >
+            <G transform={`translate(0, ${String(-(content.height - gutters.paddingBottom))})`}>
+              {ticks}
+            </G>
+          </Svg>
+        </View>
+      )}
+      {tooltipLayer}
+    </View>
+  );
+
+  return (
+    <View
+      ref={ref}
+      className={cn(barChartRootVariants(), className)}
+      style={style}
+      accessible={!inspectable && !showLegend}
+      accessibilityRole={!inspectable && !showLegend ? 'image' : undefined}
+      accessibilityLabel={!inspectable && !showLegend ? summary : undefined}
+      {...props}
+      onLayout={handleHostLayout}
+      {...mergeDataAttributes(props, dataAttributes({ slot: 'bar-chart' }))}
+    >
+      {chart}
+      {showLegend ? (
+        <View
+          className={barChartLegendVariants()}
+          {...dataAttributes({ slot: 'bar-chart-legend' })}
+        >
+          {plan.series.map((item, seriesIndex) => {
+            const isSelected = highlightBar?.seriesId === item.id;
+            return (
+              <View
+                key={item.id}
+                className={barChartLegendItemVariants()}
+                {...dataAttributes({ slot: 'bar-chart-legend-item' })}
+              >
+                <View
+                  className="h-2 w-3 rounded-sm"
+                  style={{ backgroundColor: fills[seriesIndex] }}
+                />
+                <Text className={barChartLegendLabelVariants({ selected: isSelected })}>
+                  {item.label !== undefined && item.label.length > 0
+                    ? item.label
+                    : localeText.defaultSeriesLabel}
+                </Text>
+              </View>
+            );
+          })}
+        </View>
+      ) : null}
+    </View>
+  );
+}
+
+/**
+ * Category bars from `dataset` rows. MUI X Charts–shaped: `series[].dataKey`, axis arrays,
+ * `layout`, `stack` groups, and `selectedItem`.
+ */
+export const BarChart = forwardRef(BarChartInner) as <TRow extends object>(
+  props: BarChartProps<TRow> & { ref?: ForwardedRef<View> },
+) => ReactElement | null;
+
+(BarChart as { displayName?: string }).displayName = 'BarChart';
+
+function BarPlot({
+  layout,
+  orientation,
+  overlay,
+  waterfall,
+  showGrid,
+  barLabel,
+  formatBar,
+  formatStackTotal,
+  fills,
+  gradientId,
+  chrome,
+  accent,
+  borderRadius,
+  animated,
+  highlightBar,
+  emphasizedIndex,
+}: {
+  layout: BarChartLayout;
+  orientation: BarChartOrientation;
+  overlay: boolean;
+  waterfall: boolean;
+  showGrid: boolean;
+  barLabel: boolean;
+  formatBar: BarFormatter;
+  formatStackTotal: (anchor: ReturnType<typeof stackedTotalAnchors>[number]) => string;
+  fills: readonly string[];
+  gradientId: string;
+  chrome: ChartChrome;
+  accent: string;
+  borderRadius: number;
+  animated: boolean;
+  highlightBar: BarSelection | null;
+  emphasizedIndex: number | undefined;
+}) {
+  const labeledBars = layout.bars.filter((bar) => {
+    if (bar.stackId !== undefined) {
+      return false;
+    }
+    if (emphasizedIndex !== undefined && bar.index !== emphasizedIndex) {
+      return false;
+    }
+    return !overlay || bar.seriesIndex === 0;
+  });
+  const stackLabels = stackedTotalAnchors(layout.bars, orientation).filter(
+    (anchor) => emphasizedIndex === undefined || anchor.index === emphasizedIndex,
+  );
+  const paintedBars = overlay
+    ? [...layout.bars].sort((a, b) => b.seriesIndex - a.seriesIndex)
+    : layout.bars;
+
+  return (
+    <>
+      <ChartLinearFills
+        idPrefix={gradientId}
+        colors={fills}
+        x2={orientation === 'vertical' ? '0%' : '100%'}
+        y2={orientation === 'vertical' ? '100%' : '0%'}
+      />
+      {showGrid ? (
+        layout.gridLines.map((line) => (
+          <Line
+            key={`grid-${String(line.x1)}-${String(line.y1)}`}
+            x1={line.x1}
+            y1={line.y1}
+            x2={line.x2}
+            y2={line.y2}
+            stroke={chrome.grid}
+            strokeWidth={1}
+          />
+        ))
+      ) : (
+        <Line
+          x1={orientation === 'vertical' ? layout.plot.x : layout.baseline}
+          y1={orientation === 'vertical' ? layout.baseline : layout.plot.y}
+          x2={orientation === 'vertical' ? layout.plot.x + layout.plot.width : layout.baseline}
+          y2={orientation === 'vertical' ? layout.baseline : layout.plot.y + layout.plot.height}
+          stroke={chrome.grid}
+          strokeWidth={1}
+        />
+      )}
+      {layout.referenceLines.map((line, index) => (
+        <G key={`ref-${String(line.x1)}-${String(line.y1)}-${String(index)}`}>
+          <Line
+            x1={line.x1}
+            y1={line.y1}
+            x2={line.x2}
+            y2={line.y2}
+            stroke={accent}
+            strokeWidth={1}
+            strokeDasharray={DASH}
+          />
+          {line.label !== undefined && line.label.length > 0 ? (
+            <SvgText
+              x={line.x1 + 4}
+              y={orientation === 'vertical' ? line.y1 - 4 : line.y1 + 12}
+              fill={accent}
+              fontFamily={chrome.fontFamily}
+              fontSize={chrome.captionSize}
+              textAnchor="start"
+            >
+              {line.label}
+            </SvgText>
+          ) : null}
+        </G>
+      ))}
+      {layout.connectors.map((line, index) => (
+        <Line
+          key={`wf-${String(line.x1)}-${String(line.y1)}-${String(index)}`}
+          x1={line.x1}
+          y1={line.y1}
+          x2={line.x2}
+          y2={line.y2}
+          stroke={chrome.grid}
+          strokeWidth={1}
+          strokeDasharray={DASH}
+        />
+      ))}
+      {paintedBars.map((bar) => {
+        if (bar.width <= 0 || bar.height <= 0) {
+          return null;
+        }
+        const dimmed =
+          highlightBar !== null &&
+          (bar.stackId !== undefined
+            ? !sameItem(highlightBar, barSelection(bar))
+            : highlightBar.dataIndex !== bar.index);
+        const muted = emphasizedIndex !== undefined && bar.index !== emphasizedIndex;
+        const comparison = overlay && bar.seriesIndex > 0;
+        return (
+          <AnimatedBar
+            key={`${String(bar.index)}-${bar.seriesId}`}
+            bar={bar}
+            orientation={orientation}
+            baseline={layout.baseline}
+            animated={animated}
+            fill={
+              muted || (waterfall && dimmed)
+                ? chrome.grid
+                : comparison || waterfall
+                  ? (fills[bar.seriesIndex] ?? chrome.grid)
+                  : chartFillUrl(gradientId, bar.seriesIndex)
+            }
+            opacity={waterfall ? 1 : dimmed ? INACTIVE_OPACITY : 1}
+            radius={borderRadius}
+          />
+        );
+      })}
+      {layout.categoryLabels.map((item, index) => (
+        <SvgText
+          key={`cat-${String(index)}-${item.label}`}
+          x={item.x}
+          y={item.y}
+          fill={chrome.label}
+          fontFamily={chrome.fontFamily}
+          fontSize={chrome.labelSize}
+          textAnchor={item.textAnchor}
+          alignmentBaseline="middle"
+        >
+          {item.label}
+        </SvgText>
+      ))}
+      {barLabel ? (
+        <ValueLabels
+          animated={animated}
+          motionKey={`${orientation}-${overlay ? '1' : '0'}-${layout.bars
+            .map((bar) => [bar.x, bar.y, bar.width, bar.height].join(','))
+            .join(';')}`}
+        >
+          {(labelOpacity) => (
+            <>
+              {stackLabels.map((label) => (
+                <SvgText
+                  key={`stack-val-${label.key}`}
+                  x={label.x}
+                  y={label.y}
+                  fill={chrome.label}
+                  fillOpacity={labelOpacity}
+                  fontFamily={chrome.fontFamily}
+                  fontSize={chrome.captionSize}
+                  textAnchor={label.textAnchor}
+                  alignmentBaseline="middle"
+                >
+                  {formatStackTotal(label)}
+                </SvgText>
+              ))}
+              {labeledBars.map((bar) => {
+                const anchor = waterfall
+                  ? waterfallValueAnchor(bar, orientation)
+                  : barValueAnchor(bar, orientation);
+                return (
+                  <G key={`val-${String(bar.index)}-${bar.seriesId}`}>
+                    <SvgText
+                      x={anchor.x}
+                      y={anchor.y}
+                      fill={chrome.label}
+                      fillOpacity={labelOpacity}
+                      fontFamily={chrome.fontFamily}
+                      fontSize={chrome.captionSize}
+                      textAnchor={anchor.textAnchor}
+                      alignmentBaseline="middle"
+                    >
+                      {formatBar(bar, 'label')}
+                    </SvgText>
+                  </G>
+                );
+              })}
+            </>
+          )}
+        </ValueLabels>
+      ) : null}
+    </>
+  );
+}
+
+function barTooltipContent(
+  group: readonly BarRect[],
+  bar: BarRect,
+  trigger: 'item' | 'axis',
+  fills: readonly string[],
+  fallbackFill: string,
+  formatBar: BarFormatter,
+  seriesLabelOf: (bar: BarRect) => string,
+): ChartTooltipContent {
+  const shown = trigger === 'axis' ? group : [bar];
+  return {
+    title: bar.label,
+    items: shown.map((item) => ({
+      seriesId: item.seriesId,
+      label: seriesLabelOf(item),
+      color: fills[item.seriesIndex] ?? fallbackFill,
+      formattedValue: formatBar(item, 'tooltip'),
+    })),
+  };
+}
+
+/**
+ * One hit target per drawn bar. Grouped bars get the full value-axis span of their slot so short
+ * bars stay easy to hover. Stacked segments keep their own rect, expanded to a 44px minimum
+ * (WCAG 2.5.8 / HIG) so a 9px-tall bar is still a usable touch target.
+ */
+/** Targets in scroll-content coordinates, shifted left by `offsetX`. */
+function barInspectorTargets({
+  bars,
+  layout,
+  orientation,
+  overlay,
+  waterfall,
+  trigger,
+  offsetX,
+  fills,
+  fallbackFill,
+  formatBar,
+  seriesLabelOf,
+  localeText,
+  selectedIndex,
+}: {
+  bars: readonly BarRect[];
+  layout: BarChartLayout;
+  orientation: BarChartOrientation;
+  overlay: boolean;
+  waterfall: boolean;
+  trigger: 'item' | 'axis' | 'none';
+  offsetX: number;
+  fills: readonly string[];
+  fallbackFill: string;
+  formatBar: BarFormatter;
+  seriesLabelOf: (bar: BarRect) => string;
+  localeText: ChartLocaleText;
+  selectedIndex: number | null;
+}): ChartInspectorTarget[] {
+  const { plot } = layout;
+  const vertical = orientation === 'vertical';
+  const groups = new Map<number, BarRect[]>();
+  bars.forEach((bar) => {
+    const group = groups.get(bar.index);
+    if (group === undefined) {
+      groups.set(bar.index, [bar]);
+    } else {
+      group.push(bar);
+    }
+  });
+  const outlines = new Map(
+    [...groups].map(([categoryIndex, group]) => {
+      const start = Math.min(...group.map((item) => (vertical ? item.x : item.y)));
+      const end = Math.max(
+        ...group.map((item) => (vertical ? item.x + item.width : item.y + item.height)),
+      );
+      const outline = vertical
+        ? { left: start - offsetX - 4, top: plot.y, width: end - start + 8, height: plot.height }
+        : { left: plot.x - offsetX, top: start - 4, width: plot.width, height: end - start + 8 };
+      return [categoryIndex, outline] as const;
+    }),
+  );
+  const trendText = (bar: BarRect): string | null => {
+    if (!overlay || bar.seriesIndex !== 0) {
+      return null;
+    }
+    const group = groups.get(bar.index) ?? [];
+    const delta = overlayDelta(group, bar.index);
+    if (delta === null) {
+      return null;
+    }
+    const comparison = group.find((item) => item.seriesIndex === 1);
+    return localeText.trend({
+      direction: delta > 0 ? 'up' : delta < 0 ? 'down' : 'none',
+      formattedDelta: formatBar({ ...bar, value: Math.abs(delta) }, 'a11y'),
+      comparisonLabel: comparison?.seriesLabel ?? '',
+    });
+  };
+  return bars.map((bar, index): ChartInspectorTarget => {
+    const x = bar.x - offsetX;
+    const raw =
+      bar.stackId !== undefined || waterfall || !vertical
+        ? { left: x, top: bar.y, width: bar.width, height: bar.height }
+        : { left: x, top: plot.y, width: bar.width, height: plot.height };
+    const box = expandHitBox(raw.left, raw.top, raw.width, raw.height);
+    const group = groups.get(bar.index) ?? [bar];
+    const outline = outlines.get(bar.index);
+    return {
+      key: `hit-${String(bar.index)}-${bar.seriesId}`,
+      ...box,
+      outline,
+      anchorX: vertical ? x + bar.width / 2 : x + bar.width,
+      anchorY: bar.y,
+      anchorRadius: vertical ? bar.width / 2 : 0,
+      tooltip: barTooltipContent(
+        group,
+        bar,
+        trigger === 'item' ? 'item' : 'axis',
+        fills,
+        fallbackFill,
+        formatBar,
+        seriesLabelOf,
+      ),
+      accessibilityLabel: barAccessibilityName(
+        bar.label,
+        seriesLabelOf(bar),
+        formatBar(bar, 'a11y'),
+        trendText(bar),
+      ),
+      selected: selectedIndex === index,
+    };
+  });
+}
+
+function BarInspector({
+  bars,
+  targets,
+  orientation,
+  summary,
+  selectable,
+  activeIndex,
+  selectedIndex,
+  onActivate,
+  onDeactivate,
+  onDismiss,
+  onSelectIndex,
+  holdToScrub,
+  onScrubLockChange,
+}: {
+  onScrubLockChange: (locked: boolean) => void;
+  bars: readonly BarRect[];
+  targets: readonly ChartInspectorTarget[];
+  orientation: BarChartOrientation;
+  summary: string;
+  selectable: boolean;
+  activeIndex: number | null;
+  selectedIndex: number | null;
+  holdToScrub: boolean;
+  onActivate: (index: number) => void;
+  onDeactivate: (index: number) => void;
+  onDismiss: () => void;
+  onSelectIndex: (index: number) => void;
+}) {
+  return (
+    <ChartInspector
+      targets={targets}
+      summary={summary}
+      selectable={selectable}
+      activeIndex={activeIndex}
+      selectedIndex={selectedIndex}
+      slot="bar-chart"
+      holdToScrub={holdToScrub}
+      onScrubLockChange={onScrubLockChange}
+      hitTest={(x, y) => {
+        let best: number | null = null;
+        let bestDist = Number.POSITIVE_INFINITY;
+        targets.forEach((target, index) => {
+          if (
+            x < target.left ||
+            x > target.left + target.width ||
+            y < target.top ||
+            y > target.top + target.height
+          ) {
+            return;
+          }
+          const dist = Math.hypot(
+            x - (target.left + target.width / 2),
+            y - (target.top + target.height / 2),
+          );
+          if (dist < bestDist) {
+            bestDist = dist;
+            best = index;
+          }
+        });
+        return best;
+      }}
+      onActivate={onActivate}
+      onDeactivate={onDeactivate}
+      onDismiss={onDismiss}
+      onSelectIndex={onSelectIndex}
+      neighborIndex={(index, key) => barKeyboardNeighbor(bars, index, key, orientation)}
+    />
+  );
+}
+
+function collapsedBar(bar: BarRect, orientation: BarChartOrientation, baseline: number): number[] {
+  if (orientation === 'vertical') {
+    const onBaseline = Math.abs((bar.plotValue >= 0 ? bar.y + bar.height : bar.y) - baseline) < 1;
+    return onBaseline ? [bar.x, baseline, bar.width, 0] : [bar.x, bar.y + bar.height, bar.width, 0];
+  }
+  const onBaseline = Math.abs((bar.plotValue >= 0 ? bar.x : bar.x + bar.width) - baseline) < 1;
+  return onBaseline ? [baseline, bar.y, 0, bar.height] : [bar.x, bar.y, 0, bar.height];
+}
+
+function AnimatedBar({
+  bar,
+  orientation,
+  baseline,
+  animated,
+  fill,
+  opacity,
+  radius,
+}: {
+  bar: BarRect;
+  orientation: BarChartOrientation;
+  baseline: number;
+  animated: boolean;
+  fill: string;
+  opacity: number;
+  radius: number;
+}) {
+  const { rounded, roundAll, value } = bar;
+  const morph = useChartMorph(
+    [bar.x, bar.y, bar.width, bar.height],
+    collapsedBar(bar, orientation, baseline),
+    animated,
+  );
+  const { from, to, progress } = morph;
+  const animatedProps = useAnimatedProps(() => {
+    const [x = 0, y = 0, width = 0, height = 0] = lerpVector(from.get(), to.get(), progress.get());
+    return {
+      d: barPath({ x, y, width, height, rounded, roundAll, value }, orientation, radius),
+    };
+  }, [from, to, progress, rounded, roundAll, value, orientation, radius]);
+
+  return <AnimatedPath animatedProps={animatedProps} fill={fill} opacity={opacity} />;
+}
+
+function ValueLabels({
+  animated,
+  motionKey,
+  children,
+}: {
+  animated: boolean;
+  motionKey: string;
+  children: (opacity: number) => ReactNode;
+}) {
+  const [shownKey, setShownKey] = useState(animated ? null : motionKey);
+
+  useEffect(() => {
+    if (!animated) {
+      setShownKey(motionKey);
+      return;
+    }
+    const id = setTimeout(() => setShownKey(motionKey), CHART_MOTION_DURATION);
+    return () => {
+      clearTimeout(id);
+    };
+  }, [animated, motionKey]);
+
+  if (!animated) {
+    return <>{children(1)}</>;
+  }
+  if (shownKey !== motionKey) {
+    return null;
+  }
+  return <FadeInLabels key={motionKey}>{children}</FadeInLabels>;
+}
+
+/** Group opacity on native SVG flashes a full-opacity frame; fade each text's fill instead. */
+function FadeInLabels({ children }: { children: (opacity: number) => ReactNode }) {
+  const [opacity, setOpacity] = useState(0);
+
+  useEffect(() => {
+    let frame = 0;
+    const started = Date.now();
+    const tick = () => {
+      const t = Math.min(1, (Date.now() - started) / LABEL_FADE_DURATION);
+      setOpacity(1 - (1 - t) ** 3);
+      if (t < 1) {
+        frame = requestAnimationFrame(tick);
+      }
+    };
+    frame = requestAnimationFrame(tick);
+    return () => {
+      cancelAnimationFrame(frame);
+    };
+  }, []);
+
+  return <>{children(opacity)}</>;
+}