LayrzPasswordInput

LayrzPasswordInput

Password entry field with strength indicator and show/hide toggle.

---

Specification Status

DERIVED from layrz_theme. This specification is extracted from the current ThemedPasswordInput API and awaits team confirmation. Details may change during the M3 inputs review.

---

Metadata

Field	Value
Mirrors	ThemedPasswordInput from layrz_theme
Phase	M3 (Core Inputs)
Domain	Inputs
Composes	LayrzTextInput (base chrome + keyboard)
SDK Primitive	EditableText (via LayrzTextInput), no Material/Cupertino show/hide toggle

---

Conformance

LayrzPasswordInput conforms to the shared input contract and composes LayrzTextInput internally to achieve consistent chrome and keyboard handling. Only input-specific deltas are documented here. For the baseline API (labelText, placeholder, prefix, suffix, help affordances, onChanged, onTap, readOnly, focusNode, controller, padding), refer to the contract.

---

Value Type and Interaction

• Value type: String (mutable via TextEditingController)
• Interaction: Masked text entry with optional visibility toggle
• Strength feedback: Optional linear progress indicator filling based on password strength

---

Deltas from the Input Contract

LayrzPasswordInput adds the following over LayrzTextInput:

Password-Specific Behavior

• obscureText (bool, implicit) — the field is always rendered with text obscured (•••) by default. The toggle controlled by showLevels or a separate affordance reveals the actual text.
• showLevels (bool) — whether to display a password strength progress indicator below or within the input. When true, a visual meter (e.g., linear progress) fills based on password strength (0–4 levels). Default: true.

Autofill Hints

• autofillHints (List<String>) — platform autofill hints for password managers. Defaults to [AutofillHints.newPassword, AutofillHints.password] to enable browser autofill and password manager suggestions. Can be overridden to use only AutofillHints.newPassword (for password creation) or AutofillHints.password (for existing password updates).

Strength Calculation

The strength indicator is calculated internally based on four requirements and five strength levels (0–4):

Requirements (each met = +25% fill):

1. Contains at least one lowercase letter ([a-z])
2. Contains at least one uppercase letter ([A-Z])
3. Contains at least one digit ([0-9])
4. Contains at least one special character (from a predefined set: !@#$%^&*()_-+=[]{}; : ' ", . < > / ? ~|`)

Strength Levels (based on requirements met + length):

• Level 0 (0%): Invalid or too short (< 8 characters), or requirements not met
• Level 1 (25%): Meets all 4 requirements AND 8–11 characters
• Level 2 (50%): Meets all 4 requirements AND 12–15 characters
• Level 3 (75%): Meets all 4 requirements AND 16–19 characters
• Level 4 (100%): Meets all 4 requirements AND 20+ characters

Allowed characters: The field restricts input to alphanumeric + the above special characters. Attempting to enter other characters fails silently (or triggers input formatter rejection).

Callbacks

• onChanged (ValueChanged<String>?) — invoked when the password text changes.
• onSubmitted (VoidCallback?) — invoked when the user submits the input.

State

• value (String?) — the current password string.
• disabled (bool) — when true, input is blocked and the strength meter (if shown) is hidden or grayed out.
• focusNode (FocusNode?) — inherited from LayrzTextInput.
• controller (TextEditingController?) — inherited from LayrzTextInput.

---

Reference: ThemedPasswordInput API

For porting purposes, the current layrz_theme implementation exposes (extracted from source):

// Design sketch — parameter names from layrz_theme source
class ThemedPasswordInput extends StatefulWidget {
  final String? labelText;
  final Widget? label;              // NOT supported (labelText only)
  final String? placeholder;
  final ValueChanged<String>? onChanged;
  final String? value;
  final bool disabled;
  final List<String> errors;
  final bool hideDetails;
  final EdgeInsets? padding;
  final bool isRequired;            // Markup only
  final VoidCallback? onSubmitted;
  final double? borderRadius;       // Controlled by theme
  final FocusNode? focusNode;
  final TextEditingController? controller;
  final bool showLevels;            // Default: true
  final List<String> autofillHints; // Default: [newPassword, password]
}

Internal state (not exposed as parameters):

• _showPassword — tracks whether the password text is currently revealed. Toggled by a show/hide affordance (icon or text).
• requirements — a map of RegExp patterns to i18n translation keys defining the four strength requirements.
• allowed — a RegExp defining the set of characters permitted in the password.
• _matches — computed map of requirement → boolean indicating which requirements the current password meets.
• _level — computed strength level (0–4).
• _color — computed indicator color based on level (red for 0, orange for 1–2, green for 3–4).

---

Dependencies and Blockers

Dependency: LayrzTextInput (M3)

LayrzPasswordInput is fully composed on LayrzTextInput. LayrzTextInput must ship first.

Status: LayrzTextInput is blocked on Material-free TextSelectionControls (see LayrzTextInput).

Dependency: Show/Hide Toggle Affordance

The password must have a mechanism to toggle between obscured and revealed text. In layrz_theme, this is typically an icon button (eye icon) in the suffix slot.

Design required: How is the show/hide toggle rendered? Is it:

• A custom icon button in the suffix slot?
• Integrated into the field's focus/selection UI?
• A separate toggle outside the input?

Status: Awaits design reference.

---

Open Questions

The following decisions are not yet made and must be resolved before implementation.

1. Show/Hide Toggle UI

• Is the show/hide toggle always visible, or only on focus?
• Is it an icon button (e.g., eye icon), text button ("Show/Hide"), or other affordance?
• What is its placement (suffix slot, outside field, integrated)?
• Does the toggle state persist when the field loses focus?

2. Strength Meter Appearance

• Is the strength meter a linear progress bar, circular progress, or other visual metaphor?
• When showLevels is false, is there any visual feedback about password strength?
• Should the meter update in real-time as the user types, or only on blur/submission?
• Should each strength level have distinct text labels (e.g., "Weak", "Fair", "Good", "Strong", "Very Strong")?

3. Strength Calculation Customization

• Can the caller customize the strength requirements (e.g., allow passwords without uppercase, or require special characters)?
• Can the caller customize the length thresholds for each level?
• Can the caller provide a custom strength calculation function?

4. Allowed Characters and Rejection

• When the user attempts to type a disallowed character, does the field:
  • Silently drop the character (no visual feedback)?
  • Show a brief error message or visual indicator?
  • Play a platform-specific rejection sound?

5. Autofill Integration

• Does the field work correctly with platform autofill (browser password managers, OS password managers)?
• Should autofillHints default to [newPassword] for account creation flows and [password] for login flows, or should both always be present?

6. Composition vs. Decoration

• Does LayrzPasswordInput compose LayrzTextInput directly, or does it wrap/decorate it?
• If composed, how is the value synced between the caller's value parameter and LayrzTextInput's controller?
• How is the show/hide toggle state managed — as internal widget state, or as a caller-controlled parameter?

---

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