import { Meta, Title, Subtitle, Description, Primary, Controls, Stories, Canvas } from '@storybook/addon-docs/blocks';
import * as HeaderStories from './header.stories';

<Meta of={HeaderStories} />

<Title />
<Subtitle>The primary Top Bar component for the application shell.</Subtitle>

The `Header` represents the global top bar of the application ecosystem. It provides navigation context (breadcrumbs), system controls (language and theme), and management of the logged-in user profile.

<Primary />

## Properties

The `Header` is highly configurable, allowing for everything from basic title control to complete customization of the user menu.

<Controls />

---

## Usage Differentiation

It is essential to understand the difference between the **Header** and the **PageHeader** to maintain visual consistency:

- **Header (Global)**: Fixed top bar (`sticky`). Contains the navigation trail (breadcrumbs) and the user profile. There is only **ONE** per application.
- **PageHeader (Local)**: Located inside the content area. Contains the large page title (`h1`), subtitle, and specific action buttons (such as "Save" or "New").

---

## Navigation Modes

### 1. Breadcrumbs (Default — Recommended)

The **primary pattern**. Use `breadcrumbs` for any page with navigation hierarchy. The component supports **unlimited** depth levels — do not limit to 2 or 3 items.

<Canvas of={HeaderStories.Default} />

### 2. Deep Navigation (5+ Levels)

Breadcrumbs gracefully handle deeply nested navigation structures with automatic separators and horizontal scrolling.

<Canvas of={HeaderStories.DeepNavigation} />

### 3. Title Only (Exception)

Use `title` **only** when the page is a standalone top-level page with no navigation context (e.g., a standalone dashboard or landing page). This renders a plain text label without separators.

> [!WARNING]
> The `title`-only pattern is the **exception**, not the default. Always prefer `breadcrumbs` when the page has any navigation hierarchy.

<Canvas of={HeaderStories.TitleOnly} />

### 4. SPA Navigation (React Router)

Use the `renderLink` prop to integrate with client-side routers like React Router or Next.js Link. This prevents full-page reloads when users click breadcrumb links.

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

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

<Canvas of={HeaderStories.WithReactRouter} />

### 5. Global Actions and User Menu

Use the `actions` prop for buttons that should always be visible (such as notifications or messages). The `user` prop allows for full customization of the profile dropdown.

<Canvas of={HeaderStories.WithActions} />

---

## Fallback Logic

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

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

---

## Best Practices & AI Rules

> [!IMPORTANT]
> - **Breadcrumbs First** — Always prefer `breadcrumbs` for navigable pages. Use `title` only for standalone pages with no hierarchy.
> - **Unlimited Levels** — Breadcrumbs support any depth. Do not artificially limit to 2–3 items.
> - **Mobile Navigation** — The `Header` contains the automatic trigger to open/close the Sidebar on mobile devices following the `LayoutContext` state.
> - **Height Consistency** — The header has a fixed height of `64px` (`h-[64px]`). Its breadcrumbs are automatically truncated on small screens to prevent layout breaking.
> - **Right Area Actions** — Use `actions` for frequently used interaction items. Less used configuration items should be placed inside `user.menuItems`.

### Developer Integration Guide
```tsx
import { Header } from 'xertica-ui/layout';
import { Home, Settings, Users } from 'lucide-react';

export function MyLayout({ children }) {
  return (
    <div className="flex flex-col min-h-screen">
      <Header 
        breadcrumbs={[
          { label: 'Home', href: '/', icon: <Home className="size-4" /> },
          { label: 'Settings', href: '/settings', icon: <Settings className="size-4" /> },
          { label: 'Team Management' },
        ]}
        user={{ name: "John Doe", email: "john@example.com" }}
      />
      <main className="flex-1 p-6">
        {children}
      </main>
    </div>
  )
}
```