cashdoc-cms-design-system 1.0.0 → 1.0.1

package/dist/components/LoadingCircle/LoadingCircle.d.ts

@@ -2,5 +2,75 @@ interface LoadingCircleProps {
     size?: "sm" | "md" | "lg";
     className?: string;
 }
+/**
+ * 시스템이 데이터를 처리 중이거나 다음 화면을 준비 중임을 시각적으로 나타내는 인디케이터입니다.
+ *
+ * {@link LoadingCircle}은 회전하는 원형 애니메이션을 통해 작업이 진행 중임을 알려
+ * 사용자가 시스템이 멈춘 것으로 오해하지 않도록 돕습니다.
+ *
+ * ## When (언제 사용해야 하는가)
+ *
+ * **사용해야 하는 경우:**
+ * - **데이터 로딩**: 페이지 진입 시 API로부터 데이터를 불러올 때
+ * - **작업 처리 중**: 버튼 클릭 후 서버 응답을 기다릴 때
+ * - **업로드/다운로드**: 파일 전송 상태를 표시할 때
+ * - **점진적 로딩**: 무한 스크롤 등 하단에 추가 데이터를 불러올 때
+ *
+ * **사용하지 말아야 하는 경우:**
+ * - **짧은 대기 시간**: 0.3초 미만의 아주 짧은 대기 시간에는 오히려 화면을 깜빡거리게 할 수 있으므로 생략하는 것이 좋습니다.
+ * - **진행률 표시**: 전체 작업 중 어느 정도 진행되었는지 정확한 수치가 중요한 경우 Progress Bar를 고려하세요.
+ *
+ * ## Layout behavior
+ *
+ * - **Centered**: 기본적으로 컨테이너의 중앙에 배치되도록 설정되어 있습니다.
+ * - **Fixed vs Inline**: 페이지 전체 로딩 시에는 고정된 위치(Overlay)에, 버튼 내부 등에는 인라인으로 배치할 수 있습니다.
+ *
+ * ## Usage guidelines
+ *
+ * ### ✅ Do (권장 사항)
+ *
+ * - **적절한 크기 선택**: 로딩이 일어나는 맥락(페이지 전체, 카드 내부, 버튼 내부 등)에 맞는 `size`를 선택하세요.
+ * - **텍스트와 병행**: 필요한 경우 '불러오는 중...'과 같은 텍스트를 함께 표시하여 의미를 더 명확히 하세요.
+ *
+ * ### 🚫 Don't (주의/금지 사항)
+ *
+ * - **남용 지양**: 한 화면에 너무 많은 로딩 서클이 동시에 나타나면 사용자에게 피로감을 줄 수 있습니다.
+ * - **무한 로딩**: 작업이 실패한 경우 로딩을 멈추고 적절한 에러 메시지를 표시해야 합니다.
+ *
+ * ## Accessibility
+ *
+ * - **Role**: `role="status"` 또는 `role="progressbar"`를 사용하여 현재 상태를 스크린 리더에 알립니다.
+ * - **Aria Label**: 시각적으로 확인이 어려운 사용자를 위해 `aria-label="로딩 중"`과 같은 정보를 제공하는 것이 좋습니다.
+ *
+ * ## Example
+ *
+ * {@tool snippet}
+ * 기본적인 로딩 서클 사용 예시:
+ *
+ * ```tsx
+ * {isLoading ? (
+ *   <LoadingCircle size="md" />
+ * ) : (
+ *   <DataContent />
+ * )}
+ * ```
+ * {@end-tool}
+ *
+ * {@tool snippet}
+ * 버튼 내부의 로딩 상태:
+ *
+ * ```tsx
+ * <Button disabled={isSubmitting}>
+ *   {isSubmitting && <LoadingCircle size="sm" className="mr-2" />}
+ *   제출하기
+ * </Button>
+ * ```
+ * {@end-tool}
+ *
+ * See also:
+ *
+ * - {@link Button}, 버튼 자체의 로딩 상태를 지원함
+ * - {@link Modal}, 로딩 상태를 포함할 수 있는 오버레이
+ */
 export declare function LoadingCircle({ size, className }: LoadingCircleProps): import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/components/Modal/ConfirmModal.d.ts

