@xsolla/xui-input-phone 0.174.3 → 0.176.0

package/README.md

@@ -1,6 +1,62 @@
 # InputPhone
 
 A cross-platform phone-number input with an integrated, searchable country selector (flags and dial codes); ships with a `usePhoneNumber` hook for formatting and country detection.
+<!-- BEGIN:xui-mcp-instructions:input-phone -->
+A specialised input for entering a phone number. Combines a Select (country/region picker) with a text field for the number itself. Used whenever the product requires a valid, internationally formatted phone number from the user.
+
+### When to use
+
+- Registration and account setup forms requiring a phone number
+- Two-factor authentication (2FA) enrollment flows
+- Payment and billing forms where a contact number is required
+- Any context where the phone number must include a country code
+
+### When not to use
+
+When a simple freeform text field is sufficient and international formatting is not required — use a plain Input instead
+
+When the phone number does not need country selection (e.g. a single-country product with a fixed dial code)
+
+Do not use for non-phone numeric fields (e.g. zip codes, card numbers) — use Input with appropriatetype
+
+### Content guidelines
+
+Placeholder mask should show the expected format for the selected country (e.g. (000) 000-0000 for US, 00 0000 0000 for AU). Update it dynamically when the country changes.
+
+Dial code (e.g. +1) should be displayed as a non-editable prefix, not typed by the user.
+
+Error messages should be specific: *"Enter a valid phone number"*, not just *"Invalid input"*. If the format is wrong, indicate the expected format.
+
+Country selector label — use the flag icon as the primary identifier; always include the country name in the dropdown list for accessibility.
+
+### Behaviour guidelines
+
+Auto-format the number as the user types, applying the mask for the selected country (e.g. spaces, dashes, parentheses). This reduces input errors and improves readability.
+
+Auto-detect country from the number if the user pastes a full international number with a + prefix — update the flag and dial code accordingly.
+
+Strip non-numeric characters on submit; store the number in E.164 format (e.g. +14155551234) regardless of display format.
+
+Preserve the country selection when the user clears the number field with the Remove button — only the number should be cleared, not the country.
+
+Validate on blur, not on every keystroke, to avoid showing errors before the user has finished typing.
+
+Country list should be searchable when it contains more than ~20 entries. Prioritise common countries at the top (e.g. based on locale or previous selection).
+
+### Accessibility
+
+The country selector must have an accessible name (e.g. aria-label=*"Select country"*) — flag icons alone are not sufficient for screen readers.
+
+The dial code prefix must be announced as part of the field context, either via aria-label on the input or by including it in a visible label.
+
+The phone input should use type=*"tel"* to trigger the numeric keyboard on mobile.
+
+The input should have autocomplete=*"tel"* to support autofill.
+
+Error messages must be linked via aria-describedby so screen readers announce them on focus.
+
+Ensure the country selector and number field are reachable and operable via keyboard alone.
+<!-- END:xui-mcp-instructions:input-phone -->
 
 ## Installation
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xsolla/xui-input-phone",
-  "version": "0.174.3",
+  "version": "0.176.0",
   "main": "./web/index.js",
   "module": "./web/index.mjs",
   "types": "./web/index.d.ts",
@@ -13,8 +13,8 @@
     "test:coverage": "vitest run --coverage"
   },
   "dependencies": {
-    "@xsolla/xui-core": "0.174.3",
-    "@xsolla/xui-primitives-core": "0.174.3",
+    "@xsolla/xui-core": "0.176.0",
+    "@xsolla/xui-primitives-core": "0.176.0",
     "libphonenumber-js": "^1.10.56"
   },
   "peerDependencies": {