### Install overlay-kit using npm

Source: https://github.com/toss/overlay-kit/blob/main/README.md

This command installs the overlay-kit library using npm. It's the first step to integrating overlay management into your React application.

```sh
npm install overlay-kit
```

--------------------------------

### Complete Example: Opening Overlays After API Requests

Source: https://github.com/toss/overlay-kit/blob/main/docs/src/pages/en/docs/more/open-outside-react.mdx

This is a full example demonstrating how to use 'overlay-kit' to open overlays in response to API requests. It utilizes 'ky' for making requests and 'overlay.open' to display an 'Alert' component, managed within an 'OverlayProvider'.

```tsx
import ky from 'ky';
import { OverlayProvider, overlay } from 'overlay-kit';
import Button from '@mui/material/Button';
import { Alert } from './alert';

const api = ky.extend({
  hooks: {
    afterResponse: [
      (_, __, response) => {
        overlay.open(({ isOpen, close, unmount }) => {
          return <Alert isOpen={isOpen} close={close} onExit={unmount} />;
        });
      },
    ],
  },
});

function App() {
  return <Button onClick={() => api('/api')}>API Request</Button>;
}

export function Example() {
  return (
    <OverlayProvider>
      <App />
    </OverlayProvider>
  );
}
```

```tsx
import { useEffect } from 'react';
import Button from '@mui/material/Button';
import Dialog from '@mui/material/Dialog';
import DialogTitle from '@mui/material/DialogTitle';
import DialogActions from '@mui/material/DialogActions';

export function Alert({ isOpen, close, onExit }) {
  useEffect(() => {
    return () => onExit();
  }, []);

  return (
    <Dialog open={isOpen} onClose={close} transitionDuration={1000}>
      <DialogTitle>API Response Received</DialogTitle>
      <DialogActions>
        <Button onClick={close}>Close</Button>
      </DialogActions>
    </Dialog>
  );
}
```

--------------------------------

### Open Simple Overlays with overlay.open

Source: https://github.com/toss/overlay-kit/blob/main/README.md

This example shows how to open a simple overlay using the `overlay.open` function. It's suitable for overlays that don't require asynchronous handling or returning specific results.

```tsx
import { overlay } from 'overlay-kit';

<Button
  onClick={() => {
    overlay.open(({ isOpen, close, unmount }) => (
      <Dialog open={isOpen} onClose={close} onExit={unmount} />
    ))
  }}
>
  Open
</Button>
```

--------------------------------

### Example: Unmounting Multiple Overlays (JSX)

Source: https://github.com/toss/overlay-kit/blob/main/docs/src/pages/en/api/utils/overlay-unmount-all.mdx

Demonstrates opening multiple overlays and then removing them all at once using overlay.unmountAll(). This is a straightforward way to clear the UI of all active dialogs or modals.

```tsx
overlay.open(({ isOpen, close, unmount }) => {
  return <ConfirmDialog isOpen={isOpen} close={close} onExit={unmount} />;
});
overlay.open(({ isOpen, close, unmount }) => {
  return <ConfirmDialog isOpen={isOpen} close={close} onExit={unmount} />;
});
overlay.open(({ isOpen, close, unmount }) => {
  return <ConfirmDialog isOpen={isOpen} close={close} onExit={unmount} />;
});

// Removes all three overlays above
overlay.unmountAll();
```

--------------------------------

### Open a Confirmation Dialog using overlay.open

Source: https://github.com/toss/overlay-kit/blob/main/docs/src/pages/en/docs/guides/introduction.mdx

Shows how to open the `ConfirmDialog` component using the `overlay.open` function. This example integrates with `OverlayProvider` and demonstrates a common use case for managing dialogs.

```tsx
import { OverlayProvider, overlay } from 'overlay-kit';
import Button from '@mui/material/Button';
import { ConfirmDialog } from './confirm-dialog';

function App() {
  return (
    <Button
      onClick={() => {
        overlay.open(({ isOpen, close }) => {
          return <ConfirmDialog isOpen={isOpen} close={close} />;
        });
      }}
    >
      Open Confirm Dialog
    </Button>
  );
}

export function Example() {
  return (
    <OverlayProvider>
      <App />
    </OverlayProvider>
  );
}
```

--------------------------------

### Manage and Display Overlays with OverlayProvider (React)

Source: https://github.com/toss/overlay-kit/blob/main/docs/src/pages/en/docs/guides/hooks.mdx

An example demonstrating the usage of OverlayProvider, overlay.open, and useOverlayData to manage and display overlays. It includes buttons to open overlays that can be closed or unmounted, and lists to show currently opened and all in-memory overlays.

```tsx
import { OverlayProvider, overlay, useOverlayData } from 'overlay-kit';
import Button from '@mui/material/Button';
import Stack from '@mui/material/Stack';
import List from '@mui/material/List';
import ListItem from '@mui/material/ListItem';
import Typography from '@mui/material/Typography';
import { ConfirmDialog } from './confirm-dialog';

function App() {
  const overlayData = useOverlayData();

  const allOverlayIds = Object.keys(overlayData);
  const openOverlayIds = allOverlayIds.filter((id) => overlayData[id].isOpen);

  return (
    <div>
      <Stack direction="row" spacing={1}>
        <Button
          variant="contained"
          onClick={() => {
            overlay.open(
              ({ isOpen, close }) => {
                return <ConfirmDialog isOpen={isOpen} close={close} title="Overlay A (close)" />;
              },
              { overlayId: 'modal-close' }
            );
          }}
        >
          Open Overlay A (close)
        </Button>

        <Button
          variant="outlined"
          style={{ marginLeft: '8px' }}
          onClick={() => {
            overlay.open(
              ({ isOpen, unmount }) => {
                return <ConfirmDialog isOpen={isOpen} close={unmount} title="Overlay B (unmount)" />;
              },
              { overlayId: 'modal-unmount' }
            );
          }}
        >
          Open Overlay B (unmount)
        </Button>
      </Stack>
      <div style={{ marginTop: '24px' }}>
        <Typography variant="subtitle1">Opened Overlays</Typography>
        <List dense>
          {openOverlayIds.length > 0 ? (
            openOverlayIds.map((id) => <ListItem key={id}>{id}</ListItem>)
          ) : (
            <ListItem>None</ListItem>
          )}
        </List>

        <Typography variant="subtitle1" style={{ marginTop: '16px' }}>
          Overlays in Memory
        </Typography>
        <List dense>
          {allOverlayIds.length > 0 ? (
            allOverlayIds.map((id) => <ListItem key={id}>{id}</ListItem>)
          ) : (
            <ListItem>None</ListItem>
          )}
        </List>
      </div>
    </div>
  );
}

export const Example = () => {
  return (
    <OverlayProvider>
      <App />
    </OverlayProvider>
  );
};

```

