@xsolla/xui-input-pin 0.174.2 → 0.175.0

package/README.md

@@ -1,6 +1,72 @@
 # Input Pin
 
 A cross-platform React PIN/OTP input component with individual cells for each digit. Features auto-advance between cells, paste support, and completion callbacks.
+<!-- BEGIN:xui-mcp-instructions:input-pin -->
+A specialised input for entering a short numeric or alphanumeric code — typically a PIN, OTP (one-time password), or verification code. Renders as a horizontal row of individual character cells (.pin-item), one per expected digit. Each cell has independent state, and the component supports masking, placeholder dots, and a visibility toggle.
+
+### When to use
+- For entering a PIN, OTP, SMS verification code, or 2FA code
+- When a fixed-length code must be collected and each character should be visually distinct and finger-friendly
+- In authentication flows, payment confirmation screens, and account verification modals
+- When real-time digit-by-digit visual feedback improves the entry experience
+
+### When not to use
+
+- For variable-length passwords — use InputPassword
+- For long codes (more than 8 characters) that do not benefit from individual cell rendering — use a standard Input with masking
+- For alphanumeric codes where the user must type non-numeric characters (letters) that are already clearly visible — use a styled Input instead of a PIN field
+- When the code length is unknown ahead of time — InputPin requires a fixed number of cells
+
+### Behaviour guidelines
+
+Auto-advance — after the user types a digit into the active cell, focus automatically moves to the next empty cell. The user should never need to manually click individual cells.
+
+Auto-submit — when the last cell receives a value and all cells are filled (State=Filled), submit the form automatically without requiring the user to press Enter or a Submit button. This is the expected UX for OTP and PIN flows.
+
+Backspace — pressing Backspace clears the value in the current active cell and moves focus back to the previous cell. If the active cell is already empty, Backspace moves focus back and clears the previous cell.
+
+Paste — when the user pastes a string of the correct length, distribute the characters across all cells immediately and submit if auto-submit is enabled. Trim whitespace and hyphens from pasted values (e.g. 1234 5678 → 12345678).
+
+Numeric-only enforcement — for numeric PINs/OTPs, reject non-numeric characters silently (do not show an error for a single wrong keypress — just ignore it). Use inputmode=*"numeric"* to trigger a numeric keyboard on mobile.
+
+Error state — switch to State=Error when the code fails server-side validation (wrong OTP, expired code, incorrect PIN). All cells switch to error appearance simultaneously. Show a specific error message below the component. Clear the error state when the user starts typing again and reset all cells.
+
+OTP code expiry — for time-based OTPs, show a countdown timer or *"Resend code"* link near the component. If the code expires mid-entry, show State=Error with the message *"Code has expired. Request a new one."*
+
+Resend flow — after an error due to expiry or incorrect code, provide a *"Resend code"* action that clears all cells, resets to State=Default, and moves focus to the first cell.
+
+Disabled state — use State=Disable when the PIN entry is temporarily locked (e.g. too many failed attempts). Show a reason nearby (e.g. *"Too many attempts. Try again in 30 seconds."*).
+
+Mobile keyboard — use inputmode=*"numeric"* and pattern=*"[0-9]*"* on the underlying input. Consider rendering a single hidden text input that captures keystrokes and distributes characters to the visual cells, rather than using multiple separate <input> elements.
+
+### Content guidelines
+
+Label — always provide a visible label above the component: *"Enter PIN"*, *"Verification code"*, *"Enter the 6-digit code sent to +7 (900) •••• 1234"*. Include the code length and delivery channel in the label for OTP flows.
+Error messages — be specific and actionable:
+- *"Incorrect PIN. 2 attempts remaining."*
+- *"Code expired. Request a new code below."*
+- *"Incorrect code. Please try again."*
+- Resend link label — use *"Resend code"* or *"Send a new code"*. Include a cooldown timer: *"Resend code in 0:45"*.
+- Placeholder dot vs empty — prefer Placeholder-dots=True for PIN entry screens where the digit count helps the user count positions. Use Placeholder-dots=False for cleaner designs where the code length is communicated in the label.
+
+### Accessibility
+
+The underlying input mechanism must be accessible via keyboard. The preferred implementation is a single visually-hidden <input> element that captures keyboard input and distributes it to the visual cells — this avoids focus-management complexity across multiple inputs.
+
+If multiple <input> elements are used (one per cell), each must have aria-label identifying the position: e.g. aria-label=*"Digit 1 of 6"*.
+
+The component container must have aria-label describing the whole field: e.g. aria-label=*"6-digit verification code"*.
+
+When State=Error, the error message must be in an aria-live=*"polite"* region and associated via aria-describedby so screen readers announce it.
+
+The visual dot masking is cosmetic — the underlying <input> must still use type=*"password"* (or inputmode=*"numeric"* on a text input with custom masking) to ensure the value is treated as sensitive.
+
+Auto-advance (moving focus to the next cell) must also move focus for keyboard users, not just update visual state.
+
+When the last cell is filled and the form is auto-submitted, announce the submission to screen readers via aria-live=*"assertive"* or by focussing a confirmation message.
+
+Ensure a minimum touch target of 44 × 44 px on mobile. For XS [32] and S [40] sizes, add layout padding to meet this requirement.
+<!-- END:xui-mcp-instructions:input-pin -->
 
 ## Installation
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xsolla/xui-input-pin",
-  "version": "0.174.2",
+  "version": "0.175.0",
   "main": "./web/index.js",
   "module": "./web/index.mjs",
   "types": "./web/index.d.ts",
@@ -13,9 +13,9 @@
     "test:coverage": "vitest run --coverage"
   },
   "dependencies": {
-    "@xsolla/xui-button": "0.174.2",
-    "@xsolla/xui-core": "0.174.2",
-    "@xsolla/xui-primitives-core": "0.174.2"
+    "@xsolla/xui-button": "0.175.0",
+    "@xsolla/xui-core": "0.175.0",
+    "@xsolla/xui-primitives-core": "0.175.0"
   },
   "peerDependencies": {
     "react": ">=16.8.0",