From 4a6965c4e623f5ede9a42d3a9fcda4727bcb4fbb Mon Sep 17 00:00:00 2001
From: Kishan Rathore <34465683+rkishan516@users.noreply.github.com>
Date: Sat, 19 Apr 2025 04:20:08 +0530
Subject: [PATCH] Docs: Update date picker theme day color properties doc
 (#166122)

Docs: Update date picker theme day color properties doc
fixes: #161052
Part 2 of #164972

## Pre-launch Checklist

- [x] I read the [Contributor Guide] and followed the process outlined
there for submitting PRs.
- [x] I read the [Tree Hygiene] wiki page, which explains my
responsibilities.
- [x] I read and followed the [Flutter Style Guide], including [Features
we expect every widget to implement].
- [x] I signed the [CLA].
- [x] I listed at least one issue that this PR fixes in the description
above.
- [x] I updated/added relevant documentation (doc comments with `///`).
- [x] I added new tests to check the change I am making, or this PR is
[test-exempt].
- [x] I followed the [breaking change policy] and added [Data Driven
Fixes] where supported.
- [x] All existing and new tests are passing.

---------

Co-authored-by: Qun Cheng <36861262+QuncCccccc@users.noreply.github.com>
---
 .../lib/src/material/date_picker_theme.dart   | 50 +++++++++++++++++++
 1 file changed, 50 insertions(+)

diff --git a/packages/flutter/lib/src/material/date_picker_theme.dart b/packages/flutter/lib/src/material/date_picker_theme.dart
index b8b19712877..835cc8e1d02 100644
--- a/packages/flutter/lib/src/material/date_picker_theme.dart
+++ b/packages/flutter/lib/src/material/date_picker_theme.dart
@@ -165,14 +165,64 @@ class DatePickerThemeData with Diagnosticable {
   /// grid of the date picker.
   ///
   /// This will be used instead of the color provided in [dayStyle].
+  ///
+  /// This supports different colors based on the [WidgetState]s of
+  /// the day button, such as `WidgetState.selected`, `WidgetState.hovered`,
+  /// `WidgetState.focused`, and `WidgetState.disabled`.
+  ///
+  /// ```dart
+  /// dayBackgroundColor: WidgetStateProperty.resolveWith((Set<WidgetState> states) {
+  ///   if (states.contains(WidgetState.selected)) {
+  ///     return Theme.of(context).colorScheme.primary;
+  ///   }
+  ///   return null; // Use the default color.
+  /// })
+  /// ```
+  ///
+  /// See also:
+  ///   * [dayOverlayColor] which applies an overlay over the day labels depending on the [WidgetState].
   final WidgetStateProperty<Color?>? dayForegroundColor;
 
   /// Overrides the default color used to paint the background of the
   /// day labels in the grid of the date picker.
+  ///
+  /// This supports different colors based on the [WidgetState]s of
+  /// the day button, such as `WidgetState.selected`, `WidgetState.hovered`,
+  /// `WidgetState.focused`, and `WidgetState.disabled`.
+  ///
+  /// ```dart
+  /// dayBackgroundColor: WidgetStateProperty.resolveWith((Set<WidgetState> states) {
+  ///   if (states.contains(WidgetState.selected)) {
+  ///     return Theme.of(context).colorScheme.primary;
+  ///   }
+  ///   return null; // Use the default color.
+  /// })
+  /// ```
+  /// See also:
+  ///   * [dayOverlayColor] which applies an overlay over the day labels depending on the [WidgetState].
   final WidgetStateProperty<Color?>? dayBackgroundColor;
 
   /// Overrides the default highlight color that's typically used to
   /// indicate that a day in the grid is focused, hovered, or pressed.
+  ///
+  /// This supports different colors based on the [WidgetState]s of
+  /// the day button. The overlay color is usually used with an opacity to
+  /// create hover, focus, and press effects.
+  ///
+  /// ```dart
+  /// dayOverlayColor: WidgetStateProperty.resolveWith((Set<WidgetState> states) {
+  ///   if (states.contains(WidgetState.pressed)) {
+  ///     return Colors.blue.withOpacity(0.12);
+  ///   }
+  ///   if (states.contains(WidgetState.hovered)) {
+  ///     return Colors.blue.withOpacity(0.08);
+  ///   }
+  ///   if (states.contains(WidgetState.focused)) {
+  ///     return Colors.blue.withOpacity(0.12);
+  ///   }
+  ///   return null; // Use the default color.
+  /// })
+  /// ```
   final WidgetStateProperty<Color?>? dayOverlayColor;
 
   /// Overrides the default shape used to paint the shape decoration of the