@cashdoc/cashdoc-cms-design-system 1.0.12

package/dist/src/components/SideNavigation/SideNavigation.d.ts

@@ -0,0 +1,101 @@
+import { default as React } from 'react';
+
+export interface SubMenuItem {
+    url: string;
+    title: string;
+}
+export interface MenuItem {
+    url: string;
+    title: string;
+    icon?: React.ReactNode;
+    subMenu?: SubMenuItem[];
+}
+export interface SideNavigationProps {
+    title?: string;
+    menus: MenuItem[];
+    selectedUrl: string;
+    onMenuClick: (url: string) => void;
+    headerSlot?: React.ReactNode;
+    className?: string;
+}
+/**
+ * 어플리케이션의 주요 섹션 간 이동을 담당하는 왼쪽 사이드바 메뉴 컴포넌트입니다.
+ *
+ * {@link SideNavigation}은 계층형 메뉴 구조(1단계 및 서브메뉴)를 지원하며,
+ * 현재 사용자의 위치를 시각적으로 강조하여 내비게이션 맥락을 제공합니다.
+ * 다크 테마(Dark Theme) 스타일로 고정되어 대시보드 및 CMS 관리 도구에 적합합니다.
+ *
+ * Radix UI의 Accordion 컴포넌트를 기반으로 구현되어 서브메뉴의 펼침/접힘 동작이
+ * 부드럽게 처리됩니다.
+ *
+ * ## When (언제 사용해야 하는가)
+ *
+ * **사용해야 하는 경우:**
+ * - **메인 내비게이션**: 서비스의 핵심 기능을 상시 노출하고 접근해야 할 때
+ * - **계층 구조 관리**: 대메뉴와 그에 속한 소메뉴를 구조적으로 보여줘야 할 때
+ * - **관리자 페이지**: 다양한 관리 도구와 설정 항목을 분류하여 제공할 때
+ *
+ * **사용하지 말아야 하는 경우:**
+ * - **단순 링크 목록**: 3-4개의 단순한 링크라면 상단 내비게이션(GNB)이 더 적절할 수 있습니다.
+ * - **모바일 전용 탭**: 모바일 앱 스타일의 내비게이션이 필요하다면 하단 탭 바를 고려하세요.
+ *
+ * ## Layout behavior
+ *
+ * - **Fixed Width**: 기본적으로 `w-70` (280px)의 고정 너비를 가지며, 세로 전체(h-full)를 차지합니다.
+ * - **Scrollable**: 메뉴 항목이 많아 화면 높이를 넘어가면 메뉴 영역 내부에 스크롤이 발생합니다.
+ * - **Accordion**: 서브메뉴가 있는 항목 클릭 시 아래로 펼쳐지는 애니메이션이 적용됩니다.
+ *
+ * ## Usage guidelines
+ *
+ * ### ✅ Do (권장 사항)
+ *
+ * - **아이콘 활용**: 각 대메뉴에 적절한 아이콘을 배치하여 사용자가 메뉴의 성격을 빠르게 파악하게 하세요.
+ * - **상태 연동**: 현재 활성화된 페이지의 URL과 `selectedUrl`을 정확히 일치시켜 하이라이트가 올바르게 표시되도록 하세요.
+ * - **일관된 그룹화**: 연관된 기능들은 하나의 대메뉴 아래 서브메뉴로 묶어 복잡도를 낮추세요.
+ *
+ * ### 🚫 Don't (주의/금지 사항)
+ *
+ * - **과도한 계층**: 서브메뉴의 서브메뉴(3단계 이상)는 가급적 피하세요. UI가 복잡해지고 사용성이 떨어집니다.
+ * - **긴 메뉴 명칭**: 사이드바 너비가 제한적이므로 메뉴 이름은 짧고 명확하게(가급적 10자 이내) 작성하세요.
+ *
+ * ## Accessibility
+ *
+ * - **Accordion Support**: 서브메뉴 상태를 스크린 리더에서 '펼쳐짐/접힘'으로 인식합니다.
+ * - **Keyboard Interaction**: `Tab` 키로 메뉴를 이동하고, `Enter`나 `Space`로 메뉴를 열거나 이동할 수 있습니다.
+ *
+ * ## Example
+ *
+ * {@tool snippet}
+ * 서브메뉴를 포함한 사이드 네비게이션:
+ *
+ * ```tsx
+ * const menus = [
+ *   { url: '/dashboard', title: '홈', icon: <HomeIcon /> },
+ *   {
+ *     url: '/contents',
+ *     title: '콘텐츠 관리',
+ *     icon: <FileTextIcon />,
+ *     subMenu: [
+ *       { url: '/contents/posts', title: '게시글 목록' },
+ *       { url: '/contents/comments', title: '댓글 관리' },
+ *     ]
+ *   },
+ * ];
+ *
+ * <SideNavigation
+ *   menus={menus}
+ *   selectedUrl="/contents/posts"
+ *   onMenuClick={(url) => navigate(url)}
+ * />
+ * ```
+ * {@end-tool}
+ *
+ * See also:
+ *
+ * - {@link Button}, 단순 액션 실행을 위한 요소
+ * - {@link Popover}, 클릭 시 일시적으로 나타나는 추가 메뉴가 필요한 경우
+ *
+ * ## 참고사진
+ * ![](https://github.com/AlmSmartDoctor/ccds-screenshots/blob/main/screenshots/Navigation/SideNavigation/For%20Jsdoc.png?raw=true)
+ */
+export declare const SideNavigation: React.ForwardRefExoticComponent<SideNavigationProps & React.RefAttributes<HTMLDivElement>>;

