cashdoc-cms-design-system 1.0.0 → 1.0.2

package/README.md

@@ -1 +1,107 @@
+# Cashdoc CMS Design System
 
+Cashdoc CMS용 디자인 시스템 컴포넌트 라이브러리 [Storybook](https://cashdoc-cms-design-system.vercel.app/?path=/docs/components-button--docs)
+
+## 기술 스택
+
+- **React 18** - UI 라이브러리
+- **TypeScript** - 타입 안전성
+- **TailwindCSS** - 스타일링
+- **Radix UI** - 접근성 프리미티브
+- **Framer Motion** - 애니메이션
+- **Vite** - 빌드 도구
+- **Storybook** - 컴포넌트 문서화
+
+## 설치
+
+```bash
+pnpm install cashdoc-cms-design-system
+```
+
+## 사용법
+
+프로젝트 최상단에서 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>;
+}
+```
+
+## 컴포넌트 리스트
+
+### 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` - 아이콘 세트
+
+## 개발
+
+### 로컬 개발 서버
+
+```bash
+pnpm dev
+```
+
+### Storybook 실행
+
+```bash
+pnpm storybook
+```
+
+### 빌드
+
+```bash
+pnpm build
+```
+
+### 타입 체크
+
+```bash
+pnpm type-check
+```
+
+### 린트
+
+```bash
+pnpm lint
+```

package/dist/components/Button/Button.d.ts

@@ -1,11 +1,127 @@
 import { VariantProps } from 'class-variance-authority';
 import { ButtonHTMLAttributes } from 'react';
 
+/**
+ * 버튼 컴포넌트의 스타일 variant를 정의합니다.
+ *
+ * @variant default - 기본 스타일 (회색 배경)
+ * @variant secondary - 보조 스타일 (밝은 회색 배경)
+ * @variant outline - 테두리 스타일 (투명 배경)
+ * @variant ghost - 고스트 스타일 (투명 배경, hover시 배경)
+ * @variant link - 링크 스타일 (밑줄)
+ *
+ * @size default - 기본 크기 (h-10)
+ * @size sm - 작은 크기 (h-8)
+ * @size lg - 큰 크기 (h-11)
+ * @size icon - 아이콘 크기 (정사각형 10x10)
+ */
 export declare const buttonVariants: (props?: ({
     variant?: "default" | "secondary" | "outline" | "ghost" | "link" | null | undefined;
     size?: "default" | "sm" | "lg" | "icon" | null | undefined;
 } & import('class-variance-authority/types').ClassProp) | undefined) => string;
 export interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement>, VariantProps<typeof buttonVariants> {
 }
