@acronis-platform/ui-react 3.0.0 → 4.0.0

package/dist/llms/progress.md

@@ -0,0 +1,111 @@
+# Progress
+
+> A horizontal bar showing the completion of a known-length task, or an indeterminate sliding bar when the length is unknown. Ported from the legacy shadcn-uikit `Progress`; wraps the Base UI Progress primitive.
+
+**Status:** draft · **Category:** feedback · **Since:** v0.40.0
+
+## Import
+
+```tsx
+import { Progress } from '@acronis-platform/ui-react'
+```
+
+## Quick example
+
+```tsx
+<Progress value={40} />
+<Progress value={null} />
+```
+
+A horizontal bar showing the completion of a known-length task, or an
+indeterminate sliding bar when the length is unknown.
+
+> **Status: draft (design-pending v1).** Ported from the legacy
+> `@acronis-platform/shadcn-uikit` `Progress`. No `--ui-progress-*` tier yet; the
+> track uses `bg-input` and the indicator the brand blue (`bg-secondary`).
+> Reconcile with `/figma-component Progress <url> --update` once a mockup lands.
+
+## When to use
+
+- Showing measurable progress of an operation (upload, install, multi-step flow).
+- An indeterminate bar (`value={null}`) for an in-progress operation of unknown
+  length.
+
+## When not to use
+
+- For a small inline busy indicator — use `Loading`.
+- For a status that isn't progress (e.g. a count) — use a different component.
+
+## Parts
+
+| Part        | Element | Purpose                                                        |
+| ----------- | ------- | -------------------------------------------------------------- |
+| `root`      | div     | `role="progressbar"`; owns the ARIA value range.               |
+| `track`     | div     | The full-width rail.                                           |
+| `indicator` | div     | The fill; width follows `value`, or slides when indeterminate. |
+
+## Example
+
+```tsx
+import { Progress } from '@acronis-platform/ui-react';
+
+<Progress value={40} />
+<Progress value={null} /> {/* indeterminate */}
+```
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `value` | `number | null` | `null` | no | Completion between `min` and `max`. `null` renders an indeterminate sliding bar. |
+| `max` | `number` | `100` | no | The value that represents full completion. |
+| `min` | `number` | `0` | no | The value that represents no completion. |
+
+## Behavior
+
+Progress shows the completion of a task. State is driven entirely by the `value`
+prop; there is no internal state.
+
+```gherkin
+Scenario: Determinate
+  Given a Progress with value={40}
+  Then the indicator fills 40% of the track
+  And aria-valuenow is 40
+```
+
+```gherkin
+Scenario: Custom range
+  Given a Progress with value={5} and max={10}
+  Then the indicator fills 50% of the track
+  And aria-valuemax is 10
+```
+
+```gherkin
+Scenario: Indeterminate
+  Given a Progress with value={null}
+  Then a fixed-width indicator slides across the track continuously
+  And aria-valuenow is omitted
+  And the root carries data-indeterminate
+```
+
+```gherkin
+Scenario: Reduced motion
+  Given a user with prefers-reduced-motion
+  Then the platform honors that preference for the sliding animation
+```
+
+## Accessibility
+
+- The root is `role="progressbar"` (provided by Base UI Progress.Root). It
+  exposes `aria-valuenow`, `aria-valuemin`, and `aria-valuemax` for determinate
+  bars, and omits `aria-valuenow` when indeterminate.
+- Give the bar an accessible name with `aria-label` or `aria-labelledby` (e.g.
+  pointing at a nearby Label) so assistive tech announces what is progressing.
+- Use `aria-valuetext` / `getAriaValueText` (forwarded to Base UI) when a
+  human-friendly value is clearer than the raw number (e.g. "Step 2 of 5").
+
+## Contrast
+
+The indicator uses `--ui-background-brand-secondary` (brand blue) over the
+`--ui-border-on-surface-border` track; both meet non-text contrast against the
+page surface in light and dark.

package/dist/llms/radar-chart.md

