# Breadcrumb

Eine Breadcrumb ist ein Navigationselement, das Usern Orientierung bietet, indem es die aktuelle Position sowie die übergeordneten Navigationsebenen anzeigt.

## Overview

# Playground

Verwende `<Breadcrumb />`, um eine Breadcrumb darzustellen. Die einzelnen
Navigationselemente werden dabei mit `<Link />` innerhalb der Component
erstellt.

```tsx
import {
  Breadcrumb,
  Link,
} from "@mittwald/flow-react-components";

<Breadcrumb>
  <Link href="#">Projekte</Link>
  <Link href="#">Apps</Link>
  <Link href="#">Meine App</Link>
</Breadcrumb>
```

---

# Color

Light und Dark sind Alternativen zur Standard-Color, falls diese auf farbigen
oder dekorativen Hintergründen keinen ausreichenden Kontrast bietet.

```tsx
import {
  Breadcrumb,
  Link,
} from "@mittwald/flow-react-components";

<Breadcrumb color="light">
  <Link href="#">Projekte</Link>
  <Link href="#">Apps</Link>
  <Link href="#">Meine App</Link>
</Breadcrumb>
```

```tsx
import {
  Breadcrumb,
  Link,
} from "@mittwald/flow-react-components";

<Breadcrumb color="dark">
  <Link href="#">Projekte</Link>
  <Link href="#">Apps</Link>
  <Link href="#">Meine App</Link>
</Breadcrumb>
```

**Light:** Verwende die Light-Color, bei dunklen Hintergründen mit einem HSL
Lightness-Wert von weniger als 50.

**Dark:** Verwende die Dark-Color, bei hellen, farbigen Hintergründen mit einem
HSL Lightness-Wert von größer als 50.


## Develop

# Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `color` | `"default" \| "dark" \| "light" \| "dark-static" \| "light-static"` | `"default"` | The color of the breadcrumb. |
| `size` | `"s" \| "m"` | `"m"` | The size of the element. |
| `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` | `string` | `'react-aria-Breadcrumbs'` | The CSS [className](https://developer.mozilla.org/en-US/docs/Web/API/Element/className) for the element. |
| `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` | - | - |
| `isDisabled` | `boolean` | - | Whether the breadcrumbs are disabled. |
| `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. |
| `items` | `Iterable<object>` | - | Item objects in the collection. |
| `dependencies` | `readonly any[]` | - | Values that should invalidate the item cache when using dynamic collections. |
| `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>` | - | - |
| `onAction` | `((key: Key) => void)` | - | Handler that is called when a breadcrumb is clicked. |

### 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. |


## Guidelines

# Grundlagen

## Best practices

Achte bei der Verwendung einer Breadcrumb darauf, dass ...

- sie im oberen linken Bereich des Content-Bereichs positioniert ist.
- ein sinnvoller Startpunkt gewählt wird. Im mStudio bezieht sich die Breadcrumb
  beispielsweise auf die Navigation innerhalb eines Projekts.
- sie eine lineare Hierarchie abbildet (z. B. „Projekt > Apps > App“).
- die Anzahl der angezeigten Hierarchieebenen überschaubar bleibt. Als Richtwert
  sind maximal 5 Ebenen erlaubt.
- innerhalb der Breadcrumb generische Bezeichnungen verwendet werden (z. B.
  „App“ statt eines konkreten App-Namens). Individuelle oder dynamisch
  generierte Namen können stark in ihrer Länge variieren und die Breadcrumb
  unnötig verlängern. Generische Begriffe sorgen für eine stabile, gut lesbare
  und visuell konsistente Navigation.

## Verwendung

Verwende eine Breadcrumb, um ...

- dem User die aktuelle Position innerhalb der Navigationshierarchie sichtbar zu
  machen.
- eine Möglichkeit zu bieten, leicht zu vorherigen Seiten der
  Navigationsstruktur zurückzukehren.
- eine ergänzende, schnelle Navigationsoption zusätzlich zur Hauptnavigation
  bereitzustellen.
- Usern bei Seiten mit einer komplexen Seitenhierarchie Orientierung zu geben.