@mks2508/mks-ui 0.2.0 → 0.3.1

package/src/react-ui/ui/Dialog/index.tsx

@@ -0,0 +1,452 @@
+'use client';
+
+/**
+ * Animated Dialog component built on Base UI Dialog and Motion.
+ *
+ * Provides a modal dialog overlay with perspective-flip entrance animation,
+ * animated backdrop, and full AnimatePresence exit support. All sub-components
+ * accept a `slots` prop for class-name overrides following the StyleSlots pattern.
+ *
+ * @module @mks2508/mks-ui/react/ui/Dialog
+ *
+ * @example
+ * ```tsx
+ * import {
+ *   Dialog,
+ *   DialogTrigger,
+ *   DialogPortal,
+ *   DialogBackdrop,
+ *   DialogPopup,
+ *   DialogHeader,
+ *   DialogTitle,
+ *   DialogDescription,
+ *   DialogFooter,
+ *   DialogClose,
+ * } from '@mks2508/mks-ui';
+ *
+ * function ConfirmDialog() {
+ *   return (
+ *     <Dialog>
+ *       <DialogTrigger>
+ *         <button>Delete Item</button>
+ *       </DialogTrigger>
+ *       <DialogPortal>
+ *         <DialogBackdrop />
+ *         <DialogPopup from="bottom">
+ *           <DialogHeader>
+ *             <DialogTitle>Confirm Deletion</DialogTitle>
+ *             <DialogDescription>This action cannot be undone.</DialogDescription>
+ *           </DialogHeader>
+ *           <DialogFooter>
+ *             <DialogClose><button>Cancel</button></DialogClose>
+ *             <button>Delete</button>
+ *           </DialogFooter>
+ *         </DialogPopup>
+ *       </DialogPortal>
+ *     </Dialog>
+ *   );
+ * }
+ * ```
+ */
+
+import * as React from 'react';
+import { Dialog as DialogPrimitive } from '@base-ui/react/dialog';
+import { AnimatePresence, motion } from 'motion/react';
+
+import { useControlledState } from '@/react-ui/hooks/State/UseControlledState';
+import { getStrictContext } from '@/react-ui/lib/get-strict-context';
+import { cn } from '@/react-ui/lib/utils';
+
+import { dialogStyles } from './Dialog.styles';
+import type {
+  DialogContextType,
+  DialogFlipDirection,
+  IDialogProps,
+  IDialogTriggerProps,
+  IDialogPortalProps,
+  IDialogBackdropProps,
+  IDialogPopupProps,
+  IDialogCloseProps,
+  IDialogHeaderProps,
+  IDialogFooterProps,
+  IDialogTitleProps,
+  IDialogDescriptionProps,
+} from './Dialog.types';
+
+/* -------------------------------------------------------------------------- */
+/*  Context                                                                   */
+/* -------------------------------------------------------------------------- */
+
+const [DialogProvider, useDialog] =
+  getStrictContext<DialogContextType>('DialogContext');
+
+/* -------------------------------------------------------------------------- */
+/*  Dialog (Root)                                                             */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Root Dialog component.
+ * Manages controlled/uncontrolled open state and provides context to children.
+ *
+ * @param props - Dialog root props including `open`, `defaultOpen`, and `onOpenChange`
+ *
+ * @example
+ * ```tsx
+ * <Dialog open={isOpen} onOpenChange={setIsOpen}>
+ *   {children}
+ * </Dialog>
+ * ```
+ */
+function Dialog(props: IDialogProps) {
+  const { slots, config: _config, ...rest } = props;
+
+  const [isOpen, setIsOpen] = useControlledState({
+    value: rest?.open,
+    defaultValue: rest?.defaultOpen,
+    onChange: rest?.onOpenChange,
+  });
+
+  return (
+    <DialogProvider value={{ isOpen, setIsOpen }}>
+      <DialogPrimitive.Root
+        data-slot="dialog"
+        {...rest}
+        onOpenChange={setIsOpen}
+      />
+    </DialogProvider>
+  );
+}
+
+/* -------------------------------------------------------------------------- */
+/*  DialogTrigger                                                             */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Trigger element that opens the dialog on interaction.
+ *
+ * @param props - Trigger props forwarded to Base UI Dialog.Trigger
+ *
+ * @example
+ * ```tsx
+ * <DialogTrigger>
+ *   <button>Open</button>
+ * </DialogTrigger>
+ * ```
+ */
+function DialogTrigger({ slots, className, ...props }: IDialogTriggerProps) {
+  return (
+    <DialogPrimitive.Trigger
+      data-slot="dialog-trigger"
+      className={cn(dialogStyles.root, slots?.root, className)}
+      {...props}
+    />
+  );
+}
+
+/* -------------------------------------------------------------------------- */
+/*  DialogPortal                                                              */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Portal wrapper with AnimatePresence for coordinated enter/exit animations.
+ * Internally sets `keepMounted` so motion exit animations play correctly.
+ *
+ * @param props - Portal props (without keepMounted)
+ *
+ * @example
+ * ```tsx
+ * <DialogPortal>
+ *   <DialogBackdrop />
+ *   <DialogPopup>...</DialogPopup>
+ * </DialogPortal>
+ * ```
+ */
+function DialogPortal({ slots: _slots, ...props }: IDialogPortalProps) {
+  const { isOpen } = useDialog();
+
+  return (
+    <AnimatePresence>
+      {isOpen && (
+        <DialogPrimitive.Portal
+          data-slot="dialog-portal"
+          keepMounted
+          {...props}
+        />
+      )}
+    </AnimatePresence>
+  );
+}
+
+/* -------------------------------------------------------------------------- */
+/*  DialogBackdrop                                                            */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Animated overlay backdrop behind the dialog popup.
+ * Uses a blur + fade entrance/exit animation via Motion.
+ *
+ * @param props - Backdrop props including motion transition overrides
+ *
+ * @example
+ * ```tsx
+ * <DialogBackdrop slots={{ backdrop: 'bg-black/60' }} />
+ * ```
+ */
+function DialogBackdrop({
+  slots,
+  className,
+  transition = { duration: 0.2, ease: 'easeInOut' },
+  ...props
+}: IDialogBackdropProps) {
+  return (
+    <DialogPrimitive.Backdrop
+      data-slot="dialog-backdrop"
+      render={
+        <motion.div
+          key="dialog-backdrop"
+          className={cn(dialogStyles.backdrop, slots?.backdrop, className)}
+          initial={{ opacity: 0, filter: 'blur(4px)' }}
+          animate={{ opacity: 1, filter: 'blur(0px)' }}
+          exit={{ opacity: 0, filter: 'blur(4px)' }}
+          transition={transition}
+          {...(props as any)}
+        />
+      }
+    />
+  );
+}
+
+/* -------------------------------------------------------------------------- */
+/*  DialogPopup                                                               */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Main dialog content container with a perspective-flip entrance animation.
+ * The `from` prop controls the axis and direction of the 3D rotation.
+ *
+ * @param props - Popup props including `from` direction and motion transition overrides
+ *
+ * @example
+ * ```tsx
+ * <DialogPopup from="bottom" className="max-w-md">
+ *   <DialogTitle>Confirm</DialogTitle>
+ *   <p>Are you sure?</p>
+ * </DialogPopup>
+ * ```
+ */
+function DialogPopup({
+  from = 'top',
+  initialFocus,
+  finalFocus,
+  slots,
+  className,
+  transition = { type: 'spring', stiffness: 150, damping: 25 },
+  ...props
+}: IDialogPopupProps) {
+  const initialRotation =
+    from === 'bottom' || from === 'left' ? '20deg' : '-20deg';
+  const isVertical = from === 'top' || from === 'bottom';
+  const rotateAxis = isVertical ? 'rotateX' : 'rotateY';
+
+  return (
+    <DialogPrimitive.Popup
+      initialFocus={initialFocus}
+      finalFocus={finalFocus}
+      render={
+        <motion.div
+          key="dialog-popup"
+          data-slot="dialog-popup"
+          className={cn(dialogStyles.popup, slots?.popup, className)}
+          initial={{
+            opacity: 0,
+            filter: 'blur(4px)',
+            transform: `perspective(500px) ${rotateAxis}(${initialRotation}) scale(0.8)`,
+          }}
+          animate={{
+            opacity: 1,
+            filter: 'blur(0px)',
+            transform: `perspective(500px) ${rotateAxis}(0deg) scale(1)`,
+          }}
+          exit={{
+            opacity: 0,
+            filter: 'blur(4px)',
+            transform: `perspective(500px) ${rotateAxis}(${initialRotation}) scale(0.8)`,
+          }}
+          transition={transition}
+          {...(props as any)}
+        />
+      }
+    />
+  );
+}
+
+/* -------------------------------------------------------------------------- */
+/*  DialogClose                                                               */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Button that closes the dialog when clicked.
+ *
+ * @param props - Close button props forwarded to Base UI Dialog.Close
+ *
+ * @example
+ * ```tsx
+ * <DialogClose slots={{ close: 'text-muted-foreground' }}>
+ *   <button>Cancel</button>
+ * </DialogClose>
+ * ```
+ */
+function DialogClose({ slots, className, ...props }: IDialogCloseProps) {
+  return (
+    <DialogPrimitive.Close
+      data-slot="dialog-close"
+      className={cn(dialogStyles.close, slots?.close, className)}
+      {...props}
+    />
+  );
+}
+
+/* -------------------------------------------------------------------------- */
+/*  DialogHeader                                                              */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Layout wrapper for the dialog header region (title + description).
+ *
+ * @param props - Standard div props with optional slot overrides
+ *
+ * @example
+ * ```tsx
+ * <DialogHeader>
+ *   <DialogTitle>Settings</DialogTitle>
+ *   <DialogDescription>Configure your preferences.</DialogDescription>
+ * </DialogHeader>
+ * ```
+ */
+function DialogHeader({ slots, className, ...props }: IDialogHeaderProps) {
+  return (
+    <div
+      data-slot="dialog-header"
+      className={cn(dialogStyles.header, slots?.header, className)}
+      {...props}
+    />
+  );
+}
+
+/* -------------------------------------------------------------------------- */
+/*  DialogFooter                                                              */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Layout wrapper for the dialog footer region (action buttons).
+ *
+ * @param props - Standard div props with optional slot overrides
+ *
+ * @example
+ * ```tsx
+ * <DialogFooter>
+ *   <DialogClose><button>Cancel</button></DialogClose>
+ *   <button>Confirm</button>
+ * </DialogFooter>
+ * ```
+ */
+function DialogFooter({ slots, className, ...props }: IDialogFooterProps) {
+  return (
+    <div
+      data-slot="dialog-footer"
+      className={cn(dialogStyles.footer, slots?.footer, className)}
+      {...props}
+    />
+  );
+}
+
+/* -------------------------------------------------------------------------- */
+/*  DialogTitle                                                               */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Accessible title for the dialog. Rendered as a heading element.
+ *
+ * @param props - Title props forwarded to Base UI Dialog.Title
+ *
+ * @example
+ * ```tsx
+ * <DialogTitle>Delete Workspace</DialogTitle>
+ * ```
+ */
+function DialogTitle({ slots, className, ...props }: IDialogTitleProps) {
+  return (
+    <DialogPrimitive.Title
+      data-slot="dialog-title"
+      className={cn(dialogStyles.title, slots?.title, className)}
+      {...props}
+    />
+  );
+}
+
+/* -------------------------------------------------------------------------- */
+/*  DialogDescription                                                         */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Accessible description for the dialog. Provides supplementary context.
+ *
+ * @param props - Description props forwarded to Base UI Dialog.Description
+ *
+ * @example
+ * ```tsx
+ * <DialogDescription>This will permanently remove the workspace.</DialogDescription>
+ * ```
+ */
+function DialogDescription({
+  slots,
+  className,
+  ...props
+}: IDialogDescriptionProps) {
+  return (
+    <DialogPrimitive.Description
+      data-slot="dialog-description"
+      className={cn(dialogStyles.description, slots?.description, className)}
+      {...props}
+    />
+  );
+}
+
+/* -------------------------------------------------------------------------- */
+/*  Exports                                                                   */
+/* -------------------------------------------------------------------------- */
+
+export {
+  Dialog,
+  DialogPortal,
+  DialogBackdrop,
+  DialogClose,
+  DialogTrigger,
+  DialogPopup,
+  DialogHeader,
+  DialogFooter,
+  DialogTitle,
+  DialogDescription,
+  useDialog,
+};
+
+// Re-exports from types
+export type {
+  IDialogProps,
+  IDialogTriggerProps,
+  IDialogPortalProps,
+  IDialogCloseProps,
+  IDialogBackdropProps,
+  IDialogPopupProps,
+  IDialogHeaderProps,
+  IDialogFooterProps,
+  IDialogTitleProps,
+  IDialogDescriptionProps,
+  DialogContextType,
+  DialogFlipDirection,
+  DialogSlot,
+  IDialogConfig,
+} from './Dialog.types';
+
+// Re-exports from styles
+export { dialogStyles } from './Dialog.styles';