## Overview

The Date Picker Widget provides a reusable, toolbar-integrated date picker component that allows users to select a single date through an interactive calendar interface. When clicked, the toolbar button opens a dropdown containing a calendar based on bootstrap-datepicker, with optional quick selection shortcuts for dates relative to today.

The widget provides visual state indicators showing whether the date has been changed from the default value and displays validation errors for invalid dates. A reset capability allows users to quickly return to the default value with one click.

## Use Cases

### Date Selection in Reports and Filters
When users need to filter data by a specific date or generate reports for a particular day:
- Selecting a report generation date
- Filtering project milestones by date
- Setting a deadline or due date
- Choosing a start date for an analysis period

### Quick Date Navigation
When users frequently need to select dates relative to today without clicking through calendar months:
- Selecting "10 days from now" for follow-up tasks
- Choosing "yesterday" for daily reports
- Setting "30 days ago" as a lookback period start
- Quick selection of dates like "100 days from today" for long-term planning

### Date Input in Custom Pages
When building custom pages that require date input as part of a form or configuration interface:
- Configuration dialogs requiring date parameters
- Custom workflow forms with date fields
- Dashboard filters with date selection

### Default Date with User Override
When a default date should be suggested but users need the ability to change it easily:
- Forms pre-filled with "today" that can be adjusted
- Date fields with calculated defaults (e.g., project end date based on duration)
- Reset functionality to quickly return to the default value

## Design Considerations

### When to Use This Widget
- You need a single date selection in a toolbar or form
- A calendar interface improves usability over text input
- You want visual feedback for changed/invalid states
- Users benefit from relative date shortcuts

### Technical Considerations
- All dates are normalized to midnight local time
- Built-in validation for Date objects (null or valid Date only)
- Widget tracks changes from default and allows reset
- Date restrictions in picker options may not work correctly with relative date buttons
- Only single date selection is supported (multidate not available)

## Common Pitfalls

- Using date restriction options (like startDate or daysOfWeekDisabled) in combination with relative date shortcuts - these are not fully compatible
- Expecting multidate selection support - this widget only supports single date selection
- Not accounting for timezone normalization - dates are stored at midnight local time

## Alternatives

| Alternative | When to Use |
|-------------|-------------|
| `tlf-date-range-picker` | When you need to select a date range (start and end dates) instead of a single date |
| `tlf-date-picker-core` | When you need just the calendar without toolbar button styling |
| `tlf-date-diff` | When you only need relative date selection without the calendar interface |

## Related Patterns

- **Toolbar Widget Family**: This widget is part of the 2lforge Toolbar plugin alongside DropDownWidget and MiscWidget
- **Date Range Selection**: For selecting date ranges, use the sibling component tlf-date-range-picker