@xsolla/xui-multi-select 0.202.2 → 0.202.4

package/README.md

@@ -3,67 +3,54 @@
 A cross-platform multi-select control that lets users pick multiple options from a dropdown list.
 
 <!-- BEGIN:xui-mcp-instructions:multi-select -->
-MultiSelect lets users choose several values from a predefined list at the same time. Selected values are shown inline as removable tags, so users can see and adjust their choices without reopening the menu. It is commonly used in filters, forms, and settings where more than one option can apply.
+A dropdown input that allows selecting multiple values simultaneously. Displays the current selections inside the field as text labels or removable tag chips, opens a ContextMenu with checkboxes when clicked, and supports an optional count tag when selections overflow. Built on the same trigger pattern as Select but with multi-value semantics.
 
 ### When to use
-
-When the user needs to pick more than one value from a fixed, known list (tags, categories, recipients, etc.)
-
-When it helps the user to see all current selections at once, displayed as removable tags
-- When the set of options is finite and does not require freeform typing
-- As part of a larger form or filter bar alongside other controls
+- When the user must choose more than one value from a predefined list — multiple tags, categories, permissions, countries, features
+- In filter bars where the user applies several filters simultaneously
+- In forms where a many-to-many relationship must be configured (e.g. assigning roles, selecting supported platforms)
+- When the full list of options must remain visible and re-selectable without navigating away
 
 ### When not to use
-
-- When only one value can be chosen — use a Select instead
-- When the value is freeform text the user must type — use a TextArea instead
-- When the list is short and every option should always stay visible — use a group of Checkboxes instead
-- When the choice is a single on/off — use a Switch or Checkbox instead
-- When the list is very long and the user mainly needs to search rather than browse — pair the field with search or reconsider the pattern
+- When only one value can be selected at a time — use Select
+- When the number of selectable options is very small (2–4) and all options should be permanently visible — use Checkbox group or ToggleButtonGroup
+- When the user needs to type free-form tags or values not from a predefined list — use a tag input component
+- When the user needs to rank or order selections — use a dedicated sortable list
 
 ### Content guidelines
-
-Do not use the placeholder as a substitute for a label.
-
-Placeholder text should prompt the action, not repeat the label (e.g. *"Select tags"*, not *"Tags"*).
-
-Option labels should be short, parallel in structure, and ordered logically — alphabetically, by frequency, or by a meaningful sequence — rather than at random.
-
-Each selected tag should carry the same label as its option so users can match a tag back to its source.
-
-When selections overflow a non-flexible field, collapse the remainder into a clear *"+N"* counter (e.g. *"+5"*) rather than truncating tags.
-
-Error messages should be constructive: explain what is wrong and how to fix it (e.g. *"Select at least one option"*, not just *"Invalid input"*).
-
-The clear-all button should appear only when at least one value is selected.
+- Placeholder text — use a concise instructional phrase: *"Select categories"*, *"Choose platforms"*, *"Pick permissions"*. Avoid generic *"Select…"* alone.
+- Option labels — keep each option label short (1–4 words). Use parallel structure across all options (all nouns or all short phrases). No trailing punctuation.
+- Option order — alphabetical or most common first. Do not randomise.
+- Count tag format — always use +N format (e.g. +3, +12). Do not spell out *"3 more"* inside a chip.
+- Clear button — enable for optional fields. Do not show on required fields — clearing all values on a required field immediately produces a validation error.
+- Field label — always provide a visible label above the field via FieldGroup.
+- Error messages — be specific:
+- *"Please select at least one category"* (required, empty on submit)
+- *"You can select a maximum of 5 items"* (max exceeded)
 
 ### Behaviour guidelines
