@ceed/cds 1.28.1 → 1.29.0-next.1

package/dist/components/inputs/Switch.md

@@ -2,9 +2,7 @@
 
 ## Introduction
 
-The Switch component is a toggle input that lets users turn an option on or off. It is built on Joy UI's Switch and provides a variety of sizes, colors, variants, and decorator slots for icons or text.
-
-Switches are best suited for binary settings that take effect immediately, such as enabling notifications, toggling dark mode, or activating a feature. Unlike a checkbox (which is often part of a form submission), a switch communicates an instant state change.
+Switch 컴포넌트는 사용자가 옵션을 켜고 끌 수 있는 토글 형태의 입력 요소입니다. Joy UI의 Switch를 기반으로 하며, 다양한 크기, 색상, 장식 요소를 지원합니다. 설정 화면, 기능 활성화/비활성화, 모드 전환 등에 주로 사용됩니다.
 
 ```tsx
 <Switch />
@@ -27,18 +25,23 @@ import { Switch } from '@ceed/cds';
 function MyComponent() {
   const [enabled, setEnabled] = useState(false);
 
-  return (
-    <Switch
-      checked={enabled}
-      onChange={(e) => setEnabled(e.target.checked)}
-    />
-  );
+  return <Switch checked={enabled} onChange={(e) => setEnabled(e.target.checked)} />;
 }
 ```
 
-## With Labels
+## Examples
+
+### Basic Usage
+
+가장 기본적인 Switch 사용법입니다.
+
+```tsx
+<Switch />
+```
+
+### With Labels
 
-Use `FormControl` with `FormLabel` and `FormHelperText` to provide a label and description alongside the switch. The `orientation="horizontal"` layout places the label on the left and the switch on the right.
+라벨과 함께 사용하는 Switch입니다. 폼 컨트롤 내에서 설명과 함께 사용할 수 있습니다.
 
 ```tsx
 <FormControl orientation="horizontal" sx={{
@@ -61,9 +64,9 @@ Use `FormControl` with `FormLabel` and `FormHelperText` to provide a label and d
 </FormControl>
 ```
 
-## Inline Labels
+### Inline Labels
 
-For simpler cases, wrap the switch inside a `Typography` component rendered as a `<label>`. This connects the text and switch semantically without requiring a `FormControl`.
+인라인 형태로 텍스트와 함께 사용할 수 있습니다.
 
 ```tsx
 <Typography component="label" endDecorator={<Switch sx={{
@@ -73,9 +76,9 @@ Turn alarm on
 </Typography>
 ```
 
-## With Decorators
+### With Decorators
 
-Use `startDecorator` and `endDecorator` to place icons or text around the switch. This is particularly useful for theme toggles or any context where visual cues reinforce the on/off meaning.
+아이콘이나 다른 요소를 장식으로 추가할 수 있습니다.
 
 ```tsx
 <Switch color={dark ? 'primary' : 'danger'} slotProps={{
@@ -89,9 +92,9 @@ Use `startDecorator` and `endDecorator` to place icons or text around the switch
 })} />} checked={dark} onChange={event => setDark(event.target.checked)} />
 ```
 
-## Track Children
+### Track Children
 
-Display text or symbols inside the switch track using `slotProps.track.children`. This provides an always-visible label (e.g., "On" / "Off" or "I" / "0") directly on the track.
+트랙 내부에 텍스트나 다른 요소를 표시할 수 있습니다.
 
 ```tsx
 <Stack direction="row" spacing={4}>
@@ -133,9 +136,9 @@ Display text or symbols inside the switch track using `slotProps.track.children`
 </Stack>
 ```
 
-## Thumb Children
+### Thumb Children
 
-Place an icon inside the switch thumb using `slotProps.thumb.children`. This is useful for adding a small visual indicator that moves with the toggle.
+썸(토글 버튼) 내부에 아이콘을 표시할 수 있습니다.
 
 ```tsx
 <Switch size="lg" slotProps={{
@@ -150,96 +153,36 @@ Place an icon inside the switch thumb using `slotProps.thumb.children`. This is
 }} />
 ```
 
