LayrzDateTimeRangeInput

LayrzDateTimeRangeInput

Picker-style input that collects a date+time range (start and end) via a tabbed dialog with calendar and time pickers.

Metadata

• Mirrors: ThemedDateTimeRangePicker 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

LayrzDateTimeRangeInput 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 dialog), readOnly
• Focus/lifecycle: focusNode, controller (dispose pattern specified)
• Layout: padding from M1 spacing tokens
• Value display: Formatted date+time range string and optional visual affordance

---

Value Type and Selection Surface

• Value type: List<DateTime> (two-element list: [startDateTime, endDateTime])
• Selection surface: Tabbed dialog with two sheets:
  1. Calendar picker (for date range selection)
  2. Time picker (for time range selection)
  • User can switch between tabs; both start and end can be refined in each tab.
• Display format: Formatted range string, e.g., "2026-08-01 09:00 to 2026-08-31 17:00" (customizable via datePattern, timePattern, and patternSeparator)

---

Deltas from the Contract

Specific Parameters

// Design sketch — illustrative only
class LayrzDateTimeRangeInput extends LayrzTextInput {
  /// The currently selected date+time range.
  /// 
  /// Expected format: [startDateTime, endDateTime].
  /// 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+time range selection.
  /// 
  /// Receives the full [startDateTime, endDateTime] pair.
  final void Function(List<DateTime>)? onChanged;

  /// Format pattern for the date part.
  /// 
  /// Uses strftime-style format codes (e.g., `%Y-%m-%d`).
  /// Default: `%Y-%m-%d`.
  final String datePattern;

  /// Format pattern for the time part.
  /// 
  /// Uses strftime-style format codes.
  /// If null, defaults based on [use24HourFormat].
  /// Default: `%H:%M` (24-hour) or `%I:%M %p` (12-hour).
  final String? timePattern;

  /// Whether to use 24-hour time format.
  /// 
  /// If false (default), uses 12-hour format with AM/PM.
  final bool use24HourFormat;

  /// Separator string between date and time in the display.
  /// 
  /// Default: ` ` (space).
  final String patternSeparator;

  /// List of specific dates to disable.
  /// 
  /// Dates in this list are shown as unselectable in the calendar.
  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 manage [startDateTime, endDateTime] tuple semantics.

2. Tabbed selection surface: Calendar and time picker tabs, each allowing start/end refinement.

3. Composite formatting: Date and time patterns with a separator, same as LayrzDateTimeInput.

4. Disabled dates: Only specific dates via disabledDays.

---

Reference: layrz_theme ThemedDateTimeRangePicker API

As of layrz_theme source, ThemedDateTimeRangePicker exposes:

class ThemedDateTimeRangePicker 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 and time constraints
  final List<DateTime> disabledDays;

  // Formatting
  final String datePattern; // strftime-style
  final String? timePattern; // strftime-style
  final bool use24HourFormat;
  final String patternSeparator;

  // Localisation
  final Map<String, String> translations;
  final bool overridesLayrzTranslations;

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

Notes:

• value is required (defaults to empty list).
• Combines date range and time range selection into one component.
• Color parameters are Material-specific.

---

Dependencies and Blockers

Direct Dependencies

1. LayrzTextInput (M3) — must ship first; LayrzDateTimeRangeInput composes it.
2. Calendar widget (hand-rolled or SDK-based) — with range selection.
3. Time picker widget (hand-rolled or SDK-based) — with range selection.
4. Tabbed interface — to switch between date and time range pickers.
5. 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, time format labels, and tab labels.

---

Open Questions

1. Value type: Should LayrzDateTimeRangeInput use a dedicated DateTimeRange class, or keep List<DateTime>?

2. Localisation: How are month names, "AM"/"PM" labels, and tab labels translated?

3. Tab labels: Same as LayrzDateTimeInput—are they explicitly labeled ("Date", "Time")?

4. Range format template: How is the full range displayed as a string?

   • Option 1: {startDate} {startTime} to {endDate} {endTime}
   • Option 2: {startDate} {startTime} – {endDate} {endTime}
   • Option 3: Locale-specific formatting?

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

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

7. Date range constraints: Support firstDay/lastDay for the date part?

8. Time range constraints: Restrict selectable times (e.g., only 9 AM to 5 PM)?

9. Minute granularity: Only specific time intervals?

10. Disabled state: Is disabled distinct from readOnly?

---

Related Documents

• Input Contract — shared contract for all Layrz*Input components
• LayrzDateTimeInput — single date+time variant for comparison
• LayrzDateRangeInput — date-only range variant
• LayrzTimeRangeInput — time-only range variant
• 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)