@ceed/cds 1.24.1-next.3 → 1.25.0

package/dist/components/inputs/Input.md

@@ -1,6 +1,10 @@
 # Input
 
-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.
 
 ```tsx
 <Input />
@@ -29,17 +33,52 @@ Input 컴포넌트는 사용자로부터 텍스트 입력을 받기 위한 기
 | 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
 
-Input의 기본 형태입니다. 사용자의 텍스트 입력을 받는 단일 라인 필드입니다.
+### Basic Input
+
+The default Input renders a single-line text field. Without any additional props, it uses the `outlined` variant at `md` size.
 
 ```tsx
 <Input />
 ```
 
-## 변형(Variants)
+### Variants
 
-Input은 네 가지 변형을 지원합니다: `solid`, `soft`, `outlined`, `plain`
+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.
 
 ```tsx
 <>
@@ -50,9 +89,9 @@ Input은 네 가지 변형을 지원합니다: `solid`, `soft`, `outlined`, `pla
 </>
 ```
 
-## 크기(Sizes)
+### Sizes
 
-Input은 세 가지 크기를 지원합니다: `sm`, `md`, `lg`
+Input comes in three sizes: `sm`, `md`, and `lg`. Choose a size that fits the surrounding UI density.
 
 ```tsx
 <>
@@ -62,13 +101,11 @@ Input은 세 가지 크기를 지원합니다: `sm`, `md`, `lg`
 </>
 ```
 
-## 레이블 및 도움말 텍스트
-
-Input 컴포넌트에 `label`과 `helperText` 속성을 추가하여 사용자에게 추가 정보를 제공할 수 있습니다.
+## Label and Helper Text
 
-### 레이블(Label)
+### Label
 
-`label` 속성을 사용하여 Input 위에 레이블을 표시할 수 있습니다.
+Use the `label` prop to display a label above the Input. This is the recommended way to associate a label with the input field.
 
 ```tsx
 <>
@@ -76,9 +113,9 @@ Input 컴포넌트에 `label`과 `helperText` 속성을 추가하여 사용자
 </>
 ```
 
-### 도움말 텍스트(Helper Text)
+### Helper Text
 
-`helperText` 속성을 사용하여 Input 아래에 추가 정보를 제공할 수 있습니다.
+Use the `helperText` prop to provide additional guidance below the Input.
 
 ```tsx
 <>
@@ -86,19 +123,19 @@ Input 컴포넌트에 `label`과 `helperText` 속성을 추가하여 사용자
 </>
 ```
 
-## 상태(States)
+## States
 
-### 비활성화(Disabled)
+### Disabled
 
-`disabled` 속성을 사용하여 Input을 비활성화할 수 있습니다.
+Set `disabled` to prevent user interaction. Disabled inputs are visually dimmed and do not receive focus.
 
 ```tsx
 <Input disabled />
 ```
 
-### 오류 상태(Error)
+### Error
 
-`error` 속성을 사용하여 오류 상태를 표시할 수 있습니다.
+Set `error` to indicate a validation failure. Combine with `helperText` to explain the error.
 
 ```tsx
 <>
@@ -106,9 +143,9 @@ Input 컴포넌트에 `label`과 `helperText` 속성을 추가하여 사용자
 </>
 ```
 
-### 필수 값(Required)
+### Required
 
-`required` 속성을 사용하여 필수 입력 필드임을 표시할 수 있습니다.
+Set `required` to mark the field as mandatory. This adds a visual indicator to the label.
 
 ```tsx
 <Input
@@ -119,9 +156,20 @@ Input 컴포넌트에 `label`과 `helperText` 속성을 추가하여 사용자
 />
 ```
 
-## 장식자(Decorators)
+## 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
 
-Input 컴포넌트는 `startDecorator`와 `endDecorator` 속성을 통해 입력 필드의 시작과 끝 부분에 아이콘, 버튼 또는 기타 요소를 추가할 수 있습니다.
+Use `startDecorator` and `endDecorator` to place icons, buttons, or other elements at the start and end of the input field.
 
 ```tsx
 <Stack spacing={3}>
@@ -161,7 +209,7 @@ width: 300
 </Stack>
 ```
 
-`endDecorator`와 `enableClearable`을 함께 사용하면 다음과 같습니다:
+When using `endDecorator` together with `enableClearable`, the clear button is placed before the end decorator:
 
 ```tsx
 <Input
@@ -172,9 +220,9 @@ width: 300
 />
 ```
 
