@manhphi1309/dialog 0.1.2 → 0.3.0

package/dist/index.d.mts

@@ -1,23 +1,111 @@
+import * as React from "react";
 import { Dialog as Dialog$1 } from "radix-ui";
-import * as _$react from "react";
+import { Drawer } from "@manhphi1309/drawer";
 
-//#region index.d.ts
+//#region src/dialog.d.ts
+/**
+ * Root dialog component. Controls open/close state and provides context
+ * to all child primitives via Radix `Dialog.Root`.
+ *
+ * Can be used as **uncontrolled** (via `defaultOpen`) or **controlled**
+ * (via `open` + `onOpenChange`).
+ *
+ * @example
+ * // Uncontrolled
+ * <Dialog>
+ *   <DialogTrigger>Open</DialogTrigger>
+ *   <DialogContent>...</DialogContent>
+ * </Dialog>
+ *
+ * @example
+ * // Controlled
+ * const [open, setOpen] = useState(false)
+ * <Dialog open={open} onOpenChange={setOpen}>
+ *   <DialogContent>...</DialogContent>
+ * </Dialog>
+ */
 declare function Dialog({
   ...props
-}: React.ComponentProps<typeof Dialog$1.Root>): _$react.JSX.Element;
+}: React.ComponentProps<typeof Dialog$1.Root>): React.JSX.Element;
+/**
+ * The element that opens the dialog when activated (clicked / keyboard).
+ * Thin wrapper around Radix `Dialog.Trigger`.
+ *
+ * Use `asChild` to compose with your own element instead of the default button.
+ *
+ * @example
+ * <DialogTrigger asChild>
+ *   <Button variant="outline">Open</Button>
+ * </DialogTrigger>
+ */
 declare function DialogTrigger({
   ...props
-}: React.ComponentProps<typeof Dialog$1.Trigger>): _$react.JSX.Element;
+}: React.ComponentProps<typeof Dialog$1.Trigger>): React.JSX.Element;
+/**
+ * Renders its children into a **portal** appended to `document.body`,
+ * outside the current DOM tree. This ensures the dialog always appears
+ * above other content and is never clipped by parent `overflow` or `z-index`.
+ *
+ * You rarely need to use this directly — `DialogContent` already wraps its
+ * output in a portal automatically.
+ */
 declare function DialogPortal({
   ...props
-}: React.ComponentProps<typeof Dialog$1.Portal>): _$react.JSX.Element;
+}: React.ComponentProps<typeof Dialog$1.Portal>): React.JSX.Element;
+/**
+ * A primitive close trigger. Closes the dialog when activated.
+ * Use `asChild` to compose with a custom element.
+ *
+ * Prefer the built-in `showCloseButton` prop on `DialogContent` or
+ * `DialogFooter` for standard close affordances. Use this component
+ * when you need a completely custom close action inside the dialog body.
+ *
+ * @example
+ * <DialogClose asChild>
+ *   <Button variant="ghost">Cancel</Button>
+ * </DialogClose>
+ */
 declare function DialogClose({
   ...props
-}: React.ComponentProps<typeof Dialog$1.Close>): _$react.JSX.Element;
+}: React.ComponentProps<typeof Dialog$1.Close>): React.JSX.Element;
+/**
+ * The semi-transparent **backdrop** rendered behind the dialog panel.
+ * Covers the full viewport (`fixed inset-0`) with a slight blur and dark tint.
+ *
+ * Animates:
+ * - **Open** → `fade-in-0`
+ * - **Close** → `fade-out-0`
+ *
+ * You rarely need to use this directly — `DialogContent` renders it
+ * automatically via `DialogPortal`.
+ */
 declare function DialogOverlay({
   className,
   ...props
-}: React.ComponentProps<typeof Dialog$1.Overlay>): _$react.JSX.Element;
+}: React.ComponentProps<typeof Dialog$1.Overlay>): React.JSX.Element;
+/**
+ * The **visible panel** of the dialog. Rendered centred on screen via
+ * `position: fixed; top: 50%; left: 50%; translate(-50%, -50%)`.
+ * Automatically wraps itself in `DialogPortal` and renders `DialogOverlay`
+ * behind it.
+ *
+ * By default a ghost ✕ button is positioned in the top-right corner.
+ * Pass `showCloseButton={false}` to remove it when you want to control
+ * close behaviour exclusively from the footer.
+ *
+ * Animates:
+ * - **Open** → `fade-in-0 + zoom-in-95`
+ * - **Close** → `fade-out-0 + zoom-out-95`
+ *
+ * @param showCloseButton - Whether to render the ✕ ghost button in the
+ *   top-right corner. Defaults to `true`.
+ *
+ * @example
+ * <DialogContent showCloseButton={false}>
+ *   <DialogHeader>...</DialogHeader>
+ *   <DialogFooter showCloseButton>...</DialogFooter>
+ * </DialogContent>
+ */
 declare function DialogContent({
   className,
   children,
@@ -25,11 +113,36 @@ declare function DialogContent({
   ...props
 }: React.ComponentProps<typeof Dialog$1.Content> & {
   showCloseButton?: boolean;
-}): _$react.JSX.Element;
+}): React.JSX.Element;
+/**
+ * Layout wrapper for the **top section** of a dialog.
+ * Stacks children vertically with `gap-2`. Typically contains
+ * `DialogTitle` and optionally `DialogDescription`.
+ *
+ * @example
+ * <DialogHeader>
+ *   <DialogTitle>Confirm deletion</DialogTitle>
+ *   <DialogDescription>This action is irreversible.</DialogDescription>
+ * </DialogHeader>
+ */
 declare function DialogHeader({
   className,
   ...props
-}: React.ComponentProps<"div">): _$react.JSX.Element;
+}: React.ComponentProps<"div">): React.JSX.Element;
+/**
+ * Layout wrapper for the **bottom action area** of a dialog.
+ * Bleeds to the content panel edges (`-mx-4 -mb-4`), adds a top border
+ * and a subtle muted background tint. Actions stack vertically on mobile
+ * and align to the right on `sm+` screens.
+ *
+ * @param showCloseButton - When `true`, appends an outline `Close` button
+ *   wired to `DialogClose` after any provided `children`. Defaults to `false`.
+ *
+ * @example
+ * <DialogFooter showCloseButton>
+ *   <Button type="submit">Save</Button>
+ * </DialogFooter>
+ */
 declare function DialogFooter({
   className,
   showCloseButton,
@@ -37,14 +150,212 @@ declare function DialogFooter({
   ...props
 }: React.ComponentProps<"div"> & {
   showCloseButton?: boolean;
-}): _$react.JSX.Element;
+}): React.JSX.Element;
+/**
+ * The **accessible title** of the dialog. Rendered as a Radix `Dialog.Title`,
+ * which is automatically linked to the dialog content via `aria-labelledby`.
+ * Screen readers announce this text when the dialog opens.
+ *
+ * Styled with the heading font token at `text-base font-medium`.
+ *
+ * @remarks Required for accessibility. Every dialog should have a title,
+ * even if visually hidden with `className="sr-only"`.
+ */
 declare function DialogTitle({
   className,
   ...props
-}: React.ComponentProps<typeof Dialog$1.Title>): _$react.JSX.Element;
+}: React.ComponentProps<typeof Dialog$1.Title>): React.JSX.Element;
+/**
+ * The **accessible description** of the dialog. Rendered as a Radix
+ * `Dialog.Description`, which is linked to the dialog content via
+ * `aria-describedby`. Screen readers read this after the title.
+ *
+ * Styled as small muted text. Anchor tags (`<a>`) inside the description
+ * are automatically underlined and change colour on hover.
+ *
+ * @remarks Optional but recommended. Omit only if the dialog content itself
+ * is sufficiently self-descriptive.
+ */
 declare function DialogDescription({
   className,
   ...props
-}: React.ComponentProps<typeof Dialog$1.Description>): _$react.JSX.Element;
+}: React.ComponentProps<typeof Dialog$1.Description>): React.JSX.Element;
 //#endregion
