modalio 0.9.0

package/README.md

@@ -0,0 +1,157 @@
+# modalio
+
+A lightweight, type-safe, and animation-aware modal management library for React.
+
+[![Tests](https://github.com/achromaticlabs/react-modalio/actions/workflows/test.yml/badge.svg)](https://github.com/achromaticlabs/react-modalio/actions)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Features
+
+- **🚀 Promise-based API** - `open()` returns promises for `afterOpened()` and `afterClosed()`.
+- **🛡️ Type-safe** - Full TypeScript support with generics for modal data and results.
+- **✨ Animation-aware** - Automatically waits for enter/exit animations/transitions before cleanup.
+- **🔌 Pre-built Adapters** - Seamless integration with **Shadcn UI**, **Radix UI**, and **Base UI**.
+- **📦 Lightweight** - Zero dependencies beyond React.
+- **🧠 Flexible** - Manage modals via programmatic API or declarative JSX.
+
+## Installation
+
+```bash
+npm install modalio
+```
+
+## Quick Start
+
+### 1. Wrap your app with the Provider
+
+```tsx
+import { ModalManager } from "modalio";
+
+function Root() {
+  return (
+    <ModalManager.Provider>
+      <App />
+    </ModalManager.Provider>
+  );
+}
+```
+
+### 2. Define a modal
+
+Use pre-built adapters to bridge your UI library with the modal manager logic.
+
+```tsx
+import { ModalManager, useModal, shadcnUiDialog, shadcnUiDialogContent } from "modalio";
+import { Dialog, DialogContent, DialogHeader, DialogTitle } from "@/components/ui/dialog";
+
+const MyModal = ModalManager.create(({ title }: { title: string }) => {
+  const modal = useModal();
+
+  return (
+    <Dialog {...shadcnUiDialog(modal)}>
+      <DialogContent {...shadcnUiDialogContent(modal)}>
+        <DialogHeader>
+          <DialogTitle>{title}</DialogTitle>
+        </DialogHeader>
+        <p>This is a managed modal!</p>
+        <button onClick={() => modal.close("success")}>Close with Result</button>
+      </DialogContent>
+    </Dialog>
+  );
+});
+```
+
+### 3. Open the modal
+
+```tsx
+// 1. Programmatic Usage (e.g., in an event handler)
+const openConfirmModal = async () => {
+  const result = await ModalManager.open(MyModal, {
+    data: { title: "Are you sure?" }
+  }).afterClosed();
+
+  if (result === "success") {
+    // Handle success (programmatic close)
+  } else {
+    // result is undefined if the modal was dismissed (cancelled)
+  }
+};
+
+// 2. Declarative Usage (via JSX)
+function MyPage() {
+  return (
+    <>
+      {/* Registers the modal for later use by its ID */}
+      <ModalManager.Def id="optional-id" component={MyModal} props={{ title: "Static Modal" }} />
+      <button onClick={() => ModalManager.open("optional-id")}>Open by ID</button>
+    </>
+  );
+}
+```
+
+## Common Patterns
+
+### **1. Returning Results**
+The `open()` function is generically typed to support results.
+
+```tsx
+const openConfirm = async () => {
+  // result is typed as "confirmed" | "cancelled" | undefined
+  const result = await ModalManager.open<boolean>(MyModal).afterClosed();
+  
+  if (result) {
+    console.log("User confirmed!");
+  }
+};
+```
+
+### **2. Lifecycle Hooks**
+Wait for the modal to be fully opened or perform actions before it closes.
+
+```tsx
+const ref = ModalManager.open(MyModal);
+
+ref.afterOpened().then(() => {
+  console.log("Modal is now fully visible and animations are done.");
+});
+
+const result = await ref.afterClosed();
+```
+
+### **3. Closing All Modals**
+Useful for navigation changes or resetting application state.
+
+```tsx
+// Closes all modals and waits for their exit animations
+await ModalManager.closeAll();
+```
+
+## Supported Libraries (Adapters)
+
+We provide pre-built adapters to make integration seamless:
+
+### **Shadcn UI**
+```tsx
+import { shadcnUiDialog, shadcnUiDialogContent, shadcnUiDrawer } from "modalio";
+```
+Adapters: `shadcnUiDialog`, `shadcnUiDialogContent`, `shadcnUiAlertDialog`, `shadcnUiSheet`, `shadcnUiDrawer`, `shadcnUiPopover`.
+
+### **Radix UI**
+```tsx
+import { radixUiDialog, radixUiDialogContent, radixUiPopover } from "modalio";
+```
+Adapters: `radixUiDialog`, `radixUiDialogContent`, `radixUiAlertDialog`, `radixUiAlertDialogContent`, `radixUiPopover`, `radixUiSheet`.
+
+### **Base UI**
+```tsx
+import { baseUiDialog, baseUiPopover } from "modalio";
+```
+Adapters: `baseUiDialog`, `baseUiDialogPopup`, `baseUiDialogPortal`, `baseUiAlertDialog`, `baseUiAlertDialogPopup`, `baseUiPopover`, `baseUiPopoverPopup`, `baseUiPopoverPortal`, `baseUiSheet`.
+
+## Documentation
+
+For full documentation, including advanced usage, custom adapters, and API reference, visit [achromatic.dev/docs/react-modalio](https://achromatic.dev/docs/react-modalio).
+
+## License
+
+MIT