@ceed/ads 1.13.3 → 1.15.0-next.1

package/dist/components/inputs/RadioTileGroup.md

@@ -0,0 +1,418 @@
+# RadioTileGroup
+
+RadioTileGroup 컴포넌트는 타일 형태의 라디오 옵션을 표시하는 컴포넌트입니다. 각 옵션이 타일 형태로 나타나며, 사용자가 선택할 수 있습니다.
+
+```tsx
+<RadioTileGroup
+  options={simpleOptions}
+  useIndicator
+/>
+```
+
+| Field        | Description | Default       |
+| ------------ | ----------- | ------------- |
+| options      | —           | simpleOptions |
+| value        | —           | —             |
+| defaultValue | —           | —             |
+| onChange     | —           | —             |
+| name         | —           | —             |
+| disabled     | —           | —             |
+| className    | —           | —             |
+| useIndicator | —           | —             |
+| textAlign    | —           | —             |
+| size         | —           | —             |
+| flex         | —           | —             |
+| columns      | —           | —             |
+| label        | —           | —             |
+| helperText   | —           | —             |
+| error        | —           | —             |
+| required     | —           | —             |
+
+## 기본형
+
+RadioTileGroup의 기본 형태입니다. 필수 속성 값으로 `options`를 받으며, 각 옵션은 `value`와 `label`을 포함해야 합니다.
+
+```tsx
+<RadioTileGroup
+  options={simpleOptions}
+  useIndicator
+/>
+```
+
+`label`과 `helperText`를 함께 사용하면 아래와 같은 모습입니다.
+
+```tsx
+<RadioTileGroup
+  options={simpleOptions}
+  useIndicator
+  label="Select an option"
+  helperText="This is helper text for the RadioTileGroup"
+/>
+```
+
+## 필수 값 표시
+
+`required` 속성을 사용하여 필수 입력 필드임을 표시할 수 있습니다.
+
+```tsx
+<RadioTileGroup
+  options={simpleOptions}
+  useIndicator
+  label="Select an option"
+  helperText="This field is required"
+  required
+/>
+```
+
+## 레이아웃 옵션
+
+### Flex
+
+`flex` 속성을 활성화하면 RadioTileGroup이 사용 가능한 공간을 균등하게 채웁니다.
+
+```tsx
+<RadioTileGroup
+  options={simpleOptions}
+  useIndicator
+  flex
+/>
+```
+
+### Columns
+
+`columns` 속성을 사용하여 타일을 특정 열 수로 배치할 수 있습니다.
+
+```tsx
+<RadioTileGroup
+  options={simpleOptions}
+  useIndicator
+  columns={2}
+/>
+```
+
+### Flex와 Columns 함께 사용
+
+`flex`와 `columns` 속성을 함께 사용하여 타일이 균등하게 공간을 채우면서 특정 열 수로 배치할 수 있습니다.
+
+```tsx
+<Box sx={{
+  width: '100%',
+  maxWidth: 700
+}}>
+<Typography level="body-md" sx={{
+  mb: 2
+}}>
+Flex with Columns
+</Typography>
+<RadioTileGroup options={optionsWithIcons} onChange={handleChange} value={selectedValue} flex={true} columns={3} size="md" useIndicator={true} label="Flex with Columns Example" helperText="Items stretch to fill available space and are arranged in 3 columns" />
+</Box>
+```
+
+### 수직 레이아웃
+
+`columns: 1`로 설정하면 타일이 수직으로 쌓이는 레이아웃을 만들 수 있습니다.
+
+```tsx
+<Box sx={{
+  width: '100%',
+  maxWidth: 400
+}}>
+<Typography level="body-md" sx={{
+  mb: 2
+}}>
+Vertical Layout (columns: 1)
+</Typography>
+<RadioTileGroup options={pricingOptions} onChange={handleChange} value={selectedValue} columns={1} size="md" useIndicator={true} label="Subscription Plans" helperText="Select your preferred subscription plan" />
+</Box>
+```
+
+## 정렬 옵션
+
+`textAlign` 속성을 사용하여 타일 내부의 콘텐츠 정렬 방식을 설정할 수 있습니다. 기본값은 `center`이며, `start`로 설정하면 텍스트가 왼쪽으로 정렬됩니다.
+
+```tsx
+<Box sx={{
+  display: 'flex',
+  flexDirection: 'column',
+  gap: 4,
+  width: '100%',
+  maxWidth: 700
+}}>
+<Box>
+  <Typography level="body-md" sx={{
+    mb: 2
+  }}>
+  Center Alignment (default)
+</Typography>
+<RadioTileGroup options={simpleOptions} textAlign="center" useIndicator={true} />
+</Box>
+<Box>
+  <Typography level="body-md" sx={{
+    mb: 2
+  }}>
+  Start Alignment
+</Typography>
+<RadioTileGroup options={simpleOptions} textAlign="start" useIndicator={true} />
+</Box>
+</Box>
+```
+
+## Size
+
+RadioTileGroup은 세 가지 크기를 지원합니다: `sm`, `md`, `lg`. 기본값은 `sm`입니다.
+
+```tsx
+<Box sx={{
+  display: 'flex',
+  flexDirection: 'column',
+  gap: 4,
+  width: '100%',
+  maxWidth: 700
+}}>
+<Box>
+  <Typography level="body-md" sx={{
+    mb: 2
+  }}>
+  Size: sm (default)
+</Typography>
+<RadioTileGroup options={simpleOptions} size="sm" useIndicator={true} />
+</Box>
+<Box>
+  <Typography level="body-md" sx={{
+    mb: 2
+  }}>
+  Size: md
+</Typography>
+<RadioTileGroup options={simpleOptions} size="md" useIndicator={true} />
+</Box>
+<Box>
+  <Typography level="body-md" sx={{
+    mb: 2
+  }}>
+  Size: lg
+</Typography>
+<RadioTileGroup options={simpleOptions} size="lg" useIndicator={true} />
+</Box>
+</Box>
+```
+
+## 아이콘 사용
+
+각 옵션에 `startDecorator` 속성을 사용하여 아이콘을 추가할 수 있습니다.
+
+```tsx
+<RadioTileGroup
+  options={[{
+  value: 'home',
+  label: 'Home',
+  startDecorator: <HomeIcon fontSize="large" />
+}, {
+  value: 'office',
+  label: 'Office',
+  startDecorator: <BusinessIcon fontSize="large" />
+}, {
+  value: 'shipping',
+  label: 'Shipping',
+  startDecorator: <LocalShippingIcon fontSize="large" />
+}]}
+  useIndicator
+/>
+```
+
+## 상태 관리
+
+### Controlled Component
+
+RadioTileGroup은 상태 관리를 위한 제어 컴포넌트(Controlled Component)로 사용할 수 있습니다.
+
+```tsx
+<Box sx={{
+  width: '100%',
+  maxWidth: 500
+}}>
+<Typography level="body-md" sx={{
+  mb: 1
+}}>
+Selected value: {selectedValue}
+</Typography>
+<RadioTileGroup options={simpleOptions} value={selectedValue} onChange={handleChange} />
+</Box>
+```
+
+### Uncontrolled Component
+
+또한 비제어 컴포넌트(Uncontrolled Component)로도 사용 가능합니다.
+
+```tsx
+<Box sx={{
+  display: 'flex',
+  flexDirection: 'column',
+  gap: 4
+}}>
+<Box sx={{
+  width: '100%',
+  maxWidth: 500
+}}>
+<Typography level="body-md" sx={{
+  mb: 2
+}}>
+Uncontrolled Example (with Indicator)
+</Typography>
+<RadioTileGroup options={simpleOptions} defaultValue="option2" useIndicator={true} onChange={event => console.log(`Selected value: ${event.target.value}`)} />
+</Box>
+<Box sx={{
+  width: '100%',
+  maxWidth: 500
+}}>
+<Typography level="body-md" sx={{
+  mb: 2
+}}>
+Uncontrolled Example (without Indicator)
+</Typography>
+<RadioTileGroup options={simpleOptions} defaultValue="option3" useIndicator={false} onChange={event => console.log(`Selected value: ${event.target.value}`)} />
+</Box>
+</Box>
+```
+
+## 비활성화 상태
+
+### 전체 비활성화
+
+`disabled` 속성을 사용하여 모든 옵션을 비활성화할 수 있습니다.
+
+```tsx
+<RadioTileGroup
+  options={simpleOptions}
+  disabled
+/>
+```
+
+### 개별 옵션 비활성화
+
+각 옵션별로 `disabled` 속성을 설정하여 특정 옵션만 비활성화할 수 있습니다.
+
+```tsx
+<RadioTileGroup
+  options={[{
+  value: 'option1',
+  label: 'Option 1'
+}, {
+  value: 'option2',
+  label: 'Option 2',
+  disabled: true
+}, {
+  value: 'option3',
+  label: 'Option 3'
+}]}
+/>
+```
+
+## 상태 표시
+
+### 오류 상태
+
+`error` 속성을 사용하여 오류 상태를 표시할 수 있습니다.
+
+```tsx
+<RadioTileGroup
+  options={simpleOptions}
+  useIndicator
+  label="Select an option"
+  helperText="Please select a valid option"
+  error
+/>
+```
+
+### 필수 값 검증 예제
+
+`required` 속성과 함께 오류 상태를 활용하여 필수 값 검증을 할 수 있습니다. 아래는 폼 제출 시 유효성 검사를 포함한 예제입니다.
+
+```tsx
+<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>
+```
+
+## 활용 사례
+
+### 배송 방법 선택
+
+RadioTileGroup은 배송 방법을 시각적으로 선택할 수 있는 인터페이스로 활용할 수 있습니다. 각 타일에 아이콘과 함께 배송 방법 정보를 표시하여 사용자가 직관적으로 선택할 수 있도록 합니다.
+
+```tsx
+<Box sx={{
+  width: '100%',
+  maxWidth: 700
+}}>
+<RadioTileGroup label="배송 방법 선택" helperText="배송 방법에 따라 배송비가 달라질 수 있습니다." options={[{
+  value: 'standard',
+  label: '일반 배송',
+  startDecorator: <HomeIcon />
+}, {
+  value: 'express',
+  label: '빠른 배송',
+  startDecorator: <LocalShippingIcon />
+}, {
+  value: 'business',
+  label: '기업 배송',
+  startDecorator: <BusinessIcon />
+}]} onChange={handleChange} value={selectedValue} size="md" useIndicator={true} />
+</Box>
+```
+
+### 설문조사
+
+설문조사나 선호도 조사에서 다양한 선택지를 제공하는 데 활용할 수 있습니다. 각 타일에 선택지를 시각적으로 표현하여 사용자가 직관적으로 응답할 수 있도록 합니다.
+
+```tsx
+<Box sx={{
+  width: '100%',
+  maxWidth: 700
+}}>
+<RadioTileGroup label="선호하는 운동 유형을 선택해주세요" options={[{
+  value: 'cardio',
+  label: '유산소 운동',
+  startDecorator: <DirectionsRunIcon />
+}, {
+  value: 'strength',
+  label: '근력 운동',
+  startDecorator: <FitnessCenterIcon />
+}, {
+  value: 'flexibility',
+  label: '유연성 운동',
+  startDecorator: <SelfImprovementIcon />
+}, {
+  value: 'balance',
+  label: '균형 운동',
+  startDecorator: <BalanceIcon />
+}]} onChange={handleChange} value={selectedValue} columns={2} size="md" />
+</Box>
+```
+
+### 폼 검증과 함께 사용
+
+폼 검증 기능과 함께 사용하여 사용자가 필수 항목을 선택했는지 확인할 수 있습니다.
+
+```tsx
+<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>
+```