@@ -9,4 +9,28 @@ export interface ConfirmModalProps {
     onConfirm?: () => void;
     className?: string;
 }
+/**
+ * 사용자에게 특정 작업에 대한 최종 확인을 받기 위한 단순화된 모달 컴포넌트입니다.
+ *
+ * {@link ConfirmModal}은 {@link Modal}을 기반으로 구성되었으며, 상징적인 체크 아이콘과
+ * 하나의 '확인' 버튼만을 제공하여 사용자의 빠른 의사결정을 돕습니다.
+ * 주로 성공적인 처리 알림이나 단순한 동의가 필요할 때 사용됩니다.
+ *
+ * ## When (언제 사용해야 하는가)
+ *
+ * **사용해야 하는 경우:**
+ * - **결과 확인**: 설정 변경, 데이터 저장 등 작업이 정상적으로 완료되었음을 알릴 때
+ * - **단순 안내**: 사용자에게 중요한 안내 사항을 전달하고 확인을 받아야 할 때
+ *
+ * **사용하지 말아야 하는 경우:**
+ * - **중요한 결정/취소 필요**: '예/아니오'와 같이 선택지가 필요한 경우 일반 `Modal`이나 `DeleteModal`을 사용하세요.
+ * - **데이터 입력**: 폼 입력이 필요한 경우 일반 `Modal`을 사용하세요.
+ *
+ * ## Usage guidelines
+ *
+ * ### ✅ Do (권장 사항)
+ *
+ * - **간결한 메시지**: 메시지는 가급적 2-3줄 이내로 짧고 명확하게 작성하세요.
+ * - **적절한 타이틀**: "저장 완료", "안내" 등 문맥에 맞는 타이틀을 사용하세요.
+ */
 export declare const ConfirmModal: React.ForwardRefExoticComponent<ConfirmModalProps & React.RefAttributes<HTMLDivElement>>;

package/dist/components/Modal/DeleteModal.d.ts

@@ -11,4 +11,23 @@ export interface DeleteModalProps {
     onCancel?: () => void;
     className?: string;
 }
+/**
+ * 데이터를 삭제하거나 영구적인 작업을 수행하기 전, 사용자의 최종 승인을 받기 위한 경고 모달입니다.
+ *
+ * {@link DeleteModal}은 파괴적인(Destructive) 액션을 강조하기 위해 빨간색 경고 아이콘과
+ * 눈에 띄는 삭제 버튼을 제공합니다. 사용자가 실수로 데이터를 삭제하는 것을 방지하는 안전장치 역할을 합니다.
+ *
+ * ## When (언제 사용해야 하는가)
+ *
+ * **사용해야 하는 경우:**
+ * - **영구적 데이터 삭제**: 게시글, 사용자 계정, 설정값 등을 삭제할 때
+ * - **되돌릴 수 없는 작업**: 초기화, 데이터 덮어쓰기 등 주의가 필요한 작업을 수행할 때
+ *
+ * ## Usage guidelines
+ *
+ * ### ✅ Do (권장 사항)
+ *
+ * - **구체적인 정보 포함**: 단순히 "삭제하시겠습니까?" 보다는 "사용자 '홍길동'의 정보를 삭제하시겠습니까?"와 같이 구체적인 대상을 명시하는 것이 좋습니다.
+ * - **위험성 강조**: 해당 작업이 되돌릴 수 없음을 메시지에 포함하세요.
+ */
 export declare const DeleteModal: React.ForwardRefExoticComponent<DeleteModalProps & React.RefAttributes<HTMLDivElement>>;

package/dist/components/Modal/ErrorModal.d.ts

@@ -9,4 +9,24 @@ export interface ErrorModalProps {
     onConfirm?: () => void;
     className?: string;
 }
