@xsolla/xui-multi-select 0.149.1 → 0.151.0

package/README.md

@@ -1,169 +1,208 @@
-# Multi Select
+# MultiSelect
 
-A cross-platform React multi-select component that allows users to select multiple options from a dropdown list with checkboxes.
+A cross-platform multi-select control that lets users pick multiple options from a dropdown list.
 
 ## Installation
 
 ```bash
 npm install @xsolla/xui-multi-select
-# or
-yarn add @xsolla/xui-multi-select
 ```
 
-## Demo
-
-### Basic Multi Select
+## Imports
 
 ```tsx
-import * as React from 'react';
 import { MultiSelect } from '@xsolla/xui-multi-select';
-
-export default function BasicMultiSelect() {
-  const [selected, setSelected] = React.useState<string[]>([]);
-
-  return (
-    <MultiSelect
-      options={['React', 'Vue', 'Angular', 'Svelte']}
-      value={selected}
-      onChange={setSelected}
-      placeholder="Select frameworks"
-    />
-  );
-}
+import type {
+  MultiSelectProps,
+  MultiSelectOption,
+  MultiSelectValue,
+  MultiSelectVariant,
+  MultiSelectSize,
+  MultiSelectState,
+} from '@xsolla/xui-multi-select';
 ```
 
-### With Label
+## Quick start
 
 ```tsx
-import * as React from 'react';
-import { MultiSelect } from '@xsolla/xui-multi-select';
+const options = [
+  { label: 'React', value: 'react' },
+  { label: 'Vue', value: 'vue' },
+  { label: 'Angular', value: 'angular' },
+];
 
-export default function LabeledMultiSelect() {
-  const [selected, setSelected] = React.useState<string[]>(['Marketing']);
+const [selected, setSelected] = useState<MultiSelectValue>([]);
 
-  return (
-    <MultiSelect
-      label="Departments"
-      options={['Engineering', 'Marketing', 'Sales', 'Design', 'HR']}
-      value={selected}
-      onChange={setSelected}
-      placeholder="Select departments"
-    />
-  );
-}
+<MultiSelect
+  label="Frameworks"
+  options={options}
+  value={selected}
+  onChange={setSelected}
+  placeholder="Select frameworks"
+/>;
 ```
 
-### Multi Select Sizes
+### External panel (B2B grouped select)
+
+When the option list is rendered elsewhere (for example [`@xsolla/xui-b2b-group-select`](./b2b-group-select.md)), set **`dropdownMenu={false}`** so the control does not open the built-in list. Wire the same **`value`** / **`onChange`** to both components; use **`onTriggerPress`** to toggle your panel, **`menuOpen`** for chevron/open styling, and **`menuMinWidth`** (default **540**, aligned with `GROUP_SELECT_MIN_PANEL_WIDTH`) so the field matches the panel width.
 
 ```tsx
 import * as React from 'react';
 import { MultiSelect } from '@xsolla/xui-multi-select';
+import {
+  GroupSelect,
+  GROUP_SELECT_MIN_PANEL_WIDTH,
+  type GroupSelectGroup,
+} from '@xsolla/xui-b2b-group-select';
+
+const groups: GroupSelectGroup[] = [/* ... */];
+const flatOptions = groups.flatMap((g) =>
+  g.items.map((it) => ({ value: it.id, label: it.label }))
+);
 
-export default function MultiSelectSizes() {
-  const options = ['Option 1', 'Option 2', 'Option 3'];
+export default function GroupedFieldShell() {
+  const [value, setValue] = React.useState<string[]>([]);
+  const [open, setOpen] = React.useState(false);
 
   return (
-    <div style={{ display: 'flex', flexDirection: 'column', gap: 16 }}>
-      <MultiSelect options={options} size="xs" placeholder="Extra Small" />
-      <MultiSelect options={options} size="sm" placeholder="Small" />
-      <MultiSelect options={options} size="md" placeholder="Medium" />
-      <MultiSelect options={options} size="lg" placeholder="Large" />
-      <MultiSelect options={options} size="xl" placeholder="Extra Large" />
-    </div>
+    <>
+      <MultiSelect
+        options={flatOptions}
+        value={value}
+        onChange={(v) => setValue(v.map(String))}
+        placeholder="Select regions"
+        size="sm"
+        dropdownMenu={false}
+        menuOpen={open}
+        menuMinWidth={GROUP_SELECT_MIN_PANEL_WIDTH}
+        onTriggerPress={() => setOpen((o) => !o)}
+      />
+      {open && (
+        <GroupSelect groups={groups} value={value} onChange={setValue} />
+      )}
+    </>
   );
 }
 ```
 
-## Anatomy
+Add backdrop, click-outside, and Escape handling in your layout as needed (see Storybook).
 
