LayrzMonthInput

LayrzMonthInput

Picker-style input that collects a single month+year value via a month grid dialog.

Metadata

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

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

---

Value Type and Selection Surface

• Value type: ThemedMonth? (nullable) — a Layrz-specific data class holding year and month
• Selection surface: Month grid dialog with:
  • A grid of 12 month buttons (rows/columns layout)
  • Year navigation controls (previous year / next year buttons)
  • Optional year selector (TBD)
• Display format: Formatted month string, e.g., "August 2026" (format TBD)

---

Deltas from the Contract

ThemedMonth Data Type

In layrz_theme, ThemedMonth is a value class that pairs year and month:

// Illustrative — exact definition TBD for layrz_ui
class ThemedMonth {
  final int year;
  final int month; // 1–12
  
  ThemedMonth({required this.year, required this.month});
}

Specific Parameters

// Design sketch — illustrative only
class LayrzMonthInput extends LayrzTextInput {
  /// The currently selected month, or null if no selection.
  /// 
  /// Holds a month+year pair.
  final ThemedMonth? value;

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

  /// Minimum selectable month (inclusive).
  /// 
  /// If set, any month before this is disabled.
  final ThemedMonth? minimum;

  /// Maximum selectable month (inclusive).
  /// 
  /// If set, any month after this is disabled.
  final ThemedMonth? maximum;

  /// List of specific months to disable.
  /// 
  /// Each month in this list is shown as unselectable in the grid.
  final List<ThemedMonth> disabledMonths;

  // ... inherited from LayrzTextInput
}

Key Differences from the Contract

1. Custom value type: ThemedMonth instead of a standard Dart type.

   • Encodes year + month into a single value.
   • layrz_ui must define or adopt this class; currently status unknown.

2. Month-level constraints:

   • minimum / maximum — month range bounds
   • disabledMonths — specific months to disable
   • No day-level granularity.

3. Grid-based UI: Rather than a calendar, a 12-month grid with year navigation.

   • Simpler than calendar, but less visual context for the current date.

---

Reference: layrz_theme ThemedMonthPicker API

As of layrz_theme source, ThemedMonthPicker exposes:

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

  // Month constraints
  final ThemedMonth? minimum;
  final ThemedMonth? maximum;
  final List<ThemedMonth> disabledMonths;

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

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

Notes:

• ThemedMonth is a layrz_theme-specific class; layrz_ui must determine whether to reuse or define its own.
• No formatting parameter (unlike date/time inputs); month display format is implicit in the locale.
• Color parameters are Material-specific.

---

Dependencies and Blockers

Direct Dependencies

1. LayrzTextInput (M3) — must ship first; LayrzMonthInput composes it.
2. ThemedMonth class — must be available in layrz_ui (or layrz_ui must define its own month class).
3. Month grid widget (hand-rolled or SDK-based) — to display 12-month grid with navigation.
4. 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 month names and "Previous year" / "Next year" button labels.

---

Open Questions

1. ThemedMonth class: Should layrz_ui reuse ThemedMonth from layrz_theme, define its own, or use a simpler pair (int year, int month)?

   • Reuse: maintains consistency but couples to layrz_theme.
   • Define: independence but duplication.
   • Simple pair: simpler but less type-safe.

2. Month display format: How are months displayed in the grid?

   • Full names ("January", "February", …)?
   • Abbreviations ("Jan", "Feb", …)?
   • Locale-dependent?

3. Localisation: How are month names and navigation labels translated?

   • layrz_theme has layrz.monthPicker.* translation keys.

4. Year selector: How do users navigate years?

   • Previous/next year buttons only?
   • Direct year input field?
   • Year picker dialog?

5. Range spanning multiple years: How should minimum and maximum be visualized?

   • Disable entire year if no months in that year are selectable?
   • Disable only specific months?

6. Disabled state: Is disabled distinct from readOnly?

7. Month format in display: Same as LocalDateTime month display (e.g., "August 2026")?

---

Related Documents

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