@acronis-platform/ui-react 2.0.0 → 4.0.0

package/dist/llms/funnel-chart.md

@@ -0,0 +1,333 @@
+# FunnelChart
+
+> A typed funnel-chart composition over the shared `Chart` primitives. Plots a single series of stages (rows) as stacked, narrowing segments inside a `ChartContainer`, with a tooltip and on-chart stage labels (no legend — the inline labels name every stage). One variant axis: `lastShape` (the funnel narrows to a `triangle` point or ends `rectangle` flat). Ported from the apps/demo `FunnelChartPlayground`.
+
+**Status:** draft · **Category:** data-display · **Since:** v0.58.0
+
+## Import
+
+```tsx
+import { FunnelChart } from '@acronis-platform/ui-react'
+```
+
+## Quick example
+
+```tsx
+<FunnelChart
+  config={config}
+  data={data}
+  dataKey="value"
+  nameKey="stage"
+  lastShape="triangle"
+  className="h-[380px] w-[460px]"
+/>
+```
+
+A typed funnel-chart built on the shared `Chart` primitives. Give it `data`, a
+per-stage `config`, the value field (`dataKey`), and the label field (`nameKey`);
+it renders a themed recharts `FunnelChart` — on-chart stage labels and a tooltip
+included — so you don't hand-compose recharts children. (There's no legend: the
+inline labels already name every stage.)
+
+Stage colors come from the `palette` prop — a dataviz palette resolving to the
+`--ui-dataviz-*` tokens — not from `config`. Stages are an ordered progression,
+so `{ type: 'sequential', ramp }` usually reads better than the default
+`categorical`.
+
+> **Design-pending v1.** Ported from the apps/demo `FunnelChartPlayground`. The
+> chrome is reconciled with Figma later; Code Connect is deferred.
+
+## When to use
+
+- Showing progression (and drop-off) through the ordered stages of a process —
+  a conversion funnel, a recruitment pipeline, an onboarding flow.
+- A handful of monotonically decreasing stages read best.
+
+## When not to use
+
+- Unordered categories or part-to-whole of a single total — use a pie/donut or
+  bar chart.
+- A trend over time — use a line or area chart.
+- Values that don't decrease stage to stage — the funnel metaphor misleads.
+
+## Variants
+
+| Axis        | Values                   | Effect                                         |
+| ----------- | ------------------------ | ---------------------------------------------- |
+| `lastShape` | `triangle` · `rectangle` | Final segment narrows to a point vs ends flat. |
+
+## Example
+
+```tsx
+import { FunnelChart } from '@acronis-platform/ui-react';
+import type { ChartConfig } from '@acronis-platform/ui-react';
+
+const data = [
+  { stage: 'Visits', value: 5000 },
+  { stage: 'Signups', value: 2600 },
+  { stage: 'Trials', value: 1400 },
+  { stage: 'Purchases', value: 620 },
+];
+
+const config = {
+  Visits: { label: 'Visits', color: 'var(--ui-background-brand-secondary)' },
+  Signups: {
+    label: 'Signups',
+    color: 'var(--ui-background-status-strong-success)',
+  },
+  Trials: {
+    label: 'Trials',
+    color: 'var(--ui-background-status-strong-warning)',
+  },
+  Purchases: {
+    label: 'Purchases',
+    color: 'var(--ui-background-status-strong-danger)',
+  },
+} satisfies ChartConfig;
+
+<FunnelChart
+  config={config}
+  data={data}
+  dataKey="value"
+  nameKey="stage"
+  className="h-[380px] w-[460px]"
+/>;
+```
+
+Stage colors reference existing semantic `--ui-*` tokens, keyed by each stage's
+`nameKey` value. `--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 |
+|------|------|---------|----------|-------------|
+| `lastShape` | `'triangle' | 'rectangle'` | `'triangle'` | no | How the funnel ends. `triangle` narrows the final segment to a point; `rectangle` ends it flat (a stack of trapezoids). |
+| `data` | `ReadonlyArray<Record<string, string | number>>` | — | yes | Row-per-stage data — each row holds a `nameKey` label and a `dataKey` numeric value. |
+| `config` | `ChartConfig` | — | yes | Stages take their colour from the container's `palette`; each entry, keyed by the stage's `nameKey` value, maps that stage to a `label` and an optional `tone`. Resolved into the `--color-<name>` custom properties the segments fill from. |
+| `dataKey` | `string` | — | yes | The numeric field that sizes each stage. |
+| `nameKey` | `string` | — | yes | The label field that names each stage (drives the tooltip, on-chart labels, and the `--color-<name>` lookup). Values should be unique per chart — stages sharing a name share one config/color entry. |
+| `reversed` | `boolean` | `false` | no | Flip the funnel so it widens toward the bottom instead of narrowing. |
+| `showLabels` | `boolean` | `true` | no | Render a label for each stage — see labelFormat and labelPosition. |
+| `labelFormat` | `'name' | 'value' | 'percent' | 'name-value' | 'name-percent' | 'value-percent'` | `'name'` | no | What each stage's label says. A percentage is the stage's share of the widest stage — its conversion from the top of the funnel, not a share of the sum, because a funnel's stages are nested subsets rather than parts of a whole. The value is formatted by labelFormatter and the share by percentFormatter. A composite format (a pair) narrows the funnel to leave itself room, unless funnelWidth says otherwise. |
+| `labelPosition` | `'right' | 'left' | 'inside'` | `'right'` | no | Where each stage's label sits. `right`/`left` place it beside the segment on the chart surface; `inside` centres it on the segment, which switches the label to the on-fill color so it keeps contrast over a saturated fill. `inside` only works while every stage is wide enough to hold the text — a funnel narrows, so its last stages often are not; keep the text short there (`percent`) or leave the labels beside the funnel. |
+| `showValueLabels` | `boolean` | `false` | no | Render a second label carrying the stage's value, so the name and the number can sit on opposite sides of the funnel. |
+| `valuePosition` | `'right' | 'left' | 'inside'` | `the side opposite labelPosition` | no | Where the value label sits. Defaults to the side opposite labelPosition, where every stage has room — so it follows the names rather than pinning itself to one edge, which would overprint them when the names move. See labelPosition before choosing inside. |
+| `labelFill` | `string` | — | no | Color for both label lists, overriding the contrast-matched default. Pass a --ui-* token; only needed when the default doesn't work on the surface. |
+| `labelFormatter` | `(value: number | string, index?: number) => string` | — | no | Format the numeric part of a label. |
+| `percentFormatter` | `(value: number | string, index?: number) => string` | — | no | Format the conversion share behind the percent formats. Receives the share as a fraction (0.52); defaults to a one-decimal bare percentage ("52.0%"). Replace it for a locale that doesn't write a bare percent sign. |
+| `showLegend` | `boolean` | `false` | no | Render the legend — one entry per visible stage. Off by default because a funnel labels its stages on the chart. |
+| `legendPos` | `'top' | 'bottom'` | `'bottom'` | no | Which edge the legend sits on. |
+| `colorMode` | `'palette' | 'gradient'` | `'palette'` | no | How the stages are colored. `palette` gives each stage its own config color; `gradient` ramps one hue from the widest stage down to the narrowest, mixing it toward the surface so every segment stays opaque. |
+| `gradientColor` | `string` | — | no | The hue gradient mode ramps. Defaults to the first visible stage's own color — including a stageSettings color set on it, since that is what the stage actually paints with. Ignored when colorMode is palette. |
+| `stageSettings` | `Record<string, { color?: string; hidden?: boolean }>` | — | no | Per-stage overrides keyed by the stage's nameKey value. `color` wins over both config and colorMode; `hidden` drops the stage from the funnel, its labels, the legend, and the conversion percentages. |
+| `showActiveShape` | `boolean` | `false` | no | Outline the hovered segment, rather than changing its fill, so it keeps the color that ties it to its legend entry and label. |
+| `stroke` | `string` | — | no | Segment border color — reference an existing --ui-* token. Defaults to the border token when strokeWidth is set on its own, because the renderer's own default is a hardcoded white the container neutralizes. |
+| `strokeWidth` | `number` | — | no | Segment border width, in px. Implies a default stroke when given alone. |
+| `funnelWidth` | `number | string` | — | no | Funnel width — px, or a percentage of the plot area ('70%'). Defaults to the full plot area, except that a composite labelFormat beside the funnel narrows it: the renderer word-wraps a label against the gap between its segment and the plot-area edge, so narrowing the funnel is what creates label room. A margin cannot — it moves that edge inward with the funnel. |
+| `margin` | `{ top?: number; right?: number; bottom?: number; left?: number }` | — | no | Plot-area margin, in px, merged over the defaults per side so passing one side keeps the others. It reserves the side a label list sits on so unwrappable text isn't clipped at the SVG edge — see funnelWidth for the label's wrap room. |
+| `showTooltip` | `boolean` | `true` | no | Render the hover tooltip. |
+| `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. |
+| `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. |
+
+## Behavior
+
+`FunnelChart` is a typed [recharts](https://recharts.org) composition over the
+shared `Chart` primitives. It plots a single series of stages (`data` rows) as
+stacked, narrowing segments inside a `ChartContainer`.
+
+```gherkin
+Scenario: Render stages from data and config
+  Given data rows and a config mapping each stage name to a label and color
+  And dataKey "value" and nameKey "stage"
+  Then one segment renders per row, sized by its dataKey value
+  And each segment fills from its injected --color-<name> custom property
+```
+
+```gherkin
+Scenario: Triangle last shape (default)
+  Given lastShape is "triangle"
+  Then the final segment narrows to a point
+```
+
+```gherkin
+Scenario: Rectangle last shape
+  Given lastShape is "rectangle"
+  Then the final segment ends flat (a stack of trapezoids)
+```
+
+```gherkin
+Scenario: Reversed
+  Given reversed is true
+  Then the funnel widens toward the bottom instead of narrowing
+```
+
+```gherkin
+Scenario: Stage labels
+  Given showLabels is true
+  Then each stage's name renders beside its segment
+```
+
+```gherkin
+Scenario: Label format
+  Given showLabels is true
+  And labelFormat is "name-percent"
+  Then each label pairs the stage's name with its conversion from the widest stage
+  And the widest stage reads 100.0%, whatever order the stages arrive in
+  And the share is formatted by percentFormatter, so a locale that doesn't write a
+    bare percent sign can replace it
+```
+
+```gherkin
+Scenario: Label position drives the label color
+  Given labelPosition is "inside"
+  Then each label is centred on its segment
+  And it uses the on-fill color, which holds its contrast over a saturated fill
+```
+
+```gherkin
+Scenario: An on-segment label needs a segment wide enough to hold it
+  Given labelPosition is "inside"
+  And a stage too narrow for its label text
+  Then the text runs past that segment onto the surface, where the on-fill color
+    has nothing to sit on
+  And the readable options are a short labelFormat or a position beside the funnel
+```
+
+```gherkin
+Scenario: Separate value labels
+  Given showValueLabels is true
+  Then each stage carries its name on one side of the funnel and its value on the
+    other — the values default to the side opposite the names
+  And both read against the surface, so the narrow tail stages stay legible
+```
+
+```gherkin
+Scenario: The value labels follow the names to the other side
+  Given showValueLabels is true
+  And labelPosition is "left"
+  And no valuePosition is given
+  Then the values render to the right of the funnel, not on top of the names
+```
+
+```gherkin
+Scenario: A composite label gets room by narrowing the funnel
+  Given showLabels is true
+  And labelFormat is a pair, sitting to the right of the funnel
+  And no funnelWidth is given
+  Then the funnel is narrowed within the plot area so the label has room to wrap
+    into, because a label wraps against the gap between its segment and the plot
+    area's edge — an inset moves that edge inward with the funnel and so gives it
+    less room, not more
+  And a caller-supplied funnelWidth replaces the reserve
+```
+
+```gherkin
+Scenario: A partial margin keeps the other sides
+  Given a margin that sets only one side
+  Then the remaining sides keep their default insets rather than collapsing to zero
+```
+
+```gherkin
+Scenario: Legend is opt-in
+  Given showLegend is unset
+  Then no legend renders
+```
+
+```gherkin
+Scenario: Legend entries come from the visible stages
+  Given showLegend is true
+  Then one entry renders per distinct visible stage name, labelled and colored
+    from config
+  And two stages sharing a name share the single entry they share a color with
+  And it sits on the edge given by legendPos (bottom by default)
+```
+
+```gherkin
+Scenario: Gradient color mode
+  Given colorMode is "gradient"
+  Then every stage fills from one hue — gradientColor, or the first visible stage's
+    own color, including a stageSettings color set on it
+  And the hue is mixed further toward the surface at each stage down the funnel
+```
+
+```gherkin
+Scenario: Per-stage color override
+  Given a stageSettings entry keyed by a stage's nameKey value carries a color
+  Then that stage fills with it, whatever config and colorMode say
+```
+
+```gherkin
+Scenario: Hidden stage
+  Given a stageSettings entry hides its stage
+  Then the stage has no segment, no label and no legend entry
+  And the remaining conversions are measured over the visible stages only
+```
+
+```gherkin
+Scenario: Active segment
+  Given showActiveShape is true
+  When the user hovers a stage
+  Then that segment is outlined and keeps its fill
+```
+
+```gherkin
+Scenario: Tooltip on hover
+  Given showTooltip is true
+  When the user hovers a stage
+  Then a card shows that stage's name and value
+```
+
+```gherkin
+Scenario: Empty data
+  Given data is an empty array
+  Then the chart renders with no segments 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
+```
+
+## Accessibility
+
+- recharts' `accessibilityLayer` is **on by default** (recharts v3), giving the
+  chart keyboard focus and an accessible description of the plotted stages.
+- A funnel chart is inherently visual. **Pair it with a text alternative** — a
+  caption, a summary sentence, or an adjacent data table carrying the same
+  numbers (including the drop-off between stages, which the funnel only implies) —
+  and give the chart an accessible name (`aria-label` / `aria-labelledby`
+  referencing a visible heading). The wrapper forwards native `div` attributes,
+  so `aria-*` pass through.
+- Do **not** rely on color alone to distinguish stages. Keep `showLabels` (or the
+  tooltip) visible so each color is paired with a text label — the on-chart labels
+  are the funnel's naming channel (there is no legend).
+- The tooltip chrome resolves to semantic `--ui-*` tokens, and on-chart labels use
+  the foreground text token — both meet contrast in light and dark.
+  **Stage 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.
+- Watch recharts issue [#4809](https://github.com/recharts/recharts/issues/4809)
+  on the a11y layer for heavily-customized charts.
+
+## Contrast
+
+Chart chrome and the on-chart stage labels meet contrast in both themes via the
+semantic tokens. Segment fills come from `config` and are the caller's
+responsibility — keep adjacent segments distinguishable from each other.

package/dist/llms/grid.md

@@ -0,0 +1,80 @@
+# Grid
+
+> A responsive CSS-grid layout primitive — lay children into a column count that steps down at smaller breakpoints, with a configurable gap. Ported 1:1 from the legacy shadcn-uikit `grid`.
+
+**Status:** draft · **Category:** layout · **Since:** v0.51.0
+
+## Import
+
+```tsx
+import { Grid } from '@acronis-platform/ui-react'
+```
+
+## Quick example
+
+```tsx
+<Grid cols={4} gap="lg">{cells}</Grid>
+```
+
+A responsive CSS-grid layout primitive — lay children into a column count that
+steps down at smaller breakpoints, with a configurable gap.
+
+> Design-pending v1, ported 1:1 from the legacy shadcn-uikit `grid`.
+
+## When to use
+
+- Card galleries, dashboards, and other two-dimensional layouts.
+
+## When not to use
+
+- One-dimensional rows/columns — use `Stack`.
+- Tabular data — use `Table` / `DataTable`.
+
+## Parts
+
+`Grid` is a single component.
+
+## Example
+
+```tsx
+import { Grid } from '@acronis-platform/ui-react';
+
+<Grid cols={3} gap="md">
+  {items.map((i) => (
+    <Card key={i.id} {...i} />
+  ))}
+</Grid>;
+```
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `cols` | `1 | 2 | 3 | 4 | 6 | 12` | `3` | no | Target column count at the largest breakpoint (steps down responsively). |
+| `gap` | `'none' | 'sm' | 'md' | 'lg' | 'xl'` | `'md'` | no | Space between grid cells. |
+| `container` | `boolean` | `false` | no | Size columns by the grid's own width (container queries) instead of the viewport — wraps the grid in a `@container/grid`. Use for grids inside a variable-width area (e.g. App Shell main). |
+
+## Behavior
+
+```gherkin
+Scenario: Responsive columns
+  Given a Grid with cols={4}
+  Then cells lay out in up to 4 columns at large widths, stepping down to fewer
+  columns at smaller breakpoints
+```
+
+```gherkin
+Scenario: Gap
+  Given a gap value
+  Then a consistent gap is applied between rows and columns
+```
+
+## Accessibility
+
+Grid is a presentational layout `<div>` with no semantics of its own; children
+follow source order. It uses CSS grid only for visual layout — don't rely on it to
+convey relationships that need real table/list semantics.
+
+## Contrast
+
+No color; nothing to evaluate.

package/dist/llms/histogram.md

@@ -0,0 +1,190 @@
+# Histogram
+
+> A frequency histogram — bins a set of continuous samples (`values`) into equal-width ranges and plots the count of each as contiguous bars. Distinct from `BarChart`, which plots pre-categorized rows: the binning is the component's own job (a pure helper). Built on the shared `Chart` primitives; design-pending v1 (no `--ui-chart-*` palette yet, no `apps/demo` playground).
+
+**Status:** draft · **Category:** data-display · **Since:** v0.58.0
+
+## Import
+
+```tsx
+import { Histogram } from '@acronis-platform/ui-react'
+```
+
+## Quick example
+
+```tsx
+<Histogram
+  config={{ count: { label: 'Frequency', color: 'var(--ui-background-brand-secondary)' } }}
+  values={[12, 15, 18, 20, 22, 25, 30, 42]}
+  binCount={10}
+  className="h-[320px] w-[560px]"
+/>
+```
+
+A frequency histogram built on the shared `Chart` primitives. Give it raw
+`values` and a per-series `config`; it bins the samples into equal-width ranges
+and plots the count of each as contiguous bars — you don't pre-aggregate.
+
+The bar color comes from the `palette` prop — a dataviz palette resolving to the
+`--ui-dataviz-*` tokens, `categorical` by default — not from `config`.
+
+> **Design-pending v1.** No `apps/demo` playground — built net-new. Code Connect
+> is deferred.
+
+## When to use
+
+- Showing the **distribution** of a single continuous variable — how many
+  samples fall in each value range (response times, scores, sizes).
+- Spotting shape: skew, spread, modality, outliers.
+
+## When not to use
+
+- Comparing named categories — that's a [`BarChart`](/components/bar-chart)
+  (pre-categorized rows), not a histogram (binned continuous data).
+- Part-to-whole — use a pie/donut.
+- Two-variable relationships — use a scatter chart.
+
+## Example
+
+```tsx
+import { Histogram } from '@acronis-platform/ui-react';
+import type { ChartConfig } from '@acronis-platform/ui-react';
+
+const values = [12, 15, 18, 20, 22, 22, 25, 28, 30, 35, 42, 48, 60];
+
+const config = {
+  count: { label: 'Frequency', color: 'var(--ui-background-brand-secondary)' },
+} satisfies ChartConfig;
+
+<Histogram
+  config={config}
+  values={values}
+  binCount={10}
+  className="h-[320px] w-[560px]"
+/>;
+```
+
+Tune the resolution with `binCount`, or fix the range with `domain={[0, 100]}`
+(samples outside the domain are dropped). The bar color references an existing
+semantic `--ui-*` token; `--ui-background-brand-secondary` is brand-dependent, so
+it is not color-stable across brands until the real data-viz palette lands.
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `values` | `ReadonlyArray<number>` | — | yes | Raw continuous samples to bin. Non-finite values are ignored. |
+| `config` | `ChartConfig` | — | yes | The single series takes its colour from the container's `palette`; the entry, keyed by `dataKey`, maps it to a `label` and an optional `tone`. Resolved into the `--color-<dataKey>` custom property the bars fill from. |
+| `dataKey` | `string` | `'count'` | no | The `config` key that colors + labels the frequency bars. |
+| `binCount` | `number` | `10` | no | Number of equal-width bins to split the range into. |
+| `domain` | `[number, number]` | — | no | Fix the binning range instead of deriving it from the data's min/max; samples outside the domain are dropped. |
+| `xAxisLabel` | `string` | — | no | Title rendered beneath the horizontal (X) axis. |
+| `yAxisLabel` | `string` | — | no | Title rendered beside the vertical (Y) axis (rotated). |
+| `yUnit` | `string` | — | no | Unit suffix appended to Y-axis tick values (recharts `unit`); the X axis is the bin label. |
+| `barRadius` | `number` | `0` | no | Corner radius on the top of each bar (0 = square, the histogram default). |
+| `showGrid` | `boolean` | `true` | no | Render the CartesianGrid. |
+| `showTooltip` | `boolean` | `true` | no | Render the hover tooltip. |
+| `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. |
+
+## Behavior
+
+`Histogram` bins a set of continuous samples (`values`) into equal-width ranges
+and renders their frequencies as contiguous bars, built on the shared `Chart`
+primitives.
+
+```gherkin
+Scenario: Bin and render a distribution
+  Given values and a binCount
+  Then the [min, max] range is split into binCount equal-width bins
+  And each bar's height is the number of samples in that bin
+  And the bars are contiguous (no category gap), reading as a distribution
+```
+
+```gherkin
+Scenario: Max value placement
+  Given a sample equal to the range maximum
+  Then it falls in the last bin (whose upper edge is inclusive), not dropped
+```
+
+```gherkin
+Scenario: Explicit domain
+  Given a domain [lo, hi]
+  Then bins span [lo, hi] instead of the data's own min/max
+  And samples outside [lo, hi] are dropped
+```
+
+```gherkin
+Scenario: Degenerate range
+  Given all values are equal (a zero-width range)
+  Then the range is widened so a single bin still has extent and counts them
+```
+
+```gherkin
+Scenario: Non-finite samples
+  Given values containing NaN / Infinity
+  Then those are ignored and only finite samples are binned
+```
+
+```gherkin
+Scenario: Tooltip on hover
+  Given showTooltip is true
+  When the user hovers a bar
+  Then a card shows the bin range label and its count
+```
+
+```gherkin
+Scenario: Empty data
+  Given values is empty (or has no finite samples)
+  Then no bars render and the chart 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
+```
+
+## Accessibility
+
+- recharts' `accessibilityLayer` is **on by default** (recharts v3), giving the
+  chart keyboard focus and an accessible description of the plotted bins.
+- A histogram is inherently visual. **Pair it with a text alternative** — a
+  caption, a summary, or an adjacent data table carrying the same counts — and
+  give the chart an accessible name (`aria-label` / `aria-labelledby` referencing
+  a visible heading). The wrapper forwards native `div` attributes, so `aria-*`
+  pass through.
+- Do **not** rely on the bar color alone — the x-axis bin labels and the tooltip
+  (kept on via `showTooltip`) carry the range and count. Keep enough bins for the
+  distribution to be legible, but not so many that labels collide.
+- Watch recharts issue [#4809](https://github.com/recharts/recharts/issues/4809)
+  on the a11y layer for heavily-customized charts.
+
+## Contrast
+
+Tooltip chrome, axis labels, and the grid meet contrast in both themes via the
+semantic tokens. The bar fill comes from `config` and is the caller's
+responsibility — pick a token with sufficient contrast on the surface.