LayrzDateInput

LayrzDateInput

Picker-style input that collects a single date value via a calendar dialog.

Metadata

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

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

---

Value Type and Selection Surface

• Value type: DateTime? (nullable)
• Selection surface: Calendar dialog with month/year navigation
• Display format: Formatted date string (default pattern: %Y-%m-%d; customizable via datePattern)

---

Deltas from the Contract

Specific Parameters

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

  /// Callback invoked when the user commits a date selection.
  final void Function(DateTime)? onChanged;

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

  /// Earliest date the user can select.
  /// 
  /// Any date before this is disabled in the calendar.
  /// If null, no lower bound is applied.
  final DateTime? firstDay;

  /// Latest date the user can select.
  /// 
  /// Any date after this is disabled in the calendar.
  /// If null, no upper bound is applied.
  final DateTime? lastDay;

  /// List of specific dates to disable.
  /// 
  /// Each date in this list is shown as unselectable in the calendar.
  final List<DateTime> disabledDays;

  // ... inherited from LayrzTextInput
}

Key Differences from the Contract

1. Disabled dates: Three mechanisms to restrict selection:

   • firstDay / lastDay — range bounds
   • disabledDays — specific dates (e.g., weekends, holidays)

2. Custom formatting: datePattern allows caller-supplied strftime-style format (default sensible).

3. Localisation implications: Date formatting and calendar UI (month names, weekday headers) need localisation. See Open Questions.

---

Reference: layrz_theme ThemedDatePicker API

As of layrz_theme source, ThemedDatePicker exposes:

class ThemedDatePicker 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 constraints
  final DateTime? firstDay;
  final DateTime? lastDay;
  final List<DateTime> disabledDays;

  // Formatting and localisation
  final String pattern; // strftime-style
  final Map<String, String> translations;
  final bool overridesLayrzTranslations;

  const ThemedDatePicker({
    // ... parameters
  });
}

Notes:

• disabled state is distinct from readOnly.
• Color parameters (hoverColor, etc.) are Material-specific and will not carry forward to layrz_ui.
• Translations are provided as a map; layrz_ui will align with the localization strategy TBD.
• pattern uses strftime codes; layrz_ui will retain this or adopt a new scheme per design decisions.

---

Dependencies and Blockers

Direct Dependencies

1. LayrzTextInput (M3) — must ship first; LayrzDateInput composes it.
2. Calendar widget (hand-rolled or SDK-based) — to display month/year grid with navigation.
3. Dialog routing — showGeneralDialog or equivalent (SDK provides RawDialogRoute, Overlay, OverlayPortal).

Implicit Dependencies

• M1 spacing tokens — padding and inner spacing via design-tokens.md.
• Tooltip component (M2) — for help affordance.
• Material-free selection controls — if LayrzTextInput has not resolved text selection (see flutter-347-audit.md).
• Localisation infrastructure — month names, calendar UI labels. Strategy TBD.

---

Open Questions

1. Localisation: How are month names, weekday headers ("Mon", "Tue", etc.), and button labels ("Cancel", "Save") translated?

   • layrz_theme uses LayrzAppLocalizations and a translations map parameter.
   • layrz_ui has no localisation strategy yet. Should we use intl package, context-based lookups, or defer to the app?

2. Date formatting: Adopt strftime codes like layrz_theme, or use Dart's DateFormat (from intl)?

   • Strftime is familiar but minimal; intl is more powerful but adds a dependency.

3. Disabled state: Is disabled distinct from readOnly?

   • layrz_theme has both; disabled prevents interaction, readOnly shows value without editing.
   • Does layrz_ui collapse these, or retain both?

4. Disabled days UI: How are disabled dates shown in the calendar?

   • Strikethrough? Grayed out? Invisible? Theme-configurable?

5. Today indicator: Should the calendar highlight today's date?

   • layrz_theme has a "Today" button; should we support that, or just highlight the date?

6. Keyboard navigation: Can the user navigate the calendar with arrow keys?

   • Opens up accessibility but adds interaction complexity.

---

Related Documents

• Input Contract — shared contract for all Layrz*Input components
• 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)