+/**
+ * 시스템 오류나 사용자의 잘못된 조작으로 인해 작업이 실패했음을 알리는 모달입니다.
+ *
+ * {@link ErrorModal}은 빨간색 X 아이콘을 통해 부정적인 결과임을 즉각적으로 전달하며,
+ * 사용자가 문제를 인지하고 다음 행동을 취할 수 있도록 돕습니다.
+ *
+ * ## When (언제 사용해야 하는가)
+ *
+ * **사용해야 하는 경우:**
+ * - **API 통신 실패**: 서버 오류나 네트워크 문제로 요청을 처리할 수 없을 때
+ * - **유효성 검사 실패**: 입력한 정보에 중대한 결함이 있어 처리가 중단되었을 때
+ * - **권한 부족**: 특정 기능을 사용할 권한이 없음을 알릴 때
+ *
+ * ## Usage guidelines
+ *
+ * ### ✅ Do (권장 사항)
+ *
+ * - **구체적인 원인 안내**: 단순히 "오류가 발생했습니다" 보다는 "이미 존재하는 이메일입니다"와 같이 해결 가능한 정보를 제공하세요.
+ * - **해결 방법 제시**: 가능하다면 "나중에 다시 시도해 주세요" 또는 "고객센터로 문의해 주세요"와 같은 가이드를 포함하세요.
+ */
 export declare const ErrorModal: React.ForwardRefExoticComponent<ErrorModalProps & React.RefAttributes<HTMLDivElement>>;

package/dist/components/Modal/Modal.d.ts

@@ -11,4 +11,175 @@ export interface ModalProps {
     showCloseButton?: boolean;
     size?: "sm" | "md" | "lg";
 }