--------------------------------

### Usage Example: Opening and Closing Multiple Overlays (TSX)

Source: https://github.com/toss/overlay-kit/blob/main/docs/src/pages/en/api/utils/overlay-close-all.mdx

Demonstrates opening multiple overlay components and then closing them all simultaneously using overlay.closeAll(). This showcases a common pattern for managing multiple dialogs or modals.

```tsx
overlay.open(({ isOpen, close, unmount }) => {
  return <ConfirmDialog isOpen={isOpen} close={close} onExit={unmount} />;
});
overlay.open(({ isOpen, close, unmount }) => {
  return <ConfirmDialog isOpen={isOpen} close={close} onExit={unmount} />;
});
overlay.open(({ isOpen, close, unmount }) => {
  return <ConfirmDialog isOpen={isOpen} close={close} onExit={unmount} />;
});

// Closes all three overlays above
overlay.closeAll();
```

--------------------------------

### Example: Unmounting Overlays with Animations (JSX)

Source: https://github.com/toss/overlay-kit/blob/main/docs/src/pages/en/api/utils/overlay-unmount-all.mdx

Illustrates the recommended approach for unmounting overlays that have closing animations. It involves calling overlay.closeAll() first, waiting for animations to complete (e.g., using setTimeout), and then calling overlay.unmountAll() for a smooth user experience.

```tsx
const overlayId = overlay.open(({ isOpen, close, unmount }) => {
  return <ConfirmDialog isOpen={isOpen} close={close} onExit={unmount} />;
});

overlay.closeAll();

setTimeout(() => {
  overlay.unmountAll();
}, 1000);
```

--------------------------------

### Setup OverlayProvider in React Application

Source: https://context7.com/toss/overlay-kit/llms.txt

The OverlayProvider component must wrap your entire React application to provide the necessary context for rendering overlays. It should be placed at the root of your application, typically within your main `index.tsx` or `App.tsx` file.

```tsx
import { OverlayProvider } from 'overlay-kit';
import { createRoot } from 'react-dom/client';

function App() {
  return (
    <div>
      <h1>My Application</h1>
      {/* Your app components */}
    </div>
  );
}

// Wrap your entire application with OverlayProvider
const root = createRoot(document.getElementById('root')!);
root.render(
  <OverlayProvider>
    <App />
  </OverlayProvider>
);
```

--------------------------------

### Using OverlayProvider to Render Modals (React)

Source: https://github.com/toss/overlay-kit/blob/main/docs/src/pages/en/api/components/overlay-provider.mdx

This example shows how to integrate OverlayProvider with a custom modal component. The `overlay.open` function is used within a component to trigger the display of a modal, which is then rendered by the OverlayProvider. It requires the 'overlay-kit' library and a Modal component.

```tsx
import React from 'react';
import { OverlayProvider, overlay } from 'overlay-kit';
import { Modal } from '@src/components';

function App() {
  const notify = () =>
    overlay.open(({ isOpen, close, unmount }) => (
      <Modal isOpen={isOpen} onClose={close} onExit={unmount}>
        {/* Modal content */}
      </Modal>
    ));

  return <button onClick={notify}>open modal</button>;
}

export function Root() {
  return (
    <OverlayProvider>
      <App />
      {/* All overlays will be rendered here */}
    </OverlayProvider>
  );
}
```

--------------------------------

### Open Overlay and Get Result (TypeScript)

Source: https://github.com/toss/overlay-kit/blob/main/docs/src/pages/en/api/utils/overlay-open-async.mdx

Demonstrates how to open an overlay asynchronously using overlay.openAsync and await its result. The result is the value passed to the close function within the overlay controller.

```typescript
const result = await overlay.openAsync(controller, options);

```

--------------------------------

### Open Confirm Dialog with Overlay Kit (TypeScript)

Source: https://github.com/toss/overlay-kit/blob/main/docs/src/pages/en/docs/guides/introduction.mdx

This example demonstrates how to open a confirmation dialog using the `overlay.open` function from `overlay-kit`. It passes the `unmount` function as the `onExit` prop to the `ConfirmDialog` component, ensuring memory is released upon closing.

```tsx
import { OverlayProvider, overlay } from 'overlay-kit';
import Button from '@mui/material/Button';
import { ConfirmDialog } from './confirm-dialog';

function App() {
  return (
    <>
      <Button
        onClick={() => {
          overlay.open(({ isOpen, close, unmount }) => {
            return <ConfirmDialog isOpen={isOpen} close={close} onExit={unmount} />; 
          });
        }}
      >
        Open Confirm Dialog
      </Button>
    </>
  );
}

export function Example() {
  return (
    <OverlayProvider>
      <App />
    </OverlayProvider>
  );
}
```

--------------------------------

### Implement Confirmation Dialog with overlay.openAsync (TypeScript/React)

Source: https://github.com/toss/overlay-kit/blob/main/docs/src/pages/en/api/utils/overlay-open-async.mdx

Shows a practical example of using overlay.openAsync to render a confirmation dialog. The controller function defines confirm and cancel actions, which call the close function with boolean values. The returned promise resolves with true for confirmation or false for cancellation.

```tsx
overlay.openAsync(({ isOpen, close, unmount }) => {
  function confirm() {
    close(true);
  }
  function cancel() {
    close(false);
  }

  return <ConfirmDialog isOpen={isOpen} confirm={confirm} close={cancel} onExit={unmount} />;
});

```

--------------------------------

### Open Simple Overlay with overlay.open

Source: https://github.com/toss/overlay-kit/blob/main/docs/src/pages/en/docs/more/basic.mdx

Demonstrates how to open a simple overlay using the `overlay.open` function. This function takes a render prop that receives `isOpen` and `close` props to control the overlay's visibility and lifecycle. It requires the `OverlayProvider` to be set up at the root of the application.

