feat (v1.0.0): initial refactor and redesign

lib/types/domain.ts

@@ -0,0 +1,380 @@
+/**
+ * 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[]
+}