# Global Alert System 사용 가이드 이 문서는 애플리케이션 전역에서 사용 가능한 `Global Alert System`의 설계 목적, 설치 방법, 그리고 사용법을 설명합니다. ## 1. 개요 (Overview) Global Alert System은 Zustand 상태 관리 라이브러리와 Shadcn/ui의 `AlertDialog` 컴포넌트를 결합하여 만든 전역 알림 시스템입니다. 복잡한 모달 로직을 매번 구현할 필요 없이, `useGlobalAlert` 훅 하나로 어디서든 일관된 UI의 알림 및 확인 창을 호출할 수 있습니다. ### 주요 특징 - **전역 상태 관리**: `useGlobalAlertStore`를 통해 모달의 상태를 중앙에서 관리합니다. - **간편한 Hook**: `useGlobalAlert` 훅을 통해 직관적인 API (`alert.success`, `alert.confirm` 등)를 제공합니다. - **다양한 타입 지원**: Success, Error, Warning, Info 등 상황에 맞는 스타일과 아이콘을 자동으로 적용합니다. - **비동기 지원**: 확인/취소 버튼 클릭 시 콜백 함수를 실행할 수 있습니다. --- ## 2. 설치 및 설정 (Setup) 이미 `app/layout.tsx`에 설정되어 있으므로, 개발자는 별도의 설정 없이 바로 사용할 수 있습니다. ### 파일 구조 ``` features/layout/ ├── components/ │ └── GlobalAlertModal.tsx # 실제 렌더링되는 모달 컴포넌트 ├── hooks/ │ └── use-global-alert.ts # 개발자가 사용하는 Custom Hook └── stores/ └── use-global-alert-store.ts # Zustand Store ``` ### Layout 통합 `app/layout.tsx`에 `GlobalAlertModal`이 이미 등록되어 있습니다. ```tsx // app/layout.tsx import { GlobalAlertModal } from "@/features/layout/components/GlobalAlertModal"; export default function RootLayout({ children, }: { children: React.ReactNode; }) { return ( {/* 전역 모달 등록 */} {children} ); } ``` --- ## 3. 사용법 (Usage) ### Hook 가져오기 ```tsx import { useGlobalAlert } from "@/features/layout/hooks/use-global-alert"; const { alert } = useGlobalAlert(); ``` ### 기본 알림 (Alert) 사용자에게 단순히 정보를 전달하고 확인 버튼만 있는 알림입니다. ```tsx // 1. 성공 알림 alert.success("저장이 완료되었습니다."); // 2. 에러 알림 alert.error("데이터 불러오기에 실패했습니다."); // 3. 경고 알림 alert.warning("입력 값이 올바르지 않습니다."); // 4. 정보 알림 alert.info("새로운 버전이 업데이트되었습니다."); ``` 옵션을 추가하여 제목이나 버튼 텍스트를 변경할 수 있습니다. ```tsx alert.success("저장 완료", { title: "성공", // 기본값: 타입에 따른 제목 (예: "성공", "오류") confirmLabel: "닫기", // 기본값: "확인" }); ``` ### 확인 대화상자 (Confirm) 사용자의 선택(확인/취소)을 요구하는 대화상자입니다. ```tsx alert.confirm("정말로 삭제하시겠습니까?", { type: "warning", // 기본값: warning (아이콘과 색상 변경됨) confirmLabel: "삭제", cancelLabel: "취소", onConfirm: () => { console.log("삭제 버튼 클릭됨"); // 여기에 삭제 로직 추가 }, onCancel: () => { console.log("취소 버튼 클릭됨"); }, }); ``` --- ## 4. API Reference ### `useGlobalAlert()` Hook은 `alert` 객체와 `close` 함수를 반환합니다. #### `alert` Methods | 메서드 | 설명 | 파라미터 | | --------- | ----------------------- | ---------------------------------------------- | | `success` | 성공 알림 표시 | `(message: ReactNode, options?: AlertOptions)` | | `error` | 오류 알림 표시 | `(message: ReactNode, options?: AlertOptions)` | | `warning` | 경고 알림 표시 | `(message: ReactNode, options?: AlertOptions)` | | `info` | 정보 알림 표시 | `(message: ReactNode, options?: AlertOptions)` | | `confirm` | 확인/취소 대화상자 표시 | `(message: ReactNode, options?: AlertOptions)` | #### `AlertOptions` Interface ```typescript interface AlertOptions { title?: ReactNode; // 모달 제목 (생략 시 타입에 맞는 기본 제목) confirmLabel?: string; // 확인 버튼 텍스트 (기본: "확인") cancelLabel?: string; // 취소 버튼 텍스트 (Confirm 모드에서 기본: "취소") onConfirm?: () => void; // 확인 버튼 클릭 시 실행될 콜백 onCancel?: () => void; // 취소 버튼 클릭 시 실행될 콜백 type?: AlertType; // 알림 타입 ("success" | "error" | "warning" | "info") } ```