@xsolla/xui-autocomplete 0.99.0 → 0.100.0

package/README.md

@@ -1,41 +1,178 @@
-# @xsolla/xui-autocomplete
+---
+title: Autocomplete
+subtitle: An input with filtered suggestion list.
+description: A cross-platform React autocomplete component with searchable dropdown, loading states, and rich option support.
+---
 
-Text input with a filterable dropdown of suggestions supporting keyboard navigation.
+# Autocomplete
+
+A cross-platform React autocomplete component that provides a filterable dropdown list of suggestions as the user types. Supports both simple string options and rich objects with icons and descriptions.
 
 ## Installation
 
 ```bash
+npm install @xsolla/xui-autocomplete
+# or
 yarn add @xsolla/xui-autocomplete
 ```
 
-## Usage
+## Demo
+
+### Basic Autocomplete
+
+```tsx
+import * as React from 'react';
+import { Autocomplete } from '@xsolla/xui-autocomplete';
+
+export default function BasicAutocomplete() {
+  const [value, setValue] = React.useState('');
+
+  return (
+    <Autocomplete
+      value={value}
+      onValueChange={setValue}
+      options={['Apple', 'Banana', 'Cherry', 'Date', 'Elderberry']}
+      placeholder="Search fruits..."
+    />
+  );
+}
+```
+
+### Rich Options with Icons
+
+```tsx
+import * as React from 'react';
+import { Autocomplete } from '@xsolla/xui-autocomplete';
+import { Settings, User } from '@xsolla/xui-icons';
+import { LayoutDashboard } from '@xsolla/xui-icons-base';
+
+export default function RichAutocomplete() {
+  const [value, setValue] = React.useState('');
+
+  const options = [
+    { id: '1', label: 'Dashboard', description: 'View your dashboard', icon: <LayoutDashboard size={16} /> },
+    { id: '2', label: 'Settings', description: 'Manage your settings', icon: <Settings size={16} /> },
+    { id: '3', label: 'Profile', description: 'Edit your profile', icon: <User size={16} /> },
+  ];
+
+  return (
+    <Autocomplete
+      value={value}
+      onValueChange={setValue}
+      list={options}
+      onSelect={(option) => console.log('Selected:', option)}
+      placeholder="Search pages..."
+    />
+  );
+}
+```
+
+### Loading State
 
 ```tsx
+import * as React from 'react';
+import { Autocomplete } from '@xsolla/xui-autocomplete';
+
+export default function LoadingAutocomplete() {
+  const [value, setValue] = React.useState('');
+  const [loading, setLoading] = React.useState(false);
+  const [options, setOptions] = React.useState([]);
+
+  const handleSearch = async (query: string) => {
+    setValue(query);
+    if (query.length >= 2) {
+      setLoading(true);
+      // Simulate API call
+      await new Promise(r => setTimeout(r, 500));
+      setOptions(['Result 1', 'Result 2', 'Result 3']);
+      setLoading(false);
+    }
+  };
+
+  return (
+    <Autocomplete
+      value={value}
+      onValueChange={handleSearch}
+      options={options}
+      isLoading={loading}
+      placeholder="Type to search..."
+    />
+  );
+}
+```
+
+## Anatomy
+
+```jsx
 import { Autocomplete } from '@xsolla/xui-autocomplete';
 
 <Autocomplete
-  label="Search games"
-  options={['Cyberpunk 2077', 'Elden Ring', 'Starfield']}
-  onValueChange={(text) => console.log(text)}
-  onSelect={(value) => console.log(value)}
+  value={inputValue}           // Input text value
+  onValueChange={setValue}     // Input change handler
+  options={['a', 'b']}         // Simple string options
+  list={[{id, label, ...}]}    // Rich options with metadata
+  onSelect={handleSelect}      // Selection handler
+  isLoading={false}            // Show loading spinner
+  placeholder="Search..."      // Placeholder text
+  size="md"                     // Size variant
+  label="Label"                // Label above input
+  errorLabel="Error"           // Error message
+  state="default"              // Visual state
+  maxHeight={200}              // Dropdown max height
+  emptyMessage="No results"    // Empty state message
 />
 ```
 
