@manhphi1309/dialog 0.1.1 → 0.2.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,245 @@ 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.
+
+---
+
+## 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>
+  )
 }
 ```