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

part of '../../today_state.dart';

/// One item in the Today read model, with task status/source metadata.
class TodayTimelineItem {
  /// Creates a `TodayTimelineItem` 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.
  TodayTimelineItem({
    required this.item,
    required this.source,
    this.taskStatus,
    this.taskId,
    this.lockedBlockId,
    this.lockedOverrideId,
    this.hiddenByDefault = false,
    this.isCurrent = false,
    this.isNextRequired = false,
    this.isNextFlexible = false,
  });

  /// Display-ready framework-neutral item.
  final TimelineItem item;

  /// Repository/domain source for this item.
  final TodayTimelineItemSource source;

  /// Source task status. Null for locked occurrences.
  final TaskStatus? taskStatus;

  /// Source task id, when [source] is [TodayTimelineItemSource.task].
  final String? taskId;

  /// Source locked block id, when this is a locked occurrence.
  final String? lockedBlockId;

  /// Source override id, when this occurrence was replaced or added.
  final String? lockedOverrideId;

  /// Whether the locked source is normally hidden.
  final bool hiddenByDefault;

  /// Whether this item is the current selected item for the read instant.
  final bool isCurrent;

  /// Whether this item is the next required item.
  final bool isNextRequired;

  /// Whether this item is the optional next flexible item.
  final bool isNextFlexible;

  /// Stable item id.
  String get id => item.id;

  /// Timeline start.
  DateTime? get start => item.start;

  /// Timeline end.
  DateTime? get end => item.end;

  /// Source task behavior type.
  TaskType get taskType => item.taskType;

  /// Project/border color token.
  String get projectColorToken => item.projectColorToken;

  /// Structured quick actions available for this item.
  List<TimelineQuickAction> get quickActions => item.quickActions;

  /// Return a copy with selection flags changed.
  TodayTimelineItem copyWith({
    bool? isCurrent,
    bool? isNextRequired,
    bool? isNextFlexible,
  }) {
    return TodayTimelineItem(
      item: item,
      source: source,
      taskStatus: taskStatus,
      taskId: taskId,
      lockedBlockId: lockedBlockId,
      lockedOverrideId: lockedOverrideId,
      hiddenByDefault: hiddenByDefault,
      isCurrent: isCurrent ?? this.isCurrent,
      isNextRequired: isNextRequired ?? this.isNextRequired,
      isNextFlexible: isNextFlexible ?? this.isNextFlexible,
    );
  }
}
