[useFullscreen] 특정 요소를 전체화면으로 키우고 ESC 종료까지 동기화하는 훅

한 줄 요약 - 특정 카드나 화면 한 조각을 버튼 하나로 "전체화면"으로 키우고, 사용자가 ESC로 빠져나가도 화면 표시가 정확히 따라오게 만드는 훅입니다.

이럴 때 필요해요

이미지 뷰어, 동영상 플레이어, 프레젠테이션 모드처럼 "이 부분만 화면 가득 보여주고 싶다" 싶을 때가 있습니다. 브라우저에는 Fullscreen API(요소를 화면 전체로 띄우는 기능)가 있지만 직접 쓰면 함정이 많습니다. 사파리는 함수 이름이 다르고(webkitRequestFullscreen), 무엇보다 사용자가 ESC로 전체화면을 끄면 그 사실을 따로 알려주지 않습니다. 그래서 버튼은 아직 "종료"라고 떠 있는데 실제로는 이미 일반 화면인, 거짓말하는 UI가 됩니다.

어떻게 동작하나

1. 전체화면으로 만들 요소에 ref를 붙입니다. 버튼을 누르면 그 요소를(ref가 없으면 문서 전체를) 전체화면으로 요청합니다.
2. 동시에 브라우저의 fullscreenchange 이벤트를 구독합니다. 버튼이든 ESC든 F11이든 상태가 바뀌면 현재 전체화면 요소가 있는지 다시 확인해 우리 상태를 맞춥니다.
3. 컴포넌트가 사라질 때는 이 이벤트 구독을 정리(cleanup)해 누수를 막습니다.

핵심은 이거예요

"내가 켜고 끈 것"만 믿지 말고 fullscreenchange 이벤트로 실제 상태를 따라가는 것. 이 한 가지 덕분에 ESC로 나가든 어떻게 나가든 화면 표시가 절대 어긋나지 않습니다.

놓치기 쉬운 것

• 전체화면 진입은 반드시 사용자 클릭 같은 제스처 안에서 호출해야 합니다. 자동 실행하면 브라우저가 거부합니다.
• 사파리 등은 webkit- 접두사가 붙은 옛 이름을 씁니다. 표준 이름이 없으면 그쪽으로 폴백해야 합니다.
• 브라우저 API라 서버 렌더링 시점엔 없습니다. 모든 접근은 effect나 클릭 핸들러 안에서만, 지원 여부도 마운트 후에 판단합니다.

이런 곳에 써요

• 유튜브/넷플릭스식 동영상 플레이어의 전체화면 버튼
• 갤러리에서 사진 한 장만 화면 가득 띄우는 라이트박스