@redis-ui/components 42.8.0 → 43.2.1

package/skills/redis-ui-components/references/BoxSelectionGroup.md

@@ -0,0 +1,487 @@
+# BoxSelectionGroup
+
+Single- and multi-select box groups with compound item builders for custom icons, state indicators, and interactive child content.
+
+## Import
+
+```tsx
+import {
+  BoxSelectionGroup,
+  MultiBoxSelectionGroup,
+  BoxSelectionGroupBox
+} from '@redislabsdev/redis-ui-components';
+```
+
+> Story examples also use `Checkbox`, `Switch`, and `Typography` from `@redislabsdev/redis-ui-components`, plus `RocketIcon` and `WandIcon` from `@redislabsdev/redis-ui-icons`.
+
+## Props
+
+### `BoxSelectionGroup`
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| boxes | `BoxSelectionGroupBox[]` | required | Boxes rendered by the single-select wrapper |
+| defaultValue | `string` | - | Initial selected box value for uncontrolled usage |
+| value | `string` | - | Controlled selected box value |
+| onChange | `(newValue: string) => void` | - | Called when the selected box changes |
+
+`BoxSelectionGroup` also forwards standard `<div>` attributes through the compose wrapper.
+
+### `MultiBoxSelectionGroup`
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| boxes | `BoxSelectionGroupBox[]` | required | Boxes rendered by the multi-select wrapper |
+| defaultValue | `string[]` | - | Initial selected box values for uncontrolled usage |
+| value | `string[]` | - | Controlled selected box values |
+| onChange | `(newValue: string[]) => void` | - | Called when the selected boxes changes |
+
+`MultiBoxSelectionGroup` also forwards standard `<div>` attributes through the compose wrapper.
+
+### `BoxSelectionGroupBox`
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| value | `TValue` | required | Unique box value |
+| label | `string` | - | Label rendered in the item |
+| icon | `IconType` | - | Optional icon rendered by `Item.Icon` |
+| disabled | `boolean` | - | Disables the box |
+| disabledMessage | `string` | - | Tooltip text shown when the box is disabled |
+
+`BoxSelectionGroupBox` also accepts custom fields via `Record<string, unknown>`, so story data can carry values such as `text`.
+
+### `BoxSelectionGroup.Compose` / `MultiBoxSelectionGroup.Compose`
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| defaultValue | `string` / `string[]` | - | Initial selected value(s) |
+| value | `string` / `string[]` | - | Controlled selected value(s) |
+| onChange | `(newValue: string) => void` / `(newValue: string[]) => void` | - | Called when selection changes |
+| children | `React.ReactNode` | required | Box items or custom composed content |
+
+Both compose wrappers also accept standard `<div>` attributes.
+
+### `BoxSelectionGroup.Item.Compose` / `MultiBoxSelectionGroup.Item.Compose`
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| box | `BoxSelectionGroupBox` | required | Box definition used to drive selection, disabled state, and tooltip content |
+| tooltipProps | `Omit<TooltipContentProps, 'content'>` | - | Additional tooltip props for the disabled tooltip |
+| children | `React.ReactNode` | required | Custom item content rendered inside the toggle root |
+
+Both compose item wrappers also accept standard `<button>` attributes.
+
+### `BoxSelectionGroup.Item.Icon` / `MultiBoxSelectionGroup.Item.Icon`
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| icon | `IconType` | - | Overrides the box icon; falls back to `box.icon` |
+
+The icon renderer also accepts the standard monochrome icon props from `@redislabsdev/redis-ui-icons`.
+
+### `BoxSelectionGroup.Item.StateIndicator` / `MultiBoxSelectionGroup.Item.StateIndicator`
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| children | `(props: { checked: boolean; tabIndex: number; disabled: boolean }) => React.ReactNode` | required | Render prop used to render the state indicator |
+| noninteractive | `boolean` | `false` | Returns the rendered indicator without the click-blocking wrapper |
+
+### `BoxSelectionGroup.Item.Interactive` / `MultiBoxSelectionGroup.Item.Interactive`
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| children | `React.ReactNode` | required | Wraps interactive children and stops click propagation |
+
+## Sub-components
+
+- `BoxSelectionGroup.Compose` - Single-select compose wrapper.
+- `BoxSelectionGroup.Item` - Default single-select item renderer.
+- `BoxSelectionGroup.Item.Compose` - Custom single-select item wrapper with tooltip support.
+- `BoxSelectionGroup.Item.Icon` - Renders the box icon and adapts color and size to the current state.
+- `BoxSelectionGroup.Item.StateIndicator` - Render-prop wrapper for checkbox-like or read-only state indicators.
+- `BoxSelectionGroup.Item.Interactive` - Wrapper for interactive children that should not toggle the box.
+- `BoxSelectionGroup.Item.useItemContext` - Access the current item context from custom item content.
+- `BoxSelectionGroup.Item.ItemContextConsumer` - React context consumer for the item state.
+- `MultiBoxSelectionGroup.Compose` - Multi-select compose wrapper.
+- `MultiBoxSelectionGroup.Item` - Default multi-select item renderer.
+- `MultiBoxSelectionGroup.Item.Compose` - Custom multi-select item wrapper with tooltip support.
+- `MultiBoxSelectionGroup.Item.Icon` - Renders the box icon and adapts color and size to the current state.
+- `MultiBoxSelectionGroup.Item.StateIndicator` - Render-prop wrapper for checkbox-like or read-only state indicators.
+- `MultiBoxSelectionGroup.Item.Interactive` - Wrapper for interactive children that should not toggle the box.
+- `MultiBoxSelectionGroup.Item.useItemContext` - Access the current item context from custom item content.
+- `MultiBoxSelectionGroup.Item.ItemContextConsumer` - React context consumer for the item state.
+
+## Examples
+
+### BoxSelectionGroup
+
+#### Playground
+
+```tsx
+import { BoxSelectionGroup } from '@redislabsdev/redis-ui-components';
+import { boxes } from './BoxSelectionGroup.data';
+
+<BoxSelectionGroup boxes={boxes} style={{ minHeight: 140 }} />
+```
+
+#### ControlledMode
+
+> Set `value` and `onChange` props to use controlled mode
+
+```tsx
+import { useState } from 'react';
+import { BoxSelectionGroup } from '@redislabsdev/redis-ui-components';
+import { boxes } from './BoxSelectionGroup.data';
+
+function Render() {
+  const [value, setValue] = useState(boxes[0].value);
+
+  const handleChange = (newValue: string) => {
+    setValue(newValue as (typeof boxes)[0]['value']);
+  };
+
+  return (
+    <>
+      <BoxSelectionGroup
+        boxes={boxes}
+        onChange={handleChange}
+        value={value}
+        style={{ minHeight: 140 }}
+      />
+      <div>Value: {JSON.stringify(value)}</div>
+    </>
+  );
+}
+```
+
+#### DisabledBoxes
+
+> Each Box item can be disabled by adding `disabled` parameter to Box parameters
+
+```tsx
+import { BoxSelectionGroup } from '@redislabsdev/redis-ui-components';
+import { disabledBoxes } from './BoxSelectionGroup.data';
+
+<BoxSelectionGroup
+  boxes={disabledBoxes}
+  defaultValue={disabledBoxes[0].value}
+  style={{ minHeight: 140 }}
+/>
+```
+
+#### ComposeItemsAndIndicators
+
+> The component and each box can be composed, using their own and custom elements.<br/>
+> Use `BoxSelectionGroup.Item.StateIndicator` to wrap box's state indicator component.<br/>
+> This wrapper also prevents unnecessary interaction with form components,
+> such as `Checkbox` or `Switch`, that can cause unexpected behavior or even crash when used inside a form.<br/>
+
+```tsx
+import { BoxSelectionGroup, Checkbox, Switch, Typography } from '@redislabsdev/redis-ui-components';
+import { boxes } from './BoxSelectionGroup.data';
+import { StoryGroupTitle, StoryHList } from '../../helpers/Story.style';
+
+<form>
+  <BoxSelectionGroup.Compose defaultValue={boxes[0].value} style={{ minHeight: 140 }}>
+    {boxes.map((box) => (
+      <BoxSelectionGroup.Item.Compose
+        key={box.value}
+        box={box}
+        style={{ padding: '2rem', display: 'flex', flexDirection: 'column', gap: '1rem' }}
+      >
+        <StoryHList>
+          <BoxSelectionGroup.Item.Icon color="neutral700" customSize="32px" />
+          <Typography.Heading size="L">{box.label}</Typography.Heading>
+          {box.text && <p>{box.text}</p>}
+        </StoryHList>
+        <StoryGroupTitle>Box State Indicators:</StoryGroupTitle>
+        <BoxSelectionGroup.Item.StateIndicator>
+          {(props) => <Checkbox {...props} label={box.label} />}
+        </BoxSelectionGroup.Item.StateIndicator>
+        <BoxSelectionGroup.Item.StateIndicator>
+          {(props) => <Switch {...props} />}
+        </BoxSelectionGroup.Item.StateIndicator>
+        <BoxSelectionGroup.Item.StateIndicator noninteractive>
+          {({ checked }) => (checked ? 'on' : 'off')}
+        </BoxSelectionGroup.Item.StateIndicator>
+      </BoxSelectionGroup.Item.Compose>
+    ))}
+  </BoxSelectionGroup.Compose>
+</form>
+```
+
+#### ComposeDisabledItems
+
+> All top level components will have opacity to appear disabled.<br/>
+> Wrapping interactive components that have own disabled state
+> with `BoxSelectionGroup.Item.StateIndicator` allows using the
+> own component's disable look instead of the box opacity.<br/>
+> If the wrapped state component doesn't have own disable look, you will need to add it manually.
+> If the state component is not interactive, you can set the `noninteractive` flag on the wrapper.
+
+```tsx
+import { BoxSelectionGroup, Checkbox, Switch, Typography } from '@redislabsdev/redis-ui-components';
+import { disabledBoxes } from './BoxSelectionGroup.data';
+import { StoryGroupTitle, StoryHList } from '../../helpers/Story.style';
+
+<BoxSelectionGroup.Compose defaultValue={disabledBoxes[0].value} style={{ minHeight: 140 }}>
+  {disabledBoxes.map((box) => (
+    <BoxSelectionGroup.Item.Compose
+      key={box.value}
+      box={box}
+      style={{ padding: '2rem', display: 'flex', flexDirection: 'column', gap: '1rem' }}
+    >
+      <StoryHList>
+        <BoxSelectionGroup.Item.Icon color="neutral700" customSize="32px" />
+        <Typography.Heading size="L">{box.label}</Typography.Heading>
+      </StoryHList>
+      <StoryGroupTitle>Box State Indicators:</StoryGroupTitle>
+      <BoxSelectionGroup.Item.StateIndicator>
+        {(props) => <Checkbox {...props} label={box.label} disabled={box.disabled} />}
+      </BoxSelectionGroup.Item.StateIndicator>
+      <BoxSelectionGroup.Item.StateIndicator>
+        {(props) => <Switch {...props} disabled={box.disabled} />}
+      </BoxSelectionGroup.Item.StateIndicator>
+      <BoxSelectionGroup.Item.StateIndicator noninteractive>
+        {({ checked }) => <span>{checked ? 'on' : 'off'}</span>}
+      </BoxSelectionGroup.Item.StateIndicator>
+    </BoxSelectionGroup.Item.Compose>
+  ))}
+</BoxSelectionGroup.Compose>
+```
+
+#### ComposeWithInteractiveElements
+
+> Composing boxes with custom interactive components can be made easier
+> by wrapping the components with `BoxSelectionGroup.Item.Interactive`.<br/>
+> If interactive component has its own disabled state, it will be used instead of the disabled box's opacity.<br/>
+> Wrapped components without their own disabled state require additional manual styling for box's disabled state.
+
+```tsx
+import { BoxSelectionGroup, Checkbox, Switch, Typography } from '@redislabsdev/redis-ui-components';
+import { disabledBoxes } from './BoxSelectionGroup.data';
+import { StoryGroupTitle, StoryHList } from '../../helpers/Story.style';
+
+<BoxSelectionGroup.Compose defaultValue={disabledBoxes[0].value} style={{ minHeight: 140 }}>
+  {disabledBoxes.map((box) => (
+    <BoxSelectionGroup.Item.Compose
+      key={box.value}
+      box={box}
+      style={{ padding: '2rem', display: 'flex', flexDirection: 'column', gap: '1rem' }}
+    >
+      <StoryHList>
+        <BoxSelectionGroup.Item.Icon color="neutral700" customSize="32px" />
+        <Typography.Heading size="L">{box.label}</Typography.Heading>
+      </StoryHList>
+      <StoryGroupTitle>Interactive Elements:</StoryGroupTitle>
+      <BoxSelectionGroup.Item.Interactive>
+        <Checkbox
+          defaultChecked={box.value === 'box2'}
+          label="custom checkbox"
+          disabled={box.disabled}
+        />
+      </BoxSelectionGroup.Item.Interactive>
+      <StoryHList>
+        custom switch
+        <BoxSelectionGroup.Item.Interactive>
+          <Switch defaultChecked={box.value === 'box2'} disabled={box.disabled} />
+        </BoxSelectionGroup.Item.Interactive>
+      </StoryHList>
+      <BoxSelectionGroup.Item.Interactive>
+        <Checkbox defaultChecked={box.value === 'box2'} disabled label="always disabled" />
+      </BoxSelectionGroup.Item.Interactive>
+    </BoxSelectionGroup.Item.Compose>
+  ))}
+</BoxSelectionGroup.Compose>
+```
+
+### MultiBoxSelectionGroup
+
+#### Playground
+
+```tsx
+import { MultiBoxSelectionGroup } from '@redislabsdev/redis-ui-components';
+import { boxes } from '../BoxSelectionGroup.data';
+
+<MultiBoxSelectionGroup boxes={boxes} style={{ minHeight: 140 }} />
+```
+
+#### ControlledMode
+
+> Set `value` and `onChange` props to use controlled mode
+
+```tsx
+import { useState } from 'react';
+import { MultiBoxSelectionGroup } from '@redislabsdev/redis-ui-components';
+import { boxes } from '../BoxSelectionGroup.data';
+
+function Render() {
+  const [value, onChange] = useState([boxes[0].value]);
+
+  return (
+    <>
+      <MultiBoxSelectionGroup
+        boxes={boxes}
+        onChange={onChange}
+        value={value}
+        style={{ minHeight: 140 }}
+      />
+      <div>Value: {JSON.stringify(value)}</div>
+    </>
+  );
+}
+```
+
+#### DisabledBoxes
+
+> Each Box item can be disabled by adding `disabled` parameter to Box parameters
+
+```tsx
+import { MultiBoxSelectionGroup } from '@redislabsdev/redis-ui-components';
+import { disabledBoxes } from '../BoxSelectionGroup.data';
+
+<MultiBoxSelectionGroup
+  boxes={disabledBoxes}
+  defaultValue={[disabledBoxes[0].value]}
+  style={{ minHeight: 140 }}
+/>
+```
+
+#### ComposeItemsAndIndicators
+
+> The component and each box can be composed, using their own and custom elements.<br/>
+> Use `MultiBoxSelectionGroup.Item.StateIndicator` to wrap box's state indicator component.<br/>
+> This wrapper also prevents unnecessary interaction with form components,
+> such as `Checkbox` or `Switch`, that can cause unexpected behavior or even crash when used inside a form.<br/>
+
+```tsx
+import { MultiBoxSelectionGroup, Checkbox, Switch, Typography } from '@redislabsdev/redis-ui-components';
+import { boxes } from '../BoxSelectionGroup.data';
+import { StoryGroupTitle, StoryHList } from '../../../helpers/Story.style';
+
+<form>
+  <MultiBoxSelectionGroup.Compose defaultValue={[boxes[0].value]} style={{ minHeight: 140 }}>
+    {boxes.map((box) => (
+      <MultiBoxSelectionGroup.Item.Compose
+        key={box.value}
+        box={box}
+        style={{ padding: '2rem', display: 'flex', flexDirection: 'column', gap: '1rem' }}
+      >
+        <StoryHList>
+          <MultiBoxSelectionGroup.Item.Icon color="neutral700" customSize="32px" />
+          <Typography.Heading size="L">{box.label}</Typography.Heading>
+          {box.text && <p>{box.text}</p>}
+        </StoryHList>
+        <StoryGroupTitle>Box State Indicators:</StoryGroupTitle>
+        <MultiBoxSelectionGroup.Item.StateIndicator>
+          {(props) => <Checkbox {...props} label={box.label} />}
+        </MultiBoxSelectionGroup.Item.StateIndicator>
+        <MultiBoxSelectionGroup.Item.StateIndicator>
+          {(props) => <Switch {...props} />}
+        </MultiBoxSelectionGroup.Item.StateIndicator>
+        <MultiBoxSelectionGroup.Item.StateIndicator noninteractive>
+          {({ checked }) => (checked ? 'on' : 'off')}
+        </MultiBoxSelectionGroup.Item.StateIndicator>
+      </MultiBoxSelectionGroup.Item.Compose>
+    ))}
+  </MultiBoxSelectionGroup.Compose>
+</form>
+```
+
+#### ComposeDisabledItems
+
+> All top level components will have opacity to appear disabled.<br/>
+> Wrapping interactive components that have own disabled state
+> with `MultiBoxSelectionGroup.Item.StateIndicator` allows using the
+> own component's disable look instead of the box opacity.<br/>
+> If the wrapped state component doesn't have own disable look, you will need to add it manually.
+> If the state component is not interactive, you can set the `noninteractive` flag on the wrapper.
+
+```tsx
+import { MultiBoxSelectionGroup, Checkbox, Switch, Typography } from '@redislabsdev/redis-ui-components';
+import { disabledBoxes } from '../BoxSelectionGroup.data';
+import { StoryGroupTitle, StoryHList } from '../../../helpers/Story.style';
+
+<MultiBoxSelectionGroup.Compose defaultValue={[disabledBoxes[0].value]} style={{ minHeight: 140 }}>
+  {disabledBoxes.map((box) => (
+    <MultiBoxSelectionGroup.Item.Compose
+      key={box.value}
+      box={box}
+      style={{ padding: '2rem', display: 'flex', flexDirection: 'column', gap: '1rem' }}
+    >
+      <StoryHList>
+        <MultiBoxSelectionGroup.Item.Icon color="neutral700" customSize="32px" />
+        <Typography.Heading size="L">{box.label}</Typography.Heading>
+      </StoryHList>
+      <StoryGroupTitle>Box State Indicators:</StoryGroupTitle>
+      <MultiBoxSelectionGroup.Item.StateIndicator>
+        {(props) => <Checkbox {...props} label={box.label} disabled={box.disabled} />}
+      </MultiBoxSelectionGroup.Item.StateIndicator>
+      <MultiBoxSelectionGroup.Item.StateIndicator>
+        {(props) => <Switch {...props} disabled={box.disabled} />}
+      </MultiBoxSelectionGroup.Item.StateIndicator>
+      <MultiBoxSelectionGroup.Item.StateIndicator noninteractive>
+        {({ checked }) => <span>{checked ? 'on' : 'off'}</span>}
+      </MultiBoxSelectionGroup.Item.StateIndicator>
+    </MultiBoxSelectionGroup.Item.Compose>
+  ))}
+</MultiBoxSelectionGroup.Compose>
+```
+
+#### ComposeWithInteractiveElements
+
+> Composing boxes with custom interactive components can be made easier
+> by wrapping the components with `MultiBoxSelectionGroup.Item.Interactive`.<br/>
+> If interactive component has its own disabled state, it will be used instead of the disabled box's opacity.<br/>
+> Wrapped components without their own disabled state require additional manual styling for box's disabled state.
+
+```tsx
+import { MultiBoxSelectionGroup, Checkbox, Switch, Typography } from '@redislabsdev/redis-ui-components';
+import { disabledBoxes } from '../BoxSelectionGroup.data';
+import { StoryGroupTitle, StoryHList } from '../../../helpers/Story.style';
+
+<MultiBoxSelectionGroup.Compose
+  defaultValue={[disabledBoxes[0].value]}
+  style={{ minHeight: 140 }}
+>
+  {disabledBoxes.map((box) => (
+    <MultiBoxSelectionGroup.Item.Compose
+      key={box.value}
+      box={box}
+      style={{ padding: '2rem', display: 'flex', flexDirection: 'column', gap: '1rem' }}
+    >
+      <StoryHList>
+        <MultiBoxSelectionGroup.Item.Icon color="neutral700" customSize="32px" />
+        <Typography.Heading size="L">{box.label}</Typography.Heading>
+      </StoryHList>
+      <StoryGroupTitle>Interactive Elements:</StoryGroupTitle>
+      <MultiBoxSelectionGroup.Item.Interactive>
+        <Checkbox
+          defaultChecked={box.value === 'box2'}
+          label="custom checkbox"
+          disabled={box.disabled}
+        />
+      </MultiBoxSelectionGroup.Item.Interactive>
+      <StoryHList>
+        custom switch
+        <MultiBoxSelectionGroup.Item.Interactive>
+          <Switch defaultChecked={box.value === 'box2'} disabled={box.disabled} />
+        </MultiBoxSelectionGroup.Item.Interactive>
+      </StoryHList>
+      <MultiBoxSelectionGroup.Item.Interactive>
+        <Checkbox defaultChecked={box.value === 'box2'} disabled label="always disabled" />
+      </MultiBoxSelectionGroup.Item.Interactive>
+    </MultiBoxSelectionGroup.Item.Compose>
+  ))}
+</MultiBoxSelectionGroup.Compose>
+```
+
+## Notes
+
+- `BoxSelectionGroup` is the single-select variant; `MultiBoxSelectionGroup` is the multi-select variant.
+- `BoxSelectionGroupBox` can carry custom fields because it extends `Record<string, unknown>`; the stories use `text` for composed content.
+- `ControlledMode` in both story files uses `value` and `onChange` to switch the components into controlled mode.
+- `DisabledBoxes` shows that individual boxes can be disabled by setting `disabled` on the box definition.
+- `BoxSelectionGroup.Item.StateIndicator` and `MultiBoxSelectionGroup.Item.StateIndicator` are behavior wrappers, not styling wrappers. Use `noninteractive` for non-interactive state content.
+- Wrapping interactive children with `BoxSelectionGroup.Item.Interactive` or `MultiBoxSelectionGroup.Item.Interactive` prevents selection clicks from bubbling into the box.
+- When a wrapped interactive child already has a disabled state, it can show its own disabled look instead of relying on the box opacity; otherwise add the disabled styling manually.