@xsolla/xui-input 0.149.1 → 0.151.0

package/README.md

@@ -1,397 +1,142 @@
 # Input
 
-A cross-platform React input component with label, error states, icons, clear button, and validation support. Works on both React (web) and React Native.
+A cross-platform text input with label, error, icon, clear and validation support; works on web and React Native via `XUIProvider` themed contexts.
 
 ## Installation
 
 ```bash
 npm install @xsolla/xui-input
-# or
-yarn add @xsolla/xui-input
 ```
 
-## Prerequisites
-
-**Important:** Input requires `XUIProvider` from `@xsolla/xui-core` to be wrapped around your app for proper theming.
-
-If your input appears white or washed out on a light background, you need to set the theme mode:
+## Imports
 
 ```tsx
-import { XUIProvider } from '@xsolla/xui-core';
-
-// For light/white page backgrounds
-<XUIProvider initialMode="light">
-  <YourApp />
-</XUIProvider>
-
-// For dark page backgrounds (default)
-<XUIProvider initialMode="dark">
-  <YourApp />
-</XUIProvider>
+import { Input } from '@xsolla/xui-input';
+import type { InputProps } from '@xsolla/xui-input';
 ```
 
-See [Quick Start](../overview/quick-start.md) for more details.
-
-## Demo
-
-### Basic Input
+## Quick start
 
 ```tsx
-import * as React from 'react';
-import { Input } from '@xsolla/xui-input';
+const [value, setValue] = useState('');
 
-export default function BasicInput() {
-  const [value, setValue] = React.useState('');
-
-  return (
-    <Input
-      value={value}
-      onChangeText={setValue}
-      placeholder="Enter text"
-    />
-  );
-}
+<Input
+  label="Email"
+  value={value}
+  onChangeText={setValue}
+  placeholder="you@example.com"
+/>;
 ```
 
-### Input with Label
+## API Reference
 
-```tsx
-import * as React from 'react';
-import { Input } from '@xsolla/xui-input';
+### `<Input>`
 
-export default function LabeledInput() {
-  const [email, setEmail] = React.useState('');
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `value` | `string` | — | Controlled value. |
+| `placeholder` | `string` | — | Placeholder shown when empty. |
+| `onChange` | `(e: ChangeEvent<HTMLInputElement>) => void` | — | Native change handler. |
+| `onChangeText` | `(text: string) => void` | — | Simplified change handler receiving the text. |
+| `size` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` | `'md'` | Control size. |
+| `disabled` | `boolean` | `false` | Disable the input. |
+| `label` | `string` | — | Label rendered above the input. |
+| `error` | `boolean` | `false` | Apply error styling. |
+| `errorMessage` | `string` | — | Error message; also marks the input invalid. |
+| `iconLeft` | `ReactNode` | — | Icon on the left. |
+| `iconRight` | `ReactNode` | — | Icon on the right. |
+| `iconRightSize` | `number \| string` | — | Override the right-icon size. |
+| `extraClear` | `boolean` | `false` | Show a clear button when the input has a value. |
+| `onRemove` | `() => void` | — | Fired when the clear button is pressed. |
+| `checked` | `boolean` | `false` | Show a success indicator (suppressed when `errorMessage` is set). |
+| `checkedIcon` | `ReactNode` | `<CheckCr />` | Override the checked icon. |
+| `borderTopLeftRadius` | `number` | — | Override top-left corner radius. |
+| `borderTopRightRadius` | `number` | — | Override top-right corner radius. |
+| `borderBottomLeftRadius` | `number` | — | Override bottom-left corner radius. |
+| `borderBottomRightRadius` | `number` | — | Override bottom-right corner radius. |
+| `backgroundColor` | `string` | — | Override the background colour. |
+| `id` | `string` | `auto` | HTML id; also wires up the label. |
+| `aria-label` | `string` | — | Accessible label when no visible label is present. |
+| `testID` | `string` | — | Test identifier. |
+
+`Input` also accepts the standard `InputHTMLAttributes` (excluding `size` and `onChange`, which are redefined above).
+
+Inherits `ThemeOverrideProps` (`themeMode`, `themeProductContext`).
 
