Project Information

FullPopup

FullPopup과 useFullPopup usage를 기준으로 전체 화면 popup 구조와 컴포넌트 등록형 흐름을 정리한 가이드 페이지입니다.

FullPopup

FullPopup은 PopupBase를 기반으로 한 전체 화면 팝업입니다. 라우트 전환 없이도 긴 편집 흐름과 다단계 작업 화면을 구성할 수 있는 패턴을 정리합니다.

Prop

title | children | footer | hasCloseButton | shouldCloseOnEscape | className

- FullPopup은 `PopupBase`의 shell을 전체 화면 variant로 고정한 팝업입니다.
- hook에서는 어떤 작업 화면을 띄울지만 결정하고, 긴 편집 흐름에 필요한 카드, 체크리스트, 액션은 각 FullPopup 컴포넌트 내부에서 직접 구성합니다.
- `hasCloseButton` 같은 shell 정책도 popup 컴포넌트 안의 `FullPopup`에 바로 선언하는 방식이 더 자연스럽습니다.

Prop

PopupBase shell / design props

title | icon | description | children | footer | className | panelClassName | bodyClassName | footerClassName | contentAlign | hasCloseButton | closeButtonLabel | shouldCloseOnBackdrop | shouldCloseOnEscape | dialogLabel | onClickClose

- FullPopup은 `PopupBase` shell을 감싼 wrapper이므로, custom popup 컴포넌트 안에서 `title`, `footer`, `contentAlign`, `panelClassName` 같은 shell props를 직접 설정할 수 있습니다. `size`는 LayerPopup 전용입니다.
- 반대로 `id`, `open`, `onRequestClose`, `onExited`는 디자인 props가 아니라 `PopupHost`가 runtime에 주입하는 인스턴스 제어용 props입니다.
- 그래서 보통 custom popup 컴포넌트에서는 `...runtimeProps`를 펼친 뒤, 필요한 shell props만 추가 선언하는 패턴을 사용합니다.

function ExamplePopup(runtimeProps: FullPopupComponentProps) {
  return (
    <FullPopup
      {...runtimeProps}
      title="팝업 제목"
      description="PopupBase shell props를 직접 제어하는 예시"

      contentAlign="left"
      panelClassName="customPanel"
      bodyClassName="customBody"
      footerClassName="customFooter"
      hasCloseButton
      closeButtonLabel="닫기"
      shouldCloseOnBackdrop={false}
      shouldCloseOnEscape={true}
      dialogLabel="상세 설정 팝업"
      onClickClose={() => {
        console.log("close button clicked");
      }}
      footer={<button onClick={runtimeProps.onRequestClose}>닫기</button>}
    >
      <div>custom contents</div>
    </FullPopup>
  );
}

Shell prop groups

Header / content: `title`, `icon`, `description`, `children`, `footer`
Layout / style: `contentAlign`, `className`, `panelClassName`, `bodyClassName`, `footerClassName`
Close / accessibility: `hasCloseButton`, `closeButtonLabel`, `shouldCloseOnBackdrop`, `shouldCloseOnEscape`, `dialogLabel`, `onClickClose`
Runtime from host: `id`, `open`, `onRequestClose`, `onExited`

Prop

component | id

React.ComponentType<FullPopupComponentProps> | string | undefined

- FullPopup도 custom popup 컴포넌트를 등록하는 구조입니다.
- route를 바꾸지 않고도 별도의 작업 화면을 띄우는 방식이기 때문에, hook 호출부에는 `component`만 두고 화면 내부 내용은 popup 컴포넌트에서 직접 조합하는 편이 더 단순합니다.

fullPopup.open({
  id: "campaign-preview-full-popup",
  component: CampaignPreviewFullPopup,
});

Prop

useFullPopup()

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