```tsx
import { OverlayProvider, overlay } from 'overlay-kit';
import Button from '@mui/material/Button';
import Dialog from '@mui/material/Dialog';
import DialogActions from '@mui/material/DialogActions';
import DialogContent from '@mui/material/DialogContent';
import DialogContentText from '@mui/material/DialogContentText';
import DialogTitle from '@mui/material/DialogTitle';

function App() {
  return (
    <Button
      onClick={() => {
        overlay.open(({ isOpen, close }) => {
          return (
            <Dialog open={isOpen} onClose={close}>
              <DialogTitle>Are you sure you want to continue?</DialogTitle>
              <DialogActions>
                <Button onClick={close}>No</Button>
                <Button onClick={close}>Yes</Button>
              </DialogActions>
            </Dialog>
          );
        });
      }}
    >
      Open Confirm Dialog
    </Button>
  );
}

export function Example() {
  return (
    <OverlayProvider>
      <App />
    </OverlayProvider>
  );
}
```

--------------------------------

### Get Current Overlay ID with useCurrentOverlay (React)

Source: https://github.com/toss/overlay-kit/blob/main/docs/src/pages/en/docs/guides/hooks.mdx

The `useCurrentOverlay` hook returns the ID of the currently top-most overlay. This ID can be manually set when opening an overlay or automatically generated. It's useful for conditional rendering, focus management, or shortcut control based on the active overlay. This example demonstrates how the hook's output changes as different overlays are opened.

```tsx
import { OverlayProvider, overlay, useCurrentOverlay } from 'overlay-kit';
import Button from '@mui/material/Button';
import Typography from '@mui/material/Typography';
import { ConfirmDialog } from './confirm-dialog';

function App() {
  const current = useCurrentOverlay();

  return (
    <div>
      <Button
        variant="contained"
        onClick={() => {
          overlay.open(
            ({ isOpen, close }) => {
              return <ConfirmDialog isOpen={isOpen} close={close} title="Overlay A" />;
            },
            { overlayId: 'modal-a' }
          );
        }}
      >
        Open Overlay A
      </Button>

      <Button
        variant="outlined"
        style={{ marginLeft: '8px' }}
        onClick={() => {
          overlay.open(
            ({ isOpen, close }) => {
              return <ConfirmDialog isOpen={isOpen} close={close} title="Overlay B" />;
            },
            { overlayId: 'modal-b' }
          );
        }}
      >
        Open Overlay B
      </Button>

      <Typography variant="body1" style={{ marginTop: '5px' }}>
        Current value: {current}
      </Typography>
    </div>
  );
}

export const Example = () => {
  return (
    <OverlayProvider>
      <App />
    </OverlayProvider>
  );
};

```

```tsx
import Button from '@mui/material/Button';
import Dialog from '@mui/material/Dialog';
import DialogTitle from '@mui/material/DialogTitle';
import DialogContent from '@mui/material/DialogContent';
import DialogActions from '@mui/material/DialogActions';
import Typography from '@mui/material/Typography';
import { overlay } from 'overlay-kit';

export function ConfirmDialog({ isOpen, close, title }) {
  return (
    <Dialog open={isOpen} onClose={close}>
      <DialogTitle>{title}</DialogTitle>
      <DialogContent>
        <Typography>This is the content of {title}.</Typography>
      </DialogContent>
      <DialogActions>
        <Button onClick={close}>Close</Button>
      </DialogActions>
    </Dialog>
  );
}

```

--------------------------------

### Overlay Open vs OpenAsync Comparison

Source: https://github.com/toss/overlay-kit/blob/main/docs/src/pages/en/docs/guides/faq.mdx

Demonstrates the difference between overlay.open for basic operations and overlay.openAsync for asynchronous handling with Promises, including input and output.

```tsx
overlay.open(({ isOpen, close }) => (
  <Dialog open={isOpen} onClose={close}>
    <p>Simple overlay</p>
  </Dialog>
));

const result = await overlay.openAsync<boolean>(({ isOpen, close }) => (
  <Dialog open={isOpen} onClose={() => close(false)}>
    <Button onClick={() => close(true)}>Confirm</Button>
  </Dialog>
));

console.log(result ? 'Yes' : 'No');
```

--------------------------------

### Overlay Implementation with overlay-kit (After)

Source: https://github.com/toss/overlay-kit/blob/main/docs/src/pages/en/docs/guides/code-comparison.mdx

This snippet demonstrates how to implement an overlay using the overlay-kit library. It significantly reduces boilerplate by abstracting away the state management for the overlay. The `overlay.open` function handles the visibility and closing logic, making the code more concise and intuitive.

```tsx
import { overlay } from 'overlay-kit';

function MyPage() {
  /* Other Hook calls... */

  return (
    <>
      {/* Other components... */}
      <Button
        onClick={() => {
          overlay.open(({ isOpen, close }) => {
            return <Dialog open={isOpen} onClose={close} />;
          });
        }}
      >
        Open
      </Button>
    </>
  );
}
```

--------------------------------

### Overlay Close vs Unmount Comparison

Source: https://github.com/toss/overlay-kit/blob/main/docs/src/pages/en/docs/guides/faq.mdx

Illustrates the usage of overlay.closeAll to close all overlays while retaining state and overlay.unmountAll to completely remove them from memory.

```tsx
// Close all overlays
overlay.closeAll();

// Remove all overlays
overlay.unmountAll();
```

--------------------------------

### Declarative Overlay Management with overlay-kit

Source: https://github.com/toss/overlay-kit/blob/main/docs/src/pages/en/docs/guides/think-in-overlay-kit.mdx

Illustrates the declarative approach to overlay management using the overlay-kit library. This method simplifies overlay handling by removing explicit state management, leading to cleaner and more maintainable code. The overlay component is rendered directly within the `overlay.open` function.

```tsx
import { overlay } from 'overlay-kit';

function Overlay() {
  return (
    <Button
      onClick={() => {
        overlay.open(({ isOpen, close }) => (
          <Dialog open={isOpen} onClose={close}>
            <DialogTitle>Declarative Overlay</DialogTitle>
            <DialogActions>
              <Button onClick={close}>OK</Button>
              <Button onClick={close}>Cancel</Button>
            </DialogActions>
          </Dialog>
        ));
      }}
    >
      Open
    </Button>
  );
}
```

--------------------------------

