import { Meta, Title, Subtitle, Description, Primary, Controls, Stories, Canvas } from '@storybook/addon-docs/blocks';
import * as PageHeaderStories from './page-header.stories';

<Meta of={PageHeaderStories} />

<Title />
<Subtitle>Standard header component for page content and sections.</Subtitle>

The `PageHeader` is used at the top of the content area to provide context (title and subtitle), back navigation, and primary page actions. It helps visually separate the global application header (Top Bar) from context-specific page actions.

<Primary />

## Properties

<Controls />

---

## Usage Patterns

### With Back Button
Essential for sub-views, edit lists, or sequential flows.

<Canvas of={PageHeaderStories.WithBackButton} />

### With Actions
Allows for adding action buttons (Create, Save, Export) to the right side in an organized manner.

<Canvas of={PageHeaderStories.WithActions} />

### Isolated Typography
Auxiliary components to build custom headers while maintaining visual style.

<Canvas of={PageHeaderStories.Typography} />

---

## AI Integration Guide

> [!IMPORTANT]
> - **Mandatory Standard** — The `PageHeader` is the **required standard** for all pages in the Xertica UI library. Never use raw `h2` or `div` for page titles.
> - **H1 Hierarchy** — The `PageHeader` renders an `h1`. Ensure there is only ONE per page to maintain proper SEO structure.
> - **Navigation** — Use `backHref` for direct links or `onBack` to trigger programmatic events when clicking the back button.
> - **Differentiation** — Never confuse the `PageHeader` with the global `Header`. The `Header` is the global top bar with Breadcrumbs and Profile; the `PageHeader` is the internal title of your content.
