@reliability-design/web 1.0.3 → 1.0.6

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

@@ -0,0 +1,440 @@
+# 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-colors-blue-primary);
+}
+
+rel-otp::part(cell):focus {
+  box-shadow: 0 0 0 3px rgba(74, 144, 226, 0.2);
+}
+
+rel-otp::part(separator) {
+  color: var(--rel-colors-blue-secondary);
+}
+
+/* Custom invalid styling */
+rel-otp[invalid]::part(cell) {
+  border-color: var(--rel-colors-red-secondary);
+  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;
+});
+```

package/dist/components/rel-otp/index.ts

@@ -0,0 +1 @@
+export * from "./rel-otp";