# Index (/tds-mobile/)
## TDS를 소개해요
TDS는 토스 제품을 만들 때 공통적으로 사용하는 디자인 시스템이에요. 수백 개의 컴포넌트와 템플릿으로 구성되어 있고, 단순히 디자인 툴에만 머무는 것이 아니라 개발과 연결되어 토스 제품을 구성하는 하나의 언어처럼 사용돼요.
### TDS가 지향하는 목표
- 제품의 최소 품질을 언제나 보장해요. TDS를 사용하면 토스의 일관된 UI를 유지할 수 있기 때문이에요.
- 생산성을 향상시키고 문제 해결에 집중할 수 있도록 도와줘요. 재사용 할 수 있는 아름다운 디자인 시스템으로 제품의 UI 개발 과정을 효율적으로 만들어요.
- 일관성 있는 인터랙션, 애니메이션, 일러스트레이션, 디자인 템플릿을 통해 제품 완성도를 업계 최고 수준으로 끌어올리는 것이 최종 목표에요.
---
# AgreementV3 (/tds-mobile/components/Agreement/v3/)
# AgreementV3
> `AgreementV3`는 더 이상 사용되지 않아요. `AgreementV4`를 이용해 주세요.
`AgreementV3` 컴포넌트는 사용자의 동의를 받아야 하는 화면을 구성하기 위해 사용해요.
하지만 이 컴포넌트는 더 이상 유지보수되지 않으며, 최신 요구 사항을 반영한 `AgreementV4`가 역할을 대신해요.
[Preview: Basic]
## 사용법
### 체크박스 없이 정보만 표시하는 항목
`AgreementV3.SingleField` 컴포넌트는 체크박스 없이 정보를 표시하는 단순한 동의 항목을 생성하는 컴포넌트예요.
추가 정보를 안내하거나, 약관 세부 내용으로 연결되는 링크에 주로 사용돼요.
**Example: SingleField**
```tsx
이용약관
이용약관
```
### 체크박스를 포함한 동의 항목
`AgreementV3.SingleCheckboxField` 컴포넌트는 체크박스를 포함한 동의 항목을 생성하는 컴포넌트예요.
`necessity` 속성을 통해 필수 항목인지 선택 항목인지 구분할 수 있어요.
- `none`: 항목에 필수나 선택 표시가 없어요.
- `mandatory`: [필수] 라벨이 추가되며, 반드시 동의해야 하는 항목이에요.
- `optional`: [선택] 라벨이 추가되며, 사용자가 선택적으로 동의할 수 있는 항목이에요.
**Example: SingleCheckboxField**
```tsx
카드의 실제 소유자입니다
카드의 실제 소유자입니다
카드의 실제 소유자입니다
```
### 여러 동의 항목을 그룹화하기
`AgreementV3.Group` 컴포넌트는 여러 동의 항목을 하나의 그룹으로 묶어주는 컴포넌트예요.
여러 항목을 논리적으로 구분하거나, 화면을 정리된 형태로 구성하고 싶을 때 유용해요.
그룹 안의 각각의 항목은 `AgreementV3.GroupItem`으로 생성하며, 항목이 많은 경우에도 시각적으로 깔끔하게 정리할 수 있어요.
이 컴포넌트는 여러 동의 항목을 가로로 정렬하며, 화면 너비가 좁아지거나 항목이 많아질 때는 자동으로 다음 줄로 넘어가요. 이를 통해 다양한 디바이스에서 일관된 사용자 경험을 제공할 수 있어요.
**Example: Group**
```tsx
동의합니다.동의합니다.
```
### 접었다 펼치는 동의 항목
`AgreementV3.CollapsibleGroup` 컴포넌트와 `AgreementV3.Collapsible` 컴포넌트는 긴 내용을 깔끔하게 정리하고 필요할 때만 내용을 펼쳐 볼 수 있도록 도와줘요.
약관이나 정책 설명이 길거나 동의 항목이 많아 화면이 복잡해질 우려가 있을 때 특히 유용해요.
이 기능은 기본 정보만 노출하고, 추가 내용은 사용자가 필요할 때 열람할 수 있도록 만들어 사용자 경험을 개선해요.
구현 방식은 `AgreementV3.CollapsibleGroup` 컴포넌트로 전체 영역을 감싸고, 실제로 접히고 펼쳐질 내용은 `AgreementV3.Collapsible` 컴포넌트로 구성해요.
안쪽에 `SingleCheckboxField`, `Group`과 같은 다른 컴포넌트를 자유롭게 중첩할 수 있어 다양한 형태의 동의 화면을 만들 수 있어요.
들여쓰기가 필요한 경우 각 컴포넌트의 `indent` 속성을 사용해서 시각적으로 구분할 수 있어요.
**Example: CollapsibleGroup**
```tsx
개인정보 수집 동의
동의해요 1-1
동의해요 1-2
개인정보 수집 동의 group
동의해요 group item동의해요 group item동의해요 group item
```
### 체크박스 버튼
`AgreementV3.Button` 컴포넌트는 전체 동의 기능을 제공하는 컴포넌트예요.
여러 동의 항목을 한 번에 모두 동의할 수 있는 버튼 형태의 UI를 제공해요.
체크박스를 포함하고 있어 사용자가 전체 동의를 클릭하면 시각적으로도 동의 상태를 확인할 수 있어요.
**Example: Button**
```tsx
console.log('전체 동의:', checked)}>
전체 동의하기
```
### 동의 항목 설명
`AgreementV3.Description` 컴포넌트는 동의 항목에 대한 부가 정보를 제공할 때 사용하는 컴포넌트예요.
작은 회색 글씨로 표시되며, 약관 세부 내용이나 참고 정보를 보여줄 때 적합해요.
**Example: Description**
```tsx
개인정보 수집 및 이용 동의수집된 개인정보는 서비스 제공 목적으로만 사용됩니다.
```
### 태그를 활용한 강조 표시
`AgreementV3.Tag` 컴포넌트는 동의 항목에 중요한 정보를 강조하거나 추가적인 메시지를 전달할 때 사용해요. 주요 키워드를 사용자가 빠르게 인식할 수 있도록 돕는 역할을 해요.
**Example: Tag**
```tsx
안심}>
개인정보 수집 및 이용 동의
```
## 상호작용하기
`AgreementV3` 컴포넌트는 다양한 상호작용 이벤트를 제공하며, 주로 `AgreementSingleField`, `AgreementSingleCheckboxField`, 그리고 `AgreementGroupItem`에서 활용돼요.
이 컴포넌트들은 `arrowType` 속성을 사용하여 링크 이동이나 접기/펼치기 기능을 제공해요.
각 이벤트는 특정 상황에서 사용되며, 아래 표는 주요 이벤트와 그 사용 조건을 설명해요.
| 이벤트 이름 | 설명 | `arrowType`이 `none`일 때 | `arrowType`이 `none`이 아닐 때 |
| ----------------- | --------------------------------------------------- | ------------------------- | ---------------------------------- |
| `onClick` | 사용자가 컴포넌트의 주요 영역을 클릭할 때 실행돼요. | 전체 영역에서 사용돼요. | Link, Collapse Area를 제외한 영역에서 사용돼요. |
| `onPressEnd` | 사용자가 터치 영역을 눌렀다가 뗄 때 실행돼요. | 전체 영역에서 사용돼요. | Link, Collapse Area를 제외한 영역에서 사용돼요. |
| `onArrowClick` | 화살표 아이콘을 클릭할 때 실행돼요. | 사용되지 않아요. | Link, Collapse Area에서 사용돼요. |
| `onArrowPressEnd` | 화살표 아이콘을 터치했다가 뗄 때 실행돼요. | 사용되지 않아요. | Link, Collapse Area에서 사용돼요. |
체크 상태 변경 이벤트는 `AgreementV3.SingleCheckboxField`에서 `onCheckedChange`로, `AgreementV3.GroupItem`에서 `onChange`로 사용돼요.
이러한 이벤트를 적절히 활용하여 `AgreementV3` 컴포넌트의 상호작용을 더욱 풍부하게 만들 수 있어요.
**Example: AgreementEventExample**
```tsx
function AgreementEventExample() {
const handleCheckedChange = (checked: boolean) => {
console.log('Checkbox checked state:', checked);
};
const handleChange = (event: React.ChangeEvent) => {
console.log('Group item state changed:', event.target.checked);
};
const handleClick = () => {
console.log('Main area clicked');
};
const handleArrowClick = () => {
console.log('Arrow clicked');
};
return (
Single Checkbox Field
Group Item
Group Item
);
}
```
## 인터페이스
**Type: AgreementSingleFieldProps**
```typescript
export interface AgreementSingleFieldProps {
/**
* 동의 항목의 크기와 스타일을 설정해요.
*
* - `medium`: 기본 크기에요.
* - `medium-bold`: 굵은 텍스트를 사용해요.
* - `big`: 더 큰 크기에요.
*/
type: 'big' | 'medium' | 'medium-bold';
/**
* 동의 항목 옆에 배치할 화살표 형태를 설정해요.
*
* - `none`: 화살표가 없어요.
* - `link`: 링크 형태의 화살표에요.
* - `collapsible`: 펼치기/접기 형태의 화살표에요.
*
* @default none
*/
arrowType?: 'none' | 'link' | 'collapsible';
/**
* 동의 항목 아래에 구분선을 표시해요.
*
* @default false
*/
withBorder?: boolean;
/**
* 동의 항목의 동의 항목의 들여쓰기 값을 설정해요.
* @default 0
*/
indent?: number;
/**
* 동의 항목의 펼침 상태를 설정해요.
* `arrowType`이 `collapsible`일 때만 사용돼요.
* @default false
*/
open?: boolean;
/**
* 동의 항목 오른쪽에 추가할 수 있는 컴포넌트예요.
*/
rightAddon?: React.ReactNode;
/**
* 동의 항목의 내용이에요.
*/
children?: string;
/**
* `Link`, `Collapse` 영역을 제외한 모든 터치영역을 클릭했을 때 실행되는 콜백이에요.
*/
onClick?: (event: React.MouseEvent) => void;
/**
* `Link`, `Collapse` 영역을 클릭했을 때 실행되는 콜백이에요.
* `arrowType`이 none이 아닐 경우 실행돼요.
*/
onArrowClick?: (event: React.MouseEvent) => void;
/**
* `Link`, `Collapse` 영역을 제외한 영역의 터치가 끝날 때 실행되는 콜백이에요.
*/
onPressEnd?: () => void;
/**
* `Link`, `Collapse` 영역의 터치가 끝날 때 실행되는 콜백이에요.
* `arrowType`이 `none`이 아닐 경우 실행돼요.
*/
onArrowPressEnd?: () => void;
}
```
**Type: AgreementSingleCheckboxFieldProps**
```typescript
export interface AgreementSingleCheckboxFieldProps {
/**
* 동의 항목의 크기와 스타일을 설정해요.
*
* - `medium`: 기본 크기에요.
* - `medium-bold`: 굵은 텍스트를 사용해요.
* - `big`: 더 큰 크기에요.
*/
type?: 'big' | 'medium' | 'medium-bold';
/**
* 동의 항목 옆에 배치할 화살표 형태를 설정해요.
*
* - `none`: 화살표가 없어요.
* - `link`: 링크 형태의 화살표에요.
* - `collapsible`: 펼치기/접기 형태의 화살표에요.
*
* @default none
*/
arrowType?: 'none' | 'link' | 'collapsible';
/**
* 동의 항목 아래에 구분선을 표시해요.
*/
withBorder?: boolean;
/**
* 동의 항목의 체크 상태를 설정해요.
* controlled로 외부에서 상태를 제어할 수 있어요.
*/
checked?: boolean;
/**
* 동의 항목의 필수 여부를 설정해요.
*
* - `none`: 필수가 아니에요.
* - `optional`: 선택이 가능해요.
* - `mandatory`: 필수에요.
*
* @default none
*/
necessity?: 'none' | 'optional' | 'mandatory';
/**
* 동의 항목의 들여쓰기 값을 설정해요.
* @default 0
*/
indent?: number;
/**
* 동의 항목의 펼침 상태를 설정해요.
* `arrowType`이 `collapsible`일 때만 사용돼요.
* @default false
*/
open?: boolean;
/**
* 동의 항목 오른쪽에 추가할 수 있는 컴포넌트예요.
*/
rightAddon?: React.ReactNode;
/**
* 동의 항목의 내용이에요.
*/
children?: string;
/**
* 동의 항목의 체크 상태가 변경될 때 호출되는 함수에요.
*/
onCheckedChange?: (checked: boolean) => void;
/**
* `Link`, `Collapse` 영역을 제외한 모든 터치영역을 클릭했을 때 실행되는 콜백이에요.
*/
onClick?: (event: React.MouseEvent) => void;
/**
* `Link`, `Collapse` 영역의 화살표를 클릭했을 때 실행되는 콜백이에요.
* `arrowType`이 `none`이 아닐 경우 실행돼요.
*/
onArrowClick?: (event: React.MouseEvent) => void;
/**
* `Link`, `Collapse` 영역을 제외한 영역의 터치가 끝날 때 실행되는 콜백이에요.
*/
onPressEnd?: () => void;
/**
* `Link`, `Collapse` 영역의 터치가 끝날 때 실행되는 콜백이에요.
* `arrowType`이 `none`이 아닐 경우 실행돼요.
*/
onArrowPressEnd?: () => void;
}
```
**Type: AgreementGroupProps**
```typescript
export interface AgreementGroupProps {
/**
* 동의 항목의 들여쓰기 값을 설정해요.
* @default 0
*/
indent?: number;
/**
* 그룹 내부에 들어갈 컴포넌트들이에요.
* 주로 `GroupItem` 컴포넌트와 함께 사용돼요.
*/
children: React.ReactNode;
}
```
**Type: AgreementGroupItemProps**
```typescript
export interface AgreementGroupItemProps {
/**
* 동의 항목의 크기와 스타일을 설정해요.
*
* - `medium`: 기본 크기에요.
* - `medium-bold`: 굵은 텍스트를 사용해요.
* - `big`: 더 큰 크기에요.
*/
type: 'big' | 'medium' | 'medium-bold';
/**
* 동의 항목 옆에 배치할 화살표 형태를 설정해요.
*
* - `none`: 화살표가 없어요.
* - `link`: 링크 형태의 화살표에요.
* - `collapsible`: 펼치기/접기 형태의 화살표에요.
*
* @default none
*/
arrowType?: 'none' | 'link' | 'collapsible';
/**
* 체크 상태를 설정해요.
* controlled로 외부에서 상태를 제어할 수 있어요.
*/
checked?: boolean;
/**
* 동의 항목의 펼침 상태를 설정해요.
* `arrowType`이 `collapsible`일 때만 사용돼요.
* @default false
*/
open?: boolean;
/**
* 동의 항목의 오른쪽에 추가할 수 있는 컴포넌트예요.
*/
rightAddon?: React.ReactNode;
/**
* 동의 항목의 내용이에요.
*/
children?: string;
/**
* 동의 항목의 체크 상태가 변경될 때 호출되는 함수에요.
*/
onChange?: (event: React.ChangeEvent) => void;
/**
* `Link`, `Collapse` 영역을 제외한 모든 터치영역을 클릭했을 때 실행되는 콜백이에요.
*/
onClick?: (event: React.MouseEvent) => void;
/**
* `Link`, `Collapse` 영역의 화살표를 클릭했을 때 실행되는 콜백이에요.
* `arrowType`이 `none`이 아닐 경우 실행돼요.
*/
onArrowClick?: (event: React.MouseEvent) => void;
/**
* `Link`, `Collapse` 영역을 제외한 영역의 터치가 끝날 때 실행되는 콜백이에요.
*/
onPressEnd?: () => void;
/**
* `Link`, `Collapse` 영역의 터치가 끝날 때 실행되는 콜백이에요.
* `arrowType`이 `none`이 아닐 경우 실행돼요.
*/
onArrowPressEnd?: () => void;
}
```
**Type: AgreementCollapsibleGroupProps**
```typescript
export interface AgreementCollapsibleGroupProps {
/**
* `CollapsibleGroup` 컴포넌트의 펼침 상태를 설정해요.
* controlled로 외부에서 상태를 제어할 수 있어요.
*/
open?: boolean;
/**
* `CollapsibleGroup` 컴포넌트의 초기 펼침 상태를 설정해요.
* uncontrolled로 사용할 때 초기값을 설정할 수 있어요.
*/
defaultOpen?: boolean;
/**
* `CollapsibleGroup` 컴포넌트 내부에 들어갈 컴포넌트들이에요.
* 주로 `SingleField`, `SingleCheckboxField`, `Collapsible` 컴포넌트들과 함께 사용돼요.
*/
children?: React.ReactNode;
/**
* `CollapsibleGroup` 컴포넌트의 펼침 상태가 변경될 때 호출되는 함수에요.
*/
onChange?: (open: boolean) => void;
}
```
**Type: AgreementCollapsibleProps**
```typescript
export interface AgreementCollapsibleProps {
/**
* `Collapsible` 컴포넌트의 펼침/접힘 상태를 제어해요.
*/
open?: boolean;
/**
* `Collapsible` 컴포넌트 내부에 들어갈 컴포넌트들이에요.
* 주로 `SingleField`, `SingleCheckboxField`, `Group` 컴포넌트들과 함께 사용돼요.
*/
children?: React.ReactNode;
}
```
**Type: AgreementButtonProps**
```typescript
export interface AgreementButtonProps {
/**
* input 태그의 `type` 속성을 설정해요.
* @default 'checkbox'
* @note radio는 아직 지원하지 않아요.
*/
inputType?: 'checkbox' | 'radio';
/**
* `Checkbox` 컴포넌트의 크기를 설정해요.
* @default 24
*/
size?: number;
/**
* 버튼 내용으로 들어갈 컴포넌트들이에요.
*/
children: React.ReactNode;
/**
* `Checkbox` 컴포넌트의 선택 상태가 바뀔 때 실행되는 함수예요.
*/
onCheckedChange?(checked: boolean): void;
}
```
**Type: AgreementDescriptionProps**
```typescript
export interface AgreementDescriptionProps {
/**
* 설명의 들여쓰기 값을 설정해요.
* @default 0
*/
indent?: number;
/**
* 설명 내용으로 들어갈 컴포넌트들이에요.
*/
children?: React.ReactNode;
}
```
**Type: AgreementTagProps**
```typescript
export interface AgreementTagProps {
/**
* 태그의 텍스트 색상을 설정해요.
*/
color?: string;
/**
* 태그 내용으로 들어갈 컴포넌트들이에요.
*/
children: React.ReactNode;
}
```
---
# AgreementV4 (/tds-mobile/components/Agreement/v4/)
# AgreementV4
`AgreementV4` 컴포넌트는 사용자의 동의를 받아야 하는 화면을 간편하게 구성할 수 있도록 도와줘요. 여러 동의 항목을 쉽게 추가할 수 있고, 항목을 그룹화하거나 접고 펼치는 기능을 활용해 UI를 깔끔하게 정리할 수 있어요. 또, 체크박스, 설명글, 태그 등 다양한 구성 요소를 지원해서 동의받을 내용을 유저에게 잘 설명해 줄 수 있어요.
[Preview: Basic]
## AgreementV4 구성요소 활용법 알아보기
`AgreementV4` 컴포넌트는 동의 화면을 구성하는 데 필요한 다양한 하위 컴포넌트를 제공해요. 이 구성 요소들을 조합하면 사용자가 쉽게 이해할 수 있는 직관적이고 정리된 동의 화면을 만들 수 있어요.
### 텍스트 사용하기
`AgreementV4.Text`는 동의 항목의 설명이나 제목을 표시하는 텍스트 컴포넌트예요.
`onPressEnd` 속성과 함께 사용하면 사용자 클릭을 감지하여 인터랙션을 제공해 사용자에게 명확한 피드백을 제공해요.
**Example: Text**
```tsx
텍스트} />
console.log('press')}>텍스트를 클릭해보세요.}
/>
```
### 뱃지 사용하기
`AgreementV4.Badge`는 동의 항목에 시각적 강조를 추가하는 컴포넌트예요.
`variant`가 `fill`일 때 배경색을 지정할 수 있어요.
**Example: Badge**
```tsx
서비스 이용 동의}
right={
배경 있음
}
/>
서비스 이용 동의}
right={
배경 없음
}
/>
```
### 체크박스 사용하기
`AgreementV4.Checkbox`는 사용자의 선택을 받기 위한 체크박스 컴포넌트예요.
`variant`가 `'checkbox'`, `'dot'`, `'hidden'`이 있어서 상황에 맞게 사용할 수 있어요.
`hidden` 옵션은 체크박스를 시각적으로 숨기고 레이아웃만 유지할 때 유용해요. 체크박스는 보이지 않지만 공간은 그대로 차지해요.
**Example: Checkbox**
```tsx
```
### 필수 여부 나타내기
`AgreementV4.Necessity`는 동의 항목의 필수 여부를 나타내는 컴포넌트예요. `variant`가 'optional', 'mandatory'가 있어서 상황에 따라 적용할 수 있으며, 색상이 다르게 표시돼요.
주로 `AgreementV4.Text`의 `necessity` 속성에서 사용돼요.
필수와 옵션 항목을 명확히 구분하면 사용자는 어떤 항목이 반드시 필요한지 명확히 알 수 있어, 동의 과정을 더 수월하게 진행할 수 있어요.
**Example: Necessity**
```tsx
}
middle={
필수}>
서비스 이용 동의
}
/>
}
middle={
선택}>
서비스 이용 동의
}
/>
```
### 접고 펼치기 화살표 사용하기
`AgreementV4.RightArrow`는 동의 항목을 접거나 펼치는 기능을 제공하는 화살표예요. 오른쪽에 있는 화살표로, 접기 화살표가 나와요. `collapsed` 컴포넌트에 트리거 용도로 사용돼요.
**Example: RightArrow**
```tsx
개인정보 수집 동의}
right={}
/>
```
### 설명 추가하기
`AgreementV4.Description`는 동의 항목에 대한 부가 정보를 제공할 때 사용하는 컴포넌트예요. 작은 회색 글씨로 표시되며, 약관 세부 내용이나 참고 정보를 보여줄 때 적합해요.
`variant` 속성을 통해 스타일을 조정할 수 있으며 이를 통해 설명의 가독성을 높이고, 시각적으로 구분할 수 있어요.
- `box`: 설명을 박스 형태로 감싸서 강조할 수 있어요. `box` 속성은 배경색과 패딩이 추가되어 설명을 시각적으로 구분하는 데 유용해요.
- `normal`: 기본 스타일로, 패딩 없이 간결하게 설명을 표시해요. `normal` 속성은 설명을 간단하게 표시하고 싶을 때 적합해요.
**Example: Description**
```tsx
수집된 개인정보는 서비스 제공 목적으로만 사용됩니다.
수집된 개인정보는 서비스 제공 목적으로만 사용됩니다.
```
### 헤더 사용하기
`AgreementV4.Header`는 동의 항목의 제목이나 섹션을 시각적으로 구분하는 컴포넌트예요.
다양한 `variant` 옵션을 통해 크기와 스타일을 조절할 수 있어요.
**Example: Header**
```tsx
Header
Header
```
### 클릭 감지하기
`AgreementV4.Pressable`은 사용자의 클릭을 감지하여 인터랙션을 제공해 명확한 피드백을 제공해요. `onPressEnd`와 함께 사용해요.
**Example: Pressable**
```tsx
}
middle={
console.log('press')}>
필수}>
체크박스를 제외한 부분을 클릭해보세요.
안심
}
/>
```
## 사용법
### 단일 동의 항목 생성하기
`AgreementV4` 컴포넌트는 단일 동의 항목을 생성하는 데 사용돼요.
`left`, `middle`, `right` 속성을 통해 체크박스, 텍스트, 추가 정보 등 다양한 컴포넌트를 사용하여 원하는 구성을 구현할 수 있어요.
- `left`: 주로 선택 요소를 배치하는 공간이에요. `AgreementV4.Checkbox`와 같은 컴포넌트가 주로 사용돼요.
- `middle`: 동의 항목의 제목이나 주요 텍스트를 표시하는 공간이에요. `AgreementV4.Text` 컴포넌트가 주로 사용돼요.
- `right`: 추가 정보나 인터랙션을 위한 요소를 배치하는 공간이에요. `AgreementV4.Badge` 또는 `AgreementV4.RightArrow` 컴포넌트가 주로 사용돼요.
**Example: AgreementV4Item**
```tsx
}
middle={서비스 이용 동의}
right={
안심
}
/>
}
middle={서비스 이용 동의}
right={}
/>
}
middle={서비스 이용 동의}
/>
```
### 시각적 계층 구성하기
`AgreementV4.IndentPushable` 컴포넌트는 동의 항목의 시각적 계층을 명확히 할 때 유용해요.
주로 여러 단계의 동의 항목이 있을 때, 사용자가 각 항목의 관계를 명확히 이해할 수 있도록 할 때 사용돼요.
이 기능은 항목 간의 관계에 대한 이해도를 높여주어, 사용자 경험을 개선해요.
- `AgreementV4.IndentPushable`: 계층을 적용할 컴포넌트의 전체 영역을 감싸요.
- `AgreementV4.IndentPushableTrigger`: 클릭 시 내용을 들여쓰기 할 수 있는 트리거 컴포넌트예요.
- `AgreementV4.IndentPushableContent`: 트리거가 활성화되면 들여쓰기가 적용돼요.
`AgreementV4.IndentPushable` 컴포넌트는 `pushed` 속성을 통해 `AgreementV4.IndentPushableContent`의 들여쓰기를 제어할 수 있어요.
`pushed`가 `true`일 경우, `IndentPushableContent`에 포함된 약관들의 들여쓰기가 1만큼 증가해요.
하지만 약관 컴포넌트가 직접 가지는 `indent` 속성의 우선순위가 더 높기 때문에, 이 점을 고려하여 사용해야 해요.
**Example: IndentPushable**
```tsx
<>
}
middle={카드상품 이외의 부수 서비스 안내 등을 위한 수집, 이용}
right={
안심
}
/>
}
middle={고유식별정보 수집/이용}
/>
}
middle={개인(신용)정보 수집/이용}
/>
```
### 접었다 펼치는 동의 항목 구현하기
`AgreementV4.Collapsible` 컴포넌트는 긴 내용을 깔끔하게 정리하고 필요할 때만 내용을 펼쳐 볼 수 있도록 도와줘요.
약관이나 정책 설명이 길거나 동의 항목이 많아 화면이 복잡해질 우려가 있을 때 특히 유용해요.
이 기능은 기본 정보만 노출하고, 추가 내용은 사용자가 필요할 때 열람할 수 있도록 만들어 사용자 경험을 개선해요.
- `AgreementV4.Collapsible`: 컴포넌트의 상태에 따라 내용을 접거나 펼칠 수 있는 기능을 제공해요. `collapsed` 속성을 통해 현재 상태를 제어하며, `onCollapsedChange` 이벤트를 통해 상태 변화를 처리할 수 있어요.
- `AgreementV4.CollapsibleTrigger`: 클릭 시 내용을 펼치거나 접을 수 있는 트리거 컴포넌트예요.
- `AgreementV4.CollapsibleContent`: 트리거가 활성화되면 표시되는 내용을 포함해요.
**Example: Collapsed**
```tsx
function Collapsed() {
const [isOpen, setIsOpen] = React.useState(false);
return (
setIsOpen((prev) => !prev)}>
개인정보 수집 동의 (오른쪽 화살표를 클릭해보세요.)}
right={}
/>
}
middle={동의해요}
/>
}
middle={동의해요}
/>
);
}
```
### 여러 동의 항목 그룹화하기
`AgreementV4.Group` 컴포넌트는 여러 동의 항목을 하나의 그룹으로 묶어주는 컴포넌트예요.
이 컴포넌트는 여러 항목을 논리적으로 구분하여 사용자에게 일관된 정보를 제공하는 데 목적이 있어요.
또한, `showGradient` 속성을 통해 시각적 구분을 강화할 수 있어요. 이 속성은 기본적으로 활성화되어 있으며, 필요에 따라 비활성화하여 그라데이션 효과를 사용하지 않을 수도 있어요.
**Example: Group**
```tsx
}
middle={카드상품 이외의 부수서비스 안내 등을 위한 수집/이용}
/>
}
middle={개인(신용)정보 수집/이용}
/>
}
middle={전자적 매체를 통한 광고성 정보 수신}
/>
```
## 인터페이스
**Type: AgreementV4Props**
```typescript
export interface AgreementV4Props {
/**
* 동의 항목의 들여쓰기 정도를 설정해요.
*/
indent?: number;
/**
* 동의 항목의 크기 및 스타일을 결정해요.
*
* - `xLarge`: 매우 큰 크기예요.
* - `large`: 큰 크기예요.
* - `medium`: 중간 크기예요.
* - `medium-title`: 중간 크기의 제목 스타일이에요.
* - `small`: 작은 크기예요.
* - `small-last`: 마지막 작은 크기예요.
*/
variant: 'xLarge' | 'large' | 'medium' | 'medium-title' | 'small' | 'small-last';
/**
* `AgreementV4` 컴포넌트의 왼쪽 영역에 들어갈 요소를 설정해요.
*/
left?: React.ReactNode;
/**
* `AgreementV4` 컴포넌트의 중간에 들어갈 요소를 설정해요.
*/
middle?: React.ReactNode;
/**
* `AgreementV4` 컴포넌트의 오른쪽에 들어갈 요소를 설정해요.
*/
right?: React.ReactNode;
/**
* 동의 항목이 클릭되었을 때 호출되는 함수예요.
*/
onPressEnd?: () => void;
}
```
**Type: AgreementV4BadgeProps**
```typescript
export interface AgreementV4BadgeProps {
/**
* 뱃지의 스타일을 결정해요.
*
* - `fill`: 배경색이 채워진 스타일이에요.
* - `clear`: 투명한 스타일이에요.
*/
variant: 'fill' | 'clear';
/**
* 텍스트 색상을 설정해요.
*/
textColor: string;
/**
* 배경 색상을 설정해요.
* `variant` 속성이 `fill`일 때는 `string`이 적용되고, 필수값이에요.
* `variant` 속성이 `clear`일 때는 `unknown`이 적용되고, 선택적이에요.
*/
bgColor?: 'string | unknown';
}
```
**Type: AgreementV4CheckboxProps**
```typescript
export interface AgreementV4CheckboxProps {
/**
* 체크박스의 체크 상태를 제어하는 상태예요.
* 이 속성을 사용하려면 `onCheckedChange`도 함께 전달해서 제어 컴포넌트로 설정해야 해요.
*/
checked?: boolean;
/**
* 체크박스 모양을 정할 수 있어요.
*
* - `checkbox`: 기본 체크박스 모양이에요.
* - `dot`: 점 모양의 체크박스에요.
* - `hidden`: 체크박스를 노출하지 않아요.
*
* @default 'checkbox'
*/
variant?: 'checkbox' | 'dot' | 'hidden';
/**
* 체크박스가 체크/언체크될 때 모션의 형태를 정할 수 있어요.
*
* - `strong`: 바운스가 섞인 모션으로, 더 강한 시각적 효과를 줘요.
* - `weak`: 기본 모션으로, 부드러운 시각적 효과를 줘요.
*
* @default 'weak'
*/
motionVariant?: 'strong' | 'weak';
/**
* 체크박스가 체크되거나 해제될 때 모션의 시작 지연 시간을 설정해요.
* 설정된 값에 0.1초가 자동으로 추가되어, 최종 지연 시간이 계산돼요.
* 이 속성을 사용하면 체크박스 모션의 시작 타이밍을 조정할 수 있어요.
*
* 예를 들어, `transitionDelay`를 `0.2`로 설정하면, 실제 지연 시간은 `0.3초`가 돼요.
*
*
* @default 0
*/
transitionDelay?: number;
/**
* 체크박스의 체크 상태가 변경될 때 호출되는 콜백 함수에요.
* `checked` 상태가 변경되면 이 함수가 호출되어, 외부에서 상태 변화를 감지할 수 있어요.
*/
onCheckedChange?: (checked: boolean) => void;
}
```
**Type: AgreementV4TextProps**
```typescript
export interface AgreementV4TextProps {
/**
* 텍스트 앞에 표시할 추가적인 정보를 나타내는 요소에요.
* 주로 `AgreementV4.Necessity` 컴포넌트를 사용해요.
*/
necessity?: React.ReactNode;
/**
* 터치 이벤트가 끝날 때 호출되는 콜백 함수에요.
* 사용자가 텍스트를 터치한 후 손을 뗄 때 실행할 동작을 정의할 수 있어요.
*/
onPressEnd?: () => void;
}
```
**Type: AgreementV4NecessityProps**
```typescript
export interface AgreementV4NecessityProps {
/**
* 약관 필수 여부를 나타내는 속성이에요.
*
* - `optional`: 선택 사항을 나타내며, 진한 회색으로 표시돼요.
* - `mandatory`: 필수 사항을 나타내며, 파란색으로 표시돼요.
*/
variant: 'optional' | 'mandatory';
}
```
**Type: AgreementV4RightArrowProps**
```typescript
export interface AgreementV4RightArrowProps {
/**
* 화살표가 접혀 있는지 여부를 나타내는 속성이에요.
* `true`일 때는 화살표가 접혀 있고, `false`일 때는 펼쳐져 있어요.
*/
collapsed?: boolean;
/**
* 화살표를 클릭할 때 호출되는 콜백 함수에요.
* 사용자가 화살표를 클릭하면 이 함수가 실행돼요.
*/
onArrowClick?: () => void;
}
```
**Type: AgreementV4DescriptionProps**
```typescript
export interface AgreementV4DescriptionProps {
/**
* 약관 설명의 들여쓰기 정도를 설정해요.
*
* @default 0
*/
indent?: number;
/**
* 약관 설명의 스타일을 설정해요.
*
* - `box`: 박스 형태로 설명을 표시해요.
* - `normal`: 일반 텍스트 형태로 설명을 표시해요.
*/
variant: 'box' | 'normal';
}
```
**Type: AgreementV4HeaderProps**
```typescript
export interface AgreementV4HeaderProps {
/**
* `Header` 컴포넌트의 들여쓰기 정도를 설정해요.
*
* @default 0
*/
indent?: number;
/**
* `Header` 컴포넌트의 크기 및 스타일을 결정해요.
*
* - `xLarge`: 매우 큰 크기예요.
* - `large`: 큰 크기예요.
* - `medium`: 중간 크기예요.
* - `medium-title`: 중간 크기의 제목 스타일이에요.
* - `small`: 작은 크기예요.
* - `small-last`: 마지막 작은 크기예요.
*/
variant: 'xLarge' | 'large' | 'medium' | 'medium-title' | 'small' | 'small-last';
}
```
**Type: AgreementV4PressableProps**
```typescript
export interface AgreementV4PressableProps {
/**
* 터치 이벤트가 끝날 때 호출되는 콜백 함수에요.
* 사용자가 텍스트를 터치한 후 손을 뗄 때 실행할 동작을 정의할 수 있어요.
*/
onPressEnd?: () => void;
}
```
**Type: AgreementV4IndentPushableProps**
```typescript
export interface AgreementV4IndentPushableProps {
/**
* 들여쓰기 가능한 컴포넌트 내에 포함될 자식 요소들을 나타내요.
*/
children: React.ReactNode;
/**
* `IndentPushable` 컴포넌트가 현재 들여쓰기 상태인지 여부를 나타내요.
* `true`일 때는 들여쓰기가 적용되고, `false`일 때는 적용되지 않아요.
* 이 속성을 사용하면 외부에서 들여쓰기 상태를 제어할 수 있어요.
*/
pushed?: boolean;
/**
* `IndentPushable` 컴포넌트의 초기 들여쓰기 상태를 설정해요.
* `true`일 때는 기본적으로 들여쓰기가 적용되어 있고, `false`일 때는 들여쓰기를 하지 않아요.
*/
defaultPushed?: boolean;
/**
* 들여쓰기 상태가 변경될 때 호출되는 콜백 함수에요.
* 상태가 변경되면 `pushed` 값이 인자로 전달돼요.
* 이 함수를 사용하면 상태 변화를 감지하고 처리할 수 있어요.
*/
onPushedChange?: (pushed: boolean) => void;
}
```
**Type: AgreementV4IndentPushableTriggerProps**
```typescript
export interface AgreementV4IndentPushableTriggerProps {
/**
* 클릭하면 하위 콘텐츠가 들여쓰기 되는 영역에 포함될 자식 요소들을 나타내요.
* 이 컴포넌트는 클릭했을 때 하위 콘텐츠의 들여쓰기를 제어하는 역할을 해요.
*/
children: React.ReactNode;
}
```
**Type: AgreementV4IndentPushableContentProps**
```typescript
export interface AgreementV4IndentPushableContentProps {
/**
* 들여쓰기 가능한 콘텐츠 내에 포함될 자식 요소들을 나타내요.
* 이 컴포넌트는 트리거가 활성화되면 들여쓰기가 적용되는 콘텐츠를 포함해요.
*/
children?: React.ReactNode;
}
```
**Type: AgreementV4CollapsibleProps**
```typescript
export interface AgreementV4CollapsibleProps {
/**
* 약관을 접거나 펼치기가 가능한 컴포넌트 내에 포함될 자식 요소들을 나타내요.
*/
children: React.ReactNode;
/**
* `Collapsible` 컴포넌트가 현재 접혀 있는지 여부를 나타내요.
* `true`일 때는 접혀있고, `false`일 때는 펼쳐져 있어요.
* 이 속성을 사용하면 외부 컴포넌트에서 접기/펼치기 상태를 제어할 수 있어요.
*/
collapsed?: boolean;
/**
* `Collapsible` 컴포넌트의 초기 접기 상태를 설정해요.
* `true`일 때는 초기 상태가 접혀 있고, `false`일 때는 펼쳐져 있어요.
*/
defaultCollapsed?: boolean;
/**
* 약관을 접거나 펼칠 때 상태가 변경될 때 호출되는 콜백 함수에요.
* 상태가 변경되면 `collapsed` 값이 인자로 전달돼요.
* 이 함수를 사용하면 상태 변화를 감지하고 처리할 수 있어요.
*/
onCollapsedChange?: (collapsed: boolean) => void;
}
```
**Type: AgreementV4CollapsibleTriggerProps**
```typescript
export interface AgreementV4CollapsibleTriggerProps {
/**
* 약관을 접거나 펼칠 때 함께 보일 자식 요소들을 나타내요.
* `CollapsibleTrigger` 컴포넌트는 사용자가 클릭하여 콘텐츠를 접거나 펼칠 수 있는 트리거 역할을 해요.
*/
children: React.ReactNode;
}
```
**Type: AgreementV4CollapsibleContentProps**
```typescript
export interface AgreementV4CollapsibleContentProps {
/**
* 약관을 접거나 펼치기가 가능한 콘텐츠 내에 포함될 자식 요소들을 나타내요.
* `CollapsibleContent` 컴포넌트는 트리거가 활성화되면 표시되는 콘텐츠를 포함해요.
*/
children: React.ReactNode;
}
```
**Type: AgreementV4GroupProps**
```typescript
export interface AgreementV4GroupProps {
/**
* `Group` 컴포넌트 내부의 요소들 왼쪽에 세로로 표시되는 그라데이션 라인의 표시 여부를 설정해요.
* `true`일 때는 그라데이션이 표시되고, `false`일 때는 표시되지 않아요.
* @default true
*/
showGradient?: boolean;
/**
* 그룹 내에 포함될 자식 요소들을 나타내요.
*/
children: React.ReactNode;
}
```
---
# 래핑한 컴포넌트 활용하기 (/tds-mobile/components/Asset/asset/)
# 래핑한 컴포넌트 활용하기
많이 사용되는 `Frame` 컴포넌트와 `ContentIcon` 컴포넌트, `ContentImage` 컴포넌트, `ContentLottie` 컴포넌트, `ContentText` 컴포넌트, `ContentVideo` 컴포넌트의 조합을 미리 래핑하여 사용하기 쉽게 제공해요.
[Preview: BasicForAsset]
래핑된 컴포넌트들은 다음과 같아요:
- `Asset.Icon` = `Frame` + `ContentIcon`
- `Asset.Image` = `Frame` + `ContentImage`
- `Asset.Lottie` = `Frame` + `ContentLottie`
- `Asset.Text` = `Frame` + `ContentText`
- `Asset.Video` = `Frame` + `ContentVideo`
래핑된 컴포넌트들은 원래 `Frame` 컴포넌트의 `shape` 속성을 `frameShape` 속성으로 이름을 변경해서 제공해요. 예를 들면 다음 예시와 같아요.
```tsx
// Frame을 직접 사용할 때
// 래핑된 컴포넌트를 사용할 때
```
자주 사용되는 frameShape 값들은 미리 정의된 프리셋으로도 제공돼요:
```tsx
```
이 컴포넌트들을 사용하면 쉽게 `Asset` 컴포넌트를 활용할 수 있어요.
## 사용 예제
### 아이콘 에셋 사용하기
`Asset.Icon` 컴포넌트는 아이콘을 표시할 때 사용해요. 아이콘을 프레임 안에 일관된 크기와 스타일로 표현할 수 있어요. 필요에 따라 크기와 색상을 조절할 수 있어요.
**Example: IconAsset**
```tsx
```
#### 색상 변경하기
`color` 속성을 사용해 아이콘의 색상을 변경할 수 있어요. CSS 색상값을 지원해요. 토스의 색상 시스템인 adaptive 값도 사용할 수 있어요.
**Example: ColorIconAsset**
```tsx
```
### 이미지 에셋 사용하기
`Asset.Image` 컴포넌트는 이미지를 표시할 때 사용해요. `frameShape` 속성을 통해 크기와 모양을 지정할 수 있고, `scaleType` 속성으로 이미지 맞춤 방식을 조절할 수 있어요.
**Example: ImageAsset**
```tsx
```
### 로티 에셋 사용하기
`Asset.Lottie` 컴포넌트는 Lottie 애니메이션을 표시할 때 사용해요.
**Example: LottieAsset**
```tsx
```
### 텍스트 에셋 사용하기
`Asset.Text` 컴포넌트는 텍스트를 프레임 안에 표시할 때 사용해요.
**Example: TextAsset**
```tsx
Text
```
### 비디오 에셋 사용하기
`Asset.Video` 컴포넌트는 비디오를 재생할 때 사용해요. 자동재생, 반복재생, 음소거를 통해 제어할 수 있어요.
**Example: VideoAsset**
```tsx
```
#### 비디오 제어하기
`Asset.Video` 컴포넌트는 다양한 속성을 통해 비디오 재생을 제어할 수 있어요:
- `controls`: 재생, 일시정지, 음량, 전체화면 등의 컨트롤러를 표시할 수 있어요
- `autoPlay`: 비디오가 로드되면 자동으로 재생할지 설정할 수 있어요
- `loop`: 비디오가 끝나면 다시 처음부터 재생할지 설정할 수 있어요
- `muted`: 비디오의 음소거 여부를 설정할 수 있어요
**Example: ControlVideoAsset**
```tsx
```
## 인터페이스
**Type: IconProps**
```typescript
export interface IconProps extends AssetCommonType {
/**
* 아이콘의 이름을 지정해요.
*/
name: string;
/**
* 아이콘의 색상을 지정해요.
*/
color?: string;
}
```
**Type: ImageProps**
```typescript
export interface ImageProps extends AssetCommonType {
/**
* 이미지의 URL을 지정해요.
*/
src: string;
/**
* 이미지가 프레임에 맞춰지는 방식을 지정해요.
* - `fit`: 이미지의 비율을 유지하면서 프레임 안에 모두 들어가도록 맞춰요
* - `crop`: 이미지가 프레임을 가득 채우도록 맞추고, 넘치는 부분은 잘라내요
*
* @default 'fit'
*/
scaleType?: 'fit' | 'crop';
/**
* 이미지의 대체 텍스트를 지정해요.
*/
alt?: string;
}
```
**Type: VideoProps**
```typescript
export interface VideoProps extends AssetCommonType {
/**
* 비디오의 URL을 지정해요.
*/
src: string;
/**
* 자동 재생 여부를 지정해요.
*
* @default true
*/
autoPlay?: boolean;
/**
* 반복 재생 여부를 지정해요.
*
* @default true
*/
loop?: boolean;
/**
* 음소거 여부를 지정해요.
*
* @default true
*/
muted?: boolean;
/**
* 컨트롤 표시 여부를 지정해요.
*
* @default false
*/
controls?: boolean;
/**
* 비디오를 인라인으로 재생할지 지정해요.
*
* @default true
*/
playsInline?: boolean;
}
```
**Type: LottieProps**
```typescript
export interface LottieProps extends AssetCommonType {
/**
* Lottie 애니메이션 파일의 URL을 지정해요.
*
* @required
*/
src: string;
/**
* 애니메이션이 프레임에 맞춰지는 방식을 지정해요.
*
* @default 'fit'
*/
scaleType?: 'fit' | 'crop';
}
```
**Type: TextProps**
```typescript
export interface TextProps extends AssetCommonType {
/**
* 텍스트 내용을 지정해요.
*/
children?: React.ReactNode;
}
```
**Type: AssetCommonType**
```typescript
export interface AssetCommonType {
/**
* 프레임의 형태와 크기를 지정해요.
*/
frameShape?: 'FrameShapeType';
/**
* 프레임의 배경색을 지정해요.
*/
backgroundColor?: string;
/**
* `Asset` 컴포넌트의 ID를 지정해요.
*/
id?: string;
/**
* `Asset` 컴포넌트의 클래스명을 지정해요.
*/
className?: string;
/**
* 컴포넌트의 인라인 스타일을 지정해요.
*/
style?: React.CSSProperties;
/**
* 프레임에 추가할 액세서리 요소를 지정해요.
*/
acc?: React.ReactNode;
/**
* 액세서리의 위치를 지정해요.
*
* @default 'bottom-right'
*/
accPosition?: 'FrameAccPositionType';
/**
* 여러 개의 항목이 합쳐졌음을 보여주고 싶을 때 사용해요.
*
* `color` 속성으로 오버랩 색상을 설정할 수 있어요.
*/
overlap?: { color: string } | null;
}
```
---
# Asset 이해하기 (/tds-mobile/components/Asset/check-first/)
# Asset 이해하기
이 문서를 읽고나면,
- `Asset` 컴포넌트의 기본 개념과 구조를 이해할 수 있어요
- `Frame` 컴포넌트의 역할과 중요성을 이해할 수 있어요
- 각 에셋 종류의 특징과 차이점을 이해할 수 있어요
[Preview: BasicForCheckFirst]
## Asset의 구조 이해하기
`Asset` 컴포넌트는 아이콘, 이미지, 비디오, Lottie 애니메이션 등 다양한 미디어 에셋을 일관된 방식으로 표시할 수 있게 해주는 컴포넌트예요.
`Asset` 컴포넌트는 Frame, Content, Union으로 나뉘어요.
> `Asset` 컴포넌트의 핵심은 `Frame` 컴포넌트에요. `Frame` 컴포넌트는 모든 `Asset` 컴포넌트 종류에 일관된 레이아웃과
> 스타일링을 제공하는 기반이 돼요.
### Frame
- `Asset` 컴포넌트의 기본 틀을 담당해요
- 모든 종류의 `Asset` 컴포넌트에 일관된 크기와 모양을 제공해요
- 정사각형, 직사각형, 원형 등 다양한 프리셋을 제공해요
### Content
- 이미지, 아이콘, 비디오, 텍스트, 로띠와 같은 `Asset` 컴포넌트의 실제 내용물이 들어가는 영역이에요
- `scaleType` 속성을 통해 내용물이 프레임에 맞춰지는 방식을 조절할 수 있어요
### Union
- Content에 대한 부가적인 정보를 표현해요
- `overlap`: 여러 항목이 겹쳐있음을 표현해요
- `acc` (액세서리): 상태나 부가 기능을 작은 요소로 표시해요
---
# Asset 활용하기 (/tds-mobile/components/Asset/frame/)
# Asset 활용하기
모든 `Asset` 컴포넌트는 `Frame` 컴포넌트를 기반으로 만들어져 있어요. `Frame` 컴포넌트는 에셋의 크기, 모양, 배경 등 일관된 스타일을 제공하는 역할을 해요.
[Preview: PresetFrameAsset]
## 사용 예제
### Frame 컴포넌트 사용해보기
`Asset` 컴포넌트는 `Frame` 컴포넌트를 기반으로 구성되어 있어요. `Frame` 컴포넌트는 모든 종류의 `Asset` 컴포넌트의 기본 틀이 되어 일관된 레이아웃과 스타일링을 제공하고 있어요.
예를 들어 `Asset.Image` 컴포넌트는 내부적으로 `Frame` 컴포넌트와 `ContentImage` 컴포넌트의 조합으로 이루어져 있어요:
- `Frame` 컴포넌트: 크기, 모양, 배경색, 액세서리 등 에셋의 외형을 담당해요.
- `ContentImage` 컴포넌트: 실제 이미지를 표시하는 역할이에요.
가장 기본적인 사용법을 먼저 살펴보아요.
**Example: FrameContentImageAsset**
```tsx
}
/>
```
위 예시에서 `src`는 `ContentImage` 컴포넌트에 전달되어 실제 이미지를 표시하게 돼요.
여기에 `Frame` 컴포넌트의 특성을 활용하면 다양한 스타일링이 가능해요.
`Frame` 컴포넌트와 `ContentImage` 컴포넌트를 조합하여 쉽게 사용할 수 있게 `Asset.Image` 컴포넌트로 제공해요.
> `Asset.Image` 컴포넌트를 활용한 방법은 **[래핑한 컴포넌트 활용하기](/components/Asset/asset)** 페이지에서 확인할 수
> 있어요.
앞으로 `Asset.Image` 컴포넌트와 `Asset.Lottie` 컴포넌트를 기준으로 설명해요.
### 프리셋 프레임 활용하기
자주 사용되는 크기와 모양의 프레임을 프리셋으로 제공해요.
- **Square**: 정사각형 프레임 (Small, Medium, Large)
- **Rectangle**: 직사각형 프레임 (Medium, Large)
- **Circle**: 원형 프레임 (Small, Medium, Large)
- **Card**: 카드형 프레임 (Small, Medium, Large)
> **Asset.frameShape**에서 원하는 프리셋을 선택할 수 있어요.
**Example: PresetFrameAsset**
```tsx
{/* Square 프리셋 */}
Square
{/* Rectangle 프리셋 */}
Rectangle
{/* Circle 프리셋 */}
Circle
{/* Card 프리셋 */}
Card
```
### 액세서리 추가하기
에셋에 부수적인 기능을 표현하기 위해 작은 요소(뱃지 등)를 추가할 수 있어요. 주로 에셋의 모서리에 올라가는 형태로, 뱃지나 상태 표시 등의 용도로 사용돼요.
우리는 이렇게 추가한 요소를 액세서리라고 부르고 있어요.
- `acc` 속성으로 액세서리 컴포넌트를 지정할 수 있어요.
- `accPosition` 속성으로 액세서리의 위치를 지정할 수 있어요. `top-left`, `bottom-left`, `top-right`, `bottom-right`을 사용할 수 있고, 기본적으로는 `bottom-right` 이에요.
**Example: AccPresetFrameAsset**
```tsx
```
### 오버랩 추가하기
프레임에 오버랩 효과를 추가할 수 있어요. 여러 개의 항목이 합쳐졌음을 보여주고 싶을 때 사용해요. `overlap` 속성으로 테두리 색상을 지정할 수 있어요.
뒤의 배경에는 컬러값을 받을 수 있어요.
**Example: OverlapPresetFrameAsset**
```tsx
```
### 프레임 맞춤 방식 조절하기
`scaleType` 속성으로 이미지가 프레임에 맞춰지는 방식을 조절할 수 있어요:
- `fit`: 이미지의 비율을 유지하면서 프레임 안에 모두 들어가도록 맞춰요.
- `crop`: 이미지가 프레임을 가득 채우도록 맞추고, 넘치는 부분은 잘라내요.
**Example: ScaleTypeLottieAsset**
```tsx
```
### 프레임 크기 조절하기
`frameShape`의 width와 height로 텍스트가 들어갈 프레임의 크기를 지정할 수 있어요.
**Example: FrameTextAsset**
```tsx
Text
Text
```
## 인터페이스
**Type: FrameShapeType**
```typescript
export interface FrameShapeType {
/**
* 프레임의 너비를 지정해요.
*/
width?: string | number;
/**
* 프레임의 높이를 지정해요.
*/
height?: string | number;
/**
* 프레임의 모서리 둥글기를 지정해요.
*/
radius?: string | number;
/**
* 프레임의 액세서리 영역 설정이에요.
*/
acc?: 'FrameAccShapeType';
/**
* 프레임 뒤에 겹침 효과를 설정해요.
*
* 여러 개의 항목이 합쳐졌음을 표현할 때 사용해요.
*/
overlap?: 'FrameOverlapShapeType';
}
```
**Type: FrameAccShapeType**
```typescript
export interface FrameAccShapeType {
/**
* 액세서리의 너비를 지정해요.
*/
width?: string | number;
/**
* 액세서리의 높이를 지정해요.
*/
height?: string | number;
/**
* 액세서리의 X축 위치를 지정해요.
*/
x?: string | number;
/**
* 액세서리의 Y축 위치를 지정해요.
*/
y?: string | number;
}
```
**Type: FrameOverlapShapeType**
```typescript
export interface FrameOverlapShapeType {
/**
* 오버랩의 X축 오프셋을 지정해요.
*/
x?: string | number;
/**
* 오버랩의 Y축 오프셋을 지정해요.
*/
y?: string | number;
/**
* 오버랩의 블러 정도를 지정해요.
*/
blur?: string | number;
/**
* 오버랩의 확산 정도를 지정해요.
*/
spread?: string | number;
}
```
**Type: FrameProps**
```typescript
export interface FrameProps extends Omit, 'content'> {
/**
* `Frame` 컴포넌트 내부에 표시될 요소예요.
*
* `Asset` 컴포넌트의 주요 콘텐츠(아이콘, 이미지, 비디오 등)가 `content`를 통해 전달돼요.
*/
content: React.ReactNode;
/**
* `Frame` 컴포넌트의 크기와 모양을 정의하는 객체예요.
*
* 리소스 타입 별 권장하는 규격을 프리셋으로 제공하고 있어요.
*
* @example
* Asset.frameShape.SquareMedium
*/
shape: 'FrameShapeType';
/**
* `Frame` 컴포넌트의 배경색을 지정해요.
*
* @default adaptive.grey100
*/
backgroundColor?: string;
/**
* `Frame` 컴포넌트 위에 표시될 추가 요소예요.
*
* 뱃지나 상태 표시, 이미지 등을 통해 에셋에 부수적인 기능이 있음을 표현할 때 사용해요.
*/
acc?: React.ReactNode;
/**
* 액세서리(`acc`)의 위치를 지정해요.
*
* `top-left`, `top-right`, `bottom-left`, `bottom-right` 중 하나를 선택할 수 있어요.
*
* @default 'bottom-right'
*/
accPosition?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
/**
* 액세서리(`acc`) 아래 콘텐츠의 마스킹 처리 방식을 지정해요.
*
* `circle`로 설정하면 액세서리 아래 원형으로 콘텐츠가 마스킹돼요.
*
* @default 'none'
*/
accMasking?: 'circle' | 'none';
/**
* `Frame` 컴포넌트에 오버랩을 추가해요.
*
* 여러 개의 항목이 합쳐졌음을 보여주고 싶을 때 사용해요.
*/
overlap?: { color: string } | null;
/**
* `Frame` 컴포넌트 내부 콘텐츠의 색상을 지정해요.
*
* 주로 아이콘의 색상을 지정할 때 사용돼요.
*/
color?: string;
}
```
---
# Badge (/tds-mobile/components/badge/)
# Badge
`Badge` 컴포넌트는 항목의 상태를 빠르게 인식할 수 있도록 강조하는 데 사용돼요.
[Preview: Badge]
## 사용법
### 크기 조정하기
`Badge` 컴포넌트의 크기를 변경하려면 `size` 속성을 사용하세요. `xsmall`, `small`, `medium`, `large` 중 하나를 선택할 수 있어요.
**Example: Sizes**
```tsx
xsmall
small
medium
large
```
### 스타일
`Badge` 컴포넌트의 스타일을 설정하려면 `variant` 속성을 사용하세요. 선택 할 수 있는 값에는 `fill`과 `weak`이 있어요.
이때, `color` 속성을 사용하여 원하는 색상을 설정할 수 있어요.
#### fill
`fill` 스타일은 채도가 높아 시각적으로 강렬하고 눈에 띄는 디자인이라 주요 항목을 강조하는 데 적합해요.
**Example: Fill**
```tsx
Badge
Badge
Badge
Badge
```
#### weak
`weak` 스타일은 채도가 낮아서 시각적으로 덜 눈에 띄어요.
**Example: Weak**
```tsx
Badge
Badge
Badge
Badge
```
## 인터페이스
**Type: BadgeProps**
```typescript
export interface BadgeProps {
/**
* `Badge` 컴포넌트의 색상과 투명도 정보에요.
*/
variant: 'fill' | 'weak';
/**
* `Badge` 컴포넌트의 크기에요.
*/
size: 'xsmall' | 'small' | 'medium' | 'large';
/**
* `Badge` 컴포넌트의 색상이에요.
*/
color: 'blue' | 'teal' | 'green' | 'red' | 'yellow' | 'elephant';
}
```
---
# Board Row (/tds-mobile/components/board-row/)
# Board Row
`BoardRow`는 제한된 공간에서 많은 정보를 깔끔하게 정리해 표시하는 컴포넌트예요. 주로 Q&A와 같은 정보를 표현할 때 사용하며, 펼쳐졌다 접히는 방식으로 정보를 보여주는 아코디언 컴포넌트 같은 역할을 해요.
[Preview: BoardRow]
## 사용법
`BoardRow` 컴포넌트는 제목, 프리픽스, 아이콘, 그리고 콘텐츠 영역으로 구성돼요. 사용자는 제목 영역을 클릭하여 콘텐츠 영역을 열거나 닫을 수 있어요. 제목 옆의 프리픽스와 아이콘은 추가적인 정보나 상태를 시각적으로 표시하기 위해 사용해요.
**Example: Basic**
```tsx
Q}
icon={}
>
주식 거래가 실시간이 아니기 때문에 가격이 변할 것에 대비하는 금액을 말해요.
```
### 패널 초기 열림 상태 제어하기
`initialOpened` 속성을 사용하면 패널이 처음 화면에 렌더링될 때, 기본적으로 열린 상태로 표시돼요. 즉, 사용자가 별도로 클릭하지 않아도 처음부터 콘텐츠 영역이 펼쳐져 있어요.
**Example: Initial**
```tsx
Q}
icon={}
>
초기부터 콘텐츠 영역이 열려 있어요.
```
### 패널 열림/닫힘 제어하기
`isOpened` 속성과 `onOpen`, `onClose` 함수를 사용하면 컴포넌트 외부에서 패널의 열림/닫힘 상태를 직접 제어할 수 있어요. `isOpened`가 `true`면 패널이 열린 상태로, `false`면 닫힌 상태로 표시돼요. `onOpen`은 패널이 열릴 때 호출되는 함수이고, `onClose`는 패널이 닫힐 때 호출되는 함수예요. 이 속성과 함수들을 활용해서 패널의 상태를 외부에서 동적으로 제어할 수 있어요.
**Example: OpenClose**
```tsx
function OpenClose() {
const [isOpened, setIsOpened] = React.useState(false);
return (
setIsOpened(true)}
onClose={() => setIsOpened(false)}
prefix={Q}
icon={}
>
주식 거래가 실시간이 아니기 때문에 가격이 변할 것에 대비하는 금액을 말해요.
);
}
```
### 콘텐츠 영역 채우기
`BoardRow`의 콘텐츠 영역에는 주로 `Post` 컴포넌트를 사용해요. `Post` 컴포넌트를 활용하면 깔끔하게 정리된 정보를 전달할 수 있어요.
**Example: FillContent**
```tsx
Q}
icon={}
initialOpened
>
주식 거래가 실시간이 아니기 때문에 가격이 변할 것에 대비하는 금액을 말해요.
대시를 붙이고 띄어쓰면 불렛을 쓸 수 있어요.
들여쓰려면 대시 앞에 〉를 입력해요.
```
간단한 문장을 사용할 때는 `BoardRow.Text`를 사용할 수 있어요. `BoardRow.Text`는 `Post.Paragraph`를 확장한 컴포넌트예요.
**Example: SimpleContent**
```tsx
Q}
icon={}
initialOpened
>
주식 거래가 실시간이 아니기 때문에 가격이 변할 것에 대비하는 금액을 말해요.
```
## 접근성
`BoardRow` 컴포넌트는 기본적으로 접근성을 지원하는 여러 속성을 포함하고 있어요. 이 속성들은 스크린 리더 사용자들이 컴포넌트를 명확하게 이해하고 상호작용할 수 있도록 도와줘요. 특히 컴포넌트에서 패널의 열림/닫힘 상태는 시각적으로만 나타나는 것이 아니라, 스크린 리더 사용자에게도 전달될 수 있도록 설계되었어요.
| 속성 | 접근성 효과 | 설명 |
|----------------------|----------------------------------------------|------------------------------------------------------------------------------|
| `