@ceed/ads 1.23.3 → 1.23.4

package/dist/components/inputs/Textarea.md

@@ -2,11 +2,19 @@
 
 ## Introduction
 
-> 💡 **Use built-in form props**
+The Textarea component provides a multi-line text input field for collecting longer-form user input such as comments, descriptions, and notes. It is built on top of Joy UI's Textarea and automatically adjusts its height between `minRows` (default 2) and `maxRows` (default 4) as the user types.
+
+Textarea integrates with the form system by wrapping itself in a FormControl, supporting built-in `label`, `helperText`, and `error` props. It also supports decorators, multiple visual variants, sizes, and color themes to fit a wide range of admin UI use cases.
+
+> **Use built-in form props**
 >
 > This component natively supports form elements such as `label` and `helperText` props.
 > When building forms, use these built-in props instead of manually composing labels and helper text with Typography.
 
+## Playground
+
+Interact with the Textarea component using the controls below.
+
 ```tsx
 <Textarea name="Textarea" />
 ```
@@ -25,7 +33,26 @@
 | error          | —           | —          |
 | onChange       | —           | —          |
 
-### Variants
+## Usage
+
+```tsx
+import { Textarea } from '@ceed/ads';
+
+function MyComponent() {
+  return (
+    <Textarea
+      name="description"
+      label="Description"
+      placeholder="Enter a description..."
+      helperText="Provide a brief summary."
+    />
+  );
+}
+```
+
+## Variants
+
+Textarea supports four visual variants: `solid`, `soft`, `outlined`, and `plain`. The default variant is `outlined`.
 
 ```tsx
 <>
@@ -36,7 +63,16 @@
 </>
 ```
 
-### Sizes
+```tsx
+<Textarea variant="solid" placeholder="Solid" />
+<Textarea variant="soft" placeholder="Soft" />
+<Textarea variant="outlined" placeholder="Outlined" />
+<Textarea variant="plain" placeholder="Plain" />
+```
+
+## Sizes
+
+Textarea comes in three sizes: `sm`, `md`, and `lg`. The default size is `md`.
 
 ```tsx
 <>
@@ -46,7 +82,15 @@
 </>
 ```
 
-### Colors
+```tsx
+<Textarea size="sm" placeholder="Small" />
+<Textarea size="md" placeholder="Medium" />
+<Textarea size="lg" placeholder="Large" />
+```
+
+## Colors
+
+Textarea supports semantic colors via the `color` prop: `primary`, `neutral`, `danger`, and `warning`.
 
 ```tsx
 <>
@@ -57,13 +101,167 @@
 </>
 ```
 
-### Variants
+```tsx
+<Textarea color="primary" placeholder="Primary" />
+<Textarea color="neutral" placeholder="Neutral" />
+<Textarea color="danger" placeholder="Danger" />
+<Textarea color="warning" placeholder="Warning" />
+```
+
+## Required with Label and Helper Text
+
+Use the `required`, `label`, and `helperText` props together to build complete form fields. The `required` prop adds an asterisk indicator to the label.
 
 ```tsx
-<>
-  <Textarea name="Solid" placeholder="Type in here…" variant="solid" />
-  <Textarea name="Soft" placeholder="Type in here…" variant="soft" />
-  <Textarea name="Outlined" placeholder="Type in here…" variant="outlined" />
-  <Textarea name="Plain" placeholder="Type in here…" variant="plain" />
-</>
+<Textarea
+  name="Textarea"
+  placeholder="Type in here..."
+  helperText="I'm helper text"
+  label="Label"
+  required
+/>
 ```
