svelte-kit-vice/src/uix/eidos/components/pin-input/README.md

# `<PinInput>` — eidos

Multi-cell OTP / verification code input. A transparent
absolutely-positioned `<input>` captures every keystroke and paste;
visible bordered cells follow the hidden input's caret. Field-aware
(disabled / readonly / required / invalid OR-merge with the enclosing
Field.Provider).

## Usage

```svelte
<script lang="ts">
  import { PinInput } from '$uix/eidos/components/pin-input';
  let code = $state('');
</script>

<PinInput
  bind:value={code}
  length={6}
  type="numeric"
  size="md"
  onComplete={(value) => console.log('filled:', value)}
>
  {#snippet children({ cells })}
    {#each cells as cell, i}
      <PinInput.Cell {cell} index={i} />
    {/each}
  {/snippet}
</PinInput>
```

## Parts

| Part | Notes |
|---|---|
| `PinInput` (root) | Provider; container + hidden capture input. Exposes `{ cells, isFocused, isHovering, value }` via `children` snippet. |
| `Cell` | One visible cell per character position. Receives `cell` (`PinInputCellData`) and `index` from the snippet. |

## Eidos-layer props

| Prop | Type | Default | Notes |
|---|---|---|---|
| `size` | `'sm' \| 'md' \| 'lg' \| 'xl'` (responsive) | `'md'` | Cell dimensions + glyph size. |

## Headless props (forwarded to soma)

`value`, `onValueChange`, `onComplete`, `length`, `type`, `pattern`,
`pasteTransformer`, `mask`, `placeholder`, `disabled`, `readonly`,
`required`, `invalid`, `name`, `autocomplete`, `inputmode`,
`aria-label`. See `src/uix/soma/components/pin-input/types.ts`.

## Cell data-* (emitted by morfo)

| Attr | When |
|---|---|
| `data-active` | The cell holds the caret (focused + about to be typed in). |
| `data-filled` | The cell has a character. |
| `data-disabled` | Cascaded from the provider's disabled state. |

## Passive justification

Passive **at the morfo level** — pin-input's morfo declares parts
(Provider, Cell, Input) but no `events` array. The user-perceived
interactions (typing, paste, completion) are mediated by the hidden
`<input>`'s native events; sema-side perceptual feedback piggy-backs
on the `commit` family base when the consumer hooks `onComplete`.

The component IS interactive from the user's perspective. "Passive"
here is a contract-layer classification, not a UX one — same logic
as `<AlertDialog>` (delegates events to the underlying primitive).

## Baseline

WAI-ARIA Textbox pattern:
<https://www.w3.org/WAI/ARIA/apg/patterns/textbox/>

The OTP-input UX has no formal ARIA pattern. Soma follows the
de-facto behaviour established by Radix-style implementations and
the iOS / Android native code-input controls:

- Single hidden `<input>` (not one input per cell) so paste, IME and
  autofill (`one-time-code`) work naturally.
- Paste distributes across cells via the morfo's
  `pasteTransformer` hook.
- Backspace clears the previous cell when the current one is empty.
- Numeric `type` sets `inputmode='numeric'` + `autocomplete='one-time-code'`
  so iOS / Android offer the SMS-autofill banner.

## Comparativa

| Lib | Single hidden input | Mask | Paste distribute | Type presets | Custom `pattern` | Snippet cells |
|---|---|---|---|---|---|---|
| **Radix Primitives** | n/a (not provided) | — | — | — | — | — |
| **Bits UI** | ✓ | ✓ | ✓ | numeric/alphanumeric/alphabetic | ✓ | ✓ |
| **Ark UI** | input per cell | ✓ | ✓ | numeric/alphanumeric | — | — |
| **Chakra v3** | input per cell | ✓ | ✓ | numeric/alphanumeric | — | — |
| **shadcn/ui (`input-otp`)** | ✓ | ✓ | ✓ | numeric (default) | ✓ | ✓ |
| **Eidos (this)** | ✓ | ✓ | ✓ | numeric / alphanumeric / alphabetic / custom | ✓ | ✓ |

Aligned with the shadcn / Bits family (single hidden input). Ark and
Chakra use one input per cell which works but loses paste / IME
quality.

## Decisiones

- **Snippet-driven Cell rendering.** Forces the consumer to iterate
  `cells` and render `<PinInput.Cell />` per index. Auto-rendering
  would hide the per-index `index` arg which downstream consumers
  use for analytics / focus targeting.
- **Cell consumes `data-active` for the focus ring**, not a literal
  `<input:focus>`. Only the hidden input is focused; the visible
  cells receive a synthetic focus ring via `data-active` to match
  the caret position.
- **No `variant` knob.** Pin inputs are a singular visual pattern
  (bordered boxes); variants like outline-only / soft / ghost noise
  the contract. Consumers can recolor cells via `data-color` if
  needed.
- **Size as t-shirt** (`sm` / `md` / `lg` / `xl`). Matches the rest
  of UIX's input scale.

## Gaps

| Gap | Disposición | Detalle |
| --- | --- | --- |
| Group separator (e.g. `123-456`) | **diferir** | Soma's `pasteTransformer` strips dashes; rendering a visible separator between groups (Bits' `<PinInput.Group>` part) isn't in the morfo. Add when a real consumer needs it. |
| Animated caret transition between cells | **diferir** | Soma emits `data-active` instantly; a transitioned bar could be a nice polish. |
| `data-color` cascade | **diferir** | Coloured cells (success on complete, danger on invalid) would propagate from the root's `data-color`. Add when the consumer pattern stabilises. |

## Reference

- Bits UI: <https://bits-ui.com/docs/components/pin-input>
- Ark UI: <https://ark-ui.com/docs/components/pin-input>
- Chakra v3: <https://chakra-ui.com/docs/components/pin-input>
- shadcn/ui (`input-otp`):
  <https://ui.shadcn.com/docs/components/input-otp>