+/**
+ * 사용자의 클릭 동작을 통해 특정 액션을 실행하거나 페이지를 이동시키는 기본적인 컴포넌트입니다.
+ *
+ * {@link Button}은 다양한 시각적 스타일(Variant)과 크기(Size)를 제공하여 인터페이스의
+ * 계층 구조를 명확히 하고 사용자의 행동을 유도합니다.
+ *
+ * ## When (언제 사용해야 하는가)
+ * ### 사용해야 하는 경우
+ *
+ * - **액션 실행**: 데이터 저장, 삭제, 전송 등 시스템 상태를 변경하는 작업을 수행할 때
+ * - **명확한 콜 투 액션(CTA)**: 페이지 내에서 가장 중요한 작업을 강조할 때
+ * - **내비게이션**: 다른 페이지로의 이동이나 섹션 전환이 필요할 때
+ * - **상태 변경**: 모달 열기, 드롭다운 토글 등 UI 요소를 제어할 때
+ *
+ * ### 사용하지 말아야 하는 경우:
+ *
+ * - **단순 링크**: 본문 내에서 다른 페이지로 연결되는 텍스트 링크는 `<a>` 태그나 별도의 Link 컴포넌트를 사용하세요
+ * - **여러 선택지 중 하나 선택**: `RadioButton`이나 `Checkbox`를 고려하세요
+ * - **탐색 메뉴**: `SideNavigation`이나 상단 메뉴에는 전용 메뉴 아이템을 사용하세요
+ *
+ * ---
+ *
+ * ## Layout behavior
+ *
+ * - **Inline-flex**: 기본적으로 인라인 블록 요소처럼 동작하여 텍스트 흐름 내에 배치됩니다.
+ * - **W-full**: `fullWidth` prop을 통해 부모 컨테이너의 전체 너비를 차지하게 할 수 있습니다.
+ * - **Center Alignment**: 버튼 내부의 텍스트와 아이콘은 항상 중앙에 정렬됩니다.
+ * - **Responsive**: 모바일 환경을 위해 `fullWidth`를 적극 활용하는 것이 좋습니다.
+ *
+ * ---
+ *
+ * ## Usage guidelines
+ *
+ * ### ✅ Do (권장 사항)
+ *
+ * - **명확한 동사 사용**: '저장', '삭제', '추가' 등 행동을 직접적으로 나타내는 레이블을 사용하세요.
+ * - **계층 구조 유지**: 한 화면에 여러 버튼이 있다면 가장 중요한 버튼에만 'primary' variant를 적용하세요.
+ * - **일관된 위치**: 확인 버튼은 오른쪽, 취소 버튼은 왼쪽에 배치하는 등 일관된 배치 규칙을 따르세요.
+ * - **로딩 상태 활용**: 서버 통신 등 시간이 걸리는 작업 시 `isLoading` 상태를 표시하여 중복 클릭을 방지하세요.
+ *
+ * ### 🚫 Don't (주의/금지 사항)
+ *
+ * - **레이블 생략 지양**: 아이콘만 있는 버튼(Icon Button)의 경우 접근성을 위해 반드시 `aria-label`을 제공하세요.
+ * - **너무 긴 텍스트**: 버튼 레이블은 가급적 짧고 간결하게 유지하세요 (보통 2-4자).
+ * - **모호한 표현**: '확인'보다는 '변경사항 저장'과 같이 구체적인 결과가 예상되는 레이블이 좋습니다.
+ *
+ * ---
+ *
+ * ## Accessibility
+ *
+ * - **Keyboard Support**: `Enter`와 `Space` 키로 실행 가능하며, 포커스 상태가 시각적으로 명확히 표시됩니다.
+ * - **ARIA Attributes**: `disabled` 상태 시 `aria-disabled`가 자동으로 처리됩니다.
+ * - **Role**: 기본적으로 `<button>` 태그를 사용하며, 필요한 경우 `asChild`를 통해 다른 요소(Link 등)로 렌더링하면서도 버튼의 스타일을 유지할 수 있습니다.
+ *
+ * ---
+ *
+ * ## Example
+ *
+ * {@tool snippet}
+ * 기본적인 버튼 사용 예시:
+ *
+ * ```tsx
+ * <div className="flex gap-2">
+ *   <Button variant="primary">저장하기</Button>
+ *   <Button variant="outline">취소</Button>
+ *   <Button variant="ghost">닫기</Button>
+ * </div>
+ * ```
+ * {@end-tool}
+ *
+ * {@tool snippet}
+ * 아이콘과 로딩 상태가 포함된 버튼:
+ *
+ * ```tsx
+ * <Button
+ *   isLoading={isSubmitting}
+ *   leftIcon={<SaveIcon />}
+ *   onClick={handleSubmit}
+ * >
+ *   데이터 저장
+ * </Button>
+ * ```
+ * {@end-tool}
+ *
+ * {@tool snippet}
+ * 크기 변형 예시:
+ *
+ * ```tsx
+ * <div className="flex items-center gap-2">
+ *   <Button size="sm">Small</Button>
+ *   <Button size="md">Medium</Button>
+ *   <Button size="lg">Large</Button>
+ * </div>
+ * ```
+ * {@end-tool}
+ *s
+ * See also:
+ *
+ * - {@link TextInput}, 입력과 함께 액션이 필요한 경우
+ * - {@link Modal}, 중요한 결정을 위한 버튼을 포함하는 오버레이
+ * - {@link IconButton}, 아이콘만으로 구성된 버튼을 구성할 때
+ */
 declare const Button: import('react').ForwardRefExoticComponent<ButtonProps & import('react').RefAttributes<HTMLButtonElement>>;
 export { Button };

package/dist/components/Checkbox/Checkbox.d.ts

@@ -5,4 +5,83 @@ export interface CheckboxProps extends React.ComponentPropsWithoutRef<typeof Che
     label?: string;
     id?: string;
 }
