'use client';

/**
 * Hero Component
 *
 * The primary heading section at the top of documentation pages.
 * Establishes visual hierarchy and sets expectations for page content.
 *
 * ## Design Principles
 *
 * 1. **Information Hierarchy**: Clear progression from title to description
 *    - Large, bold title commands attention immediately
 *    - Subtitle provides context without competing with title
 *    - Consistent spacing creates rhythm and flow
 *
 * 2. **Typography Scale**: Responsive sizing for all devices
 *    - Mobile-first approach with thoughtful breakpoints
 *    - Maintains readability across screen sizes
 *    - Proper line-height for comfortable reading
 *
 * 3. **Visual Weight**: Balanced presence without overwhelming
 *    - White title for maximum contrast and impact
 *    - Gray subtitle for supporting, not competing
 *    - Generous margins create breathing room
 *
 * ## Size Variants
 *
 * @param {'default'} default - Standard documentation pages
 *   - Title: text-4xl (36px) → md:text-5xl (48px)
 *   - Use cases: API references, guides, tutorials
 *   - Psychology: Professional, focused, informative
 *   - Spacing: mb-12 (48px) after hero
 *
 * @param {'large'} large - Major landing pages, section introductions
 *   - Title: text-5xl (48px) → md:text-6xl (60px)
 *   - Use cases: Documentation home, major category pages
 *   - Psychology: Welcoming, important, primary entry point
 *   - Spacing: mb-16 (64px) after hero
 *
 * ## Typographic Hierarchy
 *
 * Title Characteristics:
 * - **Weight**: font-bold (700) - Commands attention
 * - **Color**: text-white - Maximum contrast, immediately readable
 * - **Spacing**: mb-4 (16px) - Connects title to subtitle
 *
 * Subtitle Characteristics:
 * - **Size**: text-xl (20px) - Large enough to be comfortable, small enough to defer
 * - **Weight**: Regular (400) - Contrast with bold title
 * - **Color**: text-gray-400 - Supporting role, doesn't compete
 * - **Line height**: leading-relaxed (1.625) - Comfortable multi-line reading
 *
 * ## Responsive Behavior
 *
 * Mobile (<768px):
 * - Smaller text sizes to fit narrow screens
 * - Maintains readability with appropriate line lengths
 * - Single column layout
 *
 * Desktop (≥768px):
 * - Larger text leverages available space
 * - Enhanced visual impact
 * - Better use of vertical rhythm
 *
 * ## Visual Language
 *
 * The hero serves multiple purposes in documentation:
 * 1. **Orientation**: Tells users where they are
 * 2. **Context**: Explains what this page covers
 * 3. **Hierarchy**: Establishes importance through size
 * 4. **Consistency**: Familiarpattern across all docs pages
 *
 * Color Psychology:
 * - **White title**: Authority, clarity, primary information
 * - **Gray subtitle**: Support, context, secondary information
 * - Creates natural reading flow: bold → light, primary → secondary
 *
 * ## Accessibility
 *
 * - Uses semantic HTML (<h1> for title)
 * - Proper heading hierarchy (h1 is first heading on page)
 * - Sufficient color contrast (white on dark background)
 * - Readable font sizes (minimum 20px for subtitle)
 * - Appropriate line-height for comfortable reading
 *
 * ## Usage Examples
 *
 * ```tsx
 * // Standard API reference page
 * <Hero
 *   title="Text to Image"
 *   subtitle="Generate high-quality images from text prompts using AI-powered models."
 * />
 *
 * // Documentation home page
 * <Hero
 *   size="large"
 *   title="Welcome to Banatie API Documentation"
 *   subtitle="Learn how to integrate AI-powered image generation into your applications in minutes."
 * />
 *
 * // Guide page
 * <Hero
 *   title="Authentication"
 *   subtitle="Learn how to authenticate with the Banatie API using API keys, manage rate limits, and implement security best practices."
 * />
 * ```
 *
 * ## Content Guidelines
 *
 * Title:
 * - Keep short and specific (1-5 words ideal)
 * - Use sentence case (capitalize first word only)
 * - Avoid punctuation unless necessary
 * - Match page's primary purpose
 *
 * Subtitle:
 * - One to two sentences maximum
 * - Explain what user will learn or accomplish
 * - Use active voice and present tense
 * - End with period for complete thoughts
 *
 * @component
 * @example
 * <Hero
 *   title="Getting Started"
 *   subtitle="Welcome to the Banatie API documentation."
 *   size="default"
 * />
 */

/**
 * Size variant determining the visual scale of the hero
 */
export type HeroSize = 'default' | 'large';

/**
 * Props for the Hero component
 */
export interface HeroProps {
  /** The main page title (renders as h1) */
  title: string;
  /** Supporting description or context */
  subtitle: string | React.ReactNode;
  /** Size variant (default: 'default') */
  size?: HeroSize;
  /** Optional CSS class name for additional styling */
  className?: string;
}

/**
 * Title size system mapping size variant to responsive text classes
 */
const titleSizes: Record<HeroSize, string> = {
  default: 'text-4xl md:text-5xl',
  large: 'text-5xl md:text-6xl',
};

/**
 * Spacing system for bottom margin
 */
const spacingSizes: Record<HeroSize, string> = {
  default: 'mb-12',
  large: 'mb-16',
};

export const Hero = ({
  title,
  subtitle,
  size = 'default',
  className = '',
}: HeroProps) => {
  return (
    <div className={`${spacingSizes[size]} ${className}`}>
      <h1 className={`${titleSizes[size]} font-bold text-white mb-4`}>
        {title}
      </h1>
      <p className="text-xl text-gray-400 leading-relaxed">
        {subtitle}
      </p>
    </div>
  );
};
