# PageHeader

## Overview

The `PageHeader` is a content-level component used to provide immediate context for a specific page or section. It focuses on the page title, subtitle, back navigation, and primary local actions (like "Create" or "Edit").

**Important:** This is NOT the global Top Bar. For the global application header with profile and system breadcrumbs, use the [`Header`](./header.md) component.

---

## Key Features

- **Primary Heading**: Standardized `h1` styling with optional subtitle.
- **Back Navigation**: Built-in back button with support for standard links (`backHref`) or programmatic handlers (`onBack`).
- **Local Actions**: Dedicated area on the right for primary page controls (Buttons, Dropdowns, etc.).
- **Typography Primitives**: Exports `PageHeaderHeading` and `PageHeaderDescription` for building custom header layouts.

---

## When to Use

- Use at the top of the **content area** of every main page.
- Perfect for detail pages, forms, or any view that requires a clear title and a "Back" button.

---

## Props

| Prop        | Type              | Default | Required | Description                                                             |
| ----------- | ----------------- | ------- | -------- | ----------------------------------------------------------------------- |
| `title`     | `string`          | —       | **Yes**  | The primary H1 title for the page.                                      |
| `subtitle`  | `string`          | —       | No       | Secondary description or context text.                                  |
| `backHref`  | `string`          | —       | No       | Relative URL for the back button. If provided, renders as an `<a>` tag. |
| `onBack`    | `() => void`      | —       | No       | Click handler for the back button.                                      |
| `actions`   | `React.ReactNode` | —       | No       | Buttons or controls to render on the right side.                        |
| `className` | `string`          | —       | No       | Additional CSS classes for the container.                               |

---

## Examples

### Standard Usage

```tsx
import { PageHeader, Button } from 'xertica-ui/ui';
import { Plus } from 'lucide-react';

<PageHeader
  title="Users"
  subtitle="Manage and invite members to your workspace."
  actions={
    <Button size="sm">
      <Plus className="mr-2 size-4" /> Add User
    </Button>
  }
/>;
```

### With Back Navigation

```tsx
import { PageHeader } from 'xertica-ui/ui';

<PageHeader title="Edit Profile" backHref="/settings" />;
```

### Custom Typography

```tsx
import { PageHeaderHeading, PageHeaderDescription } from 'xertica-ui/ui';

<section>
  <PageHeaderHeading>Analytics Overview</PageHeaderHeading>
  <PageHeaderDescription>Detailed metrics for your current project.</PageHeaderDescription>
</section>;
```

---

## AI Rules

- **SEO** — Always provide a meaningful `title`. This component renders the page's primary `h1`.
- **Navigation** — If the page is a sub-view, always provide `backHref` or `onBack` to maintain intuitive UX.
- **Hierarchy** — Place the `PageHeader` immediately after the global `Header` within the main content container.
- **Actions** — Keep the number of `actions` limited (ideally 1-3 buttons) to prevent crowding on mobile.

---

## Related Components

- [`Header`](./header.md) — The global application toolbar.
- [`Button`](./button.md) — Commonly used within the `actions` prop.
- [`Breadcrumb`](./breadcrumb.md) — Should be used in the global `Header`, not here.