@xsolla/xui-input-payment 0.174.3 → 0.176.0

package/README.md

@@ -1,6 +1,70 @@
 # Input Payment
 
 A cross-platform React payment card input that automatically detects the card type from the entered number and displays relevant payment icons.
+<!-- BEGIN:xui-mcp-instructions:input-payment -->
+A specialised text input for payment data entry. Extends the standard input with a dedicated payment icons block — a row of accepted payment method logos (Visa, Mastercard, etc.) displayed inside the field — and an optional leading icon. Used exclusively in checkout flows, billing forms, and payment method configuration screens.
+
+### When to use
+
+For collecting a card number, expiry date, CVV, or other payment-related values in a checkout or billing form
+
+When the field must visually communicate which payment methods are accepted — showing logos inside the input reassures the user before they start typing
+
+When the payment method icon should change dynamically based on detected card type (e.g. showing the Visa logo as soon as the user types a Visa prefix)
+
+As a pair: one InputPayment for the card number, one for the expiry, one for the CVV — in a standard payment card form layout
+
+### When not to use
+
+- For non-payment text inputs — use the standard Input component
+- When no payment branding is needed — use standard Input with an optional left icon
+- When accepting only one specific payment method with no ambiguity — the payment icons block may be omitted and a single logo shown via Icon left instead
+
+### Content guidelines
+
+Placeholder text — use format hints, not instructions: 1234 5678 9012 3456 for card number, MM / YY for expiry, CVV or CVC for security code. Do not use *"Enter your card number"* — the field label already communicates this.
+Error messages — be specific:
+- *"Invalid card number"* — after Luhn check fails
+- *"Expiry date has passed"* — past month/year entered
+- *"CVV must be 3 digits"* (or 4 for Amex) — wrong length
+- *"Card number is required"* — required field left empty
+- Field labels — always provide a visible label above the field: *"Card number"*, *"Expiry date"*, *"Security code"*. Do not rely on the placeholder alone.
+- Payment icons — show only the logos for payment methods actually accepted by the product's payment provider. Do not show logos for unsupported methods — it creates false expectations.
+
+### Behaviour guidelines
+
+Card number formatting — as the user types, format the card number with spaces every 4 digits: 4242 4242 4242 4242. Apply this formatting in real time without disrupting cursor position. Accept both numeric-only input and formatted strings with spaces.
+
+Card type detection — detect the card network from the first 1–6 digits (IIN/BIN range). When detected, highlight the matching logo in the payment icons block and dim or hide others. Update in real time as the user types.
+
+Expiry date formatting — auto-insert a / separator after the month digits: 12/26. Prevent the user from entering an invalid month (> 12) or a past expiry date.
+
+CVV masking — optionally mask CVV input as the user types (show dots •••). Provide a show/hide toggle via a trailing icon button if masking is enabled.
+
+Input masking — use inputmode=*"numeric"* and pattern=*"[0-9]*"* on numeric fields to trigger a numeric keyboard on mobile. Do not use type=*"number"* for card fields — it interferes with leading zeros and formatting.
+
+Validation timing — validate on blur (when the user leaves the field), not on every keystroke. Switch to State=Error with a specific error message when the value fails validation. Clear the error when the user starts typing again.
+
+Disabled state — use State=Disabled for saved payment methods being displayed in a non-editable summary. Always show the masked card value (e.g. •••• 4242) rather than an empty disabled field.
+
+Autofill — support browser and OS autofill for payment fields. Use standard autocomplete attributes: autocomplete=*"cc-number"* for card number, autocomplete=*"cc-exp"* for expiry, autocomplete=*"cc-csc"* for CVV. Autofill should trigger Filled=True and the detected card type should update the payment icons block.
+
+### Accessibility
+
+Each InputPayment field must have a visible label associated via <label for> or aria-labelledby. Do not use placeholder as the only label.
+
+Use autocomplete attributes on all payment fields — they are required for WCAG 1.3.5 (Identify Input Purpose).
+
+Use inputmode=*"numeric"* on card number, expiry, and CVV fields to trigger the numeric keyboard on touch devices.
+
+When State=Error, the error message must be associated via aria-describedby so screen readers announce it when the field is focused.
+
+The payment icons block is decorative — wrap it in aria-hidden=*"true"* so screen readers do not attempt to read logo names. The accepted payment methods should instead be listed in a visible or screen-reader-only text near the form (e.g. *"We accept Visa, Mastercard, and American Express"*).
+
+The Icon left is decorative when a label is present — set aria-hidden=*"true"* on the icon element.
+
+When State=Disabled, set aria-disabled=*"true"* and communicate the card type and masked number via aria-label — e.g. aria-label=*"Visa card ending in 4242, disabled"*.
+<!-- END:xui-mcp-instructions:input-payment -->
 
 ## Installation
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xsolla/xui-input-payment",
-  "version": "0.174.3",
+  "version": "0.176.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-core": "0.174.3",
-    "@xsolla/xui-icons-payment": "0.174.3",
-    "@xsolla/xui-primitives-core": "0.174.3"
+    "@xsolla/xui-core": "0.176.0",
+    "@xsolla/xui-icons-payment": "0.176.0",
+    "@xsolla/xui-primitives-core": "0.176.0"
   },
   "peerDependencies": {
     "react": ">=16.8.0",