@acronis-platform/ui-react 3.0.0 → 4.0.0

package/dist/llms/pie-chart.md

@@ -0,0 +1,307 @@
+# PieChart
+
+> A typed pie/donut-chart composition over the shared `Chart` primitives. Takes `data` + `config` + a `dataKey` (slice value) and `nameKey` (slice label) and renders a themed recharts `PieChart` inside a `ChartContainer`, with tooltip and legend chrome. One variant axis: `shape` (filled pie / hollow-centre donut). Ported from the apps/demo `PieChartPlayground`.
+
+**Status:** draft · **Category:** data-display · **Since:** v0.58.0
+
+## Import
+
+```tsx
+import { PieChart } from '@acronis-platform/ui-react'
+```
+
+## Quick example
+
+```tsx
+<PieChart
+  config={config}
+  data={data}
+  dataKey="value"
+  nameKey="browser"
+  shape="donut"
+  className="h-[360px] w-[360px]"
+/>
+```
+
+A typed pie/donut-chart built on the shared `Chart` primitives. Give it `data`, a
+per-slice `config`, the value field (`dataKey`), and the label field (`nameKey`);
+it renders a themed recharts `PieChart` — tooltip and legend included — so you
+don't hand-compose recharts children.
+
+Slice 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 `PieChartPlayground`. The
+> chrome is reconciled with Figma later; Code Connect is deferred.
+
+## When to use
+
+- Showing part-to-whole proportions across a handful of categories.
+- A compact, at-a-glance distribution (device share, channel split).
+- Use `shape="donut"` when you want a lighter footprint or a centre for a total.
+
+## When not to use
+
+- More than ~6 categories, or many similar-sized slices — use a bar chart, which
+  compares magnitudes far more precisely.
+- Trends over time — use a line or area chart.
+- Comparing exact values — angles are hard to read; prefer bars or a table.
+
+## Variants
+
+| Axis    | Values          | Effect                                    |
+| ------- | --------------- | ----------------------------------------- |
+| `shape` | `pie` · `donut` | Filled arc vs a hollow-centre donut ring. |
+
+## Example
+
+```tsx
+import { PieChart } from '@acronis-platform/ui-react';
+import type { ChartConfig } from '@acronis-platform/ui-react';
+
+const data = [
+  { browser: 'Chrome', value: 275 },
+  { browser: 'Safari', value: 200 },
+  { browser: 'Firefox', value: 187 },
+  { browser: 'Edge', value: 173 },
+];
+
+const config = {
+  Chrome: { label: 'Chrome', color: 'var(--ui-background-brand-secondary)' },
+  Safari: {
+    label: 'Safari',
+    color: 'var(--ui-background-status-strong-danger)',
+  },
+  Firefox: {
+    label: 'Firefox',
+    color: 'var(--ui-background-status-strong-success)',
+  },
+  Edge: { label: 'Edge', color: 'var(--ui-background-status-strong-warning)' },
+} satisfies ChartConfig;
+
+<PieChart
+  config={config}
+  data={data}
+  dataKey="value"
+  nameKey="browser"
+  shape="donut"
+  className="h-[360px] w-[360px]"
+/>;
+```
+
+Slice colors reference existing semantic `--ui-*` tokens, keyed by each slice'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 |
+|------|------|---------|----------|-------------|
+| `shape` | `'pie' | 'donut'` | `'donut'` | no | Arc shape. `donut` leaves a hollow centre (`innerRadius`); `pie` fills to the centre. |
+| `data` | `ReadonlyArray<Record<string, string | number>>` | — | yes | Row-per-slice data — each row holds a `nameKey` label and a `dataKey` numeric value. |
+| `config` | `ChartConfig` | — | yes | Slices take their colour from the container's `palette`; each entry, keyed by the slice's `nameKey` value, maps that slice to a `label` and an optional `tone`. Resolved into the `--color-<name>` custom properties the slices fill from. |
+| `dataKey` | `string` | — | yes | The numeric field that sizes each slice. |
+| `nameKey` | `string` | — | yes | The label field that names each slice (drives legend, tooltip, and the `--color-<name>` lookup). Values should be unique per chart — rows sharing a name share one config/color entry. |
+| `innerRadius` | `number` | `48` | no | Inner radius of the arc when `shape="donut"` (ignored for `shape="pie"`). |
+| `centerLabel` | `{ value?: string | number; label?: string | number }` | — | no | Custom content for the donut hole — a headline `value` and/or a `label` caption, stacked and centered. Rendered only for `shape="donut"`. |
+| `outerRadius` | `number` | `60` | no | Outer radius of the arc. |
+| `paddingAngle` | `number` | `2` | no | Gap between slices, in degrees. |
+| `cornerRadius` | `number` | — | no | Corner radius of each slice. |
+| `startAngle` | `number` | `90` | no | Angle the sweep starts at, in degrees (90 is 12 o'clock). Defaults to the top of the clock face. Pair with endAngle for a semicircle (180 → 0) or an arc. A partial sweep still centres on the full plot area, so a half turn fills only half its box — give it a short, wide one. |
+| `endAngle` | `number` | `-270` | no | Angle the sweep ends at, in degrees. Defaults to a full clockwise circle from the startAngle (startAngle − 360). |
+| `minAngle` | `number` | — | no | Smallest angle a non-zero slice may occupy, in degrees — keeps a tiny slice visible (and hoverable) at the cost of being drawn out of proportion. |
+| `sliceSettings` | `Record<string, { color?: string; hideLabel?: boolean; labelFormat?: PieChartLabelFormat }>` | — | no | Per-slice overrides keyed by the slice's nameKey value: its color, and whether/how its data label reads. A name with no entry keeps the chart-level behavior. |
+| `showTooltip` | `boolean` | `true` | no | Render the hover tooltip. |
+| `showLegend` | `boolean` | `true` | no | Render the legend. |
+| `legendValueFormatter` | `(value: string | number) => string` | — | no | Format each slice's value in the list legend. Omit to stringify the raw value. |
+| `margin` | `{ top?: number; right?: number; bottom?: number; left?: number }` | — | no | Plot-area margin, in px. Omit to use the renderer's default (5 on every side). |
+| `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. Takes precedence over tooltipFormat. Ignored when showTooltip is false. |
+| `tooltipFormat` | `'value' | 'value-percent'` | `'value'` | no | How the default tooltip reads a slice: its value alone, or the value followed by its share of the total (formatted like a data label's share, so the two always agree). Pass tooltipContent to format it differently. |
+| `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 slice. |
+| `labelPosition` | `'outside' | 'center' | 'centerTop' | 'centerBottom' | 'insideStart' | 'insideEnd' | 'end'` | `'outside'` | no | Where the value labels sit. Defaults to outside the arc, on the chart surface — the only placement guaranteed to have contrast against any palette's slice colors. Inside placements switch the label to the on-fill token. Ignored when labelLine is on — a leader line only ever ends outside the arc. |
+| `labelFormat` | `'value' | 'name-value' | 'name-percent' | 'percent'` | `'value'` | no | What each data label reads — the value alone, or the slice name and/or its share of the total (to one decimal, with a "." decimal separator and a bare "%", not locale-aware). Overridable per slice via sliceSettings. |
+| `labelLine` | `boolean` | `false` | no | Draw a leader line from each slice to its data label, in the slice's own color. Moves the labels outside the arc; a slice whose label is hidden by sliceSettings gets no line either. |
+| `labelFormatter` | `(value) => string` | — | no | Format each label value (reuses the tick formatters). Formats the slice's value, so it reaches the value and name-value formats only — a share is always rendered as NN.N% and never passes through it. |
+
+## Behavior
+
+`PieChart` is a typed [recharts](https://recharts.org) composition over the
+shared `Chart` primitives. It takes `data`, a per-slice `config`, the value field
+(`dataKey`), and the label field (`nameKey`), and renders a themed recharts
+`PieChart` inside a `ChartContainer`.
+
+```gherkin
+Scenario: Render slices from data and config
+  Given data rows and a config mapping each slice name to a label and color
+  And dataKey "value" and nameKey "browser"
+  Then one arc slice renders per row, sized by its dataKey value
+  And each slice fills from its injected --color-<name> custom property
+```
+
+```gherkin
+Scenario: Pie shape (default)
+  Given shape is "pie"
+  Then the arc fills to the centre (innerRadius 0)
+```
+
+```gherkin
+Scenario: Donut shape
+  Given shape is "donut"
+  Then the arc has a hollow centre at innerRadius
+```
+
+```gherkin
+Scenario: Padding between slices
+  Given paddingAngle is greater than 0
+  Then a gap of that many degrees separates adjacent slices
+```
+
+```gherkin
+Scenario: Partial sweep
+  Given a startAngle of 180 and an endAngle of 0
+  Then the slices are laid out over that half turn instead of a full circle
+  And their relative sizes are unchanged
+```
+
+```gherkin
+Scenario: Rounded slices
+  Given cornerRadius is greater than 0
+  Then each slice's corners are rounded by that radius
+```
+
+```gherkin
+Scenario: Minimum slice angle
+  Given minAngle is greater than 0
+  Then every non-zero slice occupies at least that angle
+  And a slice smaller than it is drawn out of proportion so it stays hoverable
+```
+
+```gherkin
+Scenario: Data-label format
+  Given showLabels is true
+  And labelFormat is one of value, name-value, name-percent or percent
+  Then each slice's label reads its value, its name, and/or its share of the
+    sum of every slice value, to one decimal
+  And a labelFormatter formats the slice's value, so it reaches the value and
+    name-value formats only — a share is always rendered as NN.N%
+```
+
+```gherkin
+Scenario: Percent with nothing to divide by
+  Given a percent-bearing labelFormat
+  And the slice values sum to zero, or this slice's value is non-numeric
+  Then name-percent falls back to the slice name and percent renders no label
+```
+
+```gherkin
+Scenario: Slice with no value at all
+  Given a data row that carries no dataKey field
+  Then the name-bearing formats fall back to the bare slice name
+  And the value-only formats render no label, rather than an empty one
+```
+
+```gherkin
+Scenario: Leader lines
+  Given showLabels and labelLine are both true
+  Then a line runs from each slice to its label, in that slice's colour
+  And the labels sit outside the arc regardless of labelPosition
+```
+
+```gherkin
+Scenario: Per-slice overrides
+  Given a sliceSettings entry keyed by a slice's nameKey value
+  Then that slice takes the entry's colour and labelFormat in place of the
+    chart-level ones
+  And an entry with hideLabel drops that slice's label — and its leader line —
+    while every other slice keeps its own
+```
+
+```gherkin
+Scenario: Tooltip on hover
+  Given showTooltip is true
+  When the user hovers a slice
+  Then a card shows that slice's name and value
+```
+
+```gherkin
+Scenario: Tooltip value format
+  Given tooltipFormat is "value-percent"
+  When the user hovers a slice
+  Then the card shows that slice's value followed by its share of the total
+  And a tooltipContent of the caller's own takes precedence over the preset
+```
+
+```gherkin
+Scenario: Legend
+  Given showLegend is true
+  Then a swatch + label renders for each slice (from nameKey / config)
+  And it sits on the edge given by legendPosition (bottom by default)
+```
+
+```gherkin
+Scenario: Donut center label
+  Given shape is "donut" and a centerLabel { value, label }
+  Then the value renders large and the label smaller beneath it, centered in the hole
+  And the block stays centered on the donut whether or not a legend is shown,
+    and on whichever edge legendPosition puts it
+```
+
+```gherkin
+Scenario: Center label ignored for a pie
+  Given shape is "pie" and a centerLabel
+  Then no center content renders (a filled pie has no hole)
+```
+
+```gherkin
+Scenario: Empty data
+  Given data is an empty array
+  Then the chart renders with no slices 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 slices.
+- A pie 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 slices. Keep `showLegend` (or the
+  tooltip) visible so each color is paired with a text label. Pie charts read
+  poorly with many similar-sized slices — prefer a handful of slices and combine
+  the tail into an "Other" slice.
+- The chrome (tooltip, legend) resolves to semantic `--ui-*` tokens that meet
+  contrast in light and dark. **Slice colors are caller-supplied** via `config` —
+  pick values that meet 3:1 against the surface and are distinguishable for
+  color-vision deficiencies (adjacent slices especially). 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 meets contrast in both themes via the semantic tokens. Slice fills
+come from `config` and are the caller's responsibility — keep adjacent slices
+distinguishable, not just against the surface but from each other.

package/dist/llms/popover.md

@@ -0,0 +1,252 @@
+# Popover
+
+> A floating panel anchored to a trigger, shown on demand for secondary content or quick actions. Built on the Base UI Popover primitive (positioning, focus management, outside-press / Esc dismissal). Ported from the legacy shadcn-uikit `Popover`; container chrome themed by the `--ui-popover-*` tier, with optional `PopoverBody`/`PopoverFooter` parts for the body-rhythm and default action-row recipe shown in Figma.
+
+**Status:** ready · **Category:** overlays · **Since:** v0.12.0
+
+## Import
+
+```tsx
+import { Popover, PopoverTrigger, PopoverContent, PopoverBody, PopoverFooter } from '@acronis-platform/ui-react'
+```
+
+## Quick example
+
+```tsx
+<Popover>
+  <PopoverTrigger render={<Button variant="secondary">Open</Button>} />
+  <PopoverContent side="bottom" align="center">
+    <PopoverBody>
+      <h4>Dimensions</h4>
+      <p>Set the dimensions for the layer.</p>
+    </PopoverBody>
+    <PopoverFooter>
+      <Button variant="secondary">Cancel</Button>
+      <Button>Apply</Button>
+    </PopoverFooter>
+  </PopoverContent>
+</Popover>
+```
+
+A floating panel anchored to a trigger, shown on demand for secondary content or
+quick actions. Built on the Base UI Popover primitive.
+
+> Ported from the legacy `@acronis-platform/shadcn-uikit` `Popover`. Container
+> chrome is themed by the `--ui-popover-*` tier; the optional `PopoverBody` /
+> `PopoverFooter` parts (body rhythm, default action-row footer) are themed by
+> `--ui-popover-body-*` and the shared `--ui-footer-*` tier. Enter/exit
+> animations use `tw-animate-css`.
+
+## When to use
+
+- Showing secondary content or a small set of controls anchored to a trigger
+  (a filter form, a quick edit, extra detail) without leaving the page.
+
+## When not to use
+
+- For a blocking decision or a focused task — use a **Dialog** (modal).
+- For a short, non-interactive hint on hover/focus — use a **Tooltip**.
+- For a list of actions/commands — use a menu.
+
+## Parts
+
+| Part             | Element            | Purpose                                        |
+| ---------------- | ------------------ | ---------------------------------------------- |
+| `Popover`        | — (Root)           | Owns the open state.                           |
+| `PopoverTrigger` | `button`           | Toggles and anchors the popover.               |
+| `PopoverContent` | `div[role=dialog]` | The portaled, positioned popup panel.          |
+| `PopoverPortal`  | —                  | Lower-level portal (`PopoverContent` uses it). |
+| `PopoverBody`    | `div`              | Optional vertical-rhythm wrapper for content.  |
+| `PopoverFooter`  | `div`              | Optional default action-row footer.            |
+
+## Example
+
+```tsx
+import {
+  Popover,
+  PopoverTrigger,
+  PopoverContent,
+  PopoverBody,
+  Button,
+} from '@acronis-platform/ui-react';
+
+<Popover>
+  <PopoverTrigger render={<Button variant="secondary">Open</Button>} />
+  <PopoverContent side="bottom" align="center">
+    <PopoverBody>
+      <h4 className="font-medium leading-none">Dimensions</h4>
+      <p className="text-sm text-muted-foreground">
+        Set the dimensions for the layer.
+      </p>
+    </PopoverBody>
+  </PopoverContent>
+</Popover>;
+```
+
+With the default action-row footer (the Figma "Popover" recipe — Cancel + Apply):
+
+```tsx
+import { PopoverFooter } from '@acronis-platform/ui-react';
+
+<PopoverContent>
+  <PopoverBody>Drop any content into this slot.</PopoverBody>
+  <PopoverFooter>
+    <Button variant="secondary">Cancel</Button>
+    <Button>Apply</Button>
+  </PopoverFooter>
+</PopoverContent>;
+```
+
+For an isolated container (e.g. a shadow root), pass `portalContainer` so the
+popup inherits that scope's styles. When portaled into a resolved
+`portalContainer`, `PopoverContent` also defaults `positionMethod` to `'fixed'`
+so the popup escapes a plain overflow-clipping ancestor (e.g. a Shadow DOM host
+with `overflow: hidden`) instead of being clipped at the container's edge.
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `open` | `boolean` | — | no | Controlled open state. Pair with the change event. |
+| `default-open` | `boolean` | `false` | no | Initial open state when uncontrolled. |
+| `side` | `'top' | 'bottom' | 'left' | 'right' | 'inline-start' | 'inline-end'` | `'bottom'` | no | On the content — which side of the trigger to render on. |
+| `align` | `'start' | 'center' | 'end'` | `'center'` | no | On the content — alignment along the chosen side. |
+| `side-offset` | `number` | `4` | no | On the content — distance in px from the trigger. |
+| `portal` | `boolean` | `true` | no | On the content — render inside a portal. Set to false for inline usage; requires a consumer-supplied ancestor Portal. When false, none of portal-container/collision-boundary/position-method's portal-dependent defaults apply — even if that ancestor Portal targets a constrained container, so pass position-method explicitly in that case. |
+| `portal-container` | `Element | ShadowRoot | null | RefObject<Element | ShadowRoot | null>` | `nearest PortalContainerProvider, or document.body` | no | On the content — portal mount point. Pass a shadow-root mount for isolated-style previews, or a constrained MFE/Shadow DOM mount point. |
+| `collision-boundary` | `Element | Element[] | Rect | 'clipping-ancestors'` | `the platform default (clipping ancestors)` | no | On the content — element/rect the popup is confined to when avoiding collisions. Left at the platform default — paired with position-method's default, that default already avoids clipping inside a constrained portal-container without needing an explicit override (see position-method). |
+| `position-method` | `'absolute' | 'fixed'` | `'fixed' whenever the popup is portaled into a resolved portal-container; otherwise the platform default ('absolute')` | no | On the content — which CSS position the popup uses. An 'absolute'-positioned popup that IS portaled into a custom portal-container is still clipped by it when it constrains overflow (e.g. a Shadow DOM host with overflow: hidden) regardless of the collision boundary, since it shares that ancestor's containing block. 'fixed' escapes a plain overflow-clipping ancestor: collision detection drops an overflow ancestor that doesn't establish its own containing block from a fixed element's clipping chain, resolving to the real, scroll-independent viewport — not one whose chain also has a transform/filter/will-change/etc. that establishes its own containing block for fixed descendants. Has no effect when not portaled. |
+| `keep-mounted` | `boolean` | `false` | no | On the content — keep the popup mounted in the DOM while closed. |
+
+## Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `open-change` | `boolean` | Fired when the popover opens or closes (React: `onOpenChange`). Payload is the new open value. |
+
+## Content slots
+
+| Slot | Description |
+|------|-------------|
+| `default` | A `trigger` plus the popover `content` (the root popup), which holds arbitrary content — text, fields, actions. |
+| `body` | Optional vertical-rhythm wrapper for the popup's main content (`PopoverBody`); a themed gap + vertical padding around whatever is passed in. |
+| `footer` | Optional default action-row footer (`PopoverFooter`) holding one or more actions (e.g. Cancel / Apply buttons), end-aligned. |
+
+## Behavior
+
+Popover shows a floating panel anchored to a trigger. It owns the open state (or
+the consumer controls it via `open`).
+
+### Opening & closing
+
+```gherkin
+Scenario: Toggling from the trigger
+  Given a closed popover
+  When the user activates the trigger
+  Then the popup opens, positioned per side/align, and receives focus
+  And open-change(true) fires
+```
+
+```gherkin
+Scenario: Dismissing
+  Given an open popover
+  When the user presses Escape, or presses outside the popup
+  Then the popover closes and open-change(false) fires
+  And focus returns to the trigger
+```
+
+### Controlled vs uncontrolled
+
+```gherkin
+Scenario: Uncontrolled with default-open
+  Given a Popover with default-open = true and no open prop
+  When it mounts
+  Then it renders open and the user can dismiss it without consumer code
+```
+
+```gherkin
+Scenario: Controlled
+  Given a Popover with a fixed open prop
+  When the user attempts to toggle it
+  Then internal state does NOT change on its own
+  And open-change fires so the consumer can update open
+```
+
+### Positioning
+
+```gherkin
+Scenario: Side and alignment
+  Given a PopoverContent with side="right" and align="start"
+  When it opens
+  Then the popup renders to the right of the trigger, aligned to its start edge
+  And it flips/shifts to stay within the viewport when space is tight
+```
+
+### Positioning inside a constrained portal container
+
+```gherkin
+Scenario: Escaping a constrained portal container's clipping
+  Given a PopoverContent portaled (default) into a resolved portal-container
+    that constrains overflow (e.g. a small or offset MFE/Shadow DOM mount)
+  When it opens
+  Then it uses 'fixed' positioning by default, with collision-boundary left at
+    the platform default ('clipping-ancestors')
+  And it is not clipped at the portal container's own edge, since 'fixed'
+    already drops that overflow-clipping ancestor from its clipping chain
+```
+
+```gherkin
+Scenario: Overriding the computed defaults
+  Given the same constrained-container setup
+  When a consumer passes an explicit collision-boundary or position-method
+  Then that value overrides the computed default
+```
+
+```gherkin
+Scenario: Non-portaled content is unaffected
+  Given a PopoverContent rendered without a portal (inline usage), even when
+    a portal-container is resolved from context
+  When it opens
+  Then it keeps the platform's default positioning and collision boundary —
+    the computed defaults only apply when this component's own `portal` prop
+    is true. If a consumer supplies their own ancestor Portal targeting a
+    constrained container, `portal={false}` content can still end up inside
+    that container's containing block and clip; pass `position-method`
+    explicitly in that case.
+```
+
+## Accessibility
+
+Popover leans on the Base UI Popover primitive for focus management, dismissal,
+and ARIA wiring.
+
+## Roles & semantics
+
+- The popup has `role="dialog"`; the trigger is associated with it via
+  `aria-haspopup` / `aria-expanded` and `aria-controls` (managed by Base UI).
+- **Name the popup** when it isn't self-evident: render a heading inside and
+  reference it (or pass `aria-label`/`aria-labelledby` on the content), so screen
+  readers announce what the popover is.
+- Unlike a modal dialog, a popover is **non-modal** by default — focus is placed
+  inside on open but background content remains available.
+
+## Keyboard
+
+- The trigger opens the popover on **Enter / Space** (it's a button).
+- On open, focus moves into the popup (first focusable, or the popup itself).
+- **Escape** closes the popover and returns focus to the trigger.
+- **Tab** moves through the popup's focusable content; focus is not trapped
+  (non-modal), so tabbing past the end returns to the page.
+
+## Screen reader
+
+- Opening announces the dialog role and its name (heading / label). Closing
+  returns the user to the trigger.
+
+## Contrast
+
+- The popup uses `--ui-text-on-surface-primary` text on `--ui-popover-container-color`
+  with a `--ui-popover-container-border-color` border — meeting WCAG AA in light
+  and dark. The default footer (`PopoverFooter`) uses `--ui-footer-default-color`
+  with a `--ui-footer-default-border-color` top border; its action buttons carry
+  their own contrast guarantees (see the Button spec).

package/dist/llms/progress-circle.md

@@ -0,0 +1,126 @@
+# ProgressCircle
+
+> A circular (radial) progress indicator — an SVG ring whose arc fills with the value and whose color tracks the level (danger / critical / warning / success), with an optional numeric or icon center. Built from the Cyber-Compliance "Compliance %" design; the sibling of the linear Progress. Design reconciliation against the Figma component master is pending.
+
+**Status:** draft · **Category:** feedback · **Since:** v0.43.0
+
+## Import
+
+```tsx
+import { ProgressCircle } from '@acronis-platform/ui-react'
+```
+
+## Quick example
+
+```tsx
+<ProgressCircle value={75} max={100} size="sm" showValue />
+```
+
+A circular (radial) progress indicator — an SVG ring whose arc fills with the
+value and whose color tracks the level.
+
+> **Status: draft (design-pending v1).** Built from the Cyber-Compliance
+> "Compliance %" design and the Vue kit's `AvProgressRadial`. Reuses the shared
+> status colors — no `--ui-progress-circle-*` tier. Reconcile with
+> `/figma-component ProgressCircle <url> --update` once the component master node
+> is confirmed.
+
+## When to use
+
+- A compact, at-a-glance completion/score in a table cell, card, or widget
+  (e.g. compliance %, usage, health).
+
+## When not to use
+
+- A full-width determinate bar — use the linear `Progress`.
+- An indeterminate "busy" state — use `Loading`.
+
+## Example
+
+```tsx
+import { ProgressCircle } from '@acronis-platform/ui-react';
+
+<ProgressCircle value={75} size="md" showValue />
+<ProgressCircle value={25} size="sm" />           {/* arc auto-colors to danger */}
+<ProgressCircle value={100} size="lg" showIcon /> {/* success check in center */}
+```
+
+In a table cell, compose the ring with an external label:
+
+```tsx
+<div className="flex items-center gap-2">
+  <ProgressCircle value={81} size="sm" />
+  <span className="text-sm">81%</span>
+</div>
+```
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `value` | `number` | `0` | no | Current progress, clamped to [0, max]. |
+| `max` | `number` | `100` | no | Value representing full completion. |
+| `size` | `'tiny' | 'sm' | 'md' | 'lg'` | `'sm'` | no | Ring diameter + stroke width. |
+| `status` | `'brand' | 'danger' | 'critical' | 'warning' | 'success'` | — | no | Arc color level. `brand` is a single neutral color; the rest are score levels. Omit to derive the level from value/max by thresholds (≈ <40% danger, <60% critical, <80% warning, else success — confirm with design). |
+| `showValue` | `boolean` | `false` | no | Show the rounded percentage in the center. |
+| `showIcon` | `boolean` | `false` | no | Show a status icon in the center (priority over showValue). |
+
+## Content slots
+
+| Slot | Description |
+|------|-------------|
+| `children` | Custom center content (priority over icon / value). |
+
+## Behavior
+
+A circular progress indicator. State is driven by `value`; there is no internal
+state.
+
+```gherkin
+Scenario: Fill
+  Given a ProgressCircle with value={75}
+  Then the arc fills 75% of the ring
+  And aria-valuenow is 75
+```
+
+```gherkin
+Scenario: Status by level
+  Given no explicit status
+  Then the arc color is derived from value/max (danger → critical → warning → success)
+```
+
+```gherkin
+Scenario: Status override
+  Given status="danger" with value={90}
+  Then the arc is the danger color regardless of value
+```
+
+```gherkin
+Scenario: Center content
+  Given showValue, the center shows the rounded percentage
+  Given showIcon, the center shows a status icon (priority over the percentage)
+  Given children, they render in the center (priority over icon / percentage)
+```
+
+```gherkin
+Scenario: Custom range
+  Given value={5} and max={10}
+  Then the arc fills 50% and aria-valuemax is 10
+```
+
+## Accessibility
+
+- The root is `role="progressbar"` (Base UI Progress.Root) with
+  `aria-valuenow`/`aria-valuemin`/`aria-valuemax`. The SVG is `aria-hidden`; the
+  value semantics come from the root.
+- Give it an accessible name via `aria-label`/`aria-labelledby` (e.g. "Compliance")
+  so assistive tech announces what is progressing.
+- Status is conveyed by the arc color **and** the value/icon — never color alone.
+  Keep the meaningful value visible (`showValue`) or labelled when color encodes
+  status.
+
+## Contrast
+
+The arc uses `--ui-text-on-status-*` over the `--ui-border-on-surface-border`
+track, and the center label uses `--ui-text-on-surface-primary` — all meeting the
+relevant contrast in light and dark.