package/dist/src/components/SideNavigation/index.d.ts

@@ -0,0 +1 @@
+export * from './SideNavigation';

package/dist/src/components/Switch/Switch.d.ts

@@ -0,0 +1,74 @@
+import { default as React } from 'react';
+import { VariantProps } from 'class-variance-authority';
+
+import * as SwitchPrimitives from "@radix-ui/react-switch";
+declare const switchVariants: (props?: ({
+    variant?: "default" | "green" | "black" | "blue" | "red" | null | undefined;
+} & import('class-variance-authority/types').ClassProp) | undefined) => string;
+export interface SwitchProps extends React.ComponentPropsWithoutRef<typeof SwitchPrimitives.Root>, VariantProps<typeof switchVariants> {
+}
+/**
+ * 두 가지 상반된 상태(On/Off, 활성/비활성)를 즉각적으로 전환할 때 사용하는 컴포넌트입니다.
+ *
+ * {@link Switch}는 실제 전등 스위치와 같은 직관적인 시각적 모델을 제공하며,
+ * 체크박스보다 더 '즉각적인 반영'의 의미를 가집니다.
+ *
+ * Radix UI의 Switch 컴포넌트를 기반으로 구현되어 접근성과 애니메이션이
+ * 자동으로 처리됩니다.
+ *
+ * ## When (언제 사용해야 하는가)
+ *
+ * **사용해야 하는 경우:**
+ * - **즉각적 설정 반영**: 클릭 즉시 시스템 설정이 변경되거나 저장되어야 할 때 (예: 다크모드 켜기, 알림 수신 동의)
+ * - **상태 전환**: 특정 기능의 사용 여부를 결정할 때
+ * - **단순 토글**: 복잡한 입력 없이 켜고 끄는 행위만 필요할 때
+ *
+ * **사용하지 말아야 하는 경우:**
+ * - **제출 버튼 필요**: 여러 정보를 입력하고 '확인' 버튼을 눌러야 결과가 반영되는 폼 내에서는 `Checkbox`를 사용하세요.
+ * - **다중 선택**: 여러 항목 중 일부를 골라야 할 때도 `Checkbox`가 더 적합합니다.
+ *
+ * ## Layout behavior
+ *
+ * - **Inline Component**: 주변 텍스트나 다른 요소와 자연스럽게 어우러지는 인라인 블록 형태입니다.
+ * - **Thumb Animation**: 클릭 시 스위치의 '손잡이(Thumb)'가 부드럽게 좌우로 이동하며 상태 변화를 시각화합니다.
+ *
+ * ## Usage guidelines
+ *
+ * ### ✅ Do (권장 사항)
+ *
+ * - **명확한 현재 상태 표시**: 색상 변화(회색 vs 색상)를 통해 켜져 있는지 꺼져 있는지 한눈에 알 수 있게 하세요.
+ * - **레이블과 함께 사용**: 스위치 옆에 무엇을 제어하는지 설명하는 텍스트를 반드시 배치하세요.
+ *
+ * ### 🚫 Don't (주의/금지 사항)
+ *
+ * - **모호한 의미**: 상태 전환 후에 어떤 변화가 생길지 명확하지 않은 경우에는 사용을 지양하세요.
+ * - **긴 대기 시간**: 서버 통신 등으로 인해 상태 반영에 시간이 걸리는 경우, 로딩 인디케이터를 함께 보여주거나 즉시 반응을 우선 처리하세요.
+ *
+ * ## Accessibility
+ *
+ * - **Keyboard Support**: `Space` 키를 사용하여 상태를 전환할 수 있습니다.
+ * - **Roles**: `role="switch"` 속성을 사용하여 스크린 리더에서 토글 상태를 읽어줍니다.
+ *
+ * ## Example
+ *
+ * {@tool snippet}
+ * 레이블과 함께 사용하는 기본적인 스위치:
+ *
+ * ```tsx
+ * <div className="flex items-center gap-2">
+ *   <Switch id="airplane-mode" />
+ *   <label htmlFor="airplane-mode">비행기 모드</label>
+ * </div>
+ * ```
+ * {@end-tool}
+ *
+ * See also:
+ *
+ * - {@link Checkbox}, 제출 전까지 상태를 유지해야 하는 경우
+ * - {@link RadioButton}, 여러 선택지 중 하나를 고르는 경우
+ *
+ * ## 참고사진
+ * ![](https://github.com/AlmSmartDoctor/ccds-screenshots/blob/main/screenshots/Forms/Switch/For%20Jsdoc.png?raw=true)
+ */
+declare const Switch: React.ForwardRefExoticComponent<SwitchProps & React.RefAttributes<HTMLButtonElement>>;
+export { Switch };