+/**
+ * 사용자가 여러 옵션 중 하나 이상을 선택하거나, 특정 항목의 활성화 상태를 제어할 때 사용하는 컴포넌트입니다.
+ *
+ * {@link Checkbox}는 개별적인 On/Off 상태를 표시하며, 주로 목록에서의 다중 선택이나
+ * 설정 화면에서 특정 기능의 사용 여부를 결정할 때 사용됩니다.
+ *
+ * Radix UI의 Checkbox 컴포넌트를 기반으로 구현되어 접근성과 키보드 내비게이션이
+ * 자동으로 처리됩니다.
+ *
+ * ## When (언제 사용해야 하는가)
+ *
+ * **사용해야 하는 경우:**
+ * - **다중 선택**: 목록에서 여러 항목을 동시에 선택해야 할 때
+ * - **단일 승인**: 이용약관 동의와 같이 하나의 항목에 대해 확인이 필요할 때
+ * - **설정 제어**: 특정 기능의 활성화/비활성화 상태를 토글할 때
+ * - **필터링**: 여러 조건(카테고리, 날짜 등)을 동시에 적용하여 결과를 필터링할 때
+ *
+ * **사용하지 말아야 하는 경우:**
+ * - **상호 배타적 선택**: 여러 옵션 중 단 하나만 선택해야 하는 경우 `RadioButton`을 사용하세요.
+ * - **즉각적인 상태 반영**: 설정을 바꾸자마자 페이지에 즉시 반영되는 경우 `Switch` 컴포넌트가 더 적절할 수 있습니다.
+ *
+ * ## Layout behavior
+ *
+ * - **Inline Alignment**: 레이블과 함께 가로로 나란히 배치되며, 기본적으로 인라인 블록 요소처럼 동작합니다.
+ * - **Spacing**: 체크박스와 레이블 사이에는 일정한 간격(8px/0.5rem)이 유지됩니다.
+ * - **Touch Area**: 모바일 대응을 위해 레이블 클릭 시에도 체크박스가 선택되도록 `htmlFor` 속성이 연결되어 있습니다.
+ *
+ * ## Usage guidelines
+ *
+ * ### ✅ Do (권장 사항)
+ *
+ * - **명확한 레이블 제공**: 체크박스가 무엇을 제어하는지 명확하게 설명하는 레이블을 함께 사용하세요.
+ * - **긍정형 문장 사용**: '알림 받지 않기'보다는 '알림 받기'와 같이 긍정형 문구로 작성하는 것이 혼란을 줄입니다.
+ * - **그룹화**: 여러 체크박스가 하나의 주제를 다룬다면 적절한 제목 아래에 그룹화하세요.
+ *
+ * ### 🚫 Don't (주의/금지 사항)
+ *
+ * - **레이블 생략 지양**: 공간이 매우 협소한 경우가 아니라면 항상 레이블을 함께 제공하세요.
+ * - **복잡한 텍스트**: 레이블에 너무 많은 정보나 설명을 넣지 마세요. 필요하다면 툴팁이나 별도의 설명 텍스트를 사용하세요.
+ *
+ * ## Accessibility
+ *
+ * - **Keyboard Interaction**: `Space` 키를 사용하여 체크 상태를 전환할 수 있습니다.
+ * - **Focus Management**: 탭 키를 통해 포커스를 이동할 수 있으며, 포커스 시 시각적인 강조 효과가 나타납니다.
+ * - **WAI-ARIA**: `role="checkbox"`를 사용하며, 체크 상태에 따라 `aria-checked` 값이 자동으로 업데이트됩니다.
+ * - **Label Connection**: `id`와 `htmlFor`가 자동으로 연결되어 스크린 리더가 레이블을 읽어줍니다.
+ *
+ * ## Example
+ *
+ * {@tool snippet}
+ * 기본적인 체크박스 사용 예시:
+ *
+ * ```tsx
+ * <Checkbox
+ *   label="이용약관에 동의합니다"
+ *   checked={agreed}
+ *   onCheckedChange={setAgreed}
+ * />
+ * ```
+ * {@end-tool}
+ *
+ * {@tool snippet}
+ * 비활성화된 체크박스:
+ *
+ * ```tsx
+ * <Checkbox
+ *   label="선택 불가능한 옵션"
+ *   disabled
+ *   checked={true}
+ * />
+ * ```
+ * {@end-tool}
+ *
+ * See also:
+ *
+ * - {@link RadioButton}, 하나만 선택해야 하는 경우
+ * - {@link Switch}, 즉각적인 상태 반영이 필요한 경우
+ * - {@link Button}, 단순 액션 실행이 필요한 경우
+ */
 export declare const Checkbox: React.ForwardRefExoticComponent<CheckboxProps & React.RefAttributes<HTMLButtonElement>>;

