@ceed/ads 1.13.4 → 1.15.0-next.2

package/dist/components/inputs/IconButton.md

@@ -0,0 +1,361 @@
+# IconButton
+
+## Introduction
+
+IconButton 컴포넌트는 아이콘만으로 구성된 버튼입니다. 공간 효율적이며, 직관적인 액션을 제공하는 UI 요소로 주로 툴바, 헤더, 카드 등에서 사용됩니다. 텍스트 없이도 의미를 전달할 수 있는 명확한 아이콘과 함께 사용하세요.
+
+```tsx
+<IconButton {...args} />
+```
+
+| Field    | Description | Default   |
+| -------- | ----------- | --------- |
+| children | 아이콘 요소      | \<Add />  |
+| color    | 버튼 색상       | "primary" |
+| variant  | 버튼 스타일 변형   | "solid"   |
+| size     | 버튼 크기       | "md"      |
+| disabled | 비활성화 상태     | —         |
+| loading  | 로딩 상태       | —         |
+
+## Usage
+
+```tsx
+import { IconButton } from '@ceed/ads';
+import AddIcon from '@mui/icons-material/Add';
+
+function MyComponent() {
+  return (
+    <div>
+      <IconButton onClick={() => console.log('clicked')}>
+        <AddIcon />
+      </IconButton>
+
+      <IconButton color="danger" onClick={() => console.log('delete')}>
+        <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
+
+다양한 색상을 적용할 수 있습니다.
+
+```tsx
+<div style={{
+  display: 'flex',
+  gap: '1rem',
+  alignItems: 'center'
+}}>
+<IconButton color="primary">
+  <Add />
+</IconButton>
+<IconButton color="neutral">
+  <Edit />
+</IconButton>
+<IconButton color="danger">
+  <Delete />
+</IconButton>
+<IconButton color="success">
+  <FavoriteIcon />
+</IconButton>
+<IconButton color="warning">
+  <Settings />
+</IconButton>
+</div>
+```
+
+### Variants
+
+다양한 스타일 변형을 제공합니다.
+
+```tsx
+<div style={{
+  display: 'flex',
+  gap: '1rem',
+  alignItems: 'center'
+}}>
+<IconButton variant="solid">
+  <Add />
+</IconButton>
+<IconButton variant="soft">
+  <Add />
+</IconButton>
+<IconButton variant="outlined">
+  <Add />
+</IconButton>
+<IconButton variant="plain">
+  <Add />
+</IconButton>
+</div>
+```
+
+### Sizes
+
+크기를 조절할 수 있습니다.
+
+```tsx
+<div style={{
+  display: 'flex',
+  gap: '1rem',
+  alignItems: 'center'
+}}>
+<IconButton size="sm">
+  <Add />
+</IconButton>
+<IconButton size="md">
+  <Add />
+</IconButton>
+<IconButton size="lg">
+  <Add />
+</IconButton>
+</div>
+```
+
+### States
+
+다양한 상태를 표현할 수 있습니다.
+
+```tsx
+<div style={{
+  display: 'flex',
+  gap: '2rem',
+  alignItems: 'center'
+}}>
+<div>
+  <h4>Normal</h4>
+  <div style={{
+    display: 'flex',
+    gap: '1rem',
+    alignItems: 'center'
+  }}>
+  <IconButton>
+    <Add />
+  </IconButton>
+  <IconButton color="danger">
+    <Delete />
+  </IconButton>
+</div>
+</div>
+<div>
+  <h4>Disabled</h4>
+  <div style={{
+    display: 'flex',
+    gap: '1rem',
+    alignItems: 'center'
+  }}>
+  <IconButton disabled>
+    <Add />
+  </IconButton>
+  <IconButton disabled color="danger">
+    <Delete />
+  </IconButton>
+</div>
+</div>
+<div>
+  <h4>Loading</h4>
+  <div style={{
+    display: 'flex',
+    gap: '1rem',
+    alignItems: 'center'
+  }}>
+  <IconButton loading>
+    <Add />
+  </IconButton>
+  <IconButton loading color="danger">
+    <Delete />
+  </IconButton>
+</div>
+</div>
+</div>
+```
+
+### With Badge
+
+Badge와 함께 사용하여 알림 수나 상태를 표시할 수 있습니다.
+
+```tsx
+<div style={{
+  display: 'flex',
+  gap: '1rem',
+  alignItems: 'center'
+}}>
+<Badge badgeContent={4} color="danger">
+  <IconButton>
+    <Settings />
+  </IconButton>
+</Badge>
+<Badge badgeContent="99+" color="warning">
+  <IconButton color="neutral">
+    <MoreVertIcon />
+  </IconButton>
+</Badge>
+<Badge variant="solid" color="success">
+  <IconButton color="primary">
+    <FavoriteIcon />
+  </IconButton>
+</Badge>
+</div>
+```
+
+### With Tooltip
+
+Tooltip과 함께 사용하여 버튼의 기능을 설명할 수 있습니다.
+
+```tsx
+<div style={{
+  display: 'flex',
+  gap: '1rem',
+  alignItems: 'center'
+}}>
+<Tooltip title="새 항목 추가">
+  <IconButton>
+    <Add />
+  </IconButton>
+</Tooltip>
+<Tooltip title="편집">
+  <IconButton color="neutral">
+    <Edit />
+  </IconButton>
+</Tooltip>
+<Tooltip title="삭제">
+  <IconButton color="danger">
+    <Delete />
+  </IconButton>
+</Tooltip>
+<Tooltip title="공유">
+  <IconButton color="success">
+    <ShareIcon />
+  </IconButton>
+</Tooltip>
+</div>
+```
+
+### Action Buttons
+
+실제 액션을 수행하는 버튼들의 예제입니다.
+
+```tsx
+<div style={{
+  display: 'flex',
+  gap: '1rem',
+  alignItems: 'center'
+}}>
+<IconButton onClick={() => alert('Add clicked!')} title="Add new item">
+  <Add />
+</IconButton>
+<IconButton onClick={() => alert('Edit clicked!')} color="neutral" title="Edit item">
+  <Edit />
+</IconButton>
+<IconButton onClick={() => alert('Delete clicked!')} color="danger" title="Delete item">
+  <Delete />
+</IconButton>
+<IconButton onClick={() => alert('Share clicked!')} color="success" title="Share item">
+  <ShareIcon />
+</IconButton>
+<IconButton onClick={() => alert('Settings clicked!')} color="neutral" variant="outlined" title="Settings">
+  <Settings />
+</IconButton>
+</div>
+```
+
+## Common Use Cases
+
+### Toolbar 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>
+```
+
+### Navigation
+
+```tsx
+<IconButton onClick={() => router.back()} variant="outlined">
+  <ArrowBackIcon />
+</IconButton>
+```
+
+### Settings & More Options
+
+```tsx
+<IconButton onClick={handleSettings} color="neutral">
+  <SettingsIcon />
+</IconButton>
+<IconButton onClick={handleMoreOptions}>
+  <MoreVertIcon />
+</IconButton>
+```
+
+### Social Actions
+
+```tsx
+<IconButton onClick={handleLike} color="danger">
+  <FavoriteIcon />
+</IconButton>
+<IconButton onClick={handleShare} color="primary">
+  <ShareIcon />
+</IconButton>
+```
+
+## Best Practices
+
+1. **명확한 아이콘**: 사용자가 쉽게 이해할 수 있는 명확하고 직관적인 아이콘을 사용하세요.
+
+2. **적절한 크기**: 터치 인터페이스를 고려하여 최소 44px 이상의 터치 영역을 확보하세요.
+
+3. **접근성**:
+   - `title` 속성이나 `aria-label`을 제공하여 스크린 리더 사용자를 위한 설명을 추가하세요.
+   - Tooltip과 함께 사용하여 기능을 명확히 설명하세요.
+
+4. **일관된 스타일**: 같은 맥락에서는 일관된 variant와 색상을 사용하세요.
+
+5. **의미 있는 색상**:
+   - 빨간색(danger): 삭제, 취소 등의 위험한 액션
+   - 초록색(success): 저장, 승인 등의 긍정적인 액션
+   - 회색(neutral): 일반적인 액션
+
+6. **피드백 제공**: 클릭 시 명확한 피드백을 제공하여 사용자가 액션이 실행되었음을 알 수 있도록 하세요.
+
+7. **로딩 상태**: 비동기 작업 시 `loading` prop을 사용하여 사용자에게 진행 상황을 알려주세요.