package/dist/src/components/Switch/index.d.ts

@@ -0,0 +1 @@
+export * from './Switch';

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

@@ -0,0 +1,195 @@
+import { default as React } from 'react';
+import { VariantProps } from 'class-variance-authority';
+
+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;
+}
+/**
+ * 데이터를 행과 열로 구조화하여 표시하는 테이블 컴포넌트입니다.
+ *
+ * {@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}
+ *
+ * ## 참고사진
+ * ![](https://github.com/AlmSmartDoctor/ccds-screenshots/blob/main/screenshots/Data Display/Table/For%20Jsdoc.png?raw=true)
+ */
+export declare const Table: React.ForwardRefExoticComponent<TableProps & React.RefAttributes<HTMLTableElement>>;
+export interface TableHeaderProps extends React.HTMLAttributes<HTMLTableSectionElement> {
+}
+/**
+ * 테이블의 헤더 섹션을 정의하는 컴포넌트입니다.
+ *
+ * `<thead>` 태그를 렌더링하며, 보통 `TableRow`와 `TableHead`를 포함하여
+ * 열의 제목을 표시하는 데 사용됩니다.
+ */
+export declare const TableHeader: React.ForwardRefExoticComponent<TableHeaderProps & React.RefAttributes<HTMLTableSectionElement>>;
+export interface TableBodyProps extends React.HTMLAttributes<HTMLTableSectionElement> {
+}
+/**
+ * 테이블의 본문 섹션을 정의하는 컴포넌트입니다.
+ *
+ * `<tbody>` 태그를 렌더링하며, 실제 데이터가 포함된 `TableRow`와 `TableCell`을
+ * 포함합니다.
+ */
+export declare const TableBody: React.ForwardRefExoticComponent<TableBodyProps & React.RefAttributes<HTMLTableSectionElement>>;
+export interface TableFooterProps extends React.HTMLAttributes<HTMLTableSectionElement> {
+}
+/**
+ * 테이블의 푸터 섹션을 정의하는 컴포넌트입니다.
+ *
+ * `<tfoot>` 태그를 렌더링하며, 합계나 요약 정보를 표시하는 데 사용됩니다.
+ */
+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;
+}
+/**
+ * 테이블의 행(Row)을 정의하는 컴포넌트입니다.
+ *
+ * `<tr>` 태그를 렌더링하며, `hoverable`이나 `striped` 속성이 `Table` 컴포넌트에
+ * 적용되었을 때 이에 따른 스타일을 자동으로 적용합니다.
+ */
+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;
+}
+/**
+ * 테이블의 헤더 셀을 정의하는 컴포넌트입니다.
+ *
+ * `<th>` 태그를 렌더링하며, 열의 제목을 표시합니다.
+ * 정렬 기능(`sortable`)을 지원하며, 정렬 방향에 따라 아이콘을 표시할 수 있습니다.
+ */
+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";
+}
+/**
+ * 테이블의 데이터 셀을 정의하는 컴포넌트입니다.
+ *
+ * `<td>` 태그를 렌더링하며, 실제 데이터를 표시합니다.
+ * 텍스트 정렬(`align`)을 설정할 수 있습니다.
+ */
+export declare const TableCell: React.ForwardRefExoticComponent<TableCellProps & React.RefAttributes<HTMLTableCellElement>>;
+export interface TableCaptionProps extends React.HTMLAttributes<HTMLTableCaptionElement> {
+}
+/**
+ * 테이블의 캡션(설명)을 정의하는 컴포넌트입니다.
+ *
+ * `<caption>` 태그를 렌더링하며, 스크린 리더 사용자에게 테이블의 목적을
+ * 설명하는 데 중요한 역할을 합니다.
+ */
+export declare const TableCaption: React.ForwardRefExoticComponent<TableCaptionProps & React.RefAttributes<HTMLTableCaptionElement>>;
+export {};