-  return (
-    <Input
-      label="Email Address"
-      value={email}
-      onChangeText={setEmail}
-      placeholder="you@example.com"
-    />
-  );
-}
-```
+## Examples
 
-### Input Sizes
+### Sizes
 
 ```tsx
-import * as React from 'react';
-import { Input } from '@xsolla/xui-input';
-
-export default function InputSizes() {
-  return (
-    <div style={{ display: 'flex', flexDirection: 'column', gap: 16 }}>
-      <Input size="xs" placeholder="Extra Small" />
-      <Input size="sm" placeholder="Small" />
-      <Input size="md" placeholder="Medium (default)" />
-      <Input size="lg" placeholder="Large" />
-      <Input size="xl" placeholder="Extra Large" />
-    </div>
-  );
-}
+<Input size="xs" placeholder="Extra small" />
+<Input size="sm" placeholder="Small" />
+<Input size="md" placeholder="Medium" />
+<Input size="lg" placeholder="Large" />
+<Input size="xl" placeholder="Extra large" />
 ```
 
-### Input with Icons
+### Icons
 
 ```tsx
-import * as React from 'react';
-import { Input } from '@xsolla/xui-input';
 import { Search, Check } from '@xsolla/xui-icons';
-import { Calendar, Mail } from '@xsolla/xui-icons-base';
-
-export default function InputWithIcons() {
-  return (
-    <div style={{ display: 'flex', flexDirection: 'column', gap: 16 }}>
-      <Input
-        iconLeft={<Search />}
-        placeholder="Search..."
-      />
-      <Input
-        iconRight={<Calendar />}
-        placeholder="Select date"
-      />
-      <Input
-        iconLeft={<Mail />}
-        iconRight={<Check />}
-        placeholder="Email"
-      />
-    </div>
-  );
-}
-```
-
-### Input with Clear Button
-
-```tsx
-import * as React from 'react';
-import { Input } from '@xsolla/xui-input';
-
-export default function ClearableInput() {
-  const [value, setValue] = React.useState('Some text');
+import { Mail } from '@xsolla/xui-icons-base';
 
-  return (
-    <Input
-      value={value}
-      onChangeText={setValue}
-      extraClear
-      onRemove={() => setValue('')}
-      placeholder="Type something..."
-    />
-  );
-}
+<Input iconLeft={<Search />} placeholder="Search..." />
+<Input iconLeft={<Mail />} iconRight={<Check />} placeholder="Email" />
 ```
 
-### Input with Validation
+### Clear button
 
 ```tsx
-import * as React from 'react';
-import { Input } from '@xsolla/xui-input';
-
-export default function ValidatedInput() {
-  const [email, setEmail] = React.useState('');
-  const [error, setError] = React.useState('');
-
-  const validateEmail = (value: string) => {
-    setEmail(value);
-    if (value && !value.includes('@')) {
-      setError('Please enter a valid email address');
-    } else {
-      setError('');
-    }
-  };
-
-  return (
-    <Input
-      label="Email"
-      value={email}
-      onChangeText={validateEmail}
-      error={!!error}
-      errorMessage={error}
-      placeholder="you@example.com"
-    />
-  );
-}
-```
-
-## Anatomy
-
-Import the component and use it directly:
-
-```jsx
-import { Input } from '@xsolla/xui-input';
+const [value, setValue] = useState('Some text');
 
 <Input
-  label="Field Label"        // Optional label above input
-  value={value}              // Controlled value
-  onChangeText={setValue}    // Value change handler
-  placeholder="Placeholder"  // Placeholder text
-  iconLeft={<Icon />}        // Optional left icon
-  iconRight={<Icon />}       // Optional right icon
-  extraClear                 // Shows clear button when has value
-  error                      // Error state boolean
-  errorMessage="Error text"  // Error message below input
-  disabled                   // Disabled state
-/>
+  value={value}
+  onChangeText={setValue}
+  extraClear
+  onRemove={() => setValue('')}
+  placeholder="Type something..."
+/>;
 ```
 
-## Examples
-
-### Disabled Input
+### Validation
 
 ```tsx
