@ilokesto/overlay 1.0.0

package/README.ko.md

@@ -0,0 +1,143 @@
+# @ilokesto/overlay
+
+[English](./README.md) | **한국어**
+
+`@ilokesto/store` 위에 얹는 작은 React overlay runtime입니다.
+
+이 패키지는 provider-scoped overlay core, built-in host, item lifecycle 관리, adapter 주입 구조를 제공합니다. modal이나 toast 의미론은 의도적으로 코어에 넣지 않아서, 상위 패키지가 같은 runtime 위에서 자신만의 동작을 구현할 수 있게 되어 있습니다.
+
+## Features
+
+- 전역 싱글턴이 아닌 provider-scoped overlay runtime
+- adapter registry를 통해 overlay item을 렌더링하는 built-in host
+- 같은 store lifecycle 위에서 동기/비동기 overlay 열기 지원
+- runtime core와 공용 contract의 명확한 분리
+- overlay를 열고 닫고 제거하고 관찰하는 작은 공개 API
+
+## Installation
+
+```bash
+pnpm add @ilokesto/overlay react
+```
+
+또는
+
+```bash
+npm install @ilokesto/overlay react
+```
+
+## Basic Usage
+
+```tsx
+import { OverlayProvider, useOverlay, type OverlayAdapterMap } from '@ilokesto/overlay';
+
+const adapters: OverlayAdapterMap = {
+  modal: ({ isOpen, close, title }) => {
+    if (!isOpen) {
+      return null;
+    }
+
+    return (
+      <div role="dialog" aria-modal="true">
+        <h1>{String(title)}</h1>
+        <button onClick={() => close(true)}>Confirm</button>
+      </div>
+    );
+  },
+};
+
+function ExampleButton() {
+  const { display } = useOverlay();
+
+  const handleClick = async () => {
+    const result = await display<boolean>({
+      type: 'modal',
+      props: { title: 'Delete this item?' },
+    });
+
+    console.log(result);
+  };
+
+  return <button onClick={handleClick}>Open</button>;
+}
+
+export function App() {
+  return (
+    <OverlayProvider adapters={adapters}>
+      <ExampleButton />
+    </OverlayProvider>
+  );
+}
+```
+
+## Source Layout
+
+```text
+src/
+  core/
+    createOverlayStore.ts
+    OverlayProvider.tsx
+    OverlayHost.tsx
+    useOverlay.ts
+    useOverlayItems.ts
+  contracts/
+    adapter.ts
+    overlay.ts
+  index.ts
+```
+
+## Responsibilities
+
+### `src/core`
+
+- `createOverlayStore.ts` → provider 단위 overlay store를 만들고 `open`, `close`, `remove`, `clear` 수명주기를 관리합니다
+- `OverlayProvider.tsx` → store를 만들거나 주입받아 context로 노출하고 built-in `OverlayHost`를 마운트합니다
+- `OverlayHost.tsx` → 현재 overlay item 목록을 읽고 각 item을 `adapters[item.type]`에 위임해 렌더링합니다
+- `useOverlay.ts` → overlay를 열고 닫고 제거하는 명령형 API를 제공합니다
+- `useOverlayItems.ts` → `useSyncExternalStore`로 현재 overlay item 목록을 구독합니다
+
+### `src/contracts`
+
+- `adapter.ts` → `OverlayRenderProps`, `OverlayAdapterComponent`, `OverlayAdapterMap` 같은 adapter 렌더링 계약을 정의합니다
+- `overlay.ts` → `OverlayItem`, `OverlayStoreApi`, `DisplayOptions`, `OverlayProviderProps` 같은 overlay runtime 계약을 정의합니다
+
+### `src/index.ts`
+
+- `core/*`의 runtime API를 다시 export합니다
+- `contracts/*`의 공용 타입을 다시 export합니다
+
+## Dependency Direction
+
+- `core/*` 는 `contracts/*` 에 의존합니다
+- `contracts/overlay.ts` 는 `contracts/adapter.ts` 에 의존합니다
+- `contracts/adapter.ts` 는 runtime 코드에 의존하지 않습니다
+- modal이나 toast 같은 adapter 패키지는 `@ilokesto/overlay` 에 의존해야 합니다
+- `@ilokesto/overlay` 는 modal/toast 구현을 직접 import하면 안 됩니다
+
+한 줄로 말하면, 코어는 lifecycle과 hosting을 담당하고 adapter 패키지는 의미론과 표현을 담당합니다.
+
+## Adapter Packages
+
+이 패키지는 의도적으로 generic하게 설계되어 있습니다.
+
+- modal 패키지는 overlay runtime 위에 modal adapter를 주입해서 사용할 수 있습니다
+- toast 패키지도 같은 runtime 위에 toast adapter를 주입해서 사용할 수 있습니다
+- focus trap, scroll lock, backdrop 동작, deduplication, timer, animation 같은 정책은 overlay core가 아니라 adapter 레이어에 있어야 합니다
+
+## Exports
+
+- `@ilokesto/overlay` → `createOverlayStore`, `OverlayProvider`, `OverlayHost`, `useOverlay`, `useOverlayItems`
+- `@ilokesto/overlay` 타입 → `src/contracts/adapter.ts`, `src/contracts/overlay.ts`, `UseOverlayReturn`에서 다시 export된 타입
+
+## Development
+
+```bash
+pnpm install
+pnpm run build
+```
+
+빌드 결과물은 `dist` 디렉터리에 생성됩니다.
+
+## License
+
+MIT

