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

part of '../../../scheduling_engine.dart';

/// Starter notice type returned by scheduling operations.
///
/// A notice is presentation-friendly context about an operation. It intentionally
/// carries both text and a structured [type] so the UI can decide whether to show
/// it as neutral info, movement, overlap, or failure.
class SchedulingNotice {
  /// Creates a `SchedulingNotice` 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.
  SchedulingNotice(
    this.message, {
    this.type = SchedulingNoticeType.info,
    this.taskId,
    this.issueCode,
    this.movementCode,
    this.conflictCode,
    Map<String, Object?> parameters = const <String, Object?>{},
  }) : parameters = Map<String, Object?>.unmodifiable(parameters);

  /// Human-readable message safe to surface in UI or logs.
  final String message;

  /// Structured category for UI styling and tests.
  final SchedulingNoticeType type;

  /// Optional task related to this notice. Null means the notice applies to the
  /// whole operation.
  final String? taskId;

  /// Stable issue code for validation/no-slot/no-op outcomes.
  final SchedulingIssueCode? issueCode;

  /// Stable movement code for placement changes.
  final SchedulingMovementCode? movementCode;

  /// Stable conflict code for overlap outcomes.
  final SchedulingConflictCode? conflictCode;

  /// Structured notice parameters for callers that need more context.
  final Map<String, Object?> parameters;
}
