# Header

## Overview

The `Header` is the global application top bar — a fixed-height strip (`64px`) rendered at the top of the application shell. It provides a standardized navigation trail (breadcrumbs) and universal system controls.

It is part of the application's "Global Shell" and is designed to work in tandem with the `Sidebar` via the `LayoutContext`.

---

## Key Features

- **Breadcrumb Navigation**: The primary pattern. Supports unlimited depth levels for complex navigation hierarchies.
- **Title Fallback**: Exception pattern for standalone pages with no navigation hierarchy — renders a plain text label.
- **Breadcrumb Slot**: Custom element rendered immediately after the breadcrumb area (badges, buttons, chips, etc.).
- **Responsive Navigation**: Includes a mobile hamburger toggle that synchronizes with the `Sidebar` state.
- **Unified Controls**: Centralizes language selection, theme switching, and user profile management.
- **Universal Actions**: Supports a custom set of sticky action buttons (like Notifications or Search) next to the user profile.

---

## When to Use

- **Always** included in the main application layout (`LayoutContent` or equivalent).
- **Always prefer breadcrumbs** — they are the primary and recommended navigation pattern.
- Use `title` **only** for standalone top-level pages with no parent/navigation context.

---

## Anatomy

```
┌──────────────────────────────────────────────────────────────────────────┐
│ [☰] Home > Settings  [BreadcrumbSlot]     [Actions] [Language] [☀] [User] │
└──────────────────────────────────────────────────────────────────────────┘
```

- **Left Section**: Mobile menu trigger, Breadcrumb trail (or title), and optional `breadcrumbSlot`.
- **Right Section**: Configurable action buttons, system toggles, and the User Profile dropdown.

---

## Props

| Prop                   | Type                                                                              | Default | Description                                                                                                                |
| ---------------------- | --------------------------------------------------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------- |
| `title`                | `string`                                                                          | —       | Page title for standalone pages with **no** navigation hierarchy. Exception pattern — prefer `breadcrumbs`.                |
| `breadcrumbs`          | `BreadcrumbType[]`                                                                | —       | **Primary pattern.** Navigation breadcrumb trail. Supports unlimited levels. Last item without `href` is the current page. |
| `breadcrumbSlot`       | `ReactNode`                                                                       | —       | Custom element rendered immediately after the breadcrumb/title. Accepts any ReactNode — badges, buttons, chips.            |
| `renderLink`           | `(href: string, props: { className?: string; children: ReactNode }) => ReactNode` | —       | Custom link renderer for SPA navigation (React Router, Next.js). When omitted, uses standard `<a>` tags.                   |
| `showLanguageSelector` | `boolean`                                                                         | `true`  | Whether to show the standard language switcher.                                                                            |
| `showThemeToggle`      | `boolean`                                                                         | `true`  | Whether to show the light/dark mode toggle button.                                                                         |
| `user`                 | `HeaderUser`                                                                      | —       | User information and custom profile dropdown menu configuration.                                                           |
| `actions`              | `HeaderAction[]`                                                                  | —       | Custom global action buttons (e.g., Notifications, Help).                                                                  |
| `showSettings`         | `boolean`                                                                         | `false` | Quick access settings icon (renders before the user profile).                                                              |
| `showLogout`           | `boolean`                                                                         | `false` | Quick logout icon (renders as the absolute last item).                                                                     |
| `className`            | `string`                                                                          | —       | Additional CSS classes for the header container.                                                                           |

---

## Navigation Modes

### Breadcrumbs (Default — Recommended)

The primary and recommended pattern. Use for any page with a navigation hierarchy.

```tsx
<Header
  breadcrumbs={[
    { label: 'Home', href: '/', icon: <Home className="size-4" /> },
    { label: 'Settings', href: '/settings' },
    { label: 'Team Management' },
  ]}
/>
```

### Deep Navigation (Unlimited Levels)

Breadcrumbs support any depth — do not artificially limit to 2 or 3 items.

```tsx
<Header
  breadcrumbs={[
    { label: 'Home', href: '/', icon: <Home className="size-4" /> },
    { label: 'Settings', href: '/settings', icon: <Settings className="size-4" /> },
    { label: 'Organization', href: '/settings/org', icon: <FolderOpen className="size-4" /> },
    { label: 'Teams', href: '/settings/org/teams', icon: <Users className="size-4" /> },
    { label: 'Engineering', href: '/settings/org/teams/engineering' },
    { label: 'Access Policies' },
  ]}
/>
```

### Title Only (Exception)

Use **only** for standalone pages with no navigation hierarchy.

```tsx
<Header title="Dashboard" />
```

### With Breadcrumb Slot

Render badges, buttons, or status chips immediately after the breadcrumb.

```tsx
import { Badge, Button } from 'xertica-ui/ui';

<Header
  breadcrumbs={[{ label: 'Home', href: '/' }, { label: 'Deployments' }]}
  breadcrumbSlot={
    <div className="flex items-center gap-2">
      <Badge variant="warning">Beta</Badge>
      <Button variant="outline" size="sm">
        Sync
      </Button>
    </div>
  }
/>;
```

---

## Fallback Logic

The `Header` ensures a navigation area is **never empty**:

1. **Breadcrumbs**: If provided, renders the full navigation trail.
2. **Title**: If provided (without breadcrumbs), renders a simple standalone text label.
3. **Default**: If neither is provided, falls back to `Xertica.ai`.

---

## SPA Navigation (renderLink)

By default, breadcrumb links render as standard `<a>` tags causing full-page reloads. Use `renderLink` to integrate with client-side routers:

### React Router

```tsx
import { Link } from 'react-router-dom';

<Header
  breadcrumbs={[...]}
  renderLink={(href, props) => <Link to={href} {...props} />}
/>
```

### Next.js

```tsx
import NextLink from 'next/link';

<Header
  breadcrumbs={[...]}
  renderLink={(href, props) => <NextLink href={href} {...props} />}
/>
```

---

## AI Rules

- **Breadcrumbs First** — Always prefer `breadcrumbs` for pages with navigation context. Use `title` only for standalone pages.
- **Unlimited Levels** — Breadcrumbs support any depth. Do not artificially limit to 2–3 items.
- **SPA Navigation** — Always use `renderLink` in React Router or Next.js projects to prevent full-page reloads.
- **breadcrumbSlot** — Use for contextual page-level indicators (environment badge, sync button, status chip) that belong visually next to the page title.
- **Integration** — Must be placed at the top of the application shell. Do not use multiple `Header` components in the same layout.
- **Mobile** — The component automatically handles the `LayoutContext` toggle. Do not wrap it in another button for mobile sidebar control.

---

## Related Components

- [`PageHeader`](./page-header.md) — Local content header (used INSIDE the page for titles and local actions).
- [`Sidebar`](./sidebar.md) — The vertical navigation panel.
- [`Breadcrumb`](./breadcrumb.md) — The underlying UI primitive.