@ceed/cds 1.28.0 → 1.29.0-next.1

package/dist/components/inputs/RadioList.md

@@ -1,241 +0,0 @@
-# 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.