cashdoc-cms-design-system 1.0.1 → 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/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/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/index.d.ts

@@ -7,9 +7,11 @@ 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';