Input Contract

This document defines the shared contract that every Layrz*Input component in layrz_ui conforms to. Rather than specifying this per-component, the contract is recorded here as the single source of truth for input field behavior, styling, and API, so the architectural decisions need to be made only once.

Central Architectural Fact: Composition Over Reimplementation

LayrzTextInput is the base of the entire input family. Every other Layrz*Input composes LayrzTextInput internally rather than reimplementing the field chrome. This is the same architectural pattern used in layrz_theme.

The picker-style inputs (date, time, color, emoji, etc.) render as a read-only LayrzTextInput that opens their selection surface on tap.

Consequences

Shipping order: LayrzTextInput must ship first in M2 (shipped in 0.0.9). Every other input depends on it.
Visual decisions are global: The chrome of LayrzTextInput — label, prefix/suffix, help affordance, padding, error display, focus state, border decoration — is the chrome of every input in the system. Design decisions made for LayrzTextInput propagate to all inputs.
No separate input-container: LayrzTextInput itself plays the role of the input container. There is no separate wrapper component; all input chrome is part of LayrzTextInput.

Naming Convention: `Input` Replaces `Picker`

Every form field in layrz_ui is named Layrz*Input, regardless of how it collects its value. The *Picker suffix from layrz_theme is retired entirely.

Renamed Components

layrz_theme Name	layrz_ui Name	Collection Method
ThemedDatePicker	LayrzDateInput	Calendar dialog
ThemedTimePicker	LayrzTimeInput	Time picker dialog
ThemedDateTimePicker	LayrzDateTimeInput	Calendar + time in tabbed dialog
ThemedMonthPicker	LayrzMonthInput	Month + year grid
ThemedEmojiPicker	LayrzEmojiInput	Emoji selection dialog
ThemedColorPicker	LayrzColorInput	Color wheel/palette dialog
ThemedFilePicker	LayrzFileInput	System file browser
ThemedIconPicker	LayrzIconInput	Icon selection dialog
ThemedAvatarPicker	LayrzAvatarInput	System image picker

Rationale

The *Picker suffix suggests a distinct interaction pattern from form fields. In layrz_ui, all of these components are inputs that participate in forms like any text field or select field. They are not separate pickers; they are inputs with selection surfaces. The unified naming clarifies this conceptual unity.

The Shared Contract

Every Layrz*Input exposes the following API, inherited from LayrzTextInput.

Field Identification and Labels

// Design sketch — illustrative only
class LayrzTextInput extends StatefulWidget {
  /// The label text displayed above the input field (optional if hintText is provided).
  /// 
  /// This is the only label representation; a `label` Widget parameter is not supported.
  /// At least one of [labelText] or [hintText] must be non-null.
  final String? labelText;

  /// Hint text displayed inside the empty field (optional if labelText is provided).
  /// 
  /// Shown inside the field, disappears when the field has text.
  /// At least one of [labelText] or [hintText] must be non-null.
  final String? hintText;

  // ...
}

At least one of labelText or hintText is mandatory — the widget asserts labelText != null || hintText != null in debug mode
Both can be non-null — a field can have both a label and a hint
No label Widget parameter; labels are text-only

Prefix and Suffix

Each input supports both a leading prefix and a trailing suffix. At most one of the three forms (icon, widget, or text) may be supplied per slot; providing multiple triggers a debug assertion.

// Design sketch — illustrative only
class LayrzTextInput extends StatefulWidget {
  /// Icon displayed in the prefix slot.
  /// 
  /// Mutually exclusive with [prefix] and [prefixText].
  final IconData? prefixIcon;

  /// Custom widget displayed in the prefix slot.
  /// 
  /// Mutually exclusive with [prefixIcon] and [prefixText].
  final Widget? prefix;

  /// Text displayed in the prefix slot.
  /// 
  /// Mutually exclusive with [prefixIcon] and [prefix].
  final String? prefixText;

  /// Callback invoked when the user taps the prefix.
  final VoidCallback? onPrefixTap;

  /// Icon displayed in the suffix slot.
  /// 
  /// Mutually exclusive with [suffix] and [suffixText].
  final IconData? suffixIcon;

  /// Custom widget displayed in the suffix slot.
  /// 
  /// Mutually exclusive with [suffixIcon] and [suffixText].
  final Widget? suffix;

  /// Text displayed in the suffix slot.
  /// 
  /// Mutually exclusive with [suffixIcon] and [suffix].
  final String? suffixText;

  /// Callback invoked when the user taps the suffix.
  final VoidCallback? onSuffixTap;

  // ...
}

