// SPDX-FileCopyrightText: 2026 FocusFlow contributors
// SPDX-License-Identifier: AGPL-3.0-only

part of '../../timeline_state.dart';

/// Display-ready timeline item derived from a domain [Task].
class TimelineItem {
  /// Creates a `TimelineItem` instance with the values required by its invariants.
  /// Callers should pass already-normalized scheduler data because validation and defaulting belong at the model or service boundary, not in arbitrary UI code.
  TimelineItem({
    required this.id,
    required this.displayTitle,
    required this.taskType,
    required this.projectColorToken,
    required this.backgroundToken,
    required this.rewardIconToken,
    required this.difficultyIconToken,
    required this.showsExplicitTime,
    required List<TimelineQuickAction> quickActions,
    required this.category,
    this.start,
    this.end,
    this.actualStart,
    this.actualEnd,
    this.completedAt,
    this.updatedAt,
    this.durationMinutes,
  }) : quickActions = List<TimelineQuickAction>.unmodifiable(quickActions);

  /// Stable id of the source item.
  final String id;

  /// Text shown as the item name.
  final String displayTitle;

  /// Source scheduling behavior type.
  final TaskType taskType;

  /// Border/project color token. This is a key, not a raw color.
  final String projectColorToken;

  /// Translucent background token derived from [taskType].
  final TimelineBackgroundToken backgroundToken;

  /// First icon token.
  final TimelineRewardIconToken rewardIconToken;

  /// Second icon token.
  final TimelineDifficultyIconToken difficultyIconToken;

  /// Whether the item should render explicit start/end time text.
  final bool showsExplicitTime;

  /// Timeline placement start, if the source item has one.
  final DateTime? start;

  /// Timeline placement end, if the source item has one.
  final DateTime? end;

  /// Actual work start instant, if the source task recorded one.
  final DateTime? actualStart;

  /// Actual work end instant, if the source task recorded one.
  final DateTime? actualEnd;

  /// Completion instant, if the source task has been completed.
  final DateTime? completedAt;

  /// Source task update timestamp, when the item was mapped from a task.
  final DateTime? updatedAt;

  /// Duration display value for flexible task cards.
  final int? durationMinutes;

  /// Quick actions available from this item.
  final List<TimelineQuickAction> quickActions;

  /// Whether this is a normal task card or a non-task overlay.
  final TimelineItemCategory category;
}
