cashdoc-cms-design-system 1.0.2 → 1.0.4

package/README.md

@@ -1,6 +1,16 @@
 # Cashdoc CMS Design System
 
-Cashdoc CMS용 디자인 시스템 컴포넌트 라이브러리 [Storybook](https://cashdoc-cms-design-system.vercel.app/?path=/docs/components-button--docs)
+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 />
 
 ## 기술 스택
 
@@ -12,12 +22,16 @@ Cashdoc CMS용 디자인 시스템 컴포넌트 라이브러리 [Storybook](http
 - **Vite** - 빌드 도구
 - **Storybook** - 컴포넌트 문서화
 
+<br />
+
 ## 설치
 
 ```bash
 pnpm install cashdoc-cms-design-system
 ```
 
+<br />
+
 ## 사용법
 
 프로젝트 최상단에서 cashdoc-cms-design-system의 `style.css` 파일을 import 후 사용하면 됩니다.
@@ -34,6 +48,8 @@ function App() {
 }
 ```
 
+<br />
+
 ## 컴포넌트 리스트
 
 ### Form
@@ -74,7 +90,9 @@ function App() {
 - `Text` - 타이포그래피
 - `Icons` - 아이콘 세트
 
-## 개발
+#
+<br />
+# 개발
 
 ### 로컬 개발 서버
 

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/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

@@ -15,3 +15,5 @@ export * from './Pagination';
 export * from './Checkbox';
 export * from './Modal';
 export * from './Toast';
+export * from './ToolTip';
+export * from './Table';