components.interface.ts

// Copyright The Linux Foundation and each contributor to LFX.
// SPDX-License-Identifier: MIT

import { ChartData, ChartOptions, ChartType } from 'chart.js';

/**
 * Named entity interface for pipes
 * @description Common interface for entities with name and email fields
 */
export interface NamedEntity {
  /** First name of the entity */
  first_name?: string | null;
  /** Last name of the entity */
  last_name?: string | null;
  /** Email address of the entity */
  email?: string;
}

/**
 * Feature toggle configuration
 * @description Configuration for feature toggle component
 */
export interface FeatureConfig {
  /** Form control key */
  key: string;
  /** Icon class (e.g., 'fa-light fa-repeat') */
  icon: string;
  /** Feature title */
  title: string;
  /** Feature description */
  description: string;
  /** Whether to show recommended badge */
  recommended?: boolean;
  /** Icon background color */
  color: string;
  /** Optional true value (default: true) */
  trueValue?: any;
  /** Optional false value (default: false) */
  falseValue?: any;
}

/**
 * Card selector option info
 * @description Information displayed for each card option in card selector
 */
export interface CardSelectorOptionInfo {
  /** Icon class (e.g., 'fa-light fa-user-crown') */
  icon: string;
  /** Description text for the option */
  description: string;
  /** Example use cases (optional) */
  examples?: string;
  /** Color for the icon background (hex or color token) */
  color: string;
}

/**
 * Card selector option
 * @description Configuration for individual options in card selector component
 */
export interface CardSelectorOption<T = string> {
  /** Display label for the option */
  label: string;
  /** Value to be selected */
  value: T;
  /** Card display information */
  info: CardSelectorOptionInfo;
}

/**
 * Button severity type
 * @description Severity levels for Button component (full set of options)
 */
export type ButtonSeverity = 'success' | 'info' | 'warn' | 'danger' | 'help' | 'primary' | 'secondary' | 'contrast';

/**
 * Tag severity type
 * @description Severity levels for Tag component
 */
export type TagSeverity = 'success' | 'info' | 'warn' | 'danger' | 'secondary' | 'contrast';

/**
 * Badge severity type
 * @description Severity levels for Badge component
 */
export type BadgeSeverity = 'success' | 'info' | 'warn' | 'danger' | 'secondary' | 'contrast';

/**
 * Component severity type
 * @description Generic severity type for general use (alias for TagSeverity)
 */
export type ComponentSeverity = TagSeverity;

/**
 * Badge severity level options
 * @description Available color schemes for badge components
 */
export interface BadgeSeverityOptions {
  /** Badge color scheme indicating status or priority */
  severity: BadgeSeverity;
}

/**
 * Badge size options
 * @description Available sizes for badge components
 */
export interface BadgeSizeOptions {
  /** Badge size variant */
  size: 'small' | 'large' | 'xlarge';
}

/**
 * Complete badge component properties
 * @description Configuration for LFX badge wrapper component (for count indicators)
 */
export interface BadgeProps {
  /** Badge content (text or number) */
  value: string | number;
  /** Color scheme for the badge */
  severity: BadgeSeverityOptions['severity'];
  /** Size variant for the badge */
  size: BadgeSizeOptions['size'];
  /** Additional CSS classes */
  styleClass: string;
  /** Whether the badge is disabled */
  badgeDisabled: boolean;
}

/**
 * Tag severity level options
 * @description Available color schemes for tag components
 */
export interface TagSeverityOptions {
  /** Tag color scheme indicating status or category */
  severity: TagSeverity;
}

/**
 * Complete tag component properties
 * @description Configuration for LFX tag wrapper component (for labels and status indicators)
 */
export interface TagProps {
  /** Tag content text */
  value: string;
  /** Color scheme for the tag */
  severity?: TagSeverityOptions['severity'];
  /** Icon class or name (e.g., 'fa-light fa-shield') */
  icon?: string;
  /** Whether the corners of the tag are rounded */
  rounded?: boolean;
  /** Additional CSS classes */
  styleClass?: string;
}

/**
 * Button severity level options
 * @description Available color schemes for button components
 */
export interface ButtonSeverityOptions {
  /** Button color scheme indicating action type */
  severity: ButtonSeverity | null | undefined;
}