### Open Asynchronous Overlays with overlay.openAsync

Source: https://github.com/toss/overlay-kit/blob/main/README.md

This code demonstrates how to open an overlay and handle its result as a Promise using `overlay.openAsync`. This is useful when you need to wait for a user's action within the overlay, like confirming a dialog.

```tsx
import { overlay } from 'overlay-kit';

<Button
  onClick={async () => {
    const result = await overlay.openAsync<boolean>(({ isOpen, close, unmount }) => (
      <Dialog
        open={isOpen}
        onConfirm={() => close(true)}
        onClose={() => close(false)}
        onExit={unmount}
      />
    ))
  }}
>
  Open
</Button>
```

--------------------------------

### Traditional React Overlay Implementation (Before overlay-kit)

Source: https://github.com/toss/overlay-kit/blob/main/docs/src/pages/en/docs/guides/code-comparison.mdx

This snippet shows a traditional React implementation for managing an overlay. It requires manual state management for the overlay's visibility (`isOpen`) and separate handlers for opening and closing. This approach leads to more boilerplate code and can disrupt the code flow due to React's Hook rules.

```tsx
import { useState } from 'react';

function MyPage() {
  const [isOpen, setIsOpen] = useState(false);
  /* Other Hook calls... */
  return (
    <>
      {/* Other components... */}
      <Button
        onClick={() => {
          setIsOpen(true);
        }}
      >
        Open
      </Button>
      {/* Other components... */}
      <Dialog
        open={isOpen}
        onClose={() => {
          setIsOpen(false);
        }}
      />
    </>
  );
}
```

--------------------------------

### Get Current Overlay ID with Hook - overlay-kit

Source: https://context7.com/toss/overlay-kit/llms.txt

A React hook that provides the ID of the currently active, top-most overlay. This hook is essential for managing overlay-specific logic, such as conditional rendering, focus management, or handling keyboard shortcuts based on the visible overlay.

```tsx
import { useCurrentOverlay, overlay, OverlayProvider } from 'overlay-kit';

function App() {
  const currentOverlayId = useCurrentOverlay();

  // Conditionally render based on current overlay
  return (
    <div>
      <p>Current overlay: {currentOverlayId ?? 'None'}</p>

      <button onClick={() => {
        overlay.open(
          ({ isOpen, close }) => <SettingsModal isOpen={isOpen} onClose={close} />,
          { overlayId: 'settings-modal' }
        );
      }}>
        Open Settings
      </button>

      {currentOverlayId === 'settings-modal' && (
        <p>Settings modal is currently active</p>
      )}
    </div>
  );
}

// Must be used within OverlayProvider
function Root() {
  return (
    <OverlayProvider>
      <App />
    </OverlayProvider>
  );
}
```

--------------------------------

### Declarative Overlay Pattern with React Component

Source: https://github.com/toss/overlay-kit/blob/main/docs/src/pages/en/index.mdx

Demonstrates the usage of the Main component from the overlay-kit library to define overlays declaratively. It showcases how to pass titles, descriptions, and an array of items, each with its own title and description, to configure overlay behavior.

```javascript
import { Main } from '@/components';

<Main
  title="overlay-kit"
  description="Declarative Overlay Pattern"
  subDescription="The New Standard in Overlay Management"
  navButtonText="Get Started"
  items={[
    {
      title: 'Declarative API',
      description: ``overlay-kit` provides a declarative API familiar to React developers.\nWith `overlay.open()`, you can create intuitive overlays with less code.`,
    },
    {
      title: 'Overlay Management Aligned with React Philosophy',
      description: `Designed to reflect React's declarative UI management approach.\nDefine overlay behavior declaratively without complex state management.`,
    },
    {
      title: 'Clean Code Without State Management',
      description: `Reduce state management code like `useState` or `onClose`.\nWrite cleaner and more maintainable code by focusing solely on overlay behavior.`,
    },
  ]} 
/>
```

--------------------------------

### Render OverlayProvider at Application Root (React)

Source: https://github.com/toss/overlay-kit/blob/main/docs/src/pages/en/api/components/overlay-provider.mdx

This snippet demonstrates the basic usage of OverlayProvider by wrapping the main App component. It ensures that all overlays are rendered within the correct context. OverlayProvider should only be rendered once.

```tsx
<OverlayProvider>
  <App />
</OverlayProvider>
```

--------------------------------

### Maintaining Closing Animation with Close and Unmount

Source: https://github.com/toss/overlay-kit/blob/main/docs/src/pages/en/docs/guides/faq.mdx

Shows how to use close() to trigger the closing animation and then unmount() after a delay to remove the overlay from memory, ensuring animations are visible.

```tsx
overlay.open(({ isOpen, close, unmount }) => (
  <Dialog
    open={isOpen}
    onClose={() => {
      close(); // Run closing animation
      setTimeout(() => unmount(), 300); // Remove from memory after animation
    }}
  >
    <p>Maintain animation</p>
  </Dialog>
));
```

--------------------------------

### Open Asynchronous Overlay with Confirmation

Source: https://github.com/toss/overlay-kit/blob/main/docs/src/pages/en/docs/guides/introduction.mdx

Demonstrates opening a confirmation dialog asynchronously using overlay.openAsync. The dialog returns a boolean promise based on user selection ('Yes' or 'No'). It requires 'overlay-kit' and '@mui/material' dependencies.

```tsx
import { useState } from 'react';
import { OverlayProvider, overlay } from 'overlay-kit';
import Button from '@mui/material/Button';
import { ConfirmDialog } from './confirm-dialog';

function App() {
  const [result, setResult] = useState<boolean | null>(null);

  return (
    <>
      <p>{result === null ? 'Not selected' : result ? 'Y' : 'N'}</p>
      <Button
        onClick={async () => {
          const result = await overlay.openAsync(({ isOpen, close }) => {
            return <ConfirmDialog isOpen={isOpen} close={() => close(false)} confirm={() => close(true)} />;
          });

          setResult(result);
        }}
      >
        Open Confirm Dialog
      </Button>
    </>
  );
}

export function Example() {
  return (
    <OverlayProvider>
      <App />
    </OverlayProvider>
  );
}
```

```tsx
import Button from '@mui/material/Button';
import Dialog from '@mui/material/Dialog';
import DialogTitle from '@mui/material/DialogTitle';
import DialogActions from '@mui/material/DialogActions';

