@ceed/ads 1.13.4 → 1.15.0-next.2

package/dist/components/data-display/Tooltip.md

@@ -0,0 +1,444 @@
+# Tooltip
+
+## Introduction
+
+Tooltip 컴포넌트는 사용자가 요소에 마우스를 올렸을 때 추가적인 정보나 도움말을 제공하는 오버레이입니다. Joy UI의 Tooltip을 기반으로 하며, 사용자 경험을 향상시키기 위해 간결하고 유용한 정보를 표시하는 데 사용됩니다. 버튼 설명, 아이콘 의미, 잘린 텍스트의 전체 내용 표시 등에 활용됩니다.
+
+```tsx
+<Tooltip
+  title="I am Tooltip"
+  arrow={false}
+  children={<Button>Hover me</Button>}
+/>
+```
+
+| Field    | Description | Default                     |
+| -------- | ----------- | --------------------------- |
+| variant  | —           | —                           |
+| color    | —           | —                           |
+| size     | —           | —                           |
+| arrow    | —           | false                       |
+| open     | —           | —                           |
+| children | —           | \<Button>Hover me\</Button> |
+
+## Usage
+
+```tsx
+import { Tooltip, Button } from '@ceed/ads';
+
+function MyComponent() {
+  return (
+    <Tooltip title="이 버튼을 클릭하면 저장됩니다">
+      <Button>저장</Button>
+    </Tooltip>
+  );
+}
+```
+
+## Examples
+
+### Basic Usage
+
+가장 기본적인 Tooltip 사용법입니다.
+
+```tsx
+<Tooltip
+  title="I am Tooltip"
+  arrow={false}
+  children={<Button>Hover me</Button>}
+/>
+```
+
+### Controlled Tooltip
+
+프로그래밍적으로 제어되는 Tooltip입니다.
+
+```tsx
+<Tooltip
+  title="I am Tooltip"
+  arrow={false}
+  children={<Button>Hover me</Button>}
+  open
+/>
+```
+
+## Common Use Cases
+
+### Icon Button Descriptions
+
+아이콘 버튼의 의미를 설명할 때 사용합니다.
+
+```tsx
+<Stack direction="row" spacing={1}>
+  <Tooltip title="편집">
+    <IconButton size="sm">
+      <EditIcon />
+    </IconButton>
+  </Tooltip>
+
+  <Tooltip title="삭제">
+    <IconButton size="sm" color="danger">
+      <DeleteIcon />
+    </IconButton>
+  </Tooltip>
+
+  <Tooltip title="공유">
+    <IconButton size="sm">
+      <ShareIcon />
+    </IconButton>
+  </Tooltip>
+</Stack>
+```
+
+### Truncated Text
+
+잘린 텍스트의 전체 내용을 표시할 때 사용합니다.
+
+```tsx
+function TruncatedText({ text }: { text: string }) {
+  const shouldTruncate = text.length > 50;
+  const displayText = shouldTruncate ? `${text.substring(0, 50)}...` : text;
+
+  const content = (
+    <Typography
+      level="body-md"
+      sx={{
+        maxWidth: 300,
+        overflow: 'hidden',
+        textOverflow: 'ellipsis',
+        whiteSpace: 'nowrap',
+      }}
+    >
+      {displayText}
+    </Typography>
+  );
+
+  return shouldTruncate ? <Tooltip title={text}>{content}</Tooltip> : content;
+}
+```
+
+### Form Field Help
+
+폼 필드에 추가 도움말을 제공할 때 사용합니다.
+
+```tsx
+<Stack spacing={2}>
+  <FormControl>
+    <FormLabel>
+      비밀번호
+      <Tooltip title="최소 8자 이상, 대소문자와 숫자를 포함해야 합니다">
+        <IconButton size="sm" variant="plain" color="neutral">
+          <InfoIcon />
+        </IconButton>
+      </Tooltip>
+    </FormLabel>
+    <Input type="password" />
+  </FormControl>
+</Stack>
+```
+
+### Status Indicators
+
+상태나 진행률 정보를 표시할 때 사용합니다.
+
+```tsx
+<Stack direction="row" spacing={2} alignItems="center">
+  <Tooltip title="성공적으로 완료됨">
+    <Chip color="success" variant="soft">
+      <CheckCircleIcon sx={{ mr: 1 }} />
+      완료
+    </Chip>
+  </Tooltip>
+
+  <Tooltip title="진행 중... 예상 완료 시간: 5분">
+    <Chip color="warning" variant="soft">
+      <AccessTimeIcon sx={{ mr: 1 }} />
+      진행중
+    </Chip>
+  </Tooltip>
+
+  <Tooltip title="오류가 발생했습니다. 다시 시도해주세요">
+    <Chip color="danger" variant="soft">
+      <ErrorIcon sx={{ mr: 1 }} />
+      실패
+    </Chip>
+  </Tooltip>
+</Stack>
+```
+
+### Navigation Hints
+
+네비게이션 요소에 도움말을 제공할 때 사용합니다.
+
+```tsx
+<Stack direction="row" spacing={2}>
+  <Tooltip title="홈페이지로 이동">
+    <Button variant="plain" startDecorator={<HomeIcon />}>
+      홈
+    </Button>
+  </Tooltip>
+
+  <Tooltip title="사용자 프로필 및 설정">
+    <Button variant="plain" startDecorator={<PersonIcon />}>
+      프로필
+    </Button>
+  </Tooltip>
+
+  <Tooltip title="알림 및 메시지 확인">
+    <Badge badgeContent={3} color="danger">
+      <Button variant="plain" startDecorator={<NotificationsIcon />}>
+        알림
+      </Button>
+    </Badge>
+  </Tooltip>
+</Stack>
+```
+
+### Complex Content
+
+복잡한 내용을 가진 Tooltip입니다.
+
+```tsx
+<Tooltip
+  title={
+    <Stack spacing={1} sx={{ maxWidth: 250 }}>
+      <Typography level="title-sm">사용자 정보</Typography>
+      <Typography level="body-sm">
+        이름: 김철수
+        <br />
+        부서: 개발팀
+        <br />
+        직급: 선임연구원
+        <br />
+        연락처: kim@example.com
+      </Typography>
+    </Stack>
+  }
+  variant="outlined"
+>
+  <Avatar>김</Avatar>
+</Tooltip>
+```
+
+### Interactive Elements
+
+상호작용이 가능한 요소들과 함께 사용합니다.
+
+```tsx
+<Stack direction="row" spacing={2}>
+  <Tooltip title="이 기능은 프리미엄 사용자만 이용할 수 있습니다">
+    <Button disabled>프리미엄 기능</Button>
+  </Tooltip>
+
+  <Tooltip title="현재 선택됨">
+    <Chip variant="solid" color="primary">
+      활성 필터
+    </Chip>
+  </Tooltip>
+
+  <Tooltip title="클릭하여 정렬 순서 변경">
+    <Button variant="plain" endDecorator={<ArrowDropDownIcon />}>
+      이름순
+    </Button>
+  </Tooltip>
+</Stack>
+```
+
+## Props and Customization
+
+### Title Prop
+
+Tooltip에 표시될 내용을 지정합니다.
+
+```tsx
+// 간단한 텍스트
+<Tooltip title="간단한 도움말">
+  <Button>버튼</Button>
+</Tooltip>
+
+// React 요소
+<Tooltip
+  title={
+    <div>
+      <strong>제목</strong><br />
+      상세 설명이 들어갑니다.
+    </div>
+  }
+>
+  <Button>버튼</Button>
+</Tooltip>
+```
+
+### Placement
+
+Tooltip이 나타나는 위치를 조정할 수 있습니다.
+
+```tsx
+<Stack direction="row" spacing={2} sx={{ mt: 4 }}>
+  <Tooltip title="위쪽" placement="top">
+    <Button>Top</Button>
+  </Tooltip>
+
+  <Tooltip title="아래쪽" placement="bottom">
+    <Button>Bottom</Button>
+  </Tooltip>
+
+  <Tooltip title="왼쪽" placement="left">
+    <Button>Left</Button>
+  </Tooltip>
+
+  <Tooltip title="오른쪽" placement="right">
+    <Button>Right</Button>
+  </Tooltip>
+</Stack>
+```
+
+### Colors and Variants
+
+다양한 색상과 변형을 적용할 수 있습니다.
+
+```tsx
+<Stack direction="row" spacing={2}>
+  <Tooltip title="Primary 색상" color="primary" variant="solid">
+    <Button>Primary</Button>
+  </Tooltip>
+
+  <Tooltip title="Success 색상" color="success" variant="soft">
+    <Button>Success</Button>
+  </Tooltip>
+
+  <Tooltip title="Warning 색상" color="warning" variant="outlined">
+    <Button>Warning</Button>
+  </Tooltip>
+
+  <Tooltip title="Danger 색상" color="danger" variant="plain">
+    <Button>Danger</Button>
+  </Tooltip>
+</Stack>
+```
+
+### Arrow
+
+화살표를 표시하여 Tooltip이 어느 요소를 가리키는지 명확히 할 수 있습니다.
+
+```tsx
+<Stack direction="row" spacing={2}>
+  <Tooltip title="화살표 없음" arrow={false}>
+    <Button>No Arrow</Button>
+  </Tooltip>
+
+  <Tooltip title="화살표 있음" arrow={true}>
+    <Button>With Arrow</Button>
+  </Tooltip>
+</Stack>
+```
+
+### Controlled Mode
+
+프로그래밍적으로 Tooltip의 표시/숨김을 제어할 수 있습니다.
+
+```tsx
+function ControlledTooltip() {
+  const [open, setOpen] = useState(false);
+
+  return (
+    <Stack spacing={2}>
+      <Tooltip title="이 Tooltip은 버튼으로 제어됩니다" open={open} onClose={() => setOpen(false)}>
+        <Button variant="outlined">제어되는 요소</Button>
+      </Tooltip>
+
+      <Button onClick={() => setOpen(!open)}>Tooltip {open ? '숨기기' : '보이기'}</Button>
+    </Stack>
+  );
+}
+```
+
+## Accessibility
+
+Tooltip 컴포넌트는 다음과 같은 접근성 기능을 제공합니다:
+
+### ARIA 속성
+
+자동으로 적절한 ARIA 속성이 적용됩니다.
+
+```tsx
+<Tooltip title="저장 버튼">
+  <Button aria-label="문서 저장">
+    <SaveIcon />
+  </Button>
+</Tooltip>
+```
+
+### 키보드 지원
+
+키보드 사용자도 Tooltip을 사용할 수 있습니다.
+
+- **Tab**: 포커스 가능한 요소로 이동
+- **Escape**: 열린 Tooltip 닫기
+
+### 터치 기기 지원
+
+터치 기기에서도 Tooltip을 사용할 수 있도록 탭 제스처를 지원합니다.
+
+```tsx
+<Tooltip title="터치 기기에서도 동작합니다" touchTapDelay={0}>
+  <Button>터치 지원</Button>
+</Tooltip>
+```
+
+## Best Practices
+
+1. **간결한 내용**: Tooltip 내용은 간결하고 이해하기 쉽게 작성하세요.
+
+```tsx
+// ✅ 좋은 예
+<Tooltip title="삭제">
+  <IconButton><DeleteIcon /></IconButton>
+</Tooltip>
+
+// ❌ 나쁜 예
+<Tooltip title="이 버튼을 클릭하면 선택된 항목이 영구적으로 삭제되며 복구할 수 없습니다">
+  <IconButton><DeleteIcon /></IconButton>
+</Tooltip>
+```
+
+2. **중요한 정보는 다른 방법으로**: 핵심적인 정보는 Tooltip에만 의존하지 마세요.
+
+3. **적절한 타이밍**: 사용자가 도움이 필요할 때만 표시되도록 하세요.
+
+4. **일관된 배치**: 애플리케이션 전체에서 일관된 placement를 사용하세요.
+
+5. **성능 고려**: 많은 수의 Tooltip이 있는 페이지에서는 필요시에만 렌더링하세요.
+
+```tsx
+// 조건부 Tooltip
+{
+  (needsTooltip && (
+    <Tooltip title="도움말">
+      <Button>버튼</Button>
+    </Tooltip>
+  )) || <Button>버튼</Button>;
+}
+```
+
+6. **모바일 고려**: 모바일 환경에서는 대안적인 정보 제공 방법을 고려하세요.
+
+7. **색상 의존 금지**: 색상에만 의존하지 말고 텍스트나 아이콘으로도 정보를 전달하세요.
+
+## Performance Considerations
+
+1. **지연 렌더링**: 많은 Tooltip이 있는 경우 필요시에만 렌더링하세요.
+
+2. **메모이제이션**: 복잡한 title 내용은 메모이제이션을 고려하세요.
+
+```tsx
+const tooltipContent = useMemo(() => <ComplexTooltipContent data={data} />, [data]);
+
+<Tooltip title={tooltipContent}>
+  <Button>복잡한 Tooltip</Button>
+</Tooltip>;
+```
+
+3. **이벤트 리스너 최적화**: 커스텀 이벤트 핸들러를 사용할 때는 적절히 정리하세요.
+
+Tooltip은 사용자에게 추가적인 맥락과 도움을 제공하는 중요한 UI 컴포넌트입니다. 적절히 사용하면 사용자 경험을 크게 향상시킬 수 있습니다.

