# Navigation

## MainNav

The primary navigation organism. Core to every Suite app. Renders the first-level navigation links, cross-app navigation, help/support features, and user identity.

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

### Sub-components

| Sub-component | Usage |
|---|---|
| `MainNav.NavLink` | A single navigation link item |
| `MainNav.NavSection` | A labelled group of `NavLink` items |

### Rules

- MUST include `MainNav` in every Suite app — it is not optional.
- Do NOT create a custom navigation bar — always use `MainNav`.
- Place `MainNav` at the root layout level, outside of `Page`.

---

## Breadcrumb

Indicates the hierarchical position of the current page within the app.

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

Breadcrumbs live inside `PageHeader` (via `PageHeader.Breadcrumb`). Do NOT render `Breadcrumb` standalone outside of a page header.

### Example

```tsx
<PageHeader.Breadcrumb>
  <Breadcrumb.Item href="/releases">Releases</Breadcrumb.Item>
  <Breadcrumb.Item active>My Album</Breadcrumb.Item>
</PageHeader.Breadcrumb>
```

---

## Tabs

Organise related content sections of the same object into distinct panels.

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

### When to use Tabs vs SegmentedButton

| Tabs | SegmentedButton |
|---|---|
| Navigate between **content sections** of one object | Switch the **display mode** of the same content |
| URL often changes per tab | URL typically does not change |
| Each tab shows different data | Same data, different view |

### Example

```tsx
<Tabs defaultActiveKey="details" id="release-tabs">
  <Tabs.Tab eventKey="details" title="Details">
    <DetailsPanel />
  </Tabs.Tab>
  <Tabs.Tab eventKey="tracks" title="Tracks">
    <TracksPanel />
  </Tabs.Tab>
</Tabs>
```

---

## Pagination

Splits a table or list of objects across multiple pages.

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

### Key Props

| Prop | Type | Description |
|---|---|---|
| `currentPage` | number | Active page number (1-indexed) |
| `totalPages` | number | Total number of pages |
| `onPageChange` | function | Called with new page number |
| `pageSize` | number | Items per page |
| `totalItems` | number | Total item count for display |

### Example

```tsx
<Pagination
  currentPage={page}
  totalPages={Math.ceil(total / pageSize)}
  onPageChange={setPage}
  pageSize={25}
  totalItems={total}
/>
```

Always render `Pagination` below a `GridTable` or list. Do NOT implement custom pagination controls.

---

## Sidebar

Collapsible inline panel that pushes page content to make room.

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

Sidebars are **inline** — they shift the content layout. They differ from `Sidecar`, which floats over content.

### When to use Sidebar vs Sidecar

| Sidebar | Sidecar |
|---|---|
| Persistent — user can leave it open | Triggered on demand, closes when done |
| Pushes adjacent content | Floats over content |
| Navigation or filter panels | Contextual detail / form |

## Common Mistakes

- Do NOT use `Tabs` to switch view modes — use `SegmentedButton`.
- Do NOT put `Breadcrumb` outside of `PageHeader` — it belongs inside `PageHeader.Breadcrumb`.
- Do NOT implement custom pagination — use `Pagination`.
- MUST include `MainNav` in every app layout.