package/dist/components/DatePicker/DatePicker.d.ts

@@ -13,4 +13,86 @@ export interface DatePickerProps {
     helperText?: string;
     className?: string;
 }
+/**
+ * 사용자가 달력 인터페이스를 통해 특정 날짜를 선택할 수 있게 하는 컴포넌트입니다.
+ *
+ * {@link DatePicker}는 직접적인 텍스트 입력 대신 시각적인 달력을 제공하여
+ * 날짜 형식의 오류를 방지하고 사용자 편의성을 높입니다.
+ *
+ * `react-day-picker`와 `dayjs`를 기반으로 구현되었으며, 한국어 로케일을 기본으로 지원합니다.
+ *
+ * ## When (언제 사용해야 하는가)
+ *
+ * **사용해야 하는 경우:**
+ * - **특정일 선택**: 생년월일, 예약일, 마감일 등 단일 날짜를 입력받아야 할 때
+ * - **제한된 범위 내 선택**: 과거 날짜만 선택 가능하거나, 특정 기간 내에서만 선택해야 할 때
+ * - **정확한 날짜 입력**: 텍스트 입력 시 발생할 수 있는 포맷 오류를 방지하고 싶을 때
+ *
+ * **사용하지 말아야 하는 경우:**
+ * - **기간 선택**: 시작일과 종료일을 함께 선택해야 하는 경우 `DateRangePicker`를 사용하세요.
+ * - **대략적인 시간/날짜**: '방금 전', '1주일 내' 등 상대적인 시간 선택이 필요한 경우 `Dropdown`이나 `RadioButton`이 더 적절할 수 있습니다.
+ * - **빠른 연도 이동**: 수십 년 전의 날짜를 선택해야 하는 경우(예: 생년월일) 달력보다는 직접 입력이나 연도 선택 기능이 포함된 별도 UI를 고려하세요.
+ *
+ * ## Layout behavior
+ *
+ * - **Popover 기반**: 클릭 시 입력창 아래에 달력 팝오버가 나타나며, 화면 공간을 효율적으로 사용합니다.
+ * - **Responsive**: 팝오버는 화면 경계 내에서 최적의 위치를 자동으로 찾아 표시됩니다.
+ * - **Full Width**: `className`을 통해 부모 요소의 너비에 맞게 조절할 수 있습니다.
+ *
+ * ## Usage guidelines
+ *
+ * ### ✅ Do (권장 사항)
+ *
+ * - **적절한 Placeholder**: "YYYY-MM-DD"와 같이 기대하는 날짜 형식을 명시하세요.
+ * - **최소/최대 날짜 설정**: 비즈니스 로직에 따라 `min`, `max` 속성을 사용하여 유효하지 않은 날짜 선택을 방지하세요.
+ * - **레이블 및 헬퍼 텍스트**: 입력 항목의 용도를 명확히 하고, 필요한 경우 보충 설명을 제공하세요.
+ *
+ * ### 🚫 Don't (주의/금지 사항)
+ *
+ * - **Read-only 입력**: 사용자가 직접 타이핑하여 입력하는 기능은 현재 지원하지 않으므로, 반드시 달력을 통해 선택하도록 안내하세요.
+ * - **복잡한 로직**: 너무 많은 날짜 제한 로직은 사용자에게 혼란을 줄 수 있습니다. 필요한 경우 에러 메시지로 명확히 안내하세요.
+ *
+ * ## Accessibility
+ *
+ * - **Keyboard Navigation**: 팝오버는 키보드로 열고 닫을 수 있으며, `Esc` 키로 취소할 수 있습니다.
+ * - **Focus Trap**: 달력이 열려 있는 동안 포커스가 달력 내부에 머무르도록 관리됩니다.
+ * - **Aria Labels**: 달력의 각 요소에는 스크린 리더를 위한 적절한 레이블이 포함되어 있습니다.
+ *
+ * ## Example
+ *
+ * {@tool snippet}
+ * 기본적인 날짜 선택 예시:
+ *
+ * ```tsx
+ * const [date, setDate] = useState("");
+ *
+ * <DatePicker
+ *   label="방문 예약일"
+ *   value={date}
+ *   onChange={setDate}
+ *   placeholder="예약 날짜를 선택하세요"
+ * />
+ * ```
+ * {@end-tool}
+ *
+ * {@tool snippet}
+ * 날짜 범위 제한 및 에러 상태:
+ *
+ * ```tsx
+ * <DatePicker
+ *   label="종료일"
+ *   min="2024-01-01"
+ *   max="2024-12-31"
+ *   error={true}
+ *   errorMessage="2024년 내의 날짜만 선택 가능합니다"
+ * />
+ * ```
+ * {@end-tool}
+ *
+ * See also:
+ *
+ * - {@link DateRangePicker}, 기간을 선택해야 하는 경우
+ * - {@link TextInput}, 단순한 텍스트 입력이 필요한 경우
+ * - {@link Popover}, 일반적인 팝오버 컴포넌트
+ */
 export declare const DatePicker: React.ForwardRefExoticComponent<DatePickerProps & React.RefAttributes<HTMLDivElement>>;

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

