@ceed/ads 1.25.1-next.3 → 1.27.0

package/dist/components/inputs/CurrencyInput.md

@@ -2,6 +2,12 @@
 
 ## Introduction
 
+CurrencyInput is a specialized numeric input for entering monetary values. It automatically formats numbers with the appropriate currency symbol, thousand separators, and decimal places based on the selected currency (USD or KRW). It supports features like maximum value validation, minor unit conversion, and controlled/uncontrolled modes.
+
+> **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
 <CurrencyInput
   name="currency-input"
@@ -25,8 +31,42 @@
 | useMinorUnit | —           | —                |
 | onChange     | —           | —                |
 
+## Usage
+
+```tsx
+import { CurrencyInput } from '@ceed/ads';
+
+function MyComponent() {
+  const [amount, setAmount] = React.useState(0);
+
+  return (
+    <CurrencyInput
+      label="Price"
+      currency="USD"
+      value={amount}
+      onChange={(e) => setAmount(e.target.value)}
+    />
+  );
+}
+```
+
+## Currency Formats
+
+### USD (Default)
+
+US Dollar format with `$` symbol, comma thousand separators, and 2 decimal places.
+
+```tsx
+<CurrencyInput
+  name="currency-input"
+  defaultValue={1000}
+/>
+```
+
 ### KRW
 
+Korean Won format with `₩` symbol, comma thousand separators, and no decimal places.
+
 ```tsx
 <CurrencyInput
   name="currency-input"
@@ -35,7 +75,13 @@
 />
 ```
 
-### Sizes
+```tsx
+<CurrencyInput currency="KRW" value={50000} />
+```
+
+## Sizes
+
+CurrencyInput supports three sizes: `sm`, `md` (default), and `lg`.
 
 ```tsx
 <Stack gap={2}>
@@ -45,7 +91,9 @@
 </Stack>
 ```
 
-### WithLabel
+## Form Features
+
+### With Label
 
 ```tsx
 <CurrencyInput
@@ -55,7 +103,11 @@
 />
 ```
 
-### WithHelperText
+```tsx
+<CurrencyInput label="Total Amount" />
+```
+
+### With Helper Text
 
 ```tsx
 <CurrencyInput
@@ -66,7 +118,11 @@
 />
 ```
 
-### Error
+```tsx
+<CurrencyInput label="Price" helperText="Enter the item price in USD." />
+```
+
+### Error State
 
 ```tsx
 <CurrencyInput
@@ -78,7 +134,13 @@
 />
 ```
 
-### PriceLimitError
+```tsx
+<CurrencyInput label="Amount" error helperText="Amount is required." />
+```
+
+## Price Limit
+
+Set the `max` prop to enforce a maximum value. When the entered value exceeds the limit, the input automatically displays an error state with a formatted limit message.
 
 ```tsx
 <CurrencyInput
@@ -89,3 +151,119 @@
   max={1000000}
 />
 ```
+
+```tsx
+<CurrencyInput
+  currency="USD"
+  max={1000000}
+  value={10000000}
+/>
+```
+
+## Minor Unit Mode
+
+When `useMinorUnit` is true, the component converts between display values and minor units (e.g., cents for USD). This is useful when your API stores amounts in the smallest currency unit.
+
+```tsx
+// Display shows "$10.00", but onChange returns 1000 (cents)
+<CurrencyInput currency="USD" useMinorUnit value={1000} />
+
+// Display shows "₩10,000", onChange returns 10000 (no conversion for KRW)
+<CurrencyInput currency="KRW" useMinorUnit value={10000} />
+```
+
+## Common Use Cases
+
+### Product Price Editor
+
+```tsx
+function ProductPriceEditor() {
+  const [priceUSD, setPriceUSD] = React.useState(0);
+  const [priceKRW, setPriceKRW] = React.useState(0);
+
+  return (
+    <Stack gap={2}>
+      <CurrencyInput
+        label="USD Price"
+        currency="USD"
+        value={priceUSD}
+        onChange={(e) => setPriceUSD(e.target.value)}
+        max={99999.99}
+      />
+      <CurrencyInput
+        label="KRW Price"
+        currency="KRW"
+        value={priceKRW}
+        onChange={(e) => setPriceKRW(e.target.value)}
+        max={99999999}
+      />
+    </Stack>
+  );
+}
+```
+
+### Invoice Line Item
+
+```tsx
+function InvoiceLineItem({ item, onChange }) {
+  return (
+    <Stack direction="row" gap={2} alignItems="flex-end">
+      <Input label="Description" value={item.description} />
+      <CurrencyInput
+        label="Unit Price"
+        currency="USD"
+        value={item.unitPrice}
+        onChange={(e) => onChange({ ...item, unitPrice: e.target.value })}
+      />
+      <Input label="Qty" type="number" value={item.quantity} sx={{ width: 80 }} />
+    </Stack>
+  );
+}
+```
+
+### Budget Limit Input
+
+```tsx
+function BudgetSetting() {
+  const [budget, setBudget] = React.useState(50000);
+
+  return (
+    <CurrencyInput
+      label="Monthly Budget"
+      helperText="Set the maximum monthly spending limit."
+      currency="USD"
+      value={budget}
+      onChange={(e) => setBudget(e.target.value)}
+      max={1000000}
+    />
+  );
+}
+```
+
+## Best Practices
+
+1. **Choose the right currency**: Always set the `currency` prop explicitly. USD uses 2 decimal places while KRW uses none.
+
+```tsx
+// ✅ Explicit currency
+<CurrencyInput currency="USD" />
+<CurrencyInput currency="KRW" />
+
+// ❌ Relying on default — may confuse users expecting KRW
+<CurrencyInput />
+```
+
+2. **Set max limits**: Use `max` to prevent unreasonable values. The component displays a helpful error message when the limit is exceeded.
+
+3. **Use `useMinorUnit` for API integration**: When your backend stores amounts in minor units (cents, etc.), enable `useMinorUnit` to avoid manual conversion.
+
+4. **Use built-in label and helperText**: Prefer the component's own `label` and `helperText` props over wrapping with FormControl.
+
+5. **Handle negative values carefully**: CurrencyInput supports negative values. If negatives are not valid for your use case, validate in `onChange`.
+
+## Accessibility
+
+- The input has `role="textbox"` with proper labeling via the `label` prop.
+- Error states are communicated via `aria-invalid` and associated error messages.
+- The currency symbol serves as a visual indicator; ensure labels also mention the currency for screen readers.
+- Keyboard input is fully supported — users can type numbers, and formatting is applied automatically.