@xsolla/xui-select 0.148.0 → 0.148.2

package/README.md

@@ -0,0 +1,358 @@
+# Select
+
+A cross-platform React select component for choosing from a list of predefined options with dropdown menu. Works on both React (web) and React Native.
+
+## Installation
+
+```bash
+npm install @xsolla/xui-select
+# or
+yarn add @xsolla/xui-select
+```
+
+## Demo
+
+### Basic Select
+
+```tsx
+import * as React from 'react';
+import { Select } from '@xsolla/xui-select';
+
+export default function BasicSelect() {
+  const [value, setValue] = React.useState('');
+
+  return (
+    <Select
+      value={value}
+      onChange={setValue}
+      options={['Option 1', 'Option 2', 'Option 3']}
+      placeholder="Select an option"
+    />
+  );
+}
+```
+
+### Select with Label
+
+```tsx
+import * as React from 'react';
+import { Select } from '@xsolla/xui-select';
+
+export default function LabeledSelect() {
+  const [country, setCountry] = React.useState('');
+
+  return (
+    <Select
+      label="Country"
+      value={country}
+      onChange={setCountry}
+      options={['United States', 'Canada', 'United Kingdom', 'Germany', 'France']}
+      placeholder="Select a country"
+    />
+  );
+}
+```
+
+### Select with Object Options
+
+```tsx
+import * as React from 'react';
+import { Select } from '@xsolla/xui-select';
+
+export default function ObjectOptionsSelect() {
+  const [status, setStatus] = React.useState('');
+
+  const options = [
+    { label: 'Active', value: 'active' },
+    { label: 'Pending', value: 'pending' },
+    { label: 'Inactive', value: 'inactive' },
+  ];
+
+  return (
+    <Select
+      label="Status"
+      value={status}
+      onChange={setStatus}
+      options={options}
+      placeholder="Select status"
+    />
+  );
+}
+```
+
+### Select Sizes
+
+```tsx
+import * as React from 'react';
+import { Select } from '@xsolla/xui-select';
+
+export default function SelectSizes() {
+  const options = ['Small', 'Medium', 'Large'];
+
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 16 }}>
+      <Select size="xs" options={options} placeholder="Extra Small" />
+      <Select size="sm" options={options} placeholder="Small" />
+      <Select size="md" options={options} placeholder="Medium (default)" />
+      <Select size="lg" options={options} placeholder="Large" />
+      <Select size="xl" options={options} placeholder="Extra Large" />
+    </div>
+  );
+}
+```
+
+### Select with Icons
+
+```tsx
+import * as React from 'react';
+import { Select } from '@xsolla/xui-select';
+import { Globe } from '@xsolla/xui-icons-base';
+
+export default function SelectWithIcons() {
+  return (
+    <Select
+      iconLeft={<Globe />}
+      options={['English', 'Spanish', 'French', 'German']}
+      placeholder="Select language"
+    />
+  );
+}
+```
+
+## Anatomy
+
+Import the component and use it directly:
+
+```jsx
+import { Select } from '@xsolla/xui-select';
+
+<Select
+  label="Field Label"           // Optional label above select
+  value={value}                 // Controlled selected value
+  onChange={setValue}           // Value change handler
+  options={['A', 'B', 'C']}     // Array of options (strings or objects)
+  placeholder="Select..."       // Placeholder text
+  iconLeft={<Icon />}           // Optional left icon
+  iconRight={<Icon />}          // Optional right icon (default: ChevronDown)
+  filled                        // Whether to show filled background
+  state="error"                 // State: "default" | "disable" | "error"
+  errorMessage="Error message"  // Error message (shown when state="error")
+/>
+```
+
+## Examples
+
+### Error State
+
+```tsx
+import * as React from 'react';
+import { Select } from '@xsolla/xui-select';
+
+export default function ErrorSelect() {
+  return (
+    <Select
+      label="Required Field"
+      state="error"
+      errorMessage="Please select an option"
+      options={['Option 1', 'Option 2', 'Option 3']}
+      placeholder="Select an option"
+    />
+  );
+}
+```
+
+### Disabled Select
+
+```tsx
+import * as React from 'react';
+import { Select } from '@xsolla/xui-select';
+
+export default function DisabledSelect() {
+  return (
+    <Select
+      label="Disabled Field"
+      value="Option 1"
+      state="disable"
+      options={['Option 1', 'Option 2', 'Option 3']}
+    />
+  );
+}
+```
+
+### Unfilled/Transparent Background
+
+```tsx
+import * as React from 'react';
+import { Select } from '@xsolla/xui-select';
+
+export default function UnfilledSelect() {
+  return (
+    <Select
+      filled={false}
+      options={['Option 1', 'Option 2', 'Option 3']}
+      placeholder="Transparent background"
+    />
+  );
+}
+```
+
+### Icon Only Select
+
+```tsx
+import * as React from 'react';
+import { Select } from '@xsolla/xui-select';
+import { Settings } from '@xsolla/xui-icons';
+
+export default function IconOnlySelect() {
+  return (
+    <Select
+      iconOnly
+      iconLeft={<Settings />}
+      options={['Settings', 'Preferences', 'Advanced']}
+    />
+  );
+}
+```
+
+### Form with Select
+
+```tsx
+import * as React from 'react';
+import { Select } from '@xsolla/xui-select';
+import { Input } from '@xsolla/xui-input';
+import { Button } from '@xsolla/xui-button';
+
+export default function FormWithSelect() {
+  const [form, setForm] = React.useState({
+    name: '',
+    category: '',
+    priority: '',
+  });
+
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 16, width: 300 }}>
+      <Input
+        label="Task Name"
+        value={form.name}
+        onChangeText={(name) => setForm(prev => ({ ...prev, name }))}
+        placeholder="Enter task name"
+      />
+      <Select
+        label="Category"
+        value={form.category}
+        onChange={(category) => setForm(prev => ({ ...prev, category }))}
+        options={['Development', 'Design', 'Marketing', 'Sales']}
+        placeholder="Select category"
+      />
+      <Select
+        label="Priority"
+        value={form.priority}
+        onChange={(priority) => setForm(prev => ({ ...prev, priority }))}
+        options={[
+          { label: 'High', value: 'high' },
+          { label: 'Medium', value: 'medium' },
+          { label: 'Low', value: 'low' },
+        ]}
+        placeholder="Select priority"
+      />
+      <Button>Create Task</Button>
+    </div>
+  );
+}
+```
+
+## API Reference
+
+### Select
+
+The main select component. Renders a button trigger with dropdown menu.
+
+**Select Props:**
+
+| Prop | Type | Default | Description |
+| :--- | :--- | :------ | :---------- |
+| value | `string` | - | The controlled selected value. |
+| placeholder | `string` | `"Select"` | Placeholder text when no value selected. |
+| onPress | `() => void` | - | Callback when select trigger is pressed. |
+| size | `"xl" \| "lg" \| "md" \| "sm" \| "xs"` | `"md"` | The size of the select. |
+| state | `"default" \| "hover" \| "focus" \| "disable" \| "error"` | `"default"` | The visual state of the select. |
+| label | `string` | - | Label text displayed above the select. |
+| disabled | `boolean` | `false` | Whether the select is disabled. Also triggered when `state="disable"`. |
+| errorMessage | `string` | - | Error message displayed below the select (also sets error styling). |
+| iconLeft | `ReactNode` | - | Icon displayed on the left side. |
+| iconRight | `ReactNode` | `<ChevronDown />` | Icon displayed on the right side. |
+| filled | `boolean` | `true` | Whether to show filled background. |
+| iconOnly | `boolean` | `false` | Whether to show only icon without text. |
+| options | `(string \| SelectOption)[]` | `[]` | Array of options to display. |
+| onChange | `(value: string) => void` | - | Callback when value changes. |
+| searchable | `boolean` | `false` | Whether to show a search input in the dropdown. |
+| searchPlaceholder | `string` | `"Search"` | Placeholder text for the search input. |
+| noOptionsMessage | `string` | `"No results"` | Message shown when no options match the search. |
+| maxHeight | `number` | `300` | Maximum height of the dropdown in pixels. |
+
+**SelectOption Type:**
+
+```typescript
+interface SelectOption {
+  label: string;     // Display text
+  value: any;        // Value to be selected
+  disabled?: boolean; // Whether this option is disabled
+}
+```
+
+## Theming
+
+Select 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.brand.primary.bg   // Selected option background
+
+// Sizing accessed via theme
+theme.sizing.input(size).height
+theme.sizing.input(size).paddingVertical
+theme.sizing.input(size).paddingHorizontal
+theme.sizing.input(size).fontSize
+
+// Border radius
+theme.radius.button
+```
+
+**Dropdown Styling:**
+
+| Property | Value |
+| :------- | :---- |
+| Max Height | 300px (configurable via `maxHeight` prop) |
+| Box Shadow | 0 4px 12px rgba(0,0,0,0.1) |
+| Z-Index | 1000 |
+| Scroll | overflowY: auto |
+
+## React Native Notes
+
+The Select component works on React Native with the following differences:
+
+| Feature | Web | React Native |
+|---------|-----|-------------|
+| Searchable dropdown | Supported (`searchable` prop) | **Not available** — prop is ignored |
+| Dropdown shadow | CSS `box-shadow` | Android `elevation: 4` |
+| Scroll behavior | `overflowY: auto` | Native `ScrollView` |
+| Cursor styles | `pointer` / `not-allowed` | Ignored |
+| Click-outside dismiss | `document.addEventListener` | Not active (guarded by `isNative`) |
+
+## Accessibility
+
+- Uses semantic button element for trigger
+- Dropdown menu has proper focus management
+- Keyboard navigation supported (Tab, Enter, Space, Escape)
+- Selected item is visually highlighted
+- Auto-scrolls to selected item when opened (web only)
+- Focus indicators follow WCAG guidelines
+- Disabled state properly communicated to assistive technology

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xsolla/xui-select",
-  "version": "0.148.0",
+  "version": "0.148.2",
   "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.148.0",
-    "@xsolla/xui-icons-base": "0.148.0",
-    "@xsolla/xui-primitives-core": "0.148.0"
+    "@xsolla/xui-core": "0.148.2",
+    "@xsolla/xui-icons-base": "0.148.2",
+    "@xsolla/xui-primitives-core": "0.148.2"
   },
   "peerDependencies": {
     "react": ">=16.8.0",