-```jsx
-import { MultiSelect } from '@xsolla/xui-multi-select';
+## API Reference
 
-<MultiSelect
-  options={['a', 'b', 'c']}   // Available options
-  value={selectedArray}        // Currently selected values
-  onChange={setSelected}       // Selection change handler
-  placeholder="Select..."      // Placeholder text
-  label="Label"                // Label above select
-  size="md"                     // Size variant
-  disabled={false}             // Disabled state
-/>
+### `<MultiSelect>`
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `options` | `MultiSelectOption[]` | — | Available options. |
+| `value` | `MultiSelectValue` | `[]` | Selected values. |
+| `onChange` | `(values: MultiSelectValue) => void` | — | Fired when the selection changes. |
+| `placeholder` | `string` | `'Select'` | Placeholder shown when empty. |
+| `label` | `string` | — | Label rendered above the control. |
+| `size` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` | `'md'` | Control size. |
+| `state` | `'default' \| 'hover' \| 'focus' \| 'disable' \| 'error'` | — | Forced visual state. |
+| `disabled` | `boolean` | `false` | Disable the control. |
+| `errorMessage` | `string` | — | Error message; also marks the control invalid. |
+| `variant` | `'tag' \| 'text'` | `'tag'` | How selected options are displayed. |
+| `flexible` | `boolean` | `true` | When `true` the control grows with content; otherwise fixed-height. |
+| `removeTagsButtons` | `boolean` | `true` | Show a remove button on each tag. |
+| `extraClear` | `boolean` | `false` | Show a clear-all button. |
+| `maxHeight` | `number` | `300` | Maximum dropdown height in pixels. |
+| `iconLeft` | `ReactNode` | — | Icon rendered on the left of the control. |
+| `iconRight` | `ReactNode` | — | Icon on the right (overrides the default caret). |
+| `dropdownMenu` | `boolean` | `true` | When `false`, hides the built-in list and disables click-to-open; use with an external picker (e.g. `GroupSelect`) wired to the same `value` / `onChange`. |
+| `onTriggerPress` | `() => void` | — | When `dropdownMenu` is `false`: fired when the user activates the field. Typically toggles the external panel. |
+| `menuOpen` | `boolean` | `false` | When `dropdownMenu` is `false`: drives chevron direction and layering like the built-in open state. |
+| `menuMinWidth` | `number` | `540` | When `dropdownMenu` is `false`: field `min-width` in px (matches `GroupSelect`). Use `0` for no minimum. |
+
+Inherits `ThemeOverrideProps` (`themeMode`, `themeProductContext`).
+
+### Types
+
+```ts
+type MultiSelectValue = (string | number)[];
+type MultiSelectVariant = 'tag' | 'text';
+type MultiSelectSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+type MultiSelectState = 'default' | 'hover' | 'focus' | 'disable' | 'error';
+
+interface MultiSelectOption {
+  label: ReactNode;
+  value: string | number;
+  disabled?: boolean;
+}
 ```
 
 ## Examples
 
-### Form Integration
+### Sizes
 
 ```tsx
-import * as React from 'react';
-import { MultiSelect } from '@xsolla/xui-multi-select';
-import { Button } from '@xsolla/xui-button';
+const options = [
+  { label: 'React', value: 'react' },
+  { label: 'Vue', value: 'vue' },
+  { label: 'Angular', value: 'angular' },
+];
+
+<MultiSelect options={options} size="xs" placeholder="Extra small" />
+<MultiSelect options={options} size="sm" placeholder="Small" />
+<MultiSelect options={options} size="md" placeholder="Medium" />
+<MultiSelect options={options} size="lg" placeholder="Large" />
+<MultiSelect options={options} size="xl" placeholder="Extra large" />
+```
 
