@mks2508/mks-ui 0.1.3 → 0.2.0

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

@@ -0,0 +1,296 @@
+/**
+ * Type definitions for the AlertDialog component.
+ *
+ * All interfaces follow the IPrefix convention. Type aliases do not.
+ * Slot types define the visual regions available for style overrides.
+ *
+ * @module @mks2508/mks-ui/react/ui/AlertDialog/AlertDialog.types
+ */
+
+import type { AlertDialog as AlertDialogPrimitive } from '@base-ui/react/alert-dialog';
+import type { HTMLMotionProps } from 'motion/react';
+
+import type { IBaseConfig, SlotOverrides } from '@/core/types';
+
+// ---------------------------------------------------------------------------
+// Slot type
+// ---------------------------------------------------------------------------
+
+/**
+ * Named visual regions of the AlertDialog that can be styled via the `slots` prop.
+ *
+ * | Slot          | Element                                        |
+ * |---------------|------------------------------------------------|
+ * | `root`        | Logical root (no DOM element by default)        |
+ * | `backdrop`    | Semi-transparent overlay behind the dialog       |
+ * | `popup`       | Main dialog container with flip animation        |
+ * | `header`      | Header area containing title and description     |
+ * | `footer`      | Footer area for action buttons                   |
+ * | `title`       | Dialog title text                                |
+ * | `description` | Descriptive text below the title                 |
+ * | `close`       | Close/cancel button                              |
+ *
+ * @example
+ * ```tsx
+ * <AlertDialogPopup slots={{ popup: 'bg-zinc-950 border-cyan-500/20' }}>
+ *   ...
+ * </AlertDialogPopup>
+ * ```
+ */
+export type AlertDialogSlot =
+  | 'root'
+  | 'backdrop'
+  | 'popup'
+  | 'header'
+  | 'footer'
+  | 'title'
+  | 'description'
+  | 'close';
+
+// ---------------------------------------------------------------------------
+// Direction type
+// ---------------------------------------------------------------------------
+
+/**
+ * Direction from which the AlertDialog flips into view.
+ * Controls the 3D perspective rotation axis and initial angle.
+ *
+ * @example
+ * ```tsx
+ * <AlertDialogPopup from="bottom">...</AlertDialogPopup>
+ * ```
+ */
+export type AlertDialogFlipDirection = 'top' | 'bottom' | 'left' | 'right';
+
+// ---------------------------------------------------------------------------
+// Context types (no IPrefix)
+// ---------------------------------------------------------------------------
+
+/**
+ * Internal context for the AlertDialog root, tracks open state.
+ */
+export type AlertDialogContextType = {
+  /** Whether the dialog is currently open. */
+  isOpen: boolean;
+  /** Callback to update open state. */
+  setIsOpen: IAlertDialogProps['onOpenChange'];
+};
+
+// ---------------------------------------------------------------------------
+// Config (IPrefix)
+// ---------------------------------------------------------------------------
+
+/**
+ * Behavioral configuration for the AlertDialog component.
+ * Extends {@link IBaseConfig} with alert-dialog-specific options.
+ *
+ * @example
+ * ```tsx
+ * <AlertDialog config={{ from: 'bottom', animation: { duration: 0.3 } }} />
+ * ```
+ */
+export interface IAlertDialogConfig extends IBaseConfig {
+  /**
+   * Direction from which the dialog popup flips into view.
+   * Passed down to AlertDialogPopup if not set directly on the popup.
+   *
+   * @default 'top'
+   */
+  from?: AlertDialogFlipDirection;
+}
+
+// ---------------------------------------------------------------------------
+// Component prop interfaces (IPrefix)
+// ---------------------------------------------------------------------------
+
+/**
+ * Props for the root AlertDialog component.
+ *
+ * @example
+ * ```tsx
+ * <AlertDialog defaultOpen={false} onOpenChange={(open) => console.log(open)}>
+ *   <AlertDialogTrigger>Open</AlertDialogTrigger>
+ *   <AlertDialogPortal>
+ *     <AlertDialogBackdrop />
+ *     <AlertDialogPopup>...</AlertDialogPopup>
+ *   </AlertDialogPortal>
+ * </AlertDialog>
+ * ```
+ */
+export interface IAlertDialogProps
+  extends React.ComponentProps<typeof AlertDialogPrimitive.Root> {
+  /** Style overrides for individual visual regions. */
+  slots?: SlotOverrides<AlertDialogSlot>;
+  /** Behavioral configuration. */
+  config?: IAlertDialogConfig;
+}
+
+/**
+ * Props for the AlertDialogTrigger button.
+ *
+ * @example
+ * ```tsx
+ * <AlertDialogTrigger className="bg-destructive text-white">
+ *   Delete Account
+ * </AlertDialogTrigger>
+ * ```
+ */
+export interface IAlertDialogTriggerProps
+  extends React.ComponentProps<typeof AlertDialogPrimitive.Trigger> {
+  /** Style overrides for individual visual regions. */
+  slots?: SlotOverrides<AlertDialogSlot>;
+}
+
+/**
+ * Props for the AlertDialogPortal.
+ * The `keepMounted` prop is omitted because it is managed internally
+ * by the AnimatePresence animation logic.
+ *
+ * @example
+ * ```tsx
+ * <AlertDialogPortal>
+ *   <AlertDialogBackdrop />
+ *   <AlertDialogPopup>...</AlertDialogPopup>
+ * </AlertDialogPortal>
+ * ```
+ */
+export interface IAlertDialogPortalProps
+  extends Omit<
+    React.ComponentProps<typeof AlertDialogPrimitive.Portal>,
+    'keepMounted'
+  > {}
+
+/**
+ * Props for the AlertDialogBackdrop overlay.
+ *
+ * Extends Motion's HTMLMotionProps for full animation control.
+ * The `render` prop from the base primitive is omitted because
+ * it is managed internally by the motion wrapper.
+ *
+ * @example
+ * ```tsx
+ * <AlertDialogBackdrop
+ *   transition={{ duration: 0.3 }}
+ *   className="bg-black/60 backdrop-blur-sm"
+ * />
+ * ```
+ */
+export interface IAlertDialogBackdropProps
+  extends Omit<
+      Omit<React.ComponentProps<typeof AlertDialogPrimitive.Backdrop>, 'render'>,
+      keyof HTMLMotionProps<'div'>
+    >,
+    HTMLMotionProps<'div'> {
+  /** Style overrides for individual visual regions. */
+  slots?: SlotOverrides<AlertDialogSlot>;
+}
+
+/**
+ * Props for the AlertDialogPopup container.
+ *
+ * Extends Motion's HTMLMotionProps for full animation control.
+ * The `render` prop from the base primitive is omitted because
+ * it is managed internally by the motion wrapper.
+ *
+ * @example
+ * ```tsx
+ * <AlertDialogPopup from="bottom" className="max-w-md">
+ *   <AlertDialogHeader>...</AlertDialogHeader>
+ *   <AlertDialogFooter>...</AlertDialogFooter>
+ * </AlertDialogPopup>
+ * ```
+ */
+export interface IAlertDialogPopupProps
+  extends Omit<
+      Omit<React.ComponentProps<typeof AlertDialogPrimitive.Popup>, 'render'>,
+      keyof HTMLMotionProps<'div'>
+    >,
+    HTMLMotionProps<'div'> {
+  /**
+   * Direction from which the popup flips into view.
+   * Controls 3D perspective rotation.
+   *
+   * @default 'top'
+   */
+  from?: AlertDialogFlipDirection;
+  /** Style overrides for individual visual regions. */
+  slots?: SlotOverrides<AlertDialogSlot>;
+}
+
+/**
+ * Props for the AlertDialogClose button.
+ *
+ * @example
+ * ```tsx
+ * <AlertDialogClose className="border-border">Cancel</AlertDialogClose>
+ * ```
+ */
+export interface IAlertDialogCloseProps
+  extends React.ComponentProps<typeof AlertDialogPrimitive.Close> {
+  /** Style overrides for individual visual regions. */
+  slots?: SlotOverrides<AlertDialogSlot>;
+}
+
+/**
+ * Props for the AlertDialogHeader layout wrapper.
+ *
+ * @example
+ * ```tsx
+ * <AlertDialogHeader>
+ *   <AlertDialogTitle>Are you sure?</AlertDialogTitle>
+ *   <AlertDialogDescription>This cannot be undone.</AlertDialogDescription>
+ * </AlertDialogHeader>
+ * ```
+ */
+export interface IAlertDialogHeaderProps extends React.ComponentProps<'div'> {
+  /** Style overrides for individual visual regions. */
+  slots?: SlotOverrides<AlertDialogSlot>;
+}
+
+/**
+ * Props for the AlertDialogFooter layout wrapper.
+ *
+ * @example
+ * ```tsx
+ * <AlertDialogFooter>
+ *   <AlertDialogClose>Cancel</AlertDialogClose>
+ *   <Button variant="destructive">Delete</Button>
+ * </AlertDialogFooter>
+ * ```
+ */
+export interface IAlertDialogFooterProps extends React.ComponentProps<'div'> {
+  /** Style overrides for individual visual regions. */
+  slots?: SlotOverrides<AlertDialogSlot>;
+}
+
+/**
+ * Props for the AlertDialogTitle text element.
+ *
+ * @example
+ * ```tsx
+ * <AlertDialogTitle className="text-destructive">
+ *   Confirm Deletion
+ * </AlertDialogTitle>
+ * ```
+ */
+export interface IAlertDialogTitleProps
+  extends React.ComponentProps<typeof AlertDialogPrimitive.Title> {
+  /** Style overrides for individual visual regions. */
+  slots?: SlotOverrides<AlertDialogSlot>;
+}
+
+/**
+ * Props for the AlertDialogDescription text element.
+ *
+ * @example
+ * ```tsx
+ * <AlertDialogDescription>
+ *   This action is permanent and cannot be reversed.
+ * </AlertDialogDescription>
+ * ```
+ */
+export interface IAlertDialogDescriptionProps
+  extends React.ComponentProps<typeof AlertDialogPrimitive.Description> {
+  /** Style overrides for individual visual regions. */
+  slots?: SlotOverrides<AlertDialogSlot>;
+}