LayrzTimeRangeInput

LayrzTimeRangeInput

Picker-style input that collects a time range (start and end times) via a time picker dialog.

Metadata

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

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

---

Value Type and Selection Surface

• Value type: List<TimeOfDay> (two-element list: [startTime, endTime])
• Selection surface: Time picker dialog with dual time spinners or increment controls (user selects start time, then end time)
• Display format: Formatted range string, e.g., "09:00 to 17:00" (customizable via timePattern)

---

Deltas from the Contract

Specific Parameters

// Design sketch — illustrative only
class LayrzTimeRangeInput extends LayrzTextInput {
  /// The currently selected time range.
  /// 
  /// Expected format: [startTime, endTime].
  /// An empty list means no selection; a single-element list means start only.
  final List<TimeOfDay> value;

  /// Callback invoked when the user commits a time range selection.
  /// 
  /// Receives the full [startTime, endTime] pair.
  final void Function(List<TimeOfDay>)? onChanged;

  /// Whether to use 24-hour time format.
  /// 
  /// If true, times display as 00:00–23:59.
  /// If false (default), uses 12-hour format with AM/PM.
  final bool use24HourFormat;

  /// Format pattern for displaying selected times.
  /// 
  /// Uses strftime-style format codes.
  /// If null, a default pattern is chosen based on [use24HourFormat].
  /// The display format for the range string is template-based; see Open Questions.
  /// Default: `%H:%M` (24-hour) or `%I:%M %p` (12-hour).
  final String? timePattern;

  /// Whether to disable the blinking animation in the time picker spinners.
  final bool disableBlink;

  // ... inherited from LayrzTextInput
}

Key Differences from the Contract

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

   • Callers manage [startTime, endTime] tuple semantics.
   • Open question: Should layrz_ui use a dedicated TimeRange class?

2. Time picker interaction: User selects start time, then end time.

   • Visual affordance: selected start/end times highlighted; times in between shown as valid range.

3. Format control: Same as LayrzTimeInput (use24HourFormat, timePattern).

---

Reference: layrz_theme ThemedTimeRangePicker API

As of layrz_theme source, ThemedTimeRangePicker exposes:

class ThemedTimeRangePicker extends StatefulWidget {
  final List<TimeOfDay> value;
  final void Function(List<TimeOfDay>)? 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;

  // Time format
  final bool use24HourFormat;
  final String? pattern; // strftime-style
  final bool disableBlink;

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

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

Notes:

• value is required (defaults to empty list).
• Shares most parameters with ThemedTimePicker.
• Color parameters are Material-specific and will not carry forward.

---

Dependencies and Blockers

Direct Dependencies

1. LayrzTextInput (M3) — must ship first; LayrzTimeRangeInput composes it.
2. Time picker widget (hand-rolled or SDK-based) — with dual time spinners and range visualization.
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 "AM"/"PM" labels and UI strings.

---

Open Questions

1. Value type: Should LayrzTimeRangeInput use a dedicated TimeRange class, or keep the List<TimeOfDay> approach?

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

2. Localisation: How are "AM"/"PM" labels and time picker UI labels translated?

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

   • Option 1: {start} to {end}
   • Option 2: {start} – {end}
   • Option 3: Locale-specific separator?

4. Minute granularity: Only specific intervals (e.g., every 5 minutes)?

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

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

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

7. Disabled state: Is disabled distinct from readOnly?

---

Related Documents

• Input Contract — shared contract for all Layrz*Input components
• LayrzTimeInput — single-time variant for comparison
• LayrzDateTimeRangeInput — combines date and time ranges
• 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)