Project Information

Confirm

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

Confirm

Confirm은 취소와 확인 두 선택지를 제공하는 고정형 확인 popup입니다. 이 페이지에서는 실제로 쓰는 props와 useConfirm 호출 흐름을 기준으로 정리합니다.

Prop

title | description | icon | cancelText | confirmText | shouldCloseOnCancel | shouldCloseOnConfirm | onCancel | onConfirm | className

- Confirm은 Alert와 같은 고정형 popup 구조를 유지하면서, 취소와 확인 두 액션을 함께 제공하는 패턴입니다.
- `title`, `description`, `icon`은 Alert와 동일한 의미로 사용하고, 버튼 텍스트와 cancel/confirm callback만 확장됩니다.
- `shouldCloseOnCancel`, `shouldCloseOnConfirm`의 기본값은 모두 `true`이고, `false`로 두면 버튼 클릭 이후에도 현재 Confirm을 유지한 채 후속 popup을 열 수 있습니다.
- `onCancel`, `onConfirm`은 각 버튼 클릭 시 실행된 뒤 popup이 닫힙니다.

Prop

Confirm 고정 동작

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

- Confirm도 Alert와 동일하게 닫기 버튼, backdrop click, `Escape` 닫힘을 모두 막아두고 버튼 액션으로만 닫히게 합니다.
- 취소 버튼은 `onCancel`, 확인 버튼은 `onConfirm` 흐름을 담당합니다.
- 현재 기본 레이아웃은 small size와 중앙 정렬을 유지하고, 버튼 클릭 후 자동 닫힘 기본값은 둘 다 `true`입니다.

Confirm defaults

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

Prop

openAsync()

(options) => Promise<boolean>

- `openAsync()`는 Confirm 결과를 `Promise<boolean>`으로 돌려줘서 `await` 다음 줄에서 바로 분기할 수 있습니다.
- 확인 버튼은 `true`, 취소 버튼은 `false`를 반환합니다.
- `close()`나 `closeAll()`처럼 코드로 닫아도 `false`로 정리됩니다.

const isConfirmed = await confirm.openAsync({
  title: "삭제 확인",
  description: "정말 삭제하시겠습니까?",
});

if (isConfirmed) {
  // 확인 이후 로직
}

Prop

id

string | undefined

- `id`를 넘기지 않으면 내부에서 고유 id를 자동 생성합니다.
- `open()`은 생성된 id를 반환하고, `openAsync()`도 내부적으로 id를 만들거나 전달받은 id를 그대로 사용합니다.
- 같은 `id`로 다시 열면 duplicate로 간주되어 에러가 발생합니다.

Confirm id rules

`id` 미지정: 자동 생성
`open()` / `openAsync()` 모두 특정 id 지정 가능
duplicate `id`: store에서 `throw`

Prop

useConfirm()

{ open: (options) => string; openAsync: (options) => Promise<boolean>; close: (id?: string) => void; closeAll: () => void; confirms: Array<{ id: string; type: "confirm"; status: "open" | "closing" }>; }

- `useConfirm()`은 `Alert`와 같은 방식으로 어느 페이지에서든 Confirm을 전역 호출할 수 있게 해줍니다.
- `open()`은 confirm id를 반환하고, `close(id?)`는 특정 id 또는 가장 마지막 Confirm을 닫습니다.
- `openAsync()`는 `await`로 확인 결과를 받아서 다음 로직을 이어갈 수 있고, 여러 개가 열린 상태에서는 `closeAll()`로 현재 열린 Confirm만 한 번에 닫을 수 있습니다.

Prop

usePopupStack()

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

전역 popup stack을 그대로 조회할 수 있어서 Alert와 Confirm이 함께 떠 있는 상태도 한 번에 확인할 수 있습니다.

Active popup stack

열린 팝업이 없습니다.

Props Table

Confirm options 한눈에 보기

useConfirm().open()과 openAsync()에 넘기는 ConfirmPopupOptions를 중심으로 정리했습니다.

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

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

Props Table

useConfirm API 한눈에 보기

전역 Confirm stack 제어와 async 분기에 사용하는 hook API를 표로 정리했습니다.

Prop	Type	Default	Required	Description
`open`	`(options: ConfirmPopupOptions) => string`	-	Required	새 Confirm을 전역 store stack에 추가하고 생성된 id를 반환합니다.
`openAsync`	`(options: ConfirmPopupOptions) => Promise<boolean>`	-	Required	확인 버튼이면 true, 취소 버튼이거나 close/closeAll로 닫히면 false를 resolve합니다.
`close`	`(id?: string) => void`	-	Required	id를 주면 해당 Confirm을 닫고, 생략하면 현재 Confirm stack의 마지막 항목을 닫습니다. openAsync 결과는 false로 정리됩니다.
`closeAll`	`() => void`	-	Required	현재 열린 Confirm 타입 인스턴스만 모두 closing 상태로 전환하고, openAsync 대기 promise도 false로 정리합니다.
`confirms`	`Array<{ id: string; type: "confirm"; status: "open" \| "closing" }>`	-	Required	전역 popup stack 중 Confirm 항목만 필터링한 snapshot 배열입니다.

useConfirm()는 route와 무관하게 Confirm을 띄우기 위한 전역 facade입니다. openAsync()는 store 위에 promise resolver를 얹은 helper라서, imperative 분기 처리에 적합합니다.