export function ConfirmDialog({ isOpen, close, confirm }) {
  return (
    <Dialog open={isOpen} onClose={close}>
      <DialogTitle>Are you sure you want to continue?</DialogTitle>
      <DialogActions>
        <Button onClick={close}>No</Button>
        <Button onClick={confirm}>Yes</Button>
      </DialogActions>
    </Dialog>
  );
}
```

--------------------------------

### Open Overlay with Controller and Options

Source: https://github.com/toss/overlay-kit/blob/main/docs/src/pages/en/api/utils/overlay-open.mdx

Opens an overlay using a controller function and optional configuration. The controller defines the overlay's UI and behavior. Options can include a unique overlayId for identification. Returns the overlay's unique ID.

```typescript
const overlayId = overlay.open(controller, options);
```

--------------------------------

### Open Overlay with Controller

Source: https://github.com/toss/overlay-kit/blob/main/docs/src/pages/en/api/utils/overlay-open.mdx

Opens an overlay by providing a controller function. The controller receives state and control functions (isOpen, close, unmount) and returns the JSX to be rendered. This is a basic usage for displaying an overlay.

```tsx
overlay.open(({ isOpen, close, unmount }) => {
  return <Alert isOpen={isOpen} close={close} onExit={unmount} />;
});
```

--------------------------------

### Open Overlay with Controller Props

Source: https://context7.com/toss/overlay-kit/llms.txt

The `overlay.open()` function displays an overlay and returns its unique ID. The provided controller function receives `isOpen`, `close`, and `unmount` props to manage the overlay's lifecycle. `close()` hides the overlay while keeping it in memory, whereas `unmount()` removes it entirely.

```tsx
import { overlay } from 'overlay-kit';
import Dialog from '@mui/material/Dialog';
import DialogTitle from '@mui/material/DialogTitle';
import DialogActions from '@mui/material/DialogActions';
import Button from '@mui/material/Button';

// Basic usage - open an overlay
function openDialog() {
  const overlayId = overlay.open(({ isOpen, close, unmount }) => (
    <Dialog open={isOpen} onClose={close}>
      <DialogTitle>Are you sure you want to continue?</DialogTitle>
      <DialogActions>
        <Button onClick={close}>Cancel</Button>
        <Button onClick={close}>Confirm</Button>
      </DialogActions>
    </Dialog>
  ));

  console.log('Opened overlay with ID:', overlayId);
  // Output: Opened overlay with ID: overlay-kit-abc123
}

// With custom overlay ID for later reference
function openNamedDialog() {
  overlay.open(
    ({ isOpen, close, unmount }) => (
      <Dialog open={isOpen} onClose={close}>
        <DialogTitle>Named Dialog</DialogTitle>
        <DialogActions>
          <Button onClick={() => {
            close();
            // Call unmount after animation completes to release memory
            setTimeout(unmount, 300);
          }}>Close</Button>
        </DialogActions>
      </Dialog>
    ),
    { overlayId: 'my-custom-dialog' }
  );
}
```

--------------------------------

### Close All Overlays with Overlay Kit

Source: https://github.com/toss/overlay-kit/blob/main/docs/src/pages/en/docs/guides/testing.mdx

Demonstrates how to close all currently open overlays using the `closeAll` method. This is useful for resetting the UI state or cleaning up after user interactions. It ensures that no overlay content remains visible.

```tsx
it('should be able to close all overlays', async () => {
  const contents = {
    first: 'overlay-content-1',
    second: 'overlay-content-2',
  };

  function Component() {
    const data = useOverlayData();
    const overlays = Object.values(data);
    const hasOpenOverlay = overlays.some((overlay) => overlay.isOpen);

    useEffect(() => {
      overlay.open(({ isOpen }) => isOpen && <div data-testid="overlay-1">{contents.first}</div>);
      overlay.open(({ isOpen }) => isOpen && <div data-testid="overlay-2">{contents.second}</div>);
    }, []);

    return <div>{hasOpenOverlay && 'has Open overlay'}</div>;
  }

  render(<Component />, { wrapper });

  await waitFor(() => {
    expect(screen.getByTestId('overlay-1')).toBeInTheDocument();
    expect(screen.getByTestId('overlay-2')).toBeInTheDocument();
  });

  overlay.closeAll();
  await waitFor(() => {
    expect(screen.queryByTestId(/^overlay-/)).not.toBeInTheDocument();
    expect(screen.queryByText('has Open overlay')).not.toBeInTheDocument();
  });
});
```

--------------------------------

### Add OverlayProvider to React App

Source: https://github.com/toss/overlay-kit/blob/main/README.md

This code snippet demonstrates how to set up the `OverlayProvider` in your React application. This provider is essential for enabling overlay functionality throughout your app.

```tsx
import { OverlayProvider } from 'overlay-kit';

const app = createRoot(document.getElementById('root')!); 
app.render(
  <OverlayProvider>
    <App />
  </OverlayProvider>
);
```

--------------------------------

### Imperative Overlay Management in React

Source: https://github.com/toss/overlay-kit/blob/main/docs/src/pages/en/docs/guides/think-in-overlay-kit.mdx

Demonstrates the traditional imperative approach to managing overlay state using React's useState hook. This method involves explicit state updates for opening and closing the overlay, which can lead to complex and less readable code.

```tsx
import { useState } from 'react';

function Overlay() {
  const [isOpen, setIsOpen] = useState(false);

  function handleOpen() {
    setIsOpen(true);
  }

  function handleClose() {
    setIsOpen(false);
  }

  return (
    <>
      <Button onClick={handleOpen}>Open</Button>
      <Dialog open={isOpen} onClose={handleClose}>
        <DialogTitle>Imperative Overlay</DialogTitle>
        <DialogActions>
          <Button onClick={handleClose}>OK</Button>
          <Button onClick={handleClose}>Cancel</Button>
        </DialogActions>
      </Dialog>
    </>
  );
}
```

--------------------------------

### Create Isolated Overlay Context

Source: https://context7.com/toss/overlay-kit/llms.txt

The `experimental_createOverlayContext` function generates an independent overlay system. It returns its own `overlay` instance, `OverlayProvider`, and hooks (`useCurrentOverlay`, `useOverlayData`). This is ideal for micro-frontends or scenarios requiring multiple, non-conflicting overlay managers.

```tsx
import { experimental_createOverlayContext } from 'overlay-kit';

