@ceed/ads 1.29.1 → 1.30.0-next.1

package/dist/components/inputs/PercentageInput.md

@@ -2,12 +2,6 @@
 
 ## Introduction
 
-PercentageInput is a specialized numeric input for entering percentage values. It automatically appends a `%` suffix, formats numbers with thousand separators, and supports min/max validation with built-in error states. Use it for any field where users need to enter a percentage, such as tax rates, discounts, or commission rates.
-
-> **Tip: Use built-in form props**
->
-> This component supports `label` and `helperText` props directly. Use these instead of wrapping with FormControl + FormLabel + FormHelperText for simpler forms.
-
 ```tsx
 <PercentageInput placeholder="Enter a percentage" />
 ```
@@ -28,29 +22,7 @@ PercentageInput is a specialized numeric input for entering percentage values. I
 | min             | —           | —       |
 | max             | —           | —       |
 
-## Usage
-
-```tsx
-import { PercentageInput } from '@ceed/ads';
-
-function MyComponent() {
-  const [rate, setRate] = React.useState(0);
-
-  return (
-    <PercentageInput
-      label="Tax Rate"
-      value={rate}
-      onChange={(e) => setRate(e.target.value)}
-      min={0}
-      max={100}
-    />
-  );
-}
-```
-
-## Sizes
-
-PercentageInput supports three sizes: `sm`, `md` (default), and `lg`.
+### Sizes
 
 ```tsx
 <Stack gap={2}>
@@ -60,80 +32,66 @@ PercentageInput supports three sizes: `sm`, `md` (default), and `lg`.
 </Stack>
 ```
 
-## Form Features
-
-### With Label
+### Disabled
 
 ```tsx
 <PercentageInput
   placeholder="Enter a percentage"
-  label="Percentage Input"
+  disabled
 />
 ```
 
-```tsx
-<PercentageInput label="Discount Rate" />
-```
-
-### With Helper Text
+### Error
 
 ```tsx
 <PercentageInput
   placeholder="Enter a percentage"
-  label="Percentage Input"
-  helperText="Please enter a percentage"
+  error
 />
 ```
 
-```tsx
-<PercentageInput label="Commission" helperText="Enter the commission percentage." />
-```
-
-### Error State
+### WithLabel
 
 ```tsx
 <PercentageInput
   placeholder="Enter a percentage"
-  error
+  label="Percentage Input"
 />
 ```
 
-### With Error Text
+### WithHelperText
 
 ```tsx
 <PercentageInput
   placeholder="Enter a percentage"
   label="Percentage Input"
   helperText="Please enter a percentage"
-  error
 />
 ```
 
-### Required
+### WithErrorText
 
 ```tsx
 <PercentageInput
   placeholder="Enter a percentage"
   label="Percentage Input"
   helperText="Please enter a percentage"
-  required
+  error
 />
 ```
 
-### Disabled
+### Required
 
 ```tsx
 <PercentageInput
   placeholder="Enter a percentage"
-  disabled
+  label="Percentage Input"
+  helperText="Please enter a percentage"
+  required
 />
 ```
 
-## Min / Max Validation
-
-Set `min` and `max` to enforce value boundaries. When the entered value is outside the range, the input automatically shows an error state.
-
-### Minimum Value
+### Min
 
 ```tsx
 <PercentageInput
@@ -145,12 +103,7 @@ Set `min` and `max` to enforce value boundaries. When the entered value is outsi
 />
 ```
 
-```tsx
-<PercentageInput min={10} defaultValue={5} />
-{/* Shows error because 5 < 10 */}
-```
-
-### Maximum Value
+### Max
 
 ```tsx
 <PercentageInput
@@ -161,125 +114,3 @@ Set `min` and `max` to enforce value boundaries. When the entered value is outsi
   defaultValue={5000}
 />
 ```
