# PasswordField

Single-line password input with masked value, visibility toggle, Caps Lock detection, and an optional strength meter. Composes inside `Field.Provider` (OR-merges `disabled` / `readonly` / `required` / `invalid`).

## Anatomy

```svelte
<PasswordField.Provider bind:value bind:visible purpose="new">
	<PasswordField.Input placeholder="At least 8 characters" />
	<PasswordField.VisibilityTrigger />
	<PasswordField.CapsLockIndicator />
	<PasswordField.StrengthMeter />
</PasswordField.Provider>
```

## Parts

| Part                  | Element    | Description                                                                                |
| --------------------- | ---------- | ------------------------------------------------------------------------------------------ |
| `Provider`            | `<div>`    | Root context. Holds value, visibility, autocomplete purpose, OR-merged Field state.        |
| `Input`               | `<input>`  | The real input. `type` flips between `password` and `text` from `visible`.                 |
| `VisibilityTrigger`   | `<button>` | Toggles `visible`. Renders Eye / EyeOff icons in the eidos wrapper.                        |
| `CapsLockIndicator`   | `<span>`   | Live region announcing Caps Lock state; visible only when the input is focused + caps on.  |
| `StrengthMeter`       | `<div>`    | Visual 0–4 meter. Reads `calculateStrength(value)` by default; override via `strength`.    |

## Props

### `Provider`

| Prop                | Type                                              | Default                | Description                                                            |
| ------------------- | ------------------------------------------------- | ---------------------- | ---------------------------------------------------------------------- |
| `value`             | `string`                                          | `''`                   | Controlled value. `bind:value` supported.                              |
| `onValueChange`     | `(value: string) => void`                         | —                      | Per-keystroke change.                                                  |
| `onSubmit`          | `(value: string) => void`                         | —                      | Fires on `Enter` in the Input.                                         |
| `visible`           | `boolean`                                         | `false`                | Plaintext mode. `bind:visible` supported.                              |
| `onVisibilityChange`| `(visible: boolean) => void`                      | —                      | Fires when the trigger flips visibility.                               |
| `purpose`           | `'current' \| 'new'`                              | `'current'`            | Drives `autocomplete` (`current-password` / `new-password`).           |
| `minLength`         | `number`                                          | —                      | Forwarded to the input.                                                |
| `maxLength`         | `number`                                          | —                      | Forwarded to the input.                                                |
| `disabled`          | `boolean`                                         | `false`                | OR-merged with `Field.disabled`.                                       |
| `readonly`          | `boolean`                                         | `false`                | OR-merged with `Field.readonly`.                                       |
| `required`          | `boolean`                                         | `false`                | OR-merged with `Field.required`.                                       |
| `invalid`           | `boolean`                                         | `false`                | OR-merged with `Field.invalid`.                                        |
| `calculateStrength` | `(pw: string) => number \| PasswordStrengthResult`| `passwordStrength`     | Strength algorithm. Default is `passwordStrength` from `$libs/secs`.   |
| `aria-label`        | `string`                                          | translated `Password`  | Accessible name when no `Field.Label` is present.                      |

### `StrengthMeter`

| Prop       | Type                                                  | Default          | Description                                                           |
| ---------- | ----------------------------------------------------- | ---------------- | --------------------------------------------------------------------- |
| `strength` | `number`                                              | provider-derived | Override the auto-computed score. Clamped to 0–4.                     |
| `labels`   | `readonly [string, string, string, string, string]`   | translated set   | Bucket labels. Defaults to `Very weak / Weak / Acceptable / Strong / Very strong`. |

## ARIA

| Part                | Attribute             | Value                                                                |
| ------------------- | --------------------- | -------------------------------------------------------------------- |
| Input               | `aria-invalid`        | When `invalid` is true                                               |
| Input               | `aria-required`       | When `required` is true                                              |
| Input               | `aria-labelledby`     | From `Field.Label` when composed inside Field                        |
| Input               | `autocomplete`        | `current-password` / `new-password` from `purpose`                   |
| VisibilityTrigger   | `aria-pressed`        | Reflects `visible`                                                   |
| VisibilityTrigger   | `aria-label`          | `Show password` / `Hide password` (translated, flips with state)     |
| VisibilityTrigger   | `tabindex`            | `-1` — not in the tab order (toggle via the icon, not Tab)           |
| CapsLockIndicator   | `aria-live`           | `polite`                                                             |
| StrengthMeter       | `role`                | `meter`                                                              |
| StrengthMeter       | `aria-valuemin`       | `0`                                                                  |
| StrengthMeter       | `aria-valuemax`       | `4`                                                                  |
| StrengthMeter       | `aria-valuenow`       | Current 0–4 score                                                    |

## Keyboard

| Key     | Action                                          |
| ------- | ----------------------------------------------- |
| `Enter` | In the Input → fires `onSubmit(value)`.         |

## Strength algorithm

The default `calculateStrength` is `passwordStrength` from `$libs/secs`. It returns a rich `PasswordStrengthResult` (`score`, `label`, `warnings[]`, `strength`, `isSecure`). The `warnings` are LangRef strings the consumer can translate via `langs.ts(...)`. Override per `<PasswordField>` to plug in zxcvbn, OWASP NIST 800-63B, server-side scoring, etc.

## See also

- Eidos visual: `src/uix/eidos/components/password-field/README.md`
- Strength canon: `src/libs/secs/README.md`
- Field composition: `src/uix/soma/components/field/README.md`