+/**
+ * 사용자에게 중요한 정보를 표시하거나 입력을 요구하는 오버레이 대화상자입니다.
+ *
+ * {@link Modal}은 사용자의 주의를 집중시켜야 하는 상황에서 사용됩니다.
+ * 모달이 열리면 배경이 어두워지며, 사용자는 모달과 상호작용하거나 닫기 전까지
+ * 페이지의 다른 부분과 상호작용할 수 없습니다.
+ *
+ * Radix UI의 Dialog 컴포넌트를 기반으로 구현되어 접근성과 키보드 내비게이션이
+ * 자동으로 처리됩니다.
+ *
+ * ## When (언제 사용해야 하는가)
+ *
+ * **사용해야 하는 경우:**
+ * - **중요한 의사 결정**: 삭제, 저장, 제출 등 되돌릴 수 없는 작업 확인
+ * - **필수 정보 입력**: 다음 단계로 진행하기 전 반드시 입력해야 하는 정보 수집
+ * - **중요 알림**: 사용자가 반드시 확인해야 하는 에러, 경고, 성공 메시지
+ * - **간단한 폼**: 페이지 전환 없이 빠르게 정보를 입력받아야 할 때
+ *
+ * **사용하지 말아야 하는 경우:**
+ * - **긴급하지 않은 알림**: Toast 컴포넌트를 사용하세요
+ * - **복잡한 다단계 폼**: 별도 페이지로 이동하세요
+ * - **많은 정보 표시**: 페이지 내 섹션으로 구현하세요
+ * - **비필수 부가 정보**: Popover나 Tooltip을 사용하세요
+ *
+ * ## Layout behavior
+ *
+ * 모달은 항상 화면 중앙에 고정되며, 배경 오버레이는 전체 화면을 덮습니다.
+ * 크기는 `size` prop에 따라 결정됩니다:
+ * - `sm`: 최대 너비 24rem (384px) - 간단한 확인 대화상자
+ * - `md`: 최대 너비 28rem (448px) - 기본값, 일반적인 폼이나 메시지
+ * - `lg`: 최대 너비 32rem (512px) - 많은 내용이나 복잡한 폼
+ *
+ * 모달의 높이는 콘텐츠에 따라 자동으로 조절되며, 화면을 넘어가면 스크롤이 발생합니다.
+ *
+ * ## Usage guidelines
+ *
+ * ### ✅ Do (권장 사항)
+ *
+ * - **명확한 제목 사용**: 모달의 목적을 한눈에 알 수 있는 제목을 제공하세요
+ *   ```tsx
+ *   <Modal title="항목 삭제">...</Modal>  // Good
+ *   <Modal title="확인">...</Modal>        // Bad - 너무 모호함
+ *   ```
+ *
+ * - **행동 지향적 버튼**: 버튼 레이블은 수행할 동작을 명확히 표현하세요
+ *   ```tsx
+ *   <Button>삭제하기</Button>  // Good
+ *   <Button>확인</Button>      // Bad - 무엇을 확인하는지 불명확
+ *   ```
+ *
+ * - **적절한 크기 선택**: 콘텐츠 양에 맞는 size를 선택하세요
+ * - **명확한 닫기 방법**: X 버튼, 취소 버튼, 배경 클릭 중 최소 하나는 제공하세요
+ * - **중요도에 따른 변형**: ConfirmModal, SuccessModal, ErrorModal 등 사용
+ *
+ * ### 🚫 Don't (주의/금지 사항)
+ *
+ * - **모달 위에 모달을 띄우지 마세요** - UX가 복잡해지고 혼란스러워집니다
+ * - **긴 스크롤이 필요한 콘텐츠는 피하세요** - 별도 페이지로 이동하는 것이 좋습니다
+ * - **자동으로 모달을 열지 마세요** - 사용자의 명시적 동작(클릭 등) 후에만 열어야 합니다
+ * - **모달 없이도 작업 가능한 경우** - 불필요하게 모달을 사용하지 마세요
+ * - **모바일에서 큰 모달(lg) 사용 지양** - 화면을 거의 다 차지하므로 페이지 이동 권장
+ *
+ * ## Accessibility
+ *
+ * 이 컴포넌트는 WAI-ARIA Dialog 패턴을 따릅니다:
+ *
+ * - **키보드 내비게이션**:
+ *   - `Esc`: 모달 닫기
+ *   - `Tab`: 모달 내부 포커스 순환 (모달 외부로 나가지 않음)
+ *   - 모달이 열리면 첫 번째 포커스 가능한 요소로 자동 포커스
+ *
+ * - **스크린 리더**:
+ *   - `role="dialog"`: 대화상자임을 인식
+ *   - `aria-labelledby`: title이 모달의 레이블로 연결됨
+ *   - `aria-describedby`: children 콘텐츠가 설명으로 연결됨
+ *
+ * - **포커스 트랩**: 모달이 열려있는 동안 포커스가 모달 내부에서만 순환합니다
+ * - **배경 스크롤 방지**: 모달이 열리면 body 스크롤이 자동으로 비활성화됩니다
+ *
+ * ## Example
+ *
+ * {@tool snippet}
+ * 기본적인 확인 모달 예시:
+ *
+ * ```tsx
+ * function DeleteConfirmDialog() {
+ *   const [open, setOpen] = useState(false);
+ *
+ *   return (
+ *     <>
+ *       <Button onClick={() => setOpen(true)}>삭제</Button>
+ *       <Modal
+ *         open={open}
+ *         onOpenChange={setOpen}
+ *         title="항목 삭제"
+ *         footer={
+ *           <div className="flex gap-2">
+ *             <Button onClick={() => setOpen(false)} variant="outline">
+ *               취소
+ *             </Button>
+ *             <Button onClick={handleDelete} variant="destructive">
+ *               삭제하기
+ *             </Button>
+ *           </div>
+ *         }
+ *       >
+ *         이 항목을 삭제하시겠습니까? 이 작업은 되돌릴 수 없습니다.
+ *       </Modal>
+ *     </>
+ *   );
+ * }
+ * ```
+ * {@end-tool}
+ *
+ * {@tool snippet}
+ * 성공 아이콘이 포함된 모달 예시:
+ *
+ * ```tsx
+ * <Modal
+ *   open={open}
+ *   onOpenChange={setOpen}
+ *   icon={<CheckCircle className="w-12 h-12 text-green-500" />}
+ *   title="저장 완료"
+ *   footer={
+ *     <Button onClick={() => setOpen(false)} className="w-full">
+ *       확인
+ *     </Button>
+ *   }
+ * >
+ *   데이터가 성공적으로 저장되었습니다.
+ * </Modal>
+ * ```
+ * {@end-tool}
+ *
+ * {@tool snippet}
+ * 큰 크기의 폼 모달 예시:
+ *
+ * ```tsx
+ * <Modal
+ *   open={open}
+ *   onOpenChange={setOpen}
+ *   title="새 사용자 추가"
+ *   size="lg"
+ *   footer={
+ *     <div className="flex justify-end gap-2">
+ *       <Button variant="outline" onClick={() => setOpen(false)}>
+ *         취소
+ *       </Button>
+ *       <Button onClick={handleSubmit}>저장</Button>
+ *     </div>
+ *   }
+ * >
+ *   <form className="space-y-4">
+ *     <TextInput label="이름" required />
+ *     <TextInput label="이메일" type="email" required />
+ *     <TextInput label="전화번호" />
+ *   </form>
+ * </Modal>
+ * ```
+ * {@end-tool}
+ *
+ * See also:
+ *
+ * - {@link ConfirmModal}, 간단한 확인 모달을 위한 사전 구성된 변형
+ * - {@link SuccessModal}, 성공 메시지를 표시하는 모달
+ * - {@link ErrorModal}, 에러 메시지를 표시하는 모달
+ * - {@link WarningModal}, 경고 메시지를 표시하는 모달
+ * - {@link DeleteModal}, 삭제 확인을 위한 모달
+ * - {@link Toast}, 긴급하지 않은 알림을 위한 컴포넌트
+ * - {@link Popover}, 비필수 부가 정보를 표시하는 컴포넌트
+ */
 export declare const Modal: React.ForwardRefExoticComponent<ModalProps & React.RefAttributes<HTMLDivElement>>;