package/README.md

@@ -0,0 +1,143 @@
+# @ilokesto/overlay
+
+**English** | [한국어](./README.ko.md)
+
+A small React overlay runtime built on top of `@ilokesto/store`.
+
+This package provides a provider-scoped overlay core with a built-in host, item lifecycle management, and adapter injection. It is intentionally headless about modal or toast semantics so higher-level packages can build on top of the same runtime without leaking behavior into the core.
+
+## Features
+
+- Provider-scoped overlay runtime instead of a global singleton
+- Built-in host that renders overlay items through an adapter registry
+- Sync and async overlay opening through the same store lifecycle
+- Clean separation between runtime core and shared contracts
+- A small public API for opening, closing, removing, and observing overlays
+
+## Installation
+
+```bash
+pnpm add @ilokesto/overlay react
+```
+
+or
+
+```bash
+npm install @ilokesto/overlay react
+```
+
+## Basic Usage
+
+```tsx
+import { OverlayProvider, useOverlay, type OverlayAdapterMap } from '@ilokesto/overlay';
+
+const adapters: OverlayAdapterMap = {
+  modal: ({ isOpen, close, title }) => {
+    if (!isOpen) {
+      return null;
+    }
+
+    return (
+      <div role="dialog" aria-modal="true">
+        <h1>{String(title)}</h1>
+        <button onClick={() => close(true)}>Confirm</button>
+      </div>
+    );
+  },
+};
+
+function ExampleButton() {
+  const { display } = useOverlay();
+
+  const handleClick = async () => {
+    const result = await display<boolean>({
+      type: 'modal',
+      props: { title: 'Delete this item?' },
+    });
+
+    console.log(result);
+  };
+
+  return <button onClick={handleClick}>Open</button>;
+}
+
+export function App() {
+  return (
+    <OverlayProvider adapters={adapters}>
+      <ExampleButton />
+    </OverlayProvider>
+  );
+}
+```
+
+## Source Layout
+
+```text
+src/
+  core/
+    createOverlayStore.ts
+    OverlayProvider.tsx
+    OverlayHost.tsx
+    useOverlay.ts
+    useOverlayItems.ts
+  contracts/
+    adapter.ts
+    overlay.ts
+  index.ts
+```
+
+## Responsibilities
+
+### `src/core`
+
+- `createOverlayStore.ts` → creates the provider-scoped overlay store and manages `open`, `close`, `remove`, and `clear`
+- `OverlayProvider.tsx` → creates or receives a store, exposes it through context, and mounts the built-in `OverlayHost`
+- `OverlayHost.tsx` → reads the current overlay items and dispatches each item to `adapters[item.type]`
+- `useOverlay.ts` → exposes the command API for opening and dismissing overlays
+- `useOverlayItems.ts` → subscribes to the current overlay item list with `useSyncExternalStore`
+
+### `src/contracts`
+
+- `adapter.ts` → adapter-facing rendering contracts such as `OverlayRenderProps`, `OverlayAdapterComponent`, and `OverlayAdapterMap`
+- `overlay.ts` → overlay runtime contracts such as `OverlayItem`, `OverlayStoreApi`, `DisplayOptions`, and `OverlayProviderProps`
+
+### `src/index.ts`
+
+- Re-exports the runtime APIs from `core/*`
+- Re-exports shared contract types from `contracts/*`
+
+## Dependency Direction
+
+- `core/*` depends on `contracts/*`
+- `contracts/overlay.ts` depends on `contracts/adapter.ts`
+- `contracts/adapter.ts` does not depend on runtime code
+- Adapter packages such as modal or toast should depend on `@ilokesto/overlay`
+- `@ilokesto/overlay` should not import modal or toast implementations directly
+
+In short, the core owns lifecycle and hosting, while adapter packages own semantics and presentation.
+
+## Adapter Packages
+
+This package is intentionally generic.
+
+- A modal package can use the overlay runtime and inject modal adapters
+- A toast package can use the same runtime and inject toast adapters
+- Policies such as focus trapping, scroll lock, backdrop behavior, deduplication, timers, and animations belong in the adapter layer, not in the overlay core
+
+## Exports
+
+- `@ilokesto/overlay` → `createOverlayStore`, `OverlayProvider`, `OverlayHost`, `useOverlay`, `useOverlayItems`
+- `@ilokesto/overlay` types → contracts from `src/contracts/adapter.ts`, `src/contracts/overlay.ts`, and `UseOverlayReturn`
+
+## Development
+
+```bash
+pnpm install
+pnpm run build
+```
+
+Build outputs are generated in the `dist` directory.
+
+## License
+
+MIT

