/**
 * ==========================================================================
 * HCL STUDIO - TYPE DEFINITIONS
 * ==========================================================================
 * Core interfaces and types for HCL color manipulation and theme management
 * ==========================================================================
 */

// ==========================================================================
// COLOR TYPES
// ==========================================================================

/**
 * HCL color representation
 */
export interface HCL {
  /** Hue (0-360 degrees) */
  h: number;
  /** Chroma (0-100+) */
  c: number;
  /** Lightness (0-100) */
  l: number;
}

/**
 * RGB color representation
 */
export interface RGB {
  /** Red (0-255) */
  r: number;
  /** Green (0-255) */
  g: number;
  /** Blue (0-255) */
  b: number;
}

/**
 * LAB color representation (intermediate for HCL conversion)
 */
export interface LAB {
  /** Lightness (0-100) */
  l: number;
  /** Green-Red axis (-128 to 127) */
  a: number;
  /** Blue-Yellow axis (-128 to 127) */
  b: number;
}

// ==========================================================================
// PALETTE TYPES
// ==========================================================================

/**
 * Tonal palette with Material Design 3 tone levels
 */
export interface TonalPalette {
  0: string;
  4: string;
  5: string;
  6: string;
  10: string;
  12: string;
  15: string;
  17: string;
  20: string;
  22: string;
  25: string;
  30: string;
  35: string;
  40: string;
  50: string;
  60: string;
  70: string;
  80: string;
  87: string;
  90: string;
  92: string;
  94: string;
  95: string;
  96: string;
  98: string;
  99: string;
  100: string;
}

/**
 * Complete Material Design 3 color palette
 */
export interface MaterialPalette {
  primary: TonalPalette;
  secondary: TonalPalette;
  tertiary: TonalPalette;
  neutral: TonalPalette;
  neutralVariant: TonalPalette;
  error: TonalPalette;
}

/**
 * Brand seed colors
 */
export interface BrandColors {
  primary: string;
  secondary: string;
  tertiary: string;
  error?: string;
}

// ==========================================================================
// THEME TYPES
// ==========================================================================

/**
 * Theme configuration
 */
export interface ThemeConfig {
  id: string;
  name: string;
  colors: BrandColors;
  mode?: 'light' | 'dark' | 'auto';
  createdAt?: Date;
  description?: string;
}

/**
 * Complete theme with generated palettes
 */
export interface Theme {
  config: ThemeConfig;
  lightPalette: MaterialPalette;
  darkPalette: MaterialPalette;
  cssVariables: CSSVariables;
}

/**
 * CSS custom properties mapping
 */
export interface CSSVariables {
  [key: string]: string;
}

/**
 * Theme preview information
 */
export interface ThemePreview {
  id: string;
  name: string;
  description?: string;
  primary: string;
  secondary: string;
  tertiary: string;
}

/**
 * Theme collection
 */
export interface ThemeCollection {
  [themeId: string]: Omit<ThemeConfig, 'id'>;
}

// ==========================================================================
// VALIDATION TYPES
// ==========================================================================

/**
 * Color validation result
 */
export interface ColorValidation {
  isValid: boolean;
  warnings: string[];
  recommendations?: string[];
  accessibility?: AccessibilityInfo;
}

/**
 * Accessibility information
 */
export interface AccessibilityInfo {
  contrastRatio: number;
  wcagLevel: 'AA' | 'AAA' | 'fail';
  colorBlindSafe: boolean;
}

// ==========================================================================
// SERVICE CONFIGURATION TYPES
// ==========================================================================

/**
 * HCL Studio initialization options
 */
export interface HCLStudioOptions {
  /** Default theme to apply */
  defaultTheme?: string | ThemeConfig;
  /** Enable automatic mode switching based on system preference */
  autoMode?: boolean;
  /** Storage key for theme persistence */
  storageKey?: string;
  /** Custom theme presets */
  themes?: ThemeCollection;
  /** Validation options */
  validation?: {
    enableContrastCheck: boolean;
    enableColorBlindCheck: boolean;
    minContrastRatio: number;
  };
}

/**
 * Theme state for reactive updates
 */
export interface ThemeState {
  currentTheme: Theme | null;
  availableThemes: ThemePreview[];
  mode: 'light' | 'dark';
  isInitialized: boolean;
}

// ==========================================================================
// UTILITY TYPES
// ==========================================================================

/**
 * Color format types
 */
export type ColorFormat = 'hex' | 'rgb' | 'hsl' | 'hcl';

/**
 * Mode switching options
 */
export type ThemeMode = 'light' | 'dark' | 'auto';

/**
 * Contrast levels for WCAG compliance
 */
export type ContrastLevel = 'AA' | 'AAA';

/**
 * Color harmony types
 */
export type ColorHarmony = 'complementary' | 'analogous' | 'triadic' | 'tetradic' | 'monochromatic';