-import * as React from 'react';
-import { Input } from '@xsolla/xui-input';
-
-export default function DisabledInput() {
-  return (
-    <Input
-      label="Disabled Field"
-      value="Cannot edit this"
-      disabled
-    />
-  );
-}
-```
-
-### Input with Success State
-
-```tsx
-import * as React from 'react';
-import { Input } from '@xsolla/xui-input';
-
-export default function SuccessInput() {
-  return (
-    <Input
-      label="Username"
-      value="johndoe"
-      checked
-      placeholder="Enter username"
-    />
-  );
-}
-```
-
-### Custom Border Radius
+const [email, setEmail] = useState('');
+const error = email && !email.includes('@') ? 'Invalid email' : '';
 
-```tsx
-import * as React from 'react';
-import { Input } from '@xsolla/xui-input';
-
-export default function CustomRadiusInput() {
-  return (
-    <Input
-      placeholder="Rounded input"
-      borderTopLeftRadius={20}
-      borderTopRightRadius={20}
-      borderBottomLeftRadius={20}
-      borderBottomRightRadius={20}
-    />
-  );
-}
+<Input
+  label="Email"
+  value={email}
+  onChangeText={setEmail}
+  error={!!error}
+  errorMessage={error}
+  placeholder="you@example.com"
+/>;
 ```
 
-### Search Input
+### Disabled and success
 
 ```tsx
-import * as React from 'react';
-import { Input } from '@xsolla/xui-input';
-import { Search } from '@xsolla/xui-icons';
-
-export default function SearchInput() {
-  const [query, setQuery] = React.useState('');
-
-  return (
-    <Input
-      value={query}
-      onChangeText={setQuery}
-      iconLeft={<Search />}
-      extraClear
-      onRemove={() => setQuery('')}
-      placeholder="Search..."
-      size="md"
-    />
-  );
-}
+<Input label="Disabled" value="Cannot edit" disabled />
+<Input label="Username" value="johndoe" checked />
 ```
 
-### Form with Multiple Inputs
+### Custom border radius
 
 ```tsx
