'use client';

/**
 * LinkCard Component
 *
 * An interactive navigation card for guiding users to related documentation pages.
 * Uses color accents and hover effects to create an engaging, explorable experience.
 *
 * ## Design Principles
 *
 * 1. **Visual Affordance**: Design signals interactivity
 *    - Gradient backgrounds hint at clickability
 *    - Hover states provide immediate feedback
 *    - Cursor changes to pointer on hover
 *    - Border transitions guide attention
 *
 * 2. **Semantic Color System**: Accent colors convey meaning
 *    - Primary (Purple): Main content, API references
 *    - Secondary (Cyan): Supporting content, guides
 *    - Success (Green): Getting started, tutorials
 *    - Warning (Amber): Important notices, deprecations
 *
 * 3. **Information Hierarchy**: Title dominates, description supports
 *    - Large, bold title draws attention
 *    - Smaller, muted description provides context
 *    - Title color changes on hover for feedback
 *    - Clean vertical rhythm (title → description)
 *
 * ## Accent Color Semantics
 *
 * @param {'primary'} primary - Main navigational elements, API documentation
 *   - Visual: Purple gradient and border
 *   - Psychology: Primary brand, core content, important
 *   - Use cases: "API Reference", "Core Concepts", main docs
 *   - Gradient: from-purple-500/10
 *   - Hover: border-purple-500/40, text-purple-400
 *
 * @param {'secondary'} secondary - Supporting content, guides, tutorials
 *   - Visual: Cyan gradient and border
 *   - Psychology: Complementary, helpful, educational
 *   - Use cases: "Guides", "Tutorials", "Best Practices"
 *   - Gradient: from-cyan-500/10
 *   - Hover: border-cyan-500/40, text-cyan-400
 *
 * @param {'success'} success - Getting started, quick wins, positive actions
 *   - Visual: Green gradient and border
 *   - Psychology: Achievement, beginning, growth
 *   - Use cases: "Getting Started", "Quick Start", "First Steps"
 *   - Gradient: from-green-500/10
 *   - Hover: border-green-500/40, text-green-400
 *
 * @param {'warning'} warning - Important notices, cautions, deprecations
 *   - Visual: Amber gradient and border
 *   - Psychology: Attention, caution, important
 *   - Use cases: "Migration Guide", "Breaking Changes", "Deprecations"
 *   - Gradient: from-amber-500/10
 *   - Hover: border-amber-500/40, text-amber-400
 *
 * ## Interactive States
 *
 * Default State:
 * - Subtle gradient background (from-{color}-500/10)
 * - Muted border (border-slate-700/50)
 * - White title, gray description
 * - Inviting but not demanding attention
 *
 * Hover State:
 * - Border brightens to accent color (/40 opacity)
 * - Title transitions to accent color
 * - Smooth transition (transition-colors)
 * - Clear feedback that element is clickable
 *
 * ## Layout Structure
 *
 * Padding System:
 * - p-5 (20px): Generous padding for comfortable clicking
 * - Creates substantial hit area for accessibility
 * - Provides breathing room for content
 *
 * Border & Radius:
 * - rounded-xl (12px): Modern, friendly appearance
 * - border: Defined structure
 * - Matches other card components in system
 *
 * ## Typography System
 *
 * Title (h3):
 * - text-lg (18px): Large enough to be primary visual element
 * - font-semibold (600): Strong but not overbearing
 * - text-white: Maximum contrast and readability
 * - mb-2 (8px): Separates from description
 * - Transitions to accent color on hover
 *
 * Description (p):
 * - text-sm (14px): Clearly secondary to title
 * - text-gray-400: Muted, supporting role
 * - Provides context without competing with title
 *
 * ## Accessibility Features
 *
 * - Semantic HTML (<a> tag for links)
 * - Proper heading hierarchy (h3 for card titles)
 * - Keyboard accessible (focusable link)
 * - Sufficient color contrast in all states
 * - Large click target (full card clickable)
 * - Clear focus states (browser default + hover)
 * - Descriptive link text (title + description)
 *
 * ## Usage Examples
 *
 * ```tsx
 * // Primary content link
 * <LinkCard
 *   href="/docs/api/text-to-image"
 *   title="API Reference"
 *   description="Explore all available endpoints, parameters, and response formats."
 *   accent="primary"
 * />
 *
 * // Getting started
 * <LinkCard
 *   href="/docs/quick-start"
 *   title="Quick Start"
 *   description="Get up and running with Banatie API in 5 minutes."
 *   accent="success"
 * />
 *
 * // Supporting guide
 * <LinkCard
 *   href="/docs/guides/authentication"
 *   title="Authentication Guide"
 *   description="Learn about API keys, rate limits, and security best practices."
 *   accent="secondary"
 * />
 *
 * // Important notice
 * <LinkCard
 *   href="/docs/migration"
 *   title="Migration Guide"
 *   description="Upgrade to v2 API with this step-by-step migration guide."
 *   accent="warning"
 * />
 * ```
 *
 * ## Content Guidelines
 *
 * Title:
 * - 2-5 words ideal
 * - Action-oriented or noun-based
 * - Clear and specific
 * - Sentence case
 * - Examples: "API Reference", "Quick Start", "Authentication Guide"
 *
 * Description:
 * - One sentence (10-20 words)
 * - Explain what user will find/learn
 * - Start with verb (Explore, Learn, Discover)
 * - End with period
 * - Be specific about content
 *
 * Accent Color:
 * - Choose based on content type and importance
 * - Maintain consistency across similar pages
 * - Use primary for most API/core documentation
 * - Reserve warning for truly important notices
 *
 * ## Visual Language
 *
 * The LinkCard system creates:
 * - Intuitive navigation patterns
 * - Clear content categorization through color
 * - Engaging, explorable documentation
 * - Professional yet friendly appearance
 * - Consistent user experience across all docs
 *
 * @component
 * @example
 * <LinkCard
 *   href="/docs/api"
 *   title="API Reference"
 *   description="Complete API documentation"
 *   accent="primary"
 * />
 */