package/dist/components/Modal/SuccessModal.d.ts

@@ -9,4 +9,23 @@ export interface SuccessModalProps {
     onConfirm?: () => void;
     className?: string;
 }
+/**
+ * 요청한 작업이 성공적으로 완료되었음을 축하하거나 알리는 모달입니다.
+ *
+ * {@link SuccessModal}은 초록색 체크 아이콘을 통해 긍정적인 결과를 전달합니다.
+ * 단순한 Toast 알림보다 더 강조된 확인이 필요할 때 사용됩니다.
+ *
+ * ## When (언제 사용해야 하는가)
+ *
+ * **사용해야 하는 경우:**
+ * - **중요 작업 완료**: 회원가입 완료, 대규모 데이터 처리 완료 등
+ * - **영구적 저장 완료**: 중요한 설정이나 게시글이 성공적으로 서버에 저장되었을 때
+ *
+ * ## Usage guidelines
+ *
+ * ### ✅ Do (권장 사항)
+ *
+ * - **긍정적인 피드백**: "처리가 완료되었습니다" 보다는 "성공적으로 저장되었습니다"와 같이 명확한 피드백을 제공하세요.
+ * - **후속 조치 안내**: 필요한 경우 다음 단계로 무엇을 해야 하는지(예: 리스트로 이동 등) 메시지에 포함하세요.
+ */
 export declare const SuccessModal: React.ForwardRefExoticComponent<SuccessModalProps & React.RefAttributes<HTMLDivElement>>;

package/dist/components/Modal/WarningModal.d.ts

@@ -11,4 +11,25 @@ export interface WarningModalProps {
     onCancel?: () => void;
     className?: string;
 }