-
-```tsx
-<PercentageInput max={500} defaultValue={5000} />
-{/* Shows error because 5000 > 500 */}
-```
-
-## Decimal Scale
-
-Use `maxDecimalScale` to control the number of decimal places allowed. The default is `0` (integers only).
-
-```tsx
-// Integer only (default)
-<PercentageInput maxDecimalScale={0} />
-
-// Up to 2 decimal places: 12.34%
-<PercentageInput maxDecimalScale={2} />
-
-// Up to 3 decimal places: 12.345%
-<PercentageInput maxDecimalScale={3} />
-```
-
-## Minor Unit Mode
-
-When `useMinorUnit` is `true`, the component converts between display values and minor units based on `maxDecimalScale`. This is useful when your API stores percentages in integer form.
-
-```tsx
-// Display shows "20.12%", onChange returns 20120
-<PercentageInput useMinorUnit maxDecimalScale={3} value={20120} />
-
-// Display shows "20.12%", onChange returns 20.12
-<PercentageInput useMinorUnit={false} maxDecimalScale={2} value={20.12} />
-```
-
-## Common Use Cases
-
-### Discount Configuration
-
-```tsx
-function DiscountSetting() {
-  const [discount, setDiscount] = React.useState(0);
-
-  return (
-    <PercentageInput
-      label="Discount"
-      helperText="Enter 0-100%"
-      value={discount}
-      onChange={(e) => setDiscount(e.target.value)}
-      min={0}
-      max={100}
-    />
-  );
-}
-```
-
-### Tax Rate Settings
-
-```tsx
-function TaxRateForm() {
-  return (
-    <Stack gap={2}>
-      <PercentageInput
-        label="VAT Rate"
-        defaultValue={10}
-        maxDecimalScale={2}
-        min={0}
-        max={100}
-      />
-      <PercentageInput
-        label="Local Tax Rate"
-        defaultValue={2.5}
-        maxDecimalScale={2}
-        min={0}
-        max={50}
-      />
-    </Stack>
-  );
-}
-```
-
-### Progress / Completion Tracker
-
-```tsx
-function CompletionTracker({ value, onChange }) {
-  return (
-    <PercentageInput
-      label="Completion"
-      value={value}
-      onChange={(e) => onChange(e.target.value)}
-      min={0}
-      max={100}
-      helperText={value >= 100 ? 'Task is complete!' : `${100 - value}% remaining`}
-    />
-  );
-}
-```
-
-## Best Practices
-
-1. **Always set min and max**: Bound the valid range to prevent unreasonable values.
-
-```tsx
-// ✅ Clear bounds
-<PercentageInput min={0} max={100} />
-
-// ❌ Unbounded — user could enter 99999%
-<PercentageInput />
-```
-
-2. **Use `maxDecimalScale` appropriately**: Set it to `0` for whole percentages (discounts, progress), or `2`–`3` for precise rates (tax, interest).
-
-3. **Use `useMinorUnit` for API compatibility**: When your backend stores percentages as integers (e.g., 1050 for 10.50%), enable `useMinorUnit` with the appropriate `maxDecimalScale`.
-
-4. **Provide context via labels and helper text**: Clarify what the percentage represents and what range is valid.
-
-5. **Handle edge cases**: Consider what happens at boundary values (0%, 100%) and negative percentages if allowed.
-
-## Accessibility
-
-- The input has proper labeling via the `label` prop, linked with `aria-labelledby`.
-- Error states trigger `aria-invalid` with associated error messages via `aria-describedby`.
-- The `%` suffix is a visual decoration — ensure labels clarify that the field expects a percentage for screen readers.
-- Min/max validation errors are communicated visually; add descriptive `helperText` to make the valid range clear.

package/dist/components/inputs/RadioButton.md

@@ -2,9 +2,7 @@
 
 ## Introduction
 
-The Radio component provides a single-selection interface where users can choose exactly one option from a set of mutually exclusive choices. When one radio button is selected, any previously selected option in the same group is automatically deselected.
-
-Radio buttons are built on Joy UI's Radio and RadioGroup components, supporting multiple visual variants, sizes, colors, and advanced customization such as custom icons, overlay interactions, and icon-free designs. They are ideal for settings forms, preference panels, and any UI where a user must commit to a single option from a predefined list.
+Radio 컴포넌트는 사용자가 여러 옵션 중 하나만 선택할 수 있는 단일 선택 인터페이스를 제공합니다. 라디오 버튼은 그룹으로 사용되어야 하며, 하나가 선택되면 다른 옵션들은 자동으로 해제됩니다.
 
 ```tsx
 <Radio />
@@ -30,28 +28,35 @@ Radio buttons are built on Joy UI's Radio and RadioGroup components, supporting
 ## Usage
 
 ```tsx
