@ceed/ads 1.29.0 → 1.30.0-next.1

package/dist/components/inputs/RadioTileGroup.md

@@ -1,15 +1,6 @@
 # RadioTileGroup
 
-## Introduction
-
-RadioTileGroup is a selection component that displays radio options as visually distinct tiles. Unlike a standard radio button list, each option occupies a tile card, making selections more prominent and scannable. This is especially useful for choices that benefit from visual emphasis, such as plan selection, category picking, or preference surveys.
-
-The component supports flexible layouts (horizontal, grid, vertical), icons via `startDecorator`, three sizes, and built-in form integration with `label`, `helperText`, `error`, and `required` props. It works in both controlled and uncontrolled modes.
-
-> **Form 구성 시 내장 prop 사용을 권장합니다**
->
-> 이 컴포넌트는 `label`, `helperText` 등의 Form 요소를 자체적으로 지원합니다.
-> Form을 구성할 때 Typography로 별도의 label이나 helperText를 만드는 대신, 컴포넌트의 내장 prop을 사용하세요.
+RadioTileGroup 컴포넌트는 타일 형태의 라디오 옵션을 표시하는 컴포넌트입니다. 각 옵션이 타일 형태로 나타나며, 사용자가 선택할 수 있습니다.
 
 ```tsx
 <RadioTileGroup
@@ -37,36 +28,18 @@ The component supports flexible layouts (horizontal, grid, vertical), icons via
 | error        | —           | —             |
 | required     | —           | —             |
 
-## Usage
+## 기본형
+
+RadioTileGroup의 기본 형태입니다. 필수 속성 값으로 `options`를 받으며, 각 옵션은 `value`와 `label`을 포함해야 합니다.
 
 ```tsx
-import { RadioTileGroup } from '@ceed/ads';
-
-function MyComponent() {
-  const [value, setValue] = useState('');
-
-  const options = [
-    { value: 'option1', label: 'Option 1' },
-    { value: 'option2', label: 'Option 2' },
-    { value: 'option3', label: 'Option 3' },
-  ];
-
-  return (
-    <RadioTileGroup
-      label="Choose an option"
-      helperText="Select one of the options below"
-      options={options}
-      value={value}
-      onChange={(e) => setValue(e.target.value)}
-      useIndicator
-    />
-  );
-}
+<RadioTileGroup
+  options={simpleOptions}
+  useIndicator
+/>
 ```
 
-## Label and Helper Text
-
-Use the `label` and `helperText` props to add descriptive text above and below the tile group. The `required` prop appends a required indicator to the label.
+`label`과 `helperText`를 함께 사용하면 아래와 같은 모습입니다.
 
 ```tsx
 <RadioTileGroup
@@ -77,6 +50,10 @@ Use the `label` and `helperText` props to add descriptive text above and below t
 />
 ```
 
+## 필수 값 표시
+
+`required` 속성을 사용하여 필수 입력 필드임을 표시할 수 있습니다.
+
 ```tsx
 <RadioTileGroup
   options={simpleOptions}
@@ -87,11 +64,11 @@ Use the `label` and `helperText` props to add descriptive text above and below t
 />
 ```
 
-## Layout Options
+## 레이아웃 옵션
 
 ### Flex
 
-Enable the `flex` prop to make tiles stretch and fill all available horizontal space equally.
+`flex` 속성을 활성화하면 RadioTileGroup이 사용 가능한 공간을 균등하게 채웁니다.
 
 ```tsx
 <RadioTileGroup
@@ -103,7 +80,7 @@ Enable the `flex` prop to make tiles stretch and fill all available horizontal s
 
 ### Columns
 
-Use the `columns` prop to arrange tiles in a specific number of columns using a grid layout.
+`columns` 속성을 사용하여 타일을 특정 열 수로 배치할 수 있습니다.
 
 ```tsx
 <RadioTileGroup
@@ -113,9 +90,9 @@ Use the `columns` prop to arrange tiles in a specific number of columns using a
 />
 ```
 
-### Flex with Columns
+### Flex와 Columns 함께 사용
 