+/**
+ * 잠재적인 문제를 경고하거나 주의가 필요한 작업을 수행하기 전 사용자의 동의를 구하는 모달입니다.
+ *
+ * {@link WarningModal}은 주황색 경고 아이콘을 통해 주의를 환기시킵니다.
+ * 완전한 파괴적 액션(삭제)은 아니지만, 데이터 변경이나 시스템 설정 변경 등
+ * 신중함이 필요한 상황에서 사용됩니다.
+ *
+ * ## When (언제 사용해야 하는가)
+ *
+ * **사용해야 하는 경우:**
+ * - **데이터 변경**: 기존 정보를 대량으로 수정하거나 업데이트할 때
+ * - **민감한 설정 변경**: 시스템 동작에 영향을 줄 수 있는 설정을 변경할 때
+ * - **동작 확인**: 예기치 않은 부작용이 발생할 수 있는 기능을 실행할 때
+ *
+ * ## Usage guidelines
+ *
+ * ### ✅ Do (권장 사항)
+ *
+ * - **위험성 명시**: 이 작업을 실행했을 때 어떤 결과가 초래될 수 있는지 명확히 설명하세요.
+ * - **취소 옵션 제공**: 사용자가 마음을 바꿀 수 있도록 명확한 취소 버튼을 함께 배치하세요.
+ */
 export declare const WarningModal: React.ForwardRefExoticComponent<WarningModalProps & React.RefAttributes<HTMLDivElement>>;

package/dist/components/Popover/Popover.d.ts

@@ -1,4 +1,74 @@
 import * as PopoverPrimitive from "@radix-ui/react-popover";
+/**
+ * 특정 요소 근처에 부가적인 정보나 컨트롤을 표시하는 플로팅 컴포넌트입니다.
+ *
+ * {@link Popover}는 사용자가 버튼이나 아이콘을 클릭했을 때 나타나며,
+ * 기존 화면의 맥락을 유지하면서 추가적인 작업(메뉴 선택, 상세 정보 확인 등)을 수행할 수 있게 합니다.
+ *
+ * Radix UI의 Popover 컴포넌트를 기반으로 구현되어 포커스 트랩, 키보드 내비게이션 등이
+ * 자동으로 처리됩니다.
+ *
+ * ## When (언제 사용해야 하는가)
+ *
+ * **사용해야 하는 경우:**
+ * - **맥락 기반 메뉴**: '더 보기' 버튼 클릭 시 나타나는 관리 기능(수정, 삭제 등)
+ * - **상세 정보 표시**: 아이콘 클릭 시 해당 항목에 대한 간단한 설명이나 데이터를 보여줄 때
+ * - **간단한 설정**: 필터 옵션이나 정렬 기준을 선택할 때
+ *
+ * **사용하지 말아야 하는 경우:**
+ * - **중요한 의사 결정**: 사용자의 주의를 완전히 집중시켜야 하는 작업은 `Modal`을 사용하세요.
+ * - **단순 힌트**: 마우스 호버 시에만 짧게 보여주는 정보는 Tooltip을 사용하세요.
+ * - **입력 폼**: 복잡한 입력이 필요한 경우 모달이나 별도 페이지가 더 적합할 수 있습니다.
+ *
+ * ## Layout behavior
+ *
+ * - **Anchor Positioning**: 트리거(버튼 등)를 기준으로 상하좌우 적절한 위치에 자동으로 배치됩니다.
+ * - **Overlay**: 다른 UI 요소들 위에 겹쳐서 나타나며, 배경(Overlay)을 생성하지 않아 뒤쪽 화면을 볼 수 있습니다.
+ * - **Size**: 콘텐츠의 양에 따라 크기가 결정되지만, `min-w-[200px]`의 최소 너비를 가집니다.
+ *
+ * ## Usage guidelines
+ *
+ * ### ✅ Do (권장 사항)
+ *
+ * - **명확한 트리거**: 사용자가 무엇을 클릭하면 팝오버가 열릴지 명확히 인지할 수 있는 버튼이나 아이콘을 사용하세요.
+ * - **적절한 배치**: `align` 속성을 조절하여 팝오버가 화면 밖으로 나가지 않도록 관리하세요. (기본값: 'end')
+ *
+ * ### 🚫 Don't (주의/금지 사항)
+ *
+ * - **너무 많은 정보**: 팝오버는 빠르고 간단한 상호작용을 위한 것입니다. 너무 많은 내용을 담지 마세요.
+ * - **비정상적인 닫기**: 팝오버 외부를 클릭하거나 `Esc`를 누르면 자연스럽게 닫히도록 기본 동작을 유지하세요.
+ *
+ * ## Accessibility
+ *
+ * - **Keyboard Interaction**: `Space`나 `Enter`로 열고, `Esc`로 닫으며, 팝오버 내부에서 `Tab` 키로 내비게이션이 가능합니다.
+ * - **Aria Attributes**: `aria-expanded`, `aria-controls` 등의 속성이 자동으로 부여됩니다.
+ *
+ * ## Example
+ *
+ * {@tool snippet}
+ * 버튼 클릭 시 상세 정보를 보여주는 팝오버:
+ *
+ * ```tsx
+ * <Popover>
+ *   <PopoverTrigger asChild>
+ *     <Button variant="ghost">상세 정보</Button>
+ *   </PopoverTrigger>
+ *   <PopoverContent>
+ *     <div className="p-4">
+ *       <h4 className="font-bold">계정 상태</h4>
+ *       <p className="text-sm">현재 활성화된 계정입니다.</p>
+ *     </div>
+ *   </PopoverContent>
+ * </Popover>
+ * ```
+ * {@end-tool}
+ *
+ * See also:
+ *
+ * - {@link Modal}, 더 중요하거나 복잡한 상호작용이 필요한 경우
+ * - {@link Dropdown}, 정해진 리스트에서 값을 선택하는 것이 주 목적인 경우
+ * - {@link PopoverMenuItem}, 팝오버 내부의 메뉴 항목을 구성할 때
+ */
 declare const Popover: import('react').FC<PopoverPrimitive.PopoverProps>;
 declare const PopoverTrigger: import('react').ForwardRefExoticComponent<PopoverPrimitive.PopoverTriggerProps & import('react').RefAttributes<HTMLButtonElement>>;
 declare const PopoverContent: import('react').ForwardRefExoticComponent<Omit<PopoverPrimitive.PopoverContentProps & import('react').RefAttributes<HTMLDivElement>, "ref"> & import('react').RefAttributes<HTMLDivElement>>;

