@reliability-design/web 1.4.5 → 1.4.7

package/dist/components/rel-otp/README.md

@@ -1,440 +1,170 @@
-# RelOtp Component
-
-An accessible one-time password (OTP) input component for the Reliability Design System.
-
-## Features
-
-- Auto-advance on input
-- Smart backspace behavior (clear current, then move back)
-- Arrow key navigation (Left/Right, Home/End)
-- Paste support (distributes characters across cells)
-- Mobile OTP autofill support (iOS/Android)
-- Numeric or alphanumeric validation
-- Optional masking (password-style)
-- Visual grouping with separators
-- Form integration via hidden input
-- Token-driven styling
-
-## Basic Usage
-
-```html
-<!-- Simple 6-digit numeric OTP -->
-<rel-otp length="6" group-size="3"></rel-otp>
-
-<!-- Alphanumeric with masking -->
-<rel-otp
-  length="8"
-  type="alphanumeric"
-  mask="true"
-  group-size="4">
-</rel-otp>
-
-<!-- With form integration -->
-<form>
-  <rel-otp
-    name="otp_code"
-    length="6"
-    required
-    aria-label="Enter verification code">
-  </rel-otp>
-  <button type="submit">Verify</button>
-</form>
-```
-
-## Properties
-
-| Property | Type | Default | Description |
-|----------|------|---------|-------------|
-| `value` | `string` | `""` | The concatenated OTP value (reflects) |
-| `length` | `number` | `6` | Total number of characters/digits |
-| `group-size` | `number` | `3` | Visual grouping size (0 = no grouping) |
-| `placeholder` | `string` | `""` | Placeholder for each cell |
-| `type` | `"numeric" \| "alphanumeric"` | `"numeric"` | Input validation type |
-| `mask` | `boolean` | `false` | Password-style masking |
-| `disabled` | `boolean` | `false` | Disables all inputs |
-| `readonly` | `boolean` | `false` | Makes inputs read-only |
-| `required` | `boolean` | `false` | HTML5 required attribute |
-| `name` | `string \| null` | `null` | Creates hidden input for forms |
-| `autocomplete` | `string` | `"one-time-code"` | Autocomplete attribute (mobile OTP) |
-| `inputmode` | `"numeric" \| "text" \| null` | `null` | Input mode (auto-detected from type) |
-| `pattern` | `string \| null` | `null` | HTML5 pattern attribute |
-| `aria-label` | `string \| null` | `null` | Label for the entire control |
-| `invalid` | `boolean` | `false` | Shows error styling |
-| `show-separator` | `boolean` | `true` | Show separator between groups |
-| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Size variant |
-
-## Events
-
-| Event | Detail | Description |
-|-------|--------|-------------|
-| `rel-change` | `{ value: string, complete: boolean }` | Fires on any value change |
-| `rel-complete` | `{ value: string }` | Fires when valid code is complete |
-
-## Keyboard Behavior
-
-| Key | Action |
-|-----|--------|
-| `0-9` / `A-Z` | Enter character (based on type), auto-advance |
-| `Backspace` | Clear current cell, or move back and clear |
-| `Delete` | Clear current cell, stay in place |
-| `ArrowLeft` | Move to previous cell |
-| `ArrowRight` | Move to next cell |
-| `Home` | Jump to first cell |
-| `End` | Jump to last cell |
-
-## Paste Behavior
-
-When you paste a value:
-- Only valid characters are accepted (based on `type`)
-- Characters distribute across cells starting from current position
-- Overflow beyond `length` is truncated
-- Focus moves to next empty cell (or last cell if full)
-- Triggers `rel-change` and `rel-complete` events
-
-Example: Pasting "123456" into a 6-digit OTP fills all cells.
-
-## Examples
-
-### Basic Numeric OTP (6 digits)
-
-```html
-<rel-otp
-  id="otp-basic"
-  length="6"
-  group-size="3">
-</rel-otp>
-
-<script>
-  const otp = document.getElementById('otp-basic');
-
-  otp.addEventListener('rel-change', (e) => {
-    console.log('Value:', e.detail.value);
-    console.log('Complete:', e.detail.complete);
-  });
-
-  otp.addEventListener('rel-complete', (e) => {
-    console.log('OTP Complete:', e.detail.value);
-    // Submit to server, etc.
-  });
-</script>
-```
-
-### Alphanumeric with Custom Grouping
-
-```html
-<rel-otp
-  length="8"
-  type="alphanumeric"
-  group-size="4"
-  aria-label="Enter 8-character code">
-</rel-otp>
-```
-
-### Masked OTP (Password Style)
-
-```html
-<rel-otp
-  length="6"
-  mask="true"
-  group-size="3"
-  aria-label="Enter PIN">
-</rel-otp>
-```
-
-### Form Integration
-
-```html
-<form id="verify-form">
-  <label>Enter verification code:</label>
-  <rel-otp
-    name="verification_code"
-    length="6"
-    required
-    invalid="false"
-    id="otp-form">
-  </rel-otp>
-  <button type="submit">Verify</button>
-</form>
-
-<script>
-  const form = document.getElementById('verify-form');
-  const otpInput = document.getElementById('otp-form');
-
-  form.addEventListener('submit', (e) => {
-    e.preventDefault();
-    const formData = new FormData(form);
-    console.log('OTP:', formData.get('verification_code'));
-  });
-
-  // Show error on invalid attempt
-  function showError() {
-    otpInput.invalid = true;
-  }
-</script>
-```
-
-### Programmatic Control
-
-```javascript
-const otp = document.querySelector('rel-otp');
-
-// Set value programmatically
-otp.value = "123456";
-
-// Clear value
-otp.value = "";
-
-// Mark as invalid
-otp.invalid = true;
-
-// Disable
-otp.disabled = true;
-```
-
-### Without Separators
-
-```html
-<rel-otp
-  length="6"
-  show-separator="false">
-</rel-otp>
-```
-
-### Different Sizes
-
-```html
-<!-- Small -->
-<rel-otp size="sm" length="4"></rel-otp>
-
-<!-- Medium (default) -->
-<rel-otp size="md" length="6"></rel-otp>
-
-<!-- Large -->
-<rel-otp size="lg" length="6"></rel-otp>
-```
-
-## Mobile OTP Autofill
-
-The component supports native mobile OTP autofill on iOS and Android:
-
-- Sets `autocomplete="one-time-code"` on the first input
-- When the browser/OS injects the full code into the first cell, the component automatically distributes it across all cells
-- Works with SMS-based verification codes
-
-```html
-<rel-otp
-  length="6"
-  autocomplete="one-time-code">
-</rel-otp>
-```
-
-## Accessibility
-
-- **Role**: The container has `role="group"` with a descriptive `aria-label`
-- **Cell Labels**: Each input has `aria-label` like "Digit 1 of 6"
-- **Input Mode**: Sets appropriate `inputmode` for mobile keyboards
-  - `numeric` type → `inputmode="numeric"`
-  - `alphanumeric` type → `inputmode="text"`
-- **Focus Management**: Auto-advances focus, keyboard navigation supported
-- **States**: `disabled`, `readonly`, `required`, and `invalid` states properly reflected
-
-```html
-<rel-otp
-  aria-label="Enter your 6-digit verification code"
-  length="6">
-</rel-otp>
-```
-
-## Styling
-
-The OTP component uses design system tokens for all styling. Customize via CSS parts:
-
-```css
-rel-otp::part(cell) {
-  border-color: var(--rel-bg-info);
-}
-
-rel-otp::part(cell):focus {
-  box-shadow: 0 0 0 3px rgba(74, 144, 226, 0.2);
-}
-
-rel-otp::part(separator) {
-  color: var(--rel-bg-info-light);
-}
-
-/* Custom invalid styling */
-rel-otp[invalid]::part(cell) {
-  border-color: var(--rel-text-danger);
-  animation: shake 0.3s;
-}
-
-@keyframes shake {
-  0%, 100% { transform: translateX(0); }
-  25% { transform: translateX(-4px); }
-  75% { transform: translateX(4px); }
-}
-```
-
-## CSS Parts
-
-| Part | Description |
-|------|-------------|
-| `root` | Root container element |
-| `cell` | Individual input cell |
-| `separator` | Separator between groups |
-| `hidden-input` | Hidden input for form submission |
-
-## Framework Integration
-
-### React
-
-```jsx
-import { RelOtp } from '@reliability-design/web';
-
-function OtpForm() {
-  const [otp, setOtp] = useState('');
-  const [isInvalid, setIsInvalid] = useState(false);
-
-  const handleChange = (e) => {
-    setOtp(e.detail.value);
-    setIsInvalid(false);
-  };
-
-  const handleComplete = async (e) => {
-    const code = e.detail.value;
-    const valid = await verifyOtp(code);
-    setIsInvalid(!valid);
-  };
-
-  return (
-    <RelOtp
-      length={6}
-      onRelChange={handleChange}
-      onRelComplete={handleComplete}
-      invalid={isInvalid}
-    />
-  );
-}
-```
-
-### Angular
-
-```html
-<rel-otp
-  [length]="6"
-  [group-size]="3"
-  (rel-complete)="onOtpComplete($event)"
-  [invalid]="isInvalid">
-</rel-otp>
-```
-
-```typescript
-export class OtpComponent {
-  isInvalid = false;
-
-  async onOtpComplete(event: CustomEvent) {
-    const code = event.detail.value;
-    const valid = await this.verifyOtp(code);
-    this.isInvalid = !valid;
-  }
-}
-```
-
-### Vue
-
-```vue
-<template>
-  <rel-otp
-    :length="6"
-    :group-size="3"
-    :invalid="isInvalid"
-    @rel-complete="handleComplete"
-  />
-</template>
-
-<script setup>
-import { ref } from 'vue';
-
-const isInvalid = ref(false);
-
-async function handleComplete(event) {
-  const code = event.detail.value;
-  const valid = await verifyOtp(code);
-  isInvalid.value = !valid;
-}
-</script>
-```
-
-## Validation
-
-The component provides basic character validation (numeric or alphanumeric) but does not validate the actual OTP code. Implement your own verification logic:
-
-```javascript
-const otp = document.querySelector('rel-otp');
-
-otp.addEventListener('rel-complete', async (e) => {
-  const code = e.detail.value;
-
-  try {
-    const response = await fetch('/api/verify-otp', {
-      method: 'POST',
-      body: JSON.stringify({ code }),
-      headers: { 'Content-Type': 'application/json' }
-    });
-
-    if (response.ok) {
-      // Success
-      console.log('OTP verified!');
-    } else {
-      // Invalid
-      otp.invalid = true;
-      otp.value = ''; // Clear for retry
-    }
-  } catch (error) {
-    console.error('Verification failed:', error);
-  }
-});
-```
-
-## Common Patterns
-
-### Resend Timer
-
-```html
-<rel-otp id="otp" length="6"></rel-otp>
-<button id="resend" disabled>Resend code in <span id="timer">60</span>s</button>
-
-<script>
-  let timeLeft = 60;
-  const timer = document.getElementById('timer');
-  const resendBtn = document.getElementById('resend');
-
-  const countdown = setInterval(() => {
-    timeLeft--;
-    timer.textContent = timeLeft;
-
-    if (timeLeft <= 0) {
-      clearInterval(countdown);
-      resendBtn.disabled = false;
-      resendBtn.textContent = 'Resend code';
-    }
-  }, 1000);
-</script>
-```
-
-### Auto-Submit on Complete
-
-```javascript
-const otp = document.querySelector('rel-otp');
-
-otp.addEventListener('rel-complete', async (e) => {
-  // Show loading state
-  otp.disabled = true;
-
-  // Auto-submit
-  await submitOtp(e.detail.value);
-
-  // Re-enable if failed
-  otp.disabled = false;
-});
-```
+# rel-otp
+
+A one-time-password input implementing the Figma "OTP Input" cell: one single-character `<input>` per position, with auto-advance, smart backspace, paste distribution, mobile OTP autofill and optional group separators. The cells accept digits only (`input-mode="numeric"`, the default) or digits plus ASCII letters (`input-mode="alphanumeric"`), and can be masked password-style. Use it for SMS / authenticator verification codes and PINs; for free-form text use `rel-textfield`.
+
+## Usage
+
+```html
+<!-- 6-digit numeric code in two groups of three -->
+<rel-otp length="6" group-size="3"></rel-otp>
+
+<!-- Alphanumeric, masked, four per group, custom accessible name -->
+<rel-otp
+  length="8"
+  input-mode="alphanumeric"
+  mask
+  group-size="4"
+  aria-label="Enter 8-character code">
+</rel-otp>
+
+<!-- Sizes: small 32px / medium 40px (default) / large 48px cells -->
+<rel-otp size="small" length="4"></rel-otp>
+<rel-otp size="medium" length="6"></rel-otp>
+<rel-otp size="large" length="6"></rel-otp>
+
+<!-- Form integration: `name` renders a hidden input carrying the value -->
+<form id="verify-form">
+  <rel-otp id="otp-form" name="verification_code" length="6" required></rel-otp>
+  <button type="submit">Verify</button>
+</form>
+<script>
+  const form = document.getElementById('verify-form');
+  const otp = document.getElementById('otp-form');
+
+  form.addEventListener('submit', (e) => {
+    e.preventDefault();
+    console.log('OTP:', new FormData(form).get('verification_code'));
+  });
+
+  otp.addEventListener('rel-change', (e) => {
+    console.log('Value:', e.detail.value, 'Complete:', e.detail.complete);
+    otp.invalid = false;
+  });
+
+  otp.addEventListener('rel-complete', async (e) => {
+    otp.disabled = true;
+    const ok = await verifyOtp(e.detail.value);
+    otp.disabled = false;
+    if (!ok) {
+      otp.invalid = true; // danger border + aria-invalid
+      otp.value = '';     // clear for retry
+    }
+  });
+</script>
+
+<!-- No separators: show-separator is a boolean attribute (presence = true),
+     so hide the dashes by setting the property -->
+<rel-otp id="otp-plain" length="6"></rel-otp>
+<script>
+  document.getElementById('otp-plain').showSeparator = false;
+</script>
+
+<!-- States -->
+<rel-otp value="123456" readonly></rel-otp>
+<rel-otp value="12" disabled></rel-otp>
+<rel-otp invalid length="6"></rel-otp>
+```
+
+### Deprecated aliases
+
+```html
+<!-- type= is a deprecated alias of input-mode; input-mode wins when both are set.
+     Logs once per page:
+     [rel-otp] "type" is deprecated and will be removed in 3.0 — use "input-mode" instead. It describes the accepted characters, not a semantic input type. -->
+<rel-otp type="alphanumeric" length="8"></rel-otp>
+
+<!-- sm / md / lg are deprecated aliases of size="small" / "medium" / "large" (no console notice) -->
+<rel-otp size="lg" length="6"></rel-otp>
+```
+
+<!-- readme-gen:start -->
+
+<!-- Generated from rel-otp.ts — do not edit; run readme-generate.mjs -->
+
+## API
+
+### Attributes / Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `value` | `value` | `string` | `""` | The concatenated code (all cells joined). Set it to fill the cells programmatically; it never exceeds `length` characters. Reflected. |
+| `length` | `length` | `number` | `6` | Total number of cells (characters in the code). |
+| `groupSize` | `group-size` | `number` | `3` | Cells per visual group; a separator renders between groups. `0` (or `show-separator` off) renders one ungrouped row. |
+| `placeholder` | `placeholder` | `string` | `""` | Placeholder character shown in every empty cell. |
+| `inputMode` | `input-mode` | `"numeric" \| "alphanumeric" \| ""` | `""` | Accepted character set (Trello 5). Describes what the field ACCEPTS, not a semantic input type — hence the name. Explicitly set it wins over the deprecated `type`; unset (`""`, like the native `inputMode` accessor it shadows on the host), `type` (default `"numeric"`) applies. Note the lowercase `inputmode` prop is a different thing: the raw native keyboard hint forwarded to each cell. |
+| `mask` | `mask` | `boolean` | `false` | Renders the cells as `type="password"` so entered characters are masked. |
+| `disabled` | `disabled` | `boolean` | `false` | Disables every cell and dims the control to 0.6 opacity. Reflected. |
+| `readonly` | `readonly` | `boolean` | `false` | Makes every cell read-only: the value is shown but typing, paste and keyboard editing are ignored. Reflected. |
+| `required` | `required` | `boolean` | `false` | Marks the first cell `required` for native form validation. |
+| `name` | `name` | `string \| null` | `null` | When set, renders a hidden `<input name="…">` (part `hidden-input`) carrying `value` for native form submission. |
+| `autocomplete` | `autocomplete` | `string` | `"one-time-code"` | Reserved autocomplete hint. Currently every cell always renders `autocomplete="one-time-code"` regardless of this value. |
+| `inputmode` | `inputmode` | `"numeric" \| "text" \| null` | `null` | Raw native `inputmode` keyboard hint forwarded to every cell. Unset, it follows the accepted character set: `numeric` for numeric, `text` for alphanumeric. |
+| `pattern` | `pattern` | `string \| null` | `null` | Native `pattern` attribute forwarded to every cell (per-character regex for form validation). |
+| `ariaLabel` | `aria-label` | `string \| null` | `null` | Accessible name of the whole group; defaults to "One-time password input". Each cell is additionally labelled "Digit/Character N of M". |
+| `invalid` | `invalid` | `boolean` | `false` | Error styling (danger border on every cell) and `aria-invalid="true"`. Reflected. |
+| `showSeparator` | `show-separator` | `boolean` | `true` | Renders the dash separator between groups. Boolean attribute: its presence means true — set the property to `false` to hide separators. |
+| `size` | `size` | `"small" \| "medium" \| "large" \| "sm" \| "md" \| "lg"` | `"medium"` | Cell size on the shared field scale (square, border-box): `small` 32px, `medium` 40px, `large` 48px (the Figma OTP Input cell). `sm` / `md` / `lg` are deprecated aliases of the full words. Reflected. |
+
+#### Deprecated (still supported — removal targeted for 3.0)
+
+| Property | Attribute | Type | Use instead |
+| --- | --- | --- | --- |
+| `type` | `type` | `"numeric" \| "alphanumeric"` | Deprecated alias of `inputMode` (attribute `input-mode`); use `input-mode` instead. Kept working in 1.x and logs a one-time console notice. |
+
+## Events
+
+| Event | Detail | Bubbles / composed | Description |
+| --- | --- | --- | --- |
+| `rel-change` | `{ value: newValue, complete }` | bubbles / composed | Fired on every value change (typing, backspace, delete, paste). Detail: `{ value: string, complete: boolean }` — `complete` is true when all cells hold a valid character. |
+| `rel-complete` | `{ value: newValue }` | bubbles / composed | Fired after `rel-change` once every cell holds a valid character. Detail: `{ value: string }` (the full code). |
+
+## Slots
+
+| Slot | Description |
+| --- | --- |
+| — | This element has no slots. |
+
+## CSS Parts
+
+| Part | Description |
+| --- | --- |
+| `base` | The `role="group"` root container (same element as `root`) |
+| `root` | Alias of `base`, kept for existing `::part(root)` selectors |
+| `input` | Each single-character cell input (same element as `cell`) |
+| `cell` | Alias of `input`, kept for existing `::part(cell)` selectors |
+| `separator` | The dash rendered between cell groups |
+| `hidden-input` | The hidden form input rendered when `name` is set |
+
+<!-- readme-gen:end -->
+
+## Accessibility
+
+- The root renders `role="group"` with `aria-label` from the `aria-label` attribute (default "One-time password input").
+- Every cell is a native `<input maxlength="1">` labelled "Digit N of M" (numeric) or "Character N of M" (alphanumeric), so screen readers announce the position while focus auto-advances.
+- `invalid` sets `aria-invalid="true"` on every cell; `disabled`, `readonly` and `required` (first cell only) are the native attributes.
+- The native `inputmode` hint on each cell follows the accepted character set — `numeric` for `input-mode="numeric"`, `text` for `alphanumeric` — unless the raw `inputmode` prop overrides it. Every cell carries `autocomplete="one-time-code"` so iOS / Android can inject an SMS code; a multi-character injection into any cell is distributed like a paste.
+- Focus management: focusing a cell selects its content (replace-on-type); a pointer-down on a cell beyond the first empty one is redirected to that empty cell so the code cannot be entered out of order; after paste focus lands on the next empty cell (or the last cell when full).
+- Live-region announcements (via the shared `announce()` utility): "Code complete" when every cell holds a valid character, and "N digits/characters entered" after a paste that does not fill the code.
+
+| Key | Action |
+| --- | --- |
+| `0-9` (numeric) / `0-9` `A-Z` `a-z` (alphanumeric) | Enter the character and advance to the next cell; other characters are rejected |
+| `Backspace` | Clear the current cell; if it is already empty, move to the previous cell and clear it |
+| `Delete` | Clear the current cell and stay |
+| `ArrowLeft` / `ArrowRight` | Move to the previous / next cell |
+| `Home` / `End` | Jump to the first / last cell |
+| `ArrowUp` / `ArrowDown` | Ignored (prevented so the page does not scroll) |
+| `Ctrl/Cmd+V` | Paste: valid characters are distributed from the current cell onward, overflow past `length` is dropped |
+| `Tab` / `Shift+Tab` | Move focus between cells (each cell is a tab stop) |
+
+## Notes / Edge Cases
+
+- `value` is truncated to `length` characters when synced into the cells; changing `length` re-initialises the cells from `value`.
+- `rel-change` fires on every edit; `rel-complete` fires right after it when all cells hold a valid character for the current mode — validate the code server-side, the component only checks the character set.
+- `input-mode` unset (`""`) falls back to the deprecated `type` prop (default `"numeric"`); set `input-mode` explicitly and it always wins.
+- The lowercase `inputmode` prop is the raw native keyboard hint, not the accepted character set — normally leave it unset.
+- `show-separator` is a boolean attribute: `show-separator="false"` still enables separators. Hide them with `el.showSeparator = false` or `group-size="0"`.
+- `required` is applied to the first cell only, so native form validation blocks submission when the code is empty but not when it is partial — check `e.detail.complete` yourself.
+- The `autocomplete` prop currently has no effect: every cell always renders `autocomplete="one-time-code"`.
+- `disabled` and `readonly` also suppress paste and keyboard handling; the value stays visible.
+- Style cells via `::part(cell)` (alias `::part(input)`) and the root via `::part(base)` (alias `::part(root)`); the two names in each pair target the same element.