package/dist/contracts/adapter.d.ts

@@ -0,0 +1,10 @@
+import type { ComponentType } from "react";
+export interface OverlayRenderProps<TResult = unknown> {
+    readonly id: string;
+    readonly isOpen: boolean;
+    readonly status: "open" | "closing";
+    readonly close: (result?: TResult) => void;
+    readonly remove: () => void;
+}
+export type OverlayAdapterComponent<TResult = unknown> = ComponentType<OverlayRenderProps<TResult> & Record<string, unknown>>;
+export type OverlayAdapterMap = Readonly<Record<string, OverlayAdapterComponent>>;

package/dist/contracts/adapter.js

@@ -0,0 +1 @@
+export {};

package/dist/contracts/overlay.d.ts

@@ -0,0 +1,37 @@
+import type { ReactNode } from "react";
+import type { OverlayAdapterMap } from "./adapter";
+export type OverlayId = string;
+export type OverlayStatus = "open" | "closing";
+export interface OverlayItem {
+    readonly id: OverlayId;
+    readonly type: string;
+    readonly props: Readonly<Record<string, unknown>>;
+    readonly status: OverlayStatus;
+    readonly createdAt: number;
+}
+export interface OverlayState {
+    readonly items: ReadonlyArray<OverlayItem>;
+}
+export interface DisplayOptions {
+    readonly id?: OverlayId;
+    readonly type: string;
+    readonly props?: Record<string, unknown>;
+}
+export interface OverlayRequest<TResult = unknown> {
+    readonly id: OverlayId;
+    readonly promise: Promise<TResult | undefined>;
+}
+export interface OverlayStoreApi {
+    open: <TResult = unknown>(options: DisplayOptions) => OverlayRequest<TResult>;
+    close: (id: OverlayId, result?: unknown) => void;
+    remove: (id?: OverlayId) => void;
+    clear: () => void;
+    subscribe: (listener: () => void) => () => void;
+    getSnapshot: () => ReadonlyArray<OverlayItem>;
+    getInitialSnapshot: () => ReadonlyArray<OverlayItem>;
+}
+export interface OverlayProviderProps {
+    readonly adapters: OverlayAdapterMap;
+    readonly children: ReactNode;
+    readonly store?: OverlayStoreApi;
+}

package/dist/contracts/overlay.js

@@ -0,0 +1 @@
+export {};

package/dist/core/OverlayHost.d.ts

@@ -0,0 +1 @@
+export declare function OverlayHost(): import("react/jsx-runtime").JSX.Element;

package/dist/core/OverlayHost.js

