# Overlays

Overlays are floating or sliding containers that interrupt or augment the current page context.

## Decision Tree

```
Need to interrupt the user?
├── Confirmation or important action? → Modal
├── Complex sub-process? → FullscreenModal
├── Tertiary / contextual action? → Sidecar
└── Secondary info for a UI element?
    ├── Triggered on click? → Popover
    └── Triggered on hover?
        ├── Short label / description → Tooltip
        └── Help text for a field → HelpTooltip
```

---

## Modal

Blocking dialog for confirmations and sub-processes connected to the current page.

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

### Key Props

| Prop | Type | Description |
|---|---|---|
| `show` | boolean | Controls visibility |
| `onHide` | function | Called when modal requests close |
| `title` | string | Modal header title |
| `size` | `'sm' \| 'lg' \| 'xl'` | Modal width |
| `footer` | ReactNode | Footer content (typically buttons) |
| `backdrop` | `boolean \| 'static'` | Backdrop behaviour (`'static'` prevents close on backdrop click) |

### Example

```tsx
<Modal
  show={isOpen}
  onHide={() => setOpen(false)}
  title="Confirm deletion"
  footer={
    <>
      <Button variant="secondary" onClick={() => setOpen(false)}>Cancel</Button>
      <Button variant="danger" onClick={handleDelete}>Delete</Button>
    </>
  }
>
  <p>This action cannot be undone.</p>
</Modal>
```

### Rules

- MUST include a close mechanism (onHide + a cancel button).
- MUST NOT nest a `Modal` inside another `Modal` — use `FullscreenModal` for complex sub-flows.
- Primary action button goes last in the footer (rightmost).

---

## FullscreenModal

Full-viewport modal for complex sub-processes that would be too large for a standard modal.

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

Use when the sub-process has multiple steps or requires substantial content area. For simple confirmations use `Modal`.

---

## Sidecar

Slide-in panel for tertiary actions or simple contextual sub-processes.

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

Sidecars are overlays (float over content). They differ from `Sidebar`, which is inline and pushes content.

### When to use Sidecar vs Modal

| Sidecar | Modal |
|---|---|
| Contextual to page content — user can still see the parent | Requires full attention — blocks the page |
| Tertiary action / detail view | Confirmation or important action |
| Keeps parent context visible | Parent is dimmed |

---

## Popover

Click-triggered floating container for secondary information or actions.

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

### Key Props

| Prop | Type | Description |
|---|---|---|
| `trigger` | ReactNode | Element that triggers the popover |
| `placement` | string | Placement hint (`'top'`, `'bottom'`, `'left'`, `'right'`) |
| `title` | string | Optional popover header |

Use `Popover` for richer content (multiple lines, actions). Use `Tooltip` for a single short label.

---

## Tooltip

Hover-triggered floating label for describing a UI element.

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

### Key Props

| Prop | Type | Description |
|---|---|---|
| `message` | string | Tooltip text |
| `id` | string | Required unique id for accessibility |
| `placement` | string | Placement hint |

### Example

```tsx
<Tooltip id="save-tooltip" message="Save changes">
  <GlyphButton name="save" />
</Tooltip>
```

Keep tooltip text to a single short phrase. For multi-line content use `Popover`.

---

## HelpTooltip

Pre-composed help icon + tooltip for form field context.

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

### Example

```tsx
<HelpTooltip message="ISRC codes are 12-character identifiers assigned to recordings." />
```

Use `HelpTooltip` inside `Label`'s `helpMessage` prop rather than manually composing `GlyphIcon` + `Tooltip`.

## Common Mistakes

- Do NOT use `Tooltip` for interactive content — use `Popover`.
- Do NOT nest modals — use `FullscreenModal` for complex flows.
- Do NOT manually compose a help icon + tooltip — use `HelpTooltip`.
- MUST provide an `id` to `Tooltip` for accessibility.