-import { Radio, RadioGroup } from '@ceed/ads';
+import { Radio } from '@ceed/ads';
 
 function MyComponent() {
   const [selectedValue, setSelectedValue] = useState('option1');
 
   return (
-    <RadioGroup
-      name="example"
-      value={selectedValue}
-      onChange={(e) => setSelectedValue(e.target.value)}
-    >
-      <Radio value="option1" label="Option 1" />
-      <Radio value="option2" label="Option 2" />
-      <Radio value="option3" label="Option 3" />
-    </RadioGroup>
+    <div>
+      <Radio
+        name="example"
+        value="option1"
+        checked={selectedValue === 'option1'}
+        onChange={(e) => setSelectedValue(e.target.value)}
+        label="옵션 1"
+      />
+      <Radio
+        name="example"
+        value="option2"
+        checked={selectedValue === 'option2'}
+        onChange={(e) => setSelectedValue(e.target.value)}
+        label="옵션 2"
+      />
+    </div>
   );
 }
 ```
 
-## Variants
+## Examples
 
-Radio supports four visual variants: `outlined` (default), `soft`, `solid`, and `plain`. Choose a variant that fits the visual context of your form.
+### Variants
 
 ```tsx
 <FormControl>
@@ -65,9 +70,7 @@ Radio supports four visual variants: `outlined` (default), `soft`, `solid`, and
 </FormControl>
 ```
 
-## Sizes
-
-Three size presets are available: `sm`, `md` (default), and `lg`. Use smaller sizes for compact layouts and larger sizes for touch-friendly interfaces.
+### Sizes
 
 ```tsx
 <FormControl>
@@ -80,9 +83,7 @@ Three size presets are available: `sm`, `md` (default), and `lg`. Use smaller si
 </FormControl>
 ```
 
-## Colors
-
-Radio supports five semantic colors: `primary`, `neutral`, `danger`, `success`, and `warning`. Use semantic colors to convey meaning -- for example, `danger` for destructive options or `success` for confirmed selections.
+### Colors
 
 ```tsx
 <FormControl>
