import { Canvas, Meta, Controls } from '@storybook/addon-docs/blocks';
import {
  PlaygroundHeaderTitle,
  DoWithClearTitle,
  DoWithLabel,
  DoWithActions,
  DoWithSecondaryAction,
  DoWithSubtitle,
  DoWithHelperLinks,
  DontNoTitle,
  DoWithTitle,
  DontLongTitle,
  DoShortTitle,
  DontTwoPrimaryButtons,
  DontInvertedButtonOrder,
} from '../../components/layout/BmsHeaderTitle.stories.js';

<Meta title="Documentation/Layout/Header Title" />

# <img src="../BmsIcon.png" /> Header Title

Header Title is a component that provides a consistent structure for page headers. It displays a title, optional label, helper links, and action buttons. The component helps create a unified header experience across the application, providing space for logos, titles, subtitles, and action buttons in a well-organized layout.

## Anatomy

Header Title components consist of several key elements: an optional logo slot, a label (optional prefix text), the main title (h1), optional helper links (documentation and activity), an optional after-title slot for secondary actions, an actions slot for primary actions, and an optional subtitle slot for additional context.

## Component

Use the controls below to interact with the component and see how it behaves with different configurations.

<Canvas of={PlaygroundHeaderTitle} />

### Props

<Controls of={PlaygroundHeaderTitle} />

## Usage Examples

### ✅ Do: Header title with clear title

Always provide a clear, descriptive title that accurately represents the page content.

<Canvas of={DoWithClearTitle} />

### ✅ Do: Header title with label

Use a label to provide context or categorization for the title, such as the resource type or section name.

<Canvas of={DoWithLabel} />

### ✅ Do: Header title with actions

Use the actions slot to place primary action buttons in the header, aligned to the right.

<Canvas of={DoWithActions} />

### ✅ Do: Header title with secondary action

When you need multiple actions, place the secondary action button to the left of the primary action button. This follows the standard pattern where the primary action is on the right.

<Canvas of={DoWithSecondaryAction} />

### ✅ Do: Header title with subtitle

Use the subtitle slot to provide additional context or description about the page.

<Canvas of={DoWithSubtitle} />

### ✅ Do: Header title with helper links

Use helper links to provide quick access to documentation or activity logs related to the page.

<Canvas of={DoWithHelperLinks} />

## Rules

### ⛔ Don't: Missing title

Always provide a title for the header. The title is the primary identifier for the page and is essential for user orientation.

**❌ Don't:**

<Canvas of={DontNoTitle} />

**✅ Do:**

<Canvas of={DoWithTitle} />

### ⛔ Don't: Too long title

Avoid overly long titles that make the header difficult to read and break the layout. Keep titles concise and clear.

**❌ Don't:**

<Canvas of={DontLongTitle} />

**✅ Do:**

<Canvas of={DoShortTitle} />

### ⛔ Don't: Two primary buttons

Avoid using multiple primary buttons. Use a secondary button for the less important action to maintain visual hierarchy and clarity.

**❌ Don't:**

<Canvas of={DontTwoPrimaryButtons} />

**✅ Do:**

<Canvas of={DoWithSecondaryAction} />

### ⛔ Don't: Inverted button order

Always place the secondary action button to the left of the primary action button. The primary action should be on the right, following standard UI patterns.

**❌ Don't:**

<Canvas of={DontInvertedButtonOrder} />

**✅ Do:**

<Canvas of={DoWithSecondaryAction} />
