/**
 * Domain type definitions for portfolio management.
 *
 * Provides comprehensive type safety for domain data, metrics, and UI components.
 * All domain-related interfaces include renewal tracking, ownership metrics, and
 * categorization for portfolio organization.
 *
 * @module lib/types/domain
 * @category Types
 */

import type { ComponentType, Dispatch, SetStateAction } from 'react'
import type { IconType } from 'react-icons'
import type { LucideIcon } from 'lucide-react'

/**
 * Domain status indicating current usage state.
 *
 * @remarks
 * - `active`: Domain is actively being used for a website or service
 * - `parked`: Domain is registered but not currently in use
 * - `reserved`: Domain is reserved for future use
 *
 * @example
 * ```ts
 * const status: DomainStatus = 'active'
 * ```
 *
 * @public
 */
export type DomainStatus = 'active' | 'parked' | 'reserved'

/**
 * Domain category for portfolio organization.
 *
 * @remarks
 * Categories help organize domains by purpose and importance:
 * - `personal`: Personal branding or portfolio domains
 * - `service`: Production services and applications
 * - `project`: Project-specific or experimental domains
 * - `fun`: Hobby or entertainment domains
 * - `legacy`: Older domains maintained for historical reasons
 *
 * @example
 * ```ts
 * const category: DomainCategory = 'service'
 * ```
 *
 * @public
 */
export type DomainCategory = 'personal' | 'service' | 'project' | 'fun' | 'legacy'

/**
 * Supported domain registrar identifiers.
 *
 * @example
 * ```ts
 * const registrar: DomainRegistrarId = 'Namecheap'
 * ```
 *
 * @public
 */
export type DomainRegistrarId = 'Spaceship' | 'Namecheap' | 'Name.com' | 'Dynadot'

/**
 * Sort options for domain lists.
 *
 * @example
 * ```ts
 * const sortBy: DomainSortOption = 'expiration'
 * ```
 *
 * @public
 */
export type DomainSortOption = 'name' | 'expiration' | 'ownership' | 'registrar'

/**
 * Timeline event types for domain history.
 *
 * @example
 * ```ts
 * const eventType: DomainTimelineEventType = 'renewal'
 * ```
 *
 * @public
 */
export type DomainTimelineEventType = 'registration' | 'renewal'

/**
 * Domain renewal record tracking renewal history.
 *
 * @example
 * ```ts
 * const renewal: Renewal = {
 *   date: '2024-01-15',
 *   years: 2
 * }
 * ```
 *
 * @public
 */
export interface Renewal {
  /** ISO date string of renewal (YYYY-MM-DD format) */
  date: string

  /** Number of years renewed */
  years: number
}

/**
 * Registrar configuration for UI display.
 *
 * @example
 * ```tsx
 * import { SiNamecheap } from 'react-icons/si'
 *
 * const config: RegistrarConfig = {
 *   name: 'Namecheap',
 *   icon: SiNamecheap,
 *   color: '#FF6C2C'
 * }
 * ```
 *
 * @public
 */
export interface RegistrarConfig {
  /** Display name of the registrar */
  name: string

  /** Icon component (from react-icons or custom) */
  icon: IconType | ComponentType<{className?: string}>

  /** Brand color for visual identification */
  color: string
}

/**
 * Core domain data structure.
 *
 * Base interface containing all raw domain information without computed metrics.
 * Use {@link DomainWithMetrics} for enriched data with ownership calculations.
 *
 * @example
 * ```ts
 * const domain: Domain = {
 *   domain: 'example.com',
 *   usage: 'Personal portfolio website',
 *   registrar: 'Namecheap',
 *   autoRenew: true,
 *   status: 'active',
 *   category: 'personal',
 *   tags: ['portfolio', 'web'],
 *   renewals: [
 *     { date: '2022-01-15', years: 1 },
 *     { date: '2023-01-15', years: 2 }
 *   ]
 * }
 * ```
 *
 * @public
 */
export interface Domain {
  /** Domain name (e.g., 'example.com') */
  domain: string

  /** Description of domain usage/purpose */
  usage: string

  /** Registrar where domain is registered */
  registrar: DomainRegistrarId

  /** Whether auto-renewal is enabled */
  autoRenew: boolean

  /** Current status of the domain */
  status: DomainStatus

  /** Portfolio category for organization */
  category: DomainCategory

  /** Tags for filtering and search */
  tags: string[]

  /** Renewal history (chronological order) */
  renewals: Renewal[]
}