@@ -0,0 +1,316 @@
+# RadarChart
+
+> A typed radar-chart composition over the shared `Chart` primitives (the first polar chart type). Plots a set of series `dataKeys` over one shared angular axis (`angleKey`) inside a `ChartContainer`, with a polar grid, tooltip, and legend. One variant axis: `gridType` (the web drawn as straight-edged `polygon` rings or smooth `circle` rings). Ported from the apps/demo `RadarChartPlayground`.
+
+**Status:** draft · **Category:** data-display · **Since:** v0.58.0
+
+## Import
+
+```tsx
+import { RadarChart } from '@acronis-platform/ui-react'
+```
+
+## Quick example
+
+```tsx
+<RadarChart
+  config={config}
+  data={data}
+  dataKeys={['alice', 'bob']}
+  angleKey="subject"
+  gridType="polygon"
+  className="h-[380px] w-[420px]"
+/>
+```
+
+A typed radar-chart built on the shared `Chart` primitives. Give it `data`, a
+per-series `config`, the series to plot (`dataKeys`), and the angular axis key
+(`angleKey`); it renders a themed recharts `RadarChart` — polar grid, spoke
+labels, tooltip, and legend 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 `RadarChartPlayground`. The
+> chrome is reconciled with Figma later; Code Connect is deferred.
+
+## When to use
+
+- Comparing several entities across the **same set of quantitative axes** (skill
+  profiles, product-feature scorecards, test results per subject).
+- A handful of axes (~4–8) and a few series read best.
+
+## When not to use
+
+- A single series or a single metric — a bar chart compares magnitudes far more
+  precisely (radial value judgement is hard).
+- Many series or many axes — the overlapping areas become unreadable.
+- A trend over time — use a line or area chart.
+
+## Variants
+
+| Axis       | Values               | Effect                                                   |
+| ---------- | -------------------- | -------------------------------------------------------- |
+| `gridType` | `polygon` · `circle` | The web drawn as straight-edged rings vs smooth circles. |
+
+## Example
+
+```tsx
+import { RadarChart } from '@acronis-platform/ui-react';
+import type { ChartConfig } from '@acronis-platform/ui-react';
+
+const data = [
+  { subject: 'Math', alice: 120, bob: 110 },
+  { subject: 'English', alice: 86, bob: 130 },
+  { subject: 'Physics', alice: 85, bob: 90 },
+  { subject: 'History', alice: 65, bob: 85 },
+];
+
+const config = {
+  alice: { label: 'Alice', color: 'var(--ui-background-brand-secondary)' },
+  bob: { label: 'Bob', color: 'var(--ui-background-status-strong-danger)' },
+} satisfies ChartConfig;
+
+<RadarChart
+  config={config}
+  data={data}
+  dataKeys={['alice', 'bob']}
+  angleKey="subject"
+  className="h-[380px] w-[420px]"
+/>;
+```
+
+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 |
+|------|------|---------|----------|-------------|
+| `gridType` | `'polygon' | 'circle'` | `'polygon'` | no | How the polar grid (web) is drawn. `polygon` = straight-edged rings connecting the spokes; `circle` = smooth concentric rings. |
+| `data` | `ReadonlyArray<Record<string, string | number>>` | — | yes | Row-per-axis data — each row holds `angleKey` plus one numeric field per series. Every plotted series needs a value in every row: a missing one is placed at the centre, which reads as a zero rather than as a gap. |
+| `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 areas stroke and fill from. |
+| `dataKeys` | `string[]` | — | yes | Series to plot — one radar area per key. Each must exist in `config` and every data row. |
+| `angleKey` | `string` | — | yes | The categorical axis key placed around the web (the spokes). |
+| `seriesSettings` | `Record<string, RadarChartSeriesSettings>` | — | no | Per-series style overrides keyed by a `dataKeys` entry — `color`, `stroke`, `fillOpacity`, `strokeWidth`, `dot`, `dotRadius`, `activeDot`. Unplotted keys are ignored. An overridden `color` — or `stroke`, which the renderer reads first — carries into that series' legend swatch and tooltip dot. |
+| `fillOpacity` | `number` | `0.3` | no | Fill opacity of each radar area. |
+| `strokeWidth` | `number` | `2` | no | Stroke width of each radar outline. |
+| `showDots` | `boolean` | `false` | no | Render a dot at each axis point. |
+| `dotRadius` | `number` | `3` | no | Radius of the per-point dots when `showDots` is on. |
+| `activeDot` | `boolean` | `true` | no | Enlarge the hovered point's dot. On by default; `false` for a chart that should not react to the pointer. |
+| `showGrid` | `boolean` | `true` | no | Render the polar grid (the web). |
+| `radialLines` | `boolean` | `true` | no | Draw the grid's spokes (the radial lines out to each category). Off leaves only the concentric rings. |
+| `showAngleAxis` | `boolean` | `true` | no | Render the categorical axis chrome (spoke labels, tick lines, outer line). The axis itself is kept either way, so the tooltip still names each category. |
+| `angleAxisOrientation` | `'inner' | 'outer'` | `'outer'` | no | Place the spoke labels outside the web or inside it. |
+| `angleAxisLine` | `boolean` | `true` | no | Draw the line around the web that the spoke labels sit against. |
+| `angleAxisLineType` | `'polygon' | 'circle'` | `'polygon'` | no | Shape of that line. Independent of `gridType`, so pair them to keep a circular web's outline circular. |
+| `angleTickLine` | `boolean` | `true` | no | Draw a tick line from the axis line to each spoke label. |
+| `angleTickSize` | `number` | — | no | Distance from the web to the spoke labels, in px. Left unset, `showLabels` widens it so a vertex's value clears its category label. |
+| `showRadiusAxis` | `boolean` | `false` | no | Render the value scale — a radial axis of ticks from the centre outward, so an area reads as a number and not only as a comparison. Only `radiusAxisAngle` and `radiusAxisOrientation` need it shown; `radiusAxisDomain`, `radiusAxisReversed` and `radiusAxisTickCount` apply either way. |
+| `radiusAxisAngle` | `number` | `0` | no | Angle the value scale is drawn at, in degrees counter-clockwise from 3 o'clock. Point it between two spokes — along one, its outermost tick collides with that category's own label. The ticks sit over the areas at any angle. |
+| `radiusAxisOrientation` | `'left' | 'right' | 'middle'` | `'right'` | no | Which side of the scale its tick labels sit on. |
+| `radiusAxisDomain` | `'auto' | 'fixed'` | — | no | How the value scale (and with it the web) is bounded. Unset — the data's largest value reaches the outer ring; `fixed` — the outer ring is `radiusAxisDomainMax`, which is what makes the radar an absolute profile; `auto` — fit the data at both ends. Applies whether or not the scale is shown. |
+| `radiusAxisDomainMax` | `number` | — | no | The value at the outer ring when `radiusAxisDomain` is `fixed`. Must be positive — a `0` or negative maximum cannot bound a scale that grows outward from 0, so it falls back to the data's own top. |
+| `radiusAxisTickCount` | `number` | `5` | no | Desired number of ticks on the value scale (a hint, not exact). Also sets how many rings the grid draws, whether or not the scale is shown. |
+| `radiusAxisReversed` | `boolean` | `false` | no | Invert the value scale (maximum at the centre) for a metric where less is better. |
+| `cx` | `number | string` | `'50%'` | no | Horizontal centre of the web, in px or a percentage of the width. |
+| `cy` | `number | string` | `'50%'` | no | Vertical centre of the web, in px or a percentage of the height. |
+| `startAngle` | `number` | `90` | no | Angle the first category sits at, in degrees. |
+| `endAngle` | `number` | `-270` | no | Angle the sweep ends at, in degrees — a full clockwise turn from `startAngle` by default. |
+| `innerRadius` | `number | string` | `0` | no | Radius of the hole at the centre, in px or a percentage of the available radius. Lifts the grid and the areas off the centre. |
+| `outerRadius` | `number | string` | `'80%'` | no | Outer radius of the web, in px or a percentage of the available radius. |
+| `margin` | `{ top?: number; right?: number; bottom?: number; left?: number }` | — | no | Plot-area margin, in px. Passing the object replaces all four sides; a side left out is `0`, not the default `5`, so name every side. |
+| `showTooltip` | `boolean` | `true` | no | Render the hover tooltip. |
+| `showLegend` | `boolean` | `true` | no | Render the legend. |
+| `legendPosition` | `'top' | 'bottom'` | `'bottom'` | no | Which side of the chart the legend sits on. |
+| `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. |
+| `showLabels` | `boolean` | `false` | no | Render a value label on each data point/segment. |
+| `labelPosition` | `'top' | 'bottom' | 'left' | 'right' | 'center' | 'insideTop' | 'insideBottom' | 'insideLeft' | 'insideRight' | 'insideStart' | 'insideEnd'` | — | no | Where the value labels sit. |
+| `labelFormatter` | `(value) => string` | — | no | Format each label value (reuses the tick formatters). |
+
+## Behavior
+
+`RadarChart` is a typed [recharts](https://recharts.org) composition over the
+shared `Chart` primitives. It plots a set of series (`dataKeys`) over one shared
+angular axis (`angleKey`) inside a `ChartContainer`.
+
+```gherkin
+Scenario: Render radar areas from data and config
+  Given data rows and a config mapping each series key to a label and color
+  And dataKeys ["alice", "bob"]
+  Then one <Radar> area renders per dataKey
+  And each area strokes and fills from its injected --color-<key> custom property
+```
+
+```gherkin
+Scenario: Polygon grid (default)
+  Given gridType is "polygon"
+  Then the polar grid draws straight-edged rings connecting the spokes
+```
+
+```gherkin
+Scenario: Circle grid
+  Given gridType is "circle"
+  Then the polar grid draws smooth concentric rings
+```
+
+```gherkin
+Scenario: Angle axis
+  Given an angleKey
+  Then each data row contributes one labelled spoke around the web
+```
+
+```gherkin
+Scenario: Angle-axis chrome
+  Given showAngleAxis is false
+  Then no spoke labels, tick lines, or outer axis line render
+  And the axis itself is still mounted, so the tooltip names each category
+```
+
+```gherkin
+Scenario: Value scale
+  Given showRadiusAxis is true
+  Then a radial scale of ticks renders from the centre outward at radiusAxisAngle
+```
+
+```gherkin
+Scenario: Absolute scaling
+  Given radiusAxisDomain is "fixed" and radiusAxisDomainMax is the metric maximum
+  Then the outer ring is that maximum rather than the largest value in the data
+  And two charts of the same metric are comparable
+  And the rescaling applies whether or not the scale is shown
+```
+
+```gherkin
+Scenario: Inverted scale
+  Given radiusAxisReversed is true
+  Then the maximum sits at the centre and 0 at the outer ring
+```
+
+```gherkin
+Scenario: Unusable fixed maximum
+  Given radiusAxisDomain is "fixed"
+  And radiusAxisDomainMax is zero, negative, or not a finite number
+  Then the outer ring falls back to the data's own largest value
+  And the web is neither collapsed onto its centre nor inverted
+```
+
+```gherkin
+Scenario: Grid spokes
+  Given radialLines is false
+  Then the web keeps its concentric rings and drops the radial spokes
+```
+
+```gherkin
+Scenario: Dots
+  Given showDots is true
+  Then a dot renders where each series crosses each spoke
+  And its radius is dotRadius
+```
+
+```gherkin
+Scenario: Per-series overrides
+  Given seriesSettings has an entry keyed by a plotted dataKeys entry
+  Then that series uses the entry's color/stroke/opacity/width/dots
+  And a color or stroke override also moves that series' legend swatch and tooltip dot
+  And every other series keeps the chart-level values
+  And an entry for a key that is not plotted is ignored
+  And a deliberately falsy override (zero opacity or width, dots off) wins over the chart-level value
+```
+
+```gherkin
+Scenario: Geometry
+  Given cx/cy, startAngle/endAngle, innerRadius/outerRadius or margin
+  Then the web, its axes, and the areas are all laid out to match
+```
+
+```gherkin
+Scenario: Tooltip on hover
+  Given showTooltip is true
+  When the user hovers near a spoke
+  Then a card shows the axis 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 legendPosition puts the row below (default) or above the chart
+```
+
+```gherkin
+Scenario: Empty data
+  Given data is an empty array
+  Then the chart renders the grid with no areas 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
+```
+
+### Not exposed, and why
+
+- **A grid-only inner/outer radius.** recharts ignores a `PolarGrid`'s own
+  `innerRadius`/`outerRadius` inside a chart — it takes both from the chart's
+  polar view box — so the web's extent is the chart-level `innerRadius` /
+  `outerRadius`, which moves the axes and the areas with it.
+- **`connectNulls`.** recharts places a radar point with no value at the centre
+  (radius 0) rather than leaving a hole, so there is no gap for a `connectNulls`
+  to bridge — a series missing a value renders as a spike into the middle, which
+  reads as a zero. Every plotted series therefore needs a value in every row;
+  drop the whole category row instead.
+- **A per-series legend marker shape.** The shared `ChartLegendContent` now picks
+  a marker from the series' `legendType` (swatch / line / dashed), so a per-series
+  shape became expressible once that rework landed. It stays unexposed here on
+  purpose: a radar paints filled areas, so every series wants the swatch, and
+  choosing per series is a design call across the whole chart suite rather than
+  one component's prop.
+
+## Accessibility
+
+- recharts' `accessibilityLayer` is **on by default** (recharts v3), giving the
+  chart keyboard focus and an accessible description of the plotted points.
+- A radar chart is inherently visual (and hard to read precisely — overlapping
+  areas, angular value judgement). **Pair it with a text alternative** — a
+  caption, a summary, or an adjacent data table carrying the same numbers — 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 series. Keep `showLegend` (or the
+  tooltip) visible so each color is paired with a text label; keep `fillOpacity`
+  low enough that overlapping areas remain distinguishable.
+- The chrome (tooltip, legend, polar grid) resolves to semantic `--ui-*` tokens
+  that meet contrast in light and dark. The component adds a local override so the
+  **angle-axis (spoke) labels** use `muted-foreground` — without it they render
+  near-black and disappear in dark mode (the shared container themes only
+  cartesian axis ticks; this is a tracked shared-primitives gap). **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.
+- Watch recharts issue [#4809](https://github.com/recharts/recharts/issues/4809)
+  on the a11y layer for heavily-customized charts.
+
+## Contrast
+
+Chart chrome and the spoke labels meet contrast in both themes via the semantic
+tokens. Radar area fills/strokes come from `config` and are the caller's
+responsibility — translucent overlapping fills lower effective contrast.