package/dist/components/inputs/Input.md

@@ -0,0 +1,283 @@
+# Input
+
+Input 컴포넌트는 사용자로부터 텍스트 입력을 받기 위한 기본 컴포넌트입니다. 다양한 스타일, 크기 및 기능을 지원합니다.
+
+```tsx
+<Input />
+```
+
+| Field                       | Description | Default |
+| --------------------------- | ----------- | ------- |
+| color                       | —           | —       |
+| size                        | —           | —       |
+| variant                     | —           | —       |
+| label                       | —           | —       |
+| helperText                  | —           | —       |
+| error                       | —           | —       |
+| required                    | —           | —       |
+| disabled                    | —           | —       |
+| value                       | —           | —       |
+| defaultValue                | —           | —       |
+| onChange                    | —           | —       |
+| name                        | —           | —       |
+| placeholder                 | —           | —       |
+| type                        | —           | —       |
+| startDecorator              | —           | —       |
+| endDecorator                | —           | —       |
+| enableClearable             | —           | —       |
+| disableTogglePasswordButton | —           | —       |
+| sx                          | —           | —       |
+| className                   | —           | —       |
+
+## 기본형
+
+Input의 기본 형태입니다. 사용자의 텍스트 입력을 받는 단일 라인 필드입니다.
+
+```tsx
+<Input />
+```
+
+## 변형(Variants)
+
+Input은 네 가지 변형을 지원합니다: `solid`, `soft`, `outlined`, `plain`
+
+```tsx
+<>
+  <Input placeholder="Type in here…" variant="solid" />
+  <Input placeholder="Type in here…" variant="soft" />
+  <Input placeholder="Type in here…" variant="outlined" />
+  <Input placeholder="Type in here…" variant="plain" />
+</>
+```
+
+## 크기(Sizes)
+
+Input은 세 가지 크기를 지원합니다: `sm`, `md`, `lg`
+
+```tsx
+<>
+  <Input {...args} size="lg" />
+  <Input {...args} size="md" />
+  <Input {...args} size="sm" />
+</>
+```
+
+## 레이블 및 도움말 텍스트
+
+Input 컴포넌트에 `label`과 `helperText` 속성을 추가하여 사용자에게 추가 정보를 제공할 수 있습니다.
+
+### 레이블(Label)
+
+`label` 속성을 사용하여 Input 위에 레이블을 표시할 수 있습니다.
+
+```tsx
+<>
+  <Input placeholder="Type in here…" label="Label" />
+</>
+```
+
+### 도움말 텍스트(Helper Text)
+
+`helperText` 속성을 사용하여 Input 아래에 추가 정보를 제공할 수 있습니다.
+
+```tsx
+<>
+  <Input placeholder="Type in here…" helperText="I'm helper text" />
+</>
+```
+
+## 상태(States)
+
+### 비활성화(Disabled)
+
+`disabled` 속성을 사용하여 Input을 비활성화할 수 있습니다.
+
+```tsx
+<Input disabled />
+```
+
+### 오류 상태(Error)
+
+`error` 속성을 사용하여 오류 상태를 표시할 수 있습니다.
+
+```tsx
+<>
+  <Input placeholder="Invalid input" label="label" error />
+</>
+```
+
+### 필수 값(Required)
+
+`required` 속성을 사용하여 필수 입력 필드임을 표시할 수 있습니다.
+
+```tsx
+<Input
+  placeholder="Type in here..."
+  helperText="I'm helper text"
+  label="Label"
+  required
+/>
+```
+
+## 장식자(Decorators)
+
+Input 컴포넌트는 `startDecorator`와 `endDecorator` 속성을 통해 입력 필드의 시작과 끝 부분에 아이콘, 버튼 또는 기타 요소를 추가할 수 있습니다.
+
+```tsx
+<Stack spacing={3}>
+  <Input placeholder="Amount" startDecorator={{
+    dollar: '$',
+    baht: '฿',
+    yen: '¥'
+  }[currency]} endDecorator={<React.Fragment>
+  <Divider orientation="vertical" />
+  <Select variant="plain" value={currency} options={[{
+    value: 'dollar',
+    label: 'US dollar'
+  }, {
+    value: 'baht',
+    label: 'Thai baht'
+  }, {
+    value: 'yen',
+    label: 'Japanese yen'
+  }]} onChange={e => setCurrency(e.target.value!)} slotProps={{
+    listbox: {
+      variant: 'outlined'
+    }
+  }} sx={{
+    mr: -1.5,
+    '&:hover': {
+      bgcolor: 'transparent'
+    }
+  }} />
+</React.Fragment>} sx={{
+width: 300
+}} />
+<Input placeholder="Your location" startDecorator={<Button variant="soft" color="neutral" startDecorator={<LocationOn />}>
+  Locate
+</Button>} sx={{
+width: 300
+}} />
+</Stack>
+```
+
+`endDecorator`와 `enableClearable`을 함께 사용하면 다음과 같습니다:
+
+```tsx
+<Input
+  placeholder="Type in here…"
+  label="Label"
+  enableClearable
+  endDecorator={<Chip color="primary">Hi</Chip>}
+/>
+```
+
+## 지울 수 있는 입력(Clearable Input)
+
+`enableClearable` 속성을 사용하여 Input에 내용을 지울 수 있는 버튼을 추가할 수 있습니다.
+
+```tsx
+<>
+  <Input placeholder="Type in here…" label="Label" enableClearable />
+</>
+```
+
+## 비밀번호 입력(Password Input)
+
+`type="password"` 속성을 사용하면 비밀번호 입력 필드가 생성되며, 자동으로 비밀번호 표시/숨김 토글 버튼이 추가됩니다.
+
+```tsx
+<Stack spacing={3}>
+  <Typography level="body-md">Default password input with toggle button:</Typography>
+  <Input {...args} placeholder="Enter password" type="password" label="Password" />
+
+  <Typography level="body-md">Disabled password input:</Typography>
+  <Input {...args} placeholder="Enter password" type="password" label="Disabled Password" disabled />
+
+  <Typography level="body-md">Password input with toggle button disabled:</Typography>
+  <Input {...args} placeholder="Enter password" type="password" label="No Toggle" disableTogglePasswordButton />
+</Stack>
+```
+
+### 비밀번호 토글 비활성화
+
+비밀번호 입력 필드의 토글 버튼은 `disableTogglePasswordButton` 속성을 사용하여 비활성화할 수 있습니다.
+
+```tsx
+<Stack spacing={3}>
+  <Typography level="body-md">Default password input with toggle button:</Typography>
+  <Input {...args} placeholder="Enter password" type="password" label="Password" />
+
+  <Typography level="body-md">Disabled password input:</Typography>
+  <Input {...args} placeholder="Enter password" type="password" label="Disabled Password" disabled />
+
+  <Typography level="body-md">Password input with toggle button disabled:</Typography>
+  <Input {...args} placeholder="Enter password" type="password" label="No Toggle" disableTogglePasswordButton />
+</Stack>
+```
+
+### 비밀번호 입력의 제한 사항
+
+비밀번호 입력 필드(`type="password"`)에서는 `endDecorator`를 사용할 수 없습니다. 이는 비밀번호 토글 버튼이 해당 위치를 차지하기 때문입니다.
+
+```tsx
+<Stack spacing={3}>
+  <Typography level="body-md">When type="password", the endDecorator is not supported:</Typography>
+  <Input {...args} placeholder="Enter password" type="password" label="Password with endDecorator (will show warning)" endDecorator={<Chip color="primary">Hi</Chip>} />
+
+  <Typography level="body-md">The password toggle button takes precedence:</Typography>
+  <Input {...args} placeholder="Enter password" type="password" label="Password" />
+</Stack>
+```
+
+## 폼 컨트롤(Form Control)
+
+Input 컴포넌트는 `label`, `helperText`, `error` 속성을 조합하여 완전한 폼 컨트롤을 구성할 수 있습니다.
+
+```tsx
+<>
+  <Input placeholder="Type in here..." helperText="I'm helper text" label="Label" />
+  <Input placeholder="Invalid input" helperText="I'm helper text" label="Label" error />
+</>
+```
+
+## 상태 관리
+
+### 제어 컴포넌트(Controlled Component)
+
+Input은 React의 제어 컴포넌트로 사용할 수 있습니다. `value`와 `onChange` 속성을 사용하여 상태를 관리합니다.
+
+```tsx
+<>
+  <Input placeholder="Type in here…" label="Label" enableClearable value={value} onChange={handleChange} />
+</>
+```
+
+### 비제어 컴포넌트(Uncontrolled Component)
+
+`defaultValue` 속성을 사용하여 비제어 컴포넌트로도 사용 가능합니다.
+
+## 접근성(Accessibility)
+
+Input 컴포넌트는 웹 접근성 표준을 준수합니다:
+
+- 적절한 레이블과 연결되어 있습니다.
+- 키보드 탐색이 가능합니다.
+- 오류 상태는 시각적으로 명확하게 표시됩니다.
+
+## 테스팅(Testing)
+
+### Testing Library 참고사항
+
+- `type="password"` 속성을 가진 Input을 Testing Library로 찾을 때는 항상 `textbox` 역할(role)로 찾아야 합니다.
+- 이는 ARIA 명세에 따라 `password` 입력이 특별한 role을 갖지 않고 기본적으로 `textbox` role을 사용하기 때문입니다.
+
+```tsx
+// 비밀번호 입력 필드를 찾는 예시
+const passwordInput = screen.getByRole('textbox', { name: /비밀번호/i });
+```
+
+**참고 이슈:**
+
+- [W3C ARIA: Should there be a role=password?](https://github.com/w3c/aria/issues/935)
+- [Testing Library: How to find password inputs](https://github.com/testing-library/dom-testing-library/issues/567)

package/dist/components/inputs/MonthPicker.md

@@ -0,0 +1,72 @@
+# MonthPicker
+
+## Introduction
+
+```tsx
+<MonthPicker />
+```
+
+| Field         | Description | Default |
+| ------------- | ----------- | ------- |
+| value         | —           | —       |
+| defaultValue  | —           | —       |
+| name          | —           | —       |
+| disabled      | —           | —       |
+| required      | —           | —       |
+| label         | —           | —       |
+| error         | —           | —       |
+| helperText    | —           | —       |
+| minDate       | —           | —       |
+| maxDate       | —           | —       |
+| disableFuture | —           | —       |
+| disablePast   | —           | —       |
+| format        | —           | —       |
+| onChange      | —           | —       |
+
+### Sizes
+
+```tsx
+<Stack gap={2}>
+  <MonthPicker size="sm" />
+  <MonthPicker size="md" />
+  <MonthPicker size="lg" />
+</Stack>
+```
+
+### WithLabel
+
+```tsx
+<MonthPicker label="Date" />
+```
+
+### WithHelperText
+
+```tsx
+<MonthPicker
+  label="Date"
+  helperText="Please select a date"
+/>
+```
+
+### Error
+
+```tsx
+<MonthPicker
+  label="Date"
+  helperText="Please select a date"
+  error
+/>
+```
+
+### WithFormats
+
+```tsx
+<Stack gap={2}>
+  <MonthPicker {...args} value={value['YYYY.MM.DD']} label="YYYY.MM.DD" name="YYYY.MM.DD" format="YYYY.MM.DD" onChange={handleChange} />
+  <MonthPicker {...args} value={value['YYYY/MM/DD']} label="YYYY/MM/DD" name="YYYY/MM/DD" format="YYYY/MM/DD" onChange={handleChange} />
+  <MonthPicker {...args} value={value['MM/DD/YYYY']} label="MM/DD/YYYY" name="MM/DD/YYYY" format="MM/DD/YYYY" onChange={handleChange} />
+  <MonthPicker {...args} value={value['YYYY-MM-DD']} label="YYYY-MM-DD" name="YYYY-MM-DD" format="YYYY-MM-DD" onChange={handleChange} />
+  <MonthPicker {...args} value={value['DD/MM/YYYY']} label="DD/MM/YYYY" name="DD/MM/YYYY" format="DD/MM/YYYY" onChange={handleChange} />
+  <MonthPicker {...args} value={value['DD.MM.YYYY']} label="DD.MM.YYYY" name="DD.MM.YYYY" format="DD.MM.YYYY" onChange={handleChange} />
+</Stack>
+```