/**
 * Button icon position options
 * @description Available positions for button icons relative to text
 */
export interface ButtonIconPositionOptions {
  /** Icon placement position */
  iconPos: 'left' | 'right' | 'top' | 'bottom';
}

/**
 * Button size options
 * @description Available sizes for button components
 */
export interface ButtonSizeOptions {
  /** Button size variant */
  size: 'small' | 'large' | undefined;
}

/**
 * Button variant style options
 * @description Available visual styles for button components
 */
export interface ButtonVariantOptions {
  /** Button visual style variant */
  variant: 'outlined' | 'text' | undefined;
}

/**
 * Complete button component properties
 * @description Configuration for LFX button wrapper component
 */
export interface ButtonProps {
  /** Color scheme for the button */
  severity?: ButtonSeverityOptions['severity'];
  /** Icon position relative to text */
  iconPos?: ButtonIconPositionOptions['iconPos'];
  /** Button size variant */
  size?: ButtonSizeOptions['size'];
  /** Visual style variant */
  variant?: ButtonVariantOptions['variant'];
  /** Button text label */
  label?: string;
  /** Icon class or name */
  icon?: string;
  /** Button type attribute */
  type?: string;
  /** Whether button is disabled */
  disabled?: boolean;
  /** Whether button shows loading state */
  loading?: boolean;
  /** Loading spinner icon */
  loadingIcon?: string;
  /** Tab index for keyboard navigation */
  tabindex?: number;
  /** Whether button should auto-focus */
  autofocus?: boolean;
  /** Whether button has raised appearance */
  raised?: boolean;
  /** Whether button has rounded corners */
  rounded?: boolean;
  /** Whether button uses text style */
  text?: boolean;
  /** Whether button uses plain style */
  plain?: boolean;
  /** Whether button uses outlined style */
  outlined?: boolean;
  /** Whether button appears as a link */
  link?: boolean;
  /** Whether button takes full width */
  fluid?: boolean;
  /** Inline styles object */
  style?: Record<string, string | number> | null;
  /** Additional CSS classes */
  styleClass?: string;
  /** Badge content for button */
  badge?: string;
  /** Badge CSS classes */
  badgeClass?: string;
  /** Badge color scheme */
  badgeSeverity?: BadgeSeverityOptions['severity'];
  /** Accessibility label */
  ariaLabel?: string;
}

/**
 * Avatar size options
 * @description Available sizes for avatar components
 */
export interface AvatarSizeOptions {
  /** Avatar size variant */
  size: 'normal' | 'large' | 'xlarge';
}

/**
 * Avatar shape options
 * @description Available shapes for avatar components
 */
export interface AvatarShapeOptions {
  /** Avatar geometric shape */
  shape: 'square' | 'circle';
}

/**
 * Complete avatar component properties
 * @description Configuration for LFX avatar wrapper component
 */
export interface AvatarProps {
  /** Text label for avatar (initials) */
  label?: string;
  /** Icon class or name for avatar */
  icon?: string;
  /** Image URL for avatar */
  image?: string;
  /** Avatar size variant */
  size?: AvatarSizeOptions['size'];
  /** Avatar shape variant */
  shape?: AvatarShapeOptions['shape'];
  /** Inline styles object */
  style?: Record<string, string | number> | null;
  /** Additional CSS classes */
  styleClass?: string;
  /** Accessibility label */
  ariaLabel?: string;
}

/**
 * Time picker size options
 * @description Available sizes for time picker components
 */
export interface TimePickerSizeOptions {
  /** Time picker size variant */
  size: 'small' | 'large';
}

/**
 * Complete time picker component properties
 * @description Configuration for LFX time picker wrapper component
 */
export interface TimePickerProps {
  /** Input field label */
  label?: string;
  /** Placeholder text */
  placeholder?: string;
  /** Whether input is disabled */
  disabled?: boolean;
  /** Whether input is required */
  required?: boolean;
  /** Input size variant */
  size?: TimePickerSizeOptions['size'];
}

/**
 * Message severity type
 * @description Severity levels for Message component (PrimeNG uses 'error' instead of 'danger')
 */
export type MessageSeverity = 'success' | 'info' | 'warn' | 'error' | 'secondary' | 'contrast';

