@xsolla/xui-input-phone 0.99.0 → 0.100.0

package/README.md

@@ -1,41 +1,218 @@
-# @xsolla/xui-input-phone
+---
+title: Input Phone
+subtitle: A phone number input with country selector.
+description: A cross-platform React phone input with country dropdown, dial codes, and searchable country list.
+---
 
-Phone number input with country selector dropdown and searchable country list.
+# Input Phone
+
+A cross-platform React phone number input component with integrated country selector. Features a searchable country dropdown with flags and dial codes.
 
 ## Installation
 
 ```bash
+npm install @xsolla/xui-input-phone
+# or
 yarn add @xsolla/xui-input-phone
 ```
 
-## Usage
+## Demo
+
+### Basic Phone Input
+
+```tsx
+import * as React from 'react';
+import { InputPhone } from '@xsolla/xui-input-phone';
+
+export default function BasicPhoneInput() {
+  const [phone, setPhone] = React.useState('');
+
+  return (
+    <InputPhone
+      value={phone}
+      onChange={(e) => setPhone(e.target.value)}
+      placeholder="+1 (000) 000-0000"
+    />
+  );
+}
+```
+
+### With Country Selection
 
 ```tsx
-import { InputPhone, defaultCountries } from '@xsolla/xui-input-phone';
+import * as React from 'react';
+import { InputPhone, Country } from '@xsolla/xui-input-phone';
+
+export default function CountryPhoneInput() {
+  const [phone, setPhone] = React.useState('');
+  const [country, setCountry] = React.useState<Country | undefined>();
+
+  return (
+    <InputPhone
+      value={phone}
+      onChange={(e) => setPhone(e.target.value)}
+      selectedCountry={country}
+      onCountryChange={setCountry}
+    />
+  );
+}
+```
+
+### With Validation
+
+```tsx
+import * as React from 'react';
+import { InputPhone } from '@xsolla/xui-input-phone';
+
+export default function ValidatedPhoneInput() {
+  const [phone, setPhone] = React.useState('');
+  const isValid = phone.length >= 10;
+
+  return (
+    <InputPhone
+      value={phone}
+      onChange={(e) => setPhone(e.target.value)}
+      checked={isValid}
+      extraClear={true}
+      onRemove={() => setPhone('')}
+    />
+  );
+}
+```
+
+## Anatomy
+
+```jsx
+import { InputPhone } from '@xsolla/xui-input-phone';
 
 <InputPhone
-  value={phone}
-  onChange={(e) => setPhone(e.target.value)}
-  selectedCountry={country}
-  onCountryChange={setCountry}
-  countries={defaultCountries}
+  value={phoneNumber}            // Phone number value
+  onChange={handleChange}        // Change event handler
+  selectedCountry={country}      // Currently selected country
+  onCountryChange={setCountry}   // Country selection handler
+  countries={customCountries}    // Custom countries array
+  placeholder="+1 (000) 000-0000" // Placeholder text
+  size="md"                       // Size variant
+  disabled={false}               // Disabled state
+  error={false}                  // Error state
+  errorMessage="Error"           // Error message
+  extraClear={false}             // Show clear button
+  onRemove={handleClear}         // Clear button handler
+  checked={false}                // Show validation checkmark
 />
 ```
 
-## Props
+## Examples
+
+### Error State
+
+```tsx
+import * as React from 'react';
+import { InputPhone } from '@xsolla/xui-input-phone';
+
+export default function ErrorPhoneInput() {
+  return (
+    <InputPhone
+      value="123"
+      error={true}
+      errorMessage="Please enter a valid phone number"
+    />
+  );
+}
+```
+
+### Phone Input Sizes
+
+```tsx
+import * as React from 'react';
+import { InputPhone } from '@xsolla/xui-input-phone';
+
+export default function PhoneInputSizes() {
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 16 }}>
+      <InputPhone size="xs" placeholder="Extra Small" />
+      <InputPhone size="sm" placeholder="Small" />
+      <InputPhone size="md" placeholder="Medium" />
+      <InputPhone size="lg" placeholder="Large" />
+      <InputPhone size="xl" placeholder="Extra Large" />
+    </div>
+  );
+}
+```
+
+### Custom Countries
+
+```tsx
+import * as React from 'react';
+import { InputPhone, Country } from '@xsolla/xui-input-phone';
+
+export default function CustomCountriesPhone() {
+  const [phone, setPhone] = React.useState('');
+
+  const countries: Country[] = [
+    { code: 'US', name: 'United States', dialCode: '+1' },
+    { code: 'GB', name: 'United Kingdom', dialCode: '+44' },
+    { code: 'DE', name: 'Germany', dialCode: '+49' },
+  ];
+
+  return (
+    <InputPhone
+      value={phone}
+      onChange={(e) => setPhone(e.target.value)}
+      countries={countries}
+    />
+  );
+}
+```
+
+## API Reference
 
 ### InputPhone
 
