LayrzTimeInput

LayrzTimeInput

Picker-style input that collects a single time-of-day value via a time picker dialog.

Metadata

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

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

---

Value Type and Selection Surface

• Value type: TimeOfDay? (nullable) — from Flutter SDK
• Selection surface: Time picker dialog with hour/minute spinners or increment buttons
• Display format: Formatted time string (default: %H:%M for 24-hour, %I:%M %p for 12-hour; customizable via timePattern)

---

Deltas from the Contract

Specific Parameters

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

  /// Callback invoked when the user commits a time selection.
  final void Function(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 the selected time.
  /// 
  /// Uses strftime-style format codes.
  /// If null, a default pattern is chosen based on [use24HourFormat].
  /// 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.
  /// 
  /// By default, selected hour/minute spinners blink; set to true to disable.
  final bool disableBlink;

  // ... inherited from LayrzTextInput
}

Key Differences from the Contract

1. Time format control: use24HourFormat flag and optional timePattern override.

   • Defaults to 12-hour with AM/PM; caller can switch to 24-hour.

2. Spinner animation: disableBlink disables the visual feedback on selected spinners.

   • Implementation detail of the time picker UI; may not carry to layrz_ui design.

---

Reference: layrz_theme ThemedTimePicker API

As of layrz_theme source, ThemedTimePicker exposes:

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

Notes:

• pattern is optional; defaults are applied based on use24HourFormat.
• Color parameters are Material-specific and will not carry forward.

---

Dependencies and Blockers

Direct Dependencies

1. LayrzTextInput (M3) — must ship first; LayrzTimeInput composes it.
2. Time picker widget (hand-rolled or SDK-based) — with hour/minute selection and format control.
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 time picker UI strings.

---

Open Questions

1. Time picker UI: What is the visual design of the time picker?

   • Spinners (iOS-style)?
   • Increment/decrement buttons with direct input?
   • Analog clock face?
   • Keyboard/text input?
   • layrz_theme uses spinners; does layrz_ui adopt this, or choose another paradigm?

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

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

4. Minute granularity: Can users select any minute, or only specific intervals (e.g., every 5 minutes)?

   • layrz_theme behavior unclear; may be implicit in the spinner design.

5. Disabled state: Is disabled distinct from readOnly?

   • Same as LayrzDateInput; needs clarification.

6. Blinking animation: Is disableBlink a user preference or a design detail?

   • Seems implementation-specific; may not be needed in layrz_ui.

---

Related Documents

• Input Contract — shared contract for all Layrz*Input components
• LayrzDateTimeInput — combines date and time selection
• 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)