@mks2508/mks-ui 0.1.3 → 0.2.0

package/src/react/ui/AlertDialog/index.tsx

@@ -0,0 +1,540 @@
+'use client';
+
+/**
+ * AlertDialog component with animated 3D flip entrance.
+ *
+ * Built on top of Base UI's AlertDialog primitive with Motion (Framer Motion)
+ * animations. Features a perspective-based flip animation from configurable
+ * directions, backdrop blur effects, and the StyleSlots pattern for granular
+ * style overrides.
+ *
+ * AlertDialog is specifically designed for destructive or important confirmations
+ * that require explicit user acknowledgment. Unlike Dialog, it blocks interaction
+ * with the rest of the page.
+ *
+ * @module @mks2508/mks-ui/react/ui/AlertDialog
+ *
+ * @example
+ * ```tsx
+ * import {
+ *   AlertDialog,
+ *   AlertDialogTrigger,
+ *   AlertDialogPortal,
+ *   AlertDialogBackdrop,
+ *   AlertDialogPopup,
+ *   AlertDialogHeader,
+ *   AlertDialogFooter,
+ *   AlertDialogTitle,
+ *   AlertDialogDescription,
+ *   AlertDialogClose,
+ * } from '@mks2508/mks-ui';
+ *
+ * function DeleteConfirmation() {
+ *   return (
+ *     <AlertDialog>
+ *       <AlertDialogTrigger>Delete Account</AlertDialogTrigger>
+ *       <AlertDialogPortal>
+ *         <AlertDialogBackdrop />
+ *         <AlertDialogPopup from="top">
+ *           <AlertDialogHeader>
+ *             <AlertDialogTitle>Are you absolutely sure?</AlertDialogTitle>
+ *             <AlertDialogDescription>
+ *               This action cannot be undone.
+ *             </AlertDialogDescription>
+ *           </AlertDialogHeader>
+ *           <AlertDialogFooter>
+ *             <AlertDialogClose>Cancel</AlertDialogClose>
+ *             <button>Delete</button>
+ *           </AlertDialogFooter>
+ *         </AlertDialogPopup>
+ *       </AlertDialogPortal>
+ *     </AlertDialog>
+ *   );
+ * }
+ * ```
+ */
+
+import * as React from 'react';
+import { AlertDialog as AlertDialogPrimitive } from '@base-ui/react/alert-dialog';
+import { AnimatePresence, motion } from 'motion/react';
+
+import { cn } from '@/react/lib/utils';
+import { getStrictContext } from '@/react/lib/get-strict-context';
+import { useControlledState } from '@/react/hooks/State/UseControlledState';
+
+import { AlertDialogStyles } from './AlertDialog.styles';
+import type {
+  AlertDialogContextType,
+  IAlertDialogProps,
+  IAlertDialogTriggerProps,
+  IAlertDialogPortalProps,
+  IAlertDialogBackdropProps,
+  IAlertDialogPopupProps,
+  IAlertDialogCloseProps,
+  IAlertDialogHeaderProps,
+  IAlertDialogFooterProps,
+  IAlertDialogTitleProps,
+  IAlertDialogDescriptionProps,
+} from './AlertDialog.types';
+
+// ---------------------------------------------------------------------------
+// Context
+// ---------------------------------------------------------------------------
+
+const [AlertDialogProvider, useAlertDialog] =
+  getStrictContext<AlertDialogContextType>('AlertDialogContext');
+
+// ---------------------------------------------------------------------------
+// AlertDialog (root)
+// ---------------------------------------------------------------------------
+
+/**
+ * Root AlertDialog component. Manages open state and provides context
+ * to all child sub-components.
+ *
+ * Supports both controlled (`open` + `onOpenChange`) and uncontrolled
+ * (`defaultOpen`) usage patterns.
+ *
+ * @param props - {@link IAlertDialogProps}
+ * @returns The rendered alert dialog root
+ *
+ * @example
+ * ```tsx
+ * // Uncontrolled
+ * <AlertDialog>
+ *   <AlertDialogTrigger>Open</AlertDialogTrigger>
+ *   <AlertDialogPortal>...</AlertDialogPortal>
+ * </AlertDialog>
+ *
+ * // Controlled
+ * const [open, setOpen] = useState(false);
+ * <AlertDialog open={open} onOpenChange={setOpen}>
+ *   ...
+ * </AlertDialog>
+ * ```
+ */
+function AlertDialog({
+  slots: _slots,
+  config: _config,
+  ...props
+}: IAlertDialogProps) {
+  const [isOpen, setIsOpen] = useControlledState({
+    value: props?.open,
+    defaultValue: props?.defaultOpen,
+    onChange: props?.onOpenChange,
+  });
+
+  return (
+    <AlertDialogProvider value={{ isOpen, setIsOpen }}>
+      <AlertDialogPrimitive.Root
+        data-slot="alert-dialog"
+        {...props}
+        onOpenChange={setIsOpen}
+      />
+    </AlertDialogProvider>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// AlertDialogTrigger
+// ---------------------------------------------------------------------------
+
+/**
+ * Button that opens the AlertDialog when clicked.
+ * Renders as a button element by default.
+ *
+ * @param props - {@link IAlertDialogTriggerProps}
+ * @returns The rendered trigger button
+ *
+ * @example
+ * ```tsx
+ * <AlertDialogTrigger className="bg-destructive text-destructive-foreground">
+ *   Delete Account
+ * </AlertDialogTrigger>
+ * ```
+ */
+function AlertDialogTrigger({
+  slots: _slots,
+  ...props
+}: IAlertDialogTriggerProps) {
+  return (
+    <AlertDialogPrimitive.Trigger
+      data-slot="alert-dialog-trigger"
+      {...props}
+    />
+  );
+}
+
+// ---------------------------------------------------------------------------
+// AlertDialogPortal
+// ---------------------------------------------------------------------------
+
+/**
+ * Portal wrapper that renders alert dialog content outside the DOM hierarchy.
+ * Manages AnimatePresence for enter/exit animations of the backdrop and popup.
+ *
+ * The portal is automatically kept mounted for exit animations and only
+ * renders its children when the dialog is open.
+ *
+ * @param props - {@link IAlertDialogPortalProps}
+ * @returns The rendered portal with AnimatePresence
+ *
+ * @example
+ * ```tsx
+ * <AlertDialogPortal>
+ *   <AlertDialogBackdrop />
+ *   <AlertDialogPopup>...</AlertDialogPopup>
+ * </AlertDialogPortal>
+ * ```
+ */
+function AlertDialogPortal(props: IAlertDialogPortalProps) {
+  const { isOpen } = useAlertDialog();
+
+  return (
+    <AnimatePresence>
+      {isOpen && (
+        <AlertDialogPrimitive.Portal
+          data-slot="alert-dialog-portal"
+          keepMounted
+          {...props}
+        />
+      )}
+    </AnimatePresence>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// AlertDialogBackdrop
+// ---------------------------------------------------------------------------
+
+/**
+ * Semi-transparent overlay behind the alert dialog.
+ * Animates in with a fade and optional blur effect.
+ *
+ * @param props - {@link IAlertDialogBackdropProps}
+ * @returns The rendered animated backdrop
+ *
+ * @example
+ * ```tsx
+ * // Default backdrop
+ * <AlertDialogBackdrop />
+ *
+ * // Custom backdrop with blur
+ * <AlertDialogBackdrop
+ *   className="bg-black/60 backdrop-blur-md"
+ *   transition={{ duration: 0.3 }}
+ * />
+ * ```
+ */
+function AlertDialogBackdrop({
+  transition = { duration: 0.2, ease: 'easeInOut' },
+  slots,
+  className,
+  ...props
+}: IAlertDialogBackdropProps) {
+  return (
+    <AlertDialogPrimitive.Backdrop
+      data-slot="alert-dialog-backdrop"
+      render={
+        <motion.div
+          key="alert-dialog-backdrop"
+          className={cn(
+            AlertDialogStyles.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)}
+        />
+      }
+    />
+  );
+}
+
+// ---------------------------------------------------------------------------
+// AlertDialogPopup
+// ---------------------------------------------------------------------------
+
+/**
+ * Main dialog container with a 3D perspective flip animation.
+ *
+ * The `from` prop controls which direction the dialog flips from:
+ * - `top` / `bottom` rotate around the X axis
+ * - `left` / `right` rotate around the Y axis
+ *
+ * Uses spring physics for a natural, bouncy entrance.
+ *
+ * @param props - {@link IAlertDialogPopupProps}
+ * @returns The rendered animated popup
+ *
+ * @example
+ * ```tsx
+ * // Flip from top (default)
+ * <AlertDialogPopup>...</AlertDialogPopup>
+ *
+ * // Flip from bottom with custom spring
+ * <AlertDialogPopup
+ *   from="bottom"
+ *   transition={{ type: 'spring', stiffness: 200, damping: 30 }}
+ * >
+ *   ...
+ * </AlertDialogPopup>
+ * ```
+ */
+function AlertDialogPopup({
+  from = 'top',
+  initialFocus,
+  finalFocus,
+  transition = { type: 'spring', stiffness: 150, damping: 25 },
+  slots,
+  className,
+  ...props
+}: IAlertDialogPopupProps) {
+  const initialRotation =
+    from === 'bottom' || from === 'left' ? '20deg' : '-20deg';
+  const isVertical = from === 'top' || from === 'bottom';
+  const rotateAxis = isVertical ? 'rotateX' : 'rotateY';
+
+  return (
+    <AlertDialogPrimitive.Popup
+      initialFocus={initialFocus}
+      finalFocus={finalFocus}
+      render={
+        <motion.div
+          key="alert-dialog-popup"
+          data-slot="alert-dialog-popup"
+          className={cn(AlertDialogStyles.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)}
+        />
+      }
+    />
+  );
+}
+
+// ---------------------------------------------------------------------------
+// AlertDialogClose
+// ---------------------------------------------------------------------------
+
+/**
+ * Button that closes the AlertDialog when clicked.
+ * Typically used in the footer alongside a confirm action.
+ *
+ * @param props - {@link IAlertDialogCloseProps}
+ * @returns The rendered close button
+ *
+ * @example
+ * ```tsx
+ * <AlertDialogClose className="border border-border px-4 py-2 rounded-md">
+ *   Cancel
+ * </AlertDialogClose>
+ * ```
+ */
+function AlertDialogClose({
+  slots,
+  className,
+  ...props
+}: IAlertDialogCloseProps) {
+  return (
+    <AlertDialogPrimitive.Close
+      data-slot="alert-dialog-close"
+      className={cn(AlertDialogStyles.close, slots?.close, className)}
+      {...props}
+    />
+  );
+}
+
+// ---------------------------------------------------------------------------
+// AlertDialogHeader
+// ---------------------------------------------------------------------------
+
+/**
+ * Layout wrapper for the dialog title and description.
+ * Provides consistent spacing and text alignment.
+ *
+ * @param props - {@link IAlertDialogHeaderProps}
+ * @returns The rendered header container
+ *
+ * @example
+ * ```tsx
+ * <AlertDialogHeader>
+ *   <AlertDialogTitle>Confirm Action</AlertDialogTitle>
+ *   <AlertDialogDescription>This cannot be undone.</AlertDialogDescription>
+ * </AlertDialogHeader>
+ * ```
+ */
+function AlertDialogHeader({
+  slots,
+  className,
+  ...props
+}: IAlertDialogHeaderProps) {
+  return (
+    <div
+      data-slot="alert-dialog-header"
+      className={cn(AlertDialogStyles.header, slots?.header, className)}
+      {...props}
+    />
+  );
+}
+
+// ---------------------------------------------------------------------------
+// AlertDialogFooter
+// ---------------------------------------------------------------------------
+
+/**
+ * Layout wrapper for dialog action buttons.
+ * Uses responsive flex layout: column on mobile, row on desktop.
+ *
+ * @param props - {@link IAlertDialogFooterProps}
+ * @returns The rendered footer container
+ *
+ * @example
+ * ```tsx
+ * <AlertDialogFooter>
+ *   <AlertDialogClose>Cancel</AlertDialogClose>
+ *   <Button variant="destructive" onClick={handleDelete}>
+ *     Delete
+ *   </Button>
+ * </AlertDialogFooter>
+ * ```
+ */
+function AlertDialogFooter({
+  slots,
+  className,
+  ...props
+}: IAlertDialogFooterProps) {
+  return (
+    <div
+      data-slot="alert-dialog-footer"
+      className={cn(AlertDialogStyles.footer, slots?.footer, className)}
+      {...props}
+    />
+  );
+}
+
+// ---------------------------------------------------------------------------
+// AlertDialogTitle
+// ---------------------------------------------------------------------------
+
+/**
+ * Title element for the AlertDialog.
+ * Automatically associated with the dialog for accessibility via Base UI.
+ *
+ * @param props - {@link IAlertDialogTitleProps}
+ * @returns The rendered title element
+ *
+ * @example
+ * ```tsx
+ * <AlertDialogTitle className="text-destructive">
+ *   Delete Workspace
+ * </AlertDialogTitle>
+ * ```
+ */
+function AlertDialogTitle({
+  slots,
+  className,
+  ...props
+}: IAlertDialogTitleProps) {
+  return (
+    <AlertDialogPrimitive.Title
+      data-slot="alert-dialog-title"
+      className={cn(AlertDialogStyles.title, slots?.title, className)}
+      {...props}
+    />
+  );
+}
+
+// ---------------------------------------------------------------------------
+// AlertDialogDescription
+// ---------------------------------------------------------------------------
+
+/**
+ * Description element for the AlertDialog.
+ * Provides additional context about the action being confirmed.
+ * Automatically associated with the dialog for accessibility via Base UI.
+ *
+ * @param props - {@link IAlertDialogDescriptionProps}
+ * @returns The rendered description element
+ *
+ * @example
+ * ```tsx
+ * <AlertDialogDescription>
+ *   This will permanently delete the workspace and all associated data.
+ *   This action cannot be undone.
+ * </AlertDialogDescription>
+ * ```
+ */
+function AlertDialogDescription({
+  slots,
+  className,
+  ...props
+}: IAlertDialogDescriptionProps) {
+  return (
+    <AlertDialogPrimitive.Description
+      data-slot="alert-dialog-description"
+      className={cn(
+        AlertDialogStyles.description,
+        slots?.description,
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Exports
+// ---------------------------------------------------------------------------
+
+export {
+  AlertDialog,
+  AlertDialogPortal,
+  AlertDialogBackdrop,
+  AlertDialogClose,
+  AlertDialogTrigger,
+  AlertDialogPopup,
+  AlertDialogHeader,
+  AlertDialogFooter,
+  AlertDialogTitle,
+  AlertDialogDescription,
+  useAlertDialog,
+};
+
+// Re-export types
+export type {
+  IAlertDialogProps,
+  IAlertDialogTriggerProps,
+  IAlertDialogPortalProps,
+  IAlertDialogCloseProps,
+  IAlertDialogBackdropProps,
+  IAlertDialogPopupProps,
+  IAlertDialogHeaderProps,
+  IAlertDialogFooterProps,
+  IAlertDialogTitleProps,
+  IAlertDialogDescriptionProps,
+  IAlertDialogConfig,
+  AlertDialogSlot,
+  AlertDialogContextType,
+  AlertDialogFlipDirection,
+} from './AlertDialog.types';
+
+// Re-export styles
+export { AlertDialogStyles } from './AlertDialog.styles';

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

@@ -0,0 +1,43 @@
+import { cva } from 'class-variance-authority';
+import type { StyleSlots } from '@/core/types';
+
+/** Visual regions for the Badge component. */
+type BadgeSlot = 'root';
+
+const badgeStyles: StyleSlots<BadgeSlot> = {
+  root: 'inline-flex items-center justify-center rounded-full border font-semibold transition-colors focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2',
+};
+
+/**
+ * CVA variants for the Badge root.
+ *
+ * @see {@link https://cva.style/docs/getting-started/variants}
+ */
+const badgeVariants = cva(
+  'inline-flex items-center justify-center rounded-full border px-2.5 py-0.5 text-xs font-semibold transition-colors focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2',
+  {
+    variants: {
+      variant: {
+        default:
+          'border-transparent bg-primary text-primary-foreground hover:bg-primary/80',
+        secondary:
+          'border-transparent bg-secondary text-secondary-foreground hover:bg-secondary/80',
+        destructive:
+          'border-transparent bg-destructive text-destructive-foreground hover:bg-destructive/80',
+        outline: 'text-foreground',
+      },
+      size: {
+        default: 'h-6 px-2.5 py-0.5',
+        sm: 'h-5 px-2 text-[10px]',
+        lg: 'h-7 px-3 text-sm',
+      },
+    },
+    defaultVariants: {
+      variant: 'default',
+      size: 'default',
+    },
+  },
+);
+
+export { badgeStyles, badgeVariants };
+export type { BadgeSlot };

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

@@ -0,0 +1,26 @@
+import type { VariantProps } from 'class-variance-authority';
+import type { SlotOverrides } from '@/core/types';
+import type { badgeVariants, BadgeSlot } from './Badge.styles';
+
+/**
+ * Props for the Badge component.
+ *
+ * @example
+ * ```tsx
+ * <Badge variant="secondary" size="sm">New</Badge>
+ * ```
+ */
+interface IBadgeProps
+  extends React.HTMLAttributes<HTMLDivElement>,
+    VariantProps<typeof badgeVariants> {
+  /** Override classes for badge visual regions. */
+  slots?: SlotOverrides<BadgeSlot>;
+}
+
+/** Available badge variants. */
+type BadgeVariant = 'default' | 'secondary' | 'destructive' | 'outline';
+
+/** Available badge sizes. */
+type BadgeSize = 'default' | 'sm' | 'lg';
+
+export type { IBadgeProps, BadgeVariant, BadgeSize };

package/src/react/ui/Badge/index.tsx

@@ -0,0 +1,34 @@
+import * as React from 'react';
+
+import { cn } from '@/react/lib/utils';
+import { badgeVariants } from './Badge.styles';
+import type { IBadgeProps } from './Badge.types';
+
+/**
+ * Badge — displays status labels, categories, or indicators.
+ *
+ * @param variant - Visual style: 'default', 'secondary', 'destructive', 'outline'
+ * @param size - Badge size: 'default', 'sm', 'lg'
+ * @param slots - Override classes for badge visual regions
+ *
+ * @example
+ * ```tsx
+ * <Badge variant="secondary">New</Badge>
+ * <Badge variant="destructive" size="sm">Error</Badge>
+ * ```
+ */
+function Badge({ className, variant, size, slots, ...props }: IBadgeProps) {
+  return (
+    <div
+      data-slot="badge"
+      data-variant={variant}
+      data-size={size}
+      className={cn(badgeVariants({ variant, size }), slots?.root, className)}
+      {...props}
+    />
+  );
+}
+
+export { Badge, badgeVariants };
+export type { IBadgeProps, BadgeVariant, BadgeSize } from './Badge.types';
+export type { BadgeSlot } from './Badge.styles';

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

@@ -0,0 +1,57 @@
+import { cva } from 'class-variance-authority';
+import type { StyleSlots } from '@/core/types';
+
+/** Visual regions for the Button component. */
+type ButtonSlot = 'root';
+
+const buttonStyles: StyleSlots<ButtonSlot> = {
+  root: 'inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-md font-medium transition-all focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0',
+};
+
+/**
+ * CVA variants for the Button root.
+ *
+ * @see {@link https://cva.style/docs/getting-started/variants}
+ */
+const buttonVariants = cva(
+  'inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-md text-sm font-medium transition-all focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0 active:scale-[0.98]',
+  {
+    variants: {
+      variant: {
+        default:
+          'bg-primary text-primary-foreground hover:bg-primary/90',
+        secondary:
+          'bg-secondary text-secondary-foreground hover:bg-secondary/80',
+        destructive:
+          'bg-destructive text-destructive-foreground hover:bg-destructive/90',
+        outline:
+          'border border-input bg-background hover:bg-accent hover:text-accent-foreground',
+        ghost: 'hover:bg-accent hover:text-accent-foreground',
+        link: 'text-primary underline-offset-4 hover:underline',
+        success:
+          'bg-emerald-600 text-white hover:bg-emerald-700 focus-visible:ring-emerald-600',
+        warning:
+          'bg-amber-500 text-white hover:bg-amber-600 focus-visible:ring-amber-500',
+      },
+      size: {
+        default: 'h-10 px-4 py-2',
+        sm: 'h-9 rounded-md px-3 text-xs',
+        lg: 'h-11 rounded-md px-8 text-base',
+        icon: 'h-10 w-10 p-0',
+      },
+    },
+    defaultVariants: {
+      variant: 'default',
+      size: 'default',
+    },
+  },
+);
+
+/** State-specific style classes for Button. */
+const buttonStateStyles = {
+  pressed: 'scale-[0.98]',
+  disabled: 'opacity-50 pointer-events-none',
+};
+
+export { buttonStyles, buttonVariants, buttonStateStyles };
+export type { ButtonSlot };