/**
 * Kanban type definitions
 * @countermeasure/web-components/visualization/kanban
 */

export interface KanbanAssignee {
  /** Stable user/group identifier. */
  id: string
  /** Display name shown in the avatar tooltip and accessible label. */
  name: string
  /** Free-form classification (e.g. `'user'`, `'team'`). */
  kind?: string
  /** Optional avatar image URL. */
  avatarUrl?: string
}

export interface KanbanSwimlane {
  /** Stable identifier. */
  id: string
  /** Lane title rendered above the cards in that lane. */
  label: string
  /** Predicate determining whether a card belongs in this lane. */
  filter: (card: KanbanCard) => boolean
}

export interface KanbanAction {
  /** Stable identifier passed to `onCardAction`. */
  id: string
  /** Action label shown in the menu. */
  label: string
  /** Optional inline SVG/HTML icon. */
  icon?: string
  /** Predicate used to hide the action contextually. */
  visible?: (card: KanbanCard, columnId: string) => boolean
}

export interface KanbanAnimations {
  /**
   * Animate cards on entrance.
   * @default true
   */
  entrance?: boolean
  /**
   * Animate card moves between columns.
   * @default true
   */
  transition?: boolean
  /**
   * Glow effect when a card moves into the done column.
   * @default true
   */
  completionGlow?: boolean
}

export interface KanbanCard {
  /** Stable identifier. */
  id: string
  /** Card title rendered prominently. */
  title: string
  /** Optional description body rendered below the title. */
  description?: string
  /** Coloured chips rendered on the card. */
  labels?: { text: string; color: string }[]
  /** Single-assignee identifier (legacy — prefer `assignees`). */
  assignee?: string
  /** Priority badge / colour band on the card. */
  priority?: 'low' | 'medium' | 'high' | 'critical'
  /** Free-form metadata tag map. */
  data?: Record<string, string>
  /** Issue tracker key (e.g. `SEC-401`) shown in the header. */
  issueKey?: string
  /** Issue type (e.g. `'task'`, `'story'`, `'bug'`). */
  issueType?: string
  /** Inline SVG/HTML icon to render before `issueKey`. */
  issueTypeIcon?: string
  /** Story-point estimate badge. */
  storyPoints?: number
  /** Manual ordering rank within a column. */
  rank?: number
  /** Parent epic name shown as a small badge. */
  epicName?: string
  /** Sprint name shown as a small badge. */
  sprintName?: string
  /** Identifier of the parent task. */
  parentId?: string
  /** Display label of the parent task. */
  parentLabel?: string
  /** Total subtask count (drives the progress bar). */
  subtaskCount?: number
  /** Number of completed subtasks. */
  subtaskCompleted?: number
  /** Explicit completion percentage (0-100). */
  completionPercentage?: number
  /** Due date — shown as a coloured pill, red if overdue. */
  dueDate?: string | Date
  /** Number of comments on the card. */
  commentCount?: number
  /** Number of attachments on the card. */
  attachmentCount?: number
  /** Multi-assignee list — rendered as overlapping avatars. */
  assignees?: KanbanAssignee[]
}

export interface KanbanColumn {
  /** Stable identifier passed to `onCardMove`. */
  id: string
  /** Column header label. */
  title: string
  /** Cards rendered in the column (order preserved). */
  cards: KanbanCard[]
  /** Optional WIP limit shown in the header (X / limit). */
  limit?: number
  /** Header accent colour. */
  color?: string
  /** Inline SVG/HTML icon rendered next to the column title. */
  icon?: string
  /**
   * Allow the column to be collapsed via the chevron in the header.
   * @default false
   */
  collapsible?: boolean
  /**
   * Initial collapsed state.
   * @default false
   */
  collapsed?: boolean
  /** Message shown in the empty state placeholder. */
  emptyMessage?: string
  /**
   * Render the `+` quick-add button in the column header.
   * @default false
   */
  addButton?: boolean
}

export interface KanbanConfig {
  /** Container element (or selector) the board is mounted into. */
  container: HTMLElement | string
  /** Columns rendered left-to-right. */
  columns: KanbanColumn[]
  /**
   * Enable HTML5 drag-and-drop card moves.
   * @default false
   */
  draggable?: boolean
  /** Fired when a card is moved between (or within) columns. */
  onCardMove?: (
    cardId: string,
    fromColumn: string,
    toColumn: string,
    index: number
  ) => void | Promise<void>
  /** Fired when a card body is clicked. */
  onCardClick?: (card: KanbanCard) => void
  /** Additional CSS class names. */
  className?: string
  /** Fired when a column is collapsed or expanded. */
  onColumnCollapse?: (columnId: string, collapsed: boolean) => void
  /** Fired when the column's `+` add-card button is clicked. */
  onAddCard?: (columnId: string) => void
  /** Optional swimlane groupings rendered as horizontal bands. */
  swimlaneGroups?: KanbanSwimlane[]
  /** Per-card quick actions exposed on hover/menu. */
  actions?: KanbanAction[]
  /** Fired when a quick action is invoked from a card. */
  onCardAction?: (action: string, card: KanbanCard) => void | Promise<void>
  /**
   * Enable card animations. `true` toggles all of them; an object grants finer control.
   * @default true
   */
  animations?: boolean | KanbanAnimations
  /**
   * Card density preset.
   * @default 'spacious'
   */
  density?: 'spacious' | 'compact'
  /**
   * Maximum number of avatar bubbles rendered before collapsing into a `+N`.
   * @default 3
   */
  maxAssigneeAvatars?: number
  /**
   * Maximum number of label chips rendered before collapsing into a `+N`.
   * @default 3
   */
  maxLabels?: number
  /**
   * Truncate long descriptions to this many characters (0 disables).
   * @default 120
   */
  descriptionMaxLength?: number
}
