@pop-kit/okcancel 0.0.0 → 0.1.0

package/README.md

@@ -2,277 +2,149 @@
 
 [![npm version](https://badge.fury.io/js/@pop-kit/okcancel.svg)](https://www.npmjs.com/package/@pop-kit/okcancel)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Live Demo](https://img.shields.io/badge/Live-Demo-blue?style=flat&logo=stackblitz)](https://stackblitz.com/edit/vitejs-vite-wszi61bn?file=src%2FApp.tsx)
 
-**React + TypeScript 기반의 비동기 UI 인터랙션 라이브러리 (Headless & Logic-First)**입니다.
-`confirm`, `alert` 뿐만 아니라 다양한 오버레이(Sheet, Toast 등)를 `await` 함수 호출로 제어할 수 있습니다.
+**React 기반의 UI-Agnostic 비동기 오버레이 관리자**입니다.  
+`confirm`, `alert` 로직을 비즈니스 로직에서 분리하여 `await` 한 줄로 우아하게 제어하세요.
+
+---
 
 ## ✨ 주요 특징
 
-- **Promise 기반 로직** - `await confirm()` 한 줄로 복잡한 상태 관리 대체
-- **Headless 아키텍처** - UI와 로직의 완전한 분리, Shadcn/MUI 등 어떤 스타일과도 호환
-- **DX (개발자 경험) 중심** - 자동 로딩 상태 관리, TypeScript 지원
-- **AI-Native** - Cursor, Copilot 등 AI가 코드를 작성하기 쉬운 구조
+- **UI-Agnostic (Headless)** - UI를 강제하지 않습니다. shadcn/ui, MUI, 또는 직접 만든 컴포넌트 등 무엇이든 주입하여 사용할 수 있습니다.
+- **Promise 기반 흐름** - 상태 지옥(isOpen, setOpen)에서 벗어나 `const ok = await confirm()` 코드를 통해 선형적인 로직을 작성합니다.
+- **IntelliSense 지원** - `confirm.destructive()`, `alert.success()` 등 사용자 정의 변형(Variant)에 대한 완벽한 자동완성을 지원합니다.
+- **shadcn/ui 프리셋 제공** - 별도의 패키지 설치 없이 CLI 명령어로 프로젝트에 바로 다이얼로그 프리셋을 추가할 수 있습니다.
+
+---
 
 ## 📦 설치
 
+### 1. Core 라이브러리 설치
+
 ```bash
 npm install @pop-kit/okcancel
 ```
 
-## 🎮 Live Demo
+### 2. shadcn/ui 프리셋 추가 (선택 사항)
 
-[**StackBlitz에서 바로 체험하기**](https://stackblitz.com/edit/vitejs-vite-wszi61bn?file=src%2FApp.tsx)
+가장 인기 있는 shadcn/ui 기반의 프리셋을 프로젝트에 즉시 추가할 수 있습니다.
 
-## 🚀 빠른 시작
+```bash
+npx shadcn@latest add "https://raw.githubusercontent.com/[USER]/react-okcancel/main/registry.json"
+```
 
-```tsx
-import { OkCancelProvider, useOkCancel } from 'react-okcancel';
+_설치 후 `components/ui/ok-cancel/` 폴더에 다이얼로그 컴포넌트들이 생성됩니다._
 
-function MyComponent() {
-  const { confirm, alert } = useOkCancel();
-
-  const handleDelete = async () => {
-    const confirmed = await confirm({
-      title: '삭제 확인',
-      description: '정말로 이 항목을 삭제하시겠습니까?',
-      confirmText: '삭제',
-      cancelText: '취소',
-    });
+---
 
-    if (confirmed) {
-      // 삭제 로직
-      await alert({
-        title: '완료',
-        description: '항목이 성공적으로 삭제되었습니다.',
-      });
-    }
-  };
+## 🚀 사용 가이드 (Usage)
 
-  return <button onClick={handleDelete}>항목 삭제</button>;
-}
+### 1. Provider 설정 (Setup)
+
+`OkCancelProvider`에 UI 컴포넌트를 주입하여 초기화합니다. `as const`를 사용하여 컴포넌트 맵을 정의하면 나중에 호출할 때 완벽한 자동완성(IntelliSense)이 지원됩니다.
+
+```tsx
+import { OkCancelProvider } from '@pop-kit/okcancel';
+import { ConfirmDialog, SimpleAlertDialog } from '@/components/ui/ok-cancel';
+
+// 🛠️ 컴포넌트 구성 (단일 또는 여러 스타일 조합 가능)
+const components = {
+  alert: SimpleAlertDialog, // 1. 단일 컴포넌트 주입
+  confirm: {
+    // 2. 여러 스타일(Variants) 주입
+    default: ConfirmDialog,
+    destructive: DestructiveConfirm, // confirm.destructive()로 호출 가능
+  },
+} as const;
 
 function App() {
   return (
-    <OkCancelProvider>
-      <MyComponent />
+    <OkCancelProvider components={components}>
+      <YourApp />
     </OkCancelProvider>
   );
 }
 ```
 
-## 📖 함수 설명
-
-### `confirm(options: ConfirmOptions): Promise<boolean>`
-
-확인/취소 버튼이 있는 확인 다이얼로그를 표시합니다.
+### 2. Hook 사용 (Hooks)
 
-#### 옵션
+`useOkCancel`을 사용하여 사용자 인터랙션을 기다립니다. 기본적인 호출과 미리 정의한 변형(Variant) 호출이 모두 가능합니다.
 
-| 옵션                | 타입        | 기본값   | 설명                                  |
-| ------------------- | ----------- | -------- | ------------------------------------- |
-| `title`             | `ReactNode` | -        | 다이얼로그 제목                       |
-| `description`       | `ReactNode` | -        | 다이얼로그 내용/메시지                |
-| `confirmText`       | `ReactNode` | `'확인'` | 확인 버튼 텍스트                      |
-| `cancelText`        | `ReactNode` | `'취소'` | 취소 버튼 텍스트                      |
-| `canCloseOnOverlay` | `boolean`   | `true`   | 오버레이 클릭으로 닫기 허용           |
-| `canCloseOnEsc`     | `boolean`   | `true`   | Escape 키로 닫기 허용                 |
-| `showCloseButton`   | `boolean`   | `false`  | 오른쪽 상단 X 버튼 표시               |
-| `enableAnimation`   | `boolean`   | `true`   | 다이얼로그 슬라이드 애니메이션 활성화 |
+```tsx
+import { useOkCancel } from '@pop-kit/okcancel';
 
-#### 반환값
+function MyComponent() {
+  // 정의한 components 타입을 전달하면 자동완성이 지원됩니다.
+  const { confirm, alert } = useOkCancel<typeof components>();
+
+  const handleAction = async () => {
+    // 💡 기본적인 confirm 호출
+    const ok = await confirm({
+      title: '삭제하시겠습니까?',
+      description: '이 작업은 되돌릴 수 없습니다.',
+    });
 
-- `true` 사용자가 확인 버튼을 클릭한 경우
-- `false` 사용자가 취소 버튼을 클릭하거나, Escape를 누르거나, 오버레이를 클릭한 경우
+    if (ok) {
+      // 💡 미리 정의한 'destructive' 변형 호출 (IntelliSense 지원)
+      const forceDelete = await confirm.destructive({
+        title: '정말 강제로 삭제할까요?',
+        confirmText: '강제 삭제',
+      });
 
-#### 예제
+      if (forceDelete) {
+        await deleteItem();
+        await alert({ title: '삭제 성공!' });
+      }
+    }
+  };
 
-```tsx
-const result = await confirm({
-  title: '저장 확인',
-  description: (
-    <div>
-      <p>변경사항을 저장하시겠습니까?</p>
-      <p>
-        <strong>주의:</strong> 이 작업은 되돌릴 수 없습니다.
-      </p>
-    </div>
-  ),
-  confirmText: '저장',
-  cancelText: '취소',
-  canCloseOnOverlay: false, // 실수로 닫히는 것 방지
-  showCloseButton: true, // X 버튼 표시
-  enableAnimation: false, // 애니메이션 비활성화
-});
-
-if (result) {
-  console.log('사용자가 저장을 확인했습니다');
-} else {
-  console.log('사용자가 저장을 취소했습니다');
+  return <button onClick={handleAction}>삭제</button>;
 }
 ```
 
-### `alert(options: AlertOptions): Promise<void>`
-
-확인 버튼만 있는 알림 다이얼로그를 표시합니다.
-
-#### 옵션
-
-| 옵션                | 타입        | 기본값   | 설명                                  |
-| ------------------- | ----------- | -------- | ------------------------------------- |
-| `title`             | `ReactNode` | -        | 다이얼로그 제목                       |
-| `description`       | `ReactNode` | -        | 다이얼로그 내용/메시지                |
-| `confirmText`       | `ReactNode` | `'확인'` | 확인 버튼 텍스트                      |
-| `canCloseOnOverlay` | `boolean`   | `true`   | 오버레이 클릭으로 닫기 허용           |
-| `canCloseOnEsc`     | `boolean`   | `true`   | Escape 키로 닫기 허용                 |
-| `showCloseButton`   | `boolean`   | `false`  | 오른쪽 상단 X 버튼 표시               |
-| `enableAnimation`   | `boolean`   | `true`   | 다이얼로그 슬라이드 애니메이션 활성화 |
+### 3. 커스텀 컴포넌트 만들기 (Custom Components)
 
-#### 반환값
+Headless 라이브러리이므로 UI는 자유롭게 정의할 수 있습니다. 단, 라이브러리가 `await` 로직을 제어하기 위해 **반드시 제공된 Props 타입(`ConfirmDialogProps`, `AlertDialogProps`)을 사용해야 합니다.**
 
-- `undefined` 다이얼로그가 닫힐 때 (닫힌 방법과 관계없이)
+#### 확인 다이얼로그 (`ConfirmDialogProps`)
 
-#### 예제
+`onConfirm`과 `onCancel`을 모두 받아 `boolean` 결과를 반환합니다.
 
 ```tsx
-await alert({
-  title: '성공',
-  description: '파일이 성공적으로 업로드되었습니다.',
-  confirmText: '확인',
-});
+import type { ConfirmDialogProps } from '@pop-kit/okcancel';
 
-console.log('사용자가 알림을 확인했습니다');
-```
-
-## 🎨 커스터마이징
-
-CSS 변수를 재정의하여 모양을 커스터마이징할 수 있습니다:
-
-```css
-:root {
-  /* 다이얼로그 */
-  --okcancel-dialog-bg: #fff;
-  --okcancel-dialog-border-radius: 8px;
-  --okcancel-dialog-shadow: 0 20px 25px -5px rgb(0 0 0 / 10%), 0 8px 10px -6px rgb(0 0 0 / 10%);
-  --okcancel-dialog-max-width: none;
-  --okcancel-dialog-min-width: auto;
-  --okcancel-dialog-max-height: none;
-  --okcancel-dialog-min-height: auto;
-  --okcancel-dialog-width: 500px;
-  --okcancel-dialog-height: max-content;
-  --okcancel-dialog-padding: 16px 24px;
-  --okcancel-dialog-border: none;
-
-  /* 다이얼로그 콘텐츠 */
-  --okcancel-content-padding: 0;
-  --okcancel-content-gap: 8px;
-  --okcancel-content-flex-direction: column;
-  --okcancel-content-justify-content: center;
-  --okcancel-content-align-items: normal;
-  --okcancel-content-height: auto;
-  --okcancel-content-max-height: none;
-  --okcancel-content-min-height: 100px;
-
-  /* 제목 */
-  --okcancel-title-font-size: 20px;
-  --okcancel-title-color: #222;
-  --okcancel-title-font-weight: 600;
-
-  /* 설명 */
-  --okcancel-description-font-size: 16px;
-  --okcancel-description-color: #8e8e8e;
-  --okcancel-description-font-weight: 400;
-
-  /* 버튼 컨테이너 */
-  --okcancel-btn-box-padding: 10px 0;
-  --okcancel-btn-box-gap: 12px;
-  --okcancel-btn-box-flex-direction: row;
-  --okcancel-btn-box-justify-content: flex-end;
-  --okcancel-btn-box-align-items: center;
-  --okcancel-btn-box-height: auto;
-
-  /* 버튼 */
-  --okcancel-button-padding: 8px 16px;
-  --okcancel-button-border-radius: 6px;
-  --okcancel-button-width: 100px;
-  --okcancel-button-height: 40px;
-  --okcancel-button-max-width: none;
-  --okcancel-button-min-width: auto;
-  --okcancel-button-border: none;
-  --okcancel-button-box-shadow: none;
-  --okcancel-button-font-size: 16px;
-  --okcancel-button-font-weight: 500;
-  --okcancel-button-text-align: center;
-  --okcancel-button-flex: 0 1 auto;
-
-  /* 주 버튼 (확인) */
-  --okcancel-button-primary-bg: #2c89e5;
-  --okcancel-button-primary-color: #fff;
-  --okcancel-button-primary-border: none;
-
-  /* 보조 버튼 (취소) */
-  --okcancel-button-secondary-bg: transparent;
-  --okcancel-button-secondary-color: #222;
-  --okcancel-button-secondary-border: 1px solid #d4d4d4;
-
-  /* 오버레이 */
-  --okcancel-overlay-bg: rgb(0 0 0 / 50%);
-  --okcancel-z-index: 1000;
+export function MyConfirm({ title, description, onConfirm, onCancel }: ConfirmDialogProps) {
+  return (
+    <div className="modal">
+      <h2>{title}</h2>
+      <p>{description}</p>
+      <button onClick={onCancel}>취소</button>
+      <button onClick={onConfirm}>확인</button>
+    </div>
+  );
 }
 ```
 
-### 반응형 커스터마이징
+#### 알림 다이얼로그 (`AlertDialogProps`)
 
-모바일에서는 자동으로 다음과 같이 조정됩니다:
+`onConfirm`만 받아 작업을 완료하고 `void`를 반환합니다.
 
-- 다이얼로그 너비: 화면의 85%
-- 버튼 간격: 더 넓게 조정
-- 버튼: 전체 너비로 확장
-
-모바일 스타일을 커스터마이징하려면:
+```tsx
+import type { AlertDialogProps } from '@pop-kit/okcancel';
 
-```css
-@media (width < 640px) {
-  :root {
-    --okcancel-dialog-width: 90%; /* 모바일 너비 조정 */
-    --okcancel-btn-box-gap: 16px; /* 버튼 간격 조정 */
-    --okcancel-button-flex: 1; /* 버튼 전체 너비 */
-    --okcancel-btn-box-flex-direction: column; /* 버튼 세로 배치 */
-  }
+export function MyAlert({ title, description, onConfirm }: AlertDialogProps) {
+  return (
+    <div className="alert">
+      <h2>{title}</h2>
+      <p>{description}</p>
+      <button onClick={onConfirm}>닫기</button>
+    </div>
+  );
 }
 ```
 
-## ♿ 접근성 기능
+---
 
-- **ARIA 역할**: 적절한 `dialog` 및 `alertdialog` 역할
-- **포커스 관리**: 확인 버튼에 자동 포커스, 포커스 트래핑
-- **키보드 내비게이션**:
-  - `Tab` / `Shift+Tab`으로 버튼 간 이동
-  - `Enter` / `Space`로 포커스된 버튼 활성화
-  - `Escape`로 다이얼로그 닫기 (활성화된 경우)
-- **스크린 리더 지원**: 적절한 라벨링 및 알림
+## ⚖️ License
 
-## 🔧 고급 사용법
-
-### JSX를 사용한 커스텀 콘텐츠
-
-```tsx
-const result = await confirm({
-  title: '파일 삭제',
-  description: (
-    <div>
-      <p>다음 파일들을 삭제하시겠습니까?</p>
-      <ul>
-        <li>document.pdf</li>
-        <li>image.jpg</li>
-        <li>data.json</li>
-      </ul>
-      <p>
-        <strong>경고:</strong> 이 작업은 되돌릴 수 없습니다.
-      </p>
-    </div>
-  ),
-  confirmText: '삭제',
-  cancelText: '취소',
-});
-```
+MIT License. 자유롭게 사용하고 기여해 주세요!