package/dist/components/inputs/Select.md

@@ -0,0 +1,56 @@
+# Select
+
+## Introduction
+
+```tsx
+<Select options={options} />
+```
+
+| Field          | Description | Default |
+| -------------- | ----------- | ------- |
+| variant        | —           | —       |
+| color          | —           | —       |
+| size           | —           | —       |
+| autoFocus      | —           | —       |
+| placeholder    | —           | —       |
+| startDecorator | —           | —       |
+| endDecorator   | —           | —       |
+| error          | —           | —       |
+| helperText     | —           | —       |
+| value          | —           | —       |
+| defaultValue   | —           | —       |
+| onChange       | —           | —       |
+| options        | —           | options |
+
+### Variants
+
+```tsx
+<Stack spacing={4}>
+  <Select defaultValue="dog" options={options} />
+  <Select defaultValue="dog" variant="plain" options={options} />
+  <Select defaultValue="dog" variant="soft" options={options} />
+  <Select defaultValue="dog" variant="solid" options={options} />
+</Stack>
+```
+
+### Sizes
+
+```tsx
+<Stack spacing={4}>
+  <Select defaultValue="dog" size="sm" options={options} />
+  <Select defaultValue="dog" size="md" options={options} />
+  <Select defaultValue="dog" size="lg" options={options} />
+</Stack>
+```
+
+### Colors
+
+```tsx
+<Stack spacing={4}>
+  <Select defaultValue="dog" color="primary" options={options} />
+  <Select defaultValue="dog" color="neutral" options={options} />
+  <Select defaultValue="dog" color="success" options={options} />
+  <Select defaultValue="dog" color="danger" options={options} />
+  <Select defaultValue="dog" color="warning" options={options} />
+</Stack>
+```