{"id":14243204,"url":"https://github.com/toss/overlay-kit","last_synced_at":"2025-04-13T17:26:51.683Z","repository":{"id":246359334,"uuid":"804804220","full_name":"toss/overlay-kit","owner":"toss","description":"A library for handling overlays more easily in React.","archived":false,"fork":false,"pushed_at":"2025-04-01T01:52:26.000Z","size":4441,"stargazers_count":436,"open_issues_count":12,"forks_count":44,"subscribers_count":8,"default_branch":"main","last_synced_at":"2025-04-06T15:01:35.364Z","etag":null,"topics":["overlay","react"],"latest_commit_sha":null,"homepage":"https://overlay-kit.slash.page","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/toss.png","metadata":{"files":{"readme":"README-ko_kr.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-05-23T09:53:47.000Z","updated_at":"2025-04-05T06:32:21.000Z","dependencies_parsed_at":null,"dependency_job_id":"53fae5a5-754b-41d2-b180-fe65ef32c058","html_url":"https://github.com/toss/overlay-kit","commit_stats":{"total_commits":82,"total_committers":17,"mean_commits":4.823529411764706,"dds":0.5609756097560976,"last_synced_commit":"a3836f0b4e49d59a1fb06aa7af205d07e2b998bb"},"previous_names":["toss/overlay-kit"],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toss%2Foverlay-kit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toss%2Foverlay-kit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toss%2Foverlay-kit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toss%2Foverlay-kit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/toss","download_url":"https://codeload.github.com/toss/overlay-kit/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248751720,"owners_count":21155941,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["overlay","react"],"created_at":"2024-08-21T13:01:15.567Z","updated_at":"2025-04-13T17:26:51.657Z","avatar_url":"https://github.com/toss.png","language":"TypeScript","readme":"![](./docs/public/og.png)\n\n# overlay-kit \u0026middot; [![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/toss/overlay-kit/blob/main/LICENSE) [![codecov](https://codecov.io/gh/toss/overlay-kit/graph/badge.svg?token=JBEAQTL7XK)](https://codecov.io/gh/toss/overlay-kit)\n\n[English](https://github.com/toss/overlay-kit/blob/main/README.md) | 한국어\n\noverlay-kit은 React에서 모달, 팝업, 다이얼로그 같은 오버레이를 선언적으로 관리하기 위한 라이브러리예요.\n\n복잡한 상태 관리나 불필요한 이벤트 핸들링 없이, 효율적으로 오버레이를 구현할 수 있어요.\n\n```sh\nnpm install overlay-kit\n```\n\n## 예제\n\n### 간단한 오버레이 열기\n\n`overlay.open`을 사용하면 오버레이를 간단하게 열고 닫을 수 있어요.\n\n```tsx\nimport { overlay } from 'overlay-kit';\n\n\u003cButton\n  onClick={() =\u003e {\n    overlay.open(({ isOpen, close, unmount }) =\u003e (\n      \u003cDialog open={isOpen} onClose={close} onExit={unmount} /\u003e\n    ))\n  }}\n\u003e\n  Open\n\u003c/Button\u003e\n```\n\n### 비동기 오버레이 열기\n\n`overlay.openAsync`를 사용하면 오버레이의 결과를 `Promise`로 처리할 수 있어요.\n\n```tsx\nimport { overlay } from 'overlay-kit';\n\n\u003cButton\n  onClick={async () =\u003e {\n    const result = await overlay.openAsync\u003cboolean\u003e(({ isOpen, close }) =\u003e (\n      \u003cDialog\n        open={isOpen}\n        onConfirm={() =\u003e close(true)}\n        onClose={() =\u003e close(false)}\n        onExit={unmount}\n      /\u003e\n    ))\n  }}\n\u003e\n  Open\n\u003c/Button\u003e\n```\n\n## overlay-kit을 사용하는 이유\n\n### 기존 오버레이 관리의 문제점\n\n1. 상태 관리의 복잡성\n   - useState나 전역 상태를 사용해 직접 오버레이 상태를 관리해야 했어요.\n   - 상태 관리와 UI 로직이 섞여 코드가 복잡해지고 가독성이 떨어졌어요.\n2. 이벤트 핸들링의 반복\n   - 열기, 닫기, 결과 반환 같은 이벤트 핸들링 코드를 반복해서 작성해야 했어요.\n   - 이는 중복 코드를 유발하고 개발 경험을 저하시키는 주요 원인이 되었어요.\n3. 재사용성 부족\n   - 오버레이에서 값을 반환하려면 callback 함수 등으로 UI와 로직이 강하게 결합되었어요.\n   - 이로 인해 컴포넌트를 재사용하기 어려웠어요.\n\n### overlay-kit의 목표\n\n1. React 철학을 따르는 설계\n   - React는 선언적인 코드를 지향해요.\n   - overlay-kit은 오버레이를 선언적으로 관리할 수 있게 도와줘요.\n2. 개발 생산성 향상\n   - 상태 관리와 이벤트 핸들링을 캡슐화해, 개발자는 UI와 비즈니스 로직에만 집중할 수 있어요.\n3. 확장성과 재사용성 강화\n   - UI와 동작을 분리하고, Promise를 반환하는 방식으로 오버레이의 재사용성을 높였어요.\n\n## License\n\nMIT © Viva Republica, Inc. 자세한 내용은 [LICENSE](https://github.com/toss/overlay-kit/blob/main/LICENSE)를 참고하세요.\n\n\u003ca title=\"Toss\" href=\"https://toss.im\"\u003e\n  \u003cpicture\u003e\n    \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://static.toss.im/logos/png/4x/logo-toss-reverse.png\"\u003e\n    \u003cimg alt=\"Toss\" src=\"https://static.toss.im/logos/png/4x/logo-toss.png\" width=\"100\"\u003e\n  \u003c/picture\u003e\n\u003c/a\u003e\n","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftoss%2Foverlay-kit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftoss%2Foverlay-kit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftoss%2Foverlay-kit/lists"}