147 lines
4.6 KiB
Markdown
147 lines
4.6 KiB
Markdown
|
# 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 (
|
||
|
|
<html>
|
||
|
|
<body>
|
||
|
|
<GlobalAlertModal /> {/* 전역 모달 등록 */}
|
||
|
|
{children}
|
||
|
|
</body>
|
||
|
|
</html>
|
||
|
|
);
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 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")
|
||
|
|
}
|
||
|
|
```
|