package/dist/src/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/src/components/TagInput/TagInput.d.ts

@@ -0,0 +1,121 @@
+import { default as React } from 'react';
+import { VariantProps } from 'class-variance-authority';
+
+declare const tagInputContainerVariants: (props?: ({
+    readOnly?: boolean | null | undefined;
+    layout?: "row" | "column" | null | undefined;
+} & import('class-variance-authority/types').ClassProp) | undefined) => string;
+export interface TagInputProps extends Omit<VariantProps<typeof tagInputContainerVariants>, "readOnly"> {
+    label?: string;
+    required?: boolean;
+    maxTags?: number;
+    placeholder?: string;
+    value?: string[];
+    onChange?: (tags: string[]) => void;
+    readOnly?: boolean;
+    noLimit?: boolean;
+    validateTag?: (tag: string, currentTags: string[]) => boolean | string | undefined;
+    className?: string;
+    id?: string;
+    labelLayout?: "vertical" | "horizontal";
+    labelWidth?: string;
+}
+/**
+ * 사용자가 텍스트를 입력하여 여러 개의 태그(키워드) 목록을 생성하고 관리할 수 있는 컴포넌트입니다.
+ *
+ * {@link TagInput}은 입력창 내부에 시각적인 태그를 표시하며,
+ * 엔터(Enter) 키를 통해 새로운 태그를 추가하고 'x' 버튼을 눌러 기존 태그를 제거할 수 있습니다.
+ * 주로 게시글의 태그, 검색 필터 조건, 수신자 목록 등을 입력받을 때 사용됩니다.
+ *
+ * ## When (언제 사용해야 하는가)
+ *
+ * **사용해야 하는 경우:**
+ * - **키워드 입력**: 게시글의 해시태그나 카테고리를 입력받을 때
+ * - **다중 항목 수집**: 여러 개의 이메일 주소나 사용자 아이디를 한꺼번에 입력받아야 할 때
+ * - **제한된 개수의 항목 선택**: 최대 N개까지의 조건을 입력받아야 할 때 (`maxTags` 활용)
+ *
+ * **사용하지 말아야 하는 경우:**
+ * - **단일 텍스트 입력**: 하나의 값만 필요한 경우 일반 `TextInput`을 사용하세요.
+ * - **미리 정의된 옵션**: 고정된 목록에서만 선택해야 한다면 `Dropdown`이나 `Combobox`가 더 적합합니다.
+ *
+ * ## Layout behavior
+ *
+ * - **Flow Layout**: 태그들은 가로 방향으로 나열되며, 공간이 부족하면 자동으로 다음 줄로 넘어갑니다 (`layout="row"`).
+ * - **Column Layout**: 태그들을 수직으로 쌓고 싶을 경우 `layout="column"` 설정을 사용할 수 있습니다.
+ * - **Constraint**: `maxTags`에 도달하면 추가 입력이 차단되며 시각적으로 안내됩니다.
+ *
+ * 레이블 배치는 `labelLayout` prop으로 제어됩니다:
+ * - **vertical** (기본값): Label이 태그 입력 필드 위에 세로로 배치됩니다.
+ * - **horizontal**: Label과 태그 입력 필드가 가로로 나란히 배치됩니다. `labelWidth`로 Label 너비를 조정할 수 있습니다 (기본값: 120px).
+ *
+ * ## Usage guidelines
+ *
+ * ### ✅ Do (권장 사항)
+ *
+ * - **유효성 검사 활용**: `validateTag`를 통해 이메일 형식 확인이나 글자 수 제한 등 비즈니스 로직을 적용하세요.
+ * - **중복 방지**: 동일한 태그가 입력되지 않도록 자동으로 처리되지만, 필요에 따라 사용자에게 알림을 줄 수 있습니다.
+ * - **가로 배치 활용**: 폼에서 여러 입력 필드를 정렬할 때는 `labelLayout="horizontal"`을 사용하여 일관된 레이아웃을 유지하세요.
+ *
+ * ### 🚫 Don't (주의/금지 사항)
+ *
+ * - **너무 긴 태그**: 태그 하나에 너무 긴 문장이 들어가는 것은 피하세요. 가급적 단어나 짧은 구문으로 제한하는 것이 좋습니다.
+ * - **복잡한 인터페이스**: 태그 내부에 너무 많은 기능을 넣지 마세요. 태그는 가볍고 빠르게 훑어볼 수 있어야 합니다.
+ *
+ * ## Accessibility
+ *
+ * - **Keyboard Management**: `Enter`로 추가, `Backspace`(구현 예정) 또는 'x' 버튼 클릭으로 삭제가 가능합니다.
+ * - **Screen Reader**: 추가된 각 태그의 내용과 삭제 버튼의 역할을 음성으로 안내합니다.
+ *
+ * ## Example
+ *
+ * {@tool snippet}
+ * 기본적인 태그 입력 예시:
+ *
+ * ```tsx
+ * <TagInput
+ *   label="게시글 태그"
+ *   maxTags={5}
+ *   placeholder="태그 입력 후 Enter"
+ *   value={['React', 'Next.js']}
+ *   onChange={(tags) => console.log(tags)}
+ * />
+ * ```
+ * {@end-tool}
+ *
+ * {@tool snippet}
+ * 커스텀 유효성 검사가 포함된 태그 입력:
+ *
+ * ```tsx
+ * <TagInput
+ *   validateTag={(tag) => {
+ *     if (tag.length < 2) return "태그는 2글자 이상이어야 합니다.";
+ *     return true;
+ *   }}
+ * />
+ * ```
+ * {@end-tool}
+ *
+ * {@tool snippet}
+ * 가로 배치 레이아웃:
+ *
+ * ```tsx
+ * <TagInput
+ *   label="키워드"
+ *   required={true}
+ *   labelLayout="horizontal"
+ *   labelWidth="150px"
+ *   placeholder="태그 입력 후 Enter"
+ * />
+ * ```
+ * {@end-tool}
+ *
+ * See also:
+ *
+ * - {@link TextInput}, 단순 텍스트 입력이 필요한 경우
+ * - {@link Combobox}, 목록에서 검색하여 태그를 추가하고 싶은 경우
+ *
+ * ## 참고사진
+ * ![](https://github.com/AlmSmartDoctor/ccds-screenshots/blob/main/screenshots/Forms/TagInput/For%20Jsdoc.png?raw=true)
+ */
+export declare const TagInput: React.ForwardRefExoticComponent<TagInputProps & React.RefAttributes<HTMLDivElement>>;
+export {};

