Project Information

Alert

Alert와 useAlert usage를 기준으로 전역 호출, props, store stack 구조를 정리한 가이드 페이지입니다.

Alert

Alert는 전역 store와 PopupHost를 통해 어느 페이지에서든 호출할 수 있는 고정형 확인 팝업입니다. 이 페이지에서는 실제로 쓰는 props와 useAlert 호출 흐름을 기준으로 정리합니다.

Prop

title | description | icon | confirmText | shouldCloseOnConfirm | onConfirm | className

- Alert는 아이콘, 제목, 설명, 확인 버튼 텍스트만 바꿔서 쓰는 고정형 팝업입니다.
- `title`은 선택이고, `description`은 실제 안내 문구를 표현하는 기본 텍스트입니다.
- `icon`은 기본 경고 아이콘 대신 다른 시각 요소로 바꿀 수 있고, `className`은 Alert 루트 스타일을 확장할 때 사용합니다.
- `shouldCloseOnConfirm`의 기본값은 `true`이고, `false`로 두면 확인 버튼 클릭 이후에도 현재 Alert를 유지한 채 다른 popup을 이어서 띄울 수 있습니다.
- `onConfirm`을 전달하면 확인 버튼 클릭 시 원하는 후처리를 실행하고, 기본적으로는 그 뒤 Alert가 닫힙니다.

Prop

icon

ReactNode | null

- `icon`에는 ReactNode를 그대로 전달할 수 있어서 Alert 목적에 맞는 시각 표현을 얹을 수 있습니다.
- 경고, 삭제 확인, 일정 안내, 서비스 안내처럼 같은 Alert 구조를 유지한 채 아이콘만 바꿔서 사용할 수 있습니다.

Prop

Alert 고정 동작

hasCloseButton=false | shouldCloseOnBackdrop=false | shouldCloseOnEscape=false | shouldCloseOnConfirm=true

- Alert는 `PopupBase`를 그대로 노출하는 페이지가 아니라, 고정된 규칙을 가진 Alert 패턴만 다룹니다.
- 닫기 버튼은 없고, backdrop 클릭이나 `Escape`로 닫히지 않습니다.
- 현재 구조에서는 확인 버튼을 통한 닫기 흐름을 기본 동작으로 사용하고, 확인 클릭 후 자동 닫힘 기본값은 `true`입니다.

Alert defaults

`hasCloseButton = false`
`shouldCloseOnBackdrop = false`
`shouldCloseOnEscape = false`
`shouldCloseOnConfirm = true`
`size = small`

Prop

id

string | undefined

- `id`를 넘기지 않으면 내부에서 고유 id를 자동 생성합니다.
- `open()`은 생성된 id를 반환하므로, 필요하면 `close(id)`로 특정 Alert만 닫을 수 있습니다.
- 같은 `id`로 다시 열면 duplicate로 간주되어 에러가 발생합니다.

Alert id rules

`id` 미지정: 자동 생성
`open()` 반환값: 생성된 id
duplicate `id`: store에서 `throw`

Prop

useAlert()

{ open: (options) => string; close: (id?: string) => void; closeAll: () => void; alerts: Array<{ id: string; type: "alert"; status: "open" | "closing" }>; }

- `PopupHost`를 앱 루트에 한 번만 두고, 어느 페이지에서든 `useAlert()`로 Alert를 띄우고 닫는 구조입니다.
- `open()`은 생성된 alert id를 반환하고, `close(id?)`는 특정 id 또는 가장 마지막 Alert를 닫습니다.
- 이 예제처럼 여러 개를 연 뒤에는 `close(id?)`로 마지막 Alert 또는 원하는 id를 닫고, `closeAll()`은 현재 열려 있는 Alert들을 한 번에 닫습니다.

Prop

usePopupStack()

Array<{ id: string; type: "alert" | "confirm"; status: "open" | "closing" }>

전역에서 현재 어떤 popup이 열려 있는지, 닫히는 중인지 Zustand selector로 바로 조회할 수 있습니다.

Active popup stack

열린 팝업이 없습니다.

Props Table

Alert options 한눈에 보기

useAlert().open()에 넘기는 AlertPopupOptions와 내부 Alert 고정 동작을 함께 정리했습니다.

Prop	Type	Default	Required	Description
`title`	`React.ReactNode`	`undefined`	Optional	선택적 제목입니다. 없으면 description 중심의 단순 안내형 Alert로 사용할 수 있습니다.
`description`	`React.ReactNode`	`undefined`	Optional	실제 안내 문구 본문입니다.
`icon`	`React.ReactNode \| null`	`<AttentionIcon />`	Optional	기본 경고 아이콘 대신 다른 시각 요소로 바꾸거나, null로 숨길 수 있습니다.
`confirmText`	`React.ReactNode`	`"확인"`	Optional	하단 단일 확인 버튼 텍스트입니다.
`onConfirm`	`() => void`	`undefined`	Optional	확인 버튼 클릭 시 실행되는 후처리입니다. 기본적으로 그 뒤 Alert가 닫힙니다.
`shouldCloseOnConfirm`	`boolean`	`true`	Optional	확인 클릭 뒤 현재 Alert를 자동으로 닫을지 제어합니다. false면 후속 popup을 이어서 띄우는 흐름을 만들 수 있습니다.
`className`	`string`	`undefined`	Optional	Alert 루트 스타일 확장용 클래스입니다.
`id`	`string`	`auto generated id`	Optional	특정 Alert를 직접 추적하거나 close(id) 대상으로 삼고 싶을 때 사용합니다.

페이지에서 직접 다루는 API는 AlertPopupOptions입니다. 내부 AlertProps의 open, onExited, isTopmost는 PopupHost가 주입하는 runtime 값이라 보통 직접 넘기지 않습니다.

Props Table

useAlert API 한눈에 보기

전역 Alert stack 제어에 사용하는 hook API를 표로 정리했습니다.

Prop	Type	Default	Required	Description
`open`	`(options: AlertPopupOptions) => string`	-	Required	새 Alert를 전역 store stack에 추가하고 생성된 id를 반환합니다.
`close`	`(id?: string) => void`	-	Required	id를 주면 해당 Alert를 닫고, 생략하면 현재 Alert stack의 마지막 항목을 닫습니다.
`closeAll`	`() => void`	-	Required	현재 열린 Alert 타입 인스턴스만 모두 closing 상태로 전환합니다.
`alerts`	`Array<{ id: string; type: "alert"; status: "open" \| "closing" }>`	-	Required	전역 popup stack 중 Alert 항목만 필터링한 snapshot 배열입니다.

useAlert()는 route와 무관하게 Alert를 띄우기 위한 전역 facade입니다. 실제 렌더링은 앱 루트의 PopupHost가 담당합니다.