@@ -0,0 +1,29 @@
+import { jsx as _jsx, Fragment as _Fragment } from "react/jsx-runtime";
+import { useCallback } from "react";
+import { useOverlayContext } from "./OverlayProvider";
+import { useOverlayItems } from "./useOverlayItems";
+function OverlayItemRenderer({ item }) {
+    const { store, adapters } = useOverlayContext();
+    const Adapter = adapters[item.type];
+    const close = useCallback((result) => {
+        store.close(item.id, result);
+    }, [item.id, store]);
+    const remove = useCallback(() => {
+        store.remove(item.id);
+    }, [item.id, store]);
+    if (!Adapter) {
+        return null;
+    }
+    const renderProps = {
+        id: item.id,
+        isOpen: item.status === "open",
+        status: item.status,
+        close,
+        remove,
+    };
+    return _jsx(Adapter, { ...renderProps, ...item.props });
+}
+export function OverlayHost() {
+    const items = useOverlayItems();
+    return (_jsx(_Fragment, { children: items.map((item) => (_jsx(OverlayItemRenderer, { item: item }, item.id))) }));
+}

package/dist/core/OverlayProvider.d.ts

@@ -0,0 +1,9 @@
+import type { OverlayAdapterMap } from "../contracts/adapter";
+import type { OverlayProviderProps, OverlayStoreApi } from "../contracts/overlay";
+interface OverlayContextValue {
+    readonly store: OverlayStoreApi;
+    readonly adapters: OverlayAdapterMap;
+}
+export declare function useOverlayContext(): OverlayContextValue;
+export declare function OverlayProvider({ adapters, children, store: storeProp, }: OverlayProviderProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/core/OverlayProvider.js

@@ -0,0 +1,17 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { createContext, useContext, useMemo } from "react";
+import { createOverlayStore } from "./createOverlayStore";
+import { OverlayHost } from "./OverlayHost";
+const OverlayContext = createContext(null);
+export function useOverlayContext() {
+    const context = useContext(OverlayContext);
+    if (context === null) {
+        throw new Error("useOverlayContext must be used within an <OverlayProvider>.");
+    }
+    return context;
+}
+export function OverlayProvider({ adapters, children, store: storeProp, }) {
+    const store = useMemo(() => storeProp ?? createOverlayStore(), [storeProp]);
+    const value = useMemo(() => ({ store, adapters }), [store, adapters]);
+    return (_jsxs(OverlayContext.Provider, { value: value, children: [children, _jsx(OverlayHost, {})] }));
+}

package/dist/core/createOverlayStore.d.ts

@@ -0,0 +1,2 @@
+import type { OverlayStoreApi } from "../contracts/overlay";
+export declare function createOverlayStore(): OverlayStoreApi;

package/dist/core/createOverlayStore.js

@@ -0,0 +1,102 @@
+import { Store } from "@ilokesto/store";
+function createOverlayItem(options, id) {
+    return {
+        id,
+        type: options.type,
+        props: options.props ?? {},
+        status: "open",
+        createdAt: Date.now(),
+    };
+}
+export function createOverlayStore() {
+    const store = new Store({ items: [] });
+    const pendingResolvers = new Map();
+    let counter = 0;
+    function nextId() {
+        counter += 1;
+        return `overlay-${counter}-${Date.now()}`;
+    }
+    function settle(id, value) {
+        const resolver = pendingResolvers.get(id);
+        if (!resolver) {
+            return;
+        }
+        pendingResolvers.delete(id);
+        resolver(value);
+    }
+    function open(options) {
+        const id = options.id ?? nextId();
+        const item = createOverlayItem(options, id);
+        const promise = new Promise((resolve) => {
+            pendingResolvers.set(id, resolve);
+        });
+        store.setState((prev) => ({
+            ...prev,
+            items: [...prev.items, item],
+        }));
+        return { id, promise };
+    }
+    function close(id, result) {
+        let shouldResolve = false;
+        store.setState((prev) => ({
+            ...prev,
+            items: prev.items.map((item) => {
+                if (item.id !== id || item.status === "closing") {
+                    return item;
+                }
+                shouldResolve = true;
+                return {
+                    ...item,
+                    status: "closing",
+                };
+            }),
+        }));
+        if (shouldResolve) {
+            settle(id, result);
+        }
+    }
+    function remove(id) {
+        const targetId = id ?? store.getState().items.at(-1)?.id;
+        if (!targetId) {
+            return;
+        }
+        const targetItem = store.getState().items.find((item) => item.id === targetId);
+        if (!targetItem) {
+            return;
+        }
+        if (targetItem.status !== "closing") {
+            settle(targetId, undefined);
+        }
+        store.setState((prev) => ({
+            ...prev,
+            items: prev.items.filter((item) => item.id !== targetId),
+        }));
+    }
+    function clear() {
+        for (const item of store.getState().items) {
+            settle(item.id, undefined);
+        }
+        store.setState((prev) => ({
+            ...prev,
+            items: [],
+        }));
+    }
+    function subscribe(listener) {
+        return store.subscribe(listener);
+    }
+    function getSnapshot() {
+        return store.getState().items;
+    }
+    function getInitialSnapshot() {
+        return store.getInitialState().items;
+    }
+    return {
+        open,
+        close,
+        remove,
+        clear,
+        subscribe,
+        getSnapshot,
+        getInitialSnapshot,
+    };
+}

package/dist/core/useOverlay.d.ts

@@ -0,0 +1,9 @@
+import type { DisplayOptions, OverlayId } from "../contracts/overlay";
+export interface UseOverlayReturn {
+    readonly display: <TResult = unknown>(options: DisplayOptions) => Promise<TResult | undefined>;
+    readonly open: (options: DisplayOptions) => OverlayId;
+    readonly close: (id: OverlayId, result?: unknown) => void;
+    readonly remove: (id?: OverlayId) => void;
+    readonly clear: () => void;
+}
+export declare function useOverlay(): UseOverlayReturn;

package/dist/core/useOverlay.js

@@ -0,0 +1,23 @@
+import { useCallback } from "react";
+import { useOverlayContext } from "./OverlayProvider";
+export function useOverlay() {
+    const { store } = useOverlayContext();
+    const display = useCallback((options) => {
+        const { promise } = store.open(options);
+        return promise;
+    }, [store]);
+    const open = useCallback((options) => {
+        const { id } = store.open(options);
+        return id;
+    }, [store]);
+    const close = useCallback((id, result) => {
+        store.close(id, result);
+    }, [store]);
+    const remove = useCallback((id) => {
+        store.remove(id);
+    }, [store]);
+    const clear = useCallback(() => {
+        store.clear();
+    }, [store]);
+    return { display, open, close, remove, clear };
+}

package/dist/core/useOverlayItems.d.ts

@@ -0,0 +1,2 @@
+import type { OverlayItem } from "../contracts/overlay";
+export declare function useOverlayItems(): ReadonlyArray<OverlayItem>;

package/dist/core/useOverlayItems.js

@@ -0,0 +1,6 @@
+import { useSyncExternalStore } from "react";
+import { useOverlayContext } from "./OverlayProvider";
+export function useOverlayItems() {
+    const { store } = useOverlayContext();
+    return useSyncExternalStore(store.subscribe, store.getSnapshot, store.getInitialSnapshot);
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { createOverlayStore } from "./core/createOverlayStore";
+export { OverlayProvider } from "./core/OverlayProvider";
+export { OverlayHost } from "./core/OverlayHost";
+export { useOverlay } from "./core/useOverlay";
+export { useOverlayItems } from "./core/useOverlayItems";
+export type { OverlayAdapterComponent, OverlayAdapterMap, OverlayRenderProps, } from "./contracts/adapter";
+export type { DisplayOptions, OverlayId, OverlayItem, OverlayProviderProps, OverlayRequest, OverlayState, OverlayStatus, OverlayStoreApi, } from "./contracts/overlay";
+export type { UseOverlayReturn } from "./core/useOverlay";

package/dist/index.js

@@ -0,0 +1,5 @@
+export { createOverlayStore } from "./core/createOverlayStore";
+export { OverlayProvider } from "./core/OverlayProvider";
+export { OverlayHost } from "./core/OverlayHost";
+export { useOverlay } from "./core/useOverlay";
+export { useOverlayItems } from "./core/useOverlayItems";

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@ilokesto/overlay",
+  "version": "1.0.0",
+  "scripts": {
+    "build": "rm -rf dist && tsc"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ilokesto/overlay"
+  },
+  "homepage": "https://ilokesto.ayden94.com/en/overlay",
+  "sideEffects": false,
+  "types": "dist/index.d.ts",
+  "module": "dist/index.js",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "overlay",
+    "react",
+    "modal",
+    "provider",
+    "hooks"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "author": "Jeong Jinho <wpfekdml@me.com>",
+  "license": "MIT",
+  "dependencies": {
+    "@ilokesto/store": "1.1.1"
+  },
+  "peerDependencies": {
+    "react": "18.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.1",
+    "@types/react": "^19.1.6",
+    "typescript": "^6.0.2"
+  }
+}