Popover — 웹 non-modal과 네이티브 adaptive 표현을 잇는 Popover

controlled open 상태, 컴포넌트가 소유하는 trigger·title·close와 웹 non-modal·네이티브 adaptive 표현을 제공하는 Expo·React Native Popover입니다.

v0.4.0 공개 예정

이 컴포넌트는 현재 소스에 포함된 다음 릴리스 미리보기입니다. npm latest에 반영될 때까지 검색 색인에서 제외됩니다.

Popover 사용 시점과 역할

Popover는 임의 trigger 합성 대신 이름과 크기를 보장하는 자체 button trigger를 렌더하고, open과 onOpenChange를 앱에 남깁니다. 웹에서는 anchor 충돌을 피하는 이름 있는 non-modal rich dialog로, 네이티브에서는 작은 화면 하단·넓은 화면 중앙의 Dialog surface로 적응하며 고정된 title·close header와 스크롤 가능한 본문을 유지합니다.

controlled open과 trigger·outside·Escape·Back·close 등 구체적인 변경 이유
12개 placement, RTL, flip·shift·collision padding과 detached anchor 정리
네이티브 auto·bottom·center presentation과 keyboardOverlap 우선 inset 합성

설치와 최소 예제

Popover: 패키지 루트 엔트리에서 import한 뒤 앱이 소유한 상태와 이벤트를 연결하세요.

TypeScript

pnpm add @gj-kit/expo-ui

import { Popover } from '@gj-kit/expo-ui';

<Popover triggerLabel="계정 도움말" title="계정 정보" open={open} onOpenChange={(next) => setOpen(next)}><Text>프로필 공개 범위를 설정합니다.</Text></Popover>

접근성과 플랫폼 동작

필수 title로 모든 플랫폼의 내용을 명명하고 아이콘 전용 trigger에는 triggerIcon과 triggerLabel을 함께 요구합니다. 웹 non-modal은 Tab으로 자연스럽게 빠져나가며 Escape와 명시적 close 뒤 trigger로 포커스를 복원합니다. arbitrary trigger, asChild와 public Portal은 공개 API가 아닙니다.

기본 스타일은 현재 UiProvider 테마의 color, spacing, radius, typography, metric 역할에서 파생됩니다. Expo, bare React Native와 React Native Web에서 같은 prop 계약을 사용합니다.

함께 사용하는 컴포넌트

Tooltip

v0.4.0 예정

44px 아이콘 액션을 직접 소유하고 웹 시각 tooltip·네이티브 accessibilityHint로 짧은 보조 설명을 전달하는 Expo·React Native Tooltip입니다.

Dialog

React Native Modal과 dismiss 가능한 백드롭을 제공하면서 패널·액션·키보드 정책을 앱에 맡기는 최소 Dialog 컴포넌트입니다.