@ceed/cds 1.24.1-next.3 → 1.25.0

package/dist/components/inputs/RadioList.md

@@ -0,0 +1,241 @@
+# RadioList
+
+## Introduction
+
+RadioList is a convenience component that renders a group of radio buttons from a data array. It wraps RadioGroup and Radio internally, providing a simpler API for the common pattern of rendering a list of options. Pass an array of `{ label, value }` items and the component handles the rest.
+
+```tsx
+<RadioList
+  items={defaultItems}
+  defaultValue="option1"
+/>
+```
+
+| Field       | Description | Default |
+| ----------- | ----------- | ------- |
+| size        | —           | —       |
+| color       | —           | —       |
+| orientation | —           | —       |
+| disabled    | —           | —       |
+
+## Usage
+
+```tsx
+import { RadioList } from '@ceed/cds';
+
+function MyComponent() {
+  return (
+    <RadioList
+      items={[
+        { label: 'Small', value: 'sm' },
+        { label: 'Medium', value: 'md' },
+        { label: 'Large', value: 'lg' },
+      ]}
+      defaultValue="md"
+    />
+  );
+}
+```
+
+## Basic List
+
+A simple radio list with three options and a default selection.
+
+```tsx
+<RadioList items={[{
+  label: 'Small',
+  value: 'sm'
+}, {
+  label: 'Medium',
+  value: 'md'
+}, {
+  label: 'Large',
+  value: 'lg'
+}]} defaultValue="md" />
+```
+
+## Controlled
+
+Use `value` and `onChange` for controlled state management.
+
+```tsx
+<Stack gap={2}>
+  <Typography level="body-sm">Selected: {value}</Typography>
+  <RadioList items={defaultItems} value={value} onChange={e => setValue((e.target as HTMLInputElement).value)} />
+</Stack>
+```
+
+```tsx
+function ControlledExample() {
+  const [value, setValue] = React.useState('option1');
+  return (
+    <RadioList
+      items={items}
+      value={value}
+      onChange={(e) => setValue((e.target as HTMLInputElement).value)}
+    />
+  );
+}
+```
+
+## With Default Value
+
+Use `defaultValue` for uncontrolled usage with an initial selection.
+
+```tsx
+<RadioList items={defaultItems} defaultValue="option2" />
+```
+
+## Disabled
+
+Set `disabled` to prevent all radio buttons from being interacted with.
+
+```tsx
+<RadioList items={defaultItems} defaultValue="option1" disabled />
+```
+
+## Horizontal Layout
+
+Set `orientation="horizontal"` to display options in a row.
+
+```tsx
+<RadioList items={defaultItems} defaultValue="option1" orientation="horizontal" />
+```
+
+```tsx
+<RadioList
+  items={items}
+  defaultValue="option1"
+  orientation="horizontal"
+/>
+```
+
+## Sizes
+
+RadioList supports `sm`, `md` (default), and `lg` sizes. The size is applied to all radio buttons in the group.
+
+```tsx
+<Stack gap={3}>
+  <Box>
+    <Typography level="body-sm" sx={{
+      mb: 1
+    }}>Small</Typography>
+    <RadioList items={defaultItems} defaultValue="option1" size="sm" />
+  </Box>
+  <Box>
+    <Typography level="body-sm" sx={{
+      mb: 1
+    }}>Medium</Typography>
+    <RadioList items={defaultItems} defaultValue="option1" size="md" />
+  </Box>
+  <Box>
+    <Typography level="body-sm" sx={{
+      mb: 1
+    }}>Large</Typography>
+    <RadioList items={defaultItems} defaultValue="option1" size="lg" />
+  </Box>
+</Stack>
+```
+
+## Colors
+
+Five semantic colors are available via the `color` prop.
+
+```tsx
+<Stack gap={3}>
+  <RadioList items={defaultItems} defaultValue="option1" color="primary" />
+  <RadioList items={defaultItems} defaultValue="option1" color="neutral" />
+  <RadioList items={defaultItems} defaultValue="option1" color="danger" />
+  <RadioList items={defaultItems} defaultValue="option1" color="success" />
+  <RadioList items={defaultItems} defaultValue="option1" color="warning" />
+</Stack>
+```
+
+## Common Use Cases
+
+### Settings Selection
+
+```tsx
+function LanguageSetting() {
+  const [language, setLanguage] = React.useState('en');
+
+  return (
+    <FormControl>
+      <FormLabel>Language</FormLabel>
+      <RadioList
+        items={[
+          { label: 'English', value: 'en' },
+          { label: '한국어', value: 'ko' },
+          { label: '日本語', value: 'ja' },
+        ]}
+        value={language}
+        onChange={(e) => setLanguage((e.target as HTMLInputElement).value)}
+      />
+    </FormControl>
+  );
+}
+```
+
+### Survey Options
+
+```tsx
+function SatisfactionSurvey() {
+  return (
+    <FormControl>
+      <FormLabel>How satisfied are you?</FormLabel>
+      <RadioList
+        orientation="horizontal"
+        items={[
+          { label: 'Very Unsatisfied', value: '1' },
+          { label: 'Unsatisfied', value: '2' },
+          { label: 'Neutral', value: '3' },
+          { label: 'Satisfied', value: '4' },
+          { label: 'Very Satisfied', value: '5' },
+        ]}
+      />
+    </FormControl>
+  );
+}
+```
+
+### Dynamic Options from API
+
+```tsx
+function RoleSelector({ roles }: { roles: { id: string; name: string }[] }) {
+  return (
+    <RadioList
+      items={roles.map((role) => ({
+        label: role.name,
+        value: role.id,
+      }))}
+    />
+  );
+}
+```
+
+## Best Practices
+
+1. **Use for mutually exclusive choices**: RadioList is for selecting exactly one option from a set. For multiple selections, use Checkbox or FilterableCheckboxGroup.
+
+```tsx
+// ✅ Mutually exclusive — only one role allowed
+<RadioList items={roles} />
+
+// ❌ Multiple selections needed — use Checkbox instead
+<RadioList items={permissions} />
+```
+
+2. **Provide a default value**: Pre-select the most common or recommended option to reduce user effort.
+
+3. **Keep labels concise**: Radio button labels should be short and scannable. Use descriptions elsewhere if more context is needed.
+
+4. **Limit visible options**: For more than 7 options, consider using a Select dropdown instead to save space.
+
+5. **Use horizontal layout sparingly**: Horizontal orientation works well for 2–4 short options. For longer lists, vertical is more readable.
+
+## Accessibility
+
+- RadioList renders a `<RadioGroup>` with `role="radiogroup"`, and each option is a `<Radio>` with `role="radio"`.
+- Keyboard navigation: Arrow keys move between options, Space selects the focused option.
+- Wrap in a FormControl with FormLabel to provide an accessible group label.
+- The `disabled` prop sets `aria-disabled` on all radio buttons in the group.