'use client';

/**
 * StatusBadge Component
 *
 * A semantic status indicator that uses color psychology and consistent styling
 * to communicate state, result, or severity across documentation.
 *
 * ## Design Principles
 *
 * 1. **Semantic Color System**: Colors convey meaning, not just decoration
 *    - Uses consistent color mapping across all documentation
 *    - Follows industry standards (green = success, red = error, etc.)
 *
 * 2. **Visual Hierarchy**: Small, unobtrusive elements that enhance readability
 *    - Pill-shaped design for friendly, modern appearance
 *    - Subtle backgrounds with semi-transparent colors
 *    - Border emphasis for definition without heaviness
 *
 * 3. **Accessibility**: Meets WCAG 2.1 AA standards
 *    - Sufficient color contrast ratios
 *    - Semantic HTML with aria-label
 *    - Text labels (never color-only communication)
 *
 * ## Semantic Status Values
 *
 * @param {'success'} success - Positive outcomes, completed actions, 2xx HTTP responses
 *   - Visual: Green color palette
 *   - Psychology: Achievement, correctness, go-ahead signal
 *   - Use cases: "200 Success", "Completed", "Active", "✓ Passed"
 *
 * @param {'info'} info - Neutral information, documentation, helpful tips
 *   - Visual: Blue/Cyan color palette
 *   - Psychology: Calm, trustworthy, educational
 *   - Use cases: "Beta", "New", "Info", "Note"
 *
 * @param {'warning'} warning - Caution, deprecation, rate limits, 4xx client errors
 *   - Visual: Amber/Orange color palette
 *   - Psychology: Attention needed, proceed with caution
 *   - Use cases: "429 Rate Limit", "Deprecated", "Warning", "Limited"
 *
 * @param {'error'} error - Failures, critical issues, 5xx server errors, security alerts
 *   - Visual: Red color palette
 *   - Psychology: Stop, danger, requires immediate attention
 *   - Use cases: "500 Error", "Failed", "Critical", "Blocked"
 *
 * @param {'neutral'} neutral - Default state, placeholder, unspecified
 *   - Visual: Slate/Gray color palette
 *   - Psychology: Neutral, balanced, inactive
 *   - Use cases: "Pending", "Unknown", "Draft", "Inactive"
 *
 * ## Size Variants
 *
 * @param {'sm'} sm - Small size for inline usage, tight spaces
 *   - Font: text-xs
 *   - Padding: px-2 py-0.5
 *   - Use: Inline with text, table cells, compact layouts
 *
 * @param {'md'} md - Medium size (default) for standard usage
 *   - Font: text-xs
 *   - Padding: px-3 py-1
 *   - Use: General purpose, code examples, section markers
 *
 * ## Visual Language
 *
 * The badge uses a rounded-full design (pill shape) which:
 * - Creates visual consistency with other UI elements (buttons, tags)
 * - Feels modern and friendly (vs. harsh rectangular badges)
 * - Groups related information visually
 * - Works well at small sizes without appearing cramped
 *
 * Color opacity levels (X/20 bg, X/40 border):
 * - Background: 20% opacity for subtle presence
 * - Border: 40% opacity for definition
 * - Text: 100% for maximum readability
 *
 * ## Usage Examples
 *
 * ```tsx
 * // HTTP Status Codes
 * <StatusBadge status="success" size="sm">200 OK</StatusBadge>
 * <StatusBadge status="error" size="sm">500 Error</StatusBadge>
 *
 * // API States
 * <StatusBadge status="info">Beta</StatusBadge>
 * <StatusBadge status="warning">Deprecated</StatusBadge>
 *
 * // System Status
 * <StatusBadge status="success">✓ Active</StatusBadge>
 * <StatusBadge status="neutral">Pending</StatusBadge>
 * ```
 *
 * @component
 * @example
 * <StatusBadge status="success" size="md">200 Success</StatusBadge>
 */

/**
 * Semantic status type representing the meaning/severity of the badge
 */
export type StatusType = 'success' | 'info' | 'warning' | 'error' | 'neutral';

/**
 * Size variant for the badge
 */
export type StatusSize = 'sm' | 'md';

/**
 * Props for the StatusBadge component
 */
export interface StatusBadgeProps {
  /** The semantic status that determines color and meaning */
  status: StatusType;
  /** The content to display inside the badge */
  children: React.ReactNode;
  /** Size variant (default: 'md') */
  size?: StatusSize;
  /** Optional CSS class name for additional styling */
  className?: string;
}

/**
 * Color system mapping semantic status to Tailwind color utilities
 * Follows the established design system color palette
 */
const statusStyles: Record<StatusType, string> = {
  success: 'bg-green-500/20 text-green-400 border border-green-500/40',
  info: 'bg-cyan-500/20 text-cyan-400 border border-cyan-500/40',
  warning: 'bg-amber-500/20 text-amber-400 border border-amber-500/40',
  error: 'bg-red-500/20 text-red-400 border border-red-500/40',
  neutral: 'bg-slate-500/20 text-slate-400 border border-slate-500/40',
};

/**
 * Size system mapping size variant to padding and font size
 */
const sizeStyles: Record<StatusSize, string> = {
  sm: 'px-2 py-0.5 text-xs',
  md: 'px-3 py-1 text-xs',
};

/**
 * Human-readable labels for screen readers
 */
const statusLabels: Record<StatusType, string> = {
  success: 'Success status',
  info: 'Information status',
  warning: 'Warning status',
  error: 'Error status',
  neutral: 'Neutral status',
};

export const StatusBadge = ({
  status,
  children,
  size = 'md',
  className = '',
}: StatusBadgeProps) => {
  return (
    <span
      className={`
        inline-flex items-center justify-center
        rounded-full font-bold
        ${statusStyles[status]}
        ${sizeStyles[size]}
        ${className}
      `}
      role="status"
      aria-label={statusLabels[status]}
    >
      {children}
    </span>
  );
};
