diff --git a/docs/public/ai.txt b/docs/public/ai.txt index fa575d8..c7ea1af 100644 --- a/docs/public/ai.txt +++ b/docs/public/ai.txt @@ -1,5 +1,5 @@ --- -updated: 2026-05-20 +updated: 2026-09-03 scope: / parent: https://overlay-kit.slash.page --- @@ -13,7 +13,7 @@ overlay-kit is a React library for declaratively managing overlays — modals, p - An npm package: `overlay-kit`. Install with `npm install overlay-kit`. - One context provider, ``, mounted exactly once at the React root. - One imperative object, `overlay`, with six methods: `open`, `openAsync`, `close`, `closeAll`, `unmount`, `unmountAll`. -- Two hooks: `useCurrentOverlay` (returns the top overlay's id), `useOverlayData` (returns the full overlay registry). +- Two hooks: `useCurrentOverlay` (returns the current overlay id and falls back through open overlays in registration order), `useOverlayData` (returns the full overlay registry). - UI-library agnostic. There is no built-in dialog UI — you supply the component, overlay-kit manages mounting, async results, and lifecycle. Verified integrations: Material UI, Chakra UI v3, Ant Design. Any React-based UI library works. ## Canonical facts diff --git a/docs/public/llms-full.txt b/docs/public/llms-full.txt index cbfd989..92e5fec 100644 --- a/docs/public/llms-full.txt +++ b/docs/public/llms-full.txt @@ -311,7 +311,13 @@ URL: https://overlay-kit.slash.page/en/docs/guides/hooks ### useCurrentOverlay -Returns the ID of the currently top-most overlay. +When an overlay is opened, it returns that overlay's ID. + +When a closed overlay is reopened with the same ID, it becomes the current overlay without changing its original registration order. + +When an overlay is closed or unmounted, it returns the last open overlay's ID in registration order, excluding the closed or unmounted overlay. + +If no overlays remain open, it returns `null`. The overlay ID can be specified by passing `overlayId` as the second argument to `overlay.open()` or `overlay.openAsync()`: @@ -393,8 +399,8 @@ The published guide demonstrates the following recipes with Jest/Vitest + React - **Closing overlays via `overlay.unmount`** — render a component that opens an overlay imperatively, click a button calling `overlay.unmount(overlayId)`, and assert the overlay leaves the DOM with `waitFor`. - **Opening multiple overlays via `overlay.open`** — open N overlays in a single `useEffect` and assert all of their contents are in the DOM. - **Async result via `overlay.openAsync`** — assert that the value passed to `close(value)` resolves as the awaited result; mock with `vi.fn()` and verify with `toHaveBeenCalledWith`. -- **Sequential unmount across overlays** — open multiple overlays, unmount them in a non-LIFO order, and assert `useCurrentOverlay` / DOM state stays consistent. -- **Active overlay tracking via `useCurrentOverlay`** — assert that the hook returns the id of the top overlay across `open` / `close` / `unmount` transitions. +- **Sequential unmount across overlays** — open multiple overlays, unmount them in a non-LIFO order, and assert removed overlays leave the DOM while the remaining overlays stay visible. +- **Active overlay tracking via `useCurrentOverlay`** — assert that the hook returns the current overlay id across `open` / `close` / `unmount` transitions. - **Closing/removing all overlays** — `overlay.closeAll()` removes them from the screen while `useOverlayData()` still reports them; `overlay.unmountAll()` removes them from memory and the DOM entirely. Rule of thumb: assert via `waitFor` (overlays mount/unmount asynchronously) and use `userEvent` for clicks so portaled overlays receive events correctly. diff --git a/docs/public/llms.txt b/docs/public/llms.txt index 5efcc85..d2643a8 100644 --- a/docs/public/llms.txt +++ b/docs/public/llms.txt @@ -6,7 +6,7 @@ overlay-kit is published as the [`overlay-kit`](https://www.npmjs.com/package/ov - ``: a context provider mounted once at the React root that determines where overlays render. - `overlay.open`, `overlay.openAsync`, `overlay.close`, `overlay.closeAll`, `overlay.unmount`, `overlay.unmountAll`: imperative API for opening and disposing overlays from inside or outside React (e.g., HTTP client hooks). -- `useCurrentOverlay`, `useOverlayData`: hooks that expose the current top overlay id and the full registry of mounted overlays. +- `useCurrentOverlay`, `useOverlayData`: hooks that expose the current overlay id and the full registry of mounted overlays. The library is UI-library agnostic. There is no built-in dialog UI — you supply the component, overlay-kit manages mounting, async results, and lifecycle. Documentation is bilingual (English at `/en`, Korean at `/ko`); English is the default locale and the canonical content surfaced here. The project is MIT-licensed and developed openly in the [toss/overlay-kit](https://github.com/toss/overlay-kit) GitHub repository. @@ -15,7 +15,7 @@ The library is UI-library agnostic. There is no built-in dialog UI — you suppl - [Getting Started](https://overlay-kit.slash.page/en/docs/guides/introduction): install, OverlayProvider setup, and a complete `overlay.open` / `overlay.openAsync` walkthrough. - [Think in overlay-kit](https://overlay-kit.slash.page/en/docs/guides/think-in-overlay-kit): rationale for the Declarative Overlay Pattern, imperative vs declarative comparison, and core design principles (Co-location, Minimum API). - [Code Comparison](https://overlay-kit.slash.page/en/docs/guides/code-comparison): before/after of overlay code with and without overlay-kit. -- [Hooks](https://overlay-kit.slash.page/en/docs/guides/hooks): `useCurrentOverlay` returns the top overlay's id; `useOverlayData` returns the full `{ id, componentKey, isOpen, controller }` registry. +- [Hooks](https://overlay-kit.slash.page/en/docs/guides/hooks): `useCurrentOverlay` returns the current overlay id and, after close or unmount, falls back through remaining open overlays in registration order; `useOverlayData` returns the full `{ id, componentKey, isOpen, controller }` registry. - [Testing](https://overlay-kit.slash.page/en/docs/guides/testing): Jest/Vitest + React Testing Library recipes for closing overlays, multiple overlays, async results, `closeAll`/`unmountAll`, and hook-based state assertions. - [FAQ](https://overlay-kit.slash.page/en/docs/guides/faq): common questions about `open` vs `openAsync`, `close` vs `unmount`, supported UI libraries, TypeScript support, and animation handling. - [Opening Overlays](https://overlay-kit.slash.page/en/docs/more/basic): expanded examples of `overlay.open`, `overlay.openAsync`, and memory-release patterns (`onExit`, `setTimeout`). diff --git a/docs/src/pages/en/docs/guides/hooks.mdx b/docs/src/pages/en/docs/guides/hooks.mdx index 0cf6925..8e55565 100644 --- a/docs/src/pages/en/docs/guides/hooks.mdx +++ b/docs/src/pages/en/docs/guides/hooks.mdx @@ -10,7 +10,13 @@ Using `useCurrentOverlay` and `useOverlayData`, you can implement state-based UX ## useCurrentOverlay -Returns the ID of the currently top-most overlay. +When an overlay is opened, it returns that overlay's ID. + +When a closed overlay is reopened with the same ID, it becomes the current overlay without changing its original registration order. + +When an overlay is closed or unmounted, it returns the last open overlay's ID in registration order, excluding the closed or unmounted overlay. + +If no overlays remain open, it returns `null`. The overlay ID can be directly specified by passing `overlayId` as the second argument to `overlay.open()` or `overlay.openAsync()` when opening an overlay: diff --git a/docs/src/pages/ko/docs/guides/hooks.mdx b/docs/src/pages/ko/docs/guides/hooks.mdx index 0e3cbd3..531acc8 100644 --- a/docs/src/pages/ko/docs/guides/hooks.mdx +++ b/docs/src/pages/ko/docs/guides/hooks.mdx @@ -12,7 +12,15 @@ import { Sandpack } from '@/components'; ## useCurrentOverlay -현재 가장 위에 떠 있는 오버레이의 ID를 반환해요. +오버레이를 열면 해당 오버레이의 ID를 반환해요. + +닫은 오버레이를 같은 ID로 다시 열면 현재 오버레이가 되지만, 기존 등록 순서는 유지돼요. + +닫거나 제거한 오버레이는 반환하지 않아요. + +이때 등록 순서상 마지막 ID를 반환해요. + +열린 오버레이가 없으면 `null`을 반환해요. 오버레이의 ID는 오버레이를 열 때 `overlay.open()` 또는 `overlay.openAsync()`의 두 번째 인자로 다음처럼 `overlayId`를 넘겨 직접 지정할 수 있어요: