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

'use client';

/**
 * MethodBadge Component
 *
 * A specialized badge for HTTP method display in API documentation.
 * Uses industry-standard color conventions to communicate REST operation types.
 *
 * ## Design Principles
 *
 * 1. **REST Semantic Mapping**: Colors align with HTTP method semantics
 *    - Follows industry conventions (GitHub, Stripe, Swagger UI)
 *    - Immediate visual recognition for developers
 *    - Consistent with HTTP specification meanings
 *
 * 2. **Visual Distinction**: Each method has unique, memorable color
 *    - High contrast for readability against dark backgrounds
 *    - Distinct enough to differentiate at a glance
 *    - Professional appearance suitable for technical documentation
 *
 * 3. **Typography**: Bold, uppercase display reinforces technical nature
 *    - font-bold for emphasis and readability
 *    - Uppercase matches HTTP specification format
 *    - Monospace-friendly sizing
 *
 * ## HTTP Method Semantics
 *
 * @param {'GET'} GET - Read/Retrieve operations (Safe, Idempotent)
 *   - Visual: Cyan/Blue - represents data flow inward (reading)
 *   - Psychology: Information retrieval, safe operation
 *   - Use cases: Fetch resources, list endpoints, query data
 *   - HTTP: Safe method, no side effects, cacheable
 *
 * @param {'POST'} POST - Create operations (Not safe, Not idempotent)
 *   - Visual: Green - represents creation, addition, growth
 *   - Psychology: Positive action, new resource creation
 *   - Use cases: Create resource, submit form, trigger action
 *   - HTTP: Creates new resource, may have side effects
 *
 * @param {'PUT'} PUT - Update/Replace operations (Not safe, Idempotent)
 *   - Visual: Amber/Orange - represents modification, change
 *   - Psychology: Caution, transformation, state change
 *   - Use cases: Update entire resource, replace content
 *   - HTTP: Idempotent, full resource update
 *
 * @param {'PATCH'} PATCH - Partial Update operations (Not safe, Not idempotent)
 *   - Visual: Purple - represents refinement, partial change
 *   - Psychology: Precision, targeted modification
 *   - Use cases: Update specific fields, partial resource modification
 *   - HTTP: Partial update, may not be idempotent
 *
 * @param {'DELETE'} DELETE - Delete operations (Not safe, Idempotent)
 *   - Visual: Red - represents removal, destruction, danger
 *   - Psychology: Warning, irreversible action, stop
 *   - Use cases: Remove resource, deactivate, destroy data
 *   - HTTP: Idempotent, removes resource
 *
 * ## Size Variants
 *
 * @param {'sm'} sm - Small size for inline usage (px-2 py-0.5, text-xs)
 * @param {'md'} md - Medium size for standard usage (px-3 py-1, text-xs) [default]
 *
 * ## Visual Language
 *
 * - **Rounded corners**: Modern, friendly appearance
 * - **Semi-transparent backgrounds**: Integrates with dark theme
 * - **Solid borders**: Adds definition and structure
 * - **Bold text**: Ensures readability and emphasis
 * - **Consistent sizing**: Aligns with other badges in the design system
 *
 * Color Opacity Strategy:
 * - Background: 20% opacity for subtle presence
 * - Border: 40% opacity for clear definition
 * - Text: 100% (400 weight) for maximum readability
 *
 * ## Usage Examples
 *
 * ```tsx
 * // API Endpoint Documentation
 * <MethodBadge method="GET" /> /api/users
 * <MethodBadge method="POST" /> /api/users
 *
 * // With size variants
 * <MethodBadge method="DELETE" size="sm" />
 * <MethodBadge method="PUT" size="md" />
 *
 * // In endpoint cards
 * <div className="flex items-center gap-2">
 *   <MethodBadge method="POST" />
 *   <code>/api/text-to-image</code>
 * </div>
 * ```
 *
 * ## Industry Standards Reference
 *
 * This color scheme aligns with popular API documentation tools:
 * - Swagger UI: Blue (GET), Green (POST), Orange (PUT), Red (DELETE)
 * - Postman: Similar color conventions
 * - GitHub API Docs: Consistent method color coding
 *
 * @component
 * @example
 * <MethodBadge method="POST" size="md" />
 */

import { ReactNode } from 'react';

/**
 * HTTP method types following REST conventions
 */
export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';

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

/**
 * Props for the MethodBadge component
 */
export interface MethodBadgeProps {
  /** The HTTP method to display */
  method: HttpMethod;
  /** Size variant (default: 'md') */
  size?: MethodBadgeSize;
  /** Optional CSS class name for additional styling */
  className?: string;
}

/**
 * Color system mapping HTTP methods to semantic colors
 * Follows industry standards for API documentation
 */
const methodStyles: Record<HttpMethod, string> = {
  GET: 'bg-cyan-600/20 text-cyan-400 border-cyan-500/40',
  POST: 'bg-green-600/20 text-green-400 border-green-500/40',
  PUT: 'bg-amber-600/20 text-amber-400 border-amber-500/40',
  PATCH: 'bg-purple-600/20 text-purple-400 border-purple-500/40',
  DELETE: 'bg-red-600/20 text-red-400 border-red-500/40',
};

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

/**
 * Accessibility labels describing the HTTP method's purpose
 */
const methodLabels: Record<HttpMethod, string> = {
  GET: 'GET request - retrieve data',
  POST: 'POST request - create resource',
  PUT: 'PUT request - update resource',
  PATCH: 'PATCH request - partial update',
  DELETE: 'DELETE request - remove resource',
};

export const MethodBadge = ({
  method,
  size = 'md',
  className = '',
}: MethodBadgeProps) => {
  return (
    <span
      className={`
        inline-flex items-center justify-center
        rounded border font-bold
        ${methodStyles[method]}
        ${sizeStyles[size]}
        ${className}
      `}
      role="status"
      aria-label={methodLabels[method]}
    >
      {method}
    </span>
  );
};