Skip to content

LayrzDateTimeInput

Jump to bottom
Kenny Mochizuki Escalona edited this page Aug 13, 2026 · 2 revisions

LayrzDateTimeInput

Picker-style input that collects a single date+time value via a tabbed dialog with calendar and time picker.

Metadata

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

LayrzDateTimeInput 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 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: Tabbed dialog with two sheets:
    1. Calendar picker (for date selection)
    2. Time picker (for time selection)
  • 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 LayrzDateTimeInput 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).
  /// Example: with default, displays as "2026-08-13 14:30".
  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. Tabbed selection surface: Rather than a single dialog, a two-tab interface:

    • Tab 1: Calendar (date selection)
    • Tab 2: Time picker (time selection)
    • User can switch between tabs to refine their selection.

  2. Composite formatting: datePattern, timePattern, and patternSeparator allow independent formatting of each component.

    • Display format: {formatted_date}{separator}{formatted_time}

  3. Disabled dates: Only specific dates via disabledDays (layrz_theme source does not expose firstDay/lastDay).

Reference: layrz_theme ThemedDateTimePicker API

As of layrz_theme source, ThemedDateTimePicker exposes:

class ThemedDateTimePicker 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 ThemedDateTimePicker({
    // ... parameters
  });
}

Notes:

  • Combines date and time formatting into a single DateTime value.
  • Color parameters are Material-specific.
  • Translations include both calendar and time picker UI labels.

Dependencies and Blockers

Direct Dependencies

  1. LayrzTextInput (M3) — must ship first; LayrzDateTimeInput 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. Tabbed interface — to switch between date and time pickers (or a sequential dialog).
  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. Localisation: How are month names, weekday headers, "AM"/"PM" labels, and tab labels ("Date", "Time") translated?

  2. Tab labels: Are tabs explicitly labeled, or implied by content?

    • layrz_theme translations include layrz.datetimePicker.date and layrz.datetimePicker.time keys, suggesting explicit labels.

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

  4. Disabled dates and times: Can certain time ranges (e.g., only 9 AM to 5 PM) be restricted?

    • Currently only specific dates can be disabled.

  5. Sequential vs. tabbed: Is the dialog truly tabbed, or does it step sequentially?

    • Compare with LayrzDateTimeSteppedInput (which is explicitly stepped).
    • If both exist, what's the behavioral difference?

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

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

  8. Disabled state: Is disabled distinct from readOnly?

Related Documents

Made with ❤️ by Golden M, Inc.

← Home

Reference

Buttons

Display

Data

Layout

Navigation

Feedback

Inputs

Pickers

Clone this wiki locally