@xsolla/xui-checkbox-tag-group 0.148.0 → 0.148.1

package/README.md

@@ -0,0 +1,211 @@
+# Checkbox Tag Group
+
+A cross-platform React component for selecting multiple options displayed as tag-style checkboxes. Supports controlled and uncontrolled modes with validation. Works on both React (web) and React Native.
+
+## Installation
+
+```bash
+npm install @xsolla/xui-checkbox-tag-group
+# or
+yarn add @xsolla/xui-checkbox-tag-group
+```
+
+## Demo
+
+### Basic Usage
+
+```tsx
+import * as React from 'react';
+import { CheckboxTagGroup } from '@xsolla/xui-checkbox-tag-group';
+
+const options = [
+  { label: 'Action', value: 'action' },
+  { label: 'RPG', value: 'rpg' },
+  { label: 'Strategy', value: 'strategy' },
+];
+
+export default function BasicCheckboxTagGroup() {
+  return (
+    <CheckboxTagGroup
+      options={options}
+      defaultValue={['action']}
+      aria-label="Game genres"
+    />
+  );
+}
+```
+
+### Controlled
+
+```tsx
+import * as React from 'react';
+import { CheckboxTagGroup } from '@xsolla/xui-checkbox-tag-group';
+
+const options = [
+  { label: 'Action', value: 'action' },
+  { label: 'RPG', value: 'rpg' },
+  { label: 'Strategy', value: 'strategy' },
+];
+
+export default function ControlledCheckboxTagGroup() {
+  const [values, setValues] = React.useState(['action']);
+
+  return (
+    <CheckboxTagGroup
+      options={options}
+      value={values}
+      onChange={setValues}
+      aria-label="Game genres"
+    />
+  );
+}
+```
+
+### Sizes
+
+```tsx
+import * as React from 'react';
+import { CheckboxTagGroup } from '@xsolla/xui-checkbox-tag-group';
+
+const options = [
+  { label: 'Item 1', value: 'item1' },
+  { label: 'Item 2', value: 'item2' },
+  { label: 'Item 3', value: 'item3' },
+];
+
+export default function CheckboxTagGroupSizes() {
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 24 }}>
+      <CheckboxTagGroup options={options} size="xl" defaultValue={['item1']} aria-label="XL tags" />
+      <CheckboxTagGroup options={options} size="lg" defaultValue={['item1']} aria-label="LG tags" />
+      <CheckboxTagGroup options={options} size="md" defaultValue={['item1']} aria-label="MD tags" />
+      <CheckboxTagGroup options={options} size="sm" defaultValue={['item1']} aria-label="SM tags" />
+    </div>
+  );
+}
+```
+
+## Anatomy
+
+Import the component and use it directly:
+
+```jsx
+import { CheckboxTagGroup } from '@xsolla/xui-checkbox-tag-group';
+
+<CheckboxTagGroup
+  options={options}               // Array of { label, value, disabled? }
+  value={selectedValues}          // Controlled selected values
+  defaultValue={['item1']}       // Default values (uncontrolled)
+  onChange={handleChange}         // Callback with new values array
+  size="md"                       // Size variant
+  disabled={false}                // Disable all options
+  errorMessage="Select at least one" // Error message
+  aria-label="Filter options"    // Accessible label
+/>
+```
+
+## Examples
+
+### With Error
+
+```tsx
+import * as React from 'react';
+import { CheckboxTagGroup } from '@xsolla/xui-checkbox-tag-group';
+
+const options = [
+  { label: 'Action', value: 'action' },
+  { label: 'RPG', value: 'rpg' },
+  { label: 'Strategy', value: 'strategy' },
+];
+
+export default function ErrorCheckboxTagGroup() {
+  return (
+    <CheckboxTagGroup
+      options={options}
+      errorMessage="Please select at least one genre"
+      aria-label="Game genres"
+    />
+  );
+}
+```
+
+### With Disabled Option
+
+```tsx
+import * as React from 'react';
+import { CheckboxTagGroup } from '@xsolla/xui-checkbox-tag-group';
+
+const options = [
+  { label: 'Action', value: 'action' },
+  { label: 'RPG (coming soon)', value: 'rpg', disabled: true },
+  { label: 'Strategy', value: 'strategy' },
+];
+
+export default function DisabledOptionCheckboxTagGroup() {
+  return (
+    <CheckboxTagGroup
+      options={options}
+      defaultValue={['action']}
+      aria-label="Game genres"
+    />
+  );
+}
+```
+
+### Fully Disabled
+
+```tsx
+import * as React from 'react';
+import { CheckboxTagGroup } from '@xsolla/xui-checkbox-tag-group';
+
+const options = [
+  { label: 'Action', value: 'action' },
+  { label: 'RPG', value: 'rpg' },
+  { label: 'Strategy', value: 'strategy' },
+];
+
+export default function DisabledCheckboxTagGroup() {
+  return (
+    <CheckboxTagGroup
+      options={options}
+      defaultValue={['action']}
+      disabled
+      aria-label="Game genres"
+    />
+  );
+}
+```
+
+## API Reference
+
+### CheckboxTagGroup
+
+**Props:**
+
+| Prop | Type | Default | Description |
+| :--- | :--- | :------ | :---------- |
+| options | `CheckboxTagGroupItem[]` | - | Array of options to display. |
+| value | `string[]` | - | Controlled selected values. |
+| defaultValue | `string[]` | `[]` | Default selected values (uncontrolled). |
+| onChange | `(values: string[]) => void` | - | Callback when selection changes. |
+| size | `"xl" \| "lg" \| "md" \| "sm"` | `"md"` | Size of the tag items. |
+| disabled | `boolean` | `false` | Disable all options. |
+| errorMessage | `string` | - | Error message displayed below the group. |
+| aria-label | `string` | - | Accessible label for the group. |
+
+### CheckboxTagGroupItem
+
+| Prop | Type | Default | Description |
+| :--- | :--- | :------ | :---------- |
+| label | `string` | - | Display text for the option. |
+| value | `string` | - | Value identifier for the option. |
+| disabled | `boolean` | `false` | Disable this specific option. |
+
+## Accessibility
+
+- Uses `role="group"` with `aria-label` on the container
+- Each option has `role="checkbox"` with `aria-checked`
+- `aria-disabled` set on disabled options
+- `aria-describedby` links to error message when present
+- Error messages use `role="alert"` for screen reader announcement
+- Keyboard navigation with Tab between options and Space/Enter to toggle

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xsolla/xui-checkbox-tag-group",
-  "version": "0.148.0",
+  "version": "0.148.1",
   "main": "./web/index.js",
   "module": "./web/index.mjs",
   "types": "./web/index.d.ts",
@@ -13,8 +13,8 @@
     "test:coverage": "vitest run --coverage"
   },
   "dependencies": {
-    "@xsolla/xui-core": "0.148.0",
-    "@xsolla/xui-primitives-core": "0.148.0"
+    "@xsolla/xui-core": "0.148.1",
+    "@xsolla/xui-primitives-core": "0.148.1"
   },
   "peerDependencies": {
     "react": ">=16.8.0",