@mks2508/mks-ui 0.1.3 → 0.2.0

package/src/react/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/hooks/State/UseControlledState';
+import { getStrictContext } from '@/react/lib/get-strict-context';
+import { cn } from '@/react/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';

package/src/react/ui/DropdownMenu/DropdownMenu.styles.ts

@@ -0,0 +1,35 @@
+import type { StyleSlots } from '@/core/types';
+
+/** Visual regions for the DropdownMenu component family. */
+type DropdownMenuSlot =
+  | 'root'
+  | 'content'
+  | 'item'
+  | 'label'
+  | 'separator'
+  | 'shortcut'
+  | 'subTrigger'
+  | 'subContent'
+  | 'checkboxItem'
+  | 'radioItem';
+
+const dropdownMenuStyles: StyleSlots<DropdownMenuSlot> = {
+  root: '',
+  content:
+    'data-open:animate-in data-closed:animate-out data-closed:fade-out-0 data-open:fade-in-0 data-closed:zoom-out-95 data-open:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 ring-foreground/10 bg-popover text-popover-foreground min-w-32 rounded-lg p-1 shadow-md ring-1 duration-100 data-[side=inline-start]:slide-in-from-right-2 data-[side=inline-end]:slide-in-from-left-2 z-50 max-h-(--available-height) w-(--anchor-width) origin-(--transform-origin) overflow-x-hidden overflow-y-auto outline-none data-closed:overflow-hidden',
+  item: 'focus:bg-accent focus:text-accent-foreground data-[variant=destructive]:text-destructive data-[variant=destructive]:focus:bg-destructive/10 dark:data-[variant=destructive]:focus:bg-destructive/20 data-[variant=destructive]:focus:text-destructive data-[variant=destructive]:*:[svg]:text-destructive not-data-[variant=destructive]:focus:**:text-accent-foreground gap-1.5 rounded-md px-1.5 py-1 text-sm data-inset:pl-7 [&_svg:not([class*=\'size-\'])]:size-4 group/dropdown-menu-item relative flex cursor-default items-center outline-hidden select-none data-disabled:pointer-events-none data-disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0',
+  label: 'text-muted-foreground px-1.5 py-1 text-xs font-medium data-inset:pl-7',
+  separator: 'bg-border -mx-1 my-1 h-px',
+  shortcut: 'text-muted-foreground group-focus/dropdown-menu-item:text-accent-foreground ml-auto text-xs tracking-widest',
+  subTrigger:
+    'focus:bg-accent focus:text-accent-foreground data-open:bg-accent data-open:text-accent-foreground not-data-[variant=destructive]:focus:**:text-accent-foreground gap-1.5 rounded-md px-1.5 py-1 text-sm data-inset:pl-7 [&_svg:not([class*=\'size-\'])]:size-4 data-popup-open:bg-accent data-popup-open:text-accent-foreground flex cursor-default items-center outline-hidden select-none [&_svg]:pointer-events-none [&_svg]:shrink-0',
+  subContent:
+    'data-open:animate-in data-closed:animate-out data-closed:fade-out-0 data-open:fade-in-0 data-closed:zoom-out-95 data-open:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 ring-foreground/10 bg-popover text-popover-foreground min-w-[96px] rounded-md p-1 shadow-lg ring-1 duration-100 w-auto',
+  checkboxItem:
+    'focus:bg-accent focus:text-accent-foreground focus:**:text-accent-foreground gap-1.5 rounded-md py-1 pr-8 pl-1.5 text-sm data-inset:pl-7 [&_svg:not([class*=\'size-\'])]:size-4 relative flex cursor-default items-center outline-hidden select-none data-disabled:pointer-events-none data-disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0',
+  radioItem:
+    'focus:bg-accent focus:text-accent-foreground focus:**:text-accent-foreground gap-1.5 rounded-md py-1 pr-8 pl-1.5 text-sm data-inset:pl-7 [&_svg:not([class*=\'size-\'])]:size-4 relative flex cursor-default items-center outline-hidden select-none data-disabled:pointer-events-none data-disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0',
+};
+
+export { dropdownMenuStyles };
+export type { DropdownMenuSlot };

