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

/// Defines the app composition protocol used by FocusFlow widgets.
library;

import 'package:scheduler_core/scheduler_core.dart';

import '../controllers/backlog_board_controller.dart';
import '../controllers/scheduler_command_controller.dart';
import '../controllers/scheduler_read_controller.dart';
import '../controllers/selected_date_controller.dart';
import '../controllers/today_screen_controller.dart';

/// Runtime-independent composition surface consumed by the app shell.
abstract interface class SchedulerAppComposition {
  /// Human-readable label for the selected local date.
  String get dateLabel;

  /// Initial selected owner-local planning date.
  CivilDate get initialDate;

  /// Default project id used by quick-capture commands.
  String get defaultProjectId;

  /// Formats [date] for compact UI date labels.
  String dateLabelFor(CivilDate date);

  /// Creates the controller that owns the visible planning date.
  SelectedDateController createSelectedDateController();

  /// Creates the controller used by the compact Today screen.
  TodayScreenController createTodayScreenController({
    required SelectedDateController selectedDates,
  });

  /// Creates the controller used by the Backlog board screen.
  BacklogBoardController createBacklogBoardController({
    required SelectedDateController selectedDates,
  });

  /// Creates a read controller for the settings screen.
  UiReadController<OwnerSettings> createOwnerSettingsController();

  /// Creates the command controller used by interactive scheduler controls.
  SchedulerCommandController createCommandController({
    required ReadRefresh refreshReads,
    required SelectedDateReader selectedDate,
  });

  /// Releases resources owned by the composition.
  Future<void> dispose();
}