package/dist/components/data-display/Typography.md

@@ -0,0 +1,271 @@
+# Typography
+
+## Introduction
+
+Typography 컴포넌트는 텍스트를 표시하기 위한 핵심 컴포넌트입니다. Joy UI의 Typography를 기반으로 하며, 다양한 텍스트 레벨과 스타일을 제공합니다. 제목, 본문, 라벨 등 모든 텍스트 요소에 일관된 타이포그래피를 적용할 수 있습니다.
+
+```tsx
+<Typography children="Typography" />
+```
+
+| Field | Description | Default |
+| ----- | ----------- | ------- |
+| level | —           | —       |
+| color | —           | —       |
+
+## Usage
+
+```tsx
+import { Typography } from '@ceed/ads';
+
+function MyComponent() {
+  return (
+    <div>
+      <Typography level="h1">메인 제목</Typography>
+      <Typography level="body-md">본문 텍스트입니다.</Typography>
+      <Typography level="body-sm" color="neutral">
+        보조 설명 텍스트입니다.
+      </Typography>
+    </div>
+  );
+}
+```
+
+## Typography Levels
+
+### Headings
+
+제목을 위한 레벨들입니다. 페이지 구조를 명확하게 나타내는 데 사용됩니다.
+
+```tsx
+<Typography level="h1">H1 - 페이지 메인 제목</Typography>
+<Typography level="h2">H2 - 섹션 제목</Typography>
+<Typography level="h3">H3 - 하위 섹션 제목</Typography>
+<Typography level="h4">H4 - 세부 제목</Typography>
+```
+
+### Titles
+
+중요한 제목이나 강조할 텍스트에 사용됩니다.
+
+```tsx
+<Typography level="title-lg">Large Title</Typography>
+<Typography level="title-md">Medium Title</Typography>
+<Typography level="title-sm">Small Title</Typography>
+```
+
+### Body Text
+
+본문 텍스트를 위한 레벨들입니다. 대부분의 읽기 내용에 사용됩니다.
+
+```tsx
+<Typography level="body-lg">큰 본문 텍스트</Typography>
+<Typography level="body-md">일반 본문 텍스트</Typography>
+<Typography level="body-sm">작은 본문 텍스트</Typography>
+<Typography level="body-xs">매우 작은 텍스트</Typography>
+```
+
+## Common Use Cases
+
+### Page Structure
+
+```tsx
+function ArticlePage() {
+  return (
+    <article>
+      <Typography level="h1" sx={{ mb: 2 }}>
+        기사 제목
+      </Typography>
+
+      <Typography level="body-sm" color="neutral" sx={{ mb: 3 }}>
+        2024년 1월 15일 · 김철수 작성
+      </Typography>
+
+      <Typography level="body-md" sx={{ mb: 2 }}>
+        기사의 본문 내용이 여기에 들어갑니다. 이 텍스트는 읽기 쉬운
+        크기와 줄 간격을 가지고 있습니다.
+      </Typography>
+
+      <Typography level="h2" sx={{ mt: 4, mb: 2 }}>
+        섹션 제목
+      </Typography>
+
+      <Typography level="body-md">
+        섹션의 내용이 계속됩니다.
+      </Typography>
+    </article>
+  );
+}
+```
+
+### Card Content
+
+```tsx
+<Card>
+  <CardContent>
+    <Typography level="title-md" sx={{ mb: 1 }}>
+      제품명
+    </Typography>
+
+    <Typography level="body-sm" color="neutral" sx={{ mb: 2 }}>
+      카테고리: 전자제품
+    </Typography>
+
+    <Typography level="body-md" sx={{ mb: 2 }}>
+      제품에 대한 상세 설명이 여기에 들어갑니다.
+    </Typography>
+
+    <Typography level="title-lg" color="primary">
+      ₩199,000
+    </Typography>
+  </CardContent>
+</Card>
+```
+
+### Form Labels and Help Text
+
+```tsx
+<Stack spacing={2}>
+  <FormControl>
+    <Typography level="title-sm" component="label">
+      사용자 이름
+    </Typography>
+    <Input placeholder="이름을 입력하세요" />
+    <Typography level="body-xs" color="neutral">
+      실명으로 입력해 주세요.
+    </Typography>
+  </FormControl>
+
+  <FormControl error>
+    <Typography level="title-sm" component="label">
+      이메일 주소
+    </Typography>
+    <Input placeholder="email@example.com" />
+    <Typography level="body-xs" color="danger">
+      올바른 이메일 형식이 아닙니다.
+    </Typography>
+  </FormControl>
+</Stack>
+```
+
+### Status and Indicators
+
+```tsx
+<Stack spacing={2}>
+  <Box>
+    <Typography level="body-md">서버 상태:</Typography>
+    <Typography level="body-md" color="success">
+      정상 운영 중
+    </Typography>
+  </Box>
+
+  <Box>
+    <Typography level="body-md">마지막 업데이트:</Typography>
+    <Typography level="body-sm" color="neutral">
+      2분 전
+    </Typography>
+  </Box>
+</Stack>
+```
+
+### List Content
+
+```tsx
+<Stack spacing={1}>
+  <Typography level="title-md">할 일 목록</Typography>
+
+  {todoItems.map((item) => (
+    <Box key={item.id} sx={{ pl: 2 }}>
+      <Typography
+        level="body-md"
+        sx={{
+          textDecoration: item.completed ? 'line-through' : 'none',
+          color: item.completed ? 'neutral.500' : 'text.primary'
+        }}
+      >
+        {item.text}
+      </Typography>
+      <Typography level="body-xs" color="neutral">
+        {item.dueDate}
+      </Typography>
+    </Box>
+  ))}
+</Stack>
+```
+
+## Colors
+
+Typography는 다양한 색상을 지원합니다:
+
+```tsx
+<Stack spacing={1}>
+  <Typography color="primary">Primary 색상</Typography>
+  <Typography color="neutral">Neutral 색상</Typography>
+  <Typography color="danger">Danger 색상</Typography>
+  <Typography color="success">Success 색상</Typography>
+  <Typography color="warning">Warning 색상</Typography>
+</Stack>
+```
+
+## Component Prop
+
+다른 HTML 요소나 React 컴포넌트로 렌더링할 수 있습니다:
+
+```tsx
+<Typography level="h1" component="h2">
+  h2 태그로 렌더링되는 h1 스타일
+</Typography>
+
+<Typography level="body-md" component="span">
+  인라인 텍스트
+</Typography>
+
+<Typography level="title-md" component={Link} href="/page">
+  링크 컴포넌트로 렌더링
+</Typography>
+```
+
+## Responsive Typography
+
+반응형 레벨을 사용할 수 있습니다:
+
+```tsx
+<Typography
+  level={{ xs: 'h3', sm: 'h2', md: 'h1' }}
+  sx={{
+    fontSize: { xs: '1.5rem', sm: '2rem', md: '2.5rem' }
+  }}
+>
+  반응형 제목
+</Typography>
+```
+
+## Best Practices
+
+1. **의미적 구조**: 제목 레벨을 순서대로 사용하여 명확한 문서 구조를 만드세요.
+
+```tsx
+// ✅ 올바른 순서
+<Typography level="h1">메인 제목</Typography>
+<Typography level="h2">섹션 제목</Typography>
+<Typography level="h3">하위 섹션</Typography>
+
+// ❌ 잘못된 순서
+<Typography level="h1">메인 제목</Typography>
+<Typography level="h3">섹션 제목</Typography>
+```
+
+2. **일관성**: 같은 용도의 텍스트에는 같은 레벨을 사용하세요.
+
+3. **가독성**: 본문 텍스트에는 적절한 줄 간격과 문단 구분을 제공하세요.
+
+4. **색상 대비**: 충분한 색상 대비를 유지하여 접근성을 보장하세요.
+
+## Accessibility
+
+- 적절한 HTML 시맨틱 태그 사용
+- 스크린 리더 지원
+- 키보드 탐색 가능 (링크나 버튼으로 사용될 때)
+- 충분한 색상 대비
+
+Typography는 사용자 인터페이스에서 정보를 효과적으로 전달하고 시각적 계층 구조를 만드는 데 핵심적인 역할을 합니다. 적절한 레벨과 스타일을 선택하여 읽기 쉽고 접근 가능한 콘텐츠를 만들 수 있습니다.