+
+```tsx
+<Textarea
+  label="Label"
+  helperText="I'm helper text"
+  placeholder="Type in here..."
+  required
+/>
+```
+
+## Common Use Cases
+
+### Feedback Form
+
+```tsx
+import { Textarea, Button, Stack } from '@ceed/ads';
+
+function FeedbackForm() {
+  const [value, setValue] = React.useState('');
+
+  return (
+    <Stack spacing={2}>
+      <Textarea
+        name="feedback"
+        label="Feedback"
+        placeholder="Tell us what you think..."
+        helperText="Your feedback helps us improve the service."
+        minRows={3}
+        maxRows={6}
+        value={value}
+        onChange={(e) => setValue(e.target.value)}
+        required
+      />
+      <Button disabled={!value.trim()}>Submit</Button>
+    </Stack>
+  );
+}
+```
+
+### Error State with Validation
+
+```tsx
+import { Textarea } from '@ceed/ads';
+
+function ValidatedTextarea() {
+  const [value, setValue] = React.useState('');
+  const isError = value.length > 0 && value.length < 10;
+
+  return (
+    <Textarea
+      name="notes"
+      label="Notes"
+      placeholder="Write at least 10 characters..."
+      helperText={isError ? 'Must be at least 10 characters.' : 'Optional notes for this record.'}
+      error={isError}
+      value={value}
+      onChange={(e) => setValue(e.target.value)}
+    />
+  );
+}
+```
+
+### Disabled Read-Only Display
+
+```tsx
+import { Textarea } from '@ceed/ads';
+
+function ReadOnlyNotes() {
+  return (
+    <Textarea
+      name="archived-notes"
+      label="Archived Notes"
+      value="This record has been archived and cannot be edited."
+      disabled
+    />
+  );
+}
+```
+
+## Best Practices
+
+1. **Use built-in form props instead of manual composition.**
+
+```tsx
+// ✅ Recommended
+<Textarea label="Description" helperText="Keep it brief." />
+
+// ❌ Avoid
+<FormControl>
+  <Typography level="title-sm" component="label">Description</Typography>
+  <Textarea />
+  <Typography level="body-xs" color="neutral">Keep it brief.</Typography>
+</FormControl>
+```
+
+2. **Set appropriate `minRows` and `maxRows` for the expected content length.**
+
+```tsx
+// ✅ Short comment field
+<Textarea minRows={2} maxRows={4} placeholder="Add a comment..." />
+
+// ✅ Long description field
+<Textarea minRows={4} maxRows={10} placeholder="Write a detailed description..." />
+```
+
+3. **Always provide a `name` prop for form submission.**
+
+```tsx
+// ✅ Named textarea for form data
+<Textarea name="description" label="Description" />
+
+// ❌ Missing name — value won't be included in form data
+<Textarea label="Description" />
+```
+
+4. **Use `error` and `helperText` together for validation feedback.**
+
+```tsx
+// ✅ Clear error feedback
+<Textarea
+  error={hasError}
+  helperText={hasError ? 'This field is required.' : 'Optional description.'}
+/>
+
+// ❌ Error state without explanation
+<Textarea error />
+```
+
+5. **Use a descriptive `placeholder` to guide user input.**
+
+```tsx
+// ✅ Descriptive placeholder
+<Textarea placeholder="Describe the issue in detail..." />
+
+// ❌ Vague placeholder
+<Textarea placeholder="Type here" />
+```
+
+## Accessibility
+
+- The component automatically associates the `label` with the textarea element through FormControl, ensuring screen readers announce the label when the field receives focus.
+- When `required` is set, the field is marked with `aria-required` and a visual asterisk indicator is added to the label.
+- When `error` is set, the `helperText` is associated with the textarea via `aria-describedby`, allowing screen readers to announce the error message.
+- Use a clear and descriptive `label` for every Textarea in a form. Avoid relying solely on `placeholder` text, as it disappears once the user starts typing and is not reliably announced by all screen readers.

package/dist/components/inputs/Uploader/Uploader.md

@@ -1,6 +1,10 @@
 # Uploader
 