/**
 * Message severity level options
 * @description Available severity levels for message components
 */
export interface MessageSeverityOptions {
  /** Message severity level indicating urgency or type */
  severity: MessageSeverity;
}

/**
 * Message size options
 * @description Available sizes for message components
 */
export interface MessageSizeOptions {
  /** Message size variant */
  size: 'small' | 'large';
}

/**
 * Message variant style options
 * @description Available visual styles for message components
 */
export interface MessageVariantOptions {
  /** Message visual style variant */
  variant: 'text' | 'outlined' | 'simple';
}

/**
 * Complete message component properties
 * @description Configuration for LFX message wrapper component
 */
export interface MessageProps {
  /** Message severity level */
  severity?: MessageSeverityOptions['severity'];
  /** Message text content */
  text?: string;
  /** Whether message can be closed manually */
  closable?: boolean;
  /** Whether to escape HTML in message content */
  escape?: boolean;
  /** Message size variant */
  size?: MessageSizeOptions['size'];
  /** Visual style variant */
  variant?: MessageVariantOptions['variant'];
  /** Custom icon class or name */
  icon?: string;
  /** Close icon class or name */
  closeIcon?: string;
  /** Show animation transition options */
  showTransitionOptions?: string;
  /** Hide animation transition options */
  hideTransitionOptions?: string;
  /** Auto-dismiss time in milliseconds */
  life?: number;
  /** Inline styles object */
  style?: Record<string, string | number> | null;
  /** Additional CSS classes */
  styleClass?: string;
  /** Accessibility label */
  ariaLabel?: string;
}

/**
 * Sidebar menu item configuration
 * @description Structure for sidebar navigation menu items
 */
export interface SidebarMenuItem {
  /** Display label for menu item */
  label: string;
  /** Icon class or name (optional for section headers) */
  icon?: string;
  /** Router link path */
  routerLink?: string;
  /** External URL */
  url?: string;
  /** Target for external links */
  target?: string;
  /** Rel for external links */
  rel?: string;
  /** Whether the link is external (shows external link icon). Defaults to true for items with url property. */
  external?: boolean;
  /** Badge content for notifications */
  badge?: string | number;
  /** Badge severity for styling */
  badgeSeverity?: BadgeSeverityOptions['severity'];
  /** Whether item is disabled */
  disabled?: boolean;
  /** Command to execute on click */
  command?: () => void;
  /** Child menu items for nested navigation */
  items?: SidebarMenuItem[];
  /** Test ID for e2e testing (computed from label if not provided) */
  testId?: string;
  /** Whether this item is a collapsible section header */
  isSection?: boolean;
  /** Default expanded state for sections (defaults to true) */
  expanded?: boolean;
  /** Whether to render a divider line before this item */
  dividerBefore?: boolean;
}

/**
 * Sidebar component properties
 * @description Configuration for LFX sidebar navigation component
 */
export interface SidebarProps {
  /** Menu items to display */
  items: SidebarMenuItem[];
  /** Whether sidebar is collapsed */
  collapsed?: boolean;
  /** Additional CSS classes */
  styleClass?: string;
}

/**
 * Progress item for dashboard metrics
 * @description Structure for progress tracking items
 */
export interface ProgressItem {
  /** Metric label */
  label: string;
  /** Metric value */
  value: string;
  /** Trend direction indicator */
  trend?: 'up' | 'down';
}

/**
 * Progress item with chart data for dashboard metrics
 * @description Extended progress item with Chart.js configuration
 * @note ChartData and ChartOptions types should be imported from chart.js
 */
export interface ProgressItemWithChart extends ProgressItem {
  /** Chart type - line or bar */
  chartType: ChartType;
  /** Chart.js data configuration - supports line and bar charts */
  chartData: ChartData<ChartType>;
  /** Chart.js options configuration - supports line and bar charts */
  chartOptions: ChartOptions<ChartType>;
  /** Optional subtitle text displayed below the value */
  subtitle?: string;
  /** Optional tooltip text to display on hover */
  tooltipText?: string;
  /** Category for filtering metrics (maintainer dashboard) */
  category?: 'code' | 'projectHealth';
  /** FontAwesome icon class (e.g., 'fa-light fa-shield') */
  icon?: string;
}

