Merge pull request #17003 from ralphjsmit/rjs/default-date-time-picker-focused-date

feat: ability to set `->defaultFocusedDate()` when opening empty `DateTimePicker`

packages/forms/docs/03-fields/08-date-time-picker.md

@@ -185,6 +185,19 @@ TimePicker::make('appointment_at')
 
 Datalists provide autocomplete options to users when they use the picker. However, these are purely recommendations, and the user is still able to type any value into the input. If you're looking to strictly limit users to a set of predefined options, check out the [select field](select).
 
+### Focusing a default calendar date
+
+By default, if the field has no state, opening the calendar panel will open the calendar at the current date. This might not be convenient for situations where you want to open the calendar on a specific date instead. You can use the `defaultFocusedDate()` to set a default focused date on the calendar:
+
+```php
+use Filament\Forms\Components\DatePicker;
+
+DatePicker::make('custom_starts_at')
+    ->native(false)
+    ->placeholder(now()->startOfMonth())
+    ->defaultFocusedDate(now()->startOfMonth())
+```
+
 ## Adding affix text aside the field
 
 You may place text before and after the input using the `prefix()` and `suffix()` methods:

packages/forms/resources/js/components/date-time-picker.js

@@ -14,6 +14,7 @@ dayjs.extend(utc)
 window.dayjs = dayjs
 
 export default function dateTimePickerFormComponent({
+    defaultFocusedDate,
     displayFormat,
     firstDayOfWeek,
     isAutofocused,
@@ -46,6 +47,8 @@ export default function dateTimePickerFormComponent({
 
         state,
 
+        defaultFocusedDate,
+
         dayLabels: [],
 
         months: [],
@@ -54,13 +57,16 @@ export default function dateTimePickerFormComponent({
             dayjs.locale(locales[locale] ?? locales['en'])
 
             this.$nextTick(() => {
-                this.focusedDate ??= dayjs().tz(timezone)
+                this.focusedDate ??= (
+                    this.getDefaultFocusedDate() ?? dayjs()
+                ).tz(timezone)
                 this.focusedMonth ??= this.focusedDate.month()
                 this.focusedYear ??= this.focusedDate.year()
             })
 
             let date =
                 this.getSelectedDate() ??
+                this.getDefaultFocusedDate() ??
                 dayjs().tz(timezone).hour(0).minute(0).second(0)
 
             if (this.getMaxDate() !== null && date.isAfter(this.getMaxDate())) {
@@ -386,6 +392,20 @@ export default function dateTimePickerFormComponent({
             return date
         },
 
+        getDefaultFocusedDate: function () {
+            if (this.defaultFocusedDate === null) {
+                return null
+            }
+
+            let defaultFocusedDate = dayjs(this.defaultFocusedDate)
+
+            if (!defaultFocusedDate.isValid()) {
+                return null
+            }
+
+            return defaultFocusedDate
+        },
+
         togglePanelVisibility: function () {
             if (!this.isOpen()) {
                 this.focusedDate =

packages/forms/resources/views/components/date-time-picker.blade.php

@@ -10,6 +10,7 @@
     $isSuffixInline = $isSuffixInline();
     $maxDate = $getMaxDate();
     $minDate = $getMinDate();
+    $defaultFocusedDate = $getDefaultFocusedDate();
     $prefixActions = $getPrefixActions();
     $prefixIcon = $getPrefixIcon();
     $prefixLabel = $getPrefixLabel();
@@ -73,6 +74,7 @@
                 @endif
                 x-load-src="{{ \Filament\Support\Facades\FilamentAsset::getAlpineComponentSrc('date-time-picker', 'filament/forms') }}"
                 x-data="dateTimePickerFormComponent({
+                            defaultFocusedDate: @js($defaultFocusedDate),
                             displayFormat:
                                 '{{ convert_date_format($getDisplayFormat())->to('day.js') }}',
                             firstDayOfWeek: {{ $getFirstDayOfWeek() }},
@@ -222,7 +224,7 @@
                                                 ! dayIsSelected(day) &&
                                                 focusedDate.date() !== day &&
                                                 ! dayIsDisabled(day),
-                                            'bg-gray-50 dark:bg-white/5':
+                                            'bg-gray-100 dark:bg-white/10':
                                                 focusedDate.date() === day &&
                                                 ! dayIsSelected(day) &&
                                                 ! dayIsDisabled(day),

packages/forms/src/Components/DateTimePicker.php

@@ -49,6 +49,8 @@ class DateTimePicker extends Field implements Contracts\HasAffixActions
 
     protected CarbonInterface | string | Closure | null $minDate = null;
 
+    protected CarbonInterface | string | Closure | null $defaultFocusedDate = null;
+
     protected string | Closure | null $timezone = null;
 
     protected string | Closure | null $locale = null;
@@ -216,6 +218,13 @@ class DateTimePicker extends Field implements Contracts\HasAffixActions
         return $this;
     }
 
+    public function defaultFocusedDate(CarbonInterface | string | Closure | null $date): static
+    {
+        $this->defaultFocusedDate = $date;
+
+        return $this;
+    }
+
     /**
      * @param  array<DateTime | string> | Closure  $dates
      */
@@ -420,6 +429,11 @@ class DateTimePicker extends Field implements Contracts\HasAffixActions
         return $this->evaluate($this->minDate);
     }
 
+    public function getDefaultFocusedDate(): ?string
+    {
+        return $this->evaluate($this->defaultFocusedDate);
+    }
+
     /**
      * @return array<DateTime | string>
      */