# Heading Component

A semantic heading component that renders HTML heading elements (h1-h6) with flexible visual styling and alignment controls, allowing the semantic level to differ from the visual appearance.

## Import path
```tsx
import Heading from '@hubspot/cms-component-library/Heading';
```

## Purpose

The Heading component provides proper semantic structure while maintaining visual design flexibility. It solves the common challenge where semantic HTML hierarchy (h1-h6) needs to differ from visual styling - for example, an h3 element styled to look like an h1. This separation of semantic meaning from visual presentation ensures both accessibility and design consistency.

## Component Structure

```
Heading/
├── index.tsx                      # Main component with render logic
├── types.ts                       # TypeScript type definitions
├── ContentFields.tsx              # HubSpot field definitions for content
├── StyleFields.tsx                # HubSpot field definitions for styling
├── index.module.scss              # CSS module with design tokens
└── stories/
    ├── Heading.stories.tsx        # Component usage examples
    ├── HeadingDecorator.tsx       # Storybook decorator
    └── HeadingDecorator.module.css # Decorator styles
```

## Props

```tsx
{
  headingLevel: 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6';  // Semantic HTML level (required)
  displayAs?: 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' | 'display_1' | 'display_2';  // Visual style (defaults to headingLevel)
  textAlign?: 'LEFT' | 'CENTER' | 'RIGHT';  // Text alignment
  className?: string;  // Additional CSS classes
  style?: React.CSSProperties;  // Inline styles (including CSS variables)
  children?: React.ReactNode;  // Heading text content
}
```

## Usage Examples

### Basic Heading

```tsx
import Heading from '@hubspot/cms-component-library/Heading';

<Heading headingLevel="h1">
  Welcome to Our Site
</Heading>
```

### Semantic vs Visual Styling

When you need a lower-level heading to look like a higher-level one:

```tsx
<Heading
  headingLevel="h3"  // Semantic: third-level heading
  displayAs="h1"     // Visual: styled like an h1
>
  Section Title
</Heading>
```

### With Text Alignment

```tsx
<Heading
  headingLevel="h2"
  textAlign="CENTER"
>
  Centered Heading
</Heading>
```


## HubSpot CMS Integration

### Field Definitions

#### ContentFields.tsx

```tsx
<Heading.ContentFields
  headingTextLabel="Heading text"
  headingTextName="headingText"
  headingTextDefault="Heading Text"
  headingLevelLabel="Heading Level"
  headingLevelName="headingLevel"
  headingLevelDefault="h1"
/>
```

**Fields:**
- `headingText`: TextField for heading content
- `headingLevel`: ChoiceField for semantic level (h1-h6)

#### StyleFields.tsx

```tsx
<Heading.StyleFields
  textAlignLabel="Heading text align"
  textAlignName="headingTextAlign"
  textAlignDefault="LEFT"
  displayAsLabel="Display as"
  displayAsName="headingDisplayAs"
  displayAsDefault="h1"
/>
```

**Fields:**
- `headingTextAlign`: AlignmentField for text alignment
- `headingDisplayAs`: ChoiceField for visual style (h1-h6, display_1, display_2)

### Module Usage Example

```tsx
import Heading from '@hubspot/cms-component-library/Heading';

export default function HeroModule({ fieldValues }) {
  return (
    <Heading
      headingLevel={fieldValues.headingLevel}
      displayAs={fieldValues.headingDisplayAs}
      textAlign={fieldValues.headingTextAlign?.horizontal_align}
    >
      {fieldValues.headingText}
    </Heading>
  );
}
```

## Styling

### CSS Variables

The Heading component uses CSS variables for theming and customization:

**Base Styles:**
- `--hscl-heading-font`: Font family
- `--hscl-heading-fontSize`: Font size (set by displayAs level)
- `--hscl-heading-fontStyle`: Font style (set by displayAs level)
- `--hscl-heading-fontWeight`: Font weight (set by displayAs level)
- `--hscl-heading-lineHeight`: Line height
- `--hscl-heading-margin`: Vertical margin (margin-block)
- `--hscl-heading-color`: Text color
- `--hscl-heading-textAlign`: Text alignment

**Level-specific Variables:**
Each heading level has its own design tokens:
- `--hscl-heading-h1-font`, `--hscl-heading-h1-fontSize`, etc.
- `--hscl-heading-h2-font`, `--hscl-heading-h2-fontSize`, etc.
- Through `--hscl-heading-h6-font`, `--hscl-heading-h6-fontSize`, etc.
- `--hscl-heading-display_1-font`, `--hscl-heading-display_1-fontSize`, etc.
- `--hscl-heading-display_2-font`, `--hscl-heading-display_2-fontSize`, etc.

## Accessibility

The Heading component follows accessibility best practices:

- **Semantic HTML**: Always renders the appropriate heading element (h1-h6) based on `headingLevel` for proper document structure
- **Visual Hierarchy Independence**: The `displayAs` prop allows visual styling to differ from semantic structure, ensuring flexibility without breaking accessibility
- **Proper Nesting**: Ensure headings follow logical order in your document (h1 → h2 → h3, etc.) regardless of visual styling
- **Screen Readers**: Screen readers announce the semantic level (`headingLevel`), not the visual style
- **Keyboard Navigation**: Native heading element support for keyboard navigation and focus management

## Best Practices

- **Follow semantic order**: Use headings in logical order (h1 for main title, h2 for sections, h3 for subsections, etc.)
- **One h1 per page**: Each page should have exactly one h1 element representing the main topic
- **Use displayAs for visual flexibility**: When you need a different visual style than the semantic level requires, use the `displayAs` prop
- **Don't skip levels**: Don't jump from h2 to h4; maintain proper hierarchy