-## All Variants Overview
-
-A comprehensive view of all color and decoration combinations.
-
-```tsx
-<Stack direction="row" spacing={4}>
-  {([undefined, 'primary', 'warning', 'success', 'danger', 'neutral'] as const).map(color => <Stack key={color} spacing={2}>
-  <Switch color={color} />
-  <Switch color={color} checked />
-  <Switch color={color} startDecorator={<LightModeIcon />} endDecorator={<DarkModeIcon />} />
-  <Switch color={color} slotProps={{
-    input: {
-      'aria-label': 'Dark mode'
-    },
-    thumb: {
-      children: <DarkModeIcon fontSize="inherit" />
-    },
-    track: {
-      children: <React.Fragment>
-      <span>I</span>
-      <span>0</span>
-    </React.Fragment>,
-    sx: {
-      justifyContent: 'space-around'
-    }
-  }
-}} sx={{
-  '--Switch-thumbSize': '27px',
-  '--Switch-trackWidth': '52px',
-  '--Switch-trackHeight': '31px'
-}} />
-<Typography component="label" startDecorator={<Switch sx={{
-  ml: 1
-}} color={color} />}>
-Label
-</Typography>
-</Stack>)}
-</Stack>
-```
-
 ## Common Use Cases
 
 ### Settings Panel
 
-```tsx
-function SettingsPanel() {
-  const [notifications, setNotifications] = useState(true);
-  const [autoSave, setAutoSave] = useState(false);
-
-  return (
-    <Stack spacing={3}>
-      <FormControl
-        orientation="horizontal"
-        sx={{ width: 400, justifyContent: 'space-between' }}
-      >
-        <div>
-          <FormLabel>Notifications</FormLabel>
-          <FormHelperText sx={{ mt: 0 }}>
-            Receive alerts when new messages arrive.
-          </FormHelperText>
-        </div>
-        <Switch
-          checked={notifications}
-          onChange={(e) => setNotifications(e.target.checked)}
-          color={notifications ? 'success' : 'neutral'}
-        />
-      </FormControl>
+설정 패널에서 기능을 활성화/비활성화할 때 사용합니다.
 
-      <FormControl
-        orientation="horizontal"
-        sx={{ width: 400, justifyContent: 'space-between' }}
-      >
-        <div>
-          <FormLabel>Auto Save</FormLabel>
-          <FormHelperText sx={{ mt: 0 }}>
-            Automatically save your work every 30 seconds.
-          </FormHelperText>
-        </div>
-        <Switch
-          checked={autoSave}
-          onChange={(e) => setAutoSave(e.target.checked)}
-        />
-      </FormControl>
-    </Stack>
-  );
-}
+```tsx
+<Stack spacing={3}>
+  <FormControl orientation="horizontal" sx={{ width: 400, justifyContent: 'space-between' }}>
+    <div>
+      <FormLabel>알림 받기</FormLabel>
+      <FormHelperText sx={{ mt: 0 }}>새로운 메시지가 도착했을 때 알림을 받습니다.</FormHelperText>
+    </div>
+    <Switch checked={notifications} onChange={(e) => setNotifications(e.target.checked)} color="success" />
+  </FormControl>
+
+  <FormControl orientation="horizontal" sx={{ width: 400, justifyContent: 'space-between' }}>
+    <div>
+      <FormLabel>자동 저장</FormLabel>
+      <FormHelperText sx={{ mt: 0 }}>작업 내용을 자동으로 저장합니다.</FormHelperText>
+    </div>
+    <Switch checked={autoSave} onChange={(e) => setAutoSave(e.target.checked)} />
+  </FormControl>
+</Stack>
 ```
 
 ### Theme Toggle
 
+다크 모드/라이트 모드 전환에 자주 사용됩니다.
+
 ```tsx
 function ThemeToggle() {
   const [darkMode, setDarkMode] = useState(false);
@@ -252,86 +195,376 @@ function ThemeToggle() {
       startDecorator={<LightModeIcon />}
       endDecorator={<DarkModeIcon />}
       slotProps={{
-        input: { 'aria-label': 'Toggle dark mode' },
+        input: { 'aria-label': '다크 모드 토글' },
       }}
     />
   );
 }
 ```
 
-### Feature Flag with Status Text
+### Feature Flags
+
+기능의 활성화/비활성화를 제어할 때 사용합니다.
 
 ```tsx
