import {
  Canvas,
  Controls,
  Meta,
  Story,
  Title,
  Subtitle,
} from '@storybook/addon-docs/blocks'
import * as ComponentStories from './PageHeader.stories'
import { LifecycleTag } from '../../docs/components'

<Meta of={ComponentStories} />

<Title>PageHeader</Title>
<Subtitle>
  A standardized header component for application pages, featuring scroll
  detection and flexible spacing strategies.
</Subtitle>

<LifecycleTag variant="Stable" />

<Canvas of={ComponentStories.Default} sourceState="shown" />
<Controls />

## Import

```tsx
import {
  PageHeader,
  PageHeaderTitle,
  PageHeaderActions,
} from '@chainlink/blocks'
```

## Usage

```tsx
<PageHeader>
  <PageHeaderTitle>My Page</PageHeaderTitle>
  <PageHeaderActions>{/* Action buttons */}</PageHeaderActions>
</PageHeader>
```

## Spacing Strategies

The `PageHeader` is fixed-positioned to support transparency effects. This
removes it from the document flow, which can cause content to be hidden
underneath it. To address this, the component offers three spacing strategies
via the `reserveSpace` prop.

### 1. Sibling Mode (Default)

This mode uses a CSS sibling selector (`[&_+_*]`) on an invisible sentinel
element to apply `padding-top` to the **immediate next sibling**.

**Pros:** Automatic for simple layouts. **Cons:** Fragile. Fails if the next
sibling is a `Toaster`, Context Provider, or `fixed` element.

```tsx
<PageHeader reserveSpace="sibling">
  {/* ... */}
</PageHeader>
<main>
  {/* Automatically gets padding-top */}
</main>
```

### 2. Spacer Mode (Recommended for Fixed Layouts)

This mode renders a visible spacer `div` that occupies the exact height of the
header in the document flow. This robustly pushes all subsequent content down.

You can customize the background color of the spacer using `spacerClassName` to
match your content background.

**Pros:** Robust, explicit, works with any sibling structure. **Cons:** Adds an
extra DOM element.

```tsx
// Example: Matching a gray background
<PageHeader reserveSpace="spacer" spacerClassName="bg-[--gray-50]">
  {/* ... */}
</PageHeader>
<main className="bg-[--gray-50]">
  {/* Content starts naturally below the header */}
</main>
```

### 3. None Mode (Recommended for Transparent/Hero Layouts)

This mode does not apply any automatic spacing. It relies on the consumer to
handle spacing, typically using the exposed CSS variables.

This is perfect for "Hero" sections where you want the background to extend to
the top of the viewport (behind the header) while keeping the text content
padded.

**CSS Variables Exposed:**

- `--page-header-height`: Height of the header (e.g., `74px`)
- `--page-header-spacing`: Height + default padding (e.g., `calc(74px + 2rem)`)

```tsx
;<PageHeader reserveSpace="none">{/* ... */}</PageHeader>

{
  /* Hero Section: Background behind header */
}
;<div className="min-h-screen bg-slate-900 text-white">
  <div className="pt-[var(--page-header-height)]">
    <h1>Hero Content</h1>
  </div>
</div>
```