-import * as React from 'react';
-import { Input } from '@xsolla/xui-input';
-import { Mail } from '@xsolla/xui-icons-base';
-
-export default function FormInputs() {
-  const [form, setForm] = React.useState({
-    firstName: '',
-    lastName: '',
-    email: '',
-  });
-
-  const updateField = (field: string) => (value: string) => {
-    setForm(prev => ({ ...prev, [field]: value }));
-  };
-
-  return (
-    <div style={{ display: 'flex', flexDirection: 'column', gap: 16 }}>
-      <Input
-        label="First Name"
-        value={form.firstName}
-        onChangeText={updateField('firstName')}
-        placeholder="John"
-      />
-      <Input
-        label="Last Name"
-        value={form.lastName}
-        onChangeText={updateField('lastName')}
-        placeholder="Doe"
-      />
-      <Input
-        label="Email"
-        value={form.email}
-        onChangeText={updateField('email')}
-        iconLeft={<Mail />}
-        placeholder="john@example.com"
-      />
-    </div>
-  );
-}
-```
-
-## API Reference
-
-### Input
-
-The main input component. Renders a semantic `<input>` element with wrapper styling.
-
-**Input Props:**
-
-| Prop | Type | Default | Description |
-| :--- | :--- | :------ | :---------- |
-| value | `string` | - | The controlled value of the input. |
-| placeholder | `string` | - | Placeholder text shown when input is empty. |
-| onChange | `(e: ChangeEvent<HTMLInputElement>) => void` | - | Native change event handler. |
-| onChangeText | `(text: string) => void` | - | Simplified change handler receiving text value. |
-| size | `"xl" \| "lg" \| "md" \| "sm" \| "xs"` | `"md"` | The size of the input. |
-| disabled | `boolean` | `false` | Whether the input is disabled. |
-| label | `string` | - | Label text displayed above the input. |
-| errorMessage | `string` | - | Error message displayed below the input. |
-| error | `boolean` | `false` | Whether to show error styling. |
-| iconLeft | `ReactNode` | - | Icon displayed on the left side. |
-| iconRight | `ReactNode` | - | Icon displayed on the right side. |
-| extraClear | `boolean` | `false` | Whether to show clear button when input has value. |
-| onRemove | `() => void` | - | Callback when clear button is clicked. |
-| checked | `boolean` | `false` | Whether to show success/check icon. |
-| checkedIcon | `ReactNode` | `<Check />` | Custom icon for checked state. |
-| iconRightSize | `number \| string` | - | Custom size for right icon. |
-| borderTopLeftRadius | `number` | - | Custom top-left border radius. |
-| borderTopRightRadius | `number` | - | Custom top-right border radius. |
-| borderBottomLeftRadius | `number` | - | Custom bottom-left border radius. |
-| borderBottomRightRadius | `number` | - | Custom bottom-right border radius. |
-| backgroundColor | `string` | - | Custom background color. |
-| aria-label | `string` | - | Accessible label for the input. |
-| id | `string` | - | HTML id attribute (also links label). |
-| testID | `string` | - | Test identifier for testing frameworks. |
-
-**Size Configuration:**
-
-| Size | Height | Padding (V/H) | Font Size | Icon Size |
-| :--- | :----- | :------------ | :-------- | :-------- |
-| xl | 56px | 12px / 12px | 16px | 18px |
-| lg | 48px | 14px / 12px | 16px | 18px |
-| md | 40px | 11px / 12px | 14px | 18px |
-| sm | 32px | 7px / 10px | 14px | 16px |
-| xs | 28px | 7px / 10px | 12px | 16px |
-
-## Theming
-
-Input components use the design system theme for colors and sizing:
-
-```typescript
-// Colors accessed via theme
-theme.colors.control.input.bg           // Background color
-theme.colors.control.input.bgHover      // Hover background
-theme.colors.control.input.bgFocus      // Focus background
-theme.colors.control.input.bgDisable    // Disabled background
-theme.colors.control.input.border       // Border color
-theme.colors.control.input.borderFocus  // Focus border color
-theme.colors.control.input.borderError  // Error border color
-theme.colors.control.input.text         // Text color
-theme.colors.control.input.placeholder  // Placeholder color
-
-// Sizing accessed via theme
-theme.sizing.input(size).height
-theme.sizing.input(size).paddingVertical
-theme.sizing.input(size).paddingHorizontal
-theme.sizing.input(size).fontSize
+<Input
+  placeholder="Rounded"
+  borderTopLeftRadius={20}
+  borderTopRightRadius={20}
+  borderBottomLeftRadius={20}
+  borderBottomRightRadius={20}
+/>
 ```
 
 ## Accessibility
 
-- Uses semantic `<input>` element with proper `<label>` association
-- Label is linked via `htmlFor` attribute
-- Error messages use `aria-describedby` for screen readers
-- Focus indicators follow WCAG guidelines
-- Disabled state properly communicated to assistive technology
-- Clear button includes accessible label
+- Renders a semantic `<input>` whose `aria-labelledby` points at the `id` of the rendered `<label>` element (rather than the standard `<label htmlFor>` pairing).
+- Error messages are linked through `aria-describedby` and announced via `role="alert"`.
+- `aria-invalid` and `aria-disabled` reflect error and disabled state.
+- Pressing Escape blurs the input.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xsolla/xui-input",
-  "version": "0.149.1",
+  "version": "0.151.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.149.1",
-    "@xsolla/xui-icons-base": "0.149.1",
-    "@xsolla/xui-primitives-core": "0.149.1"
+    "@xsolla/xui-core": "0.151.0",
+    "@xsolla/xui-icons-base": "0.151.0",
+    "@xsolla/xui-primitives-core": "0.151.0"
   },
   "peerDependencies": {
     "react": ">=16.8.0",