@ceed/cds 1.28.0 → 1.29.0-next.1

package/dist/components/inputs/Input.md

@@ -1,10 +1,6 @@
 # Input
 
-## Introduction
-
-The Input component is a fundamental form element for capturing text input from users. It supports various visual styles, sizes, and states to accommodate different use cases across forms, search fields, and data entry interfaces.
-
-Input comes with built-in form integration features such as labels, helper text, error states, and clearable functionality. It also provides specialized behavior for password fields with an automatic visibility toggle.
+Input 컴포넌트는 사용자로부터 텍스트 입력을 받기 위한 기본 컴포넌트입니다. 다양한 스타일, 크기 및 기능을 지원합니다.
 
 ```tsx
 <Input />
@@ -33,52 +29,17 @@ Input comes with built-in form integration features such as labels, helper text,
 | sx                          | —           | —       |
 | className                   | —           | —       |
 
-> **Use built-in form props**
->
-> This component natively supports `label`, `helperText`, `error`, and `required` props.
-> When building forms, use these built-in props instead of manually composing labels and helper text with Typography or FormControl.
->
-> ```tsx
-> // Recommended: use built-in props
-> <Input label="Email" helperText="We'll never share your email." error={!isValid} />
->
-> // Not recommended: manual composition with Typography
-> <FormControl>
->   <Typography component="label">Email</Typography>
->   <Input />
->   <Typography level="body-xs">We'll never share your email.</Typography>
-> </FormControl>
-> ```
-
-## Usage
-
-```tsx
-import { Input } from '@ceed/cds';
-
-function MyComponent() {
-  return (
-    <Input
-      label="Username"
-      placeholder="Enter your username"
-      helperText="Must be at least 3 characters"
-    />
-  );
-}
-```
-
-## Examples
+## 기본형
 
-### Basic Input
-
-The default Input renders a single-line text field. Without any additional props, it uses the `outlined` variant at `md` size.
+Input의 기본 형태입니다. 사용자의 텍스트 입력을 받는 단일 라인 필드입니다.
 
 ```tsx
 <Input />
 ```
 
-### Variants
+## 변형(Variants)
 
-Input supports four visual variants: `solid`, `soft`, `outlined`, and `plain`. Use `outlined` (default) for most form contexts, and `soft` or `plain` for inline or subtle placements.
+Input은 네 가지 변형을 지원합니다: `solid`, `soft`, `outlined`, `plain`
 
 ```tsx
 <>
@@ -89,9 +50,9 @@ Input supports four visual variants: `solid`, `soft`, `outlined`, and `plain`. U
 </>
 ```
 
-### Sizes
+## 크기(Sizes)
 
-Input comes in three sizes: `sm`, `md`, and `lg`. Choose a size that fits the surrounding UI density.
+Input은 세 가지 크기를 지원합니다: `sm`, `md`, `lg`
 
 ```tsx
 <>
@@ -101,11 +62,13 @@ Input comes in three sizes: `sm`, `md`, and `lg`. Choose a size that fits the su
 </>
 ```
 
-## Label and Helper Text
+## 레이블 및 도움말 텍스트
+
+Input 컴포넌트에 `label`과 `helperText` 속성을 추가하여 사용자에게 추가 정보를 제공할 수 있습니다.
 
-### Label
+### 레이블(Label)
 
-Use the `label` prop to display a label above the Input. This is the recommended way to associate a label with the input field.
+`label` 속성을 사용하여 Input 위에 레이블을 표시할 수 있습니다.
 
 ```tsx
 <>
@@ -113,9 +76,9 @@ Use the `label` prop to display a label above the Input. This is the recommended
 </>
 ```
 
-### Helper Text
+### 도움말 텍스트(Helper Text)
 
-Use the `helperText` prop to provide additional guidance below the Input.
+`helperText` 속성을 사용하여 Input 아래에 추가 정보를 제공할 수 있습니다.
 
 ```tsx
 <>
@@ -123,19 +86,19 @@ Use the `helperText` prop to provide additional guidance below the Input.
 </>
 ```
 
-## States
+## 상태(States)
 
-### Disabled
+### 비활성화(Disabled)
 
-Set `disabled` to prevent user interaction. Disabled inputs are visually dimmed and do not receive focus.
+`disabled` 속성을 사용하여 Input을 비활성화할 수 있습니다.
 
 ```tsx
 <Input disabled />
 ```
 
-### Error
+### 오류 상태(Error)
 
-Set `error` to indicate a validation failure. Combine with `helperText` to explain the error.
+`error` 속성을 사용하여 오류 상태를 표시할 수 있습니다.
 
 ```tsx
 <>
@@ -143,9 +106,9 @@ Set `error` to indicate a validation failure. Combine with `helperText` to expla
 </>
 ```
 
-### Required
+### 필수 값(Required)
 
-Set `required` to mark the field as mandatory. This adds a visual indicator to the label.
+`required` 속성을 사용하여 필수 입력 필드임을 표시할 수 있습니다.
 
 ```tsx
 <Input
