Tinyrack

Drawer

viewport 가장자리에서 미끄러져 나오며 열리고 닫힐 때 backdrop을 페이드하는 swipe 대응 작업 표면이에요.

핵심 속성

TRDrawer는 Base UI의 제어형·비제어형 상태, 스와이프와 스냅 지점 제스처, 포커스 관리, 키보드 닫기, 포털, React 19 ref와 render prop을 보존해요. 모션은 swipeDirection과 사용자의 모션 최소화 설정을 따라요. 플레이그라운드는 드로어 이벤트로 open과 snapPoint를 동기화하고, 초기화하면 아래로 열리는 전체 높이의 닫힌 기본값으로 되돌아가요.

설치

pnpm add @tinyrack/ui

긴 줄은 코드 영역 안에서 가로로 스크롤해 확인하세요.

스타일

@import '@tinyrack/ui/components/drawer.css';

긴 줄은 코드 영역 안에서 가로로 스크롤해 확인하세요.

가져오기

import { TRDrawer } from '@tinyrack/ui/components/drawer';

긴 줄은 코드 영역 안에서 가로로 스크롤해 확인하세요.

플레이그라운드

사용법

기본 고유 링크

예시

스냅 지점과 중첩 콘텐츠 고유 링크

`compact`, `medium`, `full-height` 위치 사이를 드래그해요. 중첩 드로어는 포커스 가두기와 연동되는 들여쓰기를 보여 줘요.

방향 고유 링크

`swipeDirection`을 `down`, `up`, `left`, `right`로 설정할 수 있어요. 팝업은 해당 뷰포트 가장자리에 붙고 같은 방향으로 닫혀요. 좌우 드로어는 테두리 없는 가장자리 표면을 사용해요.

Provider, 분리된 handle, 스와이프 영역 고유 링크

Provider는 페이지 들여쓰기를 조정하고 타입이 지정된 분리형 트리거는 `createHandle`로 페이로드를 전달해요. SwipeArea는 뷰포트 가장자리에서 같은 드로어를 열어요.

가상 키보드 고유 링크

VirtualKeyboardProvider는 모바일 가상 키보드가 시각적 뷰포트를 바꿀 때 포커스된 필드가 보이도록 유지해요.

구조

Root는 state를 소유하고 Trigger는 drawer를 열어요. Portal은 overlay를 body 또는 지정 container에 mount해요. Backdrop, Viewport, Popup, scroll 가능한 Content가 modal surface를 구성해요. Title과 Description은 dialog label을 제공하고 Close는 닫아요. SwipeArea는 edge opening을 제공해요. Provider, Indent, IndentBackground는 nested page effect를 조정하고 VirtualKeyboardProvider는 mobile keyboard viewport change를 처리해요. createHandle은 typed payload를 사용하는 detached trigger를 연결해요.

동작

  • controlled visibility에는 open과 onOpenChange, uncontrolled visibility에는 defaultOpen을 사용하세요.
  • controlled position에는 snapPoint와 onSnapPointChange, uncontrolled position에는 defaultSnapPoint를 사용하고 허용값은 snapPoints에 두세요.
  • swipeDirection은 가장자리와 닫힘 방향을 정해요. 좌우 드로어는 테두리 없는 가장자리 표면이고, 위아래 드로어는 기존 테두리가 있는 오버레이 표면을 유지해요. snapToSequentialPoints는 속도에 따른 스냅 지점 건너뛰기를 막아요.
  • Escape, Close, backdrop press, non-modal focus-out, swipe가 기본 dismissal이에요. outside pointer dismissal을 막으려면 disablePointerDismissal을 사용하세요.
  • modal 기본값은 true예요. outside interaction에는 false, scroll lock 없이 focus만 가두려면 trap-focus를 사용하세요.
  • Popup의 initialFocus와 finalFocus로 focus 이동을 지정하세요. 기본적으로 focus는 drawer로 들어가고 trigger로 돌아가요.
  • actionsRef는 imperative close와 unmount를 제공해요. 일반 flow에서는 declarative state를 사용하세요.
  • Portal은 클라이언트에서 마운트되고 닫힌 SSR 마크업은 hydration에 안전해요. 기본 body 포털은 예약된 스크롤바 여백까지 전체 시각적 뷰포트를 덮어요. custom portal을 사용하면 Viewport가 지정한 컨테이너 안에 머물러요.

API

모든 compound part와 prop/state type은 @tinyrack/ui/components/drawer에서 export돼요. CSS는 @tinyrack/ui/components/drawer.css로 opt-in하며 --tr-drawer-popup-max-width, --tr-drawer-popup-background, --tr-drawer-backdrop, --tr-drawer-control-background, --tr-drawer-motion-duration, --tr-drawer-motion-easing으로 appearance와 motion을 override할 수 있어요.