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이 이미 등록되어 있습니다.

// app/layout.tsx
import { GlobalAlertModal } from "@/features/layout/components/GlobalAlertModal";

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html>
      <body>
        <GlobalAlertModal /> {/* 전역 모달 등록 */}
        {children}
      </body>
    </html>
  );
}

3. 사용법 (Usage)

Hook 가져오기

import { useGlobalAlert } from "@/features/layout/hooks/use-global-alert";

const { alert } = useGlobalAlert();

기본 알림 (Alert)

사용자에게 단순히 정보를 전달하고 확인 버튼만 있는 알림입니다.

// 1. 성공 알림
alert.success("저장이 완료되었습니다.");

// 2. 에러 알림
alert.error("데이터 불러오기에 실패했습니다.");

// 3. 경고 알림
alert.warning("입력 값이 올바르지 않습니다.");

// 4. 정보 알림
alert.info("새로운 버전이 업데이트되었습니다.");

옵션을 추가하여 제목이나 버튼 텍스트를 변경할 수 있습니다.

alert.success("저장 완료", {
  title: "성공", // 기본값: 타입에 따른 제목 (예: "성공", "오류")
  confirmLabel: "닫기", // 기본값: "확인"
});

확인 대화상자 (Confirm)

사용자의 선택(확인/취소)을 요구하는 대화상자입니다.

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

interface AlertOptions {
  title?: ReactNode; // 모달 제목 (생략 시 타입에 맞는 기본 제목)
  confirmLabel?: string; // 확인 버튼 텍스트 (기본: "확인")
  cancelLabel?: string; // 취소 버튼 텍스트 (Confirm 모드에서 기본: "취소")
  onConfirm?: () => void; // 확인 버튼 클릭 시 실행될 콜백
  onCancel?: () => void; // 취소 버튼 클릭 시 실행될 콜백
  type?: AlertType; // 알림 타입 ("success" | "error" | "warning" | "info")
}

4.6 KiB Raw Blame History