// Create isolated overlay context
const {
  overlay: widgetOverlay,
  OverlayProvider: WidgetOverlayProvider,
  useCurrentOverlay: useWidgetCurrentOverlay,
  useOverlayData: useWidgetOverlayData
} = experimental_createOverlayContext();

// Use in a self-contained widget
function Widget() {
  return (
    <WidgetOverlayProvider>
      <WidgetContent />
    </WidgetOverlayProvider>
  );
}

function WidgetContent() {
  const handleClick = () => {
    // Uses widget's isolated overlay system
    widgetOverlay.open(({ isOpen, close }) => (
      <WidgetModal isOpen={isOpen} onClose={close} />
    ));
  };

  return <button onClick={handleClick}>Open Widget Modal</button>;
}
```

--------------------------------

### Unmount All Overlays with Overlay Kit

Source: https://github.com/toss/overlay-kit/blob/main/docs/src/pages/en/docs/guides/testing.mdx

Demonstrates how to completely remove all rendered overlays from the DOM using the `unmountAll` method. This is a more aggressive cleanup than `closeAll`, ensuring that all overlay components are destroyed. It's useful for scenarios where overlays might leave lingering DOM elements.

```tsx
it('should be able to unmount all overlays', async () => {
  const contents = {
    first: 'overlay-content-1',
    second: 'overlay-content-2',
  };

  function Component() {
    const data = useOverlayData();
    const overlays = Object.values(data);
    const hasOverlay = overlays.length !== 0;

    useEffect(() => {
      overlay.open(({ isOpen }) => isOpen && <div data-testid="overlay-1">{contents.first}</div>);
      overlay.open(({ isOpen }) => isOpen && <div data-testid="overlay-2">{contents.second}</div>);
    }, []);

    return <div>{hasOverlay && 'has overlay'}</div>;
  }

  render(<Component />, { wrapper });

  await waitFor(() => {
    expect(screen.getByTestId('overlay-1')).toBeInTheDocument();
    expect(screen.getByTestId('overlay-2')).toBeInTheDocument();
  });

  overlay.unmountAll();
  await waitFor(() => {
    expect(screen.queryByTestId(/^overlay-/)).not.toBeInTheDocument();
    expect(screen.queryByText('has overlay')).not.toBeInTheDocument();
  });
});
```

--------------------------------

### overlay.openAsync

Source: https://github.com/toss/overlay-kit/blob/main/docs/src/pages/en/api/utils/overlay-open-async.mdx

Opens an overlay that returns a value upon closing, typically used for user confirmation or input.

```APIDOC
## POST /toss/overlay-kit/openAsync

### Description
Opens an overlay that returns a value when closed. This is useful for scenarios requiring user input, such as confirmation dialogs.

### Method
POST

### Endpoint
/toss/overlay-kit/openAsync

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **controller** (function) - Required - The overlay controller function. It receives overlay state and control functions (`isOpen`, `close`, `unmount`) and should return JSX to render the overlay.
  - **isOpen** (boolean) - Indicates if the overlay is currently open.
  - **close** (function) - Closes the overlay and resolves the returned Promise with the provided argument.
  - **unmount** (function) - Removes the overlay from the DOM.
- **options** (object) - Optional - Overlay configuration options.
  - **overlayId** (string) - Optional - A unique identifier for the overlay. Use with caution to avoid duplicates.

### Request Example
```json
{
  "controller": "(controller_function)",
  "options": {
    "overlayId": "uniqueOverlayId"
  }
}
```

### Response
#### Success Response (200)
- **returnValue** (any) - The value passed to the `close` function when the overlay was closed.

#### Response Example
```json
{
  "returnValue": true
}
```

### Important Notes
- Ensure `overlayId` is unique if provided, as duplicate IDs can lead to unexpected behavior.
- Call `unmount` carefully to allow animations to complete before removal.
```

--------------------------------

### Close Overlay with 'close' vs 'unmount'

Source: https://github.com/toss/overlay-kit/blob/main/docs/src/pages/en/docs/guides/introduction.mdx

Illustrates the functional difference between the 'close' and 'unmount' functions provided by overlay-kit for closing overlays. 'close' retains state and plays animation, while 'unmount' immediately removes the overlay and resets its state.

```tsx
import { OverlayProvider, overlay } from 'overlay-kit';
import Button from '@mui/material/Button';
import { ConfirmDialog } from './confirm-dialog';

function App() {
  return (
    <>
      <Button
        onClick={() => {
          overlay.open(
            ({ isOpen, close }) => {
              return <ConfirmDialog isOpen={isOpen} close={close} />;
            },
            { overlayId: 'close-overlay' }
          );
        }}
      >
        Close overlay using close
      </Button>
      <Button
        onClick={() => {
          overlay.open(
            ({ isOpen, unmount }) => {
              return <ConfirmDialog isOpen={isOpen} close={unmount} />;
            },
            { overlayId: 'unmount-overlay' }
          );
        }}
      >
        Close overlay using unmount
      </Button>
    </>
  );
}

export function Example() {
  return (
    <OverlayProvider>
      <App />
    </OverlayProvider>
  );
}
```

```tsx
import { useState } from 'react';
import Button from '@mui/material/Button';
import Dialog from '@mui/material/Dialog';
import DialogTitle from '@mui/material/DialogTitle';
import DialogContent from '@mui/material/DialogContent';
import DialogActions from '@mui/material/DialogActions';

