@manhphi1309/dialog 0.1.2 → 0.3.0

package/README.md

@@ -1,15 +1,11 @@
 # @manhphi1309/dialog
 
-A custom dialog component for the shadcn-custom monorepo.
+A fully-accessible dialog package built on top of [Radix UI Dialog](https://www.radix-ui.com/primitives/docs/components/dialog). Ships two complete component families:
 
-## Subcomponents
+- **`Dialog*`** — standard modal dialog, always renders as a centered overlay
+- **`ResponsiveDialog*`** — adaptive wrapper that switches to a bottom `Drawer` on mobile screens (< 768 px)
 
-- `Dialog`
-
-## Dependencies
-
-- `@manhphi1309/utils`
-- `class-variance-authority`
+---
 
 ## Installation
 
@@ -17,12 +13,268 @@ A custom dialog component for the shadcn-custom monorepo.
 npm install @manhphi1309/dialog
 ```
 
-## Usage Example
+---
+
+## Dependencies
+
+| Package               | Role                                          |
+| --------------------- | --------------------------------------------- |
+| `@manhphi1309/button` | Close / action buttons inside dialogs         |
+| `@manhphi1309/drawer` | Mobile fallback used by `ResponsiveDialog*`   |
+| `@manhphi1309/hooks`  | `useIsMobile()` for the responsive breakpoint |
+| `@manhphi1309/utils`  | `cn()` class-name helper                      |
+
+---
+
+## Dialog Family
+
+A set of composable primitives that always render as a centred modal overlay, regardless of screen size.
+
+### `Dialog`
+
+The **root** component. Controls open/close state and provides context to all children. Thin wrapper around `Radix Dialog.Root`.
+
+```tsx
+<Dialog open={open} onOpenChange={setOpen}>
+  ...
+</Dialog>
+```
+
+| Prop           | Type                      | Notes                                                          |
+| -------------- | ------------------------- | -------------------------------------------------------------- |
+| `open`         | `boolean`                 | Controlled open state                                          |
+| `onOpenChange` | `(open: boolean) => void` | Called when open state changes                                 |
+| `defaultOpen`  | `boolean`                 | Uncontrolled initial state                                     |
+| `modal`        | `boolean`                 | Default `true` — traps focus and blocks background interaction |
+
+---
+
+### `DialogTrigger`
+
+Wraps the element that **opens** the dialog when clicked. Passes through all props to the underlying `Radix Dialog.Trigger`. Use `asChild` to compose with your own element.
+
+```tsx
+<DialogTrigger asChild>
+  <Button>Open</Button>
+</DialogTrigger>
+```
+
+---
+
+### `DialogPortal`
+
+Renders its children into a **portal** outside the current DOM tree (appended to `document.body`). Ensures the dialog appears above all other content and avoids z-index / overflow issues.
+
+> Usually you do not use this directly — `DialogContent` includes it automatically.
+
+---
+
+### `DialogOverlay`
+
+The **backdrop** behind the dialog content. Renders a fixed, full-screen semi-transparent layer (`bg-black/10`) with a backdrop blur on supported browsers.
+
+**Animations:**
+
+- Open → `fade-in-0`
+- Close → `fade-out-0`
+
+> Usually you do not use this directly — `DialogContent` includes it automatically.
+
+---
+
+### `DialogContent`
+
+The **visible panel** of the dialog. Renders centred on screen (`top-1/2 left-1/2 -translate-x-1/2 -translate-y-1/2`), inside a portal with an overlay underneath. Comes with a ✕ ghost button in the top-right corner by default.
+
+**Animations:**
+
+- Open → `fade-in-0 + zoom-in-95`
+- Close → `fade-out-0 + zoom-out-95`
+
+| Prop              | Type      | Default | Notes                                                   |
+| ----------------- | --------- | ------- | ------------------------------------------------------- |
+| `showCloseButton` | `boolean` | `true`  | Show/hide the built-in ✕ button in the top-right corner |
+| `className`       | `string`  | —       | Extra classes merged on the content panel               |
+
+```tsx
+<DialogContent showCloseButton={false}>...</DialogContent>
+```
+
+---
+
+### `DialogHeader`
+
+A **layout wrapper** for the top section of a dialog. Stacks children vertically with `gap-2`. Typically holds `DialogTitle` and `DialogDescription`.
+
+```tsx
+<DialogHeader>
+  <DialogTitle>Title</DialogTitle>
+  <DialogDescription>Optional description.</DialogDescription>
+</DialogHeader>
+```
+
+---
+
+### `DialogTitle`
+
+The **accessible title** of the dialog. Rendered as a Radix `Dialog.Title` (connected to `aria-labelledby` on the content). Styled with `text-base font-medium leading-none` using the heading font.
+
+> Required for accessibility — screen readers announce this when the dialog opens.
+
+---
+
+### `DialogDescription`
+
+The **accessible description** of the dialog. Rendered as a Radix `Dialog.Description` (connected to `aria-describedby` on the content). Styled as small muted text. Links inside it are automatically underlined.
+
+> Optional but recommended for accessibility.
+
+---
+
+### `DialogFooter`
+
+A **layout wrapper** for the bottom action area. Bleeds to the edges of the content panel (`-mx-4 -mb-4`), adds a top border and `bg-muted/50` tint. Actions stack vertically on mobile, align right horizontally on `sm+`.
+
+| Prop              | Type      | Default | Notes                                                    |
+| ----------------- | --------- | ------- | -------------------------------------------------------- |
+| `showCloseButton` | `boolean` | `false` | Appends a `Close` outline button wired to `Dialog.Close` |
+
+```tsx
+<DialogFooter showCloseButton>
+  <Button type="submit">Save</Button>
+</DialogFooter>
+```
+
+---
+
+### `DialogClose`
+
+A bare **close trigger** primitive. Closes the dialog when activated. Use `asChild` to compose with a custom element.
+
+```tsx
+<DialogClose asChild>
+  <Button variant="ghost">Cancel</Button>
+</DialogClose>
+```
+
+---
+
+## ResponsiveDialog Family
+
+Drop-in replacements for the `Dialog*` components. Each one checks `useIsMobile()` (breakpoint: `768 px`) and renders the appropriate primitive:
+
+| Component                     | Desktop (≥ 768 px)  | Mobile (< 768 px)   |
+| ----------------------------- | ------------------- | ------------------- |
+| `ResponsiveDialog`            | `Dialog`            | `Drawer`            |
+| `ResponsiveDialogTrigger`     | `DialogTrigger`     | `DrawerTrigger`     |
+| `ResponsiveDialogClose`       | `DialogClose`       | `DrawerClose`       |
+| `ResponsiveDialogContent`     | `DialogContent`     | `DrawerContent`     |
+| `ResponsiveDialogHeader`      | `DialogHeader`      | `DrawerHeader`      |
+| `ResponsiveDialogFooter`      | `DialogFooter`      | `DrawerFooter`      |
+| `ResponsiveDialogTitle`       | `DialogTitle`       | `DrawerTitle`       |
+| `ResponsiveDialogDescription` | `DialogDescription` | `DrawerDescription` |
+
+All props are forwarded to the underlying component unchanged. `showCloseButton` on `ResponsiveDialogContent` and `ResponsiveDialogFooter` works the same way as on their dialog counterparts, including the correct close primitive for the active variant.
+
+> **Note:** `ResponsiveDialogContent` does **not** forward `showCloseButton` to `DrawerContent` (the Drawer handles close via the handle bar and swipe gesture). The prop is only meaningful on desktop.
+
+### Drawer Snap Points (Mobile Only)
+
+Because `ResponsiveDialog` forwards properties directly to the underlying Vaul `<Drawer>` on mobile devices, you can pass drawer-specific props like `snapPoints` directly to the `<ResponsiveDialog>` root component. The desktop `<Dialog>` will safely ignore them.
+
+```tsx
+// Using React state to properly control the active snap point
+const [snap, setSnap] = React.useState<number | string | null>("500px")
+
+<ResponsiveDialog
+  snapPoints={["300px", "500px", 1]}
+  activeSnapPoint={snap}
+  setActiveSnapPoint={setSnap}
+  fadeFromIndex={1}
+>
+  ...
+</ResponsiveDialog>
+```
+
+> [!WARNING]
+> **Important Vaul Requirements:**
+> 1. **Strict Types:** If you provide `snapPoints`, you are strictly required by Vaul to provide `fadeFromIndex` as a number.
+> 2. **Controlled State:** If you hardcode `activeSnapPoint` as a string/number prop *without* passing a state setter to `setActiveSnapPoint`, the Drawer will glitch and snap back down when the user tries to drag it, because React will force it back to the hardcoded prop value on the next render. Always use a state hook (like `useState`) for the active point.
+
+---
+
+## Usage
+
+### Standard Dialog
+
+```tsx
+import { Button } from "@manhphi1309/button"
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+  DialogTrigger,
+} from "@manhphi1309/dialog"
+
+export default function DeleteConfirm() {
+  return (
+    <Dialog>
+      <DialogTrigger asChild>
+        <Button variant="destructive">Delete account</Button>
+      </DialogTrigger>
+      <DialogContent>
+        <DialogHeader>
+          <DialogTitle>Are you absolutely sure?</DialogTitle>
+          <DialogDescription>
+            This action cannot be undone. Your account will be permanently
+            deleted.
+          </DialogDescription>
+        </DialogHeader>
+        <DialogFooter showCloseButton>
+          <Button variant="destructive">Delete</Button>
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>
+  )
+}
+```
+
+### Responsive Dialog (Dialog on desktop, Drawer on mobile)
 
 ```tsx