-## 지울 수 있는 입력(Clearable Input)
+## Clearable Input
 
-`enableClearable` 속성을 사용하여 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.
 
 ```tsx
 <>
@@ -182,26 +230,9 @@ width: 300
 </>
 ```
 
-## 비밀번호 입력(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>
-```
-
-### 비밀번호 토글 비활성화
+## Password Input
 
-비밀번호 입력 필드의 토글 버튼은 `disableTogglePasswordButton` 속성을 사용하여 비활성화할 수 있습니다.
+Setting `type="password"` automatically adds a visibility toggle button, allowing users to reveal or hide their password.
 
 ```tsx
 <Stack spacing={3}>
@@ -216,9 +247,9 @@ width: 300
 </Stack>
 ```
 
-### 비밀번호 입력의 제한 사항
+### Password Limitations
 
-비밀번호 입력 필드(`type="password"`)에서는 `endDecorator`를 사용할 수 없습니다. 이는 비밀번호 토글 버튼이 해당 위치를 차지하기 때문입니다.
+When `type="password"` is used, the `endDecorator` prop is not supported because the password toggle button occupies that position.
 
 ```tsx
 <Stack spacing={3}>
@@ -230,54 +261,154 @@ width: 300
 </Stack>
 ```
 
-## 폼 컨트롤(Form Control)
+## State Management
 
-Input 컴포넌트는 `label`, `helperText`, `error` 속성을 조합하여 완전한 폼 컨트롤을 구성할 수 있습니다.
+### 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.
 
 ```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 />
+  <Input placeholder="Type in here…" label="Label" enableClearable value={value} onChange={handleChange} />
 </>
 ```
 
-## 상태 관리
+### 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.
+
+```tsx
+<Input defaultValue="Initial text" placeholder="Type in here..." />
+```
 
-### 제어 컴포넌트(Controlled Component)
+## Common Use Cases
 
-Input은 React의 제어 컴포넌트로 사용할 수 있습니다. `value`와 `onChange` 속성을 사용하여 상태를 관리합니다.
+### Login Form
 
 ```tsx
-<>
-  <Input placeholder="Type in here…" label="Label" enableClearable value={value} onChange={handleChange} />
-</>
+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>
+  );
+}
 ```
 
-### 비제어 컴포넌트(Uncontrolled Component)
+### Search Field with Clear
 
-`defaultValue` 속성을 사용하여 비제어 컴포넌트로도 사용 가능합니다.
+```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);
+      }}
+    />
+  );
+}
+```
 
-## 접근성(Accessibility)
+### Form with Validation
 
-Input 컴포넌트는 웹 접근성 표준을 준수합니다:
+```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>
+  );
+}
+```
 
-- 적절한 레이블과 연결되어 있습니다.
-- 키보드 탐색이 가능합니다.
-- 오류 상태는 시각적으로 명확하게 표시됩니다.
+## Best Practices
 
-## 테스팅(Testing)
+1. **Always provide a label**: Every input should have a visible label so users understand what to enter.
 
-### Testing Library 참고사항
+```tsx
+// ✅ Good: clear label
+<Input label="Email address" placeholder="you@example.com" />
 
-- `type="password"` 속성을 가진 Input을 Testing Library로 찾을 때는 항상 `textbox` 역할(role)로 찾아야 합니다.
-- 이는 ARIA 명세에 따라 `password` 입력이 특별한 role을 갖지 않고 기본적으로 `textbox` role을 사용하기 때문입니다.
+// ❌ Bad: placeholder only, no label
+<Input placeholder="Email address" />
+```
+
+2. **Use helper text for guidance, error text for problems**: Provide contextual help via `helperText`, and switch to error messaging when validation fails.
 
 ```tsx
-// 비밀번호 입력 필드를 찾는 예시
-const passwordInput = screen.getByRole('textbox', { name: /비밀번호/i });
+// ✅ Good: helpful context + error state
+<Input
+  label="Password"
+  type="password"
+  helperText={hasError ? 'Must be at least 8 characters' : 'Choose a strong password'}
+  error={hasError}
+/>
+
+// ❌ Bad: no guidance at all
+<Input label="Password" type="password" />
 ```
 
-**참고 이슈:**
+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.
+
+```tsx
+// ✅ Good: appropriate type for email
+<Input label="Email" type="email" />
 
-- [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)
+// ❌ Bad: generic text type for email
+<Input label="Email" type="text" />
+```
+
+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 });
+```