/**
 * Accent color determining the card's visual theme
 */
export type LinkCardAccent = 'primary' | 'secondary' | 'success' | 'warning';

/**
 * Props for the LinkCard component
 */
export interface LinkCardProps {
  /** Navigation URL */
  href: string;
  /** Card title (renders as h3) */
  title: string;
  /** Supporting description */
  description: string;
  /** Visual accent color */
  accent: LinkCardAccent;
  /** Optional icon or emoji to display */
  icon?: string;
  /** Optional CSS class name for additional styling */
  className?: string;
}

/**
 * Accent styles mapping color to gradient and hover colors
 */
const accentStyles: Record<LinkCardAccent, {
  gradient: string;
  hoverBorder: string;
  hoverText: string;
}> = {
  primary: {
    gradient: 'from-purple-500/10',
    hoverBorder: 'hover:border-purple-500/40',
    hoverText: 'group-hover:text-purple-400',
  },
  secondary: {
    gradient: 'from-cyan-500/10',
    hoverBorder: 'hover:border-cyan-500/40',
    hoverText: 'group-hover:text-cyan-400',
  },
  success: {
    gradient: 'from-green-500/10',
    hoverBorder: 'hover:border-green-500/40',
    hoverText: 'group-hover:text-green-400',
  },
  warning: {
    gradient: 'from-amber-500/10',
    hoverBorder: 'hover:border-amber-500/40',
    hoverText: 'group-hover:text-amber-400',
  },
};

export const LinkCard = ({
  href,
  title,
  description,
  accent,
  icon,
  className = '',
}: LinkCardProps) => {
  const styles = accentStyles[accent];

  return (
    <a
      href={href}
      className={`
        block
        p-5
        bg-gradient-to-br ${styles.gradient} to-transparent
        border border-slate-700/50
        rounded-xl
        ${styles.hoverBorder}
        transition-colors
        group
        ${className}
      `}
    >
      {icon && (
        <div className="text-2xl mb-3">{icon}</div>
      )}
      <h3
        className={`
          text-lg font-semibold text-white mb-2
          ${styles.hoverText}
          transition-colors
        `}
      >
        {title}
      </h3>
      <p className="text-sm text-gray-400">
        {description}
      </p>
    </a>
  );
};