-export default function FormMultiSelect() {
-  const [skills, setSkills] = React.useState<string[]>([]);
+### Text variant with clear-all
 
-  const handleSubmit = () => {
-    console.log('Selected skills:', skills);
-  };
+```tsx
+const options = [
+  { label: 'React', value: 'react' },
+  { label: 'Vue', value: 'vue' },
+  { label: 'Angular', value: 'angular' },
+];
 
-  return (
-    <div style={{ display: 'flex', flexDirection: 'column', gap: 16, width: 300 }}>
-      <MultiSelect
-        label="Skills"
-        options={['JavaScript', 'TypeScript', 'Python', 'Go', 'Rust', 'Java']}
-        value={skills}
-        onChange={setSkills}
-        placeholder="Select your skills"
-      />
-      <Button onPress={handleSubmit}>Submit</Button>
-    </div>
-  );
-}
+const [selected, setSelected] = useState<MultiSelectValue>([]);
+
+<MultiSelect
+  options={options}
+  value={selected}
+  onChange={setSelected}
+  variant="text"
+  extraClear
+/>;
 ```
 
-### Disabled State
+### Error state
 
 ```tsx
-import * as React from 'react';
-import { MultiSelect } from '@xsolla/xui-multi-select';
+const options = [
+  { label: 'Design', value: 'design' },
+  { label: 'Engineering', value: 'engineering' },
+  { label: 'Product', value: 'product' },
+];
 
-export default function DisabledMultiSelect() {
-  return (
-    <MultiSelect
-      options={['Option 1', 'Option 2', 'Option 3']}
-      value={['Option 1']}
-      disabled
-      placeholder="Disabled select"
-    />
-  );
-}
-```
+const [skills, setSkills] = useState<MultiSelectValue>([]);
 
-## API Reference
+<MultiSelect
+  label="Skills"
+  options={options}
+  value={skills}
+  onChange={setSkills}
+  errorMessage="Please select at least one skill"
+/>;
+```
 
-### MultiSelect
+### Disabled
 
-**MultiSelect Props:**
+```tsx
+const options = [
+  { label: 'React', value: 'react' },
+  { label: 'Vue', value: 'vue' },
+  { label: 'Angular', value: 'angular' },
+];
 
-| Prop | Type | Default | Description |
-| :--- | :--- | :------ | :---------- |
-| options | `string[]` | - | **Required.** Available options. |
-| value | `string[]` | `[]` | Currently selected values. |
-| onChange | `(value: string[]) => void` | - | Selection change handler. |
-| placeholder | `string` | - | Placeholder when nothing selected. |
-| size | `"xs" \| "sm" \| "md" \| "lg" \| "xl"` | `"md"` | Component size. |
-| label | `string` | - | Label above select. |
-| disabled | `boolean` | `false` | Disabled state. |
-
-## Display Behavior
-
-- When no items selected: Shows placeholder
-- When items selected: Shows "N selected" text
-- Dropdown shows checkboxes for each option
-- Checked items are visually indicated
+<MultiSelect options={options} value={['react']} disabled />;
+```
 
 ## Accessibility
 
-- Uses checkbox pattern for selections
-- Dropdown is keyboard navigable
-- Selection state announced to screen readers
+- Selection is rendered as a checkbox list inside the dropdown.
+- The dropdown is keyboard navigable; selection state is announced to assistive technology.
+- An `errorMessage` marks the control as invalid for screen readers.

package/native/index.d.mts

@@ -83,6 +83,29 @@ interface MultiSelectProps extends ThemeOverrideProps {
      * @default 300
      */
     maxHeight?: number;
+    /**
+     * When false, the built-in options list and backdrop are not shown and the control
+     * does not open on click. Use with an external picker (e.g. grouped select) wired
+     * to the same `value` / `onChange`.
+     * @default true
+     */
+    dropdownMenu?: boolean;
+    /**
+     * When `dropdownMenu` is false: fired when the user activates the field (same gesture
+     * that would open the built-in list). Typically toggle an external panel.
+     */
+    onTriggerPress?: () => void;
+    /**
+     * When `dropdownMenu` is false: whether an external menu/panel is open — drives
+     * chevron direction and control layering like the built-in open state.
+     */
+    menuOpen?: boolean;
+    /**
+     * When `dropdownMenu` is false: `min-width` of the field in px so it aligns with
+     * a typical grouped panel (default **540**, same as `GroupSelect`). Use `0` for
+     * no minimum. Ignored when the built-in dropdown is enabled.
+     */
+    menuMinWidth?: number;
 }
 
 declare const MultiSelect: react.ForwardRefExoticComponent<MultiSelectProps & react.RefAttributes<HTMLDivElement>>;

package/native/index.d.ts

@@ -83,6 +83,29 @@ interface MultiSelectProps extends ThemeOverrideProps {
      * @default 300
      */
     maxHeight?: number;
+    /**
+     * When false, the built-in options list and backdrop are not shown and the control
+     * does not open on click. Use with an external picker (e.g. grouped select) wired
+     * to the same `value` / `onChange`.
+     * @default true
+     */
+    dropdownMenu?: boolean;
+    /**
+     * When `dropdownMenu` is false: fired when the user activates the field (same gesture
+     * that would open the built-in list). Typically toggle an external panel.
+     */
+    onTriggerPress?: () => void;
+    /**
+     * When `dropdownMenu` is false: whether an external menu/panel is open — drives
+     * chevron direction and control layering like the built-in open state.
+     */
+    menuOpen?: boolean;
+    /**
+     * When `dropdownMenu` is false: `min-width` of the field in px so it aligns with
+     * a typical grouped panel (default **540**, same as `GroupSelect`). Use `0` for
+     * no minimum. Ignored when the built-in dropdown is enabled.
+     */
+    menuMinWidth?: number;
 }
 
 declare const MultiSelect: react.ForwardRefExoticComponent<MultiSelectProps & react.RefAttributes<HTMLDivElement>>;