# ASChartDonut

ASChartDonut displays one to four concentric percentage arcs. Each ring has its own value; the values do not need to add up to 100. The chart retains a 270-degree arc with an opening at the bottom.

```tsx
import { ASChartDonut, ComponentSize } from '@eleventheye/asui';

<ASChartDonut
  value={75}
  secondaryValue={50}
  primaryColor="#175cd3"
  secondaryColor="#ffd321"
  size={ComponentSize.Medium}
  donutSize="240px"
  donutLabel="75%"
  donutSubLabel="Completed"
/>
```

## Values and labels

- `value` defaults to zero. Values are clamped to 0–100; non-finite primary values render zero.
- `secondaryValue`, `tertiaryValue`, and `quaternaryValue` default to `-1`. Negative or non-finite values hide that ring. Zero retains an empty ring and its track space.
- Optional rings retain their positions when an earlier ring is absent. The shared track spans through the innermost enabled ring.
- `donutLabel` and `donutSubLabel` accept React nodes, including numeric zero. The sublabel is positioned relative to the main label and is displayed only when `donutLabel` is provided.

## Size and layout

`size` controls ring thickness, spacing, and label typography. Small, Medium (default), and Large use 8, 12, and 16 SVG units of ring thickness respectively, inside a fixed `240 × 240` viewBox. These are not CSS pixel sizes: the rendered thickness scales with the chart.

`donutSize` overrides the theme's `diameter` (default `200px`). It sets the SVG's width; its square viewBox determines the height. `className` and `style` customize the outer layout. Percentage widths resolve against the containing block. Labels remain single-line, so allow enough room for their text and any custom font sizes.

## Themes and data colors

The chart inherits the nearest `ASThemeProvider`, or the default yellow theme. Use `theme` for a complete replacement or `themeOverrides` for a partial local change; do not supply both.

Appearance comes from `components.chartdonut`. The yellow/classic preset retains the colored arcs, gray shared track, and text shadows. The blue/neutral preset uses the project accent for the primary arc, flat track colors, and text without shadows. Additional arc colors remain a distinct data palette and can be overridden independently.

`primaryColor`, `secondaryColor`, `tertiaryColor`, and `quaternaryColor` override only their data arcs. They do not recolor the tracks or labels. This lets consumers supply team or category colors without replacing the project theme. Complete-theme `chartdonut` settings remain supported through theme adaptation.

```tsx
<ASChartDonut
  value={75}
  donutLabel="75%"
  themeOverrides={{
    components: {
      chartdonut: {
        innerTrackColor: '#ede9fe',
        outerTrackColor: '#c4b5fd',
        labelColor: '#5b21b6',
        primaryColor: '#7c3aed',
        sizes: { ASMedium: { labelShadow: 'none' } },
      },
    },
  }}
/>
```

See the [donut theme reference](./theme-reference.md#donut-chart--componentschartdonut) for all properties and defaults, including per-size label styles and separate track colors.

## Motion and accessibility

Value changes transition the arc's dash offset. Primary and additional rings have independently configurable durations, with shared easing and delay. Reduced-motion preferences disable these transitions.

Provide meaningful labels and nearby text that explains each ring and its value; color alone should not carry the meaning. The component is a visual chart, not an interactive control or a progressbar with task semantics. It does not supply a legend, data table, keyboard interactions, or an accessible name for each ring. Applications should provide an equivalent textual summary, particularly for multi-ring charts.