Prefix slot: At most one of prefixIcon, prefix, or prefixText may be non-null; supplying multiple triggers a debug assertion.
Suffix slot: At most one of suffixIcon, suffix, or suffixText may be non-null; supplying multiple triggers a debug assertion.
Error icons coexist: The error icon is independent and always appears in the suffix when errors is non-empty
Read-only lock icon coexists: In read-only mode, a lock icon also appears in the suffix alongside caller-supplied suffix widgets

Semantics

A prefix or suffix slot always renders — the accessibility gap is in what it announces, and the rules differ by form:

A non-tappable icon slot with no name is decorative and is deliberately hidden from screen readers (ExcludeSemantics). There is nothing for it to announce, so it is removed from the tree rather than left as noise.
Text slots merge into the field's accessible name. prefixText: '$' on a field labelled 'Amount' announces as one name, not two. This is intended: '$', 'kg', '@' and similar unit/currency markers belong in the field's name, not in a separate node.
onPrefixTap:/onSuffixTap: currently create a pointer-only affordance. The icon or text is rendered and fully tappable, but it is not announced to a screen reader and it is never a keyboard focus stop. This is deliberate, not an oversight: the chrome constructs the icon or text itself, has no name for what tapping it does, and will not invent or infer one from the icon you chose — an anonymous action announced on the field's own node would be worse than no announcement at all, because it would misdirect the person using it.
What to do instead, as a contract rather than an omission: pass a real, focusable, labelled widget through prefix:/suffix: instead of the prefixIcon:/prefixText: + onPrefixTap: callback forms. A widget you supply is passed through untouched — the chrome does not exclude or reinterpret it — so any Semantics you attach to it survives exactly as you built it. The icon/text + callback forms have no such seam: there is nothing in them for you to attach a label to.
Any Semantics you attach inside that widget must set container: true. Semantics fragments from the chrome's descendants merge into the field's own single node by default, so a Semantics without container: true does not get a node of its own — its role, label, and tap action merge onto the text field's node instead. The field then announces as your control and fires your callback when activated, which is the exact defect container: true exists to prevent (see the chrome's own named-slot boundary in input_chrome.dart):
```
// Wrong — merges onto the field's own semantics node
prefix: Semantics(
  button: true,
  label: 'Copy',
  onTap: _copy,
  child: const Icon(LayrzIcons.solarOutlineCopy),
),

// Right — container: true keeps it a node of its own
prefix: Semantics(
  container: true,
  button: true,
  label: 'Copy',
  onTap: _copy,
  child: const Icon(LayrzIcons.solarOutlineCopy),
),
```
The gap is known and scheduled, not overlooked. Public prefixSemanticLabel:/suffixSemanticLabel: parameters are planned for the chrome-composing inputs, deferred so the M4 Pickers milestone can inform their final shape. Until they ship, a tappable icon/text slot built through the callback forms has no way to be named from outside this package. See decisions.md, D64 for the full mechanism and rationale.

Help Affordance

An informational tooltip can be paired with the label, accessed via hover on desktop or long-press on mobile.

// Design sketch — illustrative only
class LayrzTextInput extends StatefulWidget {
  /// Title text displayed in the help tooltip.
  /// 
  /// If supplied, a help icon appears and opens a tooltip on hover/long-press.
  final String? helpTitleText;

  /// Body text displayed in the help tooltip.
  /// 
  /// Shown below [helpTitleText] in the tooltip popup.
  final String? helpContentText;

  // ...
}

