# DonutChart

Das DonutChart stellt Verteilungen und Anteile als Ring dar.

```tsx
import { DonutChart } from "@mittwald/flow-react-components";

<DonutChart value={30} aria-label="Auslastung" />
```

---

# Best Practices

- Kombiniere die Status-Farben gezielt, um Zustände hervorzuheben. Wechsle etwa
  bei hoher Speicherplatzauslastung auf Warning oder Danger.
- Mach jede Segmentfarbe eindeutig unterscheidbar. Nutze dafür die
  [Categorical Colors](/02-foundations/01-design/02-colors#categorical-color).
- Begrenze die Segmente auf höchstens sechs. Mehr Segmente beeinträchtigen die
  Lesbarkeit stark.
- Sortiere die Segmente nach Größe. Das größte beginnt auf der 12-Uhr-Position,
  die weiteren folgen im Uhrzeigersinn absteigend.

---

# Sizes

Die Size des DonutCharts kann Medium oder Large sein. Medium ist dabei die
Standardgröße.

```tsx
import { DonutChart } from "@mittwald/flow-react-components";

<>
  <DonutChart value={30} aria-label="Auslastung" />
  <DonutChart value={30} aria-label="Auslastung" size="l" />
</>
```

---

# Status

Je nach Anwendungsfall stehen vier Status-Farben zur Auswahl: **Info**,
**Success**, **Warning** und **Danger**.

```tsx
import { DonutChart } from "@mittwald/flow-react-components";

<>
  <DonutChart
    value={30}
    status="success"
    aria-label="Auslastung"
  />
  <DonutChart value={30} aria-label="Auslastung" />
  <DonutChart
    value={80}
    status="warning"
    aria-label="Auslastung"
  />
  <DonutChart
    value={95}
    status="danger"
    aria-label="Auslastung"
  />
</>
```

---

# Mit Unit

Im Default wird das DonutChart immer mit Prozentangabe angezeigt. Über das
Property `formatOptions` können aber auch andere Einheiten gewählt werden (s.
[Intl.NumberFormat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat)).

## Gigabyte

```tsx
import { DonutChart } from "@mittwald/flow-react-components";

<DonutChart
  aria-label="Speicherplatz"
  formatOptions={{ style: "unit", unit: "gigabyte" }}
  maxValue={50}
  value={12}
/>
```

## Dezimalzahl

```tsx
import { DonutChart } from "@mittwald/flow-react-components";

<DonutChart
  aria-label="Performance"
  formatOptions={{ style: "decimal" }}
  maxValue={200}
  value={135}
/>
```

---

# Mit alternativem Text

Über die `children` kann der Text innerhalb des DonutCharts überschrieben
werden.

```tsx
import { DonutChart } from "@mittwald/flow-react-components";

<DonutChart
  value={300}
  maxValue={600}
  aria-label="Speicherplatz"
>
  <strong>300</strong>
  <small>GB</small>
</DonutChart>
```

---

# Segmente

Die Anzeige des DonutCharts kann über das `segments` Property um einzelne
Abschnitte ergänzt werden. Der `value` ergibt sich in diesem Fall aus der Summe
der Werte der einzelnen Segmente. Um die einzelnen Werte näher zu erläutern wird
automatisch die `Legend` Component angezeigt. Über das `showLegend` Property
kann diese ein- und ausgeblendet werden. Die Position der Legende kann über das
Property `legendPosition` bestimmt werden.

Die Farben der Segmente werden automatisch festgelegt, können aber über das
`color`-Property, mit
[Categorical Colors](/02-foundations/01-design/02-colors#categorical-color) oder
eigenen Colors überschrieben werden. Beim Überschreiben muss darauf geachtet
werden, dass nebeneinander liegende Farben weiterhin einen ausreichenden
Kontrast zueinander haben.

```tsx
import { DonutChart } from "@mittwald/flow-react-components";

<DonutChart
  aria-label="Items"
  segments={[
    { title: "Item 1", value: 28 },
    { title: "Item 2", value: 24 },
    { title: "Item 3", value: 20 },
    { title: "Item 4", value: 10 },
    { title: "Item 5", value: 12 },
    { title: "Item 6", value: 6 },
  ]}
/>
```

---

# Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `status` | `"info" \| "success" \| "warning" \| "danger"` | - | The status the donut chart is colored by. |
| `size` | `"m" \| "l"` | `"m"` | The size variant of the donut chart. |
| `segments` | `DonutChartSegment[]` | - | Divides the fill of the donut chart into segments |
| `showLegend` | `boolean` | `: true` | Whether the legend component is shown when segments are used. |
| `legendPosition` | `"bottom" \| "top" \| "left" \| "right"` | `"right"` | The position of the legend. |
| `id` | `string` | - | The element's unique identifier. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id). |
| `translate` | `"yes" \| "no"` | - | - |
| `className` | `ClassNameOrFunction<ProgressBarRenderProps>` | `'react-aria-ProgressBar'` | The CSS [className](https://developer.mozilla.org/en-US/docs/Web/API/Element/className) for the element. A function may be provided to compute the class based on component state. |
| `style` | `StyleOrFunction<TooltipRenderProps>` | - | The inline [style](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/style) for the element. A function may be provided to compute the style based on component state. |
| `render` | `DOMRenderFunction<"div", TooltipRenderProps>` | - | Overrides the default DOM element with a custom render function. This allows rendering existing components with built-in styles and behaviors such as router links, animation libraries, and pre-styled components. Requirements: - You must render the expected element type (e.g. if `<button>` is expected, you cannot render an `<a>`). - Only a single root DOM element can be rendered (no fragments). - You must pass through props and ref to the underlying DOM element, merging with your own prop as appropriate. |
| `dir` | `string` | - | - |
| `lang` | `string` | - | - |
| `hidden` | `boolean` | - | - |
| `inert` | `boolean` | - | - |
| `minValue` | `number` | `0` | The smallest value allowed for the input. |
| `maxValue` | `number` | `100` | The largest value allowed for the input. |
| `value` | `number` | `0` | The current value (controlled). |
| `slot` | `string` | - | A slot name for the component. Slots allow the component to receive props from a parent component. An explicit `null` value indicates that the local props completely override all props received from a parent. |
| `formatOptions` | `NumberFormatOptions` | `{ style: 'percent' }` | The display format of the value label. |
| `isIndeterminate` | `boolean` | - | Whether presentation is indeterminate when progress isn't known. |
| `children` | `ReactNode` | - | - |

### Events

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `onClick` | `MouseEventHandler<HTMLDivElement>` | - | - |
| `onClickCapture` | `MouseEventHandler<HTMLDivElement>` | - | - |
| `onAuxClick` | `MouseEventHandler<HTMLDivElement>` | - | - |
| `onAuxClickCapture` | `MouseEventHandler<HTMLDivElement>` | - | - |
| `onContextMenu` | `MouseEventHandler<HTMLDivElement>` | - | - |
| `onContextMenuCapture` | `MouseEventHandler<HTMLDivElement>` | - | - |
| `onDoubleClick` | `MouseEventHandler<HTMLDivElement>` | - | - |
| `onDoubleClickCapture` | `MouseEventHandler<HTMLDivElement>` | - | - |
| `onMouseDown` | `MouseEventHandler<HTMLDivElement>` | - | - |
| `onMouseDownCapture` | `MouseEventHandler<HTMLDivElement>` | - | - |
| `onMouseEnter` | `MouseEventHandler<HTMLDivElement>` | - | - |
| `onMouseLeave` | `MouseEventHandler<HTMLDivElement>` | - | - |
| `onMouseMove` | `MouseEventHandler<HTMLDivElement>` | - | - |
| `onMouseMoveCapture` | `MouseEventHandler<HTMLDivElement>` | - | - |
| `onMouseOut` | `MouseEventHandler<HTMLDivElement>` | - | - |
| `onMouseOutCapture` | `MouseEventHandler<HTMLDivElement>` | - | - |
| `onMouseOver` | `MouseEventHandler<HTMLDivElement>` | - | - |
| `onMouseOverCapture` | `MouseEventHandler<HTMLDivElement>` | - | - |
| `onMouseUp` | `MouseEventHandler<HTMLDivElement>` | - | - |
| `onMouseUpCapture` | `MouseEventHandler<HTMLDivElement>` | - | - |
| `onTouchCancel` | `TouchEventHandler<HTMLDivElement>` | - | - |
| `onTouchCancelCapture` | `TouchEventHandler<HTMLDivElement>` | - | - |
| `onTouchEnd` | `TouchEventHandler<HTMLDivElement>` | - | - |
| `onTouchEndCapture` | `TouchEventHandler<HTMLDivElement>` | - | - |
| `onTouchMove` | `TouchEventHandler<HTMLDivElement>` | - | - |
| `onTouchMoveCapture` | `TouchEventHandler<HTMLDivElement>` | - | - |
| `onTouchStart` | `TouchEventHandler<HTMLDivElement>` | - | - |
| `onTouchStartCapture` | `TouchEventHandler<HTMLDivElement>` | - | - |
| `onPointerDown` | `PointerEventHandler<HTMLDivElement>` | - | - |
| `onPointerDownCapture` | `PointerEventHandler<HTMLDivElement>` | - | - |
| `onPointerMove` | `PointerEventHandler<HTMLDivElement>` | - | - |
| `onPointerMoveCapture` | `PointerEventHandler<HTMLDivElement>` | - | - |
| `onPointerUp` | `PointerEventHandler<HTMLDivElement>` | - | - |
| `onPointerUpCapture` | `PointerEventHandler<HTMLDivElement>` | - | - |
| `onPointerCancel` | `PointerEventHandler<HTMLDivElement>` | - | - |
| `onPointerCancelCapture` | `PointerEventHandler<HTMLDivElement>` | - | - |
| `onPointerEnter` | `PointerEventHandler<HTMLDivElement>` | - | - |
| `onPointerLeave` | `PointerEventHandler<HTMLDivElement>` | - | - |
| `onPointerOver` | `PointerEventHandler<HTMLDivElement>` | - | - |
| `onPointerOverCapture` | `PointerEventHandler<HTMLDivElement>` | - | - |
| `onPointerOut` | `PointerEventHandler<HTMLDivElement>` | - | - |
| `onPointerOutCapture` | `PointerEventHandler<HTMLDivElement>` | - | - |
| `onGotPointerCapture` | `PointerEventHandler<HTMLDivElement>` | - | - |
| `onGotPointerCaptureCapture` | `PointerEventHandler<HTMLDivElement>` | - | - |
| `onLostPointerCapture` | `PointerEventHandler<HTMLDivElement>` | - | - |
| `onLostPointerCaptureCapture` | `PointerEventHandler<HTMLDivElement>` | - | - |
| `onScroll` | `UIEventHandler<HTMLDivElement>` | - | - |
| `onScrollCapture` | `UIEventHandler<HTMLDivElement>` | - | - |
| `onWheel` | `WheelEventHandler<HTMLDivElement>` | - | - |
| `onWheelCapture` | `WheelEventHandler<HTMLDivElement>` | - | - |
| `onAnimationStart` | `AnimationEventHandler<HTMLDivElement>` | - | - |
| `onAnimationStartCapture` | `AnimationEventHandler<HTMLDivElement>` | - | - |
| `onAnimationEnd` | `AnimationEventHandler<HTMLDivElement>` | - | - |
| `onAnimationEndCapture` | `AnimationEventHandler<HTMLDivElement>` | - | - |
| `onAnimationIteration` | `AnimationEventHandler<HTMLDivElement>` | - | - |
| `onAnimationIterationCapture` | `AnimationEventHandler<HTMLDivElement>` | - | - |
| `onTransitionCancel` | `TransitionEventHandler<HTMLDivElement>` | - | - |
| `onTransitionCancelCapture` | `TransitionEventHandler<HTMLDivElement>` | - | - |
| `onTransitionEnd` | `TransitionEventHandler<HTMLDivElement>` | - | - |
| `onTransitionEndCapture` | `TransitionEventHandler<HTMLDivElement>` | - | - |
| `onTransitionRun` | `TransitionEventHandler<HTMLDivElement>` | - | - |
| `onTransitionRunCapture` | `TransitionEventHandler<HTMLDivElement>` | - | - |
| `onTransitionStart` | `TransitionEventHandler<HTMLDivElement>` | - | - |
| `onTransitionStartCapture` | `TransitionEventHandler<HTMLDivElement>` | - | - |

### Accessibility

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `aria-label` | `string` | - | Defines a string value that labels the current element. |
| `aria-labelledby` | `string` | - | Identifies the element (or elements) that labels the current element. |
| `aria-describedby` | `string` | - | Identifies the element (or elements) that describes the object. |
| `aria-details` | `string` | - | Identifies the element (or elements) that provide a detailed, extended description for the object. |