LayrzDateTimeSteppedInput

LayrzDateTimeSteppedInput

Picker-style input that collects a single date+time value via two sequential dialogs: a calendar picker first, then a time picker as a separate dialog.

Metadata

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

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

---

Value Type and Selection Surface

• Value type: DateTime? (nullable) — holds both date and time components
• Selection surface: Sequential dialogs (not tabs):
  1. First dialog: Calendar picker (for date selection)
     • User confirms selection → first dialog closes
  2. Second dialog: Time picker (for time selection, with selected date as context)
     • User confirms selection → second dialog closes; final date+time value is set
• Display format: Formatted date+time string, e.g., "2026-08-13 14:30" (customizable via datePattern, timePattern, and patternSeparator)

---

Deltas from the Contract

Specific Parameters

// Design sketch — illustrative only
class LayrzDateTimeSteppedInput extends LayrzTextInput {
  /// The currently selected date+time, or null if no selection.
  final DateTime? value;

  /// Callback invoked when the user commits a date+time selection.
  final void Function(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 and from LayrzDateTimeInput

1. Sequential dialogs, not tabbed:

   • LayrzDateTimeInput uses a tabbed dialog; user can switch between date and time tabs.
   • LayrzDateTimeSteppedInput opens two separate dialogs sequentially.
   • User must complete the first dialog before the second appears.

2. Interaction model:

   • After selecting a date in the calendar, the user must close/confirm the calendar dialog.
   • The time picker then appears as a new overlay, with the previously selected date as context (optionally displayed).

3. Same formatting parameters as LayrzDateTimeInput.

---

Reference: layrz_theme ThemedDateTimeSteppedPicker API

As of layrz_theme source, ThemedDateTimeSteppedPicker exposes:

class ThemedDateTimeSteppedPicker extends StatefulWidget {
  final DateTime? value;
  final void Function(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 ThemedDateTimeSteppedPicker({
    // ... parameters
  });
}

Notes:

• API is identical to ThemedDateTimePicker except in interaction model.
• The distinction is purely behavioral (tabbed vs. stepped); parameters are shared.

---

Dependencies and Blockers

Direct Dependencies

1. LayrzTextInput (M3) — must ship first; LayrzDateTimeSteppedInput composes it.
2. Calendar widget (hand-rolled or SDK-based) — for date selection.
3. Time picker widget (hand-rolled or SDK-based) — for time selection.
4. Dialog routing — showGeneralDialog or equivalent (two instances sequentially).

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 time picker labels.

---

Open Questions

1. Interaction flow: After the calendar dialog is dismissed, is the time picker automatically shown, or does the user need to re-open the input?

   • Implied by "stepped" semantics: automatic progression.
   • Confirm that both dialogs appear in a single user-triggered flow.

2. Cancellation: If the user cancels the calendar (first dialog), does the entire selection cancel?

   • Implied: yes. If the user cancels the time picker (second dialog), does the date selection persist, or is the entire selection cancelled?

3. Date context in time picker: Is the selected date displayed in the time picker UI (e.g., "Select time for August 13")?

   • Helps user confirm they're picking time for the right date.

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

5. Pattern format: Adopt strftime like layrz_theme, or use Dart's DateFormat?

6. Disabled dates and times: Can certain time ranges be restricted?

7. firstDay/lastDay support: Should layrz_ui add range bounds for dates?

8. Minute granularity: Only specific time intervals?

9. Disabled state: Is disabled distinct from readOnly?

10. Distinction from LayrzDateTimeInput: Beyond UI (tabbed vs. stepped), are there behavioral differences in validation or constraint handling?

    • Both share identical parameters; the difference is purely interaction model.
    • Confirm that both are needed, or if one is redundant.

---

Related Documents

• Input Contract — shared contract for all Layrz*Input components
• LayrzDateTimeInput — tabbed variant (for comparison)
• LayrzDateInput — date-only variant
• LayrzTimeInput — time-only 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)