export function ConfirmDialog({ isOpen, close }) {
  const [count, setCount] = useState(0);
  return (
    <Dialog open={isOpen} onClose={close} transitionDuration={1000}>
      <DialogTitle>Are you sure you want to continue?</DialogTitle>

      <DialogContent>
        <p>count: {count}</p>
        <Button onClick={() => setCount(count + 1)}>Increase count</Button>
      </DialogContent>

      <DialogActions>
        <Button onClick={close}>No</Button>
        <Button onClick={close}>Yes</Button>
      </DialogActions>
    </Dialog>
  );
}
```

--------------------------------

### Test Opening Multiple Overlays with overlay.open

Source: https://github.com/toss/overlay-kit/blob/main/docs/src/pages/en/docs/guides/testing.mdx

Verifies that multiple overlays can be opened simultaneously and function correctly. It checks if all rendered overlay elements are present in the DOM after opening.

```tsx
it('should be able to open multiple overlays via overlay.open', async () => {
  const testContent1 = 'context-modal-test-content-1';
  const testContent2 = 'context-modal-test-content-2';
  const testContent3 = 'context-modal-test-content-3';
  const testContent4 = 'context-modal-test-content-4';

  function Component() {
    useEffect(() => {
      overlay.open(({ isOpen }) => isOpen && <p>{testContent1}</p>);
      overlay.open(({ isOpen }) => isOpen && <p>{testContent2}</p>);
      overlay.open(({ isOpen }) => isOpen && <p>{testContent3}</p>);
      overlay.open(({ isOpen }) => isOpen && <p>{testContent4}</p>);
    }, []);

    return <div>Empty</div>;
  }

  render(<Component />, { wrapper });

  await waitFor(() => {
    expect(screen.queryByText(testContent1)).toBeInTheDocument();
    expect(screen.queryByText(testContent2)).toBeInTheDocument();
    expect(screen.queryByText(testContent3)).toBeInTheDocument();
    expect(screen.queryByText(testContent4)).toBeInTheDocument();
  });
});
```

--------------------------------

### Open Overlay with Async/Await and Typed Results

Source: https://context7.com/toss/overlay-kit/llms.txt

The `overlay.openAsync()` function opens an overlay and returns a Promise that resolves with the value passed to `close()`. This is ideal for handling user confirmations or form submissions using async/await. The controller also provides a `reject` function for error handling.

```tsx
import { overlay } from 'overlay-kit';
import Dialog from '@mui/material/Dialog';
import DialogTitle from '@mui/material/DialogTitle';
import DialogActions from '@mui/material/DialogActions';
import Button from '@mui/material/Button';

// Async confirmation dialog
async function confirmDelete(itemName: string): Promise<boolean> {
  const result = await overlay.openAsync<boolean>(({ isOpen, close, unmount }) => (
    <Dialog open={isOpen} onClose={() => close(false)}>
      <DialogTitle>Delete "{itemName}"?</DialogTitle>
      <DialogActions>
        <Button onClick={() => close(false)}>Cancel</Button>
        <Button onClick={() => close(true)} color="error">Delete</Button>
      </DialogActions>
    </Dialog>
  ));

  return result;
}

// Usage with async/await
async function handleDeleteClick() {
  const confirmed = await confirmDelete('Important File');

  if (confirmed) {
    console.log('User confirmed deletion');
    // Proceed with delete operation
  } else {
    console.log('User cancelled');
  }
}

// Form submission with typed results
interface FormData {
  name: string;
  email: string;
}

async function openFormDialog(): Promise<FormData | null> {
  return overlay.openAsync<FormData | null>(({ isOpen, close }) => (
    <FormDialog
      open={isOpen}
      onSubmit={(data) => close(data)}
      onCancel={() => close(null)}
    />
  ));
}
```

--------------------------------

### Handle User Input from Confirmation Dialog (TypeScript/React)

Source: https://github.com/toss/overlay-kit/blob/main/docs/src/pages/en/api/utils/overlay-open-async.mdx

Illustrates how to handle the result returned by overlay.openAsync after a user interacts with a confirmation dialog. It checks if the result is true (confirm) or false (cancel) and logs the corresponding action.

```tsx
const result = await overlay.openAsync(({ isOpen, close, unmount }) => {
  function confirm() {
    close(true);
  }
  function cancel() {
    close(false);
  }

  return <ConfirmDialog isOpen={isOpen} confirm={confirm} close={cancel} onExit={unmount} />;
});

if (result === true) {
  console.log('User selected confirm.');
} else {
  console.log('User selected cancel.');
}

```

--------------------------------

### Create a Confirmation Dialog Component

Source: https://github.com/toss/overlay-kit/blob/main/docs/src/pages/en/docs/guides/introduction.mdx

Defines a reusable confirmation dialog component using Material-UI's Dialog. This component takes `isOpen` and `close` props to control its visibility and interaction.

```tsx
import Button from '@mui/material/Button';
import Dialog from '@mui/material/Dialog';
import DialogTitle from '@mui/material/DialogTitle';
import DialogActions from '@mui/material/DialogActions';

export function ConfirmDialog({ isOpen, close }) {
  return (
    <Dialog open={isOpen} onClose={close}>
      <DialogTitle>Are you sure you want to continue?</DialogTitle>
      <DialogActions>
        <Button onClick={close}>No</Button>
        <Button onClick={close}>Yes</Button>
      </DialogActions>
    </Dialog>
  );
}
```

--------------------------------

### Test Overlay Unmounting Order with useCurrentOverlay and useOverlayData

Source: https://github.com/toss/overlay-kit/blob/main/docs/src/pages/en/docs/guides/testing.mdx

This test verifies the correct handling of unmounting overlays in different sequences using the useCurrentOverlay and useOverlayData hooks. It ensures that the correct overlay is removed and that the visibility of other overlays is maintained as expected. Dependencies include React testing utilities and the overlay context.

```tsx
it('should handle current overlay correctly when unmounting overlays in different orders', async () => {
  const contents = {
    first: 'overlay-content-1',
    second: 'overlay-content-2',
    third: 'overlay-content-3',
    fourth: 'overlay-content-4',
  };
  let overlayIds: string[] = [];

  function Component() {
    useEffect(() => {
      overlayIds = [
        overlay.open(({ isOpen }) => isOpen && <div data-testid="overlay-1">{contents.first}</div>),
        overlay.open(({ isOpen }) => isOpen && <div data-testid="overlay-2">{contents.second}</div>),
        overlay.open(({ isOpen }) => isOpen && <div data-testid="overlay-3">{contents.third}</div>),
        overlay.open(({ isOpen }) => isOpen && <div data-testid="overlay-4">{contents.fourth}</div>),
      ];
    }, []);

    return <div>Base Component</div>;
  }
  render(<Component />, { wrapper });

  await waitFor(() => {
    expect(screen.getByTestId('overlay-1')).toBeInTheDocument();
    expect(screen.getByTestId('overlay-2')).toBeInTheDocument();
    expect(screen.getByTestId('overlay-3')).toBeInTheDocument();
    expect(screen.getByTestId('overlay-4')).toBeInTheDocument();
  });

  // Remove overlays in a specific order
  overlay.unmount(overlayIds[1]);
  await waitFor(() => {
    expect(screen.queryByTestId('overlay-2')).not.toBeInTheDocument();
    expect(screen.getByTestId('overlay-1')).toBeVisible();
    expect(screen.getByTestId('overlay-3')).toBeVisible();
    expect(screen.getByTestId('overlay-4')).toBeVisible();
  });

  overlay.unmount(overlayIds[3]);
  await waitFor(() => {
    expect(screen.queryByTestId('overlay-4')).not.toBeInTheDocument();
    expect(screen.getByTestId('overlay-1')).toBeVisible();
    expect(screen.getByTestId('overlay-3')).toBeVisible();
  });

  overlay.unmount(overlayIds[2]);
  await waitFor(() => {
    expect(screen.queryByTestId('overlay-3')).not.toBeInTheDocument();
    expect(screen.getByTestId('overlay-1')).toBeVisible();
  });

  overlay.unmount(overlayIds[0]);
  await waitFor(() => {
    expect(screen.queryByTestId(/^overlay-/)).not.toBeInTheDocument();
  });
});
```

--------------------------------

### Unmount Overlay After Animation with onExit

Source: https://github.com/toss/overlay-kit/blob/main/docs/src/pages/en/docs/more/basic.mdx

Illustrates how to properly unmount an overlay after its closing animation has finished using the `onExit` prop. This prevents abrupt removal and ensures a smooth user experience. The `unmount` function is passed to the overlay component and called within its `onExit` handler. Requires `OverlayProvider`.

```tsx
import { OverlayProvider, overlay } from 'overlay-kit';
import Button from '@mui/material/Button';
import { ConfirmDialog } from './confirm-dialog';

