@ceed/ads 1.23.3 → 1.23.5

package/dist/components/inputs/FormControl.md

@@ -0,0 +1,361 @@
+# 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/IconButton.md

@@ -2,7 +2,9 @@
 
 ## Introduction
 
-IconButton 컴포넌트는 아이콘만으로 구성된 버튼입니다. 공간 효율적이며, 직관적인 액션을 제공하는 UI 요소로 주로 툴바, 헤더, 카드 등에서 사용됩니다. 텍스트 없이도 의미를 전달할 수 있는 명확한 아이콘과 함께 사용하세요.
+IconButton is a compact, icon-only button component designed for actions where a visual symbol alone is sufficient to communicate meaning. It is ideal for toolbars, table row actions, card headers, navigation bars, and any context where space efficiency is critical.
+
+Because IconButton omits visible text, it relies entirely on the icon's clarity and supplementary accessibility attributes to convey its purpose. Always pair it with `aria-label` or a Tooltip to ensure all users can understand the button's function.
 
 ```tsx
 <IconButton {...args} />
@@ -22,56 +24,26 @@ IconButton 컴포넌트는 아이콘만으로 구성된 버튼입니다. 공간
 ```tsx
 import { IconButton } from '@ceed/ads';
 import AddIcon from '@mui/icons-material/Add';