- `useFullPopup()`은 전체 화면 popup을 전역으로 열고 닫는 훅입니다.
- 여러 개를 순차적으로 stack에 쌓을 수 있고, `close(id?)`, `closeAll()`로 현재 full popup 흐름만 분리해서 제어할 수 있습니다.
- 스택이 쌓인 상태에서는 `close(id?)`로 마지막 항목 또는 특정 id를 닫는 방식으로 관리합니다.

Prop

usePopupStack()

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

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

Active popup stack

열린 팝업이 없습니다.

Props Table

FullPopup props 한눈에 보기

FullPopup shell에서 직접 제어하는 디자인 props와 PopupHost가 주입하는 runtime props를 함께 정리했습니다.

Prop	Type	Default	Required	Description
`title \| description \| children \| footer`	`React.ReactNode`	`undefined`	Optional	전체 화면 흐름에서 필요한 헤더, 본문, 하단 액션 영역을 조합합니다.
`icon`	`React.ReactNode \| null`	`undefined`	Optional	description 위에 아이콘 영역을 추가합니다. null이면 아이콘 슬롯을 비웁니다.
`contentAlign`	`"left" \| "center"`	`"left"`	Optional	본문 텍스트와 footer 정렬 기준을 제어합니다.
`hasCloseButton \| closeButtonLabel`	`boolean \| string`	`true \| "팝업 닫기"`	Optional	우측 상단 닫기 버튼 노출 여부와 접근성 라벨을 제어합니다.
`shouldCloseOnBackdrop \| shouldCloseOnEscape`	`boolean`	`true \| true`	Optional	backdrop 클릭과 Escape 키로 닫힐지 제어합니다. topmost popup에만 Escape가 반응합니다.
`dialogLabel`	`string`	`"전체 팝업"`	Optional	title이 없을 때 dialog aria-label fallback으로 사용합니다.
`className \| panelClassName \| bodyClassName \| footerClassName`	`string`	`undefined`	Optional	루트, 패널, body, footer wrapper 각각에 커스텀 클래스를 추가합니다.
`onClickClose`	`() => void`	`undefined`	Optional	닫기 버튼 클릭 시 onRequestClose 직전에 부가 동작을 실행합니다.
`id \| open \| onRequestClose \| onExited \| isTopmost`	`runtime props from PopupHost`	`injected`	Optional	커스텀 full popup 컴포넌트에서는 보통 `...runtimeProps`로 받고, PopupHost가 lifecycle을 주입합니다.

FullPopup은 PopupBase의 full variant wrapper입니다. viewport 전체를 쓰는 흐름이라 size는 고정되고 외부에서 받지 않습니다.

Props Table

useFullPopup API 한눈에 보기

FullPopup 등록과 stack 제어에 사용하는 hook API를 표로 정리했습니다.

Prop	Type	Default	Required	Description
`open`	`(options: FullPopupOptions) => string`	-	Required	새 FullPopup 인스턴스를 stack에 추가하고 생성된 id를 반환합니다.
`open.options.component`	`React.ComponentType<FullPopupComponentProps>`	-	Required	PopupHost가 렌더링할 custom FullPopup 컴포넌트입니다. runtime props를 받아야 합니다.
`open.options.id`	`string`	`auto generated id`	Optional	특정 인스턴스를 직접 추적하거나 close(id) 대상으로 삼고 싶을 때 사용합니다.
`close`	`(id?: string) => void`	-	Required	id를 주면 해당 FullPopup을 닫고, 생략하면 현재 타입 stack의 마지막 popup을 닫습니다.
`closeAll`	`() => void`	-	Required	현재 열린 FullPopup 타입 인스턴스만 모두 closing 상태로 전환합니다.
`fullPopups`	`Array<{ id: string; type: "fullPopup"; status: "open" \| "closing" }>`	-	Required	전역 popup stack 중 FullPopup 항목만 필터링한 snapshot 배열입니다.

useFullPopup()도 store action을 감싼 얇은 wrapper입니다. 실제 화면 콘텐츠와 shell props는 등록한 component 안에서 선언합니다.