New component plan: FluentDateRangePicker

[Vincent Baaij (vnbaaij)]

Following the discussion in #5019, I propose we ad a new component to the library: the FluentDateRangePicker

Based on going back and forth with my assistant, we came up with the below plan. Please read ,suggest, comment, etc.

Create FluentDateRangePicker component

Understanding

Create FluentDateRangePicker<TValue> — a dedicated date range picker that wraps FluentCalendar<TValue> in CalendarSelectMode.Range mode. It binds to two independent TValue parameters (Start and End), and uses FluentInputBase<(TValue, TValue)> internally to gain form integration, validation, and field properties (Label, Disabled, Required, etc.). The control must support both popup selection and accessible manual entry of a start/end range through a masked FluentTextInput, while still auto-swapping Start/End if End < Start.

Assumptions

• Inherits FluentInputBase<(TValue, TValue)> (ValueTuple of two dates as the internal binding).
• Public API: @bind-Start and @bind-End as independent TValue parameters that map to/from the tuple CurrentValue.
• SelectMode is hardcoded to CalendarSelectMode.Range — no user control.
• Constructor guard: if (typeof(TValue).IsNotDateType()) throw.
• Re-declare 8 calendar-specific parameters: Culture, MinDate, MaxDate, DisabledDateFunc, DisabledCheckAllDaysOfMonthYear, DisabledSelectable, DayFormat, View.
• Inherit all FluentInputBase members: Label, Disabled, ReadOnly, Required, Message*, AriaLabel, Autofocus, Name, FocusLost, etc.
• FormatValueAsString: "start – end" format or empty if both null.
• TryParseValueFromString: custom parsing for manually entered range text and validation errors for incomplete/invalid ranges.
• Add AutoClose parameter support so consumers can control whether the popup closes automatically when a complete range is selected.
• Default AutoClose to true to preserve the planned close-on-complete behavior.
• Built-in validation: if End < Start, auto-swap them and trigger SelectedDatesChanged.
• Support SelectDatesHover for preset ranges (e.g., "this week", "this month").
• The text input must remain editable for accessibility and support manual start/end date entry.
• Use FluentTextInput mask support plus customized parsing/validation rather than a display-only input.
• Expose the relevant FluentTextInput mask-related parameters through FluentDateRangePicker so developers can configure them.
• Make the start/end separator used in the combined masked input developer-configurable.
• If no MaskPattern is provided, auto-generate the pattern from the active culture/date format and configured separator so both start and end dates can be entered.
• If a developer provides a custom MaskPattern, validate that it supports entry of both Start and End values in the combined range input.
• New code and tests must preserve the repository's 98% minimum line coverage requirement enforced in .github/workflows/build-core-lib.yml and tests/_StartCodeCoverage.ps1.

Approach

FluentDateRangePicker.razor.cs

FluentInputBase<(TValue, TValue)>
    └── FluentDateRangePicker<TValue>
            ├── [Parameter] Start, StartChanged        (TValue bound pair)
            ├── [Parameter] End, EndChanged
            ├── [Parameter] Culture, MinDate, MaxDate, DisabledDateFunc, ...  (8 calendar params)
            ├── [Parameter] SelectDatesHover, DaysTemplate, PickerMonthChanged, OnCalendarOpen
            ├── [Parameter] Icon, Appearance, Placeholder, AutoClose, MaskPattern, MaskLazy, MaskPlaceholder, RangeSeparator
            ├── bool Opened
            ├── Properties mapping Start/End ↔ CurrentValue (the tuple)
            ├── FormatValueAsString() → "Jan 5, 2024 – Jan 12, 2024"
            ├── TryParseValueFromString() → parse masked start/end text into tuple + validation message
            ├── Range text parsing helpers aligned with current culture/date format
            ├── Effective mask helpers: use developer-provided mask or generate from culture/date format
            ├── Custom mask validation helpers to ensure both start and end values can be entered
            ├── OnTextInputClickAsync() → toggle popup
            ├── OnIconKeydownAsync() → Enter/Space opens + focuses calendar
            ├── OnSelectedDatesChangedAsync() → extract start/end from calendar, auto-swap if needed, close popup when AutoClose is true
            └── ClassValue, StyleValue, GetPlaceholder helpers

FluentDateRangePicker.razor