-
-Flexible: True — the field grows vertically, wrapping selected tags onto multiple rows so every selection stays visible.
-
-Flexible: False — the field keeps a single row; tags that don't fit collapse into a *"+N"* counter, and the full set is visible on open or hover.
-
-Removing values — the ✕ on a tag deselects that single value; the clear-all button on the right removes every selection at once.
-
-Selecting — opening the menu shows options with their selected state marked; choosing or unchoosing an option keeps the menu open so users can pick several in a row.
-
-Dismissal — clicking outside the menu or pressing Escape closes the dropdown without discarding the current selection.
-
-Validation timing — do not show errors before the user has interacted with the field. Validate on blur or on submit, and preserve the selected values when showing an error.
+- Multi-select model — multiple values can be selected independently. Selecting one value does not deselect others. Unchecking an option in the ContextMenu removes it from the field.
+- Individual removal (Tag variant) — when Variant=Tag and Remove button=true, clicking ✕ on a chip removes that specific value from the selection without reopening the dropdown. The ContextMenu reflects the change if it is open.
+- Clear all — clicking the clear button (✕, Clear button=true) removes all selections at once and returns the field to Fill=False.
+- Count tag — when selections overflow the visible content area, show a +N count tag. Clicking it opens the dropdown panel so the user can review all selected values.
+- Opening — clicking the field or pressing Enter / Space / ↓ when focused opens the ContextMenu. The field enters State=Focus; the chevron rotates upward.
+- Closing — the ContextMenu closes on: clicking outside, pressing Escape, or pressing Tab. Focus returns to the MultiSelect field.
+- Validation — validate on blur (field loses focus with the dropdown closed) or on form submit. Show State=Error with a message if the selection is invalid (e.g. required field with no selection, or max selection exceeded).
+- Disabled — State=Disable prevents opening the dropdown. Existing selections remain visible in muted style.
+- ContextMenu width — the ContextMenu panel must be at least as wide as the MultiSelect field. Never open a narrower panel.
+- Real-time update — the field content updates as the user checks/unchecks options. Do not batch updates to the field until the dropdown closes.
 
 ### Accessibility
-
-Expose the multi-selectable nature and current selection state to assistive technology, and announce changes as values are added or removed.
-
-Each tag's remove control must be keyboard-focusable and clearly labelled (e.g. *"Remove [value]"*).
-
-Error messages must be linked to the field via aria-describedby so screen readers announce them on focus.
-
-Support full keyboard operation: open and close the menu, move through options with the arrow keys, toggle selection with Enter / Space, and remove tags without a mouse.
-
-Never rely on placeholder, tag color, or icon alone to communicate the field's purpose or state — always provide an associated label.
-
-Disabled fields should not receive keyboard focus; consider a read-only state if the selected values still need to be accessible.
+- MultiSelect must have role=*"combobox"* (or role=*"button"*) with aria-haspopup=*"listbox"* and aria-expanded=*"true"* / *"false"*.
+- The field must have an accessible name via <label for> (from FieldGroup), aria-label, or aria-labelledby.
+- The selected values must be reflected in aria-label or as visually visible text so screen readers can announce the current state — e.g. aria-label=*"Categories: Design, Development, Marketing"*.
+- When Variant=Tag and Remove button=true, each chip's remove button must have aria-label=*"Remove [value name]"* — e.g. aria-label=*"Remove Design"*.
+- The count tag (+N) must have aria-label describing the hidden count — e.g. aria-label=*"3 more selected items"*.
+- The clear button must have aria-label=*"Clear all selections"*.
+- When State=Error, the error message must be linked via aria-describedby and in an aria-live=*"polite"* region.
+- The ContextMenu dropdown uses role=*"listbox"* (or role=*"menu"*) with each option as role=*"option"* / role=*"menuitemcheckbox"* and aria-checked=*"true"* / *"false"*.
+- Keyboard navigation: Enter / Space / ↓ opens the dropdown; ↑ / ↓ navigate options; Space toggles the focused option; Escape closes without further changes; Tab closes and moves focus forward.
+- When a value is added or removed (via chip ✕ or from dropdown), announce the change via aria-live=*"polite"*: *"Design added"* or *"Design removed"*.
 <!-- END:xui-mcp-instructions:multi-select -->
 
 ## Installation

package/native/index.js

@@ -1757,7 +1757,8 @@ var MultiSelect = (0, import_react10.forwardRef)(
                 style: {
                   maxHeight: searchable ? maxHeight - 60 : maxHeight,
                   overflowY: "auto",
-                  overflowX: optionListOverflowX
+                  overflowX: optionListOverflowX,
+                  scrollbarWidth: "none"
                 },
                 children: menuItems.length === 0 ? /* @__PURE__ */ (0, import_jsx_runtime13.jsx)(
                   Box,