@xsolla/xui-autocomplete 0.174.2 → 0.175.0

package/README.md

@@ -1,7 +1,53 @@
 # 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.
-
+<!-- BEGIN:xui-mcp-instructions:autocomplete -->
+Typically used for searching large or dynamic datasets. The data source is determined by the implementation — it may be a backend API, a large pre-loaded list, or any async data source. Unlike Select, the list is filtered on each keystroke.
+
+In the Focus state, use the ContextMenu component as the dropdown. The spacing between the Autocomplete field and the ContextMenu is 4px in all sizes.
+
+### When to use
+- When the user must select a value from a large or dynamic dataset that cannot be loaded all at once
+- When a free-text search with suggestions speeds up data entry (e.g. city names, product search, user lookup)
+- When valid values need to be filtered or validated as the user types
+
+### When not to use
+- When the list is small and static — use a Select instead
+- When the user can enter any free-form text without needing suggestions — use a plain Input
+- When multiple values need to be selected simultaneously — use a MultiSelect
+
+### Content guidelines
+- Placeholder should describe what the user is searching for: *"Search city"*, *"Find product"* — not just *"Search"*.
+- Error messages should be specific: *"No results found"*, *"Select a valid option from the list"* — not *"Invalid value"*.
+- Value text should show the selected item's human-readable label, not an ID or code.
+- Do not show the Remove button in the Disable state — users cannot clear a disabled field.
+
+### ContextMenu integration
+- The dropdown list is a separate ContextMenu component, not embedded in Autocomplete itself. Rules:
+- Open on Focus; close on blur or item selection
+- Position the ContextMenu 4px below the Autocomplete field, matching the field width
+- Every keystroke should trigger a backend request to filter the list
+- Show a loading indicator inside the ContextMenu while the request is in progress
+- Show an empty state message when no results are found
+
+### Behaviour guidelines
+- Debounce backend requests — wait ~200–300ms after the user stops typing before firing the request. This reduces server load and avoids flickering results.
+- Minimum query length — consider requiring at least 1–2 characters before querying. Show a hint (*"Type to search"*) in the dropdown if fewer characters are entered.
+- Keyboard navigation — once the ContextMenu is open, arrow keys should move focus through options; Enter selects; Escape closes and returns focus to the input.
+- Clear on re-focus — if the user focuses the field after a value is selected, either retain the value (for editing) or clear it to allow a new search. Document which behaviour the team has chosen.
+- Selecting an item — selecting an option from the ContextMenu should populate the value, close the dropdown, and move the chevron back to down-state.
+- Pasting — if the user pastes a value, trigger a search immediately.
+
+### Accessibility
+- Use role=*"combobox"* on the input, aria-expanded to reflect whether the dropdown is open, and aria-controls pointing to the ContextMenu list
+- Use aria-autocomplete=*"list"* to indicate that suggestions come from a list
+- The ContextMenu list should use role=*"listbox"* with role=*"option"* on each item
+- Arrow-key navigation must move aria-activedescendant on the input to match the focused option
+- Icon left (search icon) is decorative — add aria-hidden=*"true"*
+- Remove button must have an accessible name: aria-label=*"Clear"*
+- Chevron is decorative — add aria-hidden=*"true"*. Use aria-expanded to communicate open/closed state
+- Error message must be linked via aria-describedby so screen readers announce it on focus
+<!-- END:xui-mcp-instructions:autocomplete -->
 ## Installation
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xsolla/xui-autocomplete",
-  "version": "0.174.2",
+  "version": "0.175.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.174.2",
-    "@xsolla/xui-primitives-core": "0.174.2",
-    "@xsolla/xui-spinner": "0.174.2"
+    "@xsolla/xui-core": "0.175.0",
+    "@xsolla/xui-primitives-core": "0.175.0",
+    "@xsolla/xui-spinner": "0.175.0"
   },
   "peerDependencies": {
     "react": ">=16.8.0",