cashdoc-cms-design-system 1.0.1 → 1.0.3

package/README.md

@@ -1 +1,125 @@
+# Cashdoc CMS Design System
 
+Cashdoc CMS용 디자인 시스템 컴포넌트 라이브러리
+
+## 문서
+Storybook과 JSDoc, 둘 중 더 편한 쪽을 보면 됩니다.
+### Storybook
+[Storybook](https://cashdoc-cms-design-system.vercel.app/?path=/docs/components-button--docs)
+
+### JSDoc(TSDoc)
+<img width="1038" height="363" alt="스크린샷 2025-12-24 오후 3 48 42" src="https://github.com/user-attachments/assets/1178fa60-30cb-436b-944c-495417179ac3" />
+
+<br />
+
+## 기술 스택
+
+- **React 18** - UI 라이브러리
+- **TypeScript** - 타입 안전성
+- **TailwindCSS** - 스타일링
+- **Radix UI** - 접근성 프리미티브
+- **Framer Motion** - 애니메이션
+- **Vite** - 빌드 도구
+- **Storybook** - 컴포넌트 문서화
+
+<br />
+
+## 설치
+
+```bash
+pnpm install cashdoc-cms-design-system
+```
+
+<br />
+
+## 사용법
+
+프로젝트 최상단에서 cashdoc-cms-design-system의 `style.css` 파일을 import 후 사용하면 됩니다.
+
+```tsx
+import "cashdoc-cms-design-system/dist/style.css";
+```
+
+```tsx
+import { Button, Modal, DatePicker } from "cashdoc-cms-design-system";
+
+function App() {
+  return <Button variant="default">버튼</Button>;
+}
+```
+
+<br />
+
+## 컴포넌트 리스트
+
+### Form
+
+- `Button` - 기본 버튼
+- `Checkbox` - 체크박스
+- `RadioButton` - 라디오 버튼
+- `Switch` - 토글 스위치
+- `TextInput` - 텍스트 입력 필드
+- `TagInput` - 태그 입력 필드
+
+### Data Input
+
+- `DatePicker` - 날짜 선택
+- `DateRangePicker` - 기간 선택
+- `Dropdown` - 드롭다운 메뉴
+- `Select` - 선택 입력
+- `Combobox` - 검색 가능한 선택
+
+### Feedback
+
+- `Modal` - 모달 다이얼로그
+  - `ConfirmModal` - 확인 모달
+  - `DeleteModal` - 삭제 확인 모달
+  - `ErrorModal` - 에러 알림
+  - `SuccessModal` - 성공 알림
+  - `WarningModal` - 경고 알림
+- `Toast` - 토스트 알림
+- `LoadingCircle` - 로딩 인디케이터
+
+### Navigation
+
+- `SideNavigation` - 사이드바 네비게이션
+- `Popover` - 팝오버 메뉴
+
+### Display
+
+- `Text` - 타이포그래피
+- `Icons` - 아이콘 세트
+
+#
+<br />
+# 개발
+
+### 로컬 개발 서버
+
+```bash
+pnpm dev
+```
+
+### Storybook 실행
+
+```bash
+pnpm storybook
+```
+
+### 빌드
+
+```bash
+pnpm build
+```
+
+### 타입 체크
+
+```bash
+pnpm type-check
+```
+
+### 린트
+
+```bash
+pnpm lint
+```

package/dist/components/Pagination/Pagination.d.ts

@@ -0,0 +1,106 @@
+import { default as React } from 'react';
+
+export interface PaginationProps {
+    currentPage: number;
+    totalPages: number;
+    onPageChange: (page: number) => void;
+    siblingCount?: number;
+    showPrevNext?: boolean;
+    disabled?: boolean;
+    className?: string;
+}
+/**
+ * 사용자가 여러 페이지로 나뉜 콘텐츠를 탐색할 수 있게 하는 페이지네이션 컴포넌트입니다.
+ *
+ * {@link Pagination}은 이전/다음 버튼과 페이지 번호를 제공하며,
+ * 많은 페이지가 있을 때 중간 페이지를 생략(ellipsis)하여 UI를 깔끔하게 유지합니다.
+ *
+ * ## When (언제 사용해야 하는가)
+ *
+ * **사용해야 하는 경우:**
+ * - **긴 목록**: 많은 항목을 여러 페이지로 나누어 표시할 때
+ * - **검색 결과**: 검색 결과가 여러 페이지에 걸쳐 있을 때
+ * - **데이터 테이블**: 대량의 데이터를 페이지 단위로 보여줄 때
+ * - **명확한 페이지 구분**: 사용자가 특정 페이지로 직접 이동할 필요가 있을 때
+ *
+ * **사용하지 말아야 하는 경우:**
+ * - **무한 스크롤**: 지속적으로 콘텐츠가 로드되는 피드 형태가 더 적절한 경우
+ * - **적은 항목**: 한 페이지에 모두 표시할 수 있는 소량의 데이터
+ * - **단계별 프로세스**: 순차적인 단계를 나타낼 때는 Stepper 컴포넌트 사용
+ *
+ * ## Layout behavior
+ *
+ * - **Responsive**: 모바일에서는 siblingCount를 줄여 더 적은 페이지 번호를 표시하는 것을 권장
+ * - **Centered**: 일반적으로 페이지 하단 중앙에 배치
+ * - **Ellipsis**: 많은 페이지가 있을 때 자동으로 중간 페이지를 생략 (...으로 표시)
+ *
+ * ## Usage guidelines
+ *
+ * ### ✅ Do (권장 사항)
+ *
+ * - **적절한 페이지당 항목 수**: 10-50개 사이가 적절 (콘텐츠 유형에 따라 조정)
+ * - **현재 페이지 명확히 표시**: 활성 페이지는 시각적으로 구분되어야 함
+ * - **충분한 클릭 영역**: 모바일에서도 쉽게 탭할 수 있도록 버튼 크기 유지
+ * - **첫/마지막 페이지 비활성화**: 이동할 수 없는 경우 버튼을 비활성화하여 명확히 표시
+ *
+ * ### 🚫 Don't (주의/금지 사항)
+ *
+ * - **너무 많은 페이지 번호**: siblingCount를 너무 크게 설정하지 마세요
+ * - **불명확한 상태**: 로딩 중이거나 에러 상태일 때도 적절한 피드백 제공 필요
+ *
+ * ## Accessibility
+ *
+ * - **ARIA Labels**: 각 버튼에 명확한 레이블 제공 (aria-label, aria-current)
+ * - **Keyboard Navigation**: Tab 키로 버튼 간 이동, Enter/Space로 페이지 변경
+ * - **Screen Reader**: 현재 페이지와 전체 페이지 수를 읽어주도록 설정
+ * - **Disabled State**: 비활성화된 버튼은 포커스할 수 없도록 처리
+ *
+ * ## Example
+ *
+ * {@tool snippet}
+ * 기본적인 페이지네이션 사용:
+ *
+ * ```tsx
+ * const [currentPage, setCurrentPage] = useState(1);
+ * const totalPages = 10;
+ *
+ * <Pagination
+ *   currentPage={currentPage}
+ *   totalPages={totalPages}
+ *   onPageChange={setCurrentPage}
+ * />
+ * ```
+ * {@end-tool}
+ *
+ * {@tool snippet}
+ * 많은 페이지와 커스텀 siblingCount:
+ *
+ * ```tsx
+ * <Pagination
+ *   currentPage={25}
+ *   totalPages={100}
+ *   siblingCount={2}
+ *   onPageChange={handlePageChange}
+ * />
+ * // 결과: 1 ... 23 24 25 26 27 ... 100
+ * ```
+ * {@end-tool}
+ *
+ * {@tool snippet}
+ * 비활성화 상태:
+ *
+ * ```tsx
+ * <Pagination
+ *   currentPage={5}
+ *   totalPages={10}
+ *   onPageChange={handlePageChange}
+ *   disabled={isLoading}
+ * />
+ * ```
+ * {@end-tool}
+ *
+ * See also:
+ *
+ * - {@link Button}, 단일 버튼 컴포넌트
+ */
+export declare const Pagination: React.ForwardRefExoticComponent<PaginationProps & React.RefAttributes<HTMLDivElement>>;

package/dist/components/Pagination/index.d.ts

@@ -0,0 +1,2 @@
+export { Pagination } from './Pagination';
+export type { PaginationProps } from './Pagination';

package/dist/components/Table/Table.d.ts

@@ -0,0 +1,151 @@
+import { default as React } from 'react';
+import { VariantProps } from 'class-variance-authority';
+
+/**
+ * 데이터를 행과 열로 구조화하여 표시하는 테이블 컴포넌트입니다.
+ *
+ * {@link Table}은 Compound Component 패턴을 사용하여 구성되며,
+ * TableHeader, TableBody, TableFooter, TableRow, TableHead, TableCell, TableCaption
+ * 등의 하위 컴포넌트를 조합하여 유연한 테이블 레이아웃을 만들 수 있습니다.
+ *
+ * ## When (언제 사용해야 하는가)
+ *
+ * **사용해야 하는 경우:**
+ * - **데이터 목록**: 사용자 목록, 주문 내역, 제품 리스트 등 구조화된 데이터를 표시할 때
+ * - **비교**: 여러 항목의 속성을 나란히 비교해야 할 때
+ * - **정렬 및 필터**: 데이터를 정렬하거나 필터링해서 보여줄 때
+ * - **대량 데이터**: 많은 양의 정보를 조직적으로 표시해야 할 때
+ *
+ * **사용하지 말아야 하는 경우:**
+ * - **레이아웃 목적**: 단순히 레이아웃을 만들기 위해서는 CSS Grid나 Flexbox를 사용하세요.
+ * - **소량 데이터**: 2-3개의 간단한 정보는 리스트나 카드 형태가 더 적합할 수 있습니다.
+ * - **복잡한 인터랙션**: 각 행마다 많은 버튼이나 입력이 필요하다면 카드 레이아웃을 고려하세요.
+ *
+ * ## Layout behavior
+ *
+ * - **Responsive**: 기본적으로 스크롤 가능한 컨테이너로 래핑되어 모바일에서도 사용 가능합니다.
+ * - **Full Width**: 부모 컨테이너의 전체 너비를 차지합니다.
+ * - **Auto Height**: 내용에 따라 높이가 자동으로 조정됩니다.
+ *
+ * ## Usage guidelines
+ *
+ * ### ✅ Do (권장 사항)
+ *
+ * - **명확한 헤더**: TableHead를 사용하여 각 열의 의미를 명확히 표시하세요.
+ * - **일관된 정렬**: 숫자는 오른쪽, 텍스트는 왼쪽 정렬하는 것이 일반적입니다.
+ * - **적절한 variant**: 데이터가 많을 때는 `striped`나 `hoverable`을 사용하여 가독성을 높이세요.
+ * - **Caption 활용**: 테이블의 목적을 설명하는 caption을 추가하면 접근성이 향상됩니다.
+ *
+ * ### 🚫 Don't (주의/금지 사항)
+ *
+ * - **과도한 열**: 너무 많은 열은 가독성을 해칩니다. 중요한 정보만 표시하세요.
+ * - **중첩 테이블**: 테이블 안에 테이블을 넣지 마세요. 복잡도가 급격히 증가합니다.
+ * - **빈 셀 남용**: 빈 셀이 많으면 데이터 구조를 다시 검토하세요.
+ *
+ * ## Accessibility
+ *
+ * - **Semantic HTML**: 적절한 `<table>`, `<thead>`, `<tbody>`, `<th>`, `<td>` 태그를 사용합니다.
+ * - **Scope Attribute**: TableHead는 `scope="col"`을 자동으로 가집니다.
+ * - **ARIA Attributes**: 정렬, 선택 등의 상태는 `aria-sort`, `aria-selected`로 표현됩니다.
+ * - **Caption**: 테이블의 목적을 설명하는 `<caption>`을 사용할 수 있습니다.
+ *
+ * ## Example
+ *
+ * {@tool snippet}
+ * 기본 테이블 사용:
+ *
+ * ```tsx
+ * <Table>
+ *   <TableCaption>사용자 목록</TableCaption>
+ *   <TableHeader>
+ *     <TableRow>
+ *       <TableHead>이름</TableHead>
+ *       <TableHead>이메일</TableHead>
+ *       <TableHead align="right">역할</TableHead>
+ *     </TableRow>
+ *   </TableHeader>
+ *   <TableBody>
+ *     <TableRow>
+ *       <TableCell>홍길동</TableCell>
+ *       <TableCell>hong@example.com</TableCell>
+ *       <TableCell align="right">관리자</TableCell>
+ *     </TableRow>
+ *   </TableBody>
+ * </Table>
+ * ```
+ *
+ * Striped 테이블:
+ *
+ * ```tsx
+ * <Table striped hoverable>
+ *   <TableHeader>
+ *     <TableRow>
+ *       <TableHead>제품명</TableHead>
+ *       <TableHead align="right">가격</TableHead>
+ *     </TableRow>
+ *   </TableHeader>
+ *   <TableBody>
+ *     {products.map((product) => (
+ *       <TableRow key={product.id}>
+ *         <TableCell>{product.name}</TableCell>
+ *         <TableCell align="right">{product.price}</TableCell>
+ *       </TableRow>
+ *     ))}
+ *   </TableBody>
+ * </Table>
+ * ```
+ * {@end-tool}
+ */
+declare const tableVariants: (props?: ({
+    bordered?: boolean | null | undefined;
+} & import('class-variance-authority/types').ClassProp) | undefined) => string;
+export interface TableProps extends React.TableHTMLAttributes<HTMLTableElement>, VariantProps<typeof tableVariants> {
+    /** zebra stripe 패턴 적용 여부 */
+    striped?: boolean;
+    /** row hover 효과 적용 여부 */
+    hoverable?: boolean;
+    /** 테두리 표시 여부 */
+    bordered?: boolean;
+    /** 좁은 padding 적용 여부 */
+    compact?: boolean;
+}
+export declare const Table: React.ForwardRefExoticComponent<TableProps & React.RefAttributes<HTMLTableElement>>;
+export interface TableHeaderProps extends React.HTMLAttributes<HTMLTableSectionElement> {
+}
+export declare const TableHeader: React.ForwardRefExoticComponent<TableHeaderProps & React.RefAttributes<HTMLTableSectionElement>>;
+export interface TableBodyProps extends React.HTMLAttributes<HTMLTableSectionElement> {
+}
+export declare const TableBody: React.ForwardRefExoticComponent<TableBodyProps & React.RefAttributes<HTMLTableSectionElement>>;
+export interface TableFooterProps extends React.HTMLAttributes<HTMLTableSectionElement> {
+}
+export declare const TableFooter: React.ForwardRefExoticComponent<TableFooterProps & React.RefAttributes<HTMLTableSectionElement>>;
+declare const tableRowVariants: (props?: ({
+    hoverable?: boolean | null | undefined;
+    selected?: boolean | null | undefined;
+} & import('class-variance-authority/types').ClassProp) | undefined) => string;
+export interface TableRowProps extends React.HTMLAttributes<HTMLTableRowElement>, VariantProps<typeof tableRowVariants> {
+    /** 선택된 행 표시 여부 */
+    selected?: boolean;
+}
+export declare const TableRow: React.ForwardRefExoticComponent<TableRowProps & React.RefAttributes<HTMLTableRowElement>>;
+export interface TableHeadProps extends React.ThHTMLAttributes<HTMLTableCellElement> {
+    /** 정렬 가능 여부 */
+    sortable?: boolean;
+    /** 정렬 방향 */
+    sortDirection?: "asc" | "desc" | null;
+    /** 정렬 클릭 핸들러 */
+    onSort?: () => void;
+}
+export declare const TableHead: React.ForwardRefExoticComponent<TableHeadProps & React.RefAttributes<HTMLTableCellElement>>;
+declare const tableCellVariants: (props?: ({
+    align?: "center" | "right" | "left" | null | undefined;
+} & import('class-variance-authority/types').ClassProp) | undefined) => string;
+export interface TableCellProps extends React.TdHTMLAttributes<HTMLTableCellElement>, VariantProps<typeof tableCellVariants> {
+    /** 텍스트 정렬 방식 */
+    align?: "left" | "center" | "right";
+}
+export declare const TableCell: React.ForwardRefExoticComponent<TableCellProps & React.RefAttributes<HTMLTableCellElement>>;
+export interface TableCaptionProps extends React.HTMLAttributes<HTMLTableCaptionElement> {
+}
+export declare const TableCaption: React.ForwardRefExoticComponent<TableCaptionProps & React.RefAttributes<HTMLTableCaptionElement>>;
+export {};

package/dist/components/Table/index.d.ts

@@ -0,0 +1,2 @@
+export { Table, TableHeader, TableBody, TableFooter, TableRow, TableHead, TableCell, TableCaption, } from './Table';
+export type { TableProps, TableHeaderProps, TableBodyProps, TableFooterProps, TableRowProps, TableHeadProps, TableCellProps, TableCaptionProps, } from './Table';

package/dist/components/TimePicker/TimePicker.d.ts

@@ -0,0 +1,110 @@
+import { default as React } from 'react';
+
+export interface TimePickerProps {
+    value?: string;
+    onChange?: (time: string) => void;
+    label?: string;
+    placeholder?: string;
+    format?: "24h" | "12h";
+    disabled?: boolean;
+    error?: boolean;
+    errorMessage?: string;
+    helperText?: string;
+    className?: string;
+    minuteStep?: number;
+    showIcon?: boolean;
+}
+/**
+ * 사용자가 시간을 선택할 수 있게 하는 컴포넌트입니다.
+ *
+ * {@link TimePicker}는 직관적인 스크롤 인터페이스를 통해 시간과 분을 선택할 수 있으며,
+ * 24시간 형식과 12시간(AM/PM) 형식을 모두 지원합니다.
+ *
+ * `@radix-ui/react-popover`를 기반으로 구현되었으며, 사용자가 잘못된 시간을 입력하는 것을 방지합니다.
+ *
+ * ## When (언제 사용해야 하는가)
+ *
+ * **사용해야 하는 경우:**
+ * - **특정 시간 입력**: 예약 시간, 알림 시간, 업무 시작/종료 시간 등을 선택해야 할 때
+ * - **정확한 시간 선택**: 사용자가 직접 타이핑하여 발생할 수 있는 형식 오류를 방지하고 싶을 때
+ * - **제한된 간격 선택**: 5분, 10분, 15분 단위로만 선택이 필요한 경우 (minuteStep 사용)
+ *
+ * **사용하지 말아야 하는 경우:**
+ * - **대략적인 시간**: '오전', '오후', '저녁' 등 상대적인 시간 선택이 필요한 경우 `Dropdown`이나 `RadioButton`이 더 적절할 수 있습니다.
+ * - **초 단위 정밀도**: 현재는 시간과 분까지만 지원하므로, 초 단위가 필요한 경우 다른 컴포넌트를 고려하세요.
+ *
+ * ## Layout behavior
+ *
+ * - **Popover 기반**: 클릭 시 입력창 아래에 시간 선택 팝오버가 나타나며, 화면 공간을 효율적으로 사용합니다.
+ * - **스크롤 선택**: 시간과 분을 각각 스크롤하여 선택할 수 있어 직관적입니다.
+ * - **Full Width**: `className`을 통해 부모 요소의 너비에 맞게 조절할 수 있습니다.
+ *
+ * ## Usage guidelines
+ *
+ * ### ✅ Do (권장 사항)
+ *
+ * - **적절한 Format**: 사용자가 익숙한 형식(한국: 24시간, 미국: 12시간)을 선택하세요.
+ * - **Minute Step 활용**: 일정 간격으로만 선택이 필요한 경우 `minuteStep`을 활용하여 UX를 개선하세요.
+ * - **레이블 및 헬퍼 텍스트**: 입력 항목의 용도를 명확히 하고, 필요한 경우 보충 설명을 제공하세요.
+ *
+ * ### 🚫 Don't (주의/금지 사항)
+ *
+ * - **Read-only 입력**: 사용자가 직접 타이핑하여 입력하는 기능은 지원하지 않으므로, 반드시 UI를 통해 선택하도록 안내하세요.
+ * - **과도한 Step**: `minuteStep`이 너무 크면 정확한 시간을 선택하기 어려울 수 있습니다.
+ *
+ * ## Accessibility
+ *
+ * - **Keyboard Navigation**: 팝오버는 키보드로 열고 닫을 수 있으며, `Esc` 키로 취소할 수 있습니다.
+ * - **Focus Management**: 시간 선택기가 열려 있는 동안 포커스가 적절히 관리됩니다.
+ * - **Aria Labels**: 각 버튼에는 스크린 리더를 위한 적절한 레이블이 포함되어 있습니다.
+ *
+ * ## Example
+ *
+ * {@tool snippet}
+ * 기본적인 시간 선택 예시 (24시간 형식):
+ *
+ * ```tsx
+ * const [time, setTime] = useState("");
+ *
+ * <TimePicker
+ *   label="출근 시간"
+ *   value={time}
+ *   onChange={setTime}
+ *   placeholder="시간을 선택하세요"
+ * />
+ * ```
+ * {@end-tool}
+ *
+ * {@tool snippet}
+ * 12시간 형식 및 15분 단위 선택:
+ *
+ * ```tsx
+ * <TimePicker
+ *   label="회의 시간"
+ *   format="12h"
+ *   minuteStep={15}
+ *   value="2:30 PM"
+ *   onChange={setTime}
+ * />
+ * ```
+ * {@end-tool}
+ *
+ * {@tool snippet}
+ * 에러 상태:
+ *
+ * ```tsx
+ * <TimePicker
+ *   label="마감 시간"
+ *   error={true}
+ *   errorMessage="업무 시간(9:00-18:00) 내에서 선택해주세요"
+ * />
+ * ```
+ * {@end-tool}
+ *
+ * See also:
+ *
+ * - {@link DatePicker}, 날짜를 선택해야 하는 경우
+ * - {@link DateRangePicker}, 날짜 범위를 선택해야 하는 경우
+ * - {@link TextInput}, 단순한 텍스트 입력이 필요한 경우
+ */
+export declare const TimePicker: React.ForwardRefExoticComponent<TimePickerProps & React.RefAttributes<HTMLDivElement>>;

package/dist/components/TimePicker/index.d.ts

@@ -0,0 +1,2 @@
+export { TimePicker } from './TimePicker';
+export type { TimePickerProps } from './TimePicker';

package/dist/components/ToolTip/ToolTip.d.ts

@@ -0,0 +1,110 @@
+import { default as React } from 'react';
+import * as TooltipPrimitive from "@radix-ui/react-tooltip";
+/**
+ * 마우스 호버나 포커스 시 간단한 힌트나 설명을 제공하는 툴팁 컴포넌트입니다.
+ *
+ * {@link ToolTip}은 UI 요소에 대한 추가 정보를 간결하게 제공하여
+ * 사용자가 인터페이스를 더 쉽게 이해할 수 있도록 돕습니다.
+ *
+ * Radix UI의 Tooltip 컴포넌트를 기반으로 구현되어 접근성 기능이
+ * 자동으로 처리됩니다.
+ *
+ * ## When (언제 사용해야 하는가)
+ *
+ * **사용해야 하는 경우:**
+ * - **아이콘 설명**: 텍스트 레이블이 없는 아이콘 버튼의 기능을 설명할 때
+ * - **축약된 텍스트**: 말줄임표(...)로 잘린 텍스트의 전체 내용을 보여줄 때
+ * - **간단한 힌트**: 입력 필드나 기능에 대한 짧은 도움말을 제공할 때
+ * - **추가 정보**: UI 요소의 상태나 제약사항을 간단히 알려줄 때
+ *
+ * **사용하지 말아야 하는 경우:**
+ * - **필수 정보**: 사용자가 반드시 알아야 하는 정보는 본문에 직접 표시하세요.
+ * - **복잡한 내용**: 여러 줄의 긴 텍스트나 인터랙티브 요소는 Popover나 Modal을 사용하세요.
+ * - **모바일 전용 UI**: 터치 기기에서는 호버가 없으므로 중요한 정보를 툴팁에만 의존하지 마세요.
+ *
+ * ## Layout behavior
+ *
+ * - **Positioning**: 트리거 요소를 기준으로 상하좌우 원하는 위치에 배치됩니다. (기본: top)
+ * - **Auto-adjustment**: 화면 경계를 벗어나지 않도록 자동으로 위치를 조정합니다.
+ * - **Floating**: 다른 UI 요소들 위에 떠 있으며, 레이아웃에 영향을 주지 않습니다.
+ * - **Arrow**: 트리거와의 연결을 시각적으로 나타내는 화살표를 선택적으로 표시할 수 있습니다.
+ *
+ * ## Usage guidelines
+ *
+ * ### ✅ Do (권장 사항)
+ *
+ * - **간결한 텍스트**: 한두 줄 이내의 짧은 텍스트로 핵심만 전달하세요.
+ * - **적절한 지연**: `delayDuration`을 조절하여 우발적인 호버로 인한 깜빡임을 방지하세요. (기본: 200ms)
+ * - **명확한 트리거**: 툴팁이 붙는 요소가 호버 가능함을 사용자가 인지할 수 있도록 하세요.
+ *
+ * ### 🚫 Don't (주의/금지 사항)
+ *
+ * - **중요 정보 숨기기**: 필수적인 정보를 툴팁에만 넣지 마세요.
+ * - **상호작용 요소**: 툴팁 내부에 클릭 가능한 버튼이나 링크를 넣지 마세요. (Popover 사용 권장)
+ * - **과도한 사용**: 모든 요소에 툴팁을 붙이면 오히려 사용성이 떨어집니다.
+ *
+ * ## Accessibility
+ *
+ * - **Keyboard Support**: 포커스 가능한 요소에 툴팁이 붙으면 포커스 시 자동으로 표시됩니다.
+ * - **ESC Key**: `Esc` 키를 누르면 툴팁이 닫힙니다.
+ * - **Screen Readers**: `aria-describedby` 속성이 자동으로 부여되어 스크린 리더가 내용을 읽습니다.
+ * - **Touch Devices**: 터치 기기에서는 탭으로 툴팁을 활성화할 수 있습니다.
+ *
+ * ## Example
+ *
+ * {@tool snippet}
+ * 아이콘 버튼에 툴팁 추가:
+ *
+ * ```tsx
+ * <ToolTip content="설정">
+ *   <Button variant="ghost" size="icon">
+ *     <SettingsIcon />
+ *   </Button>
+ * </ToolTip>
+ * ```
+ *
+ * 위치와 지연 시간 커스터마이징:
+ *
+ * ```tsx
+ * <ToolTip
+ *   content="이 기능은 프리미엄 사용자만 이용할 수 있습니다"
+ *   side="bottom"
+ *   delayDuration={300}
+ * >
+ *   <Button disabled>프리미엄 기능</Button>
+ * </ToolTip>
+ * ```
+ * {@end-tool}
+ *
+ * See also:
+ *
+ * - {@link Popover}, 클릭으로 열고 상호작용이 필요한 경우
+ * - {@link Modal}, 중요한 정보나 복잡한 작업이 필요한 경우
+ */
+export interface ToolTipProps extends Omit<React.ComponentPropsWithoutRef<typeof TooltipPrimitive.Content>, "content"> {
+    /** 툴팁을 트리거하는 요소 */
+    children: React.ReactNode;
+    /** 툴팁에 표시할 내용 */
+    content: React.ReactNode;
+    /** 툴팁이 나타날 위치 (기본: "top") */
+    side?: "top" | "right" | "bottom" | "left";
+    /** 트리거로부터의 거리 (픽셀) (기본: 4) */
+    sideOffset?: number;
+    /** 트리거와의 정렬 방식 (기본: "center") */
+    align?: "start" | "center" | "end";
+    /** 마우스 호버 후 툴팁이 나타나기까지의 지연 시간 (밀리초) (기본: 200) */
+    delayDuration?: number;
+    /** 다른 툴팁에서 빠르게 진입 시 지연 건너뛰기 시간 (밀리초) (기본: 300) */
+    skipDelayDuration?: number;
+    /** 툴팁 위로 마우스를 이동할 수 있는지 여부 (기본: true) */
+    disableHoverableContent?: boolean;
+    /** 화살표 표시 여부 (기본: true) */
+    showArrow?: boolean;
+    /** Controlled 모드: 툴팁 열림 상태 */
+    open?: boolean;
+    /** Uncontrolled 모드: 초기 열림 상태 */
+    defaultOpen?: boolean;
+    /** 툴팁 열림 상태 변경 시 콜백 */
+    onOpenChange?: (open: boolean) => void;
+}
+export declare const ToolTip: React.ForwardRefExoticComponent<ToolTipProps & React.RefAttributes<HTMLDivElement>>;

package/dist/components/ToolTip/index.d.ts

@@ -0,0 +1,2 @@
+export { ToolTip } from './ToolTip';
+export type { ToolTipProps } from './ToolTip';

package/dist/components/index.d.ts

@@ -7,9 +7,13 @@ export * from './Text';
 export * from './TextInput';
 export * from './DatePicker';
 export * from './DateRangePicker';
+export * from './TimePicker';
 export * from './Switch';
 export * from './RadioButton';
 export * from './SideNavigation';
+export * from './Pagination';
 export * from './Checkbox';
 export * from './Modal';
 export * from './Toast';
+export * from './ToolTip';
+export * from './Table';