-import { Dialog } from "@manhphi1309/dialog"
+import { Button } from "@manhphi1309/button"
+import {
+  ResponsiveDialog,
+  ResponsiveDialogContent,
+  ResponsiveDialogDescription,
+  ResponsiveDialogFooter,
+  ResponsiveDialogHeader,
+  ResponsiveDialogTitle,
+  ResponsiveDialogTrigger,
+} from "@manhphi1309/dialog"
 
-export default function App() {
-  return <Dialog>Hello World</Dialog>
+export default function EditProfile() {
+  return (
+    <ResponsiveDialog>
+      <ResponsiveDialogTrigger asChild>
+        <Button>Edit Profile</Button>
+      </ResponsiveDialogTrigger>
+      <ResponsiveDialogContent>
+        <ResponsiveDialogHeader>
+          <ResponsiveDialogTitle>Edit profile</ResponsiveDialogTitle>
+          <ResponsiveDialogDescription>
+            Make changes to your profile here.
+          </ResponsiveDialogDescription>
+        </ResponsiveDialogHeader>
+        {/* form content */}
+        <ResponsiveDialogFooter>
+          <Button type="submit">Save changes</Button>
+        </ResponsiveDialogFooter>
+      </ResponsiveDialogContent>
+    </ResponsiveDialog>
+  )
 }
 ```