'use client';

/**
 * InlineCode Component
 *
 * A consistent inline code element for technical content within documentation text.
 * Provides semantic color variants to emphasize context and meaning.
 *
 * ## Design Principles
 *
 * 1. **Readability First**: High contrast with surrounding text
 *    - Dark background distinguishes code from prose
 *    - Slightly larger padding creates breathing room
 *    - Rounded corners soften appearance for inline usage
 *
 * 2. **Semantic Coloring**: Color conveys meaning beyond monospace
 *    - Different contexts require different visual emphasis
 *    - Colors match broader design system for consistency
 *    - Never rely on color alone (always has monospace + background)
 *
 * 3. **Typography**: Monospace font signals technical content
 *    - Built-in font-mono class ensures code appearance
 *    - Small size (text-sm) fits inline with body text
 *    - Maintains readability without disrupting flow
 *
 * ## Color Semantic Values
 *
 * @param {'primary'} primary - Default technical content, variable names, general code
 *   - Visual: Purple accent (matches brand primary)
 *   - Psychology: Neutral technical content, primary focus
 *   - Use cases: `apiKey`, `userId`, general inline code snippets
 *   - When to use: Default choice for any code reference
 *
 * @param {'success'} success - Positive examples, correct values, successful states
 *   - Visual: Green accent
 *   - Psychology: Correct, recommended, successful outcome
 *   - Use cases: `status: 200`, `"success": true`, correct API responses
 *   - When to use: Showing what TO do, expected good outcomes
 *
 * @param {'error'} error - Error values, incorrect usage, warnings
 *   - Visual: Red accent
 *   - Psychology: Wrong, dangerous, avoid
 *   - Use cases: `status: 500`, error codes, anti-patterns
 *   - When to use: Showing what NOT to do, error states
 *
 * @param {'neutral'} neutral - Informational, documentation, placeholders
 *   - Visual: Slate/Gray (matches text color scheme)
 *   - Psychology: Reference, documentation, less emphasis
 *   - Use cases: HTTP headers like `X-API-Key`, endpoints, technical terms
 *   - When to use: Supporting information, less critical code references
 *
 * ## Visual Language
 *
 * Background Strategy:
 * - Dark bg (slate-800) creates clear separation from surrounding text
 * - Works on both light and dark documentation themes
 * - Sufficient contrast meets WCAG AA standards
 *
 * Padding Strategy:
 * - Horizontal: px-1.5 (6px) - enough space but not disruptive
 * - Vertical: py-0.5 (2px) - maintains inline text flow
 * - Border radius: rounded (4px) - soft enough for inline, defined enough for blocks
 *
 * Font Strategy:
 * - text-sm: Slightly smaller than body text but still readable
 * - font-mono: Clear distinction from prose, signals code
 * - font-normal: Not bold, integrates naturally with surrounding text
 *
 * ## Usage Examples
 *
 * ```tsx
 * // Default technical content
 * Set your <InlineCode>API_KEY</InlineCode> environment variable.
 *
 * // With semantic colors
 * The response includes <InlineCode color="success">status: 200</InlineCode>.
 * Avoid using <InlineCode color="error">hardcoded credentials</InlineCode>.
 * Include the <InlineCode color="neutral">X-API-Key</InlineCode> header.
 *
 * // Parameter documentation
 * The <InlineCode>autoEnhance</InlineCode> parameter defaults to true.
 *
 * // Error messages
 * If you receive <InlineCode color="error">401 Unauthorized</InlineCode>, check your API key.
 * ```
 *
 * ## Composition Guidelines
 *
 * DO:
 * - Use for short code snippets (1-4 words)
 * - Use for technical terms, variable names, values
 * - Use semantic colors to reinforce meaning
 * - Place naturally within sentences
 *
 * DON'T:
 * - Use for multi-line code (use CodeBlock instead)
 * - Use for long strings (creates readability issues)
 * - Overuse color variants (primary is default for a reason)
 * - Use as a design element (it's for code content only)
 *
 * @component
 * @example
 * <InlineCode color="primary">apiKey</InlineCode>
 */

/**
 * Semantic color variants for inline code
 */
export type InlineCodeColor = 'primary' | 'success' | 'error' | 'neutral';

/**
 * Props for the InlineCode component
 */
export interface InlineCodeProps {
  /** The code content to display */
  children: React.ReactNode;
  /** Semantic color variant (default: 'primary') */
  color?: InlineCodeColor;
  /** Optional CSS class name for additional styling */
  className?: string;
}

/**
 * Color system mapping semantic meanings to text colors
 * All use same dark background for consistency
 */
const colorStyles: Record<InlineCodeColor, string> = {
  primary: 'text-purple-400',
  success: 'text-green-400',
  error: 'text-red-400',
  neutral: 'text-gray-400',
};

export const InlineCode = ({
  children,
  color = 'primary',
  className = '',
}: InlineCodeProps) => {
  return (
    <code
      className={`
        inline-block
        px-1.5 py-0.5
        bg-slate-800
        rounded
        font-mono text-sm
        ${colorStyles[color]}
        ${className}
      `}
    >
      {children}
    </code>
  );
};