-function FeatureToggle() {
-  const [betaEnabled, setBetaEnabled] = useState(false);
+<Card>
+  <CardContent>
+    <Typography level="title-md" sx={{ mb: 2 }}>
+      실험적 기능
+    </Typography>
 
-  return (
-    <FormControl
-      orientation="horizontal"
-      sx={{ justifyContent: 'space-between' }}
+    <Stack spacing={2}>
+      <FormControl orientation="horizontal" sx={{ justifyContent: 'space-between' }}>
+        <FormLabel>베타 기능 활성화</FormLabel>
+        <Switch
+          checked={betaFeatures}
+          onChange={(e) => setBetaFeatures(e.target.checked)}
+          color="warning"
+          endDecorator={betaFeatures ? 'On' : 'Off'}
+        />
+      </FormControl>
+
+      <FormControl orientation="horizontal" sx={{ justifyContent: 'space-between' }}>
+        <FormLabel>고급 모드</FormLabel>
+        <Switch checked={advancedMode} onChange={(e) => setAdvancedMode(e.target.checked)} disabled={!betaFeatures} />
+      </FormControl>
+    </Stack>
+  </CardContent>
+</Card>
+```
+
+### List Items with Switches
+
+목록 아이템에서 각 항목을 개별적으로 제어할 때 사용합니다.
+
+```tsx
+<List>
+  {permissions.map((permission) => (
+    <ListItem
+      key={permission.id}
+      endAction={
+        <Switch
+          checked={permission.enabled}
+          onChange={(e) => handlePermissionToggle(permission.id, e.target.checked)}
+          size="sm"
+          color={permission.enabled ? 'success' : 'neutral'}
+        />
+      }
     >
-      <FormLabel>Enable Beta Features</FormLabel>
-      <Switch
-        checked={betaEnabled}
-        onChange={(e) => setBetaEnabled(e.target.checked)}
-        color="warning"
-        endDecorator={betaEnabled ? 'On' : 'Off'}
-      />
-    </FormControl>
+      <ListItemContent>
+        <Typography level="title-sm">{permission.name}</Typography>
+        <Typography level="body-sm" color="neutral">
+          {permission.description}
+        </Typography>
+      </ListItemContent>
+    </ListItem>
+  ))}
+</List>
+```
+
+### Controlled Form
+
+폼 상태 관리와 함께 사용하는 예제입니다.
+
+```tsx
+function UserPreferences() {
+  const [preferences, setPreferences] = useState({
+    emailNotifications: true,
+    smsNotifications: false,
+    pushNotifications: true,
+    darkMode: false,
+  });
+
+  const handleToggle = (key: keyof typeof preferences) => (event: React.ChangeEvent<HTMLInputElement>) => {
+    setPreferences((prev) => ({
+      ...prev,
+      [key]: event.target.checked,
+    }));
+  };
+
+  return (
+    <form onSubmit={handleSubmit}>
+      <Stack spacing={3}>
+        <Typography level="h4">알림 설정</Typography>
+
+        <Stack spacing={2}>
+          <Typography
+            component="label"
+            endDecorator={
+              <Switch
+                checked={preferences.emailNotifications}
+                onChange={handleToggle('emailNotifications')}
+                sx={{ ml: 1 }}
+              />
+            }
+          >
+            이메일 알림
+          </Typography>
+
+          <Typography
+            component="label"
+            endDecorator={
+              <Switch
+                checked={preferences.smsNotifications}
+                onChange={handleToggle('smsNotifications')}
+                sx={{ ml: 1 }}
+              />
+            }
+          >
+            SMS 알림
+          </Typography>
+
+          <Typography
+            component="label"
+            endDecorator={
+              <Switch
+                checked={preferences.pushNotifications}
+                onChange={handleToggle('pushNotifications')}
+                sx={{ ml: 1 }}
+              />
+            }
+          >
+            푸시 알림
+          </Typography>
+        </Stack>
+
+        <Divider />
+
+        <Typography
+          component="label"
+          endDecorator={
+            <Switch
+              checked={preferences.darkMode}
+              onChange={handleToggle('darkMode')}
+              startDecorator={<LightModeIcon />}
+              endDecorator={<DarkModeIcon />}
+              sx={{ ml: 1 }}
+            />
+          }
+        >
+          다크 모드
+        </Typography>
+
+        <Button type="submit">설정 저장</Button>
+      </Stack>
+    </form>
   );
 }
 ```
 
-## Best Practices
+## Props and Customization
 
-1. **Use switches for immediate effects**: Switches should apply their change instantly without requiring a "Save" button. If the setting requires a form submission, use a checkbox instead.
+### Colors
+
+다양한 색상을 적용할 수 있습니다.
+
+```tsx
+<Stack direction="row" spacing={2}>
+  <Switch color="primary" checked />
+  <Switch color="success" checked />
+  <Switch color="warning" checked />
+  <Switch color="danger" checked />
+  <Switch color="neutral" checked />
+</Stack>
+```
+
+### Sizes
+
+스위치의 크기를 조절할 수 있습니다.
+
+```tsx
+<Stack direction="row" spacing={2} alignItems="center">
+  <Switch size="sm" checked />
+  <Switch size="md" checked />
+  <Switch size="lg" checked />
+</Stack>
+```
+
+### Variants
+
+다양한 시각적 스타일을 적용할 수 있습니다.
+
+```tsx
+<Stack direction="row" spacing={2}>
+  <Switch variant="solid" checked />
+  <Switch variant="soft" checked />
+  <Switch variant="outlined" checked />
+  <Switch variant="plain" checked />
+</Stack>
+```
+
+### Custom Styling
+
+CSS 변수를 통해 세밀한 커스터마이징이 가능합니다.
 
 ```tsx
-// ✅ Immediate effect -- toggling notifications on/off
 <Switch
-  checked={notificationsEnabled}
-  onChange={(e) => toggleNotifications(e.target.checked)}
+  checked={customSwitch}
+  onChange={(e) => setCustomSwitch(e.target.checked)}
+  sx={{
+    '--Switch-thumbSize': '24px',
+    '--Switch-trackWidth': '60px',
+    '--Switch-trackHeight': '32px',
+    '--Switch-trackRadius': '16px',
+    '--Switch-thumbRadius': '12px',
+  }}
 />
+```
+
+## States
+
+### Disabled State
 
-// ❌ Deferred effect requiring form submission -- use Checkbox instead
-<form onSubmit={handleSubmit}>
-  <Switch checked={agreed} onChange={(e) => setAgreed(e.target.checked)} />
-  <Button type="submit">Save</Button>
-</form>
+비활성 상태의 스위치입니다.
+
+```tsx
+<Stack direction="row" spacing={2}>
+  <Switch disabled />
+  <Switch disabled checked />
+</Stack>
 ```
 
-2. **Always provide a label**: Every switch needs a visible text label or an `aria-label` so users understand what it controls.
+### Loading/Processing State
+
+처리 중일 때의 시각적 피드백을 제공할 수 있습니다.
 
 ```tsx
-// ✅ Clear label via FormControl
-<FormControl orientation="horizontal">
-  <FormLabel>Email Notifications</FormLabel>
-  <Switch checked={enabled} onChange={handleChange} />
-</FormControl>
+function ProcessingSwitch() {
+  const [processing, setProcessing] = useState(false);
+  const [enabled, setEnabled] = useState(false);
+
+  const handleToggle = async (event: React.ChangeEvent<HTMLInputElement>) => {
+    setProcessing(true);
+    try {
+      // API 호출 시뮬레이션
+      await new Promise((resolve) => setTimeout(resolve, 1000));
+      setEnabled(event.target.checked);
+    } finally {
+      setProcessing(false);
+    }
+  };
 
-// ❌ No label -- unclear what the switch does
-<Switch checked={enabled} onChange={handleChange} />
+  return (
+    <Switch
+      checked={enabled}
+      onChange={handleToggle}
+      disabled={processing}
+      endDecorator={processing ? 'Processing...' : enabled ? 'On' : 'Off'}
+    />
+  );
+}
 ```
 
-3. **Use semantic colors to reinforce meaning**: Apply `color="success"` for active/enabled states and `color="danger"` for risky toggles. Avoid using color as the sole indicator -- pair it with text.
+## Best Practices
+
+1. **명확한 라벨**: 스위치가 무엇을 제어하는지 명확하게 표시하세요.
+
+```tsx
+// ✅ 명확한 라벨
+<Typography component="label" endDecorator={<Switch />}>
+  이메일 알림 받기
+</Typography>
+
+// ❌ 모호한 라벨
+<Typography component="label" endDecorator={<Switch />}>
+  설정
+</Typography>
+```
+
+2. **즉시 효과**: 스위치 토글은 즉시 효과가 나타나야 합니다.
+
+3. **적절한 색상 사용**:
+   - 일반적인 기능: `primary` 또는 기본 색상
+   - 성공/활성화: `success`
+   - 주의사항: `warning`
+   - 위험한 기능: `danger`
+
+4. **상태 표시**: 현재 상태를 명확히 보여주는 장식 요소를 활용하세요.
 
 ```tsx
-// ✅ Color + text indicator
 <Switch
   checked={enabled}
   onChange={handleChange}
+  endDecorator={enabled ? '켜짐' : '꺼짐'}
   color={enabled ? 'success' : 'neutral'}
-  endDecorator={enabled ? 'On' : 'Off'}
 />
 ```
 
-4. **Handle async operations gracefully**: If toggling triggers an API call, disable the switch and show a processing indicator until the operation completes.
+5. **그룹화**: 관련된 스위치들은 논리적으로 그룹화하세요.
 
-5. **Group related switches logically**: Place related switches under a shared heading and use consistent spacing to create a scannable settings layout.
+```tsx
+<Stack spacing={3}>
+  <Typography level="title-md">알림 설정</Typography>
+  <Stack spacing={1} sx={{ pl: 1 }}>
+    <Switch label="이메일 알림" />
+    <Switch label="SMS 알림" />
+    <Switch label="푸시 알림" />
+  </Stack>
+</Stack>
+```
 
 ## Accessibility
 
-- **Role and state**: The Switch renders an `<input type="checkbox" role="switch">` with `aria-checked` reflecting the current state. Screen readers announce it as a switch, not a checkbox.
-- **Keyboard interaction**: `Tab` moves focus to the switch. `Space` toggles the state. No additional key bindings are needed.
-- **Labeling**: Use `FormLabel`, a `<label>` wrapper (via `Typography component="label"`), or `slotProps.input['aria-label']` to provide an accessible name. Use `aria-describedby` to connect supplementary descriptions.
-- **Visual indicators beyond color**: Do not rely solely on color to communicate state. Use `endDecorator` text (e.g., "On" / "Off") or track children to ensure the state is perceivable without color vision.
+Switch 컴포넌트는 다음과 같은 접근성 기능을 제공합니다:
+
+### 키보드 탐색
+
+- **Tab**: 스위치로 포커스 이동
+- **Space**: 스위치 토글
+- **Enter**: 스위치 토글 (라벨이 연결된 경우)
+
+### ARIA 속성
+
+- `role="switch"`: 스위치 역할 정의
+- `aria-checked`: 현재 상태 표시
+- `aria-label` 또는 `aria-labelledby`: 접근 가능한 이름 제공
+
+### 추가 접근성 고려사항
+
+```tsx
+<Switch
+  slotProps={{
+    input: {
+      'aria-label': '다크 모드 활성화',
+      'aria-describedby': 'dark-mode-description',
+    },
+  }}
+/>
+<FormHelperText id="dark-mode-description">
+  화면을 어둡게 표시하여 눈의 피로를 줄입니다.
+</FormHelperText>
+```
+
+### 색상 대비 및 시각적 표시
+
+```tsx
+// 색상에만 의존하지 않고 텍스트 표시도 함께 제공
+<Switch
+  checked={enabled}
+  onChange={handleChange}
+  endDecorator={
+    <Typography level="body-xs" sx={{ minWidth: 32 }}>
+      {enabled ? 'ON' : 'OFF'}
+    </Typography>
+  }
+/>
+```
+
+## Performance Considerations
+
+1. **상태 최적화**: 불필요한 리렌더링을 방지하기 위해 상태를 적절히 관리하세요.
+
+```tsx
+// ✅ 개별 상태 관리
+const [emailNotify, setEmailNotify] = useState(false);
+const [smsNotify, setSmsNotify] = useState(false);
+
+// ❌ 전체 객체 업데이트로 인한 불필요한 리렌더링
+const [settings, setSettings] = useState({ email: false, sms: false });
+```
+
+2. **비동기 처리**: API 호출이 필요한 경우 적절한 로딩 상태를 제공하세요.
+
+3. **메모이제이션**: 복잡한 핸들러는 useCallback으로 메모이제이션하세요.
+
+Switch는 직관적이고 접근 가능한 토글 인터페이스를 제공하는 핵심 입력 컴포넌트입니다. 적절한 라벨링과 시각적 피드백을 통해 사용자 친화적인 설정 및 제어 인터페이스를 만들 수 있습니다.