-## Props
+## API Reference
 
 ### Autocomplete
 
+**Autocomplete Props:**
+
 | Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `options` | `string[]` | `[]` | Simple string options |
-| `list` | `AutocompleteOption[]` | — | Rich options with `id`, `label`, `description`, `icon`; takes priority over `options` |
-| `value` | `string` | — | Controlled input value |
-| `onValueChange` | `(value: string) => void` | — | Called on every keystroke |
-| `onSelect` | `(option: string \| AutocompleteOption) => void` | — | Called when an option is selected |
-| `placeholder` | `string` | `"Search..."` | Input placeholder text |
-| `label` | `string` | — | Label displayed above the input |
-| `size` | `"xl" \| "lg" \| "md" \| "sm" \| "xs"` | `"md"` | Size of the control |
-| `state` | `"default" \| "hover" \| "focus" \| "disable" \| "error"` | — | Visual state |
-| `isLoading` | `boolean` | `false` | Shows a spinner in the dropdown while loading |
-| `errorLabel` | `string` | — | Error message shown below the control |
-| `emptyMessage` | `string` | `"No results found"` | Shown when no options match |
+| :--- | :--- | :------ | :---------- |
+| value | `string` | - | Current input value. |
+| onValueChange | `(value: string) => void` | - | Input change handler. |
+| options | `string[]` | - | Simple string options array. |
+| list | `AutocompleteOption[]` | - | Rich options with metadata. |
+| onSelect | `(option: string \| AutocompleteOption) => void` | - | Selection handler. |
+| isLoading | `boolean` | `false` | Show loading spinner. |
+| placeholder | `string` | - | Input placeholder text. |
+| size | `"xl" \| "lg" \| "md" \| "sm" \| "xs"` | `"md"` | Component size. |
+| state | `"default" \| "hover" \| "focus" \| "disable" \| "error"` | `"default"` | Visual state. |
+| label | `string` | - | Label above input. |
+| errorLabel | `string` | - | Error message below input. |
+| iconLeft | `ReactNode` | - | Icon on left side. |
+| chevronRight | `boolean` | - | Show chevron on right. |
+| filled | `boolean` | - | Filled background style. |
+| maxHeight | `number` | - | Dropdown max height in px. |
+| dropdownWidth | `number \| string` | - | Custom dropdown width. |
+| emptyMessage | `string` | - | Message when no results. |
+
+**AutocompleteOption:**
+
+```typescript
+interface AutocompleteOption {
+  id: string;           // Unique identifier
+  label: string;        // Display text
+  description?: string; // Optional description
+  icon?: ReactNode;     // Optional leading icon
+  disabled?: boolean;   // Disabled state
+}
+```
+
+## Keyboard Navigation
+
+| Key | Action |
+| :-- | :----- |
+| Arrow Down | Move to next option |
+| Arrow Up | Move to previous option |
+| Enter | Select highlighted option |
+| Escape | Close dropdown |
+
+## Accessibility
+
+- Uses `role="combobox"` pattern
+- `aria-expanded` indicates dropdown state
+- `aria-autocomplete="list"` for screen readers
+- Options have proper focus management

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xsolla/xui-autocomplete",
-  "version": "0.99.0",
+  "version": "0.100.0",
   "main": "./web/index.js",
   "module": "./web/index.mjs",
   "types": "./web/index.d.ts",
@@ -10,9 +10,9 @@
     "build:native": "PLATFORM=native tsup"
   },
   "dependencies": {
-    "@xsolla/xui-core": "0.99.0",
-    "@xsolla/xui-primitives-core": "0.99.0",
-    "@xsolla/xui-spinner": "0.99.0"
+    "@xsolla/xui-core": "0.100.0",
+    "@xsolla/xui-primitives-core": "0.100.0",
+    "@xsolla/xui-spinner": "0.100.0"
   },
   "peerDependencies": {
     "react": ">=16.8.0",