---

## PinInput
Segmented one-time-code / PIN entry — a row of single-character
cells with auto-advance, backspace-to-previous, paste-to-fill, and optional
masking. Purpose-built for the 2FA/OTP step: the first cell carries
`autocomplete="one-time-code"` on its own, so iOS offers an incoming SMS code
as a keyboard suggestion. The value is the concatenated string; `onComplete`
fires each time the row becomes complete.

The instance (`bind:this`) has one method, `focus()`: it puts the caret on
the first empty cell — cell 0 after a clear, the last cell when the row is
full — and does nothing while `disabled`; a `readonly` row stays a focus
target. The retry after a rejected code is `value = ''` followed by
`focus()`, in that order and in the same tick if you like; from inside
`onComplete` it wins over the row's own auto-advance. `autoFocus` is the
same call, made on mount and whenever it turns true.

**Import:** `import { PinInput } from '@urbicon-ui/blocks';`

### Examples
```svelte
<script>
  let code = $state('');
</script>
<PinInput bind:value={code} length={6} onComplete={(v) => verify(v)} />
```

```svelte
<PinInput length={8} type="alphanumeric" mask separator="-" groupSize={4} />
```

```svelte
<script lang="ts">
let code = $state('');
let error = $state('');
let pin: ReturnType<typeof PinInput> | undefined = $state();

async function verify(v: string) {
if (await verifyTwoFactor(v)) return;
error = 'Incorrect code';
code = '';
pin?.focus();
}
</script>
<PinInput bind:this={pin} bind:value={code} {error} onComplete={verify} />
```

### Variants
- intent: danger, default, success, warning (default: default)
- variant: filled, ghost, outlined (default: outlined)
- size: lg, md, sm (default: md)
- disabled: true (default: false)
- messageType: error, helper (default: helper)
- readonly: true (default: false)
- required: true (default: false)
- tier: commit, modify (default: modify)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| ...HTMLAttributes<HTMLDivElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'class' | 'id' | 'aria-label') |
| ...PinInputVariants | `VariantProps` | no |  | Styling variants from PinInputVariants |
| aria-label | `string` | no |  | Accessible name for the cell group when no visible `label` is set. Each cell additionally announces its position ("Character 2 of 6"). |
| autoFocus | `boolean` | no | false | Calls `focus()` on mount and whenever it turns true — the caret lands on the first empty cell, and no later edit moves it again. Does nothing while `disabled`. For the retry after a rejected code, call `focus()` on the instance instead. |
| class | `string` | no |  | Extra classes merged onto the root element. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| disabled | `boolean` | no | false | Blocks input and dims the whole row. |
| error | `string` | no |  | Error message below the cells. When set it overrides `helper`, colours the cells danger, and sets `aria-invalid` on every cell. |
| groupSize | `number` | no | 3 | Cells per group when `separator` is set. |
| helper | `string` | no |  | Helper text below the cells — hidden when `error` is present. |
| id | `string` | no |  | Root id; the cells derive their ids and ARIA wiring from it. |
| label | `string` | no |  | Group label rendered above the cells and linked via `aria-labelledby`. |
| length | `number` | no | 6 | Number of cells. |
| mask | `boolean` | no | false | Render each filled cell as a masked dot (password style). For a standing PIN or passcode, not for a throwaway SMS code — masking one buys no secrecy and costs the user the ability to check what they typed. |
| name | `string` | no |  | Shared `name` for a hidden input, for native form submission. |
| onComplete | `(value: string) => void` | no |  | Fires each time the row becomes complete, with the full value — so correcting a rejected code fires it again. Not once per mount. |
| onValueChange | `(value: string) => void` | no |  | Fires after any change (typing, paste, backspace) with the full value. |
| placeholder | `string` | no | '' | Placeholder character shown in every empty cell. |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ PinInput: {...} }}>`. |
| readonly | `boolean` | no | false | Shows the value but refuses edits; the cells stay focusable. |
| required | `boolean` | no | false | Marks the label with an asterisk and sets `aria-required` on the cells. It does not block a native submit — the value lives in component state, so validate it yourself before you act on it. |
| separator | `string` | no |  | Render a separator between groups of `groupSize` cells (e.g. `123-456`). A string is shown verbatim; omit for no separator. |
| slotClasses | `Partial<Record<PinInputSlots, string>>` | no |  | Per-slot class overrides merged with tv() styles. Slots: root (what `class` also targets) | label | requiredMark | group | cell | separator | message. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| type | `'numeric' | 'alphanumeric'` | no | 'numeric' | Allowed characters and keyboard hint. `numeric` accepts `0-9` and sets a numeric inputmode; `alphanumeric` also accepts `A-Z`/`a-z`. |
| unstyled | `boolean` | no |  | Remove all default tv() classes — only user-provided classes apply. |
| uppercase | `boolean` | no | false | Uppercase alphanumeric input as it is entered — keeps a code like `ABCD` visually consistent regardless of caps lock. Ignored for `numeric`. |
| value | `string` | no |  | Current value — the concatenated cell characters. Supports `bind:value`. |
| intent | `'danger' | 'default' | 'success' | 'warning'` | no | default | Controls the color theme and semantic meaning of the PinInput. Affects the overall appearance and user perception. Available options: danger, default, success, warning. |
| variant | `'filled' | 'ghost' | 'outlined'` | no | outlined | Controls the visual style and presentation of the PinInput. Determines the component's visual treatment. Available options: filled, ghost, outlined. |
| size | `'lg' | 'md' | 'sm'` | no | md | Controls the dimensions, padding, and text size of the PinInput. Affects the component's physical footprint. Available options: lg, md, sm. |
| messageType | `'error' | 'helper'` | no | helper | Controls the messageType behavior and appearance of the PinInput component. Available options: error, helper. |
| tier | `'commit' | 'modify'` | no | modify | Selects the semantic radius tier of the PinInput — the shape family it belongs to (`--radius-commit`/`-modify`/`-contain`/`-bridge`). Shape is retuned per family in your theme, so this picks the family rather than a pixel value. Available options: commit, modify. |

Inherited from:
- Omit<PinInputVariants, 'error'> (omit-pattern)
- Omit<HTMLAttributes<HTMLDivElement>, 'class' | 'id' | 'aria-label'> (omit-pattern)

### Types
```ts
type SlotNames = keyof ReturnType<T> & string
```

```ts
type VariantProps = Omit<
  Exclude<Parameters<T>[0], undefined>,
  'class'
>
```

### Slots (slotClasses keys)
`root`, `label`, `requiredMark`, `group`, `cell`, `separator`, `message`