banatie-service/apps/landing/src/components/docs/blocks/SectionHeader.tsx

'use client';

/**
 * SectionHeader Component
 *
 * Consistent heading elements for organizing documentation content into hierarchical sections.
 * Provides visual rhythm and structure throughout documentation pages.
 *
 * ## Design Principles
 *
 * 1. **Visual Hierarchy**: Size and weight indicate content importance
 *    - Level 2 (h2): Major sections, primary content divisions
 *    - Level 3 (h3): Subsections, supporting details
 *    - Consistent styling creates predictable structure
 *
 * 2. **Semantic HTML**: Proper heading levels for accessibility
 *    - Uses correct HTML heading tags (h2, h3)
 *    - Supports screen readers and document outline
 *    - Enables Table of Contents generation
 *    - Critical for SEO and document structure
 *
 * 3. **Spacing System**: Establishes vertical rhythm
 *    - Top margin separates from previous content
 *    - Bottom margin creates breathing room before content
 *    - Consistent spacing improves scannability
 *
 * ## Heading Level Semantics
 *
 * @param {2} level2 - Major section headings (h2)
 *   - Visual: text-3xl (30px), font-bold, text-white
 *   - Spacing: mb-4 (16px) below, mb-6 (24px) for sections with mb-12
 *   - Psychology: Primary divisions, main topics
 *   - Use cases: "Overview", "Parameters", "Response", "Error Codes"
 *   - Hierarchy: Second level (after page h1/Hero)
 *   - SEO: Key topic signals for search engines
 *
 * @param {3} level3 - Subsection headings (h3)
 *   - Visual: text-xl (20px), font-semibold, text-white
 *   - Spacing: mb-3 (12px) below, mb-4 (16px) for subsections with mb-8
 *   - Psychology: Supporting topics, detailed breakdowns
 *   - Use cases: "Key Types", "Creating Keys", "Rate Limits"
 *   - Hierarchy: Third level (under h2 sections)
 *   - SEO: Supporting detail signals
 *
 * ## Typography Scale Reasoning
 *
 * Level 2 (text-3xl / 30px):
 * - Large enough to clearly mark major sections
 * - Smaller than Hero (36-48px) to maintain hierarchy
 * - Bold weight adds emphasis and structure
 * - White color ensures readability and prominence
 *
 * Level 3 (text-xl / 20px):
 * - Noticeably smaller than h2, maintaining hierarchy
 * - Semibold (600) instead of bold provides subtle distinction
 * - Large enough to serve as clear subsection marker
 * - Balances prominence with subordinate role
 *
 * ## Spacing Philosophy
 *
 * Bottom Margin Strategy:
 * - h2: mb-4 or mb-6 depending on section context
 *   - mb-4 for tighter sections with nearby content
 *   - mb-6 for major sections introducing substantial content
 * - h3: mb-3 or mb-4 depending on subsection context
 *   - Smaller margins reflect subordinate hierarchy
 *   - Still provides clear separation from content
 *
 * ## Anchor Link Support
 *
 * The `id` prop enables:
 * - Direct linking to specific sections (#section-name)
 * - Table of Contents navigation
 * - Deep linking from external sources
 * - Browser history for scrolled positions
 *
 * ID Naming Convention:
 * - Use kebab-case (lowercase with hyphens)
 * - Descriptive and unique per page
 * - Example: "api-keys", "rate-limits", "error-handling"
 *
 * ## Accessibility Features
 *
 * - Semantic HTML heading levels (h2, h3)
 * - Proper document outline structure
 * - Sufficient color contrast (white on dark)
 * - Clear visual distinction between levels
 * - Screen reader friendly navigation
 * - Keyboard accessible anchor links
 *
 * ## Usage Examples
 *
 * ```tsx
 * // Major section heading (h2)
 * <SectionHeader level={2} id="overview">
 *   Overview
 * </SectionHeader>
 *
 * // Subsection heading (h3)
 * <SectionHeader level={3} id="key-types">
 *   Key Types
 * </SectionHeader>
 *
 * // Custom spacing with className
 * <SectionHeader level={2} id="parameters" className="mb-6">
 *   Parameters
 * </SectionHeader>
 * ```
 *
 * ## Content Guidelines
 *
 * Level 2 Headings:
 * - 1-3 words ideal (concise and scannable)
 * - Sentence case (capitalize first word)
 * - Action-oriented or descriptive nouns
 * - Examples: "Quick Start", "Authentication", "Rate Limits"
 *
 * Level 3 Headings:
 * - 1-4 words, slightly more descriptive
 * - Sentence case
 * - Specific subtopics or steps
 * - Examples: "Creating Keys", "Using API Keys", "Security Best Practices"
 *
 * ## Visual Language
 *
 * The header system creates a visual rhythm that:
 * - Guides the eye through content naturally
 * - Breaks long pages into digestible chunks
 * - Signals importance through size and weight
 * - Maintains consistency across all documentation
 * - Supports quick scanning and navigation
 *
 * @component
 * @example
 * <SectionHeader level={2} id="getting-started">
 *   Getting Started
 * </SectionHeader>
 */

import { ReactNode } from 'react';

/**
 * Heading level determining HTML tag and visual styling
 */
export type SectionHeaderLevel = 2 | 3;

/**
 * Props for the SectionHeader component
 */
export interface SectionHeaderProps {
  /** Heading level (h2 or h3) for semantic structure */
  level: SectionHeaderLevel;
  /** The heading text content */
  children: ReactNode;
  /** Optional ID for anchor linking and table of contents */
  id?: string;
  /** Optional CSS class name for additional styling (e.g., custom margins) */
  className?: string;
}

/**
 * Typography styles mapping heading level to text size and weight
 */
const levelStyles: Record<SectionHeaderLevel, string> = {
  2: 'text-3xl font-bold',
  3: 'text-xl font-semibold',
};

/**
 * Default spacing system for bottom margins
 */
const defaultSpacing: Record<SectionHeaderLevel, string> = {
  2: 'mb-4',
  3: 'mb-3',
};

export const SectionHeader = ({
  level,
  children,
  id,
  className,
}: SectionHeaderProps) => {
  const Tag = `h${level}` as 'h2' | 'h3';
  const spacing = className?.includes('mb-') ? '' : defaultSpacing[level];

  return (
    <Tag
      id={id}
      className={`
        ${levelStyles[level]}
        text-white
        ${spacing}
        ${className || ''}
      `}
    >
      {children}
    </Tag>
  );
};