# Buttons

## Button

The primary interactive element for user-triggered actions.

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

### Variants

| Variant | Usage | When to use |
|---|---|---|
| `'primary'` | Orange filled | Single highest-priority CTA on a page or modal |
| `'secondary'` (default) | Outlined | Secondary actions, most common button type |
| `'tertiary'` | Text-only | Low-emphasis actions, inside alerts or dense UIs |
| `'danger'` | Red filled | Destructive actions (delete, remove) |
| `'link'` | Hyperlink style | Inline text actions |

### Sizes

| `size` prop | Usage |
|---|---|
| `'lg'` | Large — primary page-level CTAs |
| (default) | Standard — most use cases |
| `'sm'` | Small — compact toolbars |

### Key Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `variant` | string | `'secondary'` | Visual style |
| `size` | `'lg' \| 'sm'` | — | Size override |
| `disabled` | boolean | — | Disables interaction |
| `loading` | boolean | — | Shows spinner, disables interaction |
| `glyph` | boolean | — | Renders as a round icon button (use `GlyphButton` instead) |
| `onClick` | function | — | Click handler |
| `type` | `'button' \| 'submit' \| 'reset'` | `'button'` | HTML button type |
| `form` | string | — | Links button to a form by id |

### Examples

```tsx
// Primary CTA
<Button variant="primary" onClick={handleSave}>Save</Button>

// Loading state
<Button variant="primary" loading>Saving…</Button>

// Destructive
<Button variant="danger" onClick={handleDelete}>Delete</Button>

// Submit button for a form
<Button type="submit" form="my-form" variant="primary">Submit</Button>
```

### Decision Tree

```
Single most important action on screen? → variant="primary"
Standard action (cancel, edit, view)? → variant="secondary"
Low-emphasis / inline action? → variant="tertiary"
Destructive (delete, remove)? → variant="danger"
Icon-only action? → use GlyphButton (not Button with glyph prop)
```

---

## GlyphButton

Icon-only button. Shows a text tooltip on hover.

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

### Key Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `name` | `GlyphName` | required | Glyph icon name |
| `size` | `'sm' \| 'lg' \| 'xl'` | `'lg'` (16px) | Icon size: sm=12px, lg=16px, xl=24px |
| `tooltip` | string | — | Tooltip text shown on hover |
| `variant` | string | — | Same variants as `Button` |
| `disabled` | boolean | — | Disables interaction |

### Examples

```tsx
<GlyphButton name="edit" tooltip="Edit item" onClick={handleEdit} />
<GlyphButton name="close" size="sm" variant="control" onClick={handleClose} />
<GlyphButton name="download" size="xl" tooltip="Download" />
```

---

## GlyphToggle

Icon button that switches between on/off states and changes icon to reflect state.

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

Use when the icon itself communicates the toggled state (e.g. star/unstar, pin/unpin).

---

## ToggleButton

Text or icon button that changes colour to indicate active/inactive state.

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

Use for filter toggles or view-mode switches where the button must visually indicate it is "on".

---

## SegmentedButton

A mutually exclusive group of buttons for switching between views or modes.

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

### Sub-components

| Sub-component | Usage |
|---|---|
| `SegmentedButton.Text` | Text-labelled segment |
| `SegmentedButton.Glyph` | Icon-labelled segment |

### Example

```tsx
<SegmentedButton>
  <SegmentedButton.Glyph name="list" active={view === 'list'} onClick={() => setView('list')} />
  <SegmentedButton.Glyph name="grid" active={view === 'grid'} onClick={() => setView('grid')} />
</SegmentedButton>
```

Use `SegmentedButton` to switch between views (list/grid, chart types). Do NOT use `Tabs` for this — tabs navigate between content sections; `SegmentedButton` changes the display mode of the same content.

## Common Mistakes

- Do NOT put multiple `variant="primary"` buttons in the same view — there should be at most one primary CTA.
- Do NOT use `Button` with the `glyph` prop — use `GlyphButton` for icon-only buttons.
- Do NOT use `SegmentedButton` for navigation — use `Tabs` instead.