helpTitleText and helpContentText form a two-part help message.
Rendered as a tooltip component (wrapping the SDK's RawTooltip).

Validation and Error Display

Errors are caller-owned. There is no built-in validator callback. Callers provide error messages directly as a list.

// Design sketch — illustrative only
class LayrzTextInput extends StatefulWidget {
  /// List of error messages to display below the field.
  /// 
  /// Caller-owned; no automatic validation.
  /// Multiple errors are joined with ", " (comma-space) into a single line.
  /// When non-empty, an error icon appears in the field and the joined message
  /// is rendered below the field in danger colour.
  final List<String> errors;

  /// Whether to hide the error message text below the field.
  /// 
  /// When true, error messages are not rendered (though the field's error visual state remains).
  final bool hideDetails;

  // ...
}

errors is a List<String>, not a validator callback. Callers manage validation and provide error messages.
Errors are joined with ", " into a single line (e.g., ['required', 'too short'] renders as 'required, too short')
Error visual state on field: When errors is non-empty, the field border becomes danger colour, the background becomes danger.shade50, and an error icon is displayed in the suffix.
hideDetails: When true, error messages below the field are hidden (but the field's error visual state remains).

Interactivity

// Design sketch — illustrative only
class LayrzTextInput extends StatefulWidget {
  /// Callback invoked when the input value changes.
  final ValueChanged<String>? onChanged;

  /// Callback invoked when the user submits the input (e.g., via Enter on desktop).
  final ValueChanged<String>? onSubmit;

  /// Callback invoked when the input gains or loses focus.
  final ValueChanged<bool>? onFocusChanged;

  /// Callback invoked when the user taps anywhere on the input field.
  /// 
  /// Distinct from [onPrefixTap] and [onSuffixTap]. Useful for picker-style inputs
  /// to open their selection surface. Fires even in read-only mode, but not in disabled mode.
  final VoidCallback? onTap;

  /// Whether the field is disabled (not editable, not tappable).
  /// 
  /// When true, keyboard input is blocked, the field does not respond to taps,
  /// and no callbacks fire. Text is darkened to fg4 and border becomes transparent.
  final bool disabled;

  /// Whether the field is read-only (not editable, but tappable).
  /// 
  /// When true, the field displays a value but is not directly editable.
  /// Callbacks like [onTap], [onPrefixTap], and [onSuffixTap] still fire.
  /// A lock icon is displayed in the suffix to signal read-only mode.
  /// Picker-style inputs use this to present a read-only display of the selected value.
  final bool readOnly;

  // ...
}

onChanged and onSubmit are independent callbacks.
onFocusChanged receives true when focus is gained, false when lost.
onTap fires in read-only mode (for pickers) but not in disabled mode.
disabled blocks all taps and input; text darkens to fg4; border becomes transparent.
readOnly allows onTap to fire (for pickers) and displays a lock icon in the suffix; rest fill and transparent border.

Focus and Lifecycle Management

// Design sketch — illustrative only
class LayrzTextInput extends StatefulWidget {
  /// Focus node for this input field.
  /// 
  /// If null, the widget constructs a node in [initState].
  /// The widget disposes only nodes it creates. Caller-supplied nodes are left untouched.
  final FocusNode? focusNode;

  /// Text controller for this input field.
  /// 
  /// If null, the widget constructs a controller in [initState].
  /// The widget disposes only controllers it creates. Caller-supplied controllers are left untouched.
  final TextEditingController? controller;

  // ...
}

Disposal contract: The widget disposes ONLY the instances it created; caller-supplied instances are left untouched. This is the standard pattern and prevents controller leaks, but bears explicit documentation because it is a common source of bugs.

Layout and Styling

// Design sketch — illustrative only
class LayrzTextInput extends StatefulWidget {
  /// Padding applied inside the input field around the text and slots.
  /// 
  /// When null, defaults to `pd2` (8 logical pixels on all sides).
  /// Can be overridden per-field to support custom layouts.
  final EdgeInsets? padding;

  // ...
}

padding uses spacing tokens from the design-tokens document by default (pd2, 8 logical pixels uniformly).
Customizable per-field via the padding parameter.

Layout in Rows

When laying out inputs side-by-side in a Row, use CrossAxisAlignment.start on the Row. Inputs with error messages or labels are taller than those without, and the default CrossAxisAlignment.center alignment will misalign field boxes across the row and prevent error messages from hanging cleanly below. With CrossAxisAlignment.start, all field boxes sit on the same line regardless of label or error message height.

Value Display and Formatting

Concrete inputs compose LayrzTextInput and supply display text through the controller. Any visual affordance (color swatch, avatar thumbnail, icon preview) is rendered through the existing prefix widget parameter.

Each concrete input specifies:

The value type it holds (Color, DateTime, List<String>, etc.).
How to format that value for display in the controller's text.
The widget to render as a visual affordance in the prefix slot (if any).

What Each Concrete Input Adds

Every concrete Layrz*Input specifies only its deltas from the base contract:

Value type — the data structure the input holds (e.g., Color, DateTime, Duration).
Selection surface — the dialog or interaction pattern used to set the value (e.g., calendar picker, color wheel, emoji grid).
Input-specific parameters — validation rules, formatting options, or constraints particular to the input type.

Illustrative Examples

Input	Value Type	Selection Surface	Notes
LayrzNumberInput	`double`	Stepper buttons + keyboard input	Min/max bounds, decimal formatting, step value
LayrzSelectInput	`String` (or generic `T`)	Searchable dropdown dialog	Single selection, custom item rendering
LayrzMultiSelectInput	`List<String>` (or generic `List<T>`)	Searchable dropdown with checkboxes	Multiple selection, checkboxes for visibility
LayrzCheckboxInput	`bool`	Inline checkbox, switch, or dropdown field	Style variants: checkbox, switch, field (dropdown)
LayrzColorInput	`Color`	Color wheel and/or palette picker	Hand-rolled to avoid Material dependency
LayrzFileInput	`{base64: String, bytes: Uint8List}`	System file browser	Returns both base64 and raw bytes
LayrzIconInput	`IconData`	Icon selection dialog	Picker over Solar icon set with search
LayrzAvatarInput	`String` (base64)	System image picker	Stores image as base64, displays thumbnail

This table is illustrative of the pattern, not the complete catalogue. See Component Catalog for the full mapping of layrz_theme to layrz_ui inputs.

Shared Dependencies for the Entire Input Family

M1 Spacing Tokens

All default padding and inner spacing come from the spacing and radius token systems. The spacing tokens use five semantic levels: sp1 (4px), sp2 (8px), sp3 (16px), sp4 (24px), sp5 (32px). The radius tokens follow the same five-level model: r1 (4px), r2 (8px), r3 (16px), r4 (24px), r5 (32px). See the design-tokens document for detailed token specifications.

Impact: Spacing is consistent across all inputs and customizable from the theme.

Tooltip Component

The help affordance is built on the tooltip component, which wraps the SDK's RawTooltip. This must be available for all inputs to render help text.

Dependency: LayrzTooltip (M2) shipped in 0.0.7.

Material-Free Text Selection (DESIGN-74)

The SDK's EditableText ships with selection-handle positioning, drag-selection via keyboard, and keyboard selection (Ctrl+A, Ctrl+C). Touch drag handles, a selection toolbar, and the magnifier are deferred to DESIGN-74. LayrzTextInput is configured with selectionControls: null and contextMenuBuilder: null, making the selection overlay invisible while keyboard-driven selection remains functional.

Current state: Text selection and keyboard shortcuts work. Touch affordances (drag handles, selection toolbar) are DESIGN-74 scope and may land after the initial M2 ship.

Reference

See the flutter-347-audit document for the full analysis of SDK dependencies and Material coupling.

Interaction State Matrix

LayrzTextInput renders in six visual states. This matrix is the shared chrome for the entire input family:

State	Fill	Border (always 1.5px)	Text
Rest	`surface2`	transparent	`fg1`, hint `fg3`
Hover	`surface3`	transparent	`fg1`
Focus	`surface2`	`colors.primary`	`fg1`
Error	`colors.danger.shade50`	`colors.danger`	`fg1`
Disabled	`surface2`	transparent	`fg4`
Read-only	`surface2`	transparent	`fg1` + lock icon

State precedence: disabled > read-only > error > pressed > hover/focused > default.

Key characteristics:

Focus preserves fill — focus only changes the border to primary; fill stays surface2 (not elevated to surface)
Read-only is rest + lock icon — uses the rest state fill and transparent border, with a lock icon in the suffix
Disabled darkens text to fg4 and uses transparent border to signal permanent non-editability
All borders are solid — all six states use solid borders with constant width (1.5px) and radius (r2, 8 logical pixels)
Transparency creates invisible borders — states without a border color use transparent Color(0x00000000) to maintain constant geometry
Error state has danger colours on both fill and border
Light mode only — dark theme variants are out of scope (decision D7)
Fixed content height — padding is separate from content height; all inputs use the same default padding (pd2, 8 logical pixels uniformly)

Progress Tracking

Progress for input components and milestones is tracked in the Milestone Status tables in the repository documentation. See engineering/milestone-2.md for M2 work items and status.

Documentation files record specification and architecture; milestone tables record progress.

Last updated: 2026-08-18
Related documents: Component Catalog, design-tokens, architecture, roadmap, decisions, flutter-347-audit

Made with ❤️ by Golden M, Inc.

Home

Getting Started

Foundation

Reference

Widgets

Widgets

Uh oh!

Input Contract

Input Contract

Central Architectural Fact: Composition Over Reimplementation

Consequences

Naming Convention: *Input Replaces *Picker

Renamed Components

Rationale

The Shared Contract

Field Identification and Labels

Prefix and Suffix

Semantics

Help Affordance

Validation and Error Display

Interactivity

Focus and Lifecycle Management

Layout and Styling

Layout in Rows

Value Display and Formatting

What Each Concrete Input Adds

Illustrative Examples

Shared Dependencies for the Entire Input Family

M1 Spacing Tokens

Tooltip Component

Material-Free Text Selection (DESIGN-74)

Reference

Interaction State Matrix

Progress Tracking

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Naming Convention: `Input` Replaces `Picker`