@@ -97,9 +98,9 @@ Radio supports five semantic colors: `primary`, `neutral`, `danger`, `success`,
 </FormControl>
 ```
 
-## Custom Icons
+### Custom Icons
 
-Replace the default radio indicator with custom icons using the `checkedIcon` prop. This is useful for card-style selectors where the selection state needs a distinctive visual treatment.
+아이콘을 커스터마이징하여 특별한 용도로 사용할 수 있습니다.
 
 ```tsx
 <RadioGroup aria-label="platform" defaultValue="Website" overlay name="platform" sx={{
@@ -141,9 +142,9 @@ Replace the default radio indicator with custom icons using the `checkedIcon` pr
 </RadioGroup>
 ```
 
-## No Icon
+### No Icon
 
-Use the `disableIcon` prop to hide the radio indicator entirely. This pattern is commonly used for card-style selectors where the entire card acts as the selectable target, and the selection state is conveyed through border or background styling.
+아이콘 없이 텍스트만으로 구성할 수 있습니다.
 
 ```tsx
 <Box sx={{
@@ -194,9 +195,9 @@ Storage
 </Box>
 ```
 
-## Segmented Controls
+### Segmented Controls
 
-Radio buttons can be styled as segmented controls for compact, inline option switching. This pattern works well for toolbar-style controls where horizontal space is limited.
+세그먼트 컨트롤 스타일로 사용할 수 있습니다.
 
 ```tsx
 <Box sx={{
@@ -237,9 +238,9 @@ Radio buttons can be styled as segmented controls for compact, inline option swi
 </Box>
 ```
 
-## Product Attributes
+### Product Attributes
 
-Radio groups can be customized to represent product attributes such as colors and sizes. Using `overlay`, `disableIcon`, and custom `Sheet` containers, you can create rich visual selectors.
+제품 속성 선택 등의 용도로 활용할 수 있습니다.
 
 ```tsx
 <Box sx={{
@@ -336,143 +337,14 @@ Size
 </Box>
 ```
 
-## Common Use Cases
-
-### Survey / Questionnaire Form
-
-```tsx
-function SurveyQuestion() {
-  const [answer, setAnswer] = useState('');
-
-  return (
-    <FormControl>
-      <FormLabel>How satisfied are you with our service?</FormLabel>
-      <RadioGroup
-        name="satisfaction"
-        value={answer}
-        onChange={(e) => setAnswer(e.target.value)}
-      >
-        <Radio value="very-satisfied" label="Very Satisfied" color="success" />
-        <Radio value="satisfied" label="Satisfied" />
-        <Radio value="neutral" label="Neutral" />
-        <Radio value="dissatisfied" label="Dissatisfied" color="warning" />
-        <Radio value="very-dissatisfied" label="Very Dissatisfied" color="danger" />
-      </RadioGroup>
-    </FormControl>
-  );
-}
-```
-
-### Payment Method Selection
-
-```tsx
-function PaymentMethodSelector() {
-  const [method, setMethod] = useState('credit-card');
-
-  return (
-    <FormControl>
-      <FormLabel>Payment Method</FormLabel>
-      <RadioGroup
-        name="payment"
-        value={method}
-        onChange={(e) => setMethod(e.target.value)}
-        sx={{ gap: 1.5 }}
-      >
-        {[
-          { value: 'credit-card', label: 'Credit Card' },
-          { value: 'bank-transfer', label: 'Bank Transfer' },
-          { value: 'paypal', label: 'PayPal' },
-        ].map((option) => (
-          <Sheet key={option.value} variant="outlined" sx={{ p: 2, borderRadius: 'md' }}>
-            <Radio
-              overlay
-              value={option.value}
-              label={option.label}
-              slotProps={{
-                action: ({ checked }) => ({
-                  sx: {
-                    ...(checked && {
-                      '--variant-borderWidth': '2px',
-                      borderColor: 'primary.500',
-                    }),
-                  },
-                }),
-              }}
-            />
-          </Sheet>
-        ))}
-      </RadioGroup>
-    </FormControl>
-  );
-}
-```
-
-### Shipping Speed Selection
-
-```tsx
-function ShippingOptions() {
-  const [shipping, setShipping] = useState('standard');
-
-  return (
-    <FormControl>
-      <FormLabel>Shipping Speed</FormLabel>
-      <RadioGroup
-        name="shipping"
-        value={shipping}
-        onChange={(e) => setShipping(e.target.value)}
-      >
-        <Radio value="standard" label="Standard (5-7 business days) - Free" />
-        <Radio value="express" label="Express (2-3 business days) - $9.99" />
-        <Radio value="overnight" label="Overnight (next day) - $24.99" />
-      </RadioGroup>
-    </FormControl>
-  );
-}
-```
-
 ## Best Practices
 
-1. **Always use RadioGroup**: Wrap Radio buttons in a `RadioGroup` to ensure proper grouping, keyboard navigation, and mutual exclusivity.
-
-```tsx
-// ✅ Wrapped in RadioGroup
-<RadioGroup name="options" value={value} onChange={handleChange}>
-  <Radio value="a" label="Option A" />
-  <Radio value="b" label="Option B" />
-</RadioGroup>
-
-// ❌ Standalone radios without a group
-<Radio name="options" value="a" label="Option A" />
-<Radio name="options" value="b" label="Option B" />
-```
-
-2. **Provide clear labels**: Every radio button must have a visible label or an `aria-label` to describe its purpose.
-
-```tsx
-// ✅ Descriptive label
-<Radio value="monthly" label="Monthly billing ($10/month)" />
-
-// ❌ Vague label
-<Radio value="monthly" label="Option 1" />
-```
-
-3. **Set a default selection**: Pre-select the most common or recommended option using `defaultValue` or a controlled `value` to reduce user effort.
-
-```tsx
-// ✅ Sensible default
-<RadioGroup defaultValue="standard" name="shipping">
-  <Radio value="standard" label="Standard Shipping" />
-  <Radio value="express" label="Express Shipping" />
-</RadioGroup>
-```
+1. **그룹 사용**: Radio 버튼들은 반드시 동일한 `name` 속성을 가진 그룹으로 사용해야 합니다.
 
-4. **Limit options to 2-7 items**: If more than 7 options exist, consider using a Select or Autocomplete component instead.
+2. **레이블 제공**: 접근성을 위해 항상 의미 있는 `label`을 제공하세요.
 
-5. **Use vertical layout by default**: Vertical lists are easier to scan. Only use horizontal (`orientation="horizontal"`) when options are very short (e.g., segmented controls).
+3. **초기값 설정**: 사용자 경험을 위해 적절한 초기값을 설정하는 것이 좋습니다.
 
-## Accessibility
+4. **적절한 간격**: 여러 라디오 버튼 간에는 충분한 간격을 두어 선택하기 쉽게 만드세요.
 
-- **Keyboard navigation**: Users can move between options using `Arrow Up` / `Arrow Down` (vertical) or `Arrow Left` / `Arrow Right` (horizontal). `Space` selects the focused option.
-- **ARIA roles**: `RadioGroup` renders with `role="radiogroup"`, and each `Radio` renders with `role="radio"` and `aria-checked` reflecting its state.
-- **Labeling**: Always connect a `FormLabel` to the `RadioGroup` via `aria-labelledby`, or provide an `aria-label` directly on the group so screen readers can announce the group purpose.
-- **Focus management**: When using `overlay` or `disableIcon` patterns, ensure the interactive area is clearly communicated -- the `overlay` prop extends the clickable area to the parent container, which is also reflected in focus styling.
+5. **상태 관리**: 제어 컴포넌트로 사용하여 상태를 명확히 관리하세요.