package/src/react/ui/DropdownMenu/DropdownMenu.types.ts

@@ -0,0 +1,81 @@
+import type { Menu as MenuPrimitive } from '@base-ui/react/menu';
+import type { SlotOverrides } from '@/core/types';
+import type { DropdownMenuSlot } from './DropdownMenu.styles';
+
+/** Props for the DropdownMenu root. */
+type IDropdownMenuProps = MenuPrimitive.Root.Props;
+
+/** Props for DropdownMenuPortal. */
+type IDropdownMenuPortalProps = MenuPrimitive.Portal.Props;
+
+/** Props for DropdownMenuTrigger. */
+type IDropdownMenuTriggerProps = MenuPrimitive.Trigger.Props;
+
+/** Props for DropdownMenuContent. */
+interface IDropdownMenuContentProps
+  extends MenuPrimitive.Popup.Props,
+    Pick<MenuPrimitive.Positioner.Props, 'align' | 'alignOffset' | 'side' | 'sideOffset'> {
+  /** Override classes for dropdown menu visual regions. */
+  slots?: SlotOverrides<DropdownMenuSlot>;
+}
+
+/** Props for DropdownMenuGroup. */
+type IDropdownMenuGroupProps = MenuPrimitive.Group.Props;
+
+/** Props for DropdownMenuLabel. */
+interface IDropdownMenuLabelProps extends MenuPrimitive.GroupLabel.Props {
+  /** Indent the label to align with items that have icons. */
+  inset?: boolean;
+}
+
+/** Props for DropdownMenuItem. */
+interface IDropdownMenuItemProps extends MenuPrimitive.Item.Props {
+  /** Indent the item. */
+  inset?: boolean;
+  /** Visual style variant. */
+  variant?: 'default' | 'destructive';
+}
+
+/** Props for DropdownMenuSub. */
+type IDropdownMenuSubProps = MenuPrimitive.SubmenuRoot.Props;
+
+/** Props for DropdownMenuSubTrigger. */
+interface IDropdownMenuSubTriggerProps extends MenuPrimitive.SubmenuTrigger.Props {
+  inset?: boolean;
+}
+
+/** Props for DropdownMenuCheckboxItem. */
+interface IDropdownMenuCheckboxItemProps extends MenuPrimitive.CheckboxItem.Props {
+  inset?: boolean;
+}
+
+/** Props for DropdownMenuRadioGroup. */
+type IDropdownMenuRadioGroupProps = MenuPrimitive.RadioGroup.Props;
+
+/** Props for DropdownMenuRadioItem. */
+interface IDropdownMenuRadioItemProps extends MenuPrimitive.RadioItem.Props {
+  inset?: boolean;
+}
+
+/** Props for DropdownMenuSeparator. */
+type IDropdownMenuSeparatorProps = MenuPrimitive.Separator.Props;
+
+/** Props for DropdownMenuShortcut. */
+type IDropdownMenuShortcutProps = React.ComponentProps<'span'>;
+
+export type {
+  IDropdownMenuProps,
+  IDropdownMenuPortalProps,
+  IDropdownMenuTriggerProps,
+  IDropdownMenuContentProps,
+  IDropdownMenuGroupProps,
+  IDropdownMenuLabelProps,
+  IDropdownMenuItemProps,
+  IDropdownMenuSubProps,
+  IDropdownMenuSubTriggerProps,
+  IDropdownMenuCheckboxItemProps,
+  IDropdownMenuRadioGroupProps,
+  IDropdownMenuRadioItemProps,
+  IDropdownMenuSeparatorProps,
+  IDropdownMenuShortcutProps,
+};