@@ -1,4 +1,2 @@
 export { DatePicker } from './DatePicker';
 export type { DatePickerProps } from './DatePicker';
-export { DateRangePicker } from './DateRangePicker';
-export type { DateRangePickerProps, DateRange } from './DateRangePicker';

package/dist/components/DateRangePicker/DateRangePicker.d.ts

@@ -0,0 +1,93 @@
+import { default as React } from 'react';
+
+export interface DateRange {
+    start: string;
+    end: string;
+}
+export interface DateRangePickerProps {
+    value?: DateRange;
+    onChange?: (range: DateRange) => void;
+    startLabel?: string;
+    endLabel?: string;
+    className?: string;
+}
+/**
+ * 사용자가 특정 기간(시작일과 종료일)을 선택할 수 있게 하는 컴포넌트입니다.
+ *
+ * {@link DateRangePicker}는 두 개의 연동된 달력을 통해 기간을 시각적으로 선택할 수 있으며,
+ * '오늘', '이번주', '7일' 등 자주 사용되는 기간에 대한 빠른 선택(Quick Select) 기능을 제공합니다.
+ *
+ * `react-day-picker`와 `dayjs`를 기반으로 구현되었으며, 대규모 데이터 조회나
+ * 일정 설정 등 기간 입력이 필요한 서비스에서 주로 사용됩니다.
+ *
+ * ## When (언제 사용해야 하는가)
+ *
+ * **사용해야 하는 경우:**
+ * - **조회 기간 설정**: 특정 기간 내의 로그, 주문 내역, 통계 데이터 등을 조회할 때
+ * - **일정 범위 지정**: 이벤트 진행 기간, 캠페인 유효 기간 등 시작과 끝이 있는 일정을 설정할 때
+ * - **상대적 기간 선택**: '최근 7일', '이번 달' 등 현재 시점 기준의 상대적 기간을 빠르게 선택해야 할 때
+ *
+ * **사용하지 말아야 하는 경우:**
+ * - **단일 날짜 선택**: 하나의 날짜만 필요한 경우 `DatePicker`를 사용하세요.
+ * - **고정된 기간**: '1주일', '1개월' 등 기간이 고정되어 있고 시작일만 선택하면 되는 경우 `DatePicker`와 드롭다운 조합이 더 나을 수 있습니다.
+ *
+ * ## Layout behavior
+ *
+ * - **Dual Calendar**: 두 개의 달력이 나란히 표시되어 시작일과 종료일을 한눈에 확인하고 조절할 수 있습니다.
+ * - **Side Panels**: 왼쪽 사이드바에 '오늘', '이번주' 등 빠른 선택 버튼이 배치되어 접근성을 높입니다.
+ * - **Combined Input**: 두 개의 입력창(시작, 종료)이 하나의 그룹으로 묶여 표시됩니다.
+ *
+ * ## Usage guidelines
+ *
+ * ### ✅ Do (권장 사항)
+ *
+ * - **적절한 시작/종료 레이블**: "시작일", "종료일" 또는 "등록일", "수정일" 등 문맥에 맞는 레이블을 사용하세요.
+ * - **기간 확인 피드백**: 선택된 총 일수(예: 7일간)를 하단에 표시하여 사용자가 선택한 범위를 쉽게 인지하게 하세요.
+ * - **빠른 선택 활용**: 사용자 조사의 80% 이상이 '최근 7일'이라면 해당 옵션을 눈에 띄게 배치하거나 기본값으로 고려하세요.
+ *
+ * ### 🚫 Don't (주의/금지 사항)
+ *
+ * - **너무 넓은 기본 범위**: 데이터 양이 많을 경우 기본 범위를 너무 넓게 잡으면 성능 문제가 발생할 수 있습니다.
+ * - **모바일에서의 레이아웃**: 2개의 달력이 나란히 표시되므로 모바일 환경에서는 화면을 넘칠 수 있습니다. 반응형 대응에 주의하세요.
+ *
+ * ## Accessibility
+ *
+ * - **Keyboard Management**: `Tab` 키로 시작일/종료일 입력창과 달력 내부 요소를 순차적으로 이동할 수 있습니다.
+ * - **Visual Indicators**: 선택된 기간 내의 날짜들은 배경색으로 하이라이트되어 시각적으로 구분됩니다.
+ * - **Screen Reader**: 시작일과 종료일의 레이블이 각각 명확히 연결되어 음성으로 안내됩니다.
+ *
+ * ## Example
+ *
+ * {@tool snippet}
+ * 기본적인 기간 선택 예시:
+ *
+ * ```tsx
+ * const [range, setRange] = useState({ start: "2024-01-01", end: "2024-01-07" });
+ *
+ * <DateRangePicker
+ *   value={range}
+ *   onChange={setRange}
+ *   startLabel="조회 시작"
+ *   endLabel="조회 종료"
+ * />
+ * ```
+ * {@end-tool}
+ *
+ * {@tool snippet}
+ * 빠른 선택 옵션이 포함된 초기 상태:
+ *
+ * ```tsx
+ * // '전체', '오늘', '내일', '이번주', '이번달', '7일', '30일' 등의
+ * // 빠른 선택 옵션이 기본적으로 내장되어 있습니다.
+ * <DateRangePicker
+ *   className="w-[400px]"
+ * />
+ * ```
+ * {@end-tool}
+ *
+ * See also:
+ *
+ * - {@link DatePicker}, 단일 날짜 선택이 필요한 경우
+ * - {@link Dropdown}, 기간을 텍스트 기반의 선택지로 제공할 때
+ */
+export declare const DateRangePicker: React.ForwardRefExoticComponent<DateRangePickerProps & React.RefAttributes<HTMLDivElement>>;

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

