react-confirm-lite 1.2.5 → 1.3.0

package/README.md

@@ -1,151 +1,243 @@
-# react-confirm-lite
-
-**A lightweight, promise-based confirm dialog for React with built-in styling**
-
-✨ **Features:**
-- Promise-based API like window.confirm
-- Built-in styling with multiple color schemes
-- Zero dependencies
-- Fully customizable
-- TypeScript support
-- Queue system for multiple dialogs
-- Works with Next.js App Router (no 'use client' needed)
-- Automatic CSS injection (no separate imports needed)
----
-
-## Recommendations
-- Always use the latest version for bug fixes and improvements
-- If you face any issues, please report them on [GitHub](https://github.com/SaadNasir-git/react-confirm-lite/issues)
-
-![react-confirm-lite sample](https://res.cloudinary.com/dhcqn5bmq/image/upload/v1766778602/Screencastfrom2025-12-2700-42-14-ezgif.com-optimize_od1ht2.gif)
+# React Confirm Lite ✨
 
-## Quick Comparison
+**A lightweight, promise-based confirm dialog for React, designed to be as easy to use as react-toastify, while remaining fully customizable.**
 
-| Feature | react-confirm-lite | react-confirm | react-confirm-toast |
-|---------|-------------------|---------------|---------------------|
-| Built-in styling | ✅ Multiple color schemes | ❌ None | ✅ Toast style |
-| Promise-based | ✅ | ✅ | ✅ |
-| Zero dependencies | ✅ | ✅ | ✅ |
-| Queue system | ✅ | ❌ | ❌ |
-| Automatic CSS | ✅ No separate imports | ❌ | ❌ |
-| Next.js App Router | ✅ Works out of the box | ❌ Needs 'use client' | ✅ |
+[![npm version](https://img.shields.io/npm/v/react-confirm-lite)](https://www.npmjs.com/package/react-confirm-lite)
+[![bundle size](https://img.shields.io/bundlephobia/minzip/react-confirm-lite)](https://bundlephobia.com/package/react-confirm-lite)
+[![npm downloads](https://img.shields.io/npm/dm/react-confirm-lite)](https://www.npmjs.com/package/react-confirm-lite)
+[![license](https://img.shields.io/npm/l/react-confirm-lite)](https://github.com/SaadNasir-git/react-confirm-lite/blob/main/LICENSE)
+[![typescript](https://img.shields.io/badge/types-TypeScript-blue)](https://www.typescriptlang.org/)
+[![react](https://img.shields.io/badge/react-%3E%3D18-blue)](https://reactjs.org/)
 
-## Why Choose react-confirm-lite?
-
-If you want a **simple, lightweight** confirm dialog that **just works** without any configuration, `react-confirm-lite` is perfect. No separate CSS imports, no 'use client' directives needed in Next.js App Router, and fully customizable when you need it.
+![Sample Image](https://camo.githubusercontent.com/af08928ac7006e57dc2a28f01b1fbc7214ea742379365f364f37bb204a93906b/68747470733a2f2f7265732e636c6f7564696e6172792e636f6d2f646863716e35626d712f696d6167652f75706c6f61642f76313736363737383630322f53637265656e6361737466726f6d323032352d31322d323730302d34322d31342d657a6769662e636f6d2d6f7074696d697a655f6f64316874322e676966)
 
 ## 🔗 Live Demo
 
 [![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/edit/vitejs-vite-bfthlpmw?file=src%2FApp.tsx)
 
-## Getting Started
+## 📦 Installation
 
-### Step 1: **Install the package**:
 ```bash
 npm install react-confirm-lite
+# or
+yarn add react-confirm-lite
+# or
+pnpm add react-confirm-lite
 ```
 
-### Step 2: Import in your component:
+## 🚀 Quick Start
+
+### 1. Add the Container Component
+
+Place `<ConfirmContainer />` in your app (usually in root layout):
+
 ```tsx
-import { confirm, ConfirmContainer } from 'react-confirm-lite';
-```
+import { ConfirmContainer } from 'react-confirm-lite';
 
-### Step 3: Add ConfirmContainer to your component tree:
-```jsx
 function App() {
   return (
-    <>
-      <ConfirmContainer />
+    <div>
       {/* Your app content */}
-    </>
+      <ConfirmContainer />
+    </div>
   );
 }
 ```
 
-### Step 4: Use the confirm function:
+### 2. Use the Confirm Function
+
+Import and use `confirm()` anywhere in your app:
+
 ```tsx
-const handleAction = async () => {
-  const isConfirmed = await confirm('Are you sure?');
-  if (isConfirmed) {
-    // Perform action
-    console.log('Confirmed!');
+import { confirm } from 'react-confirm-lite';
+
+async function handleAction() {
+  const result = await confirm('Are you sure?');
+  
+  if (result) {
+    console.log('User confirmed!');
+  } else {
+    console.log('User cancelled!');
   }
-};
+}
 ```
 
-### Complete Example:
+## 🎯 Features
 
+### ✅ Simple Promise-based API
 ```tsx
-import { confirm, ConfirmContainer } from 'react-confirm-lite';
+const result = await confirm('Message here');
+// Returns true for OK, false for Cancel, null for ESC/outside click
+```
 
-function App() {
-  const handleDelete = async () => {
-    const isConfirmed = await confirm('Are you sure you want to delete this item?');
-    if (isConfirmed) {
-      // Delete logic here
-      console.log('Item deleted');
-    }
-  };
+### ✅ 18 Built-in Animations
+Choose from various animations:
+- `slide` (default) - Smooth slide up/down
+- `fadeScale` - Fade with scale effect
+- `bounce` - Playful bounce animation
+- `flip` - 3D flip effect
+- `zoom` - Zoom in/out
+- `rotate` - Rotate animation
+- `fadeUp` / `fadeDown` - Directional fade
+- `drop` - 3D drop effect
+- `slideRight` / `slideLeft` - Horizontal slides
+- `slideVertical` - Vertical slide
+- `slideDown` - Slide down
+- `rotateRight` - Rotate from right
+- `zoomSmall` / `bounceSmall` - Subtle animations
+- `fadeBlur` / `fadeShrink` - Creative effects
+
+### ✅ 6 Color Schemes
+Pre-built color themes:
+- `dark` (default) - Dark theme
+- `light` - Light theme
+- `blue` - Blue theme
+- `red` - Perfect for destructive actions
+- `green` - Success actions
+- `purple` - Premium/feature actions
+
+### ✅ Interactive Controls
+- `closeOnEscape` (default: true) - Press ESC to close
+- `closeOnClickOutside` (default: true) - Click backdrop to close
+- Returns `null` when closed via ESC or backdrop click
+
+### ✅ Customizable Options
+Control every aspect:
+- Custom OK/Cancel button text
+- Separate animation durations for enter/exit
+- Override colors per dialog
+- Custom CSS classes for all elements
+
+### ✅ Queue System
+Multiple confirm requests automatically queue and show one at a time:
+```tsx
+// These will show sequentially
+await confirm('First?');
+await confirm('Second?');
+await confirm('Third?');
+```
 
-  return (
-    <div>
-      <button onClick={handleDelete}>Delete Item</button>
-      <ConfirmContainer />
-    </div>
-  );
+### ✅ Zero Configuration
+No CSS imports needed. Styles are automatically injected.
+
+## 🎨 Usage Examples
+
+### Basic Usage
+```tsx
+const result = await confirm('Delete this item?');
+if (result) {
+  // User clicked OK
+  deleteItem();
+} else if (result === false) {
+  // User clicked Cancel
+  console.log('Cancelled');
+} else if (result === null) {
+  // User pressed ESC or clicked outside
+  console.log('Closed via ESC/backdrop');
 }
 ```
 
-## Advanced Usage
+### Custom Dialog Options
+```tsx
+const result = await confirm({
+  title: 'Delete Account',
+  message: 'This will permanently delete your account and all data.',
+  okText: 'Delete Forever',
+  cancelText: 'Cancel',
+  colorSchema: 'red'
+});
+```
 
-### Custom Options:
+### Disable ESC and Backdrop Closing
 ```tsx
-const handleCustomConfirm = async () => {
-  const isConfirmed = await confirm({
-    title: "Delete Item",
-    message: "This action cannot be undone. Are you sure?",
-    cancelText: 'No, keep it',
-    okText: 'Yes, delete',
-    colorSchema: 'red',
-    isDestructive: true
-  });
-  
-  if (isConfirmed) {
-    // Delete item
-  }
-};
+<ConfirmContainer 
+  closeOnEscape={false}
+  closeOnClickOutside={false}
+/>
+// Now dialog can only be closed with Cancel/OK buttons
 ```
 
-### Custom Color Scheme:
-```jsx
-<ConfirmContainer defaultColorSchema="light" />
-// Available options: 'light', 'dark', 'blue', 'red', 'green', 'purple'
+## 🔧 API Reference
+
+### Confirm Container Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `animation` | `AnimationType` | `'slide'` | Animation type (18 options) |
+| `animationDuration` | `number` | `300` | Base animation duration (ms) |
+| `animationDurationIn` | `number` | - | Enter animation duration |
+| `animationDurationOut` | `number` | - | Exit animation duration |
+| `defaultColorSchema` | `ColorSchema` | `'dark'` | Default color scheme |
+| `closeOnEscape` | `boolean` | `true` | Close with ESC key |
+| `closeOnClickOutside` | `boolean` | `true` | Close on backdrop click |
+| `classes` | `ConfirmClasses` | `{}` | Custom CSS classes |
+
+### Confirm Function
+
+```tsx
+// String input (simple)
+await confirm('Simple message');
+
+// Object input (full options)
+await confirm({
+  title: 'Custom Title',           // Optional
+  message: 'Required message',     // Required
+  okText: 'Proceed',               // Optional
+  cancelText: 'Go Back',           // Optional
+  colorSchema: 'blue',             // Optional
+});
 ```
 
-### Custom Styling:
-```jsx
+**Return values:**
+- `true` - User clicked OK
+- `false` - User clicked Cancel
+- `null` - User pressed ESC or clicked outside (if enabled)
+
+### Custom Styling with CSS Classes
+
+```tsx
 <ConfirmContainer 
   classes={{
-    overlay: "bg-black/50",
-    wrapper: "rounded-xl shadow-2xl",
-    title: "text-2xl font-bold",
-    message: "text-gray-600",
-    button: "px-6 py-3 rounded-lg font-medium",
-    cancel: "border border-gray-300 hover:bg-gray-50",
-    ok: "bg-blue-600 hover:bg-blue-700 text-white"
+    overlay: "my-overlay-class",    // Background overlay
+    wrapper: "my-modal-class",      // Modal container
+    title: "my-title-class",        // Title text
+    message: "my-message-class",    // Message text
+    button: "my-button-class",      // Both buttons
+    cancel: "my-cancel-class",      // Cancel button only
+    ok: "my-ok-class",              // OK button only
   }}
 />
 ```
 
-### Fully Custom UI with Render Prop:
-```jsx
+## 🎭 Custom UI with Render Prop
+
+Want complete control over the UI? Use the render prop:
+
+```tsx
 <ConfirmContainer animationDuration={500}>
-  {({ isVisible, confirm, handleCancel, handleOk }) => (
-    <div className={`modal ${isVisible ? 'show' : 'hide'}`}>
-      <div className="modal-content">
+  {({ 
+    isVisible, 
+    confirm, 
+    handleCancel, 
+    handleOk, 
+    containerRef, 
+    animationClass, 
+    animationStyle 
+  }) => (
+    <div className={`modal-overlay ${isVisible ? 'show' : 'hide'}`}>
+      {/* Your custom backdrop */}
+      <div className="backdrop" onClick={handleCancel} />
+      
+      {/* Your custom modal */}
+      <div 
+        ref={containerRef}
+        className={`custom-modal ${animationClass}`}
+        style={animationStyle}
+      >
         <h2>{confirm.title}</h2>
         <p>{confirm.message}</p>
-        <div className="modal-actions">
+        
+        <div className="buttons">
           <button onClick={handleCancel}>
             {confirm.cancelText || 'Cancel'}
           </button>
@@ -159,222 +251,238 @@ const handleCustomConfirm = async () => {
 </ConfirmContainer>
 ```
 
-## Next.js App Router Support
+**Available render props:**
+- `isVisible`: Boolean indicating if dialog should be visible
+- `confirm`: The current confirm options object
+- `handleCancel`: Function to cancel the dialog (returns false)
+- `handleOk`: Function to confirm the dialog (returns true)
+- `containerRef`: React ref for the modal container
+- `colorSchema`: Current color scheme
+- `animationClass`: CSS class for current animation
+- `animationStyle`: Style object with animation duration
 
-Works automatically! No 'use client' directive needed for the library. The library handles everything internally.
+## 📱 Real-World Examples
 
-### Server Components Example:
+### Delete Confirmation with ESC Disabled
 ```tsx
-// app/layout.tsx
-import { ConfirmContainer } from 'react-confirm-lite';
+const handleDelete = async () => {
+  // Force user to make explicit choice
+  const result = await confirm({
+    title: 'Delete Item',
+    message: 'This action cannot be undone. Are you sure?',
+    okText: 'Delete',
+    cancelText: 'Keep',
+    colorSchema: 'red'
+  });
 
-export default function RootLayout({
-  children,
-}: {
-  children: React.ReactNode;
-}) {
-  return (
-    <html lang="en">
-      <body>
-        {children}
-        <ConfirmContainer />
-      </body>
-    </html>
-  );
-}
-```
-```tsx
-// app/page.tsx (server component)
-import { confirm } from 'react-confirm-lite';
+  // Result can only be true or false (no null since ESC/backdrop disabled)
+  if (result) {
+    await deleteItem();
+  }
+};
 
-export default async function Page() {
-  // Server-side logic here
-  
-  return (
-    <form action={async () => {
-      'use server';
-      const isConfirmed = await confirm('Are you sure?');
-      if (isConfirmed) {
-        // Server action
-      }
-    }}>
-      <button>Submit</button>
-    </form>
-  );
-}
+// In your component
+<ConfirmContainer closeOnEscape={false} closeOnClickOutside={false} />
 ```
 
-### Client Component Example:
+### Form Submission with Backdrop Only
 ```tsx
-'use client';
-import { confirm, ConfirmContainer } from 'react-confirm-lite';
-
-export default function ClientComponent() {
-  const handleClick = async () => {
-    const result = await confirm('Confirm action?');
-    if (result) {
-      // Handle confirmation
-    }
-  };
+// Allow closing by clicking backdrop but not ESC
+<ConfirmContainer closeOnEscape={false} closeOnClickOutside={true} />
+
+const handleSubmit = async () => {
+  const result = await confirm({
+    title: 'Submit Form',
+    message: 'Ready to submit this form?',
+    okText: 'Submit',
+    cancelText: 'Review',
+    colorSchema: 'green'
+  });
 
-  return (
-    <div>
-      <button onClick={handleClick}>Click me</button>
-      <ConfirmContainer />
-    </div>
-  );
-}
+  if (result) {
+    await submitForm();
+  } else if (result === null) {
+    // User clicked backdrop
+    console.log('Closed by clicking outside');
+  }
+};
 ```
 
-## API Reference
+### Different Behaviors for Different Dialogs
+```tsx
+// Global: ESC and backdrop disabled
+<ConfirmContainer 
+  closeOnEscape={false} 
+  closeOnClickOutside={false} 
+/>
 
-### `confirm(message: string | ConfirmOptions): Promise<boolean>`
+// Some dialogs can override via custom UI
+const handleFlexibleDialog = async () => {
+  // Create custom UI that allows ESC/backdrop
+  const result = await confirm('Flexible dialog?');
+  // result can be true, false, or null
+};
+```
 
-Displays a confirmation dialog. Returns a promise that resolves to `true` if confirmed, `false` if cancelled.
+## 🏗️ Container Configuration
 
-**String usage:**
-```ts
-await confirm('Simple message');
-// Equivalent to: { title: 'Confirm', message: 'Simple message' }
+### Global Settings
+```tsx
+<ConfirmContainer
+  defaultColorSchema="light"        // Light theme by default
+  animation="zoom"                  // Zoom animation for all dialogs
+  animationDuration={400}           // 400ms animations
+  closeOnEscape={true}              // Allow ESC to close
+  closeOnClickOutside={true}        // Allow backdrop click to close
+  animationDurationIn={350}         // Enter: 350ms
+  animationDurationOut={250}        // Exit: 250ms
+/>
 ```
 
-**Object usage:**
-```ts
-await confirm({
-  title: 'Warning',
-  message: 'This action cannot be undone',
-  cancelText: 'Cancel',
-  okText: 'Delete',
-  colorSchema: 'red',
-  isDestructive: true
-});
-```
+### Different Close Behaviors
+```tsx
+// Option 1: Fully closable (default)
+<ConfirmContainer closeOnEscape={true} closeOnClickOutside={true} />
+// Users can close via: OK, Cancel, ESC, or backdrop click
 
-### `ConfirmContainer` Props:
+// Option 2: Force explicit choice
+<ConfirmContainer closeOnEscape={false} closeOnClickOutside={false} />
+// Users can only close via: OK or Cancel buttons
 
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `defaultColorSchema` | `ColorSchema` | `'dark'` | Default color scheme |
-| `animationDuration` | `number` | `300` | Animation duration in ms |
-| `classes` | `ConfirmClasses` | `{}` | Custom CSS classes |
-| `children` | Render function | - | For complete UI customization |
-
-### Types:
-```ts
-type ColorSchema = 'light' | 'dark' | 'blue' | 'red' | 'green' | 'purple';
-
-interface ConfirmClasses {
-  overlay?: string;
-  wrapper?: string;
-  title?: string;
-  message?: string;
-  button?: string;
-  cancel?: string;
-  ok?: string;
-}
+// Option 3: Backdrop only
+<ConfirmContainer closeOnEscape={false} closeOnClickOutside={true} />
+// Users can close via: OK, Cancel, or backdrop click
 
-interface ConfirmOptions {
-  title?: string;
-  message: string;
-  cancelText?: string;
-  okText?: string;
-  colorSchema?: ColorSchema;
-  isDestructive?: boolean;
-}
+// Option 4: ESC only
+<ConfirmContainer closeOnEscape={true} closeOnClickOutside={false} />
+// Users can close via: OK, Cancel, or ESC key
 ```
 
-## Troubleshooting
+## 🎨 Animation Gallery
 
-### ❌ Dialog not appearing?
-- Make sure `<ConfirmContainer />` is rendered in your component tree
-- Check that you're not conditionally rendering it in a way that unmounts it
+### Slide Animations
+- `slide` - Smooth vertical slide (default)
+- `slideRight` / `slideLeft` - Horizontal slides
+- `slideVertical` - Vertical slide
+- `slideDown` - Slide down
 
-### ❌ Multiple dialogs overlapping?
-- The library has a built-in queue system that handles multiple confirm requests sequentially
+### Fade Animations
+- `fadeScale` - Fade with scaling
+- `fadeUp` / `fadeDown` - Directional fades
+- `fadeBlur` - Fade with blur effect
+- `fadeShrink` - Fade with shrink effect
 
-### ❌ Styling not working?
-- If using custom classes, ensure they have proper CSS specificity
-- Try using `!important` flag for custom styles if needed
-- Make sure you're on the latest version
+### 3D Animations
+- `flip` - Card flip effect
+- `drop` - 3D drop animation
+- `rotate` / `rotateRight` - Rotation effects
 
-### ❌ Animation issues with custom UI?
-- When using the `children` render prop, use the `isVisible` prop for animations
-- Set appropriate `animationDuration` to match your CSS transitions
+### Playful Animations
+- `bounce` / `bounceSmall` - Bounce effects
+- `zoom` / `zoomSmall` - Zoom in/out
 
-### ❌ Next.js hydration errors?
-- The library is designed to work with Next.js App Router
-- If using in a layout, ensure it's placed after dynamic content
+## 🚨 Troubleshooting
 
-## Features in Detail
+### Dialog not showing?
+- Make sure `<ConfirmContainer />` is mounted
+- Check it's not conditionally rendered
 
-### 🎨 Multiple Color Schemes
-Six built-in color schemes: light, dark, blue, red, green, purple. Set globally or per confirm dialog.
+### ESC key not working?
+- Check if `closeOnEscape={true}` (default)
+- Ensure no other event is preventing ESC
+- Try different browsers
 
-### 🔄 Queue System
-Multiple confirm requests are queued and shown one at a time, preventing overlapping dialogs.
+### Backdrop click not working?
+- Verify `closeOnClickOutside={true}` (default)
+- Check if any parent element is preventing clicks
 
-### 🎯 Zero Configuration
-Works out of the box with default styling. No CSS imports needed.
+### Animation not working?
+- Verify animation name is correct
+- Check browser console for errors
 
-### 🔧 Fully Customizable
-From simple class overrides to complete UI replacement with render props.
+### TypeScript errors?
+- Ensure you have `@types/react` installed
+- Update to latest TypeScript version
 
-### 📱 Responsive Design
-Built-in responsive styling that works on all screen sizes.
+### Styling issues?
+- Use `classes` prop to override styles
+- Check CSS specificity
 
-### 🔒 Type Safety
-Full TypeScript support with comprehensive type definitions.
+## 📱 Next.js Support
 
-## Performance
-
-- **Zero dependencies**: Only React as a peer dependency
-- **Tree-shakeable**: Only imports what you use
-- **Small bundle size**: ~5KB gzipped (including styles)
-- **Optimized renders**: Minimal re-renders with React.memo
+### App Router (Next.js 15+)
+```tsx
+// app/layout.tsx
+import { ConfirmContainer } from 'react-confirm-lite';
 
-## Migration from Older Versions
+export default function RootLayout({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  return (
+    <html lang="en">
+      <body>
+        {children}
+        <ConfirmContainer />
+      </body>
+    </html>
+  );
+}
+```
 
-If you're upgrading from version <1.3.0:
+### Server Components
+```tsx
+// Server actions
+'use server';
+import { confirm } from 'react-confirm-lite';
 
-1. **'use client' not needed**: The library handles this internally
-2. **Simpler API**: Same functions, better internals
+export async function serverAction() {
+  const result = await confirm('Confirm from server?');
+  if (result) {
+    // Perform action
+  } else if (result === null) {
+    // User pressed ESC or clicked outside
+    console.log('Action cancelled');
+  }
+}
+```
 
+## 🔄 Migration from Other Libraries
 
-## Contributing
+### From window.confirm()
+```tsx
+// Old way (always returns true/false)
+if (window.confirm('Delete?')) {
+  deleteItem();
+}
 
-Contributions are welcome! Please:
+// New way (returns true/false/null)
+const result = await confirm('Delete?');
+if (result === true) {
+  await deleteItem();
+} else if (result === false) {
+  console.log('User clicked Cancel');
+} else if (result === null) {
+  console.log('User pressed ESC');
+}
+```
 
-1. Fork the repository
-2. Create a feature branch
-3. Add tests for your changes
-4. Submit a pull request
+### From Other Confirm Libraries
+- No CSS imports needed
+- Automatic queue system
+- Built-in animations
+- Zero configuration
+- Three return states (true/false/null)
 
-## Author
+## 📄 License
 
-**Saad Nasir** - Full Stack Developer
-- GitHub: [@SaadNasir-git](https://github.com/SaadNasir-git)
-- For support: Open an issue on GitHub
+MIT License - free for personal and commercial use.
 
-## License
+## 👨‍💻 Author
 
-MIT © Saad Nasir
+**Saad Nasir** - Creator of react-confirm-lite
 
 ---
 
-![npm version](https://img.shields.io/npm/v/react-confirm-lite)
-![bundle size](https://img.shields.io/bundlephobia/minzip/react-confirm-lite)
-![npm downloads](https://img.shields.io/npm/dm/react-confirm-lite)
-![license](https://img.shields.io/npm/l/react-confirm-lite)
-![typescript](https://img.shields.io/badge/types-TypeScript-blue)
-![react](https://img.shields.io/badge/react-%3E%3D18-blue)
-![next.js](https://img.shields.io/badge/next.js-15+-black)
-
-## Support
-
-If you find this library helpful, please consider:
-- ⭐ Starring the repository on GitHub
-- 📢 Sharing with your network
-- 🐛 Reporting issues you encounter
-- 💡 Suggesting new features
-
-Happy coding! 🚀
+⭐ **Found this useful? Give it a star on GitHub!** ⭐