LayrzDurationInput

LayrzDurationInput

Time span selection field with day, hour, minute, and second components.

Specification Status: Derived from layrz_theme.ThemedDurationInput. This documentation reflects the current layrz_theme API and is NOT YET CONFIRMED as the design for layrz_ui. Team review and design sign-off are required before implementation.

Metadata

Property	Value
Mirror	ThemedDurationInput
Phase	M3 Inputs
Domain	Inputs
SDK Primitive	Composes LayrzTextInput (read-only) + RawDialog with LayrzNumberInput controls

Conformance

LayrzDurationInput conforms to the Input Contract. Like all picker-style inputs, it composes LayrzTextInput internally in read-only mode and opens a selection surface on tap. The entire contract applies: labels, prefix/suffix, help affordance, focus management, padding, and validation error display.

Value Type and Selection Surface

• Value type: Duration — represents a time span (days, hours, minutes, seconds)
• Selection surface: Dialog with numeric input fields for each time unit
• Summary display: The field displays the duration in human-readable format (e.g., "2 days 3 hours 15 minutes"); unselected state shows placeholder or empty
• Formatting: Duration is formatted using human-readable language (e.g., "2 days, 3 hours, and 15 minutes")

Deltas from the Input Contract

Duration Composition

// Design sketch — illustrative only
class LayrzDurationInput extends StatefulWidget {
  /// The currently selected duration.
  final Duration? value;

  /// Callback invoked when user changes the duration.
  final void Function(Duration?)? onChanged;

  /// Which time units are visible in the picker.
  /// Supported: day, hour, minute, second.
  /// Defaults to all four.
  final List<LDurationUnit> visibleUnits;

  const LayrzDurationInput({
    required this.value,
    this.onChanged,
    this.visibleUnits = const [
      LDurationUnit.day,
      LDurationUnit.hour,
      LDurationUnit.minute,
      LDurationUnit.second,
    ],
    // ... shared contract parameters (label, placeholder, prefix, suffix, etc.)
  });
}

enum LDurationUnit {
  /// Day unit (24-hour increment)
  day,

  /// Hour unit (0–23 range; wraps when combined with days)
  hour,

  /// Minute unit (0–59 range; wraps when combined with hours)
  minute,

  /// Second unit (0–59 range; wraps when combined with minutes)
  second,
}

Dialog Layout

Inside the dialog:

• Each visible unit is rendered as a numeric input field with a label and suffix (e.g., "Days: [2]")
• Numeric inputs display step buttons (+/−) or spin controls
• Minimum value for all units is 0; no maximum constraints

Formatting

The field displays the duration as human-readable text, e.g.:

• "2 days, 3 hours, and 15 minutes" (with localized "and")
• "1 hour 30 minutes" (short format if only two units)
• "45 seconds" (single unit)

The format depends on which units are visible; hidden units are omitted from the summary.

Inherits from Input Contract

All of the following are inherited from LayrzTextInput:

• labelText and label (mutually exclusive)
• placeholder
• prefixIcon, prefixWidget, onPrefixTap (mutually exclusive icon and widget)
• suffixIcon, suffixWidget, onSuffixTap (mutually exclusive icon and widget)
• helpTitleText, helpContentText (two-part help tooltip)
• readOnly (always true for duration input)
• onTap (opens the duration picker dialog)
• focusNode, controller (focus and value management)
• padding (defaults to spacing tokens)
• disabled and error display

Reference: Current layrz_theme API

ThemedDurationInput (source: lib/src/inputs/src/general/duration_input.dart):

Parameter	Type	Notes
value	Duration?	Currently selected duration
onChanged	Function(Duration?)?	Callback when duration changes
errors	List<String>	Error messages (default: [])
labelText	String?	Label text (or use label Widget instead)
label	Widget?	Label widget (mutually exclusive with labelText)
suffixIcon	IconData?	Icon in suffix slot
prefixIcon	IconData?	Icon in prefix slot
disabled	bool	Disable the field (default: false)
padding	EdgeInsets?	Field padding
visibleValues	List<ThemedUnits>	Which units to display (default: day, hour, minute, second)

ThemedUnits enum:

• year (not supported in duration picker; mentioned for reference)
• month (not supported)
• week (not supported)
• day
• hour
• minute
• second
• millisecond (not typically used)

Supported units for ThemedDurationInput:

const kThemedDurationSupported = [
  ThemedUnits.day,
  ThemedUnits.hour,
  ThemedUnits.minute,
  ThemedUnits.second,
];

Dependencies and Blockers

• LayrzTextInput — must ship first; LayrzDurationInput composes it.
• LayrzNumberInput — required for numeric controls inside the picker dialog.
• LayrzTooltip — required for help affordances if using helpTitleText / helpContentText.
• Material-free TextSelectionControls — if LayrzTextInput requires copy/paste in read-only mode, this blocker applies.
• i18n Support — humanized duration formatting requires localization strings for unit names (days, hours, minutes, seconds).

Implementation Notes from layrz_theme

• Step controls: The numeric input controls inside the dialog include +/− step buttons for easy adjustment.
• Reset button: The dialog includes a "Reset" button to set all units to 0.
• Field value update: When the dialog closes, the field's display text is updated with the newly formatted duration.
• Humanized formatting: The duration is formatted using a humanization library; the format respects the visible units and the current locale.

Open Questions

1. Additional time units: Should year, month, and week be added as optional visible units? Currently, only day/hour/minute/second are supported.

2. Unit constraints: Should there be maximum values for each unit (e.g., hours capped at 23, minutes at 59)? Or should overflow be allowed and calculated into days?

3. Formatting options: Should there be a valueFormatter callback to customize the human-readable summary display? Or is localized humanization the only option?

4. Keyboard entry: Can users type values directly into the numeric input fields, or only use step buttons?

5. Negative durations: Should negative durations be supported, or are all values constrained to ≥ 0?

6. Dialog height/constraints: Is the dialog height fixed, or does it adapt based on the number of visible units?

7. Millisecond precision: Should millisecond duration component be supported if needed (e.g., for timeout values)?

---

Last updated: 2026-08-13
Related documents: Input Contract, Component Catalog, Design Tokens