• Editable FluentTextInput with calendar icon in EndTemplate.
• Forward MaskPattern, MaskLazy, and MaskPlaceholder to the internal FluentTextInput so developers can configure masking behavior.
• If MaskPattern is omitted, apply an auto-generated culture-aware range mask that supports both start and end date entry and uses the configured separator.
• Bind the text input through the component's custom tuple formatting/parsing so typed values participate in form validation.
• Use the configured separator consistently in formatting, parsing, and mask generation.
• Reject invalid developer-provided masks early with validation/guard logic when they cannot represent both start and end values in the combined input.
• FluentPopover containing FluentCalendar with SelectMode="CalendarSelectMode.Range" hardcoded.
• Calendar wired to internal SelectedDates (derived from Start/End), with all 8 params forwarded.

FluentDateRangePicker.razor.css

• Minimal stub.

ComponentBaseTests.cs

• Add FluentDateRangePicker<> entry with DateTime type arg.

InputBaseTests.cs

• Add typeof(FluentDateRangePicker<>) to Excluded array.

FluentDateRangePickerTests.razor

• Coverage-oriented bUnit test suite for default render, null/partial/full value states, click and keyboard open, disabled/readonly guards, manual masked entry, valid typed range parsing, invalid/incomplete typed range validation, auto-generated culture-based masks, configurable separator behavior, forwarded mask parameters, invalid custom mask rejection, range completion popup close, display formatting, auto-swap on End < Start, min/max forwarding, parameter pass-through, AutoClose=true and AutoClose=false behavior, and SelectDatesHover preset ranges.
• Add enough branch coverage to keep the component work aligned with the repository 98% minimum line coverage rule.

DateRangePickerExample.razor

• Basic range selection, manual masked entry, configurable separator behavior, default culture-generated mask behavior, custom mask usage, AutoClose usage, and preset ranges demo.

FluentDateRangePicker.md

• Documentation page, including keyboard/manual entry guidance, configurable separator behavior, auto-generated and custom mask behavior, and validation rules.

tests/_StartCodeCoverage.ps1

• Use the existing merged coverage script to validate that the new component and tests keep line coverage at or above 98%.

Key Files

• src/Core/Components/DateTime/FluentDateRangePicker.razor.cs — code-behind (new)
• src/Core/Components/DateTime/FluentDateRangePicker.razor — markup (new)
• src/Core/Components/DateTime/FluentDateRangePicker.razor.css — styles (new)
• src/Core/Components/DateTime/FluentCalendarBase.cs — reference only, NOT modified
• src/Core/Components/DateTime/CalendarTValue.cs — reference for IsNotDateType guard
• tests/Core/Components/DateTimes/FluentDateRangePickerTests.razor — bUnit tests with coverage-driven scenarios (new)
• tests/Core/Components/Base/ComponentBaseTests.cs — add entry (modify)
• tests/Core/Components/Base/InputBaseTests.cs — add to Excluded (modify)
• tests/_StartCodeCoverage.ps1 — local coverage validation at the repository 98% threshold
• .github/workflows/build-core-lib.yml — CI coverage threshold reference (MIN_COVERAGE: 98)
• examples/.../DatePicker/Examples/DateRangePickerExample.razor — demo (new)
• examples/.../DatePicker/FluentDateRangePicker.md — docs (new)

Risks & Open Questions

• Tuple binding in FluentInputBase<(TValue, TValue)> — is there precedent in the codebase? Check if ValueTuple works cleanly with edit context validation.
• Masking and parsing must work with supported date types and culture-aware date formats; when no mask is supplied, generate one from the active format/culture.
• Developer-provided masks must be validated so they can represent both start and end values plus the configured separator in the combined input.
• Separator configuration must remain compatible with parsing, formatting, and culture-based default mask generation.
• Auto-swap on End < Start — should this also trigger SelectedDatesChanged? Yes; it's a semantic correction.
• Should we expose an IEnumerable<TValue> getter that returns new[] { Start, End } for consumers who prefer that interface? Yes, add as a convenience property.
• AutoClose=false changes the post-selection interaction model; tests must verify the popup remains open after a complete range is selected.
• Manual entry introduces additional validation branches for partial masks, invalid dates, and malformed separators; the suite must explicitly cover these so the added component does not pull core coverage below 98%.

Steps

