@ceed/cds 1.22.2 → 1.22.4

package/dist/components/inputs/Switch.md

@@ -2,7 +2,9 @@
 
 ## Introduction
 
-Switch 컴포넌트는 사용자가 옵션을 켜고 끌 수 있는 토글 형태의 입력 요소입니다. Joy UI의 Switch를 기반으로 하며, 다양한 크기, 색상, 장식 요소를 지원합니다. 설정 화면, 기능 활성화/비활성화, 모드 전환 등에 주로 사용됩니다.
+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.
 
 ```tsx
 <Switch />
@@ -25,23 +27,18 @@ 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)}
+    />
+  );
 }
 ```
 
-## Examples
-
-### Basic Usage
-
-가장 기본적인 Switch 사용법입니다.
-
-```tsx
-<Switch />
-```
-
-### With Labels
+## With Labels
 
-라벨과 함께 사용하는 Switch입니다. 폼 컨트롤 내에서 설명과 함께 사용할 수 있습니다.
+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.
 
 ```tsx
 <FormControl orientation="horizontal" sx={{
@@ -64,9 +61,9 @@ function MyComponent() {
 </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={{
@@ -76,9 +73,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={{
@@ -92,9 +89,9 @@ Turn alarm on
 })} />} 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}>
@@ -136,9 +133,9 @@ Turn alarm on
 </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={{
@@ -153,36 +150,96 @@ Turn alarm on
 }} />
 ```
 
+## 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
-<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>
+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>
+  );
+}
 ```
 
 ### Theme Toggle
 
-다크 모드/라이트 모드 전환에 자주 사용됩니다.
-
 ```tsx
 function ThemeToggle() {
   const [darkMode, setDarkMode] = useState(false);
@@ -195,376 +252,86 @@ function ThemeToggle() {
       startDecorator={<LightModeIcon />}
       endDecorator={<DarkModeIcon />}
       slotProps={{
-        input: { 'aria-label': '다크 모드 토글' },
+        input: { 'aria-label': 'Toggle dark mode' },
       }}
     />
   );
 }
 ```
 
-### Feature Flags
-
-기능의 활성화/비활성화를 제어할 때 사용합니다.
+### Feature Flag with Status Text
 
 ```tsx
-<Card>
-  <CardContent>
-    <Typography level="title-md" sx={{ mb: 2 }}>
-      실험적 기능
-    </Typography>
-
-    <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'}
-        />
-      }
-    >
-      <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,
-    }));
-  };
+function FeatureToggle() {
+  const [betaEnabled, setBetaEnabled] = useState(false);
 
   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>
+    <FormControl
+      orientation="horizontal"
+      sx={{ justifyContent: 'space-between' }}
+    >
+      <FormLabel>Enable Beta Features</FormLabel>
+      <Switch
+        checked={betaEnabled}
+        onChange={(e) => setBetaEnabled(e.target.checked)}
+        color="warning"
+        endDecorator={betaEnabled ? 'On' : 'Off'}
+      />
+    </FormControl>
   );
 }
 ```
 
-## Props and Customization
-
-### 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
+## Best Practices
 
-CSS 변수를 통해 세밀한 커스터마이징이 가능합니다.
+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.
 
 ```tsx
+// ✅ Immediate effect -- toggling notifications on/off
 <Switch
-  checked={customSwitch}
-  onChange={(e) => setCustomSwitch(e.target.checked)}
-  sx={{
-    '--Switch-thumbSize': '24px',
-    '--Switch-trackWidth': '60px',
-    '--Switch-trackHeight': '32px',
-    '--Switch-trackRadius': '16px',
-    '--Switch-thumbRadius': '12px',
-  }}
+  checked={notificationsEnabled}
+  onChange={(e) => toggleNotifications(e.target.checked)}
 />
-```
-
-## States
-
-### Disabled State
 
-비활성 상태의 스위치입니다.
-
-```tsx
-<Stack direction="row" spacing={2}>
-  <Switch disabled />
-  <Switch disabled checked />
-</Stack>
+// ❌ 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>
 ```
 
-### Loading/Processing State
-
-처리 중일 때의 시각적 피드백을 제공할 수 있습니다.
+2. **Always provide a label**: Every switch needs a visible text label or an `aria-label` so users understand what it controls.
 
 ```tsx
-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);
-    }
-  };
-
-  return (
-    <Switch
-      checked={enabled}
-      onChange={handleToggle}
-      disabled={processing}
-      endDecorator={processing ? 'Processing...' : enabled ? 'On' : 'Off'}
-    />
-  );
-}
-```
-
-## Best Practices
-
-1. **명확한 라벨**: 스위치가 무엇을 제어하는지 명확하게 표시하세요.
-
-```tsx
-// ✅ 명확한 라벨
-<Typography component="label" endDecorator={<Switch />}>
-  이메일 알림 받기
-</Typography>
+// ✅ Clear label via FormControl
+<FormControl orientation="horizontal">
+  <FormLabel>Email Notifications</FormLabel>
+  <Switch checked={enabled} onChange={handleChange} />
+</FormControl>
 
-// ❌ 모호한 라벨
-<Typography component="label" endDecorator={<Switch />}>
-  설정
-</Typography>
+// ❌ No label -- unclear what the switch does
+<Switch checked={enabled} onChange={handleChange} />
 ```
 
-2. **즉시 효과**: 스위치 토글은 즉시 효과가 나타나야 합니다.
-
-3. **적절한 색상 사용**:
-   - 일반적인 기능: `primary` 또는 기본 색상
-   - 성공/활성화: `success`
-   - 주의사항: `warning`
-   - 위험한 기능: `danger`
-
-4. **상태 표시**: 현재 상태를 명확히 보여주는 장식 요소를 활용하세요.
+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.
 
 ```tsx
+// ✅ Color + text indicator
 <Switch
   checked={enabled}
   onChange={handleChange}
-  endDecorator={enabled ? '켜짐' : '꺼짐'}
   color={enabled ? 'success' : 'neutral'}
+  endDecorator={enabled ? 'On' : 'Off'}
 />
 ```
 
-5. **그룹화**: 관련된 스위치들은 논리적으로 그룹화하세요.
+4. **Handle async operations gracefully**: If toggling triggers an API call, disable the switch and show a processing indicator until the operation completes.
 
-```tsx
-<Stack spacing={3}>
-  <Typography level="title-md">알림 설정</Typography>
-  <Stack spacing={1} sx={{ pl: 1 }}>
-    <Switch label="이메일 알림" />
-    <Switch label="SMS 알림" />
-    <Switch label="푸시 알림" />
-  </Stack>
-</Stack>
-```
+5. **Group related switches logically**: Place related switches under a shared heading and use consistent spacing to create a scannable settings layout.
 
 ## Accessibility
 
-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는 직관적이고 접근 가능한 토글 인터페이스를 제공하는 핵심 입력 컴포넌트입니다. 적절한 라벨링과 시각적 피드백을 통해 사용자 친화적인 설정 및 제어 인터페이스를 만들 수 있습니다.
+- **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.