@acronis-platform/ui-react 3.0.0 → 4.1.0

package/dist/llms/bar-chart.md

@@ -0,0 +1,406 @@
+# BarChart
+
+> A typed bar-chart composition over the shared `Chart` primitives. Takes `data` + `config` + a set of series `dataKeys` and renders a themed recharts `BarChart` inside a `ChartContainer`, with tooltip and legend chrome. Two variant axes: `orientation` (vertical / horizontal bars) and `layout` (grouped / stacked). Ported from the apps/demo `BarChartPlayground`.
+
+**Status:** draft · **Category:** data-display · **Since:** v0.57.0
+
+## Import
+
+```tsx
+import { BarChart } from '@acronis-platform/ui-react'
+```
+
+## Quick example
+
+```tsx
+<BarChart
+  config={config}
+  data={data}
+  dataKeys={['desktop', 'mobile']}
+  xKey="month"
+  orientation="vertical"
+  layout="grouped"
+  className="h-[320px] w-[560px]"
+/>
+```
+
+A typed bar-chart built on the shared `Chart` primitives. Give it `data`, a
+per-series `config`, the series to plot (`dataKeys`), and the category key
+(`xKey`); it renders a themed recharts `BarChart` — tooltip, legend, axes, and
+grid included — so you don't hand-compose recharts children.
+
+Series colors come from the `palette` prop — a dataviz palette resolving to the
+`--ui-dataviz-*` tokens, `categorical` by default — not from `config`.
+
+> **Design-pending v1.** Ported from the apps/demo `BarChartPlayground`. The
+> chrome is reconciled with Figma later; Code Connect is deferred.
+
+## When to use
+
+- Comparing a quantity across categories (sales by month, usage by device).
+- Comparing a few series per category — grouped (side-by-side) or stacked.
+
+## When not to use
+
+- A single metric or KPI — use a `Tag`, `Badge`, or plain text.
+- Trends over a continuous dimension — prefer a line/area chart.
+- Part-to-whole of a single total — consider a pie/donut chart.
+- Tabular detail — use `Table` / `DataTable`.
+
+## Variants
+
+| Axis          | Values                    | Effect                                                 |
+| ------------- | ------------------------- | ------------------------------------------------------ |
+| `orientation` | `vertical` · `horizontal` | Bars grow up (category on x) vs right (category on y). |
+| `layout`      | `grouped` · `stacked`     | Series side-by-side vs summed on a shared stack.       |
+
+## Highlighting a range
+
+A projection, a quarter under review, or any other stretch of the category axis
+can be set apart without leaving the component:
+
+- `referenceArea` shades the range, captions it, accents the ticks it covers,
+  and optionally rules its leading edge (`divider`).
+- `barSettings` restyles one series over a range — `fill`, `opacity`, `dashed`,
+  `shape`, and a track via `background` (`true` for the full plot height, or a
+  data field name to cap it at that row's value, i.e. the headroom up to an
+  upper bound).
+
+Both address a range as `{ from, to }`, inclusive, taking either a category's
+own value or its row index; an omitted bound runs to that end of the data. A
+capped track stacks on its bar, so it needs the default `layout="grouped"`, and
+it never becomes a tooltip row or a legend entry.
+
+## Example
+
+```tsx
+import { BarChart } from '@acronis-platform/ui-react';
+import type { ChartConfig } from '@acronis-platform/ui-react';
+
+const data = [
+  { month: 'Jan', desktop: 186, mobile: 80 },
+  { month: 'Feb', desktop: 305, mobile: 200 },
+  { month: 'Mar', desktop: 237, mobile: 120 },
+];
+
+const config = {
+  desktop: { label: 'Desktop', color: 'var(--ui-background-brand-secondary)' },
+  mobile: {
+    label: 'Mobile',
+    color: 'var(--ui-background-status-strong-danger)',
+  },
+} satisfies ChartConfig;
+
+<BarChart
+  config={config}
+  data={data}
+  dataKeys={['desktop', 'mobile']}
+  xKey="month"
+  className="h-[320px] w-[560px]"
+/>;
+```
+
+Series colors reference existing semantic `--ui-*` tokens. `--ui-background-status-strong-*`
+is chromatic in every brand; `--ui-background-brand-secondary` is brand-dependent
+(blue in `default`, neutral in some white-label brands), so it is not color-stable
+across brands until the real data-viz palette lands.
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `orientation` | `'vertical' | 'horizontal'` | `'vertical'` | no | Direction the bars grow. `vertical` = bars rise (category on the x-axis); `horizontal` = bars extend rightward (category on the y-axis). |
+| `layout` | `'grouped' | 'stacked'` | `'grouped'` | no | How multiple series are arranged. `grouped` = side-by-side bars; `stacked` = segments summed on a shared `stackId`. |
+| `data` | `ReadonlyArray<Record<string, string | number>>` | — | yes | Row-per-category data — each row holds `xKey` plus one numeric field per series. |
+| `config` | `ChartConfig` | — | yes | Series take their colour from the container's `palette`; each entry maps a data key to a `label` and an optional `tone`. Resolved into the `--color-<key>` custom properties the bars fill from. |
+| `dataKeys` | `string[]` | — | yes | Series to plot — one bar per key. Each must exist in `config` and every data row. |
+| `xKey` | `string` | — | yes | The category dimension key shared across rows. |
+| `referenceLine` | `Line | Line[]  where Line = { value?: number; average?: boolean | string; label?: string }` | — | no | One or more dashed reference/average lines on the value axis (Y for vertical bars, X for horizontal). Pass a single object or an array. Per line, a fixed `value` wins; otherwise the mean of one series (`average: '<key>'`) or of every plotted series (`average: true`). An optional `label` captions each. |
+| `xAxisLabel` | `string` | — | no | Title rendered beneath the horizontal (X) axis. |
+| `yAxisLabel` | `string` | — | no | Title rendered beside the vertical (Y) axis (rotated). |
+| `xUnit` | `string` | — | no | Unit suffix appended to X-axis tick values (recharts `unit`); applies when the X axis is numeric (horizontal orientation). |
+| `yUnit` | `string` | — | no | Unit suffix appended to Y-axis tick values (recharts `unit`); applies when the Y axis is numeric (vertical orientation). |
+| `referenceArea` | `Area | Area[]  where Area = { from?: string | number; to?: string | number; label?: string; highlightTicks?: boolean; divider?: boolean }` | — | no | One or more shaded bands behind a range of categories — e.g. a forecast period. `from`/`to` are inclusive and take either the category's value or its 0-based row index; an omitted bound runs to that end of the data. The category ticks under a band pick up the accent styling unless `highlightTicks` is false, and `divider` adds a dashed rule on the band's leading edge for a forecast hand-off. |
+| `barSettings` | `Record<string, { from?: string | number; to?: string | number; fill?: string; opacity?: number; dashed?: boolean; shape?: BarShape; background?: boolean | string }>` | — | no | Per-series style override for a range of categories, keyed by `dataKeys` entry — e.g. a projection tail that reads translucent and dashed over its own track. `background` takes `true` for a full-height track or a data field name to cap it at that row's value (the headroom up to an upper bound, which stacks on the bar and so needs `layout="grouped"`). Bars outside the range, and series with no entry, render normally. |
+| `barRadius` | `number` | `4` | no | Corner radius on the growing end of each bar (0 for square corners). |
+| `barShape` | `'rounded' | 'pill' | 'gradient' | 'pattern'` | `'rounded'` | no | How every bar is painted: the growing end rounded by `barRadius`, a capsule, a fade of the series color, or diagonal hatching in it. Per-range overrides come from `barSettings`. |
+| `barSize` | `number` | — | no | Fixed bar thickness in px; unset, recharts sizes bars from the available width. |
+| `maxBarSize` | `number` | — | no | Upper bound on the computed bar thickness, in px. |
+| `barGap` | `number | string` | — | no | Gap between the bars of one category, in px or a percentage string. |
+| `barCategoryGap` | `number | string` | — | no | Gap between category groups, in px or a percentage string. |
+| `minPointSize` | `number` | — | no | Minimum rendered length for a non-zero bar, in px, so tiny values stay visible. |
+| `showBackground` | `boolean` | `false` | no | Draw a full-height track behind every bar. |
+| `backgroundFill` | `string` | `'var(--ui-background-surface-secondary)'` | no | Fill for the track background. |
+| `showActiveBar` | `boolean` | `false` | no | Highlight the hovered bar. |
+| `activeBar` | `{ fill?: string; opacity?: number }` | — | no | Painting of the hovered bar when `showActiveBar` is on; defaults to the series color. |
+| `showGrid` | `boolean` | `true` | no | Render the CartesianGrid. |
+| `showTooltip` | `boolean` | `true` | no | Render the hover tooltip. |
+| `showLegend` | `boolean` | `true` | no | Render the legend. |
+| `tooltipContent` | `ReactElement | ((props) => ReactNode)` | — | no | Replace the default tooltip. Pass a configured ChartTooltipContent (from this library) — e.g. with a formatter / labelFormatter — to customize the tooltip content without composing recharts. Ignored when showTooltip is false. |
+| `showXAxis` | `boolean` | `true` | no | Render the X axis (its ticks and title). Set false to hide it. |
+| `showYAxis` | `boolean` | `true` | no | Render the Y axis (its ticks and title). Set false to hide it. |
+| `xTickFormatter` | `(value: number | string, index?: number) => string` | — | no | Format each X-axis tick value. Unlike the `unit` suffix (append-only), a formatter transforms the value — abbreviate, prefix a symbol, or map to a label. Use formatCompactNumber / formatPercent / createTickFormatter from the shared Chart primitives, or any function. |
+| `yTickFormatter` | `(value: number | string, index?: number) => string` | — | no | Format each Y-axis tick value (see xTickFormatter). |
+| `xAxisAngle` | `number` | — | no | Rotate the X-axis tick labels by this many degrees (a negative angle tilts them up toward the right); the tick anchor + axis height adjust. |
+| `xAxisInterval` | `number | 'preserveStart' | 'preserveEnd' | 'preserveStartEnd' | 'equidistantPreserveStart'` | — | no | X-axis tick density — a recharts placement strategy, or a fixed number of ticks to skip between two rendered ones (recharts interval: 0 shows every tick, 1 every other one, 2 every third). |
+| `yAxisTickCount` | `number` | — | no | Desired number of ticks on the value axis (recharts tickCount; a hint, not exact). Applies to whichever axis holds the values — Y for most charts, X for BarChart with orientation="horizontal". |
+| `yAxisDomain` | `'auto' | 'dataMin-dataMax' | 'zero'` | — | no | Value-axis domain preset — auto (fit the data at both ends; the axis need not include 0), zero (anchor the axis at 0, which is also recharts' behaviour when the prop is omitted), or dataMin-dataMax (tight to the data, no padding). Applies to whichever axis holds the values — Y for most charts, X for BarChart with orientation="horizontal". |
+| `gridDashed` | `boolean` | — | no | Draw grid lines dashed instead of solid. |
+| `gridHorizontal` | `boolean` | — | no | Show horizontal grid lines (defaults to the chart's own default when unset). |
+| `gridVertical` | `boolean` | — | no | Show vertical grid lines (defaults to the chart's own default when unset). |
+| `animate` | `boolean` | `false` | no | Enable entrance animation. Off by default so output/baselines are unchanged. |
+| `animationDuration` | `number` | — | no | Animation duration in ms. |
+| `animationBegin` | `number` | — | no | Delay before the animation starts, in ms. |
+| `animationEasing` | `'ease' | 'ease-in' | 'ease-out' | 'ease-in-out' | 'linear'` | — | no | Easing curve. |
+| `showLabels` | `boolean` | `false` | no | Render a value label on each bar segment. |
+| `labelPosition` | `'top' | 'bottom' | 'left' | 'right' | 'center' | 'insideTop' | 'insideBottom' | 'insideLeft' | 'insideRight' | 'insideStart' | 'insideEnd'` | — | no | Where the value labels sit. Defaults to the bar's growing end — top for vertical bars, right for horizontal — or center when layout is stacked. |
+| `labelFormatter` | `(value) => string` | — | no | Format each label value (reuses the tick formatters). |
+| `showBrush` | `boolean` | `false` | no | Render a range brush beneath the chart — drag a handle (or the selected window) to zoom the series into a slice of the data. |
+| `brushHeight` | `number` | `28` | no | Height of the brush strip in px. A non-positive value falls back to the default rather than erasing the brush. |
+| `brushAriaLabel` | `string` | `'Chart range selector'` | no | Accessible name for the brush's two range handles, which are focusable `role="slider"` elements. Consumers localize by passing their own. |
+
+## Behavior
+
+`BarChart` is a typed [recharts](https://recharts.org) composition over the
+shared `Chart` primitives. It takes `data`, a per-series `config`, the series to
+plot (`dataKeys`), and the category key (`xKey`), and renders a themed recharts
+`BarChart` inside a `ChartContainer`.
+
+```gherkin
+Scenario: Render bars from data and config
+  Given data rows and a config mapping each series key to a label and color
+  And dataKeys ["desktop", "mobile"]
+  Then one <Bar> renders per dataKey
+  And each bar fills from its injected --color-<key> custom property
+```
+
+```gherkin
+Scenario: Vertical orientation (default)
+  Given orientation is "vertical"
+  Then bars grow upward
+  And the category axis (xKey) is the x-axis and the value axis is the y-axis
+  And the grid draws horizontal lines
+```
+
+```gherkin
+Scenario: Horizontal orientation
+  Given orientation is "horizontal"
+  Then bars extend rightward (recharts layout="vertical")
+  And the category axis (xKey) is the y-axis and the value axis is the x-axis
+  And the grid draws vertical lines
+```
+
+```gherkin
+Scenario: Grouped layout (default)
+  Given layout is "grouped" and two or more dataKeys
+  Then the bars in each category render side by side
+  And each bar's growing end is rounded by barRadius
+```
+
+```gherkin
+Scenario: Stacked layout
+  Given layout is "stacked" and two or more dataKeys
+  Then the bars in each category share a stackId and sum into one column/row
+  And only the last segment's growing end is rounded
+```
+
+```gherkin
+Scenario: Tooltip on hover
+  Given showTooltip is true
+  When the user hovers a category
+  Then a card shows the category label and one row per series (indicator + value)
+```
+
+```gherkin
+Scenario: Legend
+  Given showLegend is true
+  Then a swatch + label renders for each series in dataKeys
+  And the entries follow the dataKeys order, not the underlying chart library's
+      default alphabetical sort
+  And the order does not change when bar-styling props (barShape, barSettings) are set
+```
+
+```gherkin
+Scenario: Fixed reference line
+  Given referenceLine is { value: 250, label: "Target" }
+  Then a dashed line draws across the value axis at 250
+  And it is captioned "Target"
+  And for horizontal orientation the line is vertical (on the x-axis), else horizontal (on the y-axis)
+```
+
+```gherkin
+Scenario: Averaged reference line
+  Given referenceLine is { average: true } (or a single series key)
+  Then the line draws at the mean of every plotted series' values (or that one series)
+  And when there are no numeric values to average, no line is drawn
+```
+
+```gherkin
+Scenario: Multiple reference lines
+  Given referenceLine is an array of line configs (e.g. a fixed target and an average)
+  Then one dashed line draws per config
+  And each config is resolved independently (a config with nothing to draw is skipped)
+```
+
+```gherkin
+Scenario: Empty data
+  Given data is an empty array
+  Then the chart renders its axes and grid with no bars and does not throw
+```
+
+```gherkin
+Scenario: Entrance animation is opt-in
+  Given animate is unset
+  Then the series render at their final geometry with no entrance animation
+  And the committed visual baselines are unaffected
+```
+
+```gherkin
+Scenario: Reduced motion
+  Given animate is true
+  And a user with prefers-reduced-motion
+  Then the entrance animation does not play and the series render at their final geometry
+  And the same applies when rendering on the server
+```
+
+```gherkin
+Scenario: Range brush
+  Given showBrush is true
+  Then a brush strip renders beneath the plot with a handle at each end
+  And dragging a handle (or the selected window) zooms the series to that slice
+  And the category axis and tooltip follow the selected range
+  And the brush renders whether or not the category axis is shown
+  And unset renders no brush
+```
+
+```gherkin
+Scenario: Range brush keyboard and accessible name
+  Given showBrush is true
+  Then each of the two handles is reachable by Tab
+  And the focused handle moves one row per left/right arrow key press
+  And each handle exposes brushAriaLabel as its accessible name
+```
+
+```gherkin
+Scenario: Highlight a range of categories
+  Given referenceArea is { from: "Apr" }
+  Then a shaded band spans from the "Apr" category through the last one
+  And the category ticks it covers render in the accent style, italic
+  But the accent is skipped when the entry sets highlightTicks: false
+```
+
+```gherkin
+Scenario: Address a range by index or by value
+  Given a referenceArea or barSettings entry with from and/or to
+  Then a bound matching a category's own value selects that category
+  And an integer bound with no matching category selects that row index
+  And an omitted bound runs to that end of the data
+  And nothing is drawn when a bound resolves to no category, or to lies before from
+```
+
+```gherkin
+Scenario: Mark the hand-off into a forecast
+  Given a referenceArea entry sets divider: true
+  Then a dashed rule draws on the band's leading edge
+  And it follows the category axis — the band's left edge for vertical bars, its top edge for horizontal ones
+```
+
+```gherkin
+Scenario: Restyle one series over a range
+  Given barSettings maps "desktop" to { from: "Apr", opacity: 0.35, dashed: true }
+  Then the "desktop" bars from "Apr" onward render translucent with a dashed outline in the series color
+  And the "desktop" bars before "Apr" render normally
+  And every other series renders normally
+```
+
+```gherkin
+Scenario: Track behind a bar
+  Given showBackground is true
+  Then a full-height track renders behind every bar, filled with backgroundFill
+  And a barSettings entry with background: true limits that track to its own range
+```
+
+```gherkin
+Scenario: Cap a track at an upper bound
+  Given a barSettings entry sets background to a data field name
+  Then the matched bars carry a headroom segment from their value up to that field's value
+  And the headroom stacks on its own bar, so the series stay side by side
+  And it is excluded from the tooltip rows and the legend entries
+  But it is not drawn at all under layout="stacked"
+```
+
+```gherkin
+Scenario: Bar shape
+  Given barShape is "pill"
+  Then every corner of each bar is rounded into a capsule
+  And "gradient" fades the series color along the bar while "pattern" hatches it
+  And a barSettings entry's shape overrides the chart's for its own range
+```
+
+```gherkin
+Scenario: Bar sizing
+  Given barSize, maxBarSize, barGap, barCategoryGap or minPointSize is set
+  Then the bar thickness, the gaps around it, and the floor for a non-zero value follow those values
+  And a value of exactly 0 still renders nothing, including a zero segment inside a stack
+```
+
+```gherkin
+Scenario: Active bar on hover
+  Given showActiveBar is true
+  When the user hovers a bar
+  Then that bar repaints with the activeBar fill and opacity, defaulting to the series color
+  And a bar that carries a barSettings track keeps that track while it is hovered
+```
+
+## Accessibility
+
+- recharts' `accessibilityLayer` is **on by default** (recharts v3), giving the
+  chart keyboard focus and an accessible description of the plotted points.
+- The **range brush** (`showBrush`) is the only interactive control these charts
+  render. It adds two focusable `role="slider"` handles: Tab reaches each one and
+  the left/right arrow keys move the selection a row at a time, so the whole
+  feature is operable without a pointer.
+  - Both handles take their accessible name from `brushAriaLabel` (default
+    `'Chart range selector'`); pass your own to localize it. Never leave it to
+    recharts' fallback, which names the handles from a `name` field on the data
+    row and otherwise announces "Min value: undefined, Max value: undefined".
+  - The handles keep a visible focus indicator: the shared `ChartContainer`
+    suppresses outlines on recharts layers, so it re-enables one for
+    `.recharts-brush-traveller` specifically (an `outline`, since `box-shadow`
+    does not paint on SVG children).
+  - The two range captions only appear while a handle is hovered, dragged, or
+    focused — they are a supplement to the category axis, not a replacement for
+    it. Zooming changes which rows are plotted, so **pair the brush with a text
+    alternative that reflects the current range** rather than the full series.
+- A bar chart is inherently visual. **Pair it with a text alternative** — a
+  caption, a summary sentence, or an adjacent data table carrying the same
+  numbers — and give the chart an accessible name (`aria-label` /
+  `aria-labelledby` referencing a visible heading) when it is meaningful on its
+  own. The wrapper forwards native `div` attributes, so `aria-*` pass through.
+- Do **not** rely on color alone to distinguish series. Keep `showLegend` (or the
+  tooltip) visible so each color is paired with a text label.
+- The chrome (tooltip, legend, axis ticks, grid) resolves to semantic `--ui-*`
+  tokens that meet contrast in light and dark. **Series colors are
+  caller-supplied** via `config` — pick values that meet 3:1 against the surface
+  and are distinguishable for color-vision deficiencies. The borrowed semantic
+  tokens are a design-pending stopgap until the `--ui-chart-*` palette lands.
+- A **highlighted range** (`referenceArea`) is carried by more than one channel:
+  the band's shading, the italic accent on the ticks it covers, and the optional
+  `divider` rule. Caption it (`label`) when the reason for the highlight is not
+  obvious from the surrounding copy, since none of those channels is announced.
+- A **`barSettings` range** likewise should not lean on `opacity` alone —
+  `dashed`, or `shape: 'pattern'`, distinguishes those bars by texture rather
+  than by color or lightness, which survives both color-vision deficiency and a
+  low-quality display. Restate the distinction in text (a caption, the tooltip)
+  because it is purely visual.
+- A **capped track** (`background: '<field>'`) is decoration: it is deliberately
+  excluded from the tooltip rows and the legend, so the bound it depicts is not
+  otherwise available. Surface that number in the tooltip or a table if it
+  matters to the reader.
+- Watch recharts issue [#4809](https://github.com/recharts/recharts/issues/4809)
+  on the a11y layer for heavily-customized charts.
+
+## Contrast
+
+Chart chrome meets contrast in both themes via the semantic tokens. Bar fills
+come from `config` and are the caller's responsibility.