Fix todayBorder todayBorder color is incorrectly overridden by todayForegroundColor in CalendarDatePicker (flutter#178792)

- Fix flutter#177911
- In this PR:
- Avoid auto-overriding border side color with `dayForegroundColor` when
users specify an explicit border color
    - Improve `todayBorder` documentation to clarify cases can happen.
- Add an opacity check: this is because if we don't respect/specify an
explicit border color, we still need to keep enabled/disabled states
(state-aware) that `dayForegroundColor` always does:


https://github.com/flutter/flutter/blob/de3f804590cea1e68065b93f4a0b55a7a451f233/packages/flutter/lib/src/material/date_picker_theme.dart#L1174

So we need a fallback compatibility here:

```dart
final bool hasCustomBorderColor =
        datePickerTheme.todayBorder != null && datePickerTheme.todayBorder?.color.opacity != 0.0;
    final BorderSide todayBorderSide = hasCustomBorderColor
        ? datePickerTheme.todayBorder!
        : (datePickerTheme.todayBorder ?? defaults.todayBorder!).copyWith(
            color: dayForegroundColor,
          );
```

- Added 3 tests in `calendar_date_picker_test.dart‎`.
- Update test data in `date_picker_theme_test.dart`: Updated todayBorder
from `BorderSide(width: 3)` to `BorderSide(width: 3, color:
Color(0x00000000))` to maintain backward compatible behavior in tests:
after changing color to transparent, it should fall back to
`todayForegroundColor`. This is because the test's real purpose was to
verify theme properties work, and it was expecting foreground color
(which is the bug reported).

<details open>
<summary>Demo</summary>

| Before | After |
| --------------- | --------------- |
<img width="400"
src="https://github.com/user-attachments/assets/59c70071-d278-46f8-a566-40589cf01f9a">
| <img width="400"
src="https://github.com/user-attachments/assets/a4309fb0-7360-4c11-a9c1-dd1f1ebf9190">
</details>

## 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.

If you need help, consider asking for advice on the #hackers-new channel
on [Discord].

**Note**: The Flutter team is currently trialing the use of [Gemini Code
Assist for
GitHub](https://developers.google.com/gemini-code-assist/docs/review-github-code).
Comments from the `gemini-code-assist` bot should not be taken as
authoritative feedback from the Flutter team. If you find its comments
useful you can update your code accordingly, but if you are unsure or
disagree with the feedback, please feel free to wait for a Flutter team
member's review for guidance on which automated comments should be
addressed.

<!-- Links -->
[Contributor Guide]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#overview
[Tree Hygiene]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md
[test-exempt]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#tests
[Flutter Style Guide]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md
[Features we expect every widget to implement]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md#features-we-expect-every-widget-to-implement
[CLA]: https://cla.developers.google.com/
[flutter/tests]: https://github.com/flutter/tests
[breaking change policy]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#handling-breaking-changes
[Discord]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Chat.md
[Data Driven Fixes]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Data-driven-Fixes.md

---------

Signed-off-by: huycozy <huy@nevercode.io>
Co-authored-by: Tong Mu <dkwingsmt@users.noreply.github.com>

Author: huycozy

packages/flutter/lib/src/material/calendar_date_picker.dart

@@ -1213,14 +1213,17 @@ class _DayState extends State<_Day> {
       (DatePickerThemeData? theme) => theme?.dayShape,
       states,
     )!;
+    final bool hasCustomBorderColor =
+        datePickerTheme.todayBorder != null && datePickerTheme.todayBorder!.color.opacity != 0.0;
+    final BorderSide todayBorderSide = hasCustomBorderColor
+        ? datePickerTheme.todayBorder!
+        : (datePickerTheme.todayBorder ?? defaults.todayBorder!).copyWith(
+            color: dayForegroundColor,
+          );
     final decoration = widget.isToday
         ? ShapeDecoration(
             color: dayBackgroundColor,
-            shape: dayShape.copyWith(
-              side: (datePickerTheme.todayBorder ?? defaults.todayBorder!).copyWith(
-                color: dayForegroundColor,
-              ),
-            ),
+            shape: dayShape.copyWith(side: todayBorderSide),
           )
         : ShapeDecoration(color: dayBackgroundColor, shape: dayShape);
 

packages/flutter/lib/src/material/date_picker_theme.dart

@@ -276,8 +276,10 @@ class DatePickerThemeData with Diagnosticable {
   /// [DatePickerDialog.currentDate] label in the grid of the date
   /// picker.
   ///
-  /// The border side's [BorderSide.color] is not used,
-  /// [todayForegroundColor] is used instead.
+  /// If the border side's [BorderSide.color] is transparent (has 0 opacity),
+  /// [todayForegroundColor] is used instead. Otherwise, the border's color
+  /// is used as specified. To omit the border entirely,
+  /// set [todayBorder] to [BorderSide.none].
   ///
   /// {@tool dartpad}
   /// This sample demonstrates how to customize the day selector shape decoration

packages/flutter/test/material/calendar_date_picker_test.dart

@@ -540,6 +540,79 @@ void main() {
       );
     });
 
+    testWidgets('Non-null todayBorder color should be respected over foreground color', (
+      WidgetTester tester,
+    ) async {
+      const Color customBorderColor = Colors.red;
+      await tester.pumpWidget(
+        calendarDatePicker(
+          initialDate: DateTime(2016, 1, 15),
+          currentDate: DateTime(2016, 1, 2),
+          theme: ThemeData(
+            datePickerTheme: DatePickerThemeData(
+              todayBorder: const BorderSide(color: customBorderColor),
+              todayForegroundColor: WidgetStateProperty.all(Colors.blue),
+            ),
+          ),
+        ),
+      );
+      expect(
+        Material.of(tester.element(find.text('2'))),
+        // The current day should be painted with the custom border color.
+        paints..circle(color: customBorderColor, style: PaintingStyle.stroke, strokeWidth: 1.0),
+      );
+    });
+
+    testWidgets('Non-null todayBorder color is used even when disabled', (
+      WidgetTester tester,
+    ) async {
+      const Color customBorderColor = Colors.red;
+      await tester.pumpWidget(
+        calendarDatePicker(
+          firstDate: DateTime(2016, 1, 3),
+          lastDate: DateTime(2016, 1, 31),
+          currentDate: DateTime(2016, 1, 2), // not between first and last
+          initialDate: DateTime(2016, 1, 5),
+          theme: ThemeData(
+            datePickerTheme: DatePickerThemeData(
+              todayBorder: const BorderSide(color: customBorderColor),
+              todayForegroundColor: WidgetStateProperty.all(Colors.blue),
+            ),
+          ),
+        ),
+      );
+      expect(
+        Material.of(tester.element(find.text('2'))),
+        // The current day should be painted with the custom border color,
+        // not with foreground color opacity applied, even it's disabled day.
+        paints..circle(color: customBorderColor, style: PaintingStyle.stroke, strokeWidth: 1.0),
+      );
+    });
+
+    testWidgets('Transparent todayBorder should fall back to foreground color', (
+      WidgetTester tester,
+    ) async {
+      const Color customForegroundColor = Colors.green;
+      await tester.pumpWidget(
+        calendarDatePicker(
+          initialDate: DateTime(2016, 1, 15),
+          currentDate: DateTime(2016, 1, 2),
+          theme: ThemeData(
+            datePickerTheme: DatePickerThemeData(
+              todayBorder: const BorderSide(color: Color(0x00000000)),
+              todayForegroundColor: WidgetStateProperty.all(customForegroundColor),
+            ),
+          ),
+        ),
+      );
+      expect(
+        Material.of(tester.element(find.text('2'))),
+        // The current day should use the foreground color since
+        // todayBorder color is transparent.
+        paints..circle(color: customForegroundColor, style: PaintingStyle.stroke, strokeWidth: 1.0),
+      );
+    });
+
     testWidgets('Selecting date does not switch picker to year selection', (
       WidgetTester tester,
     ) async {

packages/flutter/test/material/date_picker_theme_test.dart

@@ -27,7 +27,7 @@ void main() {
     dayShape: MaterialStatePropertyAll<OutlinedBorder>(RoundedRectangleBorder()),
     todayForegroundColor: MaterialStatePropertyAll<Color>(Color(0xfffffff8)),
     todayBackgroundColor: MaterialStatePropertyAll<Color>(Color(0xfffffff9)),
-    todayBorder: BorderSide(width: 3),
+    todayBorder: BorderSide(width: 3, color: Color(0x00000000)),
     yearStyle: TextStyle(fontSize: 13),
     yearForegroundColor: MaterialStatePropertyAll<Color>(Color(0xfffffffa)),
     yearBackgroundColor: MaterialStatePropertyAll<Color>(Color(0xfffffffb)),
@@ -509,7 +509,7 @@ void main() {
         'dayShape: WidgetStatePropertyAll(RoundedRectangleBorder(BorderSide(width: 0.0, style: none), BorderRadius.zero))',
         'todayForegroundColor: WidgetStatePropertyAll(${const Color(0xfffffff8)})',
         'todayBackgroundColor: WidgetStatePropertyAll(${const Color(0xfffffff9)})',
-        'todayBorder: BorderSide(width: 3.0)',
+        'todayBorder: BorderSide(color: Color(alpha: 0.0000, red: 0.0000, green: 0.0000, blue: 0.0000, colorSpace: ColorSpace.sRGB), width: 3.0)',
         'yearStyle: TextStyle(inherit: true, size: 13.0)',
         'yearForegroundColor: WidgetStatePropertyAll(${const Color(0xfffffffa)})',
         'yearBackgroundColor: WidgetStatePropertyAll(${const Color(0xfffffffb)})',