-Combine `flex` and `columns` to create a grid where each tile stretches to fill its column width evenly.
+`flex`와 `columns` 속성을 함께 사용하여 타일이 균등하게 공간을 채우면서 특정 열 수로 배치할 수 있습니다.
 
 ```tsx
 <Box sx={{
@@ -131,9 +108,9 @@ Flex with Columns
 </Box>
 ```
 
-### Vertical Layout
+### 수직 레이아웃
 
-Set `columns={1}` to stack tiles vertically. This layout is well-suited for list-style selections like pricing plans or step-by-step options.
+`columns: 1`로 설정하면 타일이 수직으로 쌓이는 레이아웃을 만들 수 있습니다.
 
 ```tsx
 <Box sx={{
@@ -149,9 +126,9 @@ Vertical Layout (columns: 1)
 </Box>
 ```
 
-## Text Alignment
+## 정렬 옵션
 
-The `textAlign` prop controls the alignment of content inside each tile. The default is `center`. Set it to `start` for left-aligned content.
+`textAlign` 속성을 사용하여 타일 내부의 콘텐츠 정렬 방식을 설정할 수 있습니다. 기본값은 `center`이며, `start`로 설정하면 텍스트가 왼쪽으로 정렬됩니다.
 
 ```tsx
 <Box sx={{
@@ -180,9 +157,9 @@ The `textAlign` prop controls the alignment of content inside each tile. The def
 </Box>
 ```
 
-## Sizes
+## Size
 
-RadioTileGroup supports three sizes: `sm` (default), `md`, and `lg`. Choose the size that best fits the density of your layout.
+RadioTileGroup은 세 가지 크기를 지원합니다: `sm`, `md`, `lg`. 기본값은 `sm`입니다.
 
 ```tsx
 <Box sx={{
@@ -219,9 +196,9 @@ RadioTileGroup supports three sizes: `sm` (default), `md`, and `lg`. Choose the
 </Box>
 ```
 
-## Icons
+## 아이콘 사용
 
-Add icons to tiles using the `startDecorator` property on each option. Icons help users visually distinguish between choices at a glance.
+각 옵션에 `startDecorator` 속성을 사용하여 아이콘을 추가할 수 있습니다.
 
 ```tsx
 <RadioTileGroup
@@ -242,11 +219,11 @@ Add icons to tiles using the `startDecorator` property on each option. Icons hel
 />
 ```
 
-## State Management
+## 상태 관리
 
-### Controlled
+### Controlled Component
 
-Pass `value` and `onChange` to fully control the selected state from the parent component. This is recommended when the selection participates in form state or triggers side effects.
+RadioTileGroup은 상태 관리를 위한 제어 컴포넌트(Controlled Component)로 사용할 수 있습니다.
 
 ```tsx
 <Box sx={{
@@ -262,9 +239,9 @@ Selected value: {selectedValue}
 </Box>
 ```
 
-### Uncontrolled
+### Uncontrolled Component
 
-Use `defaultValue` to set an initial selection without managing state externally. The component tracks its own selection internally.
+또한 비제어 컴포넌트(Uncontrolled Component)로도 사용 가능합니다.
 
 ```tsx
 <Box sx={{
@@ -297,11 +274,11 @@ Uncontrolled Example (without Indicator)
 </Box>
 ```
 
-## Disabled State
+## 비활성화 상태
 
-### Fully Disabled
+### 전체 비활성화
 
-Set the `disabled` prop on the group to disable all tiles.
+`disabled` 속성을 사용하여 모든 옵션을 비활성화할 수 있습니다.
 
 ```tsx
 <RadioTileGroup
@@ -310,9 +287,9 @@ Set the `disabled` prop on the group to disable all tiles.
 />
 ```
 
-### Individual Disabled
+### 개별 옵션 비활성화
 
-Set `disabled: true` on specific option objects to disable only those tiles while keeping the rest interactive.
+각 옵션별로 `disabled` 속성을 설정하여 특정 옵션만 비활성화할 수 있습니다.
 
 ```tsx
 <RadioTileGroup
@@ -330,9 +307,11 @@ Set `disabled: true` on specific option objects to disable only those tiles whil
 />
 ```
 
-## Error State
+## 상태 표시
+
+### 오류 상태
 