1. Create FluentDateRangePicker.razor.cs
   • Inherit FluentInputBase<(TValue, TValue)>
   • Constructor guard with IsNotDateType
   • Start / End parameters backed by tuple CurrentValue
   • Re-declare 8 calendar params + range/UI params, including AutoClose, MaskPattern, MaskLazy, MaskPlaceholder, and RangeSeparator
   • Implement FormatValueAsString, TryParseValueFromString, helper methods for parsing a typed start/end range, and effective mask generation/validation logic
   • OnTextInputClickAsync, OnIconKeydownAsync, OnSelectedDatesChangedAsync (with auto-swap and conditional close behavior)
   • Add convenience SelectedDates property returning new[] { Start, End }
   • ClassValue, StyleValue, GetPlaceholder helpers
2. Create FluentDateRangePicker.razor
   • Editable FluentTextInput with icon EndTemplate
   • Forward developer-settable mask parameters to the inner text input
   • Apply the configured separator consistently in the combined text value
   • Apply developer-provided MaskPattern or a culture-generated default mask for the combined start/end value
   • FluentPopover + FluentCalendar with SelectMode="Range" hardcoded
3. Create FluentDateRangePicker.razor.css
4. Register in ComponentBaseTests.cs
   • Add FluentDateRangePicker<> → DateTime entry
5. Update InputBaseTests.cs
   • Add typeof(FluentDateRangePicker<>) to Excluded array
6. Create FluentDateRangePickerTests.razor
   • Cover default render plus null, partial, and full range states
   • Cover popup open/close, keyboard open, and disabled/readonly guards
   • Cover manual typed entry for valid, incomplete, invalid, and auto-swapped ranges
   • Cover default culture-generated masks, configurable separators, forwarded MaskLazy/MaskPlaceholder, and invalid custom mask rejection
   • Cover AutoClose=true close-on-complete and AutoClose=false stay-open behavior
   • Cover display format, min/max forwarding, and SelectDatesHover presets
   • Add branch-focused assertions so the new component stays compatible with the 98% line coverage requirement
7. Create DateRangePickerExample.razor
   • Basic range, manual entry, configurable separator behavior, culture-generated mask behavior, custom mask configuration, AutoClose, and preset ranges demo
8. Create FluentDateRangePicker.md
   • Documentation page including manual entry, configurable separator behavior, default/generated mask behavior, custom mask validation, and AutoClose
9. Run build, targeted tests, and coverage validation
   • Run component tests for the new picker
   • Run tests/_StartCodeCoverage.ps1 (or equivalent coverage command) and confirm line coverage remains at or above 98%

[Denis Voituron (dvoituron)]

• Remove StartChanged and EndChanged. These parameters should not be bound bidirectionally.

• Check whether InputBase accepts a complex object. If so, use a custom class instead of a Tuple (easier to extend).

[Johan (gotmoo)]

I like this plan! I'm already thinking of places I could use this. There are perhaps a few options that could be nice to add:

• StartDateInclusive: Returns DateTime value at beginning of the day 2026-07-18 00:00:00 default: true
• EndDateInclusive: Returns DateTime value at the end of the day 2026-08-20 23:59:59, not sure what the default value should be here.
• Allow for future extension to include start and end times as well

[Denis Voituron (dvoituron)]

We've already defined the MinDate and MaxDate parameters. But you're right: we also need to add StartHour and EndHour.

[RobDene]

Would you not need then to have time zone settings ie to respect Daylight Savings ? We are always having to code for that

[Denis Voituron (dvoituron)]

The Culture parameter lets you configure this. And .NET does all the rest behind the scenes.

[RobDene]

When using Azure SQL , it always stores the time data as UTC , so you always have to change the data to view correctly in local time (unless you are on UTC).
In flows you can use for example "GMT Standard Time" for UK times which will automatically adjust depending on whether DST needs to be applied - but this doesn't necessarily work with Azure hosted apps as they could be Linux hosted which could expect IANA id's instead. Just thought if you were working on it, you could have the Culture also define the displaying TimeZone, but I guess I'm making the assumption that most cloud data is now stored as UTC and you'd want to localise for viewing/entering.
We already do this in code but just thought it might make sense.

[Denis Voituron (dvoituron)]

Culture controls how dates are formatted and parsed, but it does not identify a time zone. However, FluentDatePicker selects a calendar date rather than an instant in time, so time-zone conversion should normally not be performed by the component. If an application combines the selected date with a time and stores it as UTC, it must also provide the relevant user or business time zone and perform the UTC conversion itself. TimeZoneInfo will then apply the appropriate daylight-saving rules. This separation is important because a culture such as en-GB does not necessarily mean that the user is in the Europe/London time zone.