/**
 * Pending action item for task list
 * @description Structure for pending action items
 */
export interface PendingActionItem {
  /** Action type (e.g., Issue, PR, Review) */
  type: string;
  /** Project or repository badge */
  badge: string;
  /** Action description text */
  text: string;
  /** Icon class for the action type */
  icon: string;
  /** Severity theme for the action */
  severity: TagSeverity;
  /** Button text */
  buttonText: string;
  /** Button link */
  buttonLink?: string;
  /** Optional date string for display (e.g., "Jan 15, 2025 at 10:00 AM") */
  date?: string;
}

/**
 * Meeting item for schedule display
 * @description Structure for meeting information
 */
export interface MeetingItem {
  /** Meeting title */
  title: string;
  /** Meeting time/date */
  time: string;
  /** Number of attendees */
  attendees: number;
}

/**
 * Project item for project list
 * @description Structure for project information from USER_PROJECT_CONTRIBUTIONS_DAILY
 */
export interface ProjectItem {
  /** Project name */
  name: string;
  /** Project URL slug */
  slug: string;
  /** Project logo URL */
  logo?: string;
  /** User's role in project (Maintainer or Contributor) */
  role: 'Maintainer' | 'Contributor';
  /** User's affiliations (comma-separated if multiple) */
  affiliations: string[];
  /** Code activity data for chart (daily values) */
  codeActivities: number[];
  /** Non-code activity data for chart (daily values) */
  nonCodeActivities: number[];
}

/**
 * Project item with pre-generated chart data for dashboard
 * @description Extended project item with Chart.js line chart configurations
 */
export interface ProjectItemWithCharts extends ProjectItem {
  /** Chart.js data configuration for code activities line chart */
  codeActivitiesChartData: ChartData<'line'>;
  /** Chart.js data configuration for non-code activities line chart */
  nonCodeActivitiesChartData: ChartData<'line'>;
}

/**
 * Dashboard meeting card feature flags
 * @description Enabled features for a meeting displayed on dashboard
 */
export interface DashboardMeetingFeatures {
  /** YouTube auto-upload enabled */
  youtubeAutoUploads?: boolean;
  /** Recording enabled */
  recordingEnabled: boolean;
  /** Transcripts enabled */
  transcriptsEnabled?: boolean;
  /** AI summary enabled */
  aiSummary?: boolean;
  /** Chat enabled */
  chatEnabled?: boolean;
}

/**
 * Dashboard meeting card properties
 * @description Configuration for dashboard meeting card component
 */
export interface DashboardMeetingCardProps {
  /** Unique meeting identifier */
  id: string;
  /** Meeting title */
  title: string;
  /** Meeting date string */
  date: string;
  /** Meeting time string */
  time: string;
  /** Meeting type category */
  meetingType: string;
  /** Whether meeting is private */
  isPrivate: boolean;
  /** Enabled meeting features */
  features: DashboardMeetingFeatures;
  /** Project name (optional) */
  project?: string;
}

/**
 * Dashboard quick link
 * @description Navigation shortcut displayed in the dashboard header for write-enabled users
 */
export interface DashboardQuickLink {
  /** Display label for the quick link */
  label: string;
  /** FontAwesome icon class (e.g. 'fa-light fa-calendar') */
  icon: string;
  /** Router link path segments */
  route: string[];
  /** Pre-computed data-testid slug (e.g. 'create-meeting') */
  testId: string;
}

/**
 * Committee selector option
 * @description Configuration for committee selector component options
 */
export interface CommitteeSelectorOption {
  /** Unique identifier for the committee */
  id: string;
  /** Display name for the committee */
  name: string;
  /** Optional member count to display */
  memberCount?: number;
}

/**
 * Relative date display information
 * @description Structure for displaying relative date with styling
 */
export interface RelativeDateInfo {
  /** Display text (e.g., "3 days left", "Closed") */
  text: string;
  /** Tailwind color class for text styling */
  color: string;
}

/**
 * Generic tab option interface
 * @description Configuration for tab options in tab-based navigation
 */
export interface TabOption<T = string> {
  /** Display label for the tab */
  label: string;
  /** Value associated with the tab */
  value: T;
}