-export { Dialog, DialogClose, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogOverlay, DialogPortal, DialogTitle, DialogTrigger };
+//#region src/responsive-dialog.d.ts
+/**
+ * Adaptive root component that switches between `Dialog` and `Drawer`
+ * depending on screen width:
+ * - **Desktop (≥ 768 px)** → renders `Dialog` (centred modal overlay)
+ * - **Mobile (< 768 px)** → renders `Drawer` (bottom-sheet panel)
+ *
+ * All props are forwarded unchanged to the active primitive, so `open`,
+ * `defaultOpen`, `onOpenChange`, and `modal` all behave identically to
+ * the standard `Dialog` root.
+ *
+ * **Drawer-Specific Props (Mobile Only)**
+ * You can pass Vaul-specific props like `snapPoints`. They are cleanly ignored on desktop.
+ * - **IMPORTANT:** If you provide `snapPoints`, you must also provide `fadeFromIndex` as a strict number.
+ * - **IMPORTANT:** If you pass `activeSnapPoint`, you must also pass `setActiveSnapPoint` and manage it via state (e.g. `useState`). Do not hardcode `activeSnapPoint` without a setter, otherwise the Drawer will glitch and aggressively snap back when dragged.
+ *
+ * @example
+ * <ResponsiveDialog>
+ *   <ResponsiveDialogTrigger asChild>
+ *     <Button>Open</Button>
+ *   </ResponsiveDialogTrigger>
+ *   <ResponsiveDialogContent>
+ *     <ResponsiveDialogHeader>
+ *       <ResponsiveDialogTitle>Title</ResponsiveDialogTitle>
+ *     </ResponsiveDialogHeader>
+ *   </ResponsiveDialogContent>
+ * </ResponsiveDialog>
+ */
+declare function ResponsiveDialog({
+  children,
+  snapPoints,
+  activeSnapPoint,
+  setActiveSnapPoint,
+  fadeFromIndex,
+  shouldScaleBackground,
+  dismissible,
+  snap,
+  ...props
+}: React.ComponentProps<typeof Dialog$1.Root> & Partial<React.ComponentProps<typeof Drawer>> & {
+  snap?: boolean;
+}): React.JSX.Element;
+/**
+ * The element that opens the responsive dialog/drawer when activated.
+ *
+ * - **Desktop** → `DialogTrigger` (Radix `Dialog.Trigger`)
+ * - **Mobile** → `DrawerTrigger` (Vaul `Drawer.Trigger`)
+ *
+ * Use `asChild` to render your own element as the trigger instead of
+ * the default button wrapper.
+ *
+ * @example
+ * <ResponsiveDialogTrigger asChild>
+ *   <Button variant="outline">Open</Button>
+ * </ResponsiveDialogTrigger>
+ */
+declare function ResponsiveDialogTrigger({
+  children,
+  ...props
+}: React.ComponentProps<typeof Dialog$1.Trigger>): React.JSX.Element;
+/**
+ * A close trigger that targets the correct primitive for the current
+ * viewport:
+ * - **Desktop** → `DialogClose` (Radix `Dialog.Close`)
+ * - **Mobile** → `DrawerClose` (Vaul `Drawer.Close`)
+ *
+ * Use `asChild` to wrap a custom element.
+ *
+ * @example
+ * <ResponsiveDialogClose asChild>
+ *   <Button variant="ghost">Cancel</Button>
+ * </ResponsiveDialogClose>
+ */
+declare function ResponsiveDialogClose({
+  children,
+  ...props
+}: React.ComponentProps<typeof Dialog$1.Close>): React.JSX.Element;
+/**
+ * The visible panel of the responsive dialog. Delegates to the
+ * appropriate primitive:
+ * - **Desktop** → `DialogContent` — centred modal with fade + zoom animations.
+ *   The ✕ close button is shown by default (`showCloseButton={true}`).
+ * - **Mobile** → `DrawerContent` — bottom-sheet panel with a drag handle.
+ *   `showCloseButton` has **no effect** on mobile; the drawer is closed
+ *   via swipe gesture or the drag handle.
+ *
+ * @param showCloseButton - Show/hide the ✕ button in the top-right corner
+ *   on desktop. Has no effect on mobile. Defaults to `true`.
+ *
+ * @example
+ * // Hide the ✕ button and force close via footer only (desktop)
+ * <ResponsiveDialogContent showCloseButton={false}>
+ *   ...
+ * </ResponsiveDialogContent>
+ */
+declare function ResponsiveDialogContent({
+  className,
+  children,
+  showCloseButton,
+  ...props
+}: React.ComponentProps<typeof Dialog$1.Content> & {
+  showCloseButton?: boolean;
+}): React.JSX.Element;
+/**
+ * Layout wrapper for the **top section** of the responsive dialog/drawer.
+ *
+ * - **Desktop** → `DialogHeader` — vertical stack with `gap-2`
+ * - **Mobile** → `DrawerHeader` — vertically centred text for bottom/top
+ *   drawers, left-aligned for side drawers
+ *
+ * Typically contains `ResponsiveDialogTitle` and optionally
+ * `ResponsiveDialogDescription`.
+ */
+declare function ResponsiveDialogHeader({
+  className,
+  leftNode,
+  rightNode,
+  children,
+  ...props
+}: React.ComponentProps<"div"> & {
+  leftNode?: React.ReactNode;
+  rightNode?: React.ReactNode;
+}): React.JSX.Element;
+/**
+ * Layout wrapper for the **bottom action area** of the responsive
+ * dialog/drawer.
+ *
+ * - **Desktop** → `DialogFooter` — bleeds to panel edges, top border,
+ *   actions aligned right on `sm+`
+ * - **Mobile** → `DrawerFooter` — `mt-auto` stacked column at the bottom
+ *   of the drawer
+ *
+ * @param showCloseButton - When `true`, appends a close button after
+ *   `children`. On **desktop** this is a `DialogClose`-wrapped outline
+ *   button; on **mobile** this is a `DrawerClose`-wrapped outline button.
+ *   Defaults to `false`.
+ *
+ * @example
+ * <ResponsiveDialogFooter showCloseButton>
+ *   <Button type="submit">Save</Button>
+ * </ResponsiveDialogFooter>
+ */
+declare function ResponsiveDialogFooter({
+  className,
+  children,
+  showCloseButton,
+  ...props
+}: React.ComponentProps<"div"> & {
+  showCloseButton?: boolean;
+}): React.JSX.Element;
+/**
+ * The **accessible title** of the responsive dialog/drawer.
+ *
+ * - **Desktop** → `DialogTitle` (linked via `aria-labelledby`)
+ * - **Mobile** → `DrawerTitle` (linked via `aria-labelledby`)
+ *
+ * Screen readers announce this text when the panel opens.
+ *
+ * @remarks Required for accessibility on both desktop and mobile.
+ */
+declare function ResponsiveDialogTitle({
+  className,
+  ...props
+}: React.ComponentProps<typeof Dialog$1.Title>): React.JSX.Element;
+/**
+ * The **accessible description** of the responsive dialog/drawer.
+ *
+ * - **Desktop** → `DialogDescription` (linked via `aria-describedby`)
+ * - **Mobile** → `DrawerDescription` (linked via `aria-describedby`)
+ *
+ * @remarks Optional but recommended. Provides supplementary context for
+ * screen reader users after the title is announced.
+ */
+declare function ResponsiveDialogDescription({
+  className,
+  ...props
+}: React.ComponentProps<typeof Dialog$1.Description>): React.JSX.Element;
+//#endregion
+export { Dialog, DialogClose, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogOverlay, DialogPortal, DialogTitle, DialogTrigger, ResponsiveDialog, ResponsiveDialogClose, ResponsiveDialogContent, ResponsiveDialogDescription, ResponsiveDialogFooter, ResponsiveDialogHeader, ResponsiveDialogTitle, ResponsiveDialogTrigger };