@cdx-ui/components 0.3.4 → 0.3.6

package/docs/components/bar-chart/content.md

@@ -0,0 +1,703 @@
+# Bar Chart (https://design.candescent.com/docs/components/bar-chart)
+
+Resources: [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/charts-barchart--default)
+
+`BarChart` follows the MUI X Charts shape. Pass your own rows as `dataset`, name the category column on the band axis, and give each series a `dataKey`. No row key is reserved, so a server payload can go in as is. The [Insights Overview](https://design.candescent.com/docs/patterns/dashboard/content.md#insights-overview) pattern shows compact bar charts inside dashboard cards.
+
+```tsx
+import { BarChart } from '@cdx-ui/components';
+```
+
+## Basic
+
+One series over a band axis. `xAxis[0].dataKey` names the category column; `series[].dataKey` names the value column. The plot uses Forge `--color-chart-simple-primary`.
+
+```tsx
+import { BarChart } from '@cdx-ui/components';
+import { MONTH_AXIS, SIGNUPS } from './_data';
+
+export default function BarChartBasicDemo() {
+  return (
+    <BarChart
+      dataset={SIGNUPS}
+      xAxis={MONTH_AXIS}
+      series={[{ id: 'signups', dataKey: 'value', label: 'Signups' }]}
+      hideLegend
+      scrollable={false}
+      accessibilityLabel="Monthly signups"
+    />
+  );
+}
+```
+
+## Sizes
+
+`size` picks a preset plot box: `sm`, `md`, `lg` (the default), or `xl`. `width` and `height` override one side.
+
+```tsx
+import { useState } from 'react';
+import { BarChart, Box, Slider, VStack } from '@cdx-ui/components';
+import { GROUPED, GROUPED_AXIS, SERIES } from './_data';
+
+const SIZES = ['sm', 'md', 'lg', 'xl'] as const;
+
+export default function BarChartSizesDemo() {
+  const [index, setIndex] = useState(2);
+  const size = SIZES[index] ?? 'lg';
+
+  return (
+    <VStack space="2xl" className="w-full items-center">
+      <Box className="w-full max-w-xs">
+        <Slider
+          value={index}
+          onChange={setIndex}
+          min={0}
+          max={SIZES.length - 1}
+          step={1}
+          accessibilityLabel="Chart size"
+        >
+          <Slider.Rail>
+            <Slider.Track />
+          </Slider.Rail>
+          <Slider.Thumb>
+            <Slider.Popup>{size}</Slider.Popup>
+          </Slider.Thumb>
+          <Slider.MarkerGroup>
+            <Slider.Marker />
+          </Slider.MarkerGroup>
+        </Slider>
+      </Box>
+      <BarChart
+        key={size}
+        dataset={GROUPED}
+        xAxis={GROUPED_AXIS}
+        series={SERIES}
+        size={size}
+        scrollable={false}
+        accessibilityLabel="Signups by channel"
+      />
+    </VStack>
+  );
+}
+```
+
+## Horizontal
+
+`layout="horizontal"` swaps the axes, as in MUI X: the category axis moves to `yAxis` and the value axis to `xAxis`. Use it when labels are longer than a month abbreviation. Grouped and stacked series work the same way; the second chart puts a loans stack and a cards stack in each quarter.
+
+```tsx
+import { BarChart, VStack } from '@cdx-ui/components';
+import { CHANNELS, PIPELINE } from './_data';
+
+export default function BarChartHorizontalDemo() {
+  return (
+    <VStack space="2xl" className="w-full">
+      <BarChart
+        dataset={CHANNELS}
+        layout="horizontal"
+        yAxis={[{ id: 'channel', dataKey: 'channel', scaleType: 'band' }]}
+        series={[{ id: 'contacts', dataKey: 'contacts' }]}
+        barLabel
+        hideLegend
+        scrollable={false}
+        height={280}
+        accessibilityLabel="Contacts by channel"
+      />
+      <BarChart
+        dataset={PIPELINE}
+        layout="horizontal"
+        yAxis={[{ id: 'quarter', dataKey: 'quarter', scaleType: 'band' }]}
+        series={[
+          { id: 'newLoans', dataKey: 'newLoans', label: 'New loans', stack: 'loans' },
+          { id: 'renewals', dataKey: 'renewals', label: 'Renewals', stack: 'loans' },
+          { id: 'newCards', dataKey: 'newCards', label: 'New cards', stack: 'cards' },
+          { id: 'upgrades', dataKey: 'upgrades', label: 'Upgrades', stack: 'cards' },
+        ]}
+        barLabel
+        scrollable={false}
+        height={360}
+        accessibilityLabel="Loans and cards by quarter"
+      />
+    </VStack>
+  );
+}
+```
+
+## Axis config
+
+The value axis takes `min`, `max`, and `tickNumber` to set the domain and the number of ticks, and `valueFormatter` for tick text. A series `valueFormatter` wins over the axis one everywhere except ticks, so ticks can read `$1k` while the tooltip reads `$860`. `position: 'none'` on the value axis hides its ticks. On the category axis, `position` moves the names (`'top'` / `'bottom'` when vertical, `'left'` / `'right'` when horizontal, `'none'` to hide them) and a `tickLabelInterval` function picks which names draw.
+
+```tsx
+import { BarChart } from '@cdx-ui/components';
+import { formatWholeUsd, MONTH_AXIS, SIGNUPS } from './_data';
+
+export default function BarChartAxisDemo() {
+  return (
+    <BarChart
+      dataset={SIGNUPS}
+      xAxis={MONTH_AXIS}
+      yAxis={[
+        {
+          id: 'revenue',
+          min: 0,
+          max: 1000,
+          tickNumber: 6,
+          valueFormatter: (value) => {
+            if (value === null) {
+              return '';
+            }
+            return value >= 1000 ? `$${String(value / 1000)}k` : `$${String(value)}`;
+          },
+        },
+      ]}
+      series={[
+        { id: 'revenue', dataKey: 'value', label: 'Revenue', valueFormatter: formatWholeUsd },
+      ]}
+      hideLegend
+      scrollable={false}
+      accessibilityLabel="Monthly revenue"
+    />
+  );
+}
+```
+
+## Series colors
+
+Each series draws its own bar in the category. Up to three series use `simple-primary`, `simple-secondary`, and `simple-tertiary` (the FI brand family). Four or more switch the whole chart to `categorical-1`…`6`; pass `palette="categorical"` to use them at any count. A series `color` (a chart token name) wins over both, as in this demo. The legend shows by default; `hideLegend` turns it off.
+
+```tsx
+import { BarChart } from '@cdx-ui/components';
+import { GROUPED, GROUPED_AXIS } from './_data';
+
+export default function BarChartGroupedDemo() {
+  return (
+    <BarChart
+      dataset={GROUPED}
+      xAxis={GROUPED_AXIS}
+      series={[
+        { id: 'online', dataKey: 'online', label: 'Online', color: 'categorical-3' },
+        { id: 'retail', dataKey: 'retail', label: 'Retail', color: 'categorical-5' },
+        { id: 'direct', dataKey: 'direct', label: 'Direct', color: 'simple-secondary' },
+      ]}
+      scrollable={false}
+      accessibilityLabel="Signups by channel"
+    />
+  );
+}
+```
+
+## Colors
+
+A series `color` can also be a severity token: `danger`, `warning`, `success`, or `info`. Use one, on the series that carries the message. Pair it with `emphasizedIndex` to mute the other bars to neutral, so the severity color is the only hue on the plot. Here February's electric bill is flagged `warning`.
+
+```tsx
+import { useState } from 'react';
+import { BarChart, Box, Tabs, type ChartColor, type ChartValueFormatter } from '@cdx-ui/components';
+
+const COLORS: readonly ChartColor[] = [
+  'danger',
+  'warning',
+  'success',
+  'info',
+  'simple-primary',
+  'simple-secondary',
+  'simple-tertiary',
+  'categorical-1',
+  'categorical-2',
+  'categorical-3',
+  'categorical-4',
+  'categorical-5',
+  'categorical-6',
+];
+
+const ELECTRIC = [
+  { month: 'Jan', bill: 128 },
+  { month: 'Feb', bill: 212 },
+  { month: 'Mar', bill: 121 },
+  { month: 'Apr', bill: 109 },
+  { month: 'May', bill: 102 },
+  { month: 'Jun', bill: 118 },
+];
+
+const SPIKE_INDEX = 1;
+
+const formatDollars: ChartValueFormatter = (value) => (value === null ? '' : `$${value}`);
+
+export default function BarChartColorsDemo() {
+  const [color, setColor] = useState<string>('warning');
+
+  return (
+    <Tabs value={color} onValueChange={setColor} className="w-full">
+      <Box className="w-90 max-w-full self-center">
+        <Tabs.List accessibilityLabel="Bar color">
+          {COLORS.map((item) => (
+            <Tabs.Tab key={item} value={item}>
+              <Tabs.TabLabel>{item}</Tabs.TabLabel>
+            </Tabs.Tab>
+          ))}
+        </Tabs.List>
+      </Box>
+      {COLORS.map((item) => (
+        <Tabs.Panel key={item} value={item} className="mt-4">
+          <BarChart
+            dataset={ELECTRIC}
+            xAxis={[{ id: 'month', dataKey: 'month', scaleType: 'band' }]}
+            yAxis={[{ id: 'bill', position: 'none', max: 240 }]}
+            series={[
+              {
+                id: 'bill',
+                dataKey: 'bill',
+                label: 'Electric bill',
+                color: item,
+                valueFormatter: formatDollars,
+              },
+            ]}
+            grid={{ horizontal: false }}
+            emphasizedIndex={SPIKE_INDEX}
+            barLabel
+            hideLegend
+            scrollable={false}
+            accessibilityLabel="Electric bill by month. February is $212, about $95 above the usual bill."
+          />
+        </Tabs.Panel>
+      ))}
+    </Tabs>
+  );
+}
+```
+
+## Stacking groups
+
+Series with the same `stack` id pile into one bar. Different ids draw side by side, so one category can hold two stacks. `barLabel` labels each stack with its total. `stackGap` sets the gap between segments, and with a gap every segment is rounded. The second chart passes `stackGap={0}` to join the segments and `borderRadius={0}` to square the corners.
+
+```tsx
+import { BarChart, VStack, type BarChartSeries, type ChartAxis } from '@cdx-ui/components';
+import { PIPELINE, type QuarterPipeline } from './_data';
+
+const PIPELINE_SERIES: BarChartSeries<QuarterPipeline>[] = [
+  { id: 'newLoans', dataKey: 'newLoans', label: 'New loans', stack: 'loans' },
+  { id: 'renewals', dataKey: 'renewals', label: 'Renewals', stack: 'loans' },
+  { id: 'newCards', dataKey: 'newCards', label: 'New cards', stack: 'cards' },
+  { id: 'upgrades', dataKey: 'upgrades', label: 'Upgrades', stack: 'cards' },
+];
+
+const QUARTER_AXIS: ChartAxis<QuarterPipeline>[] = [
+  { id: 'quarter', dataKey: 'quarter', scaleType: 'band' },
+];
+
+export default function BarChartStackedDemo() {
+  return (
+    <VStack space="2xl" className="w-full">
+      <BarChart
+        dataset={PIPELINE}
+        xAxis={QUARTER_AXIS}
+        series={PIPELINE_SERIES}
+        barLabel
+        scrollable={false}
+        accessibilityLabel="Loans and cards by quarter"
+      />
+      <BarChart
+        dataset={PIPELINE}
+        xAxis={QUARTER_AXIS}
+        series={PIPELINE_SERIES}
+        stackGap={0}
+        borderRadius={0}
+        barLabel
+        scrollable={false}
+        accessibilityLabel="Loans and cards by quarter, flat stacks"
+      />
+    </VStack>
+  );
+}
+```
+
+## Stack expand
+
+`stackOffset: 'expand'` on any series in the group scales every category to the same length, so each segment shows its share. Ticks, tooltip, and labels read percentages, and an axis `valueFormatter` receives a 0–1 share.
+
+```tsx
+import { BarChart } from '@cdx-ui/components';
+import { PLATFORMS } from './_data';
+
+export default function BarChartStacked100Demo() {
+  return (
+    <BarChart
+      dataset={PLATFORMS}
+      xAxis={[{ id: 'month', dataKey: 'month', scaleType: 'band' }]}
+      series={[
+        { id: 'ios', dataKey: 'ios', label: 'iOS', stack: 'share', stackOffset: 'expand' },
+        { id: 'android', dataKey: 'android', label: 'Android', stack: 'share' },
+        { id: 'web', dataKey: 'web', label: 'Web', stack: 'share' },
+      ]}
+      scrollable={false}
+      accessibilityLabel="Sessions by platform"
+    />
+  );
+}
+```
+
+## Negative values
+
+Values below zero grow down from a zero baseline. The axis includes zero unless `min` says otherwise, so gains and losses read against the same line.
+
+```tsx
+import { BarChart } from '@cdx-ui/components';
+import { MONTH_AXIS, PROFIT } from './_data';
+
+export default function BarChartNegativeDemo() {
+  return (
+    <BarChart
+      dataset={PROFIT}
+      xAxis={MONTH_AXIS}
+      series={[{ id: 'profit', dataKey: 'value', label: 'Profit' }]}
+      barLabel
+      hideLegend
+      scrollable={false}
+      accessibilityLabel="Monthly profit"
+    />
+  );
+}
+```
+
+## Overlay
+
+`overlay: { seriesId }` draws a series as a thinner comparison bar beside the series it names — this month versus last month, or actual versus budget. Screen readers hear the change after the primary value, worded by `localeText.trend`.
+
+```tsx
+import { BarChart } from '@cdx-ui/components';
+import { formatUsd, SPENDING } from './_data';
+
+export default function BarChartOverlayDemo() {
+  return (
+    <BarChart
+      dataset={SPENDING}
+      layout="horizontal"
+      yAxis={[{ id: 'category', dataKey: 'category', scaleType: 'band' }]}
+      series={[
+        { id: 'this', dataKey: 'thisMonth', label: 'This month', valueFormatter: formatUsd },
+        {
+          id: 'last',
+          dataKey: 'lastMonth',
+          label: 'Last month',
+          overlay: { seriesId: 'this' },
+          valueFormatter: formatUsd,
+        },
+      ]}
+      barLabel
+      grid={{ vertical: false }}
+      xAxis={[{ id: 'amount', position: 'none' }]}
+      scrollable={false}
+      height={280}
+      accessibilityLabel="Spending this month versus last month"
+    />
+  );
+}
+```
+
+## Waterfall
+
+`waterfall: { totalKey }` turns a series into a running total. Each row is a change, except rows where your `totalKey` column is `true`: those draw from zero to the total so far. Pick any boolean column — a column named `sum` is ordinary data. Step names come from `localeText.waterfallIncrease` and `localeText.waterfallDecrease`.
+
+```tsx
+import { BarChart } from '@cdx-ui/components';
+import { formatUsd, WATERFALL } from './_data';
+
+export default function BarChartWaterfallDemo() {
+  return (
+    <BarChart
+      dataset={WATERFALL}
+      layout="horizontal"
+      yAxis={[{ id: 'step', dataKey: 'step', scaleType: 'band' }]}
+      series={[
+        {
+          id: 'balance',
+          dataKey: 'amount',
+          waterfall: { totalKey: 'isTotal' },
+          valueFormatter: formatUsd,
+        },
+      ]}
+      barLabel
+      grid={{ vertical: false }}
+      xAxis={[{ id: 'amount', position: 'none' }]}
+      scrollable={false}
+      height={280}
+      accessibilityLabel="Checking starting balance, income, expenses, and ending balance"
+    />
+  );
+}
+```
+
+## Reference line
+
+`referenceLines` draws a dashed line at a value. `emphasizedIndex` keeps one bar in full color and mutes the rest — this week against a typical week. An empty category name hides that label.
+
+```tsx
+import { BarChart } from '@cdx-ui/components';
+import { DINING_WEEKS, formatWholeUsd } from './_data';
+
+export default function BarChartReferenceDemo() {
+  return (
+    <BarChart
+      dataset={DINING_WEEKS}
+      xAxis={[{ id: 'week', dataKey: 'week', scaleType: 'band' }]}
+      series={[{ id: 'dining', dataKey: 'spend', valueFormatter: formatWholeUsd }]}
+      grid={{ horizontal: false }}
+      yAxis={[{ id: 'spend', position: 'none' }]}
+      hideLegend
+      barLabel
+      emphasizedIndex={DINING_WEEKS.length - 1}
+      referenceLines={[{ value: 340, label: 'Typical week $340' }]}
+      scrollable={false}
+      accessibilityLabel="Dining versus a typical week"
+    />
+  );
+}
+```
+
+## Scrollable
+
+When there are more categories than fit, the plot scrolls while the value axis stays put. `visiblePoints` sets how many categories are on screen at once.
+
+```tsx
+import { BarChart, Box } from '@cdx-ui/components';
+import { WEEKS } from './_data';
+
+export default function BarChartScrollableDemo() {
+  return (
+    <Box className="w-64">
+      <BarChart
+        dataset={WEEKS}
+        xAxis={[{ id: 'week', dataKey: 'week', scaleType: 'band' }]}
+        series={[{ id: 'spend', dataKey: 'spend' }]}
+        hideLegend
+        visiblePoints={6}
+        accessibilityLabel="Weekly spend"
+      />
+    </Box>
+  );
+}
+```
+
+## Selectable
+
+Pass `selectedItem` and `onSelectedItemChange` to dim unselected bars. The item is `{ seriesId, dataIndex }`, where `dataIndex` is the `dataset` row. Pressing the selected bar again reports `null`. Use `defaultSelectedItem` for an uncontrolled chart.
+
+```tsx
+import { useState } from 'react';
+import { BarChart, Text, VStack, type ChartSelectedItem } from '@cdx-ui/components';
+import { GROUPED, GROUPED_AXIS, SERIES } from './_data';
+
+export default function BarChartSelectableDemo() {
+  const [selectedItem, setSelectedItem] = useState<ChartSelectedItem>({
+    seriesId: 'retail',
+    dataIndex: 1,
+  });
+  const row = selectedItem === null ? undefined : GROUPED[selectedItem.dataIndex];
+  const series = SERIES.find((item) => item.id === selectedItem?.seriesId);
+
+  return (
+    <VStack space="md" className="w-full">
+      <Text size="sm" color="secondary">
+        {row !== undefined && series !== undefined
+          ? `${row.month} ${series.label ?? ''} ${String(row[series.dataKey])}`
+          : 'Select a bar'}
+      </Text>
+      <BarChart
+        dataset={GROUPED}
+        xAxis={GROUPED_AXIS}
+        series={SERIES}
+        scrollable={false}
+        selectedItem={selectedItem}
+        onSelectedItemChange={setSelectedItem}
+      />
+    </VStack>
+  );
+}
+```
+
+## Data change
+
+Bars tween to their new values when `dataset` changes. Pass `animation="disable-all"` to draw the final state; Reduce Motion and `GlobalAnimationSettingsProvider` `disable-all` also turn it off.
+
+```tsx
+import { useState } from 'react';
+import { BarChart, Button, VStack } from '@cdx-ui/components';
+import { GROUPED, GROUPED_AXIS, SERIES } from './_data';
+
+export default function BarChartDataChangeDemo() {
+  const [step, setStep] = useState(0);
+  const dataset = GROUPED.map((row, index) => {
+    const shifted = GROUPED[(index + step) % GROUPED.length] ?? row;
+    return { ...shifted, month: row.month };
+  });
+
+  return (
+    <VStack space="lg" className="w-full items-center">
+      <BarChart
+        dataset={dataset}
+        xAxis={GROUPED_AXIS}
+        series={SERIES}
+        barLabel
+        scrollable={false}
+        accessibilityLabel="Signups by channel"
+      />
+      <Button
+        variant="outline"
+        onPress={() => {
+          setStep((prev) => prev + 1);
+        }}
+      >
+        <Button.Label>Shift data</Button.Label>
+      </Button>
+    </VStack>
+  );
+}
+```
+
+## API
+
+### BarChart
+
+Generic over your row type, shown here as `TRow`: `series[].dataKey` and axis `dataKey` must be keys of a `dataset` row.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | Additional Uniwind/Tailwind classes, merged after the root's own styles. |
+| `accessibilityLabel?` | `string` | — | Accessible summary. Defaults to `localeText.barChartSummary` over every category. |
+| `dataset` | `readonly TRow[]` | — | One object per category. Series and axes read it through `dataKey`. |
+| `series` | `readonly BarChartSeries<TRow>[]` | — | Bars to draw. Each reads one numeric column through `dataKey`. |
+| `xAxis?` | `readonly ChartAxis<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. |
+| `yAxis?` | `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. |
+| `layout?` | `'vertical' \| 'horizontal'` | `'vertical'` | `vertical` grows bars up from the baseline. `horizontal` grows them to the right. |
+| `hideLegend?` | `boolean` | `false` | Hides the series legend under the chart. Waterfall charts never show one. |
+| `grid?` | `ChartGrid` | `{ horizontal: true } (vertical layout), { vertical: true } (horizontal layout)` | 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. |
+| `palette?` | `'auto' \| 'categorical'` | `'auto'` | 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. |
+| `referenceLines?` | `readonly ChartReferenceLine[]` | — | Dashed guides at a value: horizontal on a vertical chart, vertical on a horizontal chart. |
+| `emphasizedIndex?` | `number` | — | 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. |
+| `barLabel?` | `boolean` | `false` | Draws formatted values at the end of each bar (each stack's total when stacked). |
+| `borderRadius?` | `number` | `6` | Corner radius in pixels. `0` draws square bars. |
+| `stackGap?` | `number` | `3` | Pixel gap between stacked segments. With a gap every segment is rounded; `0` joins them and rounds only the outer cap. |
+| `categoryGapRatio?` | `number` | `0.36` | Share of each category slot left empty around its bars, from `0` to `0.95`. Higher is thinner bars with more space between categories. |
+| `barGapRatio?` | `number` | `0.5` | Gap between side-by-side bars in one category, as a share of one bar's thickness. |
+| `scrollable?` | `boolean` | `true` | 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`. |
+| `visiblePoints?` | `number` | — | How many categories fit in the viewport when `scrollable` is on. Omit to use a readable minimum band (~48px). |
+| `selectedItem?` | `ChartSelectedItem` | — | Controlled selected bar: `seriesId` and the `dataset` row. `null` clears the selection while staying controlled. |
+| `defaultSelectedItem?` | `ChartSelectedItem` | — | Initial selected bar when `selectedItem` is omitted. |
+| `onSelectedItemChange?` | `((item: ChartSelectedItem) => void)` | — | 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. |
+| `tooltip?` | `ChartTooltipProps` | `{ trigger: 'axis' }` | 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. |
+| `locale?` | `string` | — | BCP 47 locale for default number and percent formatting. |
+| `localeText?` | `Partial<ChartLocaleText>` | — | Overrides for generated strings: summary, trend, waterfall step names, legend fallback, and no-value text. Keys you omit keep the English defaults. |
+| `animation?` | `'disable-all'` | — | 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. |
+| `size?` | `'sm' \| 'md' \| 'lg' \| 'xl'` | `'lg'` | Plot box. Named sizes set both width and height; `width` / `height` override one side. |
+| `width?` | `number` | — | Pixel width. Overrides the `size` width. |
+| `height?` | `number` | — | Pixel height. Overrides the `size` height. |
+
+Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props).
+
+| Attribute       | Values            | Description                                                     |
+| --------------- | ----------------- | --------------------------------------------------------------- |
+| `data-selected` | `true` \| `false` | On each `bar-chart-point`: whether that bar is the selected one |
+
+### BarChartSeries
+
+One entry in `series`. The first series with `waterfall`, or the first `overlay` pair, draws alone.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `type?` | `'bar'` | — | Series type. Reserved for mixed charts; bar is the only type today. |
+| `stack?` | `string` | — | 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. |
+| `stackOffset?` | `'diverging' \| 'none' \| 'expand'` | `'diverging'` | How the stack group piles its values. Set it on any one series in the group. `expand` scales each category to 100%. |
+| `waterfall?` | `BarChartWaterfall<TRow>` | — | Draws the series as a waterfall (running total). A waterfall series draws alone: other series are not plotted. |
+| `overlay?` | `BarChartOverlay` | — | 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. |
+| `dataKey` | `string` | — | Numeric column in `dataset`. A key that is not on the row type is a compile error. |
+| `id` | `string` | — | Stable id. `selectedItem.seriesId` and tooltip items refer to it. |
+| `label?` | `string` | — | Series name. Bar and line charts show it in the legend, tooltip, and screen reader text. A pie chart only prefixes tooltip values with it; slice labels name the legend and slices. |
+| `color?` | `'danger' \| 'warning' \| 'success' \| 'info' \| 'simple-primary' \| 'simple-secondary' \| 'simple-tertiary' \| 'categorical-1' \| 'categorical-2' \| 'categorical-3' \| 'categorical-4' \| 'categorical-5' \| 'categorical-6'` | — | Chart token name, not a CSS color. Omit to take the next color from the chart's `palette`. |
+| `valueFormatter?` | `ChartValueFormatter` | — | Formats this series' values for tooltips and screen reader text, plus bar value labels, line marker values, and a pie's legend value column. `context.location` says where. On charts with axes it wins over the value axis `valueFormatter`. |
+
+### ChartAxis
+
+One entry in `xAxis` or `yAxis`. Only the first entry in each direction is read.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `id` | `string` | — | Axis id, as in MUI X. |
+| `dataKey?` | `string` | — | Column in `dataset` that holds this axis's values (category names on a band axis). |
+| `scaleType?` | `'band' \| 'linear'` | — | Scale kind, as in MUI X. Accepted for parity; charts do not read it yet. |
+| `min?` | `number` | — | Lowest value on a value axis. Omit to fit the data. |
+| `max?` | `number` | — | Highest value on a value axis. Omit to fit the data. |
+| `tickNumber?` | `number` | — | Approximate tick count. The chart rounds to readable steps. |
+| `label?` | `string` | — | Axis title, as in MUI X. Accepted for parity; not drawn yet. |
+| `valueFormatter?` | `ChartValueFormatter` | — | Formats tick text on this axis (`location: 'tick'`). On a value axis it also formats series values when the series has no `valueFormatter`. On a line chart's x-axis it formats numeric categories, both the tick (`location: 'tick'`) and the tooltip title (`location: 'tooltip'`). |
+| `position?` | `'top' \| 'bottom' \| 'left' \| 'right' \| 'none'` | — | Side the axis labels draw on. `'none'` hides them. Each chart accepts the sides it can draw and falls back to its default side for the others. |
+| `tickLabelInterval?` | `"auto" \| ((value: unknown, index: number) => boolean)` | `'auto'` | Which category labels to draw. A function keeps the label at `index` when it returns `true`. `'auto'` currently draws every label; it does not thin them yet. |
+
+Formatters resolve per value: the series `valueFormatter`, then the value axis `valueFormatter`, then a `locale` number. Ticks use the axis formatter with `location: 'tick'`.
+
+On the value axis, `position: 'none'` hides the ticks; any other side falls back to the default (left in `vertical` layout, bottom in `horizontal`). On the category axis, `position` picks the side for the names. `tickLabelInterval: 'auto'` pins the first and last names inside the plot.
+
+### ChartLocaleText
+
+Every string the chart generates. Pass any subset as `localeText`.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `noData` | `string` | — | Shown when there is nothing to plot. |
+| `noValue` | `string` | — | Tooltip and screen reader text for a category with no value. |
+| `defaultSeriesLabel` | `string` | — | Legend name for a series without a `label`. |
+| `waterfallIncrease` | `string` | — | Waterfall step that raises the running total. |
+| `waterfallDecrease` | `string` | — | Waterfall step that lowers the running total. |
+| `trend` | `(trend: ChartTrend) => string` | — | Change against the comparison series, read after the value. |
+| `barChartSummary` | `(categories: readonly ChartSummaryCategory[]) => string` | — | Bar chart summary. Called with an empty list when there is no data. |
+| `lineChartSummary` | `(latest: ChartSummaryCategory \| null) => string` | — | Line chart summary of the latest category. `null` when there is no data. |
+| `pieChartSummary` | `(slices: readonly ChartSummaryValue[]) => string` | — | Pie chart summary. `formattedValue` is the share. Empty list when there is no data. |
+
+### Coming from MUI X
+
+Forge renders with `react-native-svg` on iOS, Android, and web, and does not depend on MUI. The props follow MUI X Charts names so a migration is mostly a copy.
+
+| MUI X                                                                                          | Forge                                                        | Notes                                                                                                                                                                                      |
+| ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `dataset`                                                                                      | `dataset`                                                    | Same.                                                                                                                                                                                      |
+| `series[].dataKey`, `id`, `label`, `color`, `valueFormatter`                                   | same names                                                   | `color` is a chart token name, not a CSS color, so FI themes and dark mode recolor it.                                                                                                     |
+| `series[].data`                                                                                | —                                                            | Read values from `dataset` through `dataKey`.                                                                                                                                              |
+| `series[].stack`, `stackOffset`                                                                | same names                                                   | `'diverging'`, `'none'`, and `'expand'`. `stackOrder` is not supported yet.                                                                                                                |
+| `xAxis` / `yAxis` (`id`, `dataKey`, `scaleType`, `min`, `max`, `tickNumber`, `valueFormatter`) | same names                                                   | Only the first axis in each direction is read, and only `band` category axes render today.                                                                                                 |
+| `layout`                                                                                       | `layout`                                                     | Same. The category axis moves to `yAxis` in `horizontal`, as in MUI X.                                                                                                                     |
+| `borderRadius`                                                                                 | `borderRadius`                                               | Same.                                                                                                                                                                                      |
+| `barLabel`                                                                                     | `barLabel`                                                   | A chart-level boolean. MUI X takes `'value'` or a function, per series in recent versions. Format label text with the series `valueFormatter` (`location: 'label'`).                       |
+| `xAxis[].categoryGapRatio`, `barGapRatio`                                                      | `categoryGapRatio`, `barGapRatio`                            | Same meaning, but chart-level props: Forge has one band axis, and the shared `ChartAxis` type is the same for every chart.                                                                 |
+| `hideLegend`                                                                                   | `hideLegend`                                                 | Same default (`false`).                                                                                                                                                                    |
+| `colors`                                                                                       | `palette` + series `color`                                   | MUI takes CSS colors or a function. Forge takes chart token names, so FI themes and dark mode recolor every chart: `palette` picks the default ramp, and a series `color` names one token. |
+| `slotProps.tooltip.trigger`                                                                    | `tooltip.trigger`                                            | `'axis'` by default, as in MUI X. Custom tooltip content is not supported yet.                                                                                                             |
+| `grid={{ horizontal, vertical }}`                                                              | `grid`                                                       | Same shape, but only the lines along the value axis draw, and they are on by default. MUI draws no grid unless you pass `grid`.                                                            |
+| axis `position`                                                                                | axis `position`                                              | `'none'` hides an axis. The value axis draws only on its default side.                                                                                                                     |
+| axis `tickLabelInterval`                                                                       | axis `tickLabelInterval`                                     | The function form works on the category axis. `'auto'` draws every label for now.                                                                                                          |
+| `<ChartsReferenceLine>`                                                                        | `referenceLines`                                             | Forge has no composition API yet, so reference lines are a prop.                                                                                                                           |
+| `highlightedItem` / `onItemClick`                                                              | `selectedItem` / `onSelectedItemChange`                      | Selection is shared by every Forge chart. Pressing the selected bar reports `null`. `defaultSelectedItem` is a Forge addition for uncontrolled use.                                        |
+| `skipAnimation`                                                                                | `animation="disable-all"`                                    | Matches the `animation` prop on other Forge components.                                                                                                                                    |
+| `localeText`                                                                                   | `localeText`                                                 | Keys are Forge's: `barChartSummary`, `trend`, `waterfallIncrease`, `waterfallDecrease`, `defaultSeriesLabel`, `noValue`.                                                                   |
+| —                                                                                              | `waterfall: { totalKey }`                                    | MUI X has no waterfall series.                                                                                                                                                             |
+| —                                                                                              | `overlay: { seriesId }`                                      | MUI X has no comparison overlay. The option names the series it compares against, the way `selectedItem` does.                                                                             |
+| —                                                                                              | `emphasizedIndex`, `scrollable`, `visiblePoints`, `stackGap` | Forge additions for insight cards and long category lists.                                                                                                                                 |
+
+## Anatomy
+
+| `data-slot`             | Element                                                         |
+| ----------------------- | --------------------------------------------------------------- |
+| `bar-chart`             | Root                                                            |
+| `bar-chart-plot`        | Plot area: axes, bars, and the inspector overlay                |
+| `bar-chart-inspector`   | Overlay of bar hit targets, when the tooltip or selection is on |
+| `bar-chart-point`       | Hit target for one bar                                          |
+| `bar-chart-focus`       | Keyboard focus ring                                             |
+| `bar-chart-tooltip`     | Tooltip                                                         |
+| `bar-chart-legend`      | Legend                                                          |
+| `bar-chart-legend-item` | One legend entry                                                |
+
+## Accessibility
+
+By default the plot is a group with the chart summary as its label, and every drawn bar inside it is a button. When the chart has no tooltip (`tooltip={{ trigger: 'none' }}`), no selection props, and `hideLegend`, the root becomes a single `accessibilityRole="image"` with the summary as its label instead. With a legend but no tooltip or selection, only the legend text is read and no summary is announced. The summary comes from `localeText.barChartSummary`, which receives each category's values formatted with `location: 'a11y'`. Pass `accessibilityLabel` to replace it, or `localeText` to reword or translate it.
+
+Axes, grid, bars, and value labels are SVG hidden from assistive technology, as are the tooltip and the focus ring. Legend names stay readable. Each bar is named by its category, series label, and formatted value, such as "Feb, Paid, 34". Waterfall steps take `localeText.waterfallIncrease` or `localeText.waterfallDecrease` as their series name. In an overlay pair, the primary bar's name ends with the change worded by `localeText.trend`, and the comparison bar is announced on its own.
+
+On web the plot is one tab stop. Arrow keys move between bars, Home and End jump to the first or last category, Tab and Shift+Tab step through categories before leaving the chart, and Escape hides the tooltip. On native every bar is focusable and the escape gesture hides the tooltip. In a selectable chart, pressing a bar or pressing Enter or Space toggles its selection, exposed as `aria-pressed` on web and `accessibilityState.selected` on native.