useOverlayItems

useOverlayItems()는 현재 ReadonlyArray<OverlayItem>을 반환합니다. provider store의 subscribe, getSnapshot, getInitialSnapshot을 useSyncExternalStore와 함께 사용하므로 React 렌더링 중 일관된 snapshot을 받을 수 있습니다.

function OverlayDebugPanel() {
  const items = useOverlayItems();

  return <pre>{JSON.stringify(items, null, 2)}</pre>;
}

useOverlayItem(id)은 item 하나를 구독하고 OverlayItem | undefined를 반환하며 해당 item reference가 바뀌지 않으면 Object.is로 update를 생략합니다. 관련 없는 overlay 변경에 rerender하지 않고 lifecycle 하나만 필요할 때 사용하세요.

대부분의 app은 OverlayHost가 이미 full-list hook을 사용하므로 직접 호출할 필요가 없습니다. 진단, custom host 실험, 분석 패널, 테스트 전용 컴포넌트에는 유용합니다. 반환된 item을 수정하지 마세요. 읽기 전용 snapshot으로 다루고, lifecycle 상태 변경은 useOverlay 명령으로 수행하세요.

실무 메모

레퍼런스 문서는 런타임 계약을 정확히 설명합니다. 가이드에서는 이 API를 제품별 helper로 감쌀 수 있지만, 같은 lifecycle 언어를 유지해야 합니다. open은 item을 만들고, close는 closing 상태를 시작하며, remove는 item을 완료하고 삭제하고, clear는 provider 범위의 모든 대기 중인 overlay를 끝냅니다.