function App() {
  return (
    <>
      <Button
        onClick={() => {
          overlay.open(({ isOpen, close, unmount }) => {
            return <ConfirmDialog isOpen={isOpen} close={close} onExit={unmount} />;
          });
        }}
      >
        Open Confirm Dialog
      </Button>
    </>
  );
}

export function Example() {
  return (
    <OverlayProvider>
      <App />
    </OverlayProvider>
  );
}
```

```tsx
import { useState, useEffect } from 'react';
import Button from '@mui/material/Button';
import Dialog from '@mui/material/Dialog';
import DialogTitle from '@mui/material/DialogTitle';
import DialogContent from '@mui/material/DialogContent';
import DialogActions from '@mui/material/DialogActions';

export function ConfirmDialog({ isOpen, close, onExit }) {
  const [count, setCount] = useState(0);

  useEffect(() => {
    return () => onExit();
  }, []);

  return (
    <Dialog open={isOpen} onClose={close} transitionDuration={1000}>
      <DialogTitle>Are you sure you want to continue?</DialogTitle>

      <DialogContent>
        <p>count: {count}</p>
        <Button onClick={() => setCount(count + 1)}>Increase count</Button>
      </DialogContent>

      <DialogActions>
        <Button onClick={close}>No</Button>
        <Button onClick={close}>Yes</Button>
      </DialogActions>
    </Dialog>
  );
}
```

--------------------------------

### Test Overlay Closing with overlay.unmount

Source: https://github.com/toss/overlay-kit/blob/main/docs/src/pages/en/docs/guides/testing.mdx

Verifies that an overlay closes properly when the `overlay.unmount` function is called. It uses `waitFor` to handle asynchronous DOM updates and checks for the absence of the overlay element.

```tsx
it('should be able to close an open overlay using overlay.unmount', async () => {
  const overlayDialogContent = 'context-modal-overlay-dialog-content';

  function Component() {
    useEffect(() => {
      overlay.open(({ isOpen, overlayId }) => {
        return isOpen && <button onClick={() => overlay.unmount(overlayId)}>{overlayDialogContent}</button>;
      });
    }, []);

    return <div>Empty</div>;
  }

  const { user } = renderWithUser(<Component />);
  await user.click(await screen.findByRole('button', { name: overlayDialogContent }));

  await waitFor(() => {
    expect(screen.queryByRole('button', { name: overlayDialogContent })).not.toBeInTheDocument();
  });
});
```

--------------------------------

### Confirm Dialog with State and Transition Duration (TypeScript)

Source: https://github.com/toss/overlay-kit/blob/main/docs/src/pages/en/docs/guides/introduction.mdx

This is an alternative implementation of the `ConfirmDialog` component. It includes local state management (`count`) and sets a `transitionDuration` for the dialog. It also utilizes `useEffect` cleanup to call `onExit` for memory management.

```tsx
import { useState, useEffect } from 'react';
import Button from '@mui/material/Button';
import Dialog from '@mui/material/Dialog';
import DialogTitle from '@mui/material/DialogTitle';
import DialogContent from '@mui/material/DialogContent';
import DialogActions from '@mui/material/DialogActions';

export function ConfirmDialog({ isOpen, close, onExit }) {
  const [count, setCount] = useState(0);

  useEffect(() => {
    return () => onExit();
  }, []);

  return (
    <Dialog open={isOpen} onClose={close} transitionDuration={1000}>
      <DialogTitle>Are you sure you want to continue?</DialogTitle>

      <DialogContent>
        <p>count: {count}</p>
        <Button onClick={() => setCount(count + 1)}>Increase count</Button>
      </DialogContent>

      <DialogActions>
        <Button onClick={close}>No</Button>
        <Button onClick={close}>Yes</Button>
      </DialogActions>
    </Dialog>
  );
}
```

--------------------------------

### Open Overlay on API Error with ky

Source: https://github.com/toss/overlay-kit/blob/main/docs/src/pages/en/docs/more/open-outside-react.mdx

This snippet shows how to extend the 'ky' HTTP client to automatically open an overlay when an API request returns an error status (>= 400). It uses the 'overlay.open' function from 'overlay-kit' to display an 'ErrorDialog'.

```tsx
import ky from 'ky';
import { overlay } from 'overlay-kit';

const api = ky.extend({
  hooks: {
    afterResponse: [
      (_, __, response) => {
        console.log('test:: response', response);
        if (response.status >= 400) {
          overlay.open(({ isOpen, close }) => <ErrorDialog open={isOpen} onClose={close} />);
        }
      },
    ],
  },
});
```