package/dist/src/components/TagInput/index.d.ts

@@ -0,0 +1 @@
+export * from './TagInput';

package/dist/src/components/Text/Text.d.ts

@@ -0,0 +1,74 @@
+import { default as React } from 'react';
+import { VariantProps } from 'class-variance-authority';
+
+declare const textVariants: (props?: ({
+    variant?: "h2" | "h3" | "body" | "caption" | "h1" | "subtitle" | "emphasis" | "price" | null | undefined;
+    align?: "center" | "right" | "left" | null | undefined;
+    decoration?: "none" | "underline" | "lineThrough" | null | undefined;
+} & import('class-variance-authority/types').ClassProp) | undefined) => string;
+export interface TextProps extends React.HTMLAttributes<HTMLElement>, VariantProps<typeof textVariants> {
+    as?: "p" | "span" | "div" | "h1" | "h2" | "h3" | "h4" | "h5" | "h6" | "label";
+    children: React.ReactNode;
+}
+/**
+ * 일관된 타이포그래피 시스템을 적용하기 위한 텍스트 컴포넌트입니다.
+ *
+ * {@link Text}는 제목(Heading), 본문(Body), 캡션(Caption) 등 미리 정의된 스타일을 제공하여
+ * 디자인 일관성을 유지하고 텍스트의 의미적 구조(Semantic Structure)를 쉽게 정의할 수 있게 합니다.
+ *
+ * ## When (언제 사용해야 하는가)
+ *
+ * **사용해야 하는 경우:**
+ * - **페이지 제목 및 부제목**: 화면의 위계를 나누는 타이틀을 작성할 때
+ * - **본문 콘텐츠**: 일반적인 설명글이나 데이터를 표시할 때
+ * - **캡션 및 힌트**: 부가적인 설명이나 작은 크기의 정보가 필요할 때
+ * - **정형화된 스타일**: 특정 폰트 두께나 크기를 시스템 규칙에 맞춰 적용해야 할 때
+ *
+ * **사용하지 말아야 하는 경우:**
+ * - **복잡한 스타일링**: 시스템 정의 범위를 크게 벗어나는 특수 스타일은 별도 CSS 클래스를 활용하세요.
+ *
+ * ## Layout behavior
+ *
+ * - **Semantic Tag**: `as` prop을 통해 실제 HTML 태그(`h1`, `p`, `span` 등)를 결정할 수 있어 SEO와 접근성에 유리합니다.
+ * - **Alignment**: `align` 속성을 통해 왼쪽, 중앙, 오른쪽 정렬을 손쉽게 조절할 수 있습니다.
+ *
+ * ## Usage guidelines
+ *
+ * ### ✅ Do (권장 사항)
+ *
+ * - **의미론적 태그 사용**: 제목에는 `as="h1"`, 본문에는 `as="p"`를 사용하는 등 맥락에 맞는 태그를 선택하세요.
+ * - **계층 구조 준수**: 큰 제목(h1) 아래에 작은 제목(h2, h3)이 오도록 논리적인 흐름을 유지하세요.
+ * - **변형(Variant) 활용**: 폰트 크기와 두께를 직접 조절하기보다 제공되는 `variant`를 우선적으로 사용하세요.
+ *
+ * ### 🚫 Don't (주의/금지 사항)
+ *
+ * - **과도한 폰트 크기 사용**: 가급적 시스템에서 정의한 크기를 벗어나지 않도록 주의하세요.
+ * - **의미와 맞지 않는 태그**: 시각적으로만 크게 보이기 위해 제목 태그를 남용하지 마세요.
+ *
+ * ## Example
+ *
+ * {@tool snippet}
+ * 다양한 위계의 텍스트 구성:
+ *
+ * ```tsx
+ * <div className="space-y-4">
+ *   <Text variant="h1" as="h1">대시보드</Text>
+ *   <Text variant="subtitle">오늘의 요약 정보입니다.</Text>
+ *   <Text variant="body">
+ *     현재 활성화된 사용자는 총 1,234명이며, 어제 대비 5% 증가했습니다.
+ *   </Text>
+ *   <Text variant="caption" align="right">최근 업데이트: 2024-01-24</Text>
+ * </div>
+ * ```
+ * {@end-tool}
+ *
+ * See also:
+ *
+ * - {@link TextInput}, 사용자의 입력을 받는 텍스트 필드
+ * - {@link Button}, 텍스트를 포함하는 액션 요소
+ *
+ * ## 참고사진
+ * ![](https://github.com/AlmSmartDoctor/ccds-screenshots/blob/main/screenshots/Data%20Display/Text/For%20Jsdoc.png?raw=true)
+ */
+export declare const Text: React.ForwardRefExoticComponent<TextProps & React.RefAttributes<HTMLElement>>;
+export {};

package/dist/src/components/Text/index.d.ts

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