✨ Replace CalendarThemeProvider with ThemeData.extensions and unify color palette

Removes CalendarThemeProvider and CalendarThemeData in favor of standard
ThemeData.extensions, unifies all color tokens into a single CalendarViewColors
palette (with matched light/dark sub-palettes), and makes all five BuildContext
theme accessors brightness-aware. Adds ScheduleView theming, updates the example
app to drive all calendar and chrome colors from a single AppColors source of
truth, and introduces runtime theme-mode switching via ThemeController.

Author: lavigarg-simform

CHANGELOG.md

@@ -1,6 +1,9 @@
 # [Unreleased - 29 May 2026]
 
-- [BREAKING] Added `BuildContextExtension` to public API for theme access.
+- [BREAKING] Removed `CalendarThemeProvider` and `CalendarThemeData`. Themes are resolved exclusively from `ThemeData.extensions`.
+- [BREAKING] Added `BuildContextExtension` to public API for theme access; themes now fallback to system theme (brightness-aware) when no extension is registered.
+- [BREAKING] Removed `BuildContextMultiDayViewThemeExtension.multiDayViewTheme` in favor of `BuildContextExtension.multiDayViewColors`.
+- [BREAKING] `highlightColor` was renamed to `cellHighlightColor` in `MonthViewThemeData.copyWith` method for API consistency.
 - Added `ScheduleView`, a scrollable, agenda-style calendar that groups events by day and month. [#101](https://github.com/SimformSolutionsPvtLtd/flutter_calendar_view/issues/101)
 - Added localized `months` and `monthsAbbr` fields to `CalendarLocalizations`, with the `DateTime.getMonthName({abbreviated})` and `DateTime.getMonthYear({abbreviatedMonth})` extensions.
 - [BREAKING] Changed `RecurrenceSettings.weekdays` type from `List<int>` to `List<WeekDays>`. [#509](https://github.com/SimformSolutionsPvtLtd/flutter_calendar_view/issues/509)

doc/documentation.md

@@ -1021,46 +1021,48 @@ To customise `MonthView`, `DayView`, `WeekView` & `MultiDayView` page header use
       ),
 ```
 
-### Theme implementation approaches
+### Theme implementation approach
 
-There are two main ways to customize the theme for calendar views:
+Every theme data class extends `ThemeExtension`, so themes are applied by
+registering them in `ThemeData.extensions`. Each calendar view reads its theme
+from the nearest `ThemeData` (via `context.dayViewColors`, `context.weekViewColors`,
+etc.), falling back to `.light()` / `.dark()` based on `Theme.of(context).brightness`.
 
-1. **Using `CalendarThemeProvider`** (recommended):
-   ```dart
-   CalendarThemeProvider(
-     calendarTheme: CalendarThemeData(
-       monthViewTheme: MonthViewThemeData.light().copyWith(
-         cellInMonthColor: Colors.blue.shade50,
-         cellBorderColor: Colors.blue.shade300,
-       ),
-       dayViewTheme: DayViewThemeData.light(),
-       weekViewTheme: WeekViewThemeData.light(),
-       multiDayViewTheme: MultiDayViewThemeData.light(),
-       scheduleViewTheme: ScheduleViewThemeData.light(),
-     ),
-     child: YourApp(),
-   )
-   ```
+```dart
+// Create custom theme
+final myMonthViewTheme = MonthViewThemeData.light().copyWith(
+  cellInMonthColor: Colors.blue.shade50,
+  cellBorderColor: Colors.blue.shade300,
+);
 
-2. **Using ThemeData extensions** (since all theme data classes extend `ThemeExtension`):
-   ```dart
-   // Create custom theme
-   final myMonthViewTheme = MonthViewThemeData.light().copyWith(
-     cellInMonthColor: Colors.blue.shade50,
-     cellBorderColor: Colors.blue.shade300,
-   );
+// Apply to your app theme — register extensions on BOTH theme and darkTheme
+// so customizations apply in all brightness modes.
+final lightTheme = ThemeData.light().copyWith(
+  extensions: [
+    myMonthViewTheme,
+    DayViewThemeData.light(),
+    WeekViewThemeData.light(),
+    MultiDayViewThemeData.light(),
+    ScheduleViewThemeData.light(),
+  ],
+);
 
-   // Apply to your app theme
-   final theme = ThemeData.light().copyWith(
-     extensions: [
-       myMonthViewTheme,
-       DayViewThemeData.light(),
-       WeekViewThemeData.light(),
-       MultiDayViewThemeData.light(),
-       ScheduleViewThemeData.light(),
-     ],
-   );
-   ```
+final darkTheme = ThemeData.dark().copyWith(
+  extensions: [
+    MonthViewThemeData.dark(),
+    DayViewThemeData.dark(),
+    WeekViewThemeData.dark(),
+    MultiDayViewThemeData.dark(),
+    ScheduleViewThemeData.dark(),
+  ],
+);
+
+MaterialApp(
+  theme: lightTheme,
+  darkTheme: darkTheme,
+  // ...
+);
+```
 
 ### Day view
 * Default timeline text color is `timelineTextColor` in `DayViewThemeData` (defaults to `onSurface`).
@@ -1209,19 +1211,19 @@ Hide divider in multiday view.
 * In `ScheduleDateLayout.top`, the divider beneath the default date header uses `dateDividerColor`; override it per-widget with `defaultDateHeaderDividerSettings` (use `DividerSettings.none()` to hide it).
 
 ```dart
-CalendarThemeProvider(
-  calendarTheme: CalendarThemeData(
-    monthViewTheme: MonthViewThemeData.light(),
-    dayViewTheme: DayViewThemeData.light(),
-    weekViewTheme: WeekViewThemeData.light(),
-    multiDayViewTheme: MultiDayViewThemeData.light(),
-    scheduleViewTheme: ScheduleViewThemeData.light().copyWith(
+final theme = ThemeData.light().copyWith(
+  extensions: [
+    ScheduleViewThemeData.light().copyWith(
       todayHighlightColor: Colors.blue,
       eventTileAlpha: 40,
     ),
-  ),
-  child: YourApp(),
-)
+  ],
+);
+
+MaterialApp(
+  theme: theme,
+  // ...
+);
 ```
 
 # Migration Guides
@@ -1382,6 +1384,56 @@ final end   = organized.endDuration;   // TimeOfDay
 | `DateTime.dateYMD` (Deprecated)              | Use `DateTime.withoutTime` getter          |
 | `MaterialColorExtension.accent` (Deprecated) | No replacement                             |
 
+### 10. Removed `CalendarThemeProvider` and `CalendarThemeData`
+
+`CalendarThemeProvider` and its `CalendarThemeData` payload have been removed. The calendar views never read from them — themes resolve exclusively from `ThemeData.extensions` (via `context.dayViewColors`, `context.scheduleViewColors`, etc.). Register each view's `…ViewThemeData` in `ThemeData.extensions` instead.
+
+**Before (≤ 2.x):**
+```dart
+CalendarThemeProvider(
+  calendarTheme: CalendarThemeData(
+    monthViewTheme: MonthViewThemeData.light(),
+    dayViewTheme: DayViewThemeData.light().copyWith(hourLineColor: Colors.grey),
+    weekViewTheme: WeekViewThemeData.light(),
+    multiDayViewTheme: MultiDayViewThemeData.light(),
+    scheduleViewTheme: ScheduleViewThemeData.light(),
+  ),
+  child: MaterialApp(
+    // ...
+  ),
+);
+```
+
+**After (3.0.0+):**
+```dart
+MaterialApp(
+  theme: ThemeData.light().copyWith(
+    extensions: [
+      MonthViewThemeData.light(),
+      DayViewThemeData.light().copyWith(hourLineColor: Colors.grey),
+      WeekViewThemeData.light(),
+      MultiDayViewThemeData.light(),
+      ScheduleViewThemeData.light(),
+    ],
+  ),
+  // ...
+);
+```
+
+### 11. Removed `BuildContextMultiDayViewThemeExtension.multiDayViewTheme`
+
+The standalone `context.multiDayViewTheme` accessor (from the `BuildContextMultiDayViewThemeExtension` extension) has been removed. Use `context.multiDayViewColors` from `BuildContextExtension` instead — it returns the same `MultiDayViewThemeData`, resolving from `ThemeData.extensions` and falling back to `.light()` / `.dark()` based on the ambient `Theme` brightness.
+
+**Before (≤ 2.x):**
+```dart
+final theme = context.multiDayViewTheme;
+```
+
+**After (3.0.0+):**
+```dart
+final theme = context.multiDayViewColors;
+```
+
 
 ## Migrate from `1.x.x` to latest
 ### ⚠ Note

example/lib/constants.dart

@@ -9,7 +9,7 @@ class AppConstants {
 
   static OutlineInputBorder inputBorder = OutlineInputBorder(
     borderRadius: BorderRadius.circular(7),
-    borderSide: BorderSide(width: 2, color: AppColors.outlineVariant),
+    borderSide: BorderSide(width: 2, color: AppColors.light.outlineVariant),
   );
 
   static InputDecoration get inputDecoration => InputDecoration(

example/lib/extension.dart

@@ -113,9 +113,13 @@ extension TimeOfDayExtension on TimeOfDay {
 }
 
 extension BuildContextExtension on BuildContext {
-  AppThemeExtension get appColors =>
-      Theme.of(this).extension<AppThemeExtension>() ??
-      AppThemeExtension.light();
+  AppThemeExtension get appColors {
+    final theme = Theme.of(this);
+    return theme.extension<AppThemeExtension>() ??
+        (theme.brightness == Brightness.dark
+            ? AppThemeExtension.dark()
+            : AppThemeExtension.light());
+  }
 }
 
 extension LocalizedDateExtension on DateTime {

example/lib/l10n/app_ar.arb

@@ -27,7 +27,10 @@
   "createNewEvent": "إنشاء حدث جديد",
   "updateEvent": "تحديث الحدث",
   "activeView": "العرض النشط:",
-  "darkMode": "الوضع المظلم:",
+  "theme": "السمة",
+  "themeSystem": "النظام",
+  "themeLight": "فاتح",
+  "themeDark": "داكن",
   "eventTitle": "عنوان الحدث",
   "pleaseEnterEventTitle": "الرجاء إدخال عنوان الحدث.",
   "recurringEvent": "حدث متكرر",

example/lib/l10n/app_en.arb

@@ -27,7 +27,10 @@
   "createNewEvent": "Create New Event",
   "updateEvent": "Update Event",
   "activeView": "Active View:",
-  "darkMode": "Dark mode:",
+  "theme": "Theme",
+  "themeSystem": "System",
+  "themeLight": "Light",
+  "themeDark": "Dark",
   "eventTitle": "Event Title",
   "pleaseEnterEventTitle": "Please enter event title.",
   "recurringEvent": "Recurring Event",

example/lib/l10n/app_es.arb

@@ -27,7 +27,10 @@
   "createNewEvent": "Crear nuevo evento",
   "updateEvent": "Actualizar evento",
   "activeView": "Vista activa:",
-  "darkMode": "Modo oscuro:",
+  "theme": "Tema",
+  "themeSystem": "Sistema",
+  "themeLight": "Claro",
+  "themeDark": "Oscuro",
   "eventTitle": "Título del Evento",
   "pleaseEnterEventTitle": "Por favor, introduce el título del evento.",
   "recurringEvent": "Evento Recurrente",

example/lib/main.dart

@@ -9,7 +9,7 @@ import 'l10n/app_localizations.dart';
 import 'localization/calendar_locales.dart';
 import 'localization/locale_controller.dart';
 import 'pages/home_page.dart';
-import 'theme/app_colors.dart';
+import 'theme/theme_controller.dart';
 
 void main() {
   runApp(MyApp());
@@ -21,53 +21,46 @@ class MyApp extends StatefulWidget {
 }
 
 class _MyAppState extends State<MyApp> {
-  bool isDarkMode = false;
   final String initialLocale = 'en';
 
+  /// Created once and kept stable for the app's lifetime so theme/locale
+  /// changes never recreate the controller (which would re-seed all events).
+  final _controller = EventController();
+  final _themeMode = ValueNotifier<ThemeMode>(ThemeMode.system);
+
   @override
   void initState() {
     super.initState();
     CalendarLocales.initialize();
   }
 
+  @override
+  void dispose() {
+    _controller.dispose();
+    _themeMode.dispose();
+    super.dispose();
+  }
+
   // This widget is the root of your application.
   @override
   Widget build(BuildContext context) {
-    return LocaleController(
-      initialLocale: PackageStrings.selectedLocale,
-      child: Builder(
-        builder: (context) {
-          final localeController = LocaleController.of(context);
-          return CalendarThemeProvider(
-            calendarTheme: CalendarThemeData(
-              monthViewTheme: isDarkMode
-                  ? MonthViewThemeData.dark()
-                  : MonthViewThemeData.light(),
-              dayViewTheme: isDarkMode
-                  ? DayViewThemeData.dark()
-                  : DayViewThemeData.light().copyWith(
-                          hourLineColor: AppColors.primary,
-                        )
-                        as DayViewThemeData,
-              weekViewTheme: isDarkMode
-                  ? WeekViewThemeData.dark()
-                  : WeekViewThemeData.light(),
-              multiDayViewTheme: isDarkMode
-                  ? MultiDayViewThemeData.dark()
-                  : MultiDayViewThemeData.light(),
-              scheduleViewTheme: isDarkMode
-                  ? ScheduleViewThemeData.dark()
-                  : ScheduleViewThemeData.light(),
-            ),
-            child: CalendarControllerProvider(
-              controller: EventController(),
-              child: MaterialApp(
+    return CalendarControllerProvider(
+      controller: _controller,
+      child: ThemeController(
+        notifier: _themeMode,
+        child: LocaleController(
+          initialLocale: PackageStrings.selectedLocale,
+          child: Builder(
+            builder: (context) {
+              final localeController = LocaleController.of(context);
+              final themeController = ThemeController.of(context);
+              return MaterialApp(
                 title: 'Flutter Calendar Page Demo',
                 debugShowCheckedModeBanner: false,
                 locale: Locale(localeController.currentLocale),
                 theme: AppTheme.light,
                 darkTheme: AppTheme.dark,
-                themeMode: isDarkMode ? ThemeMode.dark : ThemeMode.light,
+                themeMode: themeController.themeMode,
                 localizationsDelegates: [
                   AppLocalizations.delegate,
                   GlobalMaterialLocalizations.delegate,
@@ -86,14 +79,11 @@ class _MyAppState extends State<MyApp> {
                     PointerDeviceKind.touch,
                   },
                 ),
-                home: HomePage(
-                  onChangeTheme: (isDark) =>
-                      setState(() => isDarkMode = isDark),
-                ),
-              ),
-            ),
-          );
-        },
+                home: const HomePage(),
+              );
+            },
+          ),
+        ),
       ),
     );
   }

example/lib/pages/home_page.dart

@@ -9,11 +9,7 @@ import 'web/web_home_page.dart';
 DateTime get _now => DateTime.now();
 
 class HomePage extends StatefulWidget {
-  const HomePage({this.onChangeTheme, super.key});
-
-  /// Return true for dark mode
-  /// false for light mode
-  final void Function(bool)? onChangeTheme;
+  const HomePage({super.key});
 
   @override
   State<HomePage> createState() => _HomePageState();
@@ -352,8 +348,8 @@ class _HomePageState extends State<HomePage> {
   @override
   Widget build(BuildContext context) {
     return ResponsiveWidget(
-      mobileWidget: MobileHomePage(onChangeTheme: widget.onChangeTheme),
-      webWidget: WebHomePage(onThemeChange: widget.onChangeTheme),
+      mobileWidget: MobileHomePage(),
+      webWidget: WebHomePage(),
     );
   }
 }