# PasswordInput

A password input is a specialized text field that masks user input to protect sensitive information like passwords, PINs, or security codes. It includes a toggle button to reveal or hide the password text for user convenience.

## When to Use

- Collect passwords, PINs, or other sensitive text data
- Provide secure input fields in login and registration forms
- Enable password creation with visibility toggle for verification
- Collect security codes or tokens that should be masked by default
- Offer accessible password entry with reveal functionality

## Component

---

### Properties

- **`value`** `string` — The password value in controlled mode
- **`defaultValue`** `string` — The default password value in uncontrolled mode
- **`placeholder`** `string` — Placeholder text when input is empty
- **`icon`** — Icon element rendered before the input
- **`prefix`** — Input decoration before the main input
- **`suffix`** — Input decoration after the main input (before toggle button)
- **`suffixPosition`** `'before' | 'after'` (default: `after`) — Position of suffix relative to validation/loading icons
- **`size`** `'small' | 'medium' | 'large'` (default: `medium`) — Input size
- **`autocomplete`** `string` — HTML autocomplete attribute for browser autofill behavior
- **`inputProps`** `Props` — Direct props passed to the native input element
- **`wrapperProps`** `Props` — Direct props passed to the input wrapper element
- **`onChange`** `function` — Callback fired when the input value changes
- **`onBlur`** `function` — Callback fired when the input loses focus
- **`onFocus`** `function` — Callback fired when the input receives focus

### Base Properties

Supports [Base properties](../../BaseProperties.md)

### Field Properties

Supports all [Field properties](../../FieldProperties.md)

### Styling Properties

#### styles

Customizes the root wrapper element of the component.

**Sub-elements:**
- `Prefix` - Element displayed before the input
- `Suffix` - Element displayed after the input (contains toggle button)
- `State` - Container for validation state indicators
- `InputIcon` - Icon displayed within the input area
- `ValidationIcon` - Icon displayed for validation state

#### inputStyles

Customizes the password input field specifically.

### Style Properties

These properties allow direct style application without using the `styles` prop:

- **Base:** `display`, `font`, `preset`, `hide`, `whiteSpace`, `opacity`, `transition`
- **Position:** `gridArea`, `order`, `gridColumn`, `gridRow`, `placeSelf`, `alignSelf`, `justifySelf`, `zIndex`, `margin`, `inset`, `position`
- **Dimension:** `width`, `height`, `flexBasis`, `flexGrow`, `flexShrink`, `flex`
- **Block:** `border`, `radius`, `shadow`, `outline`, `padding`, `paddingInline`, `paddingBlock`, `overflow`, `scrollbar`, `textAlign`
- **Color:** `color`, `fill`, `fade`, `image`

### Modifiers

The `mods` property accepts the following modifiers you can override:

- **`focused`** `boolean` — Whether the input has focus
- **`disabled`** `boolean` — Whether the password input is disabled
- **`invalid`** `boolean` — Whether the password input has validation errors
- **`valid`** `boolean` — Whether the password input is valid
- **`hovered`** `boolean` — Whether the password input is being hovered
- **`inside-form`** `boolean` — Whether the password input is inside a form field

## Variants

### Sizes

- `small` - Compact size for dense interfaces
- `medium` - Standard size
- `large` - Emphasized size for important password fields

## Examples

### Basic Usage

```jsx
<PasswordInput
  label="Password"
  placeholder="Enter your password"
/>
```

### With Icon

```jsx
<PasswordInput
  label="Security Key"
  icon={<IconKey />}
  placeholder="Enter security key"
/>
```

### With Validation

```jsx
<PasswordInput
  label="New Password"
  isRequired
  validationState="invalid"
  errorMessage="Password must be at least 8 characters"
/>
```

### With Description

```jsx
<PasswordInput
  label="Password"
  description="Must be at least 8 characters with numbers and symbols"
  placeholder="Create a strong password"
/>
```

### Small Size

```jsx
<PasswordInput
  label="PIN"
  size="small"
  placeholder="Enter 4-digit PIN"
/>
```

### Disabled State

```jsx
<PasswordInput
  label="Disabled password"
  isDisabled
  value="hidden-password"
/>
```

### With Default Value

```jsx
<PasswordInput
  label="Current Password"
  defaultValue="existing-password"
/>
```

## Accessibility

### Keyboard Navigation

- `Tab` - Moves focus to the password input
- `Shift + Tab` - Moves focus to the toggle button
- `Enter` - Toggles password visibility when toggle button is focused
- `Space` - Toggles password visibility when toggle button is focused
- All standard text input keyboard shortcuts work for text entry

### Screen Reader Support

- Component announces as "password" input type to screen readers
- Toggle button announces its purpose ("Toggle masking", "Show password", "Hide password")
- Current visibility state is communicated when changed
- Validation errors and requirements are announced

### ARIA Properties

- `aria-label` - Provides accessible label when no visible label exists
- `aria-labelledby` - References external label elements
- `aria-describedby` - References additional descriptive text
- `aria-invalid` - Indicates validation state
- `aria-required` - Indicates if password entry is required
- Toggle button includes appropriate `aria-label` for its function

## Best Practices

1. **Do**: Provide clear password requirements and feedback
   ```jsx
   <PasswordInput
     label="New Password"
     description="8+ characters, including numbers and symbols"
     validationState={isValid ? "valid" : "invalid"}
   />
   ```

2. **Don't**: Use password input for non-sensitive data
   ```jsx
   <PasswordInput label="Username" /> {/* Use TextInput instead */}
   ```

3. **Security**: Always use HTTPS when handling password inputs
4. **Validation**: Provide real-time validation feedback for password creation
5. **Accessibility**: Ensure toggle button is easily accessible via keyboard
6. **UX**: Include the visibility toggle for better user experience

## Integration with Forms

This component supports all [Field properties](../../FieldProperties.md) when used within a Form.

## Suggested Improvements

- Add password strength indicator with visual feedback
- Implement configurable password requirements validation
- Add support for custom toggle button icons or text
- Consider adding copy-to-clipboard functionality for generated passwords
- Implement password suggestion/generation features

## Related Components

- [TextInput](./TextInput.md) - For non-sensitive text input
- [NumberInput](./NumberInput.md) - For numeric PIN entries
- [SearchInput](./SearchInput.md) - For search functionality