@@ -156,20 +119,9 @@ Set `required` to mark the field as mandatory. This adds a visual indicator to t
 />
 ```
 
-## Form Control
-
-Combine `label`, `helperText`, and `error` props to build a complete form control. This is the recommended pattern for form fields.
-
-```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 />
-</>
-```
-
-## Decorators
+## 장식자(Decorators)
 
-Use `startDecorator` and `endDecorator` to place icons, buttons, or other elements at the start and end of the input field.
+Input 컴포넌트는 `startDecorator`와 `endDecorator` 속성을 통해 입력 필드의 시작과 끝 부분에 아이콘, 버튼 또는 기타 요소를 추가할 수 있습니다.
 
 ```tsx
 <Stack spacing={3}>
@@ -209,7 +161,7 @@ width: 300
 </Stack>
 ```
 
-When using `endDecorator` together with `enableClearable`, the clear button is placed before the end decorator:
+`endDecorator`와 `enableClearable`을 함께 사용하면 다음과 같습니다:
 
 ```tsx
 <Input
@@ -220,9 +172,9 @@ When using `endDecorator` together with `enableClearable`, the clear button is p
 />
 ```
 
-## Clearable Input
+## 지울 수 있는 입력(Clearable Input)
 
-Set `enableClearable` to show a clear button when the input has a value. Clicking the button clears the input and returns focus to the field.
+`enableClearable` 속성을 사용하여 Input에 내용을 지울 수 있는 버튼을 추가할 수 있습니다.
 
 ```tsx
 <>
@@ -230,9 +182,9 @@ Set `enableClearable` to show a clear button when the input has a value. Clickin
 </>
 ```
 
-## Password Input
+## 비밀번호 입력(Password Input)
 
-Setting `type="password"` automatically adds a visibility toggle button, allowing users to reveal or hide their password.
+`type="password"` 속성을 사용하면 비밀번호 입력 필드가 생성되며, 자동으로 비밀번호 표시/숨김 토글 버튼이 추가됩니다.
 
 ```tsx
 <Stack spacing={3}>
@@ -247,168 +199,85 @@ Setting `type="password"` automatically adds a visibility toggle button, allowin
 </Stack>
 ```
 
-### Password Limitations
+### 비밀번호 토글 비활성화
 
-When `type="password"` is used, the `endDecorator` prop is not supported because the password toggle button occupies that position.
+비밀번호 입력 필드의 토글 버튼은 `disableTogglePasswordButton` 속성을 사용하여 비활성화할 수 있습니다.
 
 ```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>
+  <Typography level="body-md">Default password input with toggle button:</Typography>
   <Input {...args} placeholder="Enter password" type="password" label="Password" />
-</Stack>
-```
 
-## State Management
-
-### Controlled Component
-
-Use `value` and `onChange` to manage the input state externally. This is useful when you need to synchronize the value with other components or perform validation on change.
+  <Typography level="body-md">Disabled password input:</Typography>
+  <Input {...args} placeholder="Enter password" type="password" label="Disabled Password" disabled />
 
-```tsx
-<>
-  <Input placeholder="Type in here…" label="Label" enableClearable value={value} onChange={handleChange} />
-</>
+  <Typography level="body-md">Password input with toggle button disabled:</Typography>
+  <Input {...args} placeholder="Enter password" type="password" label="No Toggle" disableTogglePasswordButton />
+</Stack>
 ```
 
-### Uncontrolled Component
+### 비밀번호 입력의 제한 사항
 
-Use `defaultValue` for simpler cases where you do not need to track the value in state. The input manages its own value internally.
+비밀번호 입력 필드(`type="password"`)에서는 `endDecorator`를 사용할 수 없습니다. 이는 비밀번호 토글 버튼이 해당 위치를 차지하기 때문입니다.
 
 ```tsx
-<Input defaultValue="Initial text" placeholder="Type in here..." />
+<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>
 ```
 
-## Common Use Cases
+## 폼 컨트롤(Form Control)
 
-### Login Form
+Input 컴포넌트는 `label`, `helperText`, `error` 속성을 조합하여 완전한 폼 컨트롤을 구성할 수 있습니다.
 
 ```tsx