@@ -0,0 +1,2 @@
+export { DateRangePicker } from './DateRangePicker';
+export type { DateRangePickerProps, DateRange } from './DateRangePicker';

package/dist/components/Dropdown/Combobox.d.ts

@@ -5,4 +5,82 @@ export interface ComboboxProps extends Omit<DropdownProps, "searchable"> {
     createable?: boolean;
     onCreateOption?: (value: string) => void;
 }
+/**
+ * 텍스트 입력과 드롭다운 선택 기능이 결합되어, 목록에서 검색하거나 새로운 옵션을 생성할 수 있는 컴포넌트입니다.
+ *
+ * {@link Combobox}는 사용자가 방대한 목록에서 원하는 항목을 빠르게 찾을 수 있도록 돕고,
+ * 만약 찾는 항목이 없을 경우 즉석에서 새로운 값을 추가할 수 있는 유연성을 제공합니다.
+ *
+ * {@link Dropdown}의 확장 버전으로, 기본적으로 `searchable` 기능이 활성화되어 있습니다.
+ *
+ * ## When (언제 사용해야 하는가)
+ *
+ * **사용해야 하는 경우:**
+ * - **대량 데이터 검색**: 옵션이 수백 개 이상이어서 단순 스크롤로는 찾기 어려운 경우
+ * - **동적 옵션 추가**: 목록에 없는 값을 사용자가 직접 입력하여 데이터베이스에 추가해야 할 때 (예: 태그 입력, 신규 제조사 추가 등)
+ * - **빠른 필터링**: 사용자가 정확한 명칭을 입력하여 필터링된 결과만 보고 싶어 할 때
+ *
+ * **사용하지 말아야 하는 경우:**
+ * - **옵션이 고정된 경우**: 새로운 값을 추가할 필요가 없고 옵션 개수가 적다면 일반 `Dropdown`이나 `Select`가 더 단순합니다.
+ * - **자유 텍스트 입력**: 미리 정의된 옵션 없이 자유로운 입력을 받는 것이 주 목적이라면 `TextInput`을 사용하세요.
+ *
+ * ## Layout behavior
+ *
+ * - **Auto-filtering**: 사용자가 입력할 때마다 목록이 즉시 필터링되어 업데이트됩니다.
+ * - **Create Option**: `createable` 설정 시, 검색 결과가 없을 경우 최하단에 '생성' 옵션이 나타납니다.
+ *
+ * ## Usage guidelines
+ *
+ * ### ✅ Do (권장 사항)
+ *
+ * - **로딩 상태 표시**: 대규모 데이터를 원격에서 가져오는 경우 `loading` 속성을 통해 사용자에게 진행 상황을 알리세요.
+ * - **명확한 생성 문구**: 새로운 항목을 생성할 때 무엇이 생성되는지 사용자에게 명확히 전달하세요.
+ * - **검색 최적화**: 대소문자 구분 없는 검색 등 사용자가 입력하기 편한 검색 환경을 제공하세요.
+ *
+ * ### 🚫 Don't (주의/금지 사항)
+ *
+ * - **검색창 없는 콤보박스**: 콤보박스의 핵심은 검색입니다. 검색이 필요 없다면 일반 드롭다운을 사용하세요.
+ * - **복잡한 생성 과정**: `onCreateOption`에서 너무 복잡한 로직을 처리하면 UI가 멈춘 것처럼 보일 수 있습니다. 비동기 처리 시 로딩 상태를 적절히 활용하세요.
+ *
+ * ## Accessibility
+ *
+ * - **Aria Roles**: `role="combobox"`를 사용하여 입력과 선택이 가능한 요소임을 스크린 리더에 알립니다.
+ * - **Live Regions**: 필터링 결과의 개수 변화 등을 시각 장애 사용자에게 알릴 수 있도록 설계되었습니다.
+ *
+ * ## Example
+ *
+ * {@tool snippet}
+ * 새로운 옵션을 생성할 수 있는 콤보박스:
+ *
+ * ```tsx
+ * <Combobox
+ *   options={existingTags}
+ *   createable={true}
+ *   onCreateOption={(newTag) => {
+ *     // 서버에 태그 추가 요청 후 목록 업데이트
+ *     handleCreateTag(newTag);
+ *   }}
+ *   placeholder="태그를 검색하거나 새로 추가하세요"
+ * />
+ * ```
+ * {@end-tool}
+ *
+ * {@tool snippet}
+ * 데이터를 로딩 중인 콤보박스:
+ *
+ * ```tsx
+ * <Combobox
+ *   options={[]}
+ *   loading={true}
+ *   placeholder="데이터를 불러오는 중..."
+ * />
+ * ```
+ * {@end-tool}
+ *
+ * See also:
+ *
+ * - {@link Dropdown}, 기본 검색/선택 기능이 필요한 경우
+ * - {@link TagInput}, 여러 개의 값을 검색하여 추가해야 할 때
+ * - {@link TextInput}, 단순한 텍스트 입력만 필요한 경우
+ */
 export declare const Combobox: import('react').ForwardRefExoticComponent<ComboboxProps & import('react').RefAttributes<HTMLButtonElement>>;

