@xsolla/xui-toggle-button-group 0.149.1 → 0.151.0

package/README.md

@@ -1,21 +1,30 @@
-# @xsolla/xui-toggle-button-group
+# ToggleButtonGroup
 
-A control for picking one or several options from a linear set of closely related options. Can be used to filter or to sort elements.
+A control for picking one or several options from a linear set of closely related options; useful for filtering or sorting.
 
 ## Installation
 
 ```bash
 npm install @xsolla/xui-toggle-button-group
-# or
-yarn add @xsolla/xui-toggle-button-group
 ```
 
-## Usage
+## Imports
 
 ```tsx
 import { ToggleButtonGroup } from '@xsolla/xui-toggle-button-group';
+import type {
+  ToggleButtonGroupProps,
+  ToggleButtonGroupItem,
+  ToggleButtonGroupSize,
+  ToggleButtonGroupAppearance,
+} from '@xsolla/xui-toggle-button-group';
+```
+
+## Quick start
 
-// Single selection (default)
+`onChange` is typed `(value: string | string[]) => void` regardless of `multiple`, so single-select callers cast the value to `string`.
+
+```tsx
 const [value, setValue] = useState('item1');
 
 <ToggleButtonGroup
@@ -26,12 +35,59 @@ const [value, setValue] = useState('item1');
   ]}
   value={value}
   onChange={(v) => setValue(v as string)}
-/>
+/>;
+```
+
+## API Reference
+
+### `<ToggleButtonGroup>`
 
-// Multiple selection
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `items` | `ToggleButtonGroupItem[]` | — | Items to display. |
+| `value` | `string \| string[]` | — | Controlled value; string for single, array for multiple. |
+| `defaultValue` | `string \| string[]` | — | Initial value for uncontrolled mode. |
+| `onChange` | `(value: string \| string[]) => void` | — | Fired when the selection changes. |
+| `size` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` | `'md'` | Size variant. |
+| `appearance` | `'separated' \| 'united'` | `'separated'` | `separated` adds gaps; `united` connects items. |
+| `multiple` | `boolean` | `false` | Allow multiple selections. |
+| `fullWidth` | `boolean` | `false` | Stretch to fill the container. |
+| `id` | `string` | — | HTML id. |
+| `testID` | `string` | — | Test identifier. |
+| `aria-label` | `string` | — | Accessible label for the group. |
+| `aria-labelledby` | `string` | — | ID of an element that labels the group. |
+
+Inherits `ThemeOverrideProps` (`themeMode`, `themeProductContext`).
+
+### `ToggleButtonGroupItem`
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `id` | `string` | Unique identifier. |
+| `label` | `string` | Display text. |
+| `iconLeft` | `ReactNode` | Icon shown before the label. |
+| `iconRight` | `ReactNode` | Icon shown after the label. |
+| `disabled` | `boolean` | Disable the individual item. |
+| `aria-label` | `string` | Accessible label for the item. |
+
+### Types
+
+```ts
+type ToggleButtonGroupSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+type ToggleButtonGroupAppearance = 'separated' | 'united';
+```
+
+## Examples
+
+### Multiple selection
+
+`onChange` is still typed `(value: string | string[]) => void`, so multi-select callers cast the value to `string[]`.
+
+```tsx
 const [values, setValues] = useState(['item1', 'item3']);
 
 <ToggleButtonGroup
+  multiple
   items={[
     { id: 'item1', label: 'Option 1' },
     { id: 'item2', label: 'Option 2' },
@@ -39,40 +95,26 @@ const [values, setValues] = useState(['item1', 'item3']);
   ]}
   value={values}
   onChange={(v) => setValues(v as string[])}
-  multiple
 />
 ```
 
-## Props
+### United appearance, full width
 
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `items` | `ToggleButtonGroupItem[]` | required | Array of items to display |
-| `value` | `string \| string[]` | - | Controlled value(s) |
-| `defaultValue` | `string \| string[]` | - | Default value(s) for uncontrolled mode |
-| `onChange` | `(value: string \| string[]) => void` | - | Callback when selection changes |
-| `size` | `'xl' \| 'lg' \| 'md' \| 'sm'` | `'md'` | Size variant |
-| `appearance` | `'separated' \| 'united'` | `'separated'` | Visual style |
-| `multiple` | `boolean` | `false` | Allow multiple selections |
-| `id` | `string` | - | HTML id attribute |
-| `testID` | `string` | - | Test ID for testing frameworks |
-| `aria-label` | `string` | - | Accessible label for the group |
-| `aria-labelledby` | `string` | - | ID of element that labels this group |
-
-### ToggleButtonGroupItem
-
-| Prop | Type | Description |
-|------|------|-------------|
-| `id` | `string` | Unique identifier |
-| `label` | `string` | Display text |
-| `iconLeft` | `ReactNode` | Optional icon on the left |
-| `iconRight` | `ReactNode` | Optional icon on the right |
-| `disabled` | `boolean` | Whether the item is disabled |
-| `aria-label` | `string` | Accessible label for screen readers |
+```tsx
+<ToggleButtonGroup
+  appearance="united"
+  fullWidth
+  items={[
+    { id: 'day', label: 'Day' },
+    { id: 'week', label: 'Week' },
+    { id: 'month', label: 'Month' },
+  ]}
+  defaultValue="week"
+/>
+```
 
 ## Accessibility
 
-- Uses `role="radiogroup"` for single selection, `role="group"` for multiple
-- Arrow keys navigate between items
-- Enter/Space selects/toggles items
-- Proper `aria-checked` and `aria-disabled` states
+- `role="radiogroup"` for single selection, `role="group"` for multiple selection.
+- Arrow keys move between items; Enter/Space toggles selection.
+- `aria-checked` and `aria-disabled` reflect item state.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xsolla/xui-toggle-button-group",
-  "version": "0.149.1",
+  "version": "0.151.0",
   "main": "./web/index.js",
   "module": "./web/index.mjs",
   "types": "./web/index.d.ts",
@@ -10,8 +10,8 @@
     "build:native": "PLATFORM=native tsup"
   },
   "dependencies": {
-    "@xsolla/xui-core": "0.149.1",
-    "@xsolla/xui-primitives-core": "0.149.1"
+    "@xsolla/xui-core": "0.151.0",
+    "@xsolla/xui-primitives-core": "0.151.0"
   },
   "peerDependencies": {
     "react": ">=16.8.0",