-function LoginForm() {
-  const [email, setEmail] = useState('');
-  const [password, setPassword] = useState('');
-
-  return (
-    <Stack spacing={2}>
-      <Input
-        label="Email"
-        type="email"
-        placeholder="you@example.com"
-        required
-        value={email}
-        onChange={(e) => setEmail(e.target.value)}
-      />
-      <Input
-        label="Password"
-        type="password"
-        placeholder="Enter your password"
-        required
-        value={password}
-        onChange={(e) => setPassword(e.target.value)}
-      />
-      <Button type="submit">Sign In</Button>
-    </Stack>
-  );
-}
+<>
+  <Input placeholder="Type in here..." helperText="I'm helper text" label="Label" />
+  <Input placeholder="Invalid input" helperText="I'm helper text" label="Label" error />
+</>
 ```
 
-### Search Field with Clear
+## 상태 관리
 
-```tsx
-function SearchField({ onSearch }) {
-  const [query, setQuery] = useState('');
-
-  return (
-    <Input
-      placeholder="Search..."
-      startDecorator={<SearchIcon />}
-      enableClearable
-      value={query}
-      onChange={(e) => {
-        setQuery(e.target.value);
-        onSearch(e.target.value);
-      }}
-    />
-  );
-}
-```
+### 제어 컴포넌트(Controlled Component)
 
-### Form with Validation
+Input은 React의 제어 컴포넌트로 사용할 수 있습니다. `value`와 `onChange` 속성을 사용하여 상태를 관리합니다.
 
 ```tsx
-function ProfileForm() {
-  const [name, setName] = useState('');
-  const [submitted, setSubmitted] = useState(false);
-  const hasError = submitted && name.trim().length === 0;
-
-  return (
-    <Stack spacing={2}>
-      <Input
-        label="Full Name"
-        required
-        placeholder="John Doe"
-        value={name}
-        onChange={(e) => setName(e.target.value)}
-        error={hasError}
-        helperText={hasError ? 'Name is required' : 'Enter your legal name'}
-      />
-      <Button onClick={() => setSubmitted(true)}>Save</Button>
-    </Stack>
-  );
-}
+<>
+  <Input placeholder="Type in here…" label="Label" enableClearable value={value} onChange={handleChange} />
+</>
 ```
 
-## Best Practices
+### 비제어 컴포넌트(Uncontrolled Component)
 
-1. **Always provide a label**: Every input should have a visible label so users understand what to enter.
+`defaultValue` 속성을 사용하여 비제어 컴포넌트로도 사용 가능합니다.
 
-```tsx
-// ✅ Good: clear label
-<Input label="Email address" placeholder="you@example.com" />
+## 접근성(Accessibility)
 
-// ❌ Bad: placeholder only, no label
-<Input placeholder="Email address" />
-```
+Input 컴포넌트는 웹 접근성 표준을 준수합니다:
 
-2. **Use helper text for guidance, error text for problems**: Provide contextual help via `helperText`, and switch to error messaging when validation fails.
+- 적절한 레이블과 연결되어 있습니다.
+- 키보드 탐색이 가능합니다.
+- 오류 상태는 시각적으로 명확하게 표시됩니다.
 
-```tsx
-// ✅ Good: helpful context + error state
-<Input
-  label="Password"
-  type="password"
-  helperText={hasError ? 'Must be at least 8 characters' : 'Choose a strong password'}
-  error={hasError}
-/>
+## 테스팅(Testing)
 
-// ❌ Bad: no guidance at all
-<Input label="Password" type="password" />
-```
+### Testing Library 참고사항
 
-3. **Choose the right input type**: Use `type` to match the expected data (e.g., `email`, `tel`, `password`, `number`). This enables appropriate browser behavior and mobile keyboards.
+- `type="password"` 속성을 가진 Input을 Testing Library로 찾을 때는 항상 `textbox` 역할(role)로 찾아야 합니다.
+- 이는 ARIA 명세에 따라 `password` 입력이 특별한 role을 갖지 않고 기본적으로 `textbox` role을 사용하기 때문입니다.
 
 ```tsx
-// ✅ Good: appropriate type for email
-<Input label="Email" type="email" />
-
-// ❌ Bad: generic text type for email
-<Input label="Email" type="text" />
+// 비밀번호 입력 필드를 찾는 예시
+const passwordInput = screen.getByRole('textbox', { name: /비밀번호/i });
 ```
 
-4. **Use `enableClearable` for search and filter inputs**: Allow users to quickly reset their input in search and filter contexts.
-
-5. **Use built-in form props instead of manual composition**: Prefer `label`, `helperText`, `error`, and `required` props over wrapping with FormControl and Typography. This ensures consistent spacing, accessibility, and error handling.
-
-## Accessibility
+**참고 이슈:**
 
-- **Label association**: The `label` prop automatically creates a properly associated `<label>` element. If you cannot use the `label` prop, provide an `aria-label` or `aria-labelledby` attribute.
-- **Error announcement**: When `error` is set, the error state is conveyed to assistive technologies via `aria-invalid`. Combine with descriptive `helperText` so screen readers can announce the error message.
-- **Keyboard interaction**: Input supports standard keyboard behavior. The clear button and password toggle are focusable and can be activated with Enter or Space.
-- **Testing note**: When using Testing Library, find a `type="password"` input using the `textbox` role, as ARIA does not define a separate `password` role.
-
-```tsx
-// Finding a password input in tests
-const passwordInput = screen.getByRole('textbox', { name: /password/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)