@cdx-ui/components 0.3.5 → 0.3.7

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

@@ -0,0 +1,567 @@
+# Line Chart (https://design.candescent.com/docs/components/line-chart)
+
+Resources: [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/charts-linechart--default)
+
+`LineChart` takes your own rows in `dataset`. `xAxis[0].dataKey` names the category column and each `series[].dataKey` names a value column, so no row key is reserved — a column called `label` or `tick` is plain data. The [Insights Overview](https://design.candescent.com/docs/patterns/dashboard/content.md#insights-overview) pattern shows a compact line chart beside a headline figure.
+
+```tsx
+import { LineChart } from '@cdx-ui/components';
+```
+
+## Basic
+
+One series with `area: true`. The value domain comes from the data and does not force zero.
+
+```tsx
+import { LineChart } from '@cdx-ui/components';
+import { MONTH_AXIS, REVENUE, REVENUE_SERIES } from './_data';
+
+export default function LineChartBasicDemo() {
+  return (
+    <LineChart
+      dataset={REVENUE}
+      xAxis={MONTH_AXIS}
+      series={REVENUE_SERIES}
+      hideLegend
+      scrollable={false}
+      accessibilityLabel="Monthly revenue"
+    />
+  );
+}
+```
+
+## 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 { Box, LineChart, Slider, VStack } from '@cdx-ui/components';
+import { FORECAST, FORECAST_AXIS, SERIES } from './_data';
+
+const SIZES = ['sm', 'md', 'lg', 'xl'] as const;
+
+export default function LineChartSizesDemo() {
+  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>
+      <LineChart
+        key={size}
+        dataset={FORECAST}
+        xAxis={FORECAST_AXIS}
+        series={SERIES}
+        size={size}
+        scrollable={false}
+        accessibilityLabel="Actual versus forecast"
+      />
+    </VStack>
+  );
+}
+```
+
+## Multi-series
+
+Each `series` entry is a line. Up to three series use the FI brand family in the order `simple-primary`, `simple-tertiary`, `simple-secondary`, so two lines pair neighboring brand steps. Four or more switch the whole chart to `categorical-1`…`6`; pass `palette="categorical"` to use them at any count. A series `color` wins. `dashed: true` dashes that whole series.
+
+```tsx
+import { LineChart } from '@cdx-ui/components';
+import { FORECAST, FORECAST_AXIS, SERIES } from './_data';
+
+export default function LineChartMultiSeriesDemo() {
+  return (
+    <LineChart
+      dataset={FORECAST}
+      xAxis={FORECAST_AXIS}
+      series={SERIES}
+      scrollable={false}
+      accessibilityLabel="Actual versus forecast"
+    />
+  );
+}
+```
+
+## Colors
+
+A series `color` can also be a severity token: `danger`, `warning`, `success`, or `info`. A single line in a severity color reads as a status, here a falling credit score. `warning` is a light yellow that is hard to see as a thin line on a light surface, so prefer it for fills such as bars and slices.
+
+```tsx
+import { useState } from 'react';
+import { Box, LineChart, Tabs, type ChartAxis, type ChartColor } 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',
+];
+
+interface ScoreRow {
+  date: string;
+  score: number;
+}
+
+const SCORES: ScoreRow[] = [
+  { date: 'Nov 1', score: 575 },
+  { date: 'Nov 4', score: 568 },
+  { date: 'Nov 8', score: 570 },
+  { date: 'Nov 11', score: 563 },
+  { date: 'Nov 15', score: 559 },
+  { date: 'Nov 18', score: 560 },
+  { date: 'Nov 22', score: 557 },
+  { date: 'Nov 25', score: 553 },
+  { date: 'Nov 29', score: 555 },
+  { date: 'Dec 1', score: 558 },
+  { date: 'Dec 4', score: 556 },
+  { date: 'Dec 8', score: 552 },
+  { date: 'Dec 11', score: 554 },
+  { date: 'Dec 15', score: 555 },
+  { date: 'Dec 18', score: 557 },
+  { date: 'Dec 22', score: 556 },
+  { date: 'Dec 25', score: 558 },
+  { date: 'Dec 29', score: 557 },
+  { date: 'Jan 1', score: 554 },
+  { date: 'Jan 4', score: 550 },
+  { date: 'Jan 8', score: 549 },
+  { date: 'Jan 11', score: 547 },
+];
+
+const MONTH_STARTS = new Set([0, 9, 18]);
+
+const DATE_AXIS: ChartAxis<ScoreRow>[] = [
+  { id: 'date', dataKey: 'date', tickLabelInterval: (_, index) => MONTH_STARTS.has(index) },
+];
+
+const SCORE_AXIS: ChartAxis<ScoreRow>[] = [{ id: 'score', min: 540, max: 580, tickNumber: 3 }];
+
+export default function LineChartColorsDemo() {
+  const [color, setColor] = useState<string>('danger');
+
+  return (
+    <Tabs value={color} onValueChange={setColor} className="w-full">
+      <Box className="w-90 max-w-full self-center">
+        <Tabs.List accessibilityLabel="Line 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">
+          <LineChart
+            dataset={SCORES}
+            xAxis={DATE_AXIS}
+            yAxis={SCORE_AXIS}
+            series={[
+              {
+                id: 'score',
+                dataKey: 'score',
+                label: 'Credit score',
+                curve: 'linear',
+                color: item,
+              },
+            ]}
+            markers={[{ dataIndex: SCORES.length - 1, showValue: true, guide: false }]}
+            hideLegend
+            size="md"
+            scrollable={false}
+            accessibilityLabel="Credit score fell from 575 to 547 since Nov 1"
+          />
+        </Tabs.Panel>
+      ))}
+    </Tabs>
+  );
+}
+```
+
+## Curves and area
+
+`curve`, `area`, `showMark`, `color`, `dashed`, and `dashedFrom` are set per series, so one line can be a filled `monotoneX` curve while the next is a marked `linear` line that dashes from a row. `stepAfter` holds each value until the next point.
+
+```tsx
+import { LineChart, VStack } from '@cdx-ui/components';
+import { FORECAST, FORECAST_AXIS, MONTH_AXIS, REVENUE } from './_data';
+
+export default function LineChartCurvesDemo() {
+  return (
+    <VStack space="2xl">
+      <LineChart
+        dataset={FORECAST}
+        xAxis={FORECAST_AXIS}
+        series={[
+          {
+            id: 'actual',
+            dataKey: 'actual',
+            label: 'Actual',
+            color: 'categorical-3',
+            curve: 'monotoneX',
+            area: true,
+          },
+          {
+            id: 'forecast',
+            dataKey: 'forecast',
+            label: 'Forecast',
+            color: 'categorical-5',
+            curve: 'linear',
+            showMark: true,
+            dashedFrom: 3,
+          },
+        ]}
+        scrollable={false}
+        accessibilityLabel="Actual as a filled curve, forecast as a marked line dashed from April"
+      />
+      <LineChart
+        dataset={REVENUE}
+        xAxis={MONTH_AXIS}
+        series={[
+          {
+            id: 'revenue',
+            dataKey: 'revenue',
+            label: 'Revenue',
+            curve: 'stepAfter',
+            showMark: true,
+          },
+        ]}
+        hideLegend
+        scrollable={false}
+        accessibilityLabel="Monthly revenue, step"
+      />
+    </VStack>
+  );
+}
+```
+
+## Axes and reference lines
+
+`yAxis[0]` `min` and `max` pin the domain and `tickNumber` sets roughly how many ticks to draw. `valueFormatter` on the axis formats ticks, and on a series formats that series everywhere. `referenceLines` draws a dashed target across the plot.
+
+```tsx
+import { LineChart } from '@cdx-ui/components';
+import { ATTAINMENT, MONTH_AXIS } from './_data';
+
+export default function LineChartReferenceLineDemo() {
+  return (
+    <LineChart
+      dataset={ATTAINMENT}
+      xAxis={MONTH_AXIS}
+      yAxis={[
+        {
+          id: 'attainment',
+          min: 0,
+          max: 200,
+          tickNumber: 5,
+          valueFormatter: (value) => (value === null ? '' : `${String(value)}%`),
+        },
+      ]}
+      series={[{ id: 'attainment', dataKey: 'revenue', label: 'Attainment' }]}
+      referenceLines={[{ value: 100, label: 'Plan' }]}
+      hideLegend
+      scrollable={false}
+      accessibilityLabel="Attainment against plan"
+    />
+  );
+}
+```
+
+## Scrollable
+
+Long histories scroll while the value axis stays put. `visiblePoints` sets how many points are on screen at once.
+
+```tsx
+import { Box, LineChart } from '@cdx-ui/components';
+import { HISTORY, HISTORY_SERIES, WEEK_AXIS } from './_data';
+
+export default function LineChartScrollableDemo() {
+  return (
+    <Box className="w-64">
+      <LineChart
+        dataset={HISTORY}
+        xAxis={WEEK_AXIS}
+        series={HISTORY_SERIES}
+        hideLegend
+        visiblePoints={8}
+        accessibilityLabel="Weekly price"
+      />
+    </Box>
+  );
+}
+```
+
+## Markers
+
+`dashedFrom` takes a `dataset` row, so a balance can stay solid through today and dash after it. `markers` pin callouts by `dataIndex`, and rows that share a label resolve independently. `xAxis[0].tickLabelInterval` labels only the week starts while every day is plotted.
+
+```tsx
+import { LineChart } from '@cdx-ui/components';
+import { CASH, CASH_AXIS, CASH_SERIES, TODAY_INDEX } from './_data';
+
+export default function LineChartMarkersDemo() {
+  return (
+    <LineChart
+      dataset={CASH}
+      xAxis={CASH_AXIS}
+      series={CASH_SERIES}
+      hideLegend
+      scrollable={false}
+      markers={[
+        { dataIndex: TODAY_INDEX, label: 'Rent' },
+        { dataIndex: 21, color: 'categorical-2', guide: false },
+        { dataIndex: 22, label: 'Card bill', dot: false },
+      ]}
+      accessibilityLabel="Checking balance forecast. Rent on Sep 21. Lowest on Oct 3. Card bill on Oct 4."
+    />
+  );
+}
+```
+
+## Selectable
+
+Pass `selectedItem` and `onSelectedItemChange` to select a category. The item names the category's `dataIndex` and the first series with a value there; pressing the selected category again reports `null`. Pass `defaultSelectedItem` or only `onSelectedItemChange` to let the chart track selection itself.
+
+```tsx
+import { useState } from 'react';
+import { LineChart, Text, VStack, type ChartSelectedItem } from '@cdx-ui/components';
+import { FORECAST, FORECAST_AXIS, SERIES } from './_data';
+
+const MARKED_SERIES = SERIES.map((item) => ({ ...item, showMark: true }));
+
+export default function LineChartSelectableDemo() {
+  const [selectedItem, setSelectedItem] = useState<ChartSelectedItem>({
+    seriesId: 'actual',
+    dataIndex: 3,
+  });
+  const row = selectedItem === null ? undefined : FORECAST[selectedItem.dataIndex];
+
+  return (
+    <VStack space="md" className="w-full">
+      <Text size="sm" color="secondary">
+        {row === undefined
+          ? 'Nothing selected'
+          : `${row.month} actual ${String(row.actual)} forecast ${String(row.forecast)}`}
+      </Text>
+      <LineChart
+        dataset={FORECAST}
+        xAxis={FORECAST_AXIS}
+        series={MARKED_SERIES}
+        scrollable={false}
+        selectedItem={selectedItem}
+        onSelectedItemChange={setSelectedItem}
+      />
+    </VStack>
+  );
+}
+```
+
+## Data change
+
+Lines 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 { Button, LineChart, VStack } from '@cdx-ui/components';
+import { FORECAST, FORECAST_AXIS, SERIES } from './_data';
+
+export default function LineChartDataChangeDemo() {
+  const [step, setStep] = useState(0);
+  const dataset = FORECAST.map((row, index) => {
+    const shifted = FORECAST[(index + step) % FORECAST.length] ?? row;
+    return { ...shifted, month: row.month };
+  });
+
+  return (
+    <VStack space="lg" className="w-full items-center">
+      <LineChart
+        dataset={dataset}
+        xAxis={FORECAST_AXIS}
+        series={SERIES}
+        scrollable={false}
+        accessibilityLabel="Actual versus forecast"
+      />
+      <Button
+        variant="outline"
+        onPress={() => {
+          setStep((prev) => prev + 1);
+        }}
+      >
+        <Button.Label>Shift data</Button.Label>
+      </Button>
+    </VStack>
+  );
+}
+```
+
+## API
+
+### LineChart
+
+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.lineChartSummary` of the last category. |
+| `dataset` | `readonly TRow[]` | — | One object per point, in x order. Columns are read only through `xAxis[0].dataKey` and `series[].dataKey`, so any key (including `label` or `tick`) is plain data. Non-finite values open a gap in that series. |
+| `series` | `readonly LineChartSeries<TRow>[]` | — | One line per entry. |
+| `xAxis?` | `readonly ChartAxis<TRow>[]` | — | Category axis. Only the first entry is read; `dataKey` names the column with the category labels (defaults to the row index). |
+| `yAxis?` | `readonly ChartAxis<TRow>[]` | — | Value axis. Only the first entry is read. `min` / `max` / `tickNumber` set the domain. `position: 'none'` hides the ticks; other sides draw on the left. |
+| `grid?` | `ChartGrid` | `{ horizontal: true }` | Grid lines behind the plot. Only `horizontal` (at each value tick) is drawn; it stays on unless set to `false`. |
+| `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. |
+| `hideLegend?` | `boolean` | `false` | Hides the series legend under the chart. |
+| `tooltip?` | `ChartTooltipProps` | `{ trigger: 'axis' }` | Shows every series at a category on hover, keyboard focus, or tap. On web, Tab / Shift+Tab and arrow keys move between categories, Tab past the last one leaves the chart, Home / End jump to the ends, and Escape hides the tooltip. `'item'` behaves like `'axis'` in v1. `'none'` hides it. |
+| `selectedItem?` | `ChartSelectedItem` | — | Controlled selection. `dataIndex` is the category; `seriesId` is the first series with a value there. `null` clears it. Omit to let the chart track selection itself. |
+| `defaultSelectedItem?` | `ChartSelectedItem` | — | Initial selection when `selectedItem` is omitted. Also makes the chart selectable. |
+| `onSelectedItemChange?` | `((item: ChartSelectedItem) => void)` | — | Called when a category is pressed, with `null` when the selected category is pressed again. Providing this, `selectedItem`, or `defaultSelectedItem` makes the chart selectable and draws a crosshair. |
+| `scrollable?` | `boolean` | `true` | When points need more room than the visible box, scroll instead of squeezing. The value axis stays pinned. |
+| `visiblePoints?` | `number` | — | How many points fit in the viewport when `scrollable` is on. Omit to use a readable minimum band (~32px). |
+| `referenceLines?` | `readonly ChartReferenceLine[]` | — | Dashed horizontal lines across the plot at a value, with an optional caption. |
+| `markers?` | `readonly LineChartMarker[]` | — | Point callouts (event name, value, extra legend row), pinned by `dataIndex`. |
+| `locale?` | `string` | — | BCP 47 locale for default number formatting. Defaults to the `@cdx-ui/formatters` locale. |
+| `localeText?` | `Partial<ChartLocaleText>` | — | Overrides for generated strings (summary, no-value text, default series name). |
+| `animation?` | `'disable-all'` | — | Lines rise 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 `line-chart-point`, whether that category is selected |
+
+### LineChartSeries
+
+One entry in `series`: a line that reads one `dataset` column.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `type?` | `'line'` | — | Series type. Optional on `LineChart`; reserved for charts that mix bars and lines. |
+| `curve?` | `'linear' \| 'monotoneX' \| 'stepAfter'` | `'monotoneX'` | How points connect. `stepAfter` holds each value until the next point. |
+| `area?` | `boolean` | `false` | Fills under the line toward zero (or the domain edge nearest it) with a fade of the series color. |
+| `showMark?` | `boolean \| ((params: { index: number; }) => boolean)` | `false` | Draws a mark on each defined point. A function picks points by `index` (the `dataset` row). |
+| `dashed?` | `boolean` | `false` | Dashes the whole line. |
+| `dashedFrom?` | `number` | — | `dataset` row where the line switches from solid to dashed (e.g. actual → forecast). The curve still uses every point, so the join stays smooth. |
+| `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
+
+`xAxis` and `yAxis` take the shared `ChartAxis`. `xAxis` reads `dataKey`, `tickLabelInterval`, `position`, and `valueFormatter` (for numeric categories); `yAxis` reads `min`, `max`, `tickNumber`, `position`, and `valueFormatter`. The x-axis draws at the bottom and the y-axis on the left; any `position` other than `'none'` falls back to that side. Categories are spaced edge to edge, like a MUI `point` scale.
+
+| 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. |
+
+### LineChartMarker
+
+One entry in `markers`: a callout pinned to a `dataset` row.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `dataIndex` | `number` | — | `dataset` row to pin to. Rows with the same category label resolve independently. |
+| `seriesId?` | `string` | — | Series to pin to. Defaults to the first series with a value at `dataIndex`. |
+| `label?` | `string` | — | Caption above the point, e.g. "Rent". |
+| `showValue?` | `boolean` | `false` | Draw the formatted value beside the point. |
+| `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 for the dot. Defaults to that series' color. |
+| `legend?` | `string` | — | Extra legend row, e.g. "Today". |
+| `guide?` | `boolean` | `true` | Vertical dashed guide through the point. |
+| `dot?` | `boolean` | `true` | Filled dot on the line. |
+
+### Value formatting
+
+`valueFormatter(value, { location, seriesId, dataIndex })` is picked from the series, then the axis, then a number format for `locale`. `location` is `'tick'` for value-axis ticks, `'tooltip'` for tooltip rows, `'label'` for a marker's `showValue`, and `'a11y'` for screen reader text and the generated summary.
+
+### Coming from MUI X
+
+Names follow [MUI X Line Charts](https://mui.com/x/react-charts/lines/). MUI X is not a dependency and none of its types appear in the API.
+
+| MUI X                                                    | Forge UI                                                      | Notes                                                                                                                                                                                                  |
+| -------------------------------------------------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `dataset`                                                | `dataset`                                                     | Rows are your own type; no reserved keys.                                                                                                                                                              |
+| `series[].dataKey`, `id`, `label`, `valueFormatter`      | same                                                          | `valueFormatter` also gets `location: 'a11y'` for screen reader text.                                                                                                                                  |
+| `series[].color`                                         | `series[].color`                                              | A chart token name, not a CSS color, so it follows the theme.                                                                                                                                          |
+| `colors`                                                 | `palette` + `series[].color`                                  | MUI takes a list of CSS colors. Forge picks from theme tokens instead, so FI brands re-skin every chart: `palette` chooses the brand (`auto`) or categorical ramp, and a series `color` names a token. |
+| `series[].curve`                                         | `series[].curve`                                              | `'linear'`, `'monotoneX'` (default), and `'stepAfter'`. Other MUI curves are not supported.                                                                                                            |
+| `series[].area`                                          | `series[].area`                                               | Default `false`, as in MUI. `baseline` is not supported; the fill closes at zero or the domain edge nearest it.                                                                                        |
+| `series[].showMark`                                      | `series[].showMark`                                           | Boolean or `({ index }) => boolean`. Defaults to `false` (MUI shows marks by default). `shape` is not supported.                                                                                       |
+| `sx` with `strokeDasharray`                              | `series[].dashed`, `series[].dashedFrom`                      | Kept as props because MUI dashes lines through CSS selectors, which React Native does not have. `dashedFrom` is a `dataIndex` and has no MUI equivalent.                                               |
+| `series[].connectNulls`, `stack`                         | —                                                             | Not supported. A missing value opens a gap.                                                                                                                                                            |
+| `xAxis[0].dataKey`, `scaleType`                          | same                                                          | Only the first axis is read. Categories render as a point scale whatever `scaleType` says.                                                                                                             |
+| `xAxis[0].tickLabelInterval`                             | same                                                          | Function form `(value, index) => boolean`.                                                                                                                                                             |
+| `xAxis[0].position: 'none'`, `yAxis[0].position: 'none'` | same                                                          | Hides that axis's labels and reclaims the gutter.                                                                                                                                                      |
+| `yAxis[0].min`, `max`, `tickNumber`, `valueFormatter`    | same                                                          | `min` / `max` pin the domain exactly; open ends round to a readable tick.                                                                                                                              |
+| `grid={{ horizontal }}`                                  | `grid={{ horizontal }}`                                       | Horizontal lines are on by default (MUI draws no grid by default); pass `horizontal: false` to remove them. `vertical` is not drawn.                                                                   |
+| `hideLegend`                                             | `hideLegend`                                                  | Same default: the legend shows unless hidden.                                                                                                                                                          |
+| `slotProps.tooltip.trigger`                              | `tooltip.trigger`                                             | `'axis'` (default) or `'none'`. `'item'` behaves like `'axis'` for now. Custom tooltip content is not supported yet.                                                                                   |
+| `highlightedItem`, `onAxisClick`, `onMarkClick`          | `selectedItem`, `defaultSelectedItem`, `onSelectedItemChange` | Selection is a category that stays selected until pressed again, and works by keyboard and screen reader.                                                                                              |
+| `<ChartsReferenceLine y label />`                        | `referenceLines`                                              | Kept as a prop because Forge charts have no composition API.                                                                                                                                           |
+| —                                                        | `markers`                                                     | Point callouts (caption, value, legend row) with no MUI equivalent.                                                                                                                                    |
+| Pro `zoom`                                               | `scrollable`, `visiblePoints`                                 | Long series scroll instead of zooming.                                                                                                                                                                 |
+| `skipAnimation`                                          | `animation="disable-all"`                                     | Matches the Forge animation convention. Reduce Motion also turns it off.                                                                                                                               |
+| `width`, `height`                                        | `size`, `width`, `height`                                     | Named sizes, with `width` / `height` overriding one side.                                                                                                                                              |
+| `localeText`                                             | `localeText`                                                  | Same name; the keys are Forge's (`lineChartSummary`, `noValue`, `defaultSeriesLabel`).                                                                                                                 |
+| —                                                        | `locale`                                                      | Kept because default number formatting needs a locale and Forge has no localization provider for charts.                                                                                               |
+
+## Anatomy
+
+| `data-slot`              | Element                                                  |
+| ------------------------ | -------------------------------------------------------- |
+| `line-chart`             | Root                                                     |
+| `line-chart-plot`        | Value axis and scrollable plot                           |
+| `line-chart-inspector`   | Interactive overlay, present with a tooltip or selection |
+| `line-chart-point`       | Category hit target                                      |
+| `line-chart-focus`       | Keyboard focus ring                                      |
+| `line-chart-tooltip`     | Tooltip                                                  |
+| `line-chart-legend`      | Legend                                                   |
+| `line-chart-legend-item` | Legend row                                               |
+
+## Accessibility
+
+With a tooltip or selection, the plot is covered by a group named by the summary: `accessibilityLabel`, or `localeText.lineChartSummary` of the last category. Each category in it is one button, announced as its label, every series value formatted with `location: 'a11y'`, and any marker legend or caption; a category with no values reads `localeText.noValue`. With no tooltip, no selection, and `hideLegend`, the whole chart is instead a single image named by the summary. With a legend but no tooltip or selection, only the legend text is read. The drawn plot, axis labels, and tooltip are always hidden from assistive technology.
+
+On web, the chart is one tab stop. Tab / Shift+Tab and the arrow keys move between categories, Home / End jump to the ends, and Tab past the last category or Shift+Tab before the first leaves the chart. Escape hides the tooltip. On a selectable chart, Enter or Space selects the focused category and each category reports `aria-pressed`.
+
+On native, a selectable category reports `accessibilityState.selected`, and the VoiceOver escape gesture hides the tooltip. Dragging a finger scrubs the tooltip across categories; when the plot scrolls, scrubbing starts after a short hold so a flick still scrolls.