@acronis-platform/ui-react 3.0.0 → 4.0.0

package/dist/llms/confidence-cone.md

@@ -0,0 +1,277 @@
+# ConfidenceCone
+
+> A forecast confidence-cone over the shared `Chart` primitives: a solid line for the known/actual period, a dashed line for the forecast, and a shaded band (the "cone") between a lower and upper bound that typically widens with the horizon, visualizing growing uncertainty. Distinct from the conversion `FunnelChart`. Design-pending v1 (no `--ui-chart-*` palette, no `apps/demo` playground — built net-new).
+
+**Status:** draft · **Category:** data-display · **Since:** v0.58.0
+
+## Import
+
+```tsx
+import { ConfidenceCone } from '@acronis-platform/ui-react'
+```
+
+## Quick example
+
+```tsx
+<ConfidenceCone
+  config={{
+    actual: { label: 'Actual', color: 'var(--ui-background-brand-secondary)' },
+    forecast: { label: 'Forecast', color: 'var(--ui-background-brand-secondary)' },
+  }}
+  data={data}
+  xKey="month"
+  actualKey="actual"
+  forecastKey="forecast"
+  lowerKey="lower"
+  upperKey="upper"
+  className="h-[320px] w-[560px]"
+/>
+```
+
+A forecast confidence-cone built on the shared `Chart` primitives: give it a
+time series with actual values, forecast values, and a lower/upper bound per
+forecast point; it draws the actuals as a solid line with a filled area, the
+forecast as a dashed line, and the uncertainty as a shaded band that widens with
+the horizon — plus a divider and shaded region setting the forecast off from the
+actuals. Each metric is **one color**: actual vs forecast differ by line style
+(solid vs dashed), not hue.
+
+`series` plots several metrics against one shared axis, each with its own
+columns, hue and independent cone; `actualType="line"` drops the fill under the
+actuals so the cones stay the only shaded regions (worth it as soon as there is
+more than one metric). Omitting a series' bound keys gives a band-less
+projection — a bare dashed line, for a model with a point estimate but no
+interval. `referenceLine` adds dashed value-axis thresholds, `showDots` marks
+points (filled on the actuals, hollow on the projection), and
+`styleForecastTicks` italicizes and accents the projected period's X ticks.
+
+Metric colors come from the `palette` prop — a dataviz palette resolving to the
+`--ui-dataviz-*` tokens, `categorical` by default — not from `config`. The actual
+area and the cone band reuse the actual series' color at low opacity.
+
+> **Design-pending v1.** Built net-new (no `apps/demo` playground); Code Connect
+> deferred.
+
+## When to use
+
+- Showing a projection with **explicit uncertainty** — capacity/licenses/revenue
+  forecasts where the plausible range matters, not just the point estimate.
+
+## When not to use
+
+- A conversion funnel — that's [`FunnelChart`](/components/funnel-chart), a
+  different thing despite the "cone/funnel" shape.
+- A plain trend with no forecast — use [`LineChart`](/components/line-chart)
+  (which also supports comparison overlays + delta bands).
+
+## Example
+
+```tsx
+import { ConfidenceCone } from '@acronis-platform/ui-react';
+import type { ChartConfig } from '@acronis-platform/ui-react';
+
+const data = [
+  { month: 'Apr', actual: 130 },
+  { month: 'May', actual: 141 },
+  { month: 'Jun', actual: 150, forecast: 150, lower: 150, upper: 150 }, // hand-off
+  { month: 'Jul', forecast: 162, lower: 150, upper: 176 },
+  { month: 'Aug', forecast: 173, lower: 154, upper: 196 },
+];
+
+const config = {
+  actual: { label: 'Actual', color: 'var(--ui-background-brand-secondary)' },
+  forecast: {
+    label: 'Forecast',
+    color: 'var(--ui-background-brand-secondary)',
+  },
+} satisfies ChartConfig;
+
+<ConfidenceCone
+  config={config}
+  data={data}
+  xKey="month"
+  actualKey="actual"
+  forecastKey="forecast"
+  lowerKey="lower"
+  upperKey="upper"
+  className="h-[320px] w-[560px]"
+/>;
+```
+
+Make the actual and forecast lines meet by giving the hand-off point both an
+`actual` and a `forecast` (with `lower = upper` so the cone starts at a point).
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `data` | `ReadonlyArray<Record<string, string | number | null | undefined>>` | — | yes | Row-per-point data. Rows are naturally sparse — a point carries either an actual value or a forecast + its bounds — so missing fields are allowed. Field names starting with `__cone` are reserved for the internal prediction-band series and must not be used for a caller's own column. |
+| `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 lines and areas paint from. Each metric renders in one hue: its cone band and forecast line both reuse its actual series' color — actual and forecast differ by line style, not hue. |
+| `xKey` | `string` | — | yes | The time / category dimension key shared across rows. |
+| `series` | `ReadonlyArray<{ actualKey: string; forecastKey: string; lowerKey?: string; upperKey?: string }>` | — | no | Plot several metrics against one shared axis — each with its own actual / forecast / bound fields and its own hue (from config[actualKey]). Takes precedence over the single-series actualKey / forecastKey / lowerKey / upperKey shorthand; pass one form or the other, not both. |
+| `actualKey` | `string` | — | no | Single-series shorthand — field for the known/actual values, drawn as a solid line with a filled area. Ignored when series is set. |
+| `forecastKey` | `string` | — | no | Single-series shorthand — field for the projected values, drawn as a dashed line. Ignored when series is set. |
+| `lowerKey` | `string` | — | no | Field for the cone's lower bound. Omit (with upperKey) for a band-less projection: a bare dashed forecast line, no cone. |
+| `upperKey` | `string` | — | no | Field for the cone's upper bound. Omit (with lowerKey) for a band-less projection: a bare dashed forecast line, no cone. |
+| `showDots` | `boolean` | `false` | no | Mark each data point — a filled dot on the observed values, a hollow one on the projection — so a point reads as measured or predicted at a glance. |
+| `styleForecastTicks` | `boolean` | `false` | no | Italicize the X-axis ticks over the forecast period and paint them in the first series' hue, so the projected columns read as projected even when the shaded region is off. |
+| `referenceLine` | `{ value: number; label?: string } | Array<{ value: number; label?: string }>` | — | no | One or more dashed horizontal thresholds on the value axis — e.g. a target or a capacity limit. Pass a single object or an array to draw several. A threshold beyond the data max extends the domain so it stays visible. |
+| `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 categorical. |
+| `actualType` | `'area' | 'line'` | `'area'` | no | How the known/actual period is drawn — a filled area under the line, or a bare line, for a chart where the cone should be the only shaded region or where several metrics' fills would muddy each other. |
+| `strokeWidth` | `number` | `2` | no | Stroke width of the actual + forecast lines. |
+| `showForecastRegion` | `boolean` | `true` | no | Set off the forecast period with a dashed divider at the hand-off point (the first row with a forecast value) and a subtle shaded band over the forecast region. |
+| `showGrid` | `boolean` | `true` | no | Render the CartesianGrid. |
+| `showTooltip` | `boolean` | `true` | no | Render the hover tooltip (the band series is filtered out of it). |
+| `showLegend` | `boolean` | `true` | no | Render the legend (the band series is filtered out of it). |
+| `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
+
+`ConfidenceCone` composes a solid actual line, a dashed forecast line, and a
+shaded prediction band (the "cone") on the shared `Chart` primitives.
+
+```gherkin
+Scenario: Actual + forecast + cone (one color)
+  Given data with actual values up to a hand-off point, then forecast values with lower/upper bounds
+  Then the actual period renders as a solid line with a filled area beneath it
+  And the forecast period renders as a dashed line
+  And a shaded band fills between lower and upper across the forecast, typically widening with the horizon
+  And the metric uses one color: the actual area, forecast line, and cone band all reuse the actual series' color (actual vs forecast differ by line style, not hue)
+  And the areas mark no points unless showDots is set
+```
+
+```gherkin
+Scenario: Several metrics on one shared axis
+  Given a series array naming each metric's actual / forecast / bound fields
+  Then every metric renders its own cone and lines against the one shared axis
+  And each metric uses its own hue, taken from config[actualKey]
+  And every cone renders behind every line, so no band covers another metric's line
+  And the legend names each metric once
+  And the series array supersedes the single-series actualKey / forecastKey / lowerKey / upperKey shorthand
+```
+
+```gherkin
+Scenario: Actual as a bare line
+  Given actualType is "line"
+  Then the observed period renders as a solid line with no filled region beneath it
+  And the cone band is the only shaded region left under the series
+  And with actualType "area" (the default) the filled region returns
+```
+
+```gherkin
+Scenario: Band-less projection
+  Given a series that omits lowerKey and upperKey
+  Then its actual line hands off to a bare dashed forecast with no cone
+  And other series in the same chart still render their own cones
+```
+
+```gherkin
+Scenario: Value-axis thresholds
+  Given a referenceLine value (or an array of them)
+  Then each renders as a dashed horizontal line on the value axis, with its label at the line's right end
+  And a threshold beyond the data max extends the domain so it stays visible
+```
+
+```gherkin
+Scenario: Measured vs predicted points
+  Given showDots is true
+  Then each observed point carries a filled dot in the metric's hue
+  And each projected point carries a hollow dot — the metric's hue as its outline, the surface color as its fill
+  And with showDots false (the default) no point is marked
+```
+
+```gherkin
+Scenario: Styled forecast ticks
+  Given styleForecastTicks is true
+  Then the X-axis ticks over the projected period render italic in the first series' hue
+  And the ticks over the actual period keep the axis' default styling
+  And a caller's xTickFormatter still formats every tick
+  And the projected ticks are matched by x value, so a tick interval that skips ticks cannot mis-style them
+```
+
+```gherkin
+Scenario: Forecast region marker
+  Given showForecastRegion is true (the default) and a hand-off point exists
+  Then a dashed vertical divider is drawn at the hand-off (first row with a forecast)
+  And a subtle shaded band covers the forecast region behind the series
+  And with showForecastRegion false, neither the divider nor the shaded region render
+```
+
+```gherkin
+Scenario: Missing bounds
+  Given a row without numeric lower/upper (e.g. the actual-only period)
+  Then the cone band breaks there (only the forecast region is shaded)
+```
+
+```gherkin
+Scenario: Band excluded from chrome
+  Given showTooltip and/or showLegend are true
+  Then the synthetic band range series is filtered out of the tooltip and legend
+  And only the actual and forecast series appear there
+```
+
+```gherkin
+Scenario: Tooltip on hover
+  Given showTooltip is true
+  When the user hovers a point
+  Then a card shows the point's actual and/or forecast value (not the band)
+```
+
+```gherkin
+Scenario: Empty data
+  Given data is an empty array
+  Then the chart renders its axes and grid with no lines or band 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 series.
+- A forecast cone is inherently visual. **Pair it with a text alternative** — a
+  caption or an adjacent table with the actual, forecast, and bound values — and
+  give the chart an accessible name (`aria-label` / `aria-labelledby`). The
+  wrapper forwards native `div` attributes, so `aria-*` pass through.
+- Don't rely on color or line style alone: the legend labels the actual vs
+  forecast series, and the tooltip carries the values. The dashed forecast line
+  is a redundant cue on top of color, not the only distinction.
+- 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 actual/forecast line colors come from `config` and are the
+caller's responsibility; the cone band is a low-opacity tint of the forecast
+color, intended as a secondary cue behind the lines.