-Use the `error` prop to indicate validation errors. Pair it with `helperText` to communicate the issue to the user.
+`error` 속성을 사용하여 오류 상태를 표시할 수 있습니다.
 
 ```tsx
 <RadioTileGroup
@@ -344,9 +323,9 @@ Use the `error` prop to indicate validation errors. Pair it with `helperText` to
 />
 ```
 
-### Form Validation Example
+### 필수 값 검증 예제
 
-Combine `required`, `error`, and `helperText` to build a complete form validation flow. The example below validates that the user has made a selection before submitting.
+`required` 속성과 함께 오류 상태를 활용하여 필수 값 검증을 할 수 있습니다. 아래는 폼 제출 시 유효성 검사를 포함한 예제입니다.
 
 ```tsx
 <Stack spacing={2} sx={{
@@ -363,32 +342,11 @@ Combine `required`, `error`, and `helperText` to build a complete form validatio
 </Stack>
 ```
 
-## Common Use Cases
-
-### Shipping Method Selection
+## 활용 사례
 
-Display delivery options with icons so users can choose intuitively.
+### 배송 방법 선택
 
-```tsx
-import { RadioTileGroup } from '@ceed/ads';
-import HomeIcon from '@mui/icons-material/Home';
-import LocalShippingIcon from '@mui/icons-material/LocalShipping';
-import BusinessIcon from '@mui/icons-material/Business';
-
-<RadioTileGroup
-  label="Shipping Method"
-  helperText="Delivery fees may vary by method."
-  options={[
-    { value: 'standard', label: 'Standard', startDecorator: <HomeIcon /> },
-    { value: 'express', label: 'Express', startDecorator: <LocalShippingIcon /> },
-    { value: 'business', label: 'Business', startDecorator: <BusinessIcon /> },
-  ]}
-  value={selected}
-  onChange={(e) => setSelected(e.target.value)}
-  size="md"
-  useIndicator
-/>
-```
+RadioTileGroup은 배송 방법을 시각적으로 선택할 수 있는 인터페이스로 활용할 수 있습니다. 각 타일에 아이콘과 함께 배송 방법 정보를 표시하여 사용자가 직관적으로 선택할 수 있도록 합니다.
 
 ```tsx
 <Box sx={{
@@ -411,25 +369,9 @@ import BusinessIcon from '@mui/icons-material/Business';
 </Box>
 ```
 
-### Survey / Preference Selection
+### 설문조사
 
-Present survey options with icons in a multi-column grid for a clear, scannable layout.
-
-```tsx
-<RadioTileGroup
-  label="What type of exercise do you prefer?"
-  options={[
-    { value: 'cardio', label: 'Cardio', startDecorator: <DirectionsRunIcon /> },
-    { value: 'strength', label: 'Strength', startDecorator: <FitnessCenterIcon /> },
-    { value: 'flexibility', label: 'Flexibility', startDecorator: <SelfImprovementIcon /> },
-    { value: 'balance', label: 'Balance', startDecorator: <BalanceIcon /> },
-  ]}
-  columns={2}
-  size="md"
-  value={selected}
-  onChange={(e) => setSelected(e.target.value)}
-/>
-```
+설문조사나 선호도 조사에서 다양한 선택지를 제공하는 데 활용할 수 있습니다. 각 타일에 선택지를 시각적으로 표현하여 사용자가 직관적으로 응답할 수 있도록 합니다.
 
 ```tsx
 <Box sx={{
@@ -456,52 +398,21 @@ Present survey options with icons in a multi-column grid for a clear, scannable
 </Box>
 ```
 
-### Pricing Plan Picker
-
-Use a vertical layout with `columns={1}` for plan or tier selection.
-
-```tsx
-<RadioTileGroup
-  label="Subscription Plan"
-  helperText="Select your preferred plan"
-  options={[
-    { value: 'basic', label: 'Basic Plan', startDecorator: <AttachMoneyIcon /> },
-    { value: 'pro', label: 'Pro Plan', startDecorator: <AttachMoneyIcon /> },
-    { value: 'premium', label: 'Premium Plan', startDecorator: <StarIcon /> },
-  ]}
-  columns={1}
-  size="md"
-  useIndicator
-  value={selected}
-  onChange={(e) => setSelected(e.target.value)}
-/>
-```
-
-## Best Practices
+### 폼 검증과 함께 사용
 