package/dist/components/Popover/PopoverMenuItem.d.ts

@@ -7,5 +7,30 @@ declare const popoverMenuItemVariants: (props?: ({
 export interface PopoverMenuItemProps extends ButtonHTMLAttributes<HTMLButtonElement>, VariantProps<typeof popoverMenuItemVariants> {
     icon?: React.ReactNode;
 }
+/**
+ * Popover 내부에 배치되는 개별 액션 항목 컴포넌트입니다.
+ *
+ * {@link PopoverMenuItem}은 아이콘과 텍스트가 결합된 형태의 메뉴 버튼으로,
+ * 일관된 패딩, 폰트, 호버 효과를 제공합니다.
+ *
+ * ## Example
+ *
+ * ```tsx
+ * <PopoverContent>
+ *   <div className="flex flex-col gap-1">
+ *     <PopoverMenuItem icon={<EditIcon />} onClick={handleEdit}>
+ *       수정하기
+ *     </PopoverMenuItem>
+ *     <PopoverMenuItem
+ *       variant="destructive"
+ *       icon={<TrashIcon />}
+ *       onClick={handleDelete}
+ *     >
+ *       삭제하기
+ *     </PopoverMenuItem>
+ *   </div>
+ * </PopoverContent>
+ * ```
+ */
 declare const PopoverMenuItem: import('react').ForwardRefExoticComponent<PopoverMenuItemProps & import('react').RefAttributes<HTMLButtonElement>>;
 export { PopoverMenuItem, popoverMenuItemVariants };

package/dist/components/RadioButton/RadioButton.d.ts

@@ -2,6 +2,77 @@ import { default as React } from 'react';
 import { VariantProps } from 'class-variance-authority';
 
 import * as RadioGroupPrimitives from "@radix-ui/react-radio-group";
+/**
+ * 상호 배타적인 옵션 목록 중 단 하나만을 선택해야 할 때 사용하는 컴포넌트입니다.
+ *
+ * {@link RadioGroup}은 여러 개의 {@link RadioGroupItem}을 포함하는 컨테이너이며,
+ * 한 번에 하나의 아이템만 선택될 수 있도록 상태를 관리합니다.
+ *
+ * Radix UI의 Radio Group 컴포넌트를 기반으로 구현되어 방향키를 이용한 내비게이션 등
+ * 표준 라디오 그룹 동작을 지원합니다.
+ *
+ * ## When (언제 사용해야 하는가)
+ *
+ * **사용해야 하는 경우:**
+ * - **단일 선택**: 성별 선택, 배송 방법 선택 등 여러 옵션 중 하나만 골라야 할 때
+ * - **옵션 노출**: 모든 선택지가 사용자에게 한눈에 보여야 할 때 (옵션이 5개 이하인 경우 권장)
+ *
+ * **사용하지 말아야 하는 경우:**
+ * - **다중 선택**: 여러 개를 동시에 선택할 수 있어야 하는 경우 `Checkbox`를 사용하세요.
+ * - **옵션이 많은 경우**: 선택지가 5-6개를 넘어간다면 화면 공간을 위해 `Dropdown`을 사용하는 것이 좋습니다.
+ * - **독립적 On/Off**: 단순히 하나의 항목을 켜고 끄는 것이라면 `Checkbox`나 `Switch`가 더 적절합니다.
+ *
+ * ## Layout behavior
+ *
+ * - **asChild**: `asChild` 속성을 사용하면 기본 렌더링 요소 대신 자식 요소를 렌더링하고 속성을 병합합니다.
+ *   커스텀 컴포넌트나 다른 라이브러리와 연동할 때 유용합니다.
+ *
+ * ## Accessibility
+ *
+ * - **Keyboard Navigation**: `Tab` 키로 그룹에 진입한 후, 화살표 키(`Up`, `Down`, `Left`, `Right`)를 사용하여 옵션 간 이동 및 선택이 가능합니다.
+ * - **Roles**: `role="radiogroup"` 및 `role="radio"` 속성이 자동으로 부여됩니다.
+ *
+ * ## Example
+ *
+ * {@tool snippet}
+ * 기본적인 라디오 그룹 사용 예시:
+ *
+ * ```tsx
+ * <RadioGroup defaultValue="apple" onValueChange={(val) => console.log(val)}>
+ *   <div className="flex items-center gap-2">
+ *     <RadioGroupItem value="apple" id="apple" />
+ *     <label htmlFor="apple">사과</label>
+ *   </div>
+ *   <div className="flex items-center gap-2">
+ *     <RadioGroupItem value="banana" id="banana" />
+ *     <label htmlFor="banana">바나나</label>
+ *   </div>
+ * </RadioGroup>
+ * ```
+ * {@end-tool}
+ *
+ * {@tool snippet}
+ * `asChild`를 사용한 커스텀 렌더링 예시:
+ *
+ * ```tsx
+ * <RadioGroup asChild>
+ *   <section className="my-custom-group">
+ *     <RadioGroupItem asChild value="custom">
+ *       <button type="button" className="custom-radio-trigger">
+ *         커스텀 라디오
+ *       </button>
+ *     </RadioGroupItem>
+ *   </section>
+ * </RadioGroup>
+ * ```
+ * {@end-tool}
+ *
+ * See also:
+ *
+ * - {@link Checkbox}, 다중 선택이 필요한 경우
+ * - {@link Dropdown}, 옵션이 많아 리스트로 숨겨야 하는 경우
+ * - {@link Switch}, 단순 활성화/비활성화를 토글할 때
+ */
 declare const RadioGroup: React.ForwardRefExoticComponent<Omit<RadioGroupPrimitives.RadioGroupProps & React.RefAttributes<HTMLDivElement>, "ref"> & React.RefAttributes<HTMLDivElement>>;
 declare const radioGroupItemVariants: (props?: ({
     variant?: "default" | "black" | "green" | "blue" | "red" | null | undefined;

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

@@ -18,4 +18,81 @@ export interface SideNavigationProps {
     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}, 클릭 시 일시적으로 나타나는 추가 메뉴가 필요한 경우
+ */
 export declare const SideNavigation: React.ForwardRefExoticComponent<SideNavigationProps & React.RefAttributes<HTMLDivElement>>;