# Feedback

Feedback components communicate system state, process outcomes, and loading status to users.

## Decision Tree

```
Communicating state to user?
├── Persistent inline message (always visible)?
│   ├── Error, warning, success, info → Alert
│   └── Object/workflow status → Status
├── Transient notification (auto-dismisses)?
│   └── Background task result → Toast
├── Empty / no-results state?
│   └── InfoMessage
├── Error state?
│   └── ErrorMessage
├── Loading state?
│   ├── Full page loading → LoadingPageIndicator
│   ├── Section loading → LoadingSpinner
│   └── Layout placeholder → SkeletonLoader
├── Multi-step progress? → Stepper
└── Semantic text highlight? → Highlight
```

---

## Alert

Persistent inline contextual message. Always visible until dismissed.

```tsx
import { Alert } from '@theorchard/suite-components';
```

### Variants

| `variant` | Colour | When to use |
|---|---|---|
| `'error'` | Red | Blocking errors the user must address |
| `'warn'` | Orange | Non-blocking warnings requiring attention |
| `'success'` | Green | Completed action confirmation |
| `'information'` | Blue | Neutral info the user should know |
| `'flag'` | Red (flag icon) | High-priority system alerts |

### Key Props

| Prop | Type | Description |
|---|---|---|
| `variant` | string | required — see table above |
| `text` | `string \| ReactNode` | Message body (required) |
| `title` | string | Optional heading — enables `expandable` |
| `dismissible` | boolean | Shows a close button |
| `onDismiss` | function | Override dismiss behaviour |
| `button` | object | Optional CTA button `{ text, onClick }` |
| `link` | object | Optional link `{ text, to }` |
| `expandable` | boolean | Collapses body — requires `title` |
| `defaultExpanded` | boolean | Initial expanded state (default `true`) |

### Sub-components

| Sub-component | Usage |
|---|---|
| `Alert.Container` | Auto-fitting collapsible container for stacking multiple alerts |

### Example

```tsx
<Alert
  variant="warn"
  title="Unverified territories"
  text="3 territories have not been verified. Please review before releasing."
  dismissible
  button={{ text: 'Review now', onClick: (dismiss) => { navigate('/territories'); dismiss(); } }}
/>
```

---

## Toast / useToast

Transient floating notification for async task outcomes. **Always use the `useToast` hook** — do not render `<Toast>` directly.

```tsx
import { useToast } from '@theorchard/suite-components';

const MyComponent = () => {
  const { addToast } = useToast();

  const handleSave = async () => {
    await save();
    addToast({ variant: 'success', text: 'Changes saved.' });
  };
};
```

The `ToastProvider` must be present in the tree (added once at app root):

```tsx
import { ToastProvider } from '@theorchard/suite-components';

<ToastProvider>
  <App />
</ToastProvider>
```

### Toast variants

| variant | When to use |
|---|---|
| `'success'` | Action completed successfully |
| `'error'` | Background task failed (non-blocking) |
| `'information'` | Neutral status update |
| `'warn'` | Non-critical warning |

Use when there is no other obvious visual confirmation of a background task (e.g. save succeeded, export started). Do NOT use `Toast` for errors that require user action — use `Alert` instead.

---

## ErrorMessage

Notification for error states with recovery guidance.

```tsx
import { ErrorMessage } from '@theorchard/suite-components';
```

Use on a page or section when data fails to load or an error prevents normal operation. Pair with an `Illustration` if available.

---

## InfoMessage

Notification for empty-state or no-results-found conditions.

```tsx
import { InfoMessage } from '@theorchard/suite-components';
```

Use to explain why a list or page is empty and offer a next action. Pair with an `Illustration`.

---

## Status

Coloured indicator dot or icon with label text showing object or workflow state.

```tsx
import { Status } from '@theorchard/suite-components';
```

### Variants

| `variant` | Colour | Example usage |
|---|---|---|
| `'success'` | Green | Published, Active, Approved |
| `'error'` | Red | Failed, Rejected |
| `'warning'` | Orange | Pending review, Expiring |
| `'info'` | Blue | Processing, In progress |
| `'revision'` | Purple | Draft, Under revision |
| `'neutral'` | Gray | Inactive, Archived |
| `'loading'` | Spinner | Real-time processing |

### Key Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `variant` | string | required | Semantic colour variant |
| `text` | string | required | Status label text |
| `filled` | boolean | — | Shows filled dot instead of outline circle |
| `size` | `'small' \| 'medium'` | `'medium'` | Size |
| `layoutVariant` | `'inline' \| 'table'` | `'inline'` | `'table'` stacks the subtext below |
| `children` | ReactNode | — | Subtext below/beside status label |

### Example

```tsx
<Status variant="success" text="Published" />
<Status variant="warning" text="Pending" filled>Review required</Status>
```

---

## Highlight

Adds a semantic background colour to inline text.

```tsx
import { Highlight } from '@theorchard/suite-components';
```

Use to draw attention to a keyword, value, or term within a sentence.

---

## LoadingSpinner

Spinning ring indicator for section-level loading.

```tsx
import { LoadingSpinner } from '@theorchard/suite-components';
```

### Key Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `show` | boolean | — | Controls visibility |
| `size` | number | — | Diameter in px |

Use `LoadingSpinner` inside a card, section, or table cell. For full-page loading use `LoadingPageIndicator`.

---

## LoadingPageIndicator

Animated illustration placeholder for full-page loading states.

```tsx
import { LoadingPageIndicator } from '@theorchard/suite-components';
```

Renders as a full-page animated placeholder. Use only when the entire page is loading.

---

## SkeletonLoader

Wireframe layout placeholder while content is being fetched.

```tsx
import { SkeletonLoader } from '@theorchard/suite-components';
```

Use to show the shape of content before it loads (lists, cards, tables). Prefer `SkeletonLoader` over `LoadingSpinner` when the layout is known.

---

## Stepper

Visual progress indicator for multi-step processes.

```tsx
import { Stepper } from '@theorchard/suite-components';
```

Use at the top of multi-step forms or wizards to orient users within the flow.

## Common Mistakes

- Do NOT use `Toast` for errors requiring user action — use `Alert` with `variant="error"`.
- Do NOT use `LoadingPageIndicator` inside a section — use `LoadingSpinner` or `SkeletonLoader`.
- MUST always provide `text` to `Status` — the variant colour alone is not accessible.
- Do NOT use more than one `variant="error"` alert stacked without wrapping in `Alert.Container`.