@ceed/ads 1.29.0 → 1.30.0-next.1

package/dist/components/inputs/FormControl.md

@@ -1,361 +0,0 @@
-# FormControl
-
-## Introduction
-
-FormControl is a wrapper component that provides context to form elements such as Input, Textarea, Select, and more. It manages shared states like `error`, `disabled`, `required`, and `size`, passing them down to its children automatically. Use it with FormLabel and FormHelperText to build accessible, consistent form fields.
-
-```tsx
-<FormControl {...args}>
-  <FormLabel>Label</FormLabel>
-  <Input placeholder="Enter text…" />
-  <FormHelperText>This is helper text.</FormHelperText>
-</FormControl>
-```
-
-| Field       | Description | Default |
-| ----------- | ----------- | ------- |
-| size        | —           | —       |
-| error       | —           | —       |
-| disabled    | —           | —       |
-| required    | —           | —       |
-| orientation | —           | —       |
-
-## Usage
-
-```tsx
-import { FormControl, FormLabel, FormHelperText, Input } from '@ceed/ads';
-
-function MyForm() {
-  return (
-    <FormControl>
-      <FormLabel>Username</FormLabel>
-      <Input placeholder="Enter username" />
-      <FormHelperText>Choose a unique username.</FormHelperText>
-    </FormControl>
-  );
-}
-```
-
-## With Input
-
-The most common pattern — wrapping an Input with a label and helper text.
-
-```tsx
-<FormControl>
-  <FormLabel>Username</FormLabel>
-  <Input placeholder="Enter username" />
-  <FormHelperText>Choose a unique username.</FormHelperText>
-</FormControl>
-```
-
-## With Textarea
-
-FormControl works equally well with Textarea components.
-
-```tsx
-<FormControl>
-  <FormLabel>Description</FormLabel>
-  <Textarea placeholder="Enter description…" minRows={3} />
-  <FormHelperText>Provide a detailed description.</FormHelperText>
-</FormControl>
-```
-
-## With Select
-
-Use FormControl with Select for dropdown fields.
-
-```tsx
-<FormControl>
-  <FormLabel>Role</FormLabel>
-  <Select placeholder="Select a role" options={roleOptions} />
-  <FormHelperText>Select the user role.</FormHelperText>
-</FormControl>
-```
-
-## Error State
-
-Set `error` on FormControl to propagate the error state to all child components. FormHelperText automatically changes color to indicate the error.
-
-```tsx
-<FormControl error>
-  <FormLabel>Email</FormLabel>
-  <Input placeholder="email@example.com" defaultValue="invalid-email" />
-  <FormHelperText>Please enter a valid email address.</FormHelperText>
-</FormControl>
-```
-
-```tsx
-<FormControl error>
-  <FormLabel>Email</FormLabel>
-  <Input placeholder="email@example.com" value="invalid-email" />
-  <FormHelperText>Please enter a valid email address.</FormHelperText>
-</FormControl>
-```
-
-## Disabled State
-
-Set `disabled` to disable all child form elements at once.
-
-```tsx
-<FormControl disabled>
-  <FormLabel>Name</FormLabel>
-  <Input placeholder="Enter name" defaultValue="John Doe" />
-  <FormHelperText>This field is disabled.</FormHelperText>
-</FormControl>
-```
-
-```tsx
-<FormControl disabled>
-  <FormLabel>Name</FormLabel>
-  <Input placeholder="Enter name" value="John Doe" />
-  <FormHelperText>This field is disabled.</FormHelperText>
-</FormControl>
-```
-
-## Required Field
-
-Set `required` to add an asterisk (\*) to the label and mark the field as required.
-
-```tsx
-<FormControl required>
-  <FormLabel>Full Name</FormLabel>
-  <Input placeholder="Enter your full name" />
-  <FormHelperText>This field is required.</FormHelperText>
-</FormControl>
-```
-
-```tsx
-<FormControl required>
-  <FormLabel>Full Name</FormLabel>
-  <Input placeholder="Enter your full name" />
-</FormControl>
-```
-
-## Sizes
-
-FormControl supports `sm`, `md`, and `lg` sizes. The size is inherited by child components.
-
-```tsx
-<Stack gap={3}>
-  <FormControl size="sm">
-    <FormLabel>Small</FormLabel>
-    <Input placeholder="Small input" />
-  </FormControl>
-  <FormControl size="md">
-    <FormLabel>Medium</FormLabel>
-    <Input placeholder="Medium input" />
-  </FormControl>
-  <FormControl size="lg">
-    <FormLabel>Large</FormLabel>
-    <Input placeholder="Large input" />
-  </FormControl>
-</Stack>
-```
-
-## Horizontal Layout
-
-Use `orientation="horizontal"` for inline form controls, such as Switch or Checkbox toggles.
-
-```tsx
-<FormControl orientation="horizontal" sx={{
-  gap: 2
-}}>
-<FormLabel>Subscribe</FormLabel>
-<Switch />
-</FormControl>
-```
-
-```tsx
-<FormControl orientation="horizontal" sx={{ gap: 2 }}>
-  <FormLabel>Subscribe</FormLabel>
-  <Switch />
-</FormControl>
-```
-
-## Form Example
-
-A complete form demonstrating FormControl with multiple input types.
-
-```tsx
-<Stack gap={2} sx={{
-  maxWidth: 400
-}}>
-<FormControl required>
-  <FormLabel>Name</FormLabel>
-  <Input placeholder="Enter your name" />
-</FormControl>
-<FormControl required>
-  <FormLabel>Email</FormLabel>
-  <Input type="email" placeholder="email@example.com" />
-  <FormHelperText>We will never share your email.</FormHelperText>
-</FormControl>
-<FormControl>
-  <FormLabel>Role</FormLabel>
-  <Select placeholder="Select a role" options={roleOptions} />
-</FormControl>
-<FormControl>
-  <FormLabel>Bio</FormLabel>
-  <Textarea placeholder="Tell us about yourself…" minRows={3} />
-  <FormHelperText>Maximum 500 characters.</FormHelperText>
-</FormControl>
-</Stack>
-```
-
-## FormLabel
-
-FormLabel renders a `<label>` element associated with its sibling input. It automatically displays an asterisk when the parent FormControl has `required` set.
-
-```tsx
-<FormControl required>
-  <FormLabel>Email</FormLabel>
-  <Input />
-</FormControl>
-```
-
-## FormHelperText
-
-FormHelperText provides supplementary guidance below the input. It automatically switches to the error color when the parent FormControl has `error` set.
-
-```tsx
-<FormControl error>
-  <FormLabel>Password</FormLabel>
-  <Input type="password" />
-  <FormHelperText>Password must be at least 8 characters.</FormHelperText>
-</FormControl>
-```
-
-## Common Use Cases
-
-### Registration Form
-
-```tsx
-function RegistrationForm() {
-  const [errors, setErrors] = React.useState({});
-
-  return (
-    <Stack gap={2} component="form">
-      <FormControl required error={!!errors.name}>
-        <FormLabel>Name</FormLabel>
-        <Input placeholder="Enter your name" />
-        {errors.name && <FormHelperText>{errors.name}</FormHelperText>}
-      </FormControl>
-
-      <FormControl required error={!!errors.email}>
-        <FormLabel>Email</FormLabel>
-        <Input type="email" placeholder="email@example.com" />
-        {errors.email && <FormHelperText>{errors.email}</FormHelperText>}
-      </FormControl>
-
-      <FormControl required error={!!errors.password}>
-        <FormLabel>Password</FormLabel>
-        <Input type="password" placeholder="Enter password" />
-        <FormHelperText>{errors.password || 'Must be at least 8 characters.'}</FormHelperText>
-      </FormControl>
-
-      <FormControl orientation="horizontal">
-        <Checkbox label="I agree to the terms and conditions" />
-      </FormControl>
-    </Stack>
-  );
-}
-```
-
-### Settings Form with Mixed Controls
-
-```tsx
-function SettingsForm() {
-  return (
-    <Stack gap={2}>
-      <FormControl orientation="horizontal" sx={{ justifyContent: 'space-between' }}>
-        <FormLabel>Email notifications</FormLabel>
-        <Switch />
-      </FormControl>
-
-      <FormControl>
-        <FormLabel>Language</FormLabel>
-        <Select
-          defaultValue="en"
-          options={[
-            { value: 'en', label: 'English' },
-            { value: 'ko', label: 'Korean' },
-          ]}
-        />
-      </FormControl>
-
-      <FormControl>
-        <FormLabel>Notes</FormLabel>
-        <Textarea minRows={3} placeholder="Additional notes…" />
-        <FormHelperText>Optional</FormHelperText>
-      </FormControl>
-    </Stack>
-  );
-}
-```
-
-> **Tip: Use built-in form props instead**
->
-> Input, Select, Textarea, DatePicker 등 Input 계열 컴포넌트는 `label`, `helperText` prop을 자체적으로 지원합니다.
-> 간단한 form 필드에는 각 컴포넌트의 내장 prop을 사용하는 것이 더 간결합니다.
->
-> ```tsx
-> // ✅ Simpler: built-in props
-> <Input label="Username" helperText="Choose a unique username." />
->
-> // ⬆️ Equivalent to:
-> <FormControl>
->   <FormLabel>Username</FormLabel>
->   <Input placeholder="Enter username" />
->   <FormHelperText>Choose a unique username.</FormHelperText>
-> </FormControl>
-> ```
->
-> FormControl is most useful when you need to compose multiple elements, share state across siblings, or use horizontal orientation.
-
-## Best Practices
-
-1. **Always pair with FormLabel**: Every form field should have a label for accessibility. Use FormLabel inside FormControl.
-
-```tsx
-// ✅ Accessible — label is associated with input
-<FormControl>
-  <FormLabel>Email</FormLabel>
-  <Input />
-</FormControl>
-
-// ❌ No label — screen readers cannot identify the input
-<FormControl>
-  <Input placeholder="Email" />
-</FormControl>
-```
-
-2. **Use `error` prop on FormControl, not children**: Set error state on FormControl so all children react consistently.
-
-```tsx
-// ✅ Error propagated from FormControl
-<FormControl error>
-  <FormLabel>Email</FormLabel>
-  <Input />
-  <FormHelperText>Invalid email</FormHelperText>
-</FormControl>
-
-// ❌ Inconsistent — only Input shows error
-<FormControl>
-  <FormLabel>Email</FormLabel>
-  <Input error />
-  <FormHelperText>Invalid email</FormHelperText>
-</FormControl>
-```
-
-3. **Use consistent sizing**: Set `size` on FormControl to ensure all children (label, input, helper text) are proportionally sized.
-
-4. **Mark required fields**: Use the `required` prop to automatically add visual indicators and `aria-required` attributes.
-
-5. **Provide helpful error messages**: When using the error state, always include a FormHelperText explaining what went wrong and how to fix it.
-
-## Accessibility
-
-- FormControl automatically associates FormLabel with the input using `htmlFor` and `id`.
-- The `required` prop adds `aria-required="true"` to the input and an asterisk to the label.
-- The `error` prop adds `aria-invalid="true"` to the input.
-- FormHelperText is linked to the input via `aria-describedby` so screen readers announce it.
-- Use the `disabled` prop on FormControl to set `aria-disabled` on child elements.

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/ads';
-
-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.