# Layout & Structure

The layout system uses templates and organisms to define consistent page architecture. Never create custom layout wrappers when these components exist.

## Page

The root wrapper for all page content. Provides the layout structure and nested slots.

```tsx
import { Page } from '@theorchard/suite-frontend';
```

Note: `Page` comes from `@theorchard/suite-frontend`, **not** `@theorchard/suite-components`.

### Sub-components

| Sub-component | Usage |
|---|---|
| `Page.Header` | Page header area (contains `PageHeader`) |
| `Page.Body` | Main scrollable content area |
| `Page.Nav` | Tab navigation under the header |
| `Page.ModuleNav` | Secondary module-level navigation |
| `Page.Switch` | Route-switching content area |
| `Page.Title` | Page title slot |
| `Page.Row` | Horizontal row within page body |
| `Page.Toolbar` | Toolbar area for filters and actions |
| `Page.View` | A named view within the page |
| `Page.Grid` | Grid layout within the page |
| `Page.Col` | Column within a page grid |

### Typical Structure

```tsx
<Page>
  <Page.Header>
    <PageHeader>
      <PageHeader.Primary>
        <PageHeader.Title>Album Title</PageHeader.Title>
      </PageHeader.Primary>
      <PageHeader.Tertiary>
        <Button variant="primary">Publish</Button>
      </PageHeader.Tertiary>
    </PageHeader>
  </Page.Header>

  <Page.Body>
    <Section>
      <Section.Header>
        <Section.Title>Details</Section.Title>
      </Section.Header>
      <Section.Body>
        {/* content */}
      </Section.Body>
    </Section>
  </Page.Body>
</Page>
```

---

## PageGrid

Defines the responsive grid system rules for page content.

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

Use `PageGrid` as the outermost layout wrapper inside `Page.Body` when you need a multi-column responsive grid. Replaces the deprecated Bootstrap `Container` + `Row` + `Col` pattern.

---

## PageHeader

Sets the context of a page. Represents an object or a list of objects. All information and CTAs in the header relate to the object presented.

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

### Sub-components

| Sub-component | Usage | Position |
|---|---|---|
| `PageHeader.Primary` | Object identity (title, cover art, metadata) | Left |
| `PageHeader.Secondary` | Secondary metadata or status | Center |
| `PageHeader.Tertiary` | Primary CTAs | Right |
| `PageHeader.Description` | Object description text | Below primary |
| `PageHeader.Breadcrumb` | Breadcrumb navigation | Top of header |
| `PageHeader.ExternalLinks` | Links to external systems | Alongside title |

### Example

```tsx
<PageHeader>
  <PageHeader.Breadcrumb>
    <Breadcrumb.Item href="/artists">Artists</Breadcrumb.Item>
    <Breadcrumb.Item active>Artist Name</Breadcrumb.Item>
  </PageHeader.Breadcrumb>
  <PageHeader.Primary>
    <CoverArt src={artistImage} size="lg" />
    <PageHeader.Title>Artist Name</PageHeader.Title>
  </PageHeader.Primary>
  <PageHeader.Tertiary>
    <Button variant="primary">Edit Profile</Button>
  </PageHeader.Tertiary>
</PageHeader>
```

---

## Section

Information container that groups related object attributes. The fundamental content unit within a page body.

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

### Sub-components

| Sub-component | Usage |
|---|---|
| `Section.Header` | Section heading area |
| `Section.Title` | Section heading text |
| `Section.Body` | Content area |
| `Section.Divider` | Divider between section parts |
| `Section.Filters` | Filter controls within a section |

### Example

```tsx
<Section>
  <Section.Header>
    <Section.Title>Track List</Section.Title>
    <Section.Filters>
      <SearchInput value={search} onChange={setSearch} placeholder="Search tracks" />
    </Section.Filters>
  </Section.Header>
  <Section.Body>
    <GridTable columns={columns} data={tracks} />
  </Section.Body>
</Section>
```

---

## Card

Represents an object or its attributes. Can be static (informational) or clickable (links to object page).

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

### Sub-components

| Sub-component | Usage |
|---|---|
| `Card.Header` | Card header area |
| `Card.Body` | Card main content |
| `Card.Title` | Card title text |
| `Card.Img` | Card image |
| `Card.Subtitle` | Card subtitle text |
| `Card.Link` | Makes card clickable as a link |
| `Card.Text` | Card body text |
| `Card.ImgOverlay` | Overlay on top of card image |

### Example

```tsx
<Card>
  <Card.Img src={coverUrl} />
  <Card.Body>
    <Card.Title>Album Title</Card.Title>
    <Card.Subtitle>Artist Name</Card.Subtitle>
    <Card.Text>12 tracks · 2024</Card.Text>
  </Card.Body>
</Card>
```

## Common Mistakes

- Do NOT use Bootstrap `Container`, `Row`, or `Col` for new layouts — use `Page`, `PageGrid`, and `Section`.
- Do NOT put primary CTAs inside `PageHeader.Primary` — they belong in `PageHeader.Tertiary`.
- Do NOT create a custom page wrapper — always use `Page` with its slots.
- Do NOT build a raw `<div>`-based card — use `Card` components.