# Feedback and States

Alerts, toasts, badges, chips, progress, loading skeletons, data states and error boundaries. Exact props: `widgets-get-component-props`.

---

## DAlert

An inline message. The text goes as children; `color` is `success` (default), `danger`, `warning` or `info`:

```tsx
<DAlert color="danger">
  <p className="fw-bold mb-2">{t('config.missing.title')}</p>
  <p className="mb-2">{t('config.missing.description')}</p>
</DAlert>
```

| Prop | Use |
|------|-----|
| `role` | `alert` (default) interrupts the screen reader, for critical errors; `status` announces without interrupting, for dynamic non-critical messages; `none` renders no role, for static content already on screen |
| `showIcon`, `icon` | The leading icon is shown by default, mapped to `color`; `icon` replaces it and `showIcon={false}` removes it |
| `showClose`, `onClose`, `closeAriaLabel` | A close button |

## Toasts: DToastContainer and useDToast

A toast is dispatched with `useDToast` and rendered by a `DToastContainer`, which must be in the tree:

```tsx
<DToastContainer position="top-right" />
```

```tsx
const { toast } = useDToast();

toast({ title: t('transfer.done'), color: 'success' });
```

`toast(data, options)` takes a `ToastData` object (`title`, and optionally `description`, `icon`, `color`, `role`, `timestamp`, `closeAriaLabel`) and optional `DToastOptions` (`id`, `duration`, `position`). With `description` the toast has a header and a body; without it, a single row. `DToast` (with `DToast.Header` and `DToast.Body`) is the component a toast renders.

## DBadge

A short label. The text goes in `text`:

```tsx
<DBadge text={t('status.active')} color="success" soft />
```

`soft` uses a light background; `rounded` uses pill corners; `size` is `sm` or `lg`; `iconStart`/`iconEnd` add an icon.

## DChip

A removable tag. The text goes in `text`:

```tsx
<DChip text={filter.label} showClose onClose={() => removeFilter(filter.id)} />
```

## DProgress

```tsx
<DProgress currentValue={uploaded} maxValue={total} ariaLabel={t('upload.progress')} />
```

`currentValue` is required; `minValue` and `maxValue` default to 0 and 100. Give it an accessible name with `ariaLabel` or `ariaLabelledBy`.

## DSkeleton

A loading placeholder that keeps the layout of the content. Compose it with its subcomponents:

```tsx
<DSkeleton ariaLabel={t('states.loading')} animation="wave">
  <DSkeleton.Circle size={40} />
  <DSkeleton.Text lines={2} />
</DSkeleton>
```

| Part | Props |
|------|-------|
| `DSkeleton` | `animation` (`glow`, `wave`, `none`), `direction` (`vertical` by default, or `horizontal`), `gap` (numbers are pixels), `items` (repeats the children that many times), `ariaLabel` |
| `DSkeleton.Text` | `lines` (3 by default), `widths` (one per line), `lastLineWidth`, `size` (`xs`, `sm`, `lg`) |
| `DSkeleton.Block` | `width` (100% by default), `height` (1em by default), `rounded` |
| `DSkeleton.Circle` | `size`, the diameter (40 px by default; numbers are pixels) |

Check the accepted values of each part with `widgets-get-component-props` (for example `DSkeleton.Text`).

## DDataStateWrapper

Renders loading, error, empty or the data, in that order of precedence, and passes the data to its children. From the template's reference feature:

```tsx
<DDataStateWrapper
  isLoading={isLoading}
  isError={isError}
  data={data}
  onRetry={retry}
  renderLoading={<LoadingState variant="list" items={5} />}
  renderEmpty={<EmptyState message={t('entities.list.empty')} />}
  renderError={<ErrorState message={t('entities.list.error')} onRetry={retry} />}
>
  {(entities) => (
    <DListGroup ariaLabel={t('entities.list.title')}>
      {entities.map((entity) => (
        <DListGroup.Item key={entity.id}>{entity.name}</DListGroup.Item>
      ))}
    </DListGroup>
  )}
</DDataStateWrapper>
```

`data` can be a list (empty when it has no items) or a single resource (empty when `null` or `undefined`). States in detail: `modyo://docs/widgets/patterns-data-states`.

## DErrorBoundary

Catches render errors in its subtree and shows a fallback with a retry. The template re-exports it as `ErrorBoundary` from `src/shared/ui` and wraps the page with it in `src/app/App.tsx`. `messages` (`error`, `retry`) customizes the default texts; `fallback` replaces the fallback; `onError` and `onReset` observe it. From a component inside it, `useErrorBoundary` shows or resets the boundary (`modyo://docs/widgets/components-hooks`).

---

## Common mistakes

| Wrong | Right |
|-------|-------|
| `<DAlert variant="danger" text="…">` | `<DAlert color="danger">…</DAlert>` |
| `<DBadge theme="success">` | `<DBadge color="success" text="…" />` |
| `<DChip label="…">` | `<DChip text="…" />` |
| `useDToast` without a `DToastContainer` in the tree | Render `DToastContainer` once |
| A spinner component | `DSkeleton`, or `loading` on the button that started the action |