/**
 * Enriched domain data with computed ownership and expiration metrics.
 *
 * Extends {@link Domain} with calculated fields for ownership duration, expiration
 * tracking, and renewal progress.
 *
 * @remarks
 * All date calculations use UTC to ensure consistent timezone handling. The renewal
 * progress percentage helps visualize time until next renewal is needed.
 *
 * This interface is generated by `DomainService.enrichDomain()` method.
 * All domains returned by DomainService methods include these computed properties.
 *
 * @example
 * ```ts
 * import { DomainService } from '@/lib/services'
 *
 * const enriched: DomainWithMetrics = DomainService.enrichDomain(domain)
 * console.log(enriched.ownershipYears) // 2
 * console.log(enriched.daysUntilExpiration) // 347
 * console.log(enriched.isExpiringSoon) // false
 * console.log(enriched.renewalProgressPercent) // 15.2
 * console.log(enriched.tld) // 'com'
 * ```
 *
 * @public
 */
export interface DomainWithMetrics extends Domain {
  /** Calculated expiration date based on last renewal */
  expirationDate: Date

  /** First renewal date (registration date) */
  registrationDate: Date

  /** Total days of ownership */
  ownershipDays: number

  /** Full years of ownership (floored) */
  ownershipYears: number

  /** Remaining months after full years */
  ownershipMonths: number

  /** Days until domain expires */
  daysUntilExpiration: number

  /** Percentage of current renewal period completed (0-100) */
  renewalProgressPercent: number

  /** True if expiring within 90 days */
  isExpiringSoon: boolean

  /** Date of next scheduled renewal */
  nextRenewalDate: Date

  /** Top-level domain extension (e.g., 'com', 'net') */
  tld: string
}

/**
 * Visual styling configuration for domain status/category badges.
 *
 * @example
 * ```tsx
 * import { Circle } from 'lucide-react'
 *
 * const option: DomainVisualOption = {
 *   label: 'Active',
 *   icon: Circle,
 *   color: 'text-green-400',
 *   bg: 'bg-green-500/20',
 *   border: 'border-green-500/30'
 * }
 * ```
 *
 * @public
 */
export interface DomainVisualOption {
  /** Display label text */
  label: string

  /** Lucide icon component */
  icon: LucideIcon

  /** Tailwind text color class */
  color: string

  /** Tailwind background color class */
  bg: string

  /** Tailwind border color class */
  border: string
}

/**
 * Complete visual configuration mapping for all domain statuses and categories.
 *
 * @public
 */
export type DomainVisualConfig = {
  /** Visual options for each status type */
  status: Record<DomainStatus, DomainVisualOption>

  /** Visual options for each category type */
  category: Record<DomainCategory, DomainVisualOption>
}

/**
 * Mapping of registrar IDs to their configuration.
 *
 * @public
 */
export type DomainRegistrarMap = Record<DomainRegistrarId, RegistrarConfig>

/**
 * Domain timeline event for renewal/registration history display.
 *
 * @example
 * ```ts
 * const event: DomainTimelineEvent = {
 *   date: new Date('2024-01-15'),
 *   type: 'renewal',
 *   years: 2
 * }
 * ```
 *
 * @public
 */
export interface DomainTimelineEvent {
  /** Event date */
  date: Date

  /** Event type (registration or renewal) */
  type: DomainTimelineEventType

  /** Number of years for the renewal */
  years: number
}

/**
 * Props for DomainCard component.
 *
 * @public
 */
export interface DomainCardProps {
  /** Domain data to display */
  domain: Domain
}

/**
 * Props for DomainDetails component.
 *
 * @public
 */
export interface DomainDetailsProps {
  /** Domain data to display */
  domain: Domain
}

/**
 * Props for DomainTimeline component.
 *
 * @public
 */
export interface DomainTimelineProps {
  /** Domain data to display timeline for */
  domain: Domain
}

/**
 * Props for DomainFilters component.
 *
 * @public
 */
export interface DomainFiltersProps {
  /** Search query change handler */
  onSearchChange: Dispatch<SetStateAction<string>>

  /** Category filter change handler */
  onCategoryChange: Dispatch<SetStateAction<DomainCategory[]>>

  /** Status filter change handler */
  onStatusChange: Dispatch<SetStateAction<DomainStatus[]>>

  /** Registrar filter change handler */
  onRegistrarChange: Dispatch<SetStateAction<DomainRegistrarId[]>>

  /** Sort option change handler */
  onSortChange: Dispatch<SetStateAction<DomainSortOption>>

  /** Available registrars for filter options */
  registrars: DomainRegistrarId[]
}