LayrzDateRangeInput

LayrzDateRangeInput

Picker-style input that collects a date range (start and end dates) via a calendar dialog.

Metadata

• Mirrors: ThemedDateRangePicker from layrz_theme
• Phase: M4 (Pickers)
• Domain: Pickers
• Composes: LayrzTextInput (read-only mode)

---

Specification Status

DERIVED from layrz_theme, NOT confirmed by the team. This page synthesizes the current Themed API. Every detail here awaits review and sign-off. See Input Contract for the shared contract all inputs conform to.

---

Conformance

LayrzDateRangeInput conforms to the Layrz*Input contract defined in Input Contract:

• Field identification: labelText and placeholder
• Prefix/suffix: Mutually exclusive icon/widget pairs with callbacks
• Help affordance: helpTitleText and helpContentText
• Interactivity: onChanged (receives start+end as list), onSubmit, onTap (opens calendar), readOnly
• Focus/lifecycle: focusNode, controller (dispose pattern specified)
• Layout: padding from M1 spacing tokens
• Value display: Formatted date range string and optional visual affordance

---

Value Type and Selection Surface

• Value type: List<DateTime> (two-element list: [startDate, endDate])
• Selection surface: Calendar dialog with range selection (user taps start date, then end date)
• Display format: Formatted range string, e.g., "2026-08-01 to 2026-08-31" (customizable via datePattern)

---

Deltas from the Contract

Specific Parameters

// Design sketch — illustrative only
class LayrzDateRangeInput extends LayrzTextInput {
  /// The currently selected date range.
  /// 
  /// Expected format: [startDate, endDate].
  /// An empty list means no selection; a single-element list means start only.
  final List<DateTime> value;

  /// Callback invoked when the user commits a date range selection.
  /// 
  /// Receives the full [startDate, endDate] pair.
  final void Function(List<DateTime>)? onChanged;

  /// Format pattern for displaying selected dates.
  /// 
  /// Uses strftime-style format codes (e.g., `%Y-%m-%d`).
  /// The display format for the range string is template-based; see Open Questions.
  /// Default: `%Y-%m-%d`.
  final String datePattern;

  /// List of specific dates to disable.
  /// 
  /// Each date in this list is shown as unselectable in the calendar.
  /// Typically used for holidays or unavailable dates.
  final List<DateTime> disabledDays;

  // ... inherited from LayrzTextInput
}

Key Differences from the Contract

1. Value representation: A two-element List<DateTime> rather than a dedicated range type.

   • Callers must manage [startDate, endDate] tuple semantics themselves.
   • Open question: Should layrz_ui use a dedicated DateRange class?

2. Calendar interaction: User selects a start date, then an end date.

   • Visual affordance: selected start/end dates highlighted; dates in between shown as selected range.
   • No support for swapping start/end if user selects them in reverse order (TBD).

3. Disabled dates: Only disabledDays list (no firstDay/lastDay range in source).

   • layrz_theme ThemedDateRangePicker does not expose firstDay/lastDay; open question whether layrz_ui adds them.

---

Reference: layrz_theme ThemedDateRangePicker API

As of layrz_theme source, ThemedDateRangePicker exposes:

class ThemedDateRangePicker extends StatefulWidget {
  final List<DateTime> value;
  final void Function(List<DateTime>)? onChanged;

  // Labels and placeholder
  final String? labelText;
  final Widget? label;
  final String? placeholder;

  // Prefix
  final String? prefixText;
  final IconData? prefixIcon;
  final Widget? prefixWidget;
  final VoidCallback? onPrefixTap;

  // Custom child and styling (Material-specific, likely deprecated)
  final Widget? customChild;
  final Color hoverColor;
  final Color focusColor;
  final Color splashColor;
  final Color highlightColor;
  final BorderRadius borderRadius;

  // Error and layout
  final List<String> errors;
  final bool hideDetails;
  final EdgeInsets? padding;
  final bool disabled;

  // Date constraints
  final List<DateTime> disabledDays;

  // Formatting and localisation
  final String pattern; // strftime-style
  final Map<String, String> translations;
  final bool overridesLayrzTranslations;

  const ThemedDateRangePicker({
    required this.value,
    // ... other parameters
  });
}

Notes:

• value is required, not optional (defaults to empty list in constructor).
• No firstDay/lastDay parameters (unlike ThemedDatePicker); only disabledDays.
• Color and styling parameters are Material-specific and will not carry forward.
• Translations provided as a map.

---

Dependencies and Blockers

Direct Dependencies

1. LayrzTextInput (M3) — must ship first; LayrzDateRangeInput composes it.
2. Calendar widget (hand-rolled or SDK-based) — with range selection highlighting.
3. Dialog routing — showGeneralDialog or equivalent.

Implicit Dependencies

• M1 spacing tokens — padding and inner spacing.
• Tooltip component (M2) — for help affordance.
• Material-free selection controls — if LayrzTextInput has not resolved text selection.
• Localisation infrastructure — for calendar UI labels and translations.

---

Open Questions

1. Value type: Should LayrzDateRangeInput use a dedicated DateRange class, or keep the List<DateTime> approach?

   • Pros (list): flexible, simple, matches layrz_theme.
   • Pros (class): type-safe, explicit semantics, easier to validate.

2. Localisation: Same as LayrzDateInput. How are month names and button labels translated?

3. Range format template: How is the date range displayed as a string?

   • Option 1: {start} to {end} (caller-supplied format string?)
   • Option 2: {start} – {end} (fixed en-dash)
   • Option 3: Locale-specific separator (e.g., "to" in English, "a" in Spanish)?

4. Disabled dates and ranges: Should certain date ranges be disableable (e.g., "only select ranges < 30 days")?

   • Currently only individual dates can be disabled.

5. Start/end validation: If user selects end date before start date, what happens?

   • Swap them automatically?
   • Reject and show error?
   • Allow and let caller handle?

6. Reverse range selection: Allow picking end date first, then start date?

   • layrz_theme behavior unclear; needs clarification.

7. firstDay/lastDay support: Should layrz_ui add range bounds like LayrzDateInput?

   • layrz_theme does not expose them; design decision needed.

8. Today indicator: Same as LayrzDateInput—highlight today in the calendar?

---

Related Documents

• Input Contract — shared contract for all Layrz*Input components
• LayrzDateInput — single-date variant for comparison
• Component Catalog — mapping of layrz_theme to layrz_ui components
• Design Tokens — M1 spacing and theme tokens
• Flutter 347 Audit — SDK dependency audit
• Decisions — D5 (naming: LayrzInput replaces LPicker)