package/dist/components/Dropdown/Dropdown.d.ts

@@ -22,4 +22,85 @@ export interface DropdownProps extends VariantProps<typeof dropdownTriggerVarian
     multiple?: boolean;
     maxHeight?: number;
 }
+/**
+ * 사용자가 목록에서 하나 또는 여러 개의 옵션을 선택할 수 있게 하는 컴포넌트입니다.
+ *
+ * {@link Dropdown}은 공간이 제한적인 UI에서 다양한 선택지를 효율적으로 제공합니다.
+ * 검색 기능, 다중 선택(Multiple), 선택 해제(Clearable) 등 복잡한 선택 시나리오를 지원합니다.
+ *
+ * ## When (언제 사용해야 하는가)
+ *
+ * **사용해야 하는 경우:**
+ * - **단일/다중 선택**: 5개 이상의 옵션 중 하나 또는 여러 개를 선택해야 할 때
+ * - **공간 절약**: 라디오 버튼이나 체크박스 그룹을 표시하기엔 화면 공간이 부족할 때
+ * - **동적 필터링**: 옵션이 너무 많아 검색을 통해 원하는 항목을 찾아야 할 때
+ *
+ * **사용하지 말아야 하는 경우:**
+ * - **옵션이 적은 경우(2-4개)**: 사용자가 모든 옵션을 한눈에 볼 수 있는 `RadioButton`이나 `Checkbox`가 더 좋습니다.
+ * - **설정 토글**: 단순히 On/Off를 전환하는 것이라면 `Switch`를 사용하세요.
+ * - **단순 내비게이션**: 클릭 시 다른 페이지로 이동만 하는 기능이라면 `Button`이나 `SideNavigation` 아이템이 더 적절합니다.
+ *
+ * ## Layout behavior
+ *
+ * - **Popover Menu**: 클릭 시 버튼 아래(또는 위)에 옵션 목록이 나타나며, 다른 요소들 위에 오버레이됩니다.
+ * - **Flexible Width**: 부모 컨테이너의 너비에 맞춰지거나, `className`을 통해 고정 너비를 가질 수 있습니다.
+ * - **Scrolling**: 옵션이 많아지면 `maxHeight` 설정에 따라 목록 내부에 스크롤이 발생합니다.
+ *
+ * ## Usage guidelines
+ *
+ * ### ✅ Do (권장 사항)
+ *
+ * - **논리적 정렬**: 옵션 목록은 가나다순, 사용 빈도순 등 사용자가 예측 가능한 순서로 정렬하세요.
+ * - **검색 기능 활용**: 옵션이 10개 이상인 경우 `searchable` 속성을 활성화하여 편의성을 높이세요.
+ * - **상태 표시**: `placeholder`를 통해 무엇을 선택해야 하는지 안내하고, 선택 후에는 선택된 항목을 명확히 표시하세요.
+ *
+ * ### 🚫 Don't (주의/금지 사항)
+ *
+ * - **너무 많은 텍스트**: 각 옵션의 레이블은 가급적 한 줄에 들어오도록 짧게 작성하세요.
+ * - **중첩 드롭다운 지양**: 드롭다운 안에서 또 다른 드롭다운이 열리는 복잡한 계층 구조는 피하는 것이 좋습니다.
+ *
+ * ## Accessibility
+ *
+ * - **Keyboard Interaction**: `Enter`나 `Space`로 열고, 화살표 키로 이동하며, `Esc`로 닫을 수 있습니다.
+ * - **Screen Reader**: `aria-expanded`, `aria-haspopup` 등의 속성을 통해 드롭다운의 상태와 역할을 스크린 리더에 전달합니다.
+ * - **Focus Management**: 드롭다운이 열리면 검색창이나 첫 번째 옵션으로 포커스가 이동합니다.
+ *
+ * ## Example
+ *
+ * {@tool snippet}
+ * 기본적인 단일 선택 드롭다운:
+ *
+ * ```tsx
+ * <Dropdown
+ *   options={[
+ *     { value: 'ko', label: '한국어' },
+ *     { value: 'en', label: '영어' },
+ *     { value: 'ja', label: '일본어' },
+ *   ]}
+ *   placeholder="언어를 선택하세요"
+ *   onValueChange={(val) => console.log(val)}
+ * />
+ * ```
+ * {@end-tool}
+ *
+ * {@tool snippet}
+ * 검색과 다중 선택이 가능한 드롭다운:
+ *
+ * ```tsx
+ * <Dropdown
+ *   options={largeOptionList}
+ *   multiple={true}
+ *   searchable={true}
+ *   clearable={true}
+ *   placeholder="태그 선택"
+ * />
+ * ```
+ * {@end-tool}
+ *
+ * See also:
+ *
+ * - {@link Select}, 기본적인 HTML select 스타일의 컴포넌트
+ * - {@link Combobox}, 입력과 선택이 결합된 컴포넌트
+ * - {@link Popover}, 더 자유로운 형태의 팝오버가 필요한 경우
+ */
 export declare const Dropdown: import('react').ForwardRefExoticComponent<DropdownProps & import('react').RefAttributes<HTMLButtonElement>>;