@xsolla/xui-toggle-button-group 0.174.2 → 0.175.0

package/README.md

@@ -1,6 +1,46 @@
 # ToggleButtonGroup
 
 A control for picking one or several options from a linear set of closely related options; useful for filtering or sorting.
+<!-- BEGIN:xui-mcp-instructions:toggle-button-group -->
+A group of buttons where one or more options can be selected. Used to switch between modes, apply filters, or pick compact options — both as an immediate inline control and inside a form via Field Group. Not used for navigation.
+
+ToggleButtonGroup can be placed inside a Field Group as the content slot. This gives it a label, helper text, and validation message — the same as any other form control. Use this pattern when the selection is part of a form and needs a label or needs to align visually with adjacent fields.
+
+Checkbox vs ToggleButtonGroup: 
+- Decision guide
+
+### When to use
+- When a user needs to select one or more options from a small, fixed set (2–8+ items)
+- To switch between views, display modes, or content filters
+- When options are equal in weight and benefit from a persistent, visible selection state
+- When a compact button-style control fits better than a list of checkboxes
+- Inside a form via Field Group — as a styled alternative to radio buttons or checkboxes
+
+### When not to use
+- When the choice triggers a navigation change — use Tabs
+- For a single binary on/off toggle — use a Switch
+- When there are more options than fit comfortably in a row
+- When options are numerous, have descriptions, or need a long vertical list — use a Context-menu with Checkboxes
+
+### Content guidelines
+- Keep item labels short — one word or a brief noun phrase (e.g. Day, Week, Month).
+- Use parallel structure across all items in the same group (all nouns, or all verbs).
+- Icons should reinforce the label meaning; avoid using icons that require the label to be understood.
+- If using icon-only items (no label), ensure all icons are recognizable and add a tooltip.
+
+### Behaviour guidelines
+- Clicking an item toggles it between Active and Default.
+- The group supports both single-select (one active at a time) and multi-select (multiple active simultaneously) — the selection model is defined at the product level, not by the component itself.
+- A Disable item cannot be clicked and cannot receive Active state.
+- The group does not close or collapse on selection — it remains fully visible.
+
+### Accessibility
+- When used as a single-select control, the group should use role=*"radiogroup"* and each item role=*"radio"* with aria-checked.
+- When used as a multi-select control, each item should use role=*"checkbox"* with aria-checked.
+- Apply aria-disabled=*"true"* to disabled items.
+- Provide an accessible label on the group via aria-label or aria-labelledby.
+- Focus should be manageable via arrow keys within the group (roving tabindex pattern).
+<!-- END:xui-mcp-instructions:toggle-button-group -->
 
 ## Installation
 

package/package.json

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