-1. **Use built-in form props instead of external labels.** The component's `label`, `helperText`, `required`, and `error` props ensure consistent layout and accessibility. Avoid wrapping with separate Typography elements.
+폼 검증 기능과 함께 사용하여 사용자가 필수 항목을 선택했는지 확인할 수 있습니다.
 
 ```tsx
-// ✅ Recommended
-<RadioTileGroup label="Select option" helperText="Required field" required />
-
-// ❌ Avoid
-<Typography>Select option</Typography>
-<RadioTileGroup options={options} />
-<Typography color="danger">Required field</Typography>
+<Stack spacing={2} sx={{
+  width: '100%',
+  maxWidth: 500
+}}>
+<RadioTileGroup options={simpleOptions} value={selectedValue} onChange={handleChange} label="Choose your preferred option" helperText={error ? 'Please select an option' : 'This selection is required'} error={error} useIndicator={true} required={true} />
+<Box sx={{
+  display: 'flex',
+  justifyContent: 'flex-end'
+}}>
+<Button onClick={handleSubmit}>Submit</Button>
+</Box>
+</Stack>
 ```
-
-2. **Choose the right layout for the number of options.** Use the default horizontal flow for 2-4 options. Use `columns` for 5+ options. Use `columns={1}` when each option has long labels or descriptions.
-
-3. **Prefer controlled mode in forms.** When RadioTileGroup is part of a form with validation or submission logic, use `value` and `onChange` for predictable state management.
-
-4. **Add icons only when they aid comprehension.** Icons via `startDecorator` are helpful for visually distinct categories (e.g., shipping methods). Avoid decorating every option if icons do not add meaning.
-
-5. **Always provide an error message.** When `error` is true, update `helperText` to explain the validation issue so users know how to fix it.
-
-## Accessibility
-
-- RadioTileGroup renders a `<fieldset>` with a `<legend>` derived from the `label` prop, providing proper grouping for screen readers.
-- Each tile is backed by a native `<input type="radio">`, ensuring full keyboard navigation (arrow keys to move between options, Space/Enter to select).
-- The `disabled` prop correctly applies `aria-disabled` semantics to prevent interaction while keeping elements discoverable by assistive technologies.
-- When `error` is set, pair it with descriptive `helperText` so that screen readers can announce the validation message via `aria-describedby`.

package/dist/components/inputs/SearchBar.md

@@ -0,0 +1,44 @@
+# SearchBar
+
+검색바에서 검색 키워드를 선택할 수 있는 Select를 가질 수 있는 검색 컴포넌트입니다.
+
+> 💡 **Placeholder 표시 가이드**
+>
+> 검색 키워드가 있는 SearchBar는 `options`의 각 옵션에 `placeholder` 필드를 추가하여 사용자가 어떤 값을 입력해야 하는지 안내해 줄 수 있습니다. (사용자에게 더 유익한 정보를 표시해 주기 위함)
+>
+> - \[예시] Account #일 경우: `e.g. 1234567`
+> - \[예시] Jira Issue #일 경우: `e.g. PROC-1234`
+
+```tsx
+<SearchBar options={SAMPLE_OPTIONS} value={value} onChange={setValue} />
+```
+
+| Field      | Description | Default |
+| ---------- | ----------- | ------- |
+| hideSelect | —           | —       |
+| options    | —           | —       |
+| value      | —           | —       |
+| onChange   | —           | —       |
+| onSearch   | —           | —       |
+
+## Select 없이 사용
+
+`hideSelect` prop을 사용하여 Select를 숨길 수 있습니다.
+
+```tsx
+<SearchBar hideSelect options={SAMPLE_OPTIONS} value={value} onChange={setValue} />
+```
+
+## onSearch
+
+검색 버튼 클릭 또는 Enter 입력 시 `onSearch`가 호출됩니다.
+
+```tsx
+<Stack gap={2}>
+  <SearchBar options={SAMPLE_OPTIONS} value={value} onChange={setValue} onSearch={setLastSearch} />
+  <Typography level="body-sm">value: "{value}"</Typography>
+  {lastSearch && <Typography level="body-sm">
+  onSearch: [{lastSearch.selectValue}] "{lastSearch.inputValue}"
+</Typography>}
+</Stack>
+```