-Uploader 컴포넌트는 파일 업로드를 위한 컴포넌트입니다. [관련 가이드](https://www.figma.com/design/NoAOnaPiP2H2lzvRhkBnGZ/CDS-v1.1?node-id=2600-3701\&t=WLh4JrGHlzDGMeV4-0)는 figma에서도 확인할 수 있습니다.
+## Introduction
+
+Uploader is a file upload component that provides a drag-and-drop zone along with a file browser for selecting files. It handles file type validation, individual and total file size limits, minimum and maximum file count constraints, and displays uploaded file previews with delete capabilities. The component automatically generates helper text based on its configuration and surfaces clear error messages when validation rules are violated.
+
+Uploader is designed for forms where users need to attach documents, images, or other files. It supports both controlled error states via the `error` prop and internal validation that triggers automatically when files are added. A [Figma design guide](https://www.figma.com/design/NoAOnaPiP2H2lzvRhkBnGZ/CDS-v1.1?node-id=2600-3701\&t=WLh4JrGHlzDGMeV4-0) is available for reference.
 
 ```tsx
 <Uploader
@@ -23,10 +27,28 @@ Uploader 컴포넌트는 파일 업로드를 위한 컴포넌트입니다. [관
 | onChange         | —                                                                                                                                                                                                                                                                      | —        |
 | onDelete         | —                                                                                                                                                                                                                                                                      | —        |
 
-## 기본형
+## Usage
 
-필수 속성 값으로 `accept`, `maxFileTotalSize`를 받고, 해당 속성 값들을 바탕으로 기본 `helperText`가 설정됩니다.\
-생성된 `helperText`는 File dropzone 하단에 노출됩니다.
+```tsx
+import { Uploader } from '@ceed/ads';
+
+function MyForm() {
+  return (
+    <Uploader
+      accept=".png,.jpg,.pdf"
+      maxFileTotalSize={10 * 1024 * 1024}
+      maxCount={5}
+      label="Attachments"
+      onChange={(files) => console.log('Files added:', files)}
+      onDelete={(fileId) => console.log('File removed:', fileId)}
+    />
+  );
+}
+```
+
+## Default
+
+The most basic Uploader requires `accept` and `maxFileTotalSize` props. Helper text is automatically generated from these values.
 
 ```tsx
 <Uploader
@@ -35,7 +57,9 @@ Uploader 컴포넌트는 파일 업로드를 위한 컴포넌트입니다. [관
 />
 ```
 
-`label`과 함께 쓰이면 아래와 같은 모습입니다.
+## With Label
+
+Adding a `label` prop displays a title above the dropzone.
 
 ```tsx
 <Uploader
@@ -45,9 +69,9 @@ Uploader 컴포넌트는 파일 업로드를 위한 컴포넌트입니다. [관
 />
 ```
 
-## Size
+## Sizes
 
-Size는 `sm`, `md` 두 사이즈를 지원합니다.
+Two sizes are available: `sm` and `md`. Use the smaller size for compact form layouts.
 
 ```tsx
 <Stack gap={4}>
@@ -62,11 +86,20 @@ Size는 `sm`, `md` 두 사이즈를 지원합니다.
 </Stack>
 ```
 
-## Internal validation
+## File Type Restriction (Accepts)
+
+The `accept` prop controls which file types are allowed. You can specify individual extensions (`.png,.jpg`) or use wildcards (`image/*`, `video/*`, `audio/*`) that map to predefined extension sets.
+
+```tsx
+<Uploader
+  accept="image/png, image/jpeg, .pdf,.word,.txt,.doc,.docx"
+  maxFileTotalSize={31457280}
+/>
+```
 
-### Min Count
+## Min Count Validation
 
-`minCount` 값과 현재 업로드된 상태에 따라서 내부적으로 에러를 발생시킵니다.
+The `minCount` prop sets a minimum number of required files. Validation triggers on form submission.
 
 ```tsx
 <>
@@ -82,10 +115,9 @@ Size는 `sm`, `md` 두 사이즈를 지원합니다.
 </>
 ```
 
-### Max Count
+## With Uploaded Files
 
-`maxCount` 값과 현재 업로드된 상태에 따라서 내부적으로 에러를 발생시킵니다.\
-아래의 상황에서 두 개 이상의 파일을 업로드 해보세요.
+Display pre-existing uploaded files and enforce `maxCount` limits. Try uploading additional files to trigger the limit error.
 
 ```tsx
 <Uploader
@@ -105,30 +137,9 @@ Size는 `sm`, `md` 두 사이즈를 지원합니다.
 />
 ```
 
-### Accepts
-
-`accept` 속성을 이용해 특정 파일 형식만 업로드할 수 있도록 제한할 수 있습니다.\
-파일 확장자 제한을 위한 `accept`값은 필수적으로 받고 있으며, 확장자를 특정해서 사용하거나(`.png,.jpeg,.txt`) `image/*`, `video/*`, `audio/*`와 같은 값을 사용할 수 있습니다.
-
-일부 디바이스에선 MIME type을 사용해서 받을 파일을 제한하는 것이 의도와 다른 동작을 일으킬 수 있기 때문에 `image/*`, `video/*`, `audio/*`를 사용하면 내부적으로 특정 확장자 집합과 맵핑됩니다.
+## Total File Size Limit
 
-`image/*` = `.jpeg,.jpg,.png,.gif,.bmp,.tiff,.svg,.webp,.heic,.ico`\
-`video/*` = `.mp4,.avi,.mkv,.mov,.wmv,.flv,.webm,.mpeg,.3gp,.m4v`\
-`audio/*` = `.mp3,.wav,.flac,.aac,.ogg,.m4a,.wma,.aiff,.alac,.midi,.mp4`
-
-```tsx
-<Uploader
-  accept="image/png, image/jpeg, .pdf,.word,.txt,.doc,.docx"
-  maxFileTotalSize={31457280}
-/>
-```
-
-### File Size
-
-#### Total File Size
-
-`maxFileTotalSize`값으로 업로드 가능한 파일의 총 크기를 제한할 수 있습니다. `maxFileTotalSize`는 필수 속성 값입니다.\
-아래의 상황에서 1MB 이상으로 파일을 업로드 해보세요.
+The `maxFileTotalSize` prop limits the combined size of all uploaded files.
 
 ```tsx
 <Uploader
@@ -139,10 +150,9 @@ Size는 `sm`, `md` 두 사이즈를 지원합니다.
 />
 ```
 
-#### Indivisual File Size
+## Individual File Size Limit
 
-`maxFileSize`값으로 파일 하나의 최대 크기를 제한할 수 있습니다.\
-아래의 상황에서 Total 1MB 이상의 파일도 업로드 해보고, 1MB가 넘는 단일 파일도 업로드 해보세요.
+The `maxFileSize` prop limits the size of each individual file, independent of the total size limit.
 
 ```tsx
 <Uploader
@@ -156,9 +166,7 @@ Size는 `sm`, `md` 두 사이즈를 지원합니다.
 
 ## Error State
 
-### External Error
-
-`error` prop을 통해 외부에서 에러 상태를 제어할 수 있습니다. 에러 상태일 때 Uploader의 드롭존 테두리가 빨간색으로 변경됩니다.
+Use the `error` prop to externally control the error state, and `helperText` to display a custom error message.
 
 ```tsx
 <Uploader
@@ -170,9 +178,9 @@ Size는 `sm`, `md` 두 사이즈를 지원합니다.
 />
 ```
 
-### Validation Errors
+## Validation Errors
 
-다양한 검증 규칙을 위반했을 때 자동으로 발생하는 에러들을 확인해보세요:
+Demonstrates automatic validation error messages for various rule violations (file type, size, count).
 
 ```tsx
 <Stack gap={4}>
@@ -187,12 +195,9 @@ Size는 `sm`, `md` 두 사이즈를 지원합니다.
 </Stack>
 ```
 
-## Helper Text
+## Helper Text Variations
 
-### Custom Helper Text
-
-`helperText` prop을 사용하면 기본 안내 메시지 대신 사용자 정의 메시지를 표시할 수 있습니다.\
-`helperText`가 제공되면 모든 기본 안내 메시지와 에러 메시지보다 우선적으로 표시됩니다.
+Comparison of auto-generated helper text, custom helper text, and error-state helper text.
 
 ```tsx
 <Stack gap={4}>
@@ -211,28 +216,102 @@ Size는 `sm`, `md` 두 사이즈를 지원합니다.
 </Stack>
 ```
 
-## Validation
+## Disabled State
+
+The Uploader can be disabled to prevent file selection and drag-and-drop interactions.
+
+```tsx
+<Uploader
+  accept=".png"
+  maxFileTotalSize={31457280}
+  label="Click to Upload or drag file"
+  disabled
+/>
+```
+
+## Common Use Cases
+
+### Profile Photo Upload
+
+```tsx
+import { Uploader } from '@ceed/ads';
+
+function ProfilePhotoUpload() {
+  return (
+    <Uploader
+      label="Profile Photo"
+      accept="image/*"
+      maxFileTotalSize={5 * 1024 * 1024}
+      maxCount={1}
+      maxFileSize={5 * 1024 * 1024}
+      helperText="Upload a profile photo (JPG, PNG, max 5MB)"
+    />
+  );
+}
+```
+
+### Document Attachment in a Form
+
+```tsx
+import { Uploader, Stack, Button } from '@ceed/ads';
+
+function DocumentForm() {
+  return (
+    <form onSubmit={(e) => { e.preventDefault(); }}>
+      <Stack gap={3}>
+        <Uploader
+          label="Supporting Documents"
+          accept=".pdf,.doc,.docx"
+          maxFileTotalSize={30 * 1024 * 1024}
+          maxCount={10}
+          minCount={1}
+          maxFileSize={10 * 1024 * 1024}
+        />
+        <Button type="submit">Submit</Button>
+      </Stack>
+    </form>
+  );
+}
+```
+
+### Multi-Image Gallery Upload
+
+```tsx
+import { Uploader } from '@ceed/ads';
+
+function GalleryUpload({ existingImages }) {
+  return (
+    <Uploader
+      label="Gallery Images"
+      accept="image/*"
+      maxFileTotalSize={50 * 1024 * 1024}
+      maxCount={20}
+      maxFileSize={10 * 1024 * 1024}
+      uploaded={existingImages}
+      onChange={(files) => console.log('New files:', files)}
+      onDelete={(id) => console.log('Removed:', id)}
+    />
+  );
+}
+```
 
-Uploader 컴포넌트는 다양한 내부 검증 기능을 제공하며, 검증 실패 시 자동으로 에러 메시지를 표시합니다.
+## Best Practices
 
-### Error Messages
+- **Always set `maxFileTotalSize`.** This is a required prop that protects against excessively large uploads and informs users of the limit via auto-generated helper text.
 
-내부 검증에서 발생하는 에러 메시지들:
+- **Be specific with `accept`.** Use explicit extensions (`.png,.jpg,.pdf`) rather than wildcards when possible, as wildcard-to-extension mapping may vary across devices.
+  - ✔ `accept=".png,.jpg,.pdf"` -- clear and predictable
+  - ✘ `accept="*"` -- allows any file type with no validation
 
-- **파일 타입 오류**: "Please upload the correct file type."
-- **파일 크기 초과**: "One or more files exceeded the maximum file size. Each file size must be \[크기] or less."
-- **총 파일 크기 초과**: "The total file size exceeds the maximum limit."
-- **파일 개수 초과**: "Exceeded the maximum number of files."
-- **최소 파일 개수 미달**: "Please choose \[개수] files to upload." (form validation 시)
+- **Provide meaningful labels.** Use the `label` prop to clearly indicate what type of files the user should upload and in what context.
 
-### Helper Text Generation
+- **Set `maxFileSize` for individual limits.** Even if `maxFileTotalSize` is set, large individual files can cause upload failures. Use `maxFileSize` to catch oversized files early.
 
-`helperText` prop이 제공되지 않으면 다음 정보를 기반으로 자동 생성됩니다:
+- **Use `minCount` with form validation.** The minimum count check triggers on form submission, not on file selection. Make sure the Uploader is inside a `<form>` element for this validation to work.
 
-1. **허용 파일 타입**: `accept` prop 기반
-   - `image/*`, `video/*`, `audio/*` → "Any image file", "Any video file", "Any audio file"
-   - 특정 확장자 → 대문자 확장자명 나열
-2. **최대 파일 크기**: `maxFileTotalSize` prop 기반
-3. **파일 개수 제한**: `maxCount` prop 기반 (있는 경우)
+## Accessibility
 
-**예시**: "PNG, Maximum 30MB, Up to 3 files"
+- The dropzone is keyboard-accessible and can be activated via **Enter** or **Space** to open the file browser.
+- Error messages and helper text are associated with the dropzone via ARIA attributes, ensuring screen readers announce validation feedback.
+- Uploaded file items include accessible delete buttons with descriptive labels.
+- The `label` prop renders as a visible label associated with the upload control for screen reader identification.

package/dist/components/inputs/llms.txt

@@ -12,14 +12,17 @@
 - [DateRangePicker](./DateRangePicker.md)
 - [FilterableCheckboxGroup](./FilterableCheckboxGroup.md)
 - [FilterMenu](./FilterMenu.md)
+- [FormControl](./FormControl.md)
 - [IconButton](./IconButton.md)
 - [Input](./Input.md)
 - [MonthPicker](./MonthPicker.md)
 - [MonthRangePicker](./MonthRangePicker.md)
 - [PercentageInput](./PercentageInput.md)
 - [Radio](./RadioButton.md)
+- [RadioList](./RadioList.md)
 - [RadioTileGroup](./RadioTileGroup.md)
 - [Select](./Select.md)
+- [Slider](./Slider.md)
 - [Switch](./Switch.md)
 - [Textarea](./Textarea.md)