+**InputPhone Props:**
+
 | Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `value` | `string` | — | Controlled phone number value |
-| `placeholder` | `string` | `'+1 (000) 000-0000'` | Placeholder text |
-| `onChange` | `(e: ChangeEvent) => void` | — | Change handler |
-| `onChangeText` | `(text: string) => void` | — | Alternative change handler receiving the string value |
-| `size` | `'xl' \| 'lg' \| 'md' \| 'sm' \| 'xs'` | `'md'` | Input size |
-| `disabled` | `boolean` | `false` | Disables the input and country selector |
-| `errorMessage` | `string` | — | Error text displayed below; also sets invalid state |
-| `error` | `boolean` | — | Sets invalid state without a message |
-| `countries` | `Country[]` | All 200+ countries | Countries shown in the dropdown |
-| `selectedCountry` | `Country` | — | Currently selected country |
-| `onCountryChange` | `(country: Country) => void` | — | Called when a country is selected |
+| :--- | :--- | :------ | :---------- |
+| value | `string` | - | Phone number value. |
+| onChange | `(e: ChangeEvent) => void` | - | Change event handler. |
+| onChangeText | `(text: string) => void` | - | Text change handler. |
+| countries | `Country[]` | All countries | Available countries for selection. |
+| selectedCountry | `Country` | - | Currently selected country. |
+| onCountryChange | `(country: Country) => void` | - | Country selection handler. |
+| placeholder | `string` | `"+1 (000) 000-0000"` | Placeholder text. |
+| size | `"xl" \| "lg" \| "md" \| "sm" \| "xs"` | `"md"` | Component size. |
+| disabled | `boolean` | `false` | Disabled state. |
+| error | `boolean` | `false` | Error state. |
+| errorMessage | `string` | - | Error message text. |
+| extraClear | `boolean` | `false` | Show clear button. |
+| onRemove | `() => void` | - | Clear button handler. |
+| checked | `boolean` | `false` | Show validation checkmark. |
+| checkedIcon | `ReactNode` | Check icon | Custom checkmark icon. |
+| testID | `string` | - | Test identifier. |
+
+**Country Interface:**
+
+```typescript
+interface Country {
+  code: string;      // ISO 3166-1 alpha-2 (e.g., "US")
+  name: string;      // Country name
+  dialCode: string;  // International dial code (e.g., "+1")
+  flag?: ReactNode;  // Optional flag icon
+}
+```
+
+## Keyboard Navigation
+
+| Key | Action |
+| :-- | :----- |
+| Arrow Down | Open dropdown / Next country |
+| Arrow Up | Previous country |
+| Enter | Select country / Open dropdown |
+| Escape | Close dropdown |
+
+## Accessibility
+
+- Country selector uses `role="combobox"`
+- Country list uses `role="listbox"` with `role="option"` items
+- Searchable dropdown with `aria-controls` linking
+- Phone input uses `type="tel"` and `inputMode="tel"`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xsolla/xui-input-phone",
-  "version": "0.99.0",
+  "version": "0.100.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.99.0",
-    "@xsolla/xui-primitives-core": "0.99.0",
+    "@xsolla/xui-core": "0.100.0",
+    "@xsolla/xui-primitives-core": "0.100.0",
     "libphonenumber-js": "^1.10.56"
   },
   "peerDependencies": {