Skip to content

LayrzMonthRangeInput

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

LayrzMonthRangeInput

Picker-style input that collects a month range (start and end) via a month grid dialog, supporting both arbitrary multi-month selection and consecutive range modes.

Metadata

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

LayrzMonthRangeInput 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 (receives start+end months), onSubmit, onTap (opens month grid), readOnly
  • Focus/lifecycle: focusNode, controller (dispose pattern specified)
  • Layout: padding from M1 spacing tokens
  • Value display: Formatted month range string and optional visual affordance

Value Type and Selection Surface

  • Value type: List<ThemedMonth> (two or more elements: [startMonth, endMonth, …])
  • Selection surface: Month grid dialog with:
    • 12-month grid with year navigation
    • Two selection modes:
      1. Consecutive mode (consecutive: true): User picks a start month, then an end month; all months in between are implicitly included
      2. Arbitrary mode (consecutive: false): User can select any individual months; range returned as a list of selected months
    • Visual affordance: selected months highlighted; in consecutive mode, intermediate months shown as selected range
  • Display format: Formatted range string, e.g., "August 2026 to October 2026" or "Aug 2026, Sep 2026, Oct 2026" (format TBD)

Deltas from the Contract

Specific Parameters

// Design sketch — illustrative only
class LayrzMonthRangeInput extends LayrzTextInput {
  /// The currently selected months.
  /// 
  /// In consecutive mode: [startMonth, endMonth] (two elements).
  /// In arbitrary mode: list of selected months (any length >= 0).
  /// Empty list means no selection.
  final List<ThemedMonth> value;

  /// Callback invoked when the user commits a month range selection.
  /// 
  /// Receives the full list of selected months.
  final void Function(List<ThehedMonth>)? onChanged;

  /// Whether to enforce consecutive month selection.
  /// 
  /// If true, user picks start and end; all months in between are included.
  /// If false (default), user can select any individual months.
  final bool consecutive;

  /// 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. Dual selection mode:

    • Consecutive mode: intuitive for date ranges (e.g., "August to October").
    • Arbitrary mode: flexible for non-contiguous selections (e.g., "Aug, Oct, Dec").
    • Flag consecutive switches between them.

  2. Value representation: List<ThemedMonth> to accommodate both modes.

    • In consecutive mode, always 2 elements.
    • In arbitrary mode, variable length.

  3. Constraint parameters: minimum, maximum, and disabledMonths for finer control.

Reference: layrz_theme ThemedMonthRangePicker API

As of layrz_theme source, ThemedMonthRangePicker exposes:

class ThemedMonthRangePicker extends StatefulWidget {
  final List<ThemedMonth> value;
  final void Function(List<ThemedMonth>)? onChanged;
  final bool consecutive;

  // 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 ThemedMonthRangePicker({
    required this.value,
    this.consecutive = false,
    // ... other parameters
  });
}

Notes:

  • value is required (defaults to empty list).
  • consecutive flag defaults to false, allowing arbitrary selection by default.
  • Includes a "Reset" translation key (actions.reset), suggesting a reset-to-empty button in the UI.
  • Color parameters are Material-specific.

Dependencies and Blockers

Direct Dependencies

  1. LayrzTextInput (M3) — must ship first; LayrzMonthRangeInput composes it.
  2. ThemedMonth class — must be available (see LayrzMonthInput for discussion).
  3. Month grid widget (hand-rolled or SDK-based) — with range selection and dual mode support.
  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 button labels.

Open Questions

  1. Consecutive mode UI: How is it visually distinct from arbitrary mode?

    • Toggle switch in the dialog? Separate factory constructor?
    • layrz_theme uses the consecutive flag; how should layrz_ui expose this?

  2. Arbitrary mode display: How is a non-contiguous list of months displayed?

    • Comma-separated list ("Aug 2026, Oct 2026, Dec 2026")?
    • Count indicator ("3 months selected")?
    • Abbreviated format?

  3. Consecutive mode display: How is a consecutive range shown?

    • "August to October 2026"?
    • "Aug – Oct 2026"?

  4. Value type in consecutive mode: Should layrz_ui use a dedicated MonthRange class, or keep List<ThemedMonth>?

    • Keeps API consistent but requires callers to handle the list length semantics.

  5. ThemedMonth class: Same as LayrzMonthInput—reuse, define, or use a simple pair?

  6. Reset button: layrz_theme has an actions.reset translation key; should layrz_ui include a reset button in the UI?

    • Allows users to clear selection without closing the dialog.

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

  8. Range spanning multiple years: How should minimum and maximum constraints behave across year boundaries?

  9. Disabled state: Is disabled distinct from readOnly?

  10. Mode toggling: Can the user switch between consecutive and arbitrary modes, or is it fixed at construction time?

    • layrz_theme uses a fixed flag; dynamic switching would be a new feature.

Related Documents

Made with ❤️ by Golden M, Inc.

← Home

Reference

Buttons

Display

Data

Layout

Navigation

Feedback

Inputs

Pickers

Clone this wiki locally