@ceed/ads 1.23.3 → 1.23.5

package/dist/components/inputs/PercentageInput.md

@@ -2,10 +2,11 @@
 
 ## Introduction
 
-> 💡 **Form 구성 시 내장 prop 사용을 권장합니다**
+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**
 >
-> 이 컴포넌트는 `label`, `helperText` 등의 Form 요소를 자체적으로 지원합니다.
-> Form을 구성할 때 Typography로 별도의 label이나 helperText를 만드는 대신, 컴포넌트의 내장 prop을 사용하세요.
+> 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" />
@@ -27,7 +28,29 @@
 | min             | —           | —       |
 | max             | —           | —       |
 
-### Sizes
+## 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`.
 
 ```tsx
 <Stack gap={2}>
@@ -37,44 +60,45 @@
 </Stack>
 ```
 
-### Disabled
+## Form Features
+
+### With Label
 
 ```tsx
 <PercentageInput
   placeholder="Enter a percentage"
-  disabled
+  label="Percentage Input"
 />
 ```
 
-### Error
-
 ```tsx
-<PercentageInput
-  placeholder="Enter a percentage"
-  error
-/>
+<PercentageInput label="Discount Rate" />
 ```
 
-### WithLabel
+### With Helper Text
 
 ```tsx
 <PercentageInput
   placeholder="Enter a percentage"
   label="Percentage Input"
+  helperText="Please enter a percentage"
 />
 ```
 
-### WithHelperText
+```tsx
+<PercentageInput label="Commission" helperText="Enter the commission percentage." />
+```
+
+### Error State
 
 ```tsx
 <PercentageInput
   placeholder="Enter a percentage"
-  label="Percentage Input"
-  helperText="Please enter a percentage"
+  error
 />
 ```
 
-### WithErrorText
+### With Error Text
 
 ```tsx
 <PercentageInput
@@ -96,7 +120,20 @@
 />
 ```
 
-### Min
+### Disabled
+
+```tsx
+<PercentageInput
+  placeholder="Enter a percentage"
+  disabled
+/>
+```
+
+## 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
 
 ```tsx
 <PercentageInput
@@ -108,7 +145,12 @@
 />
 ```
 
-### Max
+```tsx
+<PercentageInput min={10} defaultValue={5} />
+{/* Shows error because 5 < 10 */}
+```
+
+### Maximum Value
 
 ```tsx
 <PercentageInput
@@ -119,3 +161,125 @@
   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,7 +2,9 @@
 
 ## Introduction
 
-Radio 컴포넌트는 사용자가 여러 옵션 중 하나만 선택할 수 있는 단일 선택 인터페이스를 제공합니다. 라디오 버튼은 그룹으로 사용되어야 하며, 하나가 선택되면 다른 옵션들은 자동으로 해제됩니다.
+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.
 
 ```tsx
 <Radio />
@@ -28,35 +30,28 @@ Radio 컴포넌트는 사용자가 여러 옵션 중 하나만 선택할 수 있
 ## Usage
 
 ```tsx
-import { Radio } from '@ceed/ads';
+import { Radio, RadioGroup } from '@ceed/ads';
 
 function MyComponent() {
   const [selectedValue, setSelectedValue] = useState('option1');
 
   return (
-    <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>
+    <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>
   );
 }
 ```
 
-## Examples
+## Variants
 
-### Variants
+Radio supports four visual variants: `outlined` (default), `soft`, `solid`, and `plain`. Choose a variant that fits the visual context of your form.
 
 ```tsx
 <FormControl>
@@ -70,7 +65,9 @@ function MyComponent() {
 </FormControl>
 ```
 
-### Sizes
+## Sizes
+
+Three size presets are available: `sm`, `md` (default), and `lg`. Use smaller sizes for compact layouts and larger sizes for touch-friendly interfaces.
 
 ```tsx
 <FormControl>
@@ -83,7 +80,9 @@ function MyComponent() {
 </FormControl>
 ```
 
-### Colors
+## 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.
 
 ```tsx
 <FormControl>
@@ -98,9 +97,9 @@ function MyComponent() {
 </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={{
@@ -142,9 +141,9 @@ function MyComponent() {
 </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={{
@@ -195,9 +194,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={{
@@ -238,9 +237,9 @@ Storage
 </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={{
@@ -337,14 +336,143 @@ 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. **그룹 사용**: Radio 버튼들은 반드시 동일한 `name` 속성을 가진 그룹으로 사용해야 합니다.
+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>
+```
 
-2. **레이블 제공**: 접근성을 위해 항상 의미 있는 `label`을 제공하세요.
+4. **Limit options to 2-7 items**: If more than 7 options exist, consider using a Select or Autocomplete component instead.
 
-3. **초기값 설정**: 사용자 경험을 위해 적절한 초기값을 설정하는 것이 좋습니다.
+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).
 
-4. **적절한 간격**: 여러 라디오 버튼 간에는 충분한 간격을 두어 선택하기 쉽게 만드세요.
+## Accessibility
 
-5. **상태 관리**: 제어 컴포넌트로 사용하여 상태를 명확히 관리하세요.
+- **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.