+import DeleteIcon from '@mui/icons-material/Delete';
 
 function MyComponent() {
   return (
-    <div>
-      <IconButton onClick={() => console.log('clicked')}>
+    <div style={{ display: 'flex', gap: '0.5rem' }}>
+      <IconButton aria-label="Add item" onClick={handleAdd}>
         <AddIcon />
       </IconButton>
 
-      <IconButton color="danger" onClick={() => console.log('delete')}>
+      <IconButton color="danger" aria-label="Delete item" onClick={handleDelete}>
         <DeleteIcon />
       </IconButton>
-
-      <IconButton disabled>
-        <EditIcon />
-      </IconButton>
     </div>
   );
 }
 ```
 
-## Examples
-
-### Basic Usage
-
-기본적인 IconButton 사용법입니다.
-
-```tsx
-<div style={{
-  display: 'flex',
-  gap: '1rem',
-  alignItems: 'center'
-}}>
-<IconButton>
-  <Add />
-</IconButton>
-<IconButton>
-  <Edit />
-</IconButton>
-<IconButton>
-  <Delete />
-</IconButton>
-<IconButton>
-  <Settings />
-</IconButton>
-</div>
-```
-
-### Colors
+## Colors
 
-다양한 색상을 적용할 수 있습니다.
+IconButton supports five semantic colors: `primary` (default), `neutral`, `danger`, `success`, and `warning`. Choose a color that reflects the nature of the action.
 
 ```tsx
 <div style={{
@@ -97,9 +69,9 @@ function MyComponent() {
 </div>
 ```
 
-### Variants
+## Variants
 
-다양한 스타일 변형을 제공합니다.
+Four visual variants are available: `solid` (filled background), `soft` (tinted background), `outlined` (border only), and `plain` (no background). Use `outlined` or `plain` for secondary actions, and `solid` for primary or high-emphasis actions.
 
 ```tsx
 <div style={{
@@ -122,9 +94,9 @@ function MyComponent() {
 </div>
 ```
 
-### Sizes
+## Sizes
 
-크기를 조절할 수 있습니다.
+The `size` prop controls the button dimensions. Available sizes are `sm`, `md` (default), and `lg`. Ensure touch targets meet the minimum 44px recommended size for touch interfaces.
 
 ```tsx
 <div style={{
@@ -144,9 +116,9 @@ function MyComponent() {
 </div>
 ```
 
-### States
+## States
 
-다양한 상태를 표현할 수 있습니다.
+IconButton supports multiple interactive states including normal, disabled, and loading. Use `disabled` to prevent interaction and `loading` to indicate an in-progress async operation.
 
 ```tsx
 <div style={{
@@ -202,9 +174,9 @@ function MyComponent() {
 </div>
 ```
 
-### With Badge
+## With Badge
 
-Badge와 함께 사용하여 알림 수나 상태를 표시할 수 있습니다.
+Combine IconButton with Badge to display notification counts, status indicators, or unread markers alongside the button.
 
 ```tsx
 <div style={{
@@ -230,9 +202,9 @@ Badge와 함께 사용하여 알림 수나 상태를 표시할 수 있습니다.
 </div>
 ```
 
-### With Tooltip
+## With Tooltip
 
-Tooltip과 함께 사용하여 버튼의 기능을 설명할 수 있습니다.
+Wrap IconButton in a Tooltip to provide a text description on hover. This is especially important for icon-only buttons since the icon alone may not be self-explanatory for all users.
 
 ```tsx
 <div style={{
@@ -263,9 +235,40 @@ Tooltip과 함께 사용하여 버튼의 기능을 설명할 수 있습니다.
 </div>
 ```
 
-### Action Buttons
+## Circular Variants
+
+IconButton renders as a circular shape by default, making it visually distinct from rectangular text buttons and well-suited for floating action buttons and compact action rows.
+
+```tsx
+<div style={{
+  display: 'flex',
+  gap: '2rem',
+  alignItems: 'center'
+}}>
+<div>
+  <h4>Default</h4>
+  <div style={{
+    display: 'flex',
+    gap: '1rem',
+    alignItems: 'center'
+  }}>
+  <IconButton>
+    <Add />
+  </IconButton>
+  <IconButton variant="outlined">
+    <Edit />
+  </IconButton>
+  <IconButton variant="soft">
+    <Delete />
+  </IconButton>
+</div>
+</div>
+</div>
+```
+
+## Action Buttons
 
-실제 액션을 수행하는 버튼들의 예제입니다.
+A practical example of IconButton used for common CRUD operations with distinct colors signaling the nature of each action.
 
 ```tsx
 <div style={{
@@ -293,69 +296,115 @@ Tooltip과 함께 사용하여 버튼의 기능을 설명할 수 있습니다.
 
 ## Common Use Cases
 
-### Toolbar Actions
+### Table Row Actions
 
 ```tsx
-<div style={{ display: 'flex', gap: '0.5rem' }}>
-  <IconButton onClick={handleAdd} title="Add item">
-    <AddIcon />
-  </IconButton>
-  <IconButton onClick={handleEdit} color="neutral" title="Edit">
-    <EditIcon />
-  </IconButton>
-  <IconButton onClick={handleDelete} color="danger" title="Delete">
-    <DeleteIcon />
-  </IconButton>
-</div>
+import { IconButton, Tooltip } from '@ceed/ads';
+import EditIcon from '@mui/icons-material/Edit';
+import DeleteIcon from '@mui/icons-material/Delete';
+import VisibilityIcon from '@mui/icons-material/Visibility';
+
+function RowActions({ onView, onEdit, onDelete }) {
+  return (
+    <div style={{ display: 'flex', gap: '0.25rem' }}>
+      <Tooltip title="View details">
+        <IconButton size="sm" variant="plain" color="neutral" onClick={onView}>
+          <VisibilityIcon />
+        </IconButton>
+      </Tooltip>
+      <Tooltip title="Edit">
+        <IconButton size="sm" variant="plain" color="neutral" onClick={onEdit}>
+          <EditIcon />
+        </IconButton>
+      </Tooltip>
+      <Tooltip title="Delete">
+        <IconButton size="sm" variant="plain" color="danger" onClick={onDelete}>
+          <DeleteIcon />
+        </IconButton>
+      </Tooltip>
+    </div>
+  );
+}
 ```
 
-### Navigation
+### Dialog Close Button
 
 ```tsx
-<IconButton onClick={() => router.back()} variant="outlined">
-  <ArrowBackIcon />
+import CloseIcon from '@mui/icons-material/Close';
+
+<IconButton
+  variant="plain"
+  color="neutral"
+  size="sm"
+  aria-label="Close dialog"
+  onClick={onClose}
+  sx={{ position: 'absolute', top: 8, right: 8 }}
+>
+  <CloseIcon />
 </IconButton>
 ```
 
-### Settings & More Options
+### Navigation Back Button
 
 ```tsx
-<IconButton onClick={handleSettings} color="neutral">
-  <SettingsIcon />
-</IconButton>
-<IconButton onClick={handleMoreOptions}>
-  <MoreVertIcon />
+import ArrowBackIcon from '@mui/icons-material/ArrowBack';
+
+<IconButton
+  variant="outlined"
+  color="neutral"
+  aria-label="Go back"
+  onClick={() => router.back()}
+>
+  <ArrowBackIcon />
 </IconButton>
 ```
 
-### Social Actions
+## Best Practices
+
+1. **Always provide an accessible label.** Since there is no visible text, use `aria-label` or wrap with a Tooltip to describe the action.
 
 ```tsx
-<IconButton onClick={handleLike} color="danger">
-  <FavoriteIcon />
+// ✅ Accessible icon button
+<IconButton aria-label="Delete item" color="danger">
+  <DeleteIcon />
 </IconButton>
-<IconButton onClick={handleShare} color="primary">
-  <ShareIcon />
+
+// ❌ No accessible label
+<IconButton color="danger">
+  <DeleteIcon />
 </IconButton>
 ```
 
-## Best Practices
+2. **Use semantic colors to convey intent.** Match the color to the action's nature: `danger` for destructive actions, `success` for confirmations, `neutral` for general-purpose actions.
 
-1. **명확한 아이콘**: 사용자가 쉽게 이해할 수 있는 명확하고 직관적인 아이콘을 사용하세요.
+```tsx
+// ✅ Color matches the action
+<IconButton color="danger" aria-label="Delete">
+  <DeleteIcon />
+</IconButton>
 
-2. **적절한 크기**: 터치 인터페이스를 고려하여 최소 44px 이상의 터치 영역을 확보하세요.
+// ❌ Misleading color
+<IconButton color="success" aria-label="Delete">
+  <DeleteIcon />
+</IconButton>
+```
 
-3. **접근성**:
-   - `title` 속성이나 `aria-label`을 제공하여 스크린 리더 사용자를 위한 설명을 추가하세요.
-   - Tooltip과 함께 사용하여 기능을 명확히 설명하세요.
+3. **Use the `loading` prop for async operations.** This prevents double-clicks and provides visual feedback during network requests or processing.
+
+```tsx
+// ✅ Shows loading spinner during async action
+<IconButton loading={isSaving} aria-label="Save" onClick={handleSave}>
+  <SaveIcon />
+</IconButton>
+```
 
-4. **일관된 스타일**: 같은 맥락에서는 일관된 variant와 색상을 사용하세요.
+4. **Prefer universally recognized icons.** Choose icons that are widely understood (e.g., trash can for delete, pencil for edit, plus for add). Avoid ambiguous symbols without a Tooltip.
 
-5. **의미 있는 색상**:
-   - 빨간색(danger): 삭제, 취소 등의 위험한 액션
-   - 초록색(success): 저장, 승인 등의 긍정적인 액션
-   - 회색(neutral): 일반적인 액션
+5. **Maintain consistent sizing within the same context.** Use the same `size` and `variant` for all IconButtons in a toolbar or action group to keep the interface clean and predictable.
 
-6. **피드백 제공**: 클릭 시 명확한 피드백을 제공하여 사용자가 액션이 실행되었음을 알 수 있도록 하세요.
+## Accessibility
 
-7. **로딩 상태**: 비동기 작업 시 `loading` prop을 사용하여 사용자에게 진행 상황을 알려주세요.
+- **`aria-label` is essential**: Every IconButton must have either an `aria-label`, `aria-labelledby`, or a wrapping Tooltip with `title` to provide a text alternative for screen readers.
+- **Keyboard interaction**: IconButton is focusable via `Tab` and can be activated with `Enter` or `Space`. Focus indicators are displayed by default.
+- **Disabled state**: When `disabled` is set, the button receives `aria-disabled="true"` and becomes non-interactive. It remains visible in the DOM for screen readers to announce.
+- **Touch targets**: Ensure the rendered button is at least 44x44 pixels for touch accessibility. The `sm` size may need additional padding in touch-heavy interfaces.