// Timeline Component Specification
// Framework-agnostic timeline component definition

export type TimelineVariant = 'default' | 'compact' | 'detailed';
export type TimelineOrientation = 'vertical' | 'horizontal';
export type TimelineItemStatus = 'pending' | 'active' | 'completed' | 'error' | 'skipped';

export interface TimelineItem {
  id: string;
  title: string;
  description?: string;
  timestamp?: Date | string;
  status: TimelineItemStatus;
  icon?: string;
  color?: string;
  
  // Metadata
  metadata?: Record<string, unknown>;
  
  // Actions
  actions?: TimelineItemAction[];
  
  // Children (for nested timelines)
  children?: TimelineItem[];
}

export interface TimelineItemAction {
  label: string;
  icon?: string;
  onClick: () => void | Promise<void>;
  variant?: 'primary' | 'secondary' | 'link';
}

export interface TimelineProps {
  items: TimelineItem[];
  variant?: TimelineVariant;
  orientation?: TimelineOrientation;
  
  // Styling
  className?: string;
  itemClassName?: string;
  
  // Behavior
  clickable?: boolean;
  onItemClick?: (item: TimelineItem) => void;
  
  // Loading
  loading?: boolean;
  loadingMessage?: string;
  
  // Empty state
  emptyMessage?: string;
}

export const timelineStatusColors = {
  pending: {
    backgroundColor: '#E0E0E0',
    borderColor: '#9E9E9E',
    textColor: '#616161',
  },
  active: {
    backgroundColor: '#2196F3',
    borderColor: '#1976D2',
    textColor: '#FFFFFF',
  },
  completed: {
    backgroundColor: '#4CAF50',
    borderColor: '#388E3C',
    textColor: '#FFFFFF',
  },
  error: {
    backgroundColor: '#F44336',
    borderColor: '#D32F2F',
    textColor: '#FFFFFF',
  },
  skipped: {
    backgroundColor: '#FF9800',
    borderColor: '#F57C00',
    textColor: '#FFFFFF',
  },
};

/**
 * Timeline Component Interface
 * 
 * Usage example (React):
 * ```tsx
 * <Timeline
 *   items={[
 *     {
 *       id: '1',
 *       title: 'Settlement Initiated',
 *       description: 'Settlement request created',
 *       timestamp: new Date(),
 *       status: 'completed',
 *       icon: 'check'
 *     },
 *     {
 *       id: '2',
 *       title: 'Validation',
 *       description: 'Validating settlement parameters',
 *       timestamp: new Date(),
 *       status: 'active',
 *       icon: 'clock'
 *     },
 *     {
 *       id: '3',
 *       title: 'Approval',
 *       description: 'Awaiting approval',
 *       status: 'pending',
 *       icon: 'pending'
 *     }
 *   ]}
 *   variant="detailed"
 *   orientation="vertical"
 * />
 * ```
 */
export interface TimelineComponent {
  props: TimelineProps;
  setItemStatus(itemId: string, status: TimelineItemStatus): void;
  addItem(item: TimelineItem): void;
  removeItem(itemId: string): void;
  render(): unknown;
}

