@jmruthers/pace-core 0.6.4 → 0.6.6

package/src/components/Dialog/Dialog.tsx

@@ -4,7 +4,7 @@
  * @module Components/Dialog
  * @since 0.1.0
  *
- * A comprehensive dialog component system built on top of Radix UI primitives.
+ * A comprehensive dialog component system using native HTML `<dialog>` element.
  * Provides accessible modal dialogs with focus management and keyboard navigation.
  * Uses semantic HTML elements including native <dialog> element for maximum accessibility.
  *
@@ -24,8 +24,9 @@
  * - Sticky headers/footers with scrollable body
  * - Overlay backdrop with customization
  * - Close button with accessibility (optional)
- * - Header, footer, title, and description components
+ * - Header and footer components
  * - Configurable close behaviors
+ * - Native dialog title and aria-description attributes for accessibility
  *
  * @example
  * ```tsx
@@ -34,12 +35,9 @@
  *   <DialogTrigger asChild>
  *     <Button>Open Dialog</Button>
  *   </DialogTrigger>
- *   <DialogContent size="lg">
+ *   <DialogContent size="lg" title="Edit Profile" description="Make changes to your profile here. Click save when you're done.">
  *     <DialogHeader>
- *       <DialogTitle>Edit Profile</DialogTitle>
- *       <DialogDescription>
- *         Make changes to your profile here. Click save when you're done.
- *       </DialogDescription>
+ *       <h2>Edit Profile</h2>
  *     </DialogHeader>
  *     <DialogBody>
  *       <section className="space-y-4">
@@ -54,81 +52,12 @@
  *     </DialogFooter>
  *   </DialogContent>
  * </Dialog>
- * 
- * // Dialog with semantic scrolling content
- * <Dialog>
- *   <DialogTrigger asChild>
- *     <Button>Scrollable Dialog</Button>
- *   </DialogTrigger>
- *   <DialogContent 
- *     size="lg" 
- *     enableScrolling={true}
- *     maxHeightPercent={80}
- *   >
- *     <DialogHeader>
- *       <DialogTitle>Large Content Dialog</DialogTitle>
- *       <DialogDescription>
- *         This dialog has lots of content and will scroll if needed.
- *       </DialogDescription>
- *     </DialogHeader>
- *     <DialogBody>
- *       <section className="space-y-4">
- *         {Array.from({ length: 50 }, (_, i) => (
- *           <article key={i}>
- *             <h4>Content Item {i + 1}</h4>
- *             <p>This is semantic content within the dialog body.</p>
- *           </article>
- *         ))}
- *       </section>
- *     </DialogBody>
- *     <DialogFooter>
- *       <Button>Save</Button>
- *     </DialogFooter>
- *   </DialogContent>
- * </Dialog>
- * 
- * // Auto-sizing dialog that fits content
- * <Dialog>
- *   <DialogTrigger asChild>
- *     <Button>Auto Size Dialog</Button>
- *   </DialogTrigger>
- *   <DialogContent size="auto">
- *     <DialogHeader>
- *       <DialogTitle>Auto-Sized Dialog</DialogTitle>
- *       <DialogDescription>
- *         This dialog automatically adjusts its width to fit the content.
- *       </DialogDescription>
- *     </DialogHeader>
- *     <DialogBody>
- *       <section>
- *         <p>Content that determines the dialog width...</p>
- *       </section>
- *     </DialogBody>
- *   </DialogContent>
- * </Dialog>
- * 
- * // Full-screen dialog with semantic structure
- * <Dialog>
- *   <DialogTrigger asChild>
- *     <Button>Full Screen</Button>
- *   </DialogTrigger>
- *   <DialogContent size="full">
- *     <DialogHeader>
- *       <DialogTitle>Full Screen Dialog</DialogTitle>
- *     </DialogHeader>
- *     <DialogBody>
- *       <section>
- *         <p>Full screen content with semantic structure...</p>
- *       </section>
- *     </DialogBody>
- *   </DialogContent>
- * </Dialog>
  * ```
  *
  * @accessibility
  * - WCAG 2.1 AA compliant
  * - Uses semantic HTML structure (dialog, header, main, footer)
- * - Native dialog element with enhanced ARIA attributes via Radix UI
+ * - Native dialog element with proper ARIA attributes
  * - Focus trapping within dialog content
  * - Keyboard navigation support
  * - Screen reader announcements
@@ -147,18 +76,28 @@
  * - Optimized scroll handling
  *
  * @dependencies
- * - @radix-ui/react-dialog - Core dialog functionality
  * - lucide-react - Icons
- * - React 19+ - Hooks and refs
+ * - React 19+ - Hooks, refs, and createPortal
  * - Tailwind CSS - Styling and animations
+ * 
+ * @note
+ * This component uses native HTML dialog element with manual focus management.
+ * Title and description are provided via props on DialogContent, which set the native
+ * title and aria-description attributes on the dialog element for accessibility.
+ * See https://developer.mozilla.org/en-US/docs/Web/API/Element/ariaDescription for details.
  */
 
 import * as React from 'react';
-import * as DialogPrimitive from '@radix-ui/react-dialog';
+import { createPortal } from 'react-dom';
 import { X } from 'lucide-react';
+import { useLocation } from 'react-router-dom';
+import { useUnifiedAuth } from '../../providers/services/UnifiedAuthProvider';
 import { cn } from '../../utils/core/cn';
 import { renderSafeHtml } from '../../utils/validation/htmlSanitization';
-import { useState, useEffect } from 'react';
+import { useState, useEffect, useRef, useCallback, useId, useMemo } from 'react';
+import { useFocusTrap } from '../../hooks/useFocusTrap';
+import { useSessionDraft } from '../../hooks/useSessionDraft';
+import { deriveDialogKey } from '../../utils/persistence/keyDerivation';
 
 /**
  * Simple debounce function that matches lodash debounce API
@@ -195,30 +134,64 @@ function debounce<T extends (...args: any[]) => void>(
  */
 export type DialogSize = 'sm' | 'md' | 'lg' | 'xl' | 'full' | 'auto';
 
+/**
+ * Dialog context value
+ */
+interface DialogContextValue {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  dialogRef: React.RefObject<HTMLDialogElement | null>;
+  titleId: string;
+  descriptionId: string;
+  dialogTitle?: string; // For persistence key derivation
+  markClosedByUser?: () => void; // Callback to mark dialog as closed by user (for Cancel buttons, etc.)
+}
+
+const DialogContext = React.createContext<DialogContextValue | null>(null);
+
+/**
+ * Hook to access Dialog context
+ */
+function useDialogContext(): DialogContextValue {
+  const context = React.useContext(DialogContext);
+  if (!context) {
+    throw new Error('Dialog components must be used within a Dialog');
+  }
+  return context;
+}
+
 /**
  * Props for the Dialog root component
  * @public
  */
-export interface DialogProps extends DialogPrimitive.DialogProps {}
+export interface DialogProps {
+  children: React.ReactNode;
+  open?: boolean;
+  defaultOpen?: boolean;
+  onOpenChange?: (open: boolean) => void;
+}
 
 /**
  * Props for the DialogTrigger component
  * @public
  */
-export interface DialogTriggerProps extends DialogPrimitive.DialogTriggerProps {}
+export interface DialogTriggerProps {
+  children: React.ReactNode;
+  asChild?: boolean;
+  className?: string;
+  onClick?: (e: React.MouseEvent) => void;
+}
 
 /**
  * Enhanced props for the DialogContent component with size variants and customization
- * Uses semantic HTML dialog element with Radix UI accessibility features
+ * Uses semantic HTML dialog element
  * @public
  */
-export interface DialogContentProps extends React.ComponentPropsWithoutRef<typeof DialogPrimitive.Content> {
+export interface DialogContentProps extends React.HTMLAttributes<HTMLDialogElement> {
   /** Dialog size variant */
   size?: DialogSize;
   /** Whether to show the close button */
   showCloseButton?: boolean;
-  /** Custom className for the overlay */
-  overlayClassName?: string;
   /** Whether to prevent closing on escape key */
   preventCloseOnEscape?: boolean;
   /** Whether to prevent closing on outside click */
@@ -237,13 +210,33 @@ export interface DialogContentProps extends React.ComponentPropsWithoutRef<typeo
   minHeight?: string;
   /** Minimum width in CSS units */
   minWidth?: string;
+  /** Dialog title for accessibility (sets native title attribute) */
+  title?: string;
+  /** Dialog description for accessibility (sets aria-description attribute) */
+  description?: string;
+  /** Whether to persist open state across tab switches */
+  persistOpenState?: boolean;
 }
 
 /**
  * Props for the DialogOverlay component
  * @public
  */
-export interface DialogOverlayProps extends React.ComponentPropsWithoutRef<typeof DialogPrimitive.Overlay> {}
+export interface DialogOverlayProps extends React.HTMLAttributes<HTMLDivElement> {}
+
+/**
+ * Props for the DialogPortal component
+ * @public
+ */
+export interface DialogPortalProps {
+  children: React.ReactNode;
+}
+
+/**
+ * Props for the DialogClose component
+ * @public
+ */
+export interface DialogCloseProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {}
 
 /**
  * Props for the DialogHeader component (semantic header element)
@@ -284,7 +277,7 @@ export interface DialogBodyProps extends React.HTMLAttributes<HTMLElement> {
  * Props for the DialogTitle component
  * @public
  */
-export interface DialogTitleProps extends React.ComponentPropsWithoutRef<typeof DialogPrimitive.Title> {
+export interface DialogTitleProps extends React.HTMLAttributes<HTMLHeadingElement> {
   /** HTML content to render as title (will be sanitized for security) */
   htmlContent?: string;
   /** Whether to allow HTML content rendering (default: true) */
@@ -295,7 +288,7 @@ export interface DialogTitleProps extends React.ComponentPropsWithoutRef<typeof
  * Props for the DialogDescription component
  * @public
  */
-export interface DialogDescriptionProps extends React.ComponentPropsWithoutRef<typeof DialogPrimitive.Description> {
+export interface DialogDescriptionProps extends React.HTMLAttributes<HTMLParagraphElement> {
   /** HTML content to render as description (will be sanitized for security) */
   htmlContent?: string;
   /** Whether to allow HTML content rendering (default: true) */
@@ -312,27 +305,144 @@ const sizeClasses = {
   auto: 'max-w-none w-auto min-w-0'
 };
 
-// Root Dialog components from Radix
-const Dialog = DialogPrimitive.Root;
-const DialogTrigger = DialogPrimitive.Trigger;
-const DialogPortal = DialogPrimitive.Portal;
-const DialogClose = DialogPrimitive.Close;
-
-// DialogOverlay component
-const DialogOverlay = React.forwardRef<
-  React.ElementRef<typeof DialogPrimitive.Overlay>,
-  DialogOverlayProps
->(({ className, ...props }, ref) => (
-  <DialogPrimitive.Overlay
-    ref={ref}
-    className={cn(
-      'fixed inset-0 z-50 bg-black/50 data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0',
-      className
-    )}
-    {...props}
-  />
-));
-DialogOverlay.displayName = DialogPrimitive.Overlay.displayName;
+/**
+ * Dialog root component
+ * Provides context for dialog state management
+ */
+const Dialog = React.memo<DialogProps>(function Dialog({
+  children,
+  open: controlledOpen,
+  defaultOpen = false,
+  onOpenChange,
+}) {
+  const [internalOpen, setInternalOpen] = useState(defaultOpen);
+  const dialogRef = useRef<HTMLDialogElement | null>(null);
+  const titleId = useId();
+  const descriptionId = useId();
+  const dialogTitleRef = useRef<string | undefined>(undefined);
+  const [markClosedByUser, setMarkClosedByUserState] = useState<(() => void) | undefined>(undefined);
+
+  const isControlled = controlledOpen !== undefined;
+  const open = isControlled ? controlledOpen : internalOpen;
+
+  const handleOpenChange = useCallback((newOpen: boolean) => {
+    if (!isControlled) {
+      setInternalOpen(newOpen);
+    }
+    onOpenChange?.(newOpen);
+  }, [isControlled, onOpenChange]);
+
+  const contextValue = React.useMemo<DialogContextValue>(() => ({
+    open,
+    onOpenChange: handleOpenChange,
+    dialogRef,
+    titleId,
+    descriptionId,
+    dialogTitle: dialogTitleRef.current,
+    markClosedByUser, // Set by DialogContent
+  }), [open, handleOpenChange, titleId, descriptionId, markClosedByUser]);
+
+  // Expose function to set dialog title (called by DialogContent)
+  const setDialogTitle = useCallback((title: string | undefined) => {
+    dialogTitleRef.current = title;
+  }, []);
+
+  // Expose function to set markClosedByUser callback (called by DialogContent)
+  const setMarkClosedByUser = useCallback((callback: (() => void) | undefined) => {
+    setMarkClosedByUserState(callback);
+  }, []);
+
+  return (
+    <DialogContext.Provider value={contextValue}>
+      <DialogTitleContext.Provider value={setDialogTitle}>
+        <DialogMarkClosedContext.Provider value={setMarkClosedByUser}>
+          {children}
+        </DialogMarkClosedContext.Provider>
+      </DialogTitleContext.Provider>
+    </DialogContext.Provider>
+  );
+});
+
+// Context for setting dialog title from DialogContent
+const DialogTitleContext = React.createContext<((title: string | undefined) => void) | null>(null);
+
+// Context for setting markClosedByUser callback from DialogContent
+const DialogMarkClosedContext = React.createContext<((callback: (() => void) | undefined) => void) | null>(null);
+
+// Context for marking dialog as closed by user (from DialogContent to DialogClose)
+const DialogCloseContext = React.createContext<(() => void) | null>(null);
+Dialog.displayName = 'Dialog';
+
+/**
+ * DialogTrigger component
+ * Opens the dialog when clicked
+ */
+const DialogTrigger = React.forwardRef<HTMLElement, DialogTriggerProps>(
+  ({ children, asChild = false, className, onClick, ...props }, ref) => {
+    const { onOpenChange } = useDialogContext();
+
+    const handleClick = useCallback((e: React.MouseEvent) => {
+      onClick?.(e);
+      onOpenChange(true);
+    }, [onOpenChange, onClick]);
+
+    if (asChild && React.isValidElement(children)) {
+      return React.cloneElement(children as React.ReactElement<any>, {
+        ref,
+        onClick: handleClick,
+        className: cn(className, (children as any).props?.className),
+        ...props,
+      });
+    }
+
+    return (
+      <button
+        ref={ref as React.RefObject<HTMLButtonElement>}
+        type="button"
+        onClick={handleClick}
+        className={className}
+        {...props}
+      >
+        {children}
+      </button>
+    );
+  }
+);
+DialogTrigger.displayName = 'DialogTrigger';
+
+/**
+ * DialogPortal component
+ * Portals dialog content to document.body
+ */
+const DialogPortal: React.FC<DialogPortalProps> = ({ children }) => {
+  const [mounted, setMounted] = useState(false);
+
+  useEffect(() => {
+    setMounted(true);
+    return () => setMounted(false);
+  }, []);
+
+  if (!mounted) return null;
+
+  return createPortal(children, document.body);
+};
+DialogPortal.displayName = 'DialogPortal';
+
+/**
+ * DialogOverlay component
+ * Backdrop overlay for the dialog (optional, native dialog provides ::backdrop)
+ * This component is kept for backward compatibility but may not be needed
+ * when using native dialog element which provides ::backdrop automatically
+ */
+const DialogOverlay = React.forwardRef<HTMLDivElement, DialogOverlayProps>(
+  ({ className, ...props }, ref) => {
+    // Note: Native dialog element provides ::backdrop automatically
+    // This component is kept for API compatibility but may not render
+    // The native dialog's ::backdrop is styled via CSS
+    return null;
+  }
+);
+DialogOverlay.displayName = 'DialogOverlay';
 
 /**
  * Custom hook for managing smart dialog dimensions
@@ -367,7 +477,7 @@ const useSmartDimensions = ({
 
       // Handle height constraints
       if (maxHeightPercent && typeof maxHeightPercent === 'number') {
-        const constrainedHeight = Math.min(maxHeightPercent, 95); // Cap at 95% to ensure some margin
+        const constrainedHeight = Math.min(maxHeightPercent, 95);
         result.maxHeight = `${constrainedHeight}vh`;
       } else if (maxHeight) {
         result.maxHeight = maxHeight;
@@ -375,7 +485,7 @@ const useSmartDimensions = ({
 
       // Handle width constraints  
       if (maxWidthPercent && typeof maxWidthPercent === 'number') {
-        const constrainedWidth = Math.min(maxWidthPercent, 95); // Cap at 95% to ensure some margin
+        const constrainedWidth = Math.min(maxWidthPercent, 95);
         result.maxWidth = `${constrainedWidth}vw`;
       } else if (maxWidth) {
         result.maxWidth = maxWidth;
@@ -407,7 +517,7 @@ const useSmartDimensions = ({
     };
   }, [maxHeightPercent, maxWidthPercent, maxHeight, maxWidth, minHeight, minWidth, enableScrolling]);
 
-  // Only return dimensions if we have something to constrain
+  // Return dimensions
   const result: React.CSSProperties = {};
 
   // Handle height constraints
@@ -437,149 +547,864 @@ const useSmartDimensions = ({
   return result;
 };
 
+/**
+ * Global lock to ensure only one dialog is open at a time
+ * Uses sessionStorage for persistence across page reloads
+ */
+const DIALOG_LOCK_KEY = 'pace-core:dialog:lock';
+
+function acquireDialogLock(persistenceKey: string | null): boolean {
+  if (!persistenceKey) {
+    return true; // Non-persisted dialogs can always open
+  }
+
+  try {
+    const lock = sessionStorage.getItem(DIALOG_LOCK_KEY);
+    if (lock) {
+      const lockData = JSON.parse(lock);
+      // If lock is held by this dialog, allow it
+      if (lockData.key === persistenceKey) {
+        return true;
+      }
+      // If lock is held by another dialog, check if that dialog is still open
+      const lockDialog = document.querySelector(`dialog[data-persistence-key="${lockData.key}"]`) as HTMLDialogElement;
+      if (lockDialog && lockDialog.open) {
+        return false; // Another dialog is still open
+      }
+      // Lock is stale, clear it
+      sessionStorage.removeItem(DIALOG_LOCK_KEY);
+    }
+    // Acquire the lock
+    sessionStorage.setItem(DIALOG_LOCK_KEY, JSON.stringify({
+      key: persistenceKey,
+      timestamp: Date.now(),
+    }));
+    return true;
+  } catch {
+    // If sessionStorage fails, allow opening (graceful degradation)
+    return true;
+  }
+}
+
+function releaseDialogLock(persistenceKey: string | null): void {
+  if (!persistenceKey) {
+    return;
+  }
+
+  try {
+    const lock = sessionStorage.getItem(DIALOG_LOCK_KEY);
+    if (lock) {
+      const lockData = JSON.parse(lock);
+      if (lockData.key === persistenceKey) {
+        sessionStorage.removeItem(DIALOG_LOCK_KEY);
+      }
+    }
+  } catch {
+    // Ignore errors
+  }
+}
+
+/**
+ * Check if any other dialog (besides the current one) has persisted open state
+ * This helps determine if another dialog should be allowed to auto-open
+ */
+function checkOtherDialogsHavePersistedState(currentPersistenceKey: string | null): boolean {
+  if (!currentPersistenceKey) {
+    return false;
+  }
+
+  try {
+    const lock = sessionStorage.getItem(DIALOG_LOCK_KEY);
+    if (lock) {
+      const lockData = JSON.parse(lock);
+      if (lockData.key !== currentPersistenceKey) {
+        // Another dialog holds the lock
+        return true;
+      }
+    }
+  } catch {
+    // Error accessing sessionStorage - assume no other dialogs
+    return false;
+  }
+
+  return false;
+}
+
 /**
  * DialogContent component
  * The main content container using semantic HTML <dialog> element with enhanced features
- * Built on Radix UI primitives for accessibility while providing semantic structure
  * 
  * @param props - Content configuration and styling
  * @param ref - Forwarded ref to the dialog element
  * @returns JSX.Element - The semantic dialog content with overlay and optional close button
- * 
- * @example
- * ```tsx
- * <DialogContent size="lg" enableScrolling={true} maxHeightPercent={80}>
- *   <DialogHeader>
- *     <DialogTitle>Scrollable Dialog</DialogTitle>
- *     <DialogDescription>This dialog will scroll if content overflows.</DialogDescription>
- *   </DialogHeader>
- *   <DialogBody>
- *     <section>Large amount of semantic content here...</section>
- *   </DialogBody>
- *   <DialogFooter>
- *     <Button>Save</Button>
- *   </DialogFooter>
- * </DialogContent>
- * ```
  */
-const DialogContent = React.forwardRef<
-  React.ElementRef<typeof DialogPrimitive.Content>,
-  DialogContentProps
->(({ 
-  className, 
-  children, 
-  size = 'md',
-  showCloseButton = true,
-  overlayClassName,
-  preventCloseOnEscape = false,
-  preventCloseOnOutsideClick = false,
-  maxHeightPercent,
-  maxWidthPercent,
-  enableScrolling = false,
-  maxHeight,
-  maxWidth,
-  minHeight,
-  minWidth,
-  style,
-  ...props 
-}, ref) => {
-  const smartDimensions = useSmartDimensions({ 
-    maxHeightPercent, 
+const DialogContent = React.forwardRef<HTMLDialogElement, DialogContentProps>(
+  ({ 
+    className, 
+    children, 
+    size = 'md',
+    showCloseButton = true,
+    preventCloseOnEscape = false,
+    preventCloseOnOutsideClick = false,
+    maxHeightPercent,
     maxWidthPercent,
-    maxHeight, 
+    enableScrolling = false,
+    maxHeight,
     maxWidth,
     minHeight,
     minWidth,
-    enableScrolling 
-  });
+    title,
+    description,
+    style,
+    persistOpenState = true,
+    ...props 
+  }, ref) => {
+    // Call all hooks unconditionally at the top level
+    // Hooks must be called in the same order on every render
+    const { open, onOpenChange, dialogRef, titleId, descriptionId } = useDialogContext();
+    const setDialogTitle = React.useContext(DialogTitleContext);
+    const setMarkClosedByUser = React.useContext(DialogMarkClosedContext);
+    
+    // Component mount/unmount tracking removed for performance
 
-  // React Compiler handles memoization automatically
-  const handleEscapeKeyDown = (event: KeyboardEvent) => {
-    if (preventCloseOnEscape) {
-      event.preventDefault();
-    }
-  };
+    // Call hooks unconditionally - if providers are missing, they will throw
+    // Errors should be handled by error boundaries at a higher level
+    const location = useLocation();
+    const auth = useUnifiedAuth();
+    const userId = auth.user?.id || null;
 
-  const handlePointerDownOutside = (event: Event) => {
-    if (preventCloseOnOutsideClick) {
-      event.preventDefault();
-    }
-  };
+    // Set dialog title in context for persistence
+    useEffect(() => {
+      if (setDialogTitle) {
+        setDialogTitle(title);
+      }
+    }, [title, setDialogTitle]);
 
-  // Merge smart dimensions with provided style
-  const mergedStyle = React.useMemo(() => {
-    // If no smart dimensions are active, just return the provided style
-    if (Object.keys(smartDimensions).length === 0) {
-      return style;
-    }
+    // Derive persistence key (scoped by user ID)
+    // CRITICAL: Only enable persistence if we have a valid userId to prevent data leakage
+    const persistenceKey = useMemo(() => {
+      if (!persistOpenState) {
+        return null;
+      }
+      // Don't create persistence key if userId is not available
+      // This prevents unscoped persistence that could leak between users
+      if (!userId) {
+        return null;
+      }
+      return deriveDialogKey(
+        {
+          title,
+          description,
+        },
+        location,
+        userId
+      );
+    }, [title, description, location, userId, persistOpenState]);
+
+    // Use session draft for open state persistence
+    // Only enabled when we have a valid persistenceKey (which requires userId)
+    const { state: persistedOpen, setState: setPersistedOpen, clearDraft, wasRestored } = useSessionDraft<boolean>(
+      persistenceKey ? `${persistenceKey}:open` : 'dialog:no-key:open',
+      false,
+      {
+        enabled: Boolean(persistenceKey && persistOpenState && userId),
+        debounceMs: 300,
+      }
+    );
 
-    // Start with smart dimensions
-    const finalStyle: React.CSSProperties = { ...smartDimensions, ...style };
+    // Track if we've attempted auto-open to prevent multiple attempts
+    const hasAutoOpenedRef = useRef(false);
+    const hasInitializedRef = useRef(false);
+    // Track if dialog was closed by user action (to clear persistence)
+    const wasClosedByUserRef = useRef(false);
+    // Track if dialog was manually opened (to prevent auto-open from interfering)
+    const wasManuallyOpenedRef = useRef(false);
     
-    // If not using smart width and no maxWidth override, don't include maxWidth
-    if (!maxWidth && !maxWidthPercent) {
-      const { maxWidth: _, ...styleWithoutMaxWidth } = finalStyle;
-      return styleWithoutMaxWidth;
-    }
+    // Callback to mark dialog as closed by user (exposed via context for DialogClose and Cancel buttons)
+    const markClosedByUser = useCallback(() => {
+      if (hasInitializedRef.current) {
+        wasClosedByUserRef.current = true;
+      }
+    }, []);
+
+    // Register markClosedByUser with parent Dialog component so it's available via DialogContext
+    useEffect(() => {
+      if (setMarkClosedByUser) {
+        setMarkClosedByUser(markClosedByUser);
+      }
+      return () => {
+        // Cleanup: unregister when DialogContent unmounts
+        if (setMarkClosedByUser) {
+          setMarkClosedByUser(undefined);
+        }
+      };
+    }, [setMarkClosedByUser, markClosedByUser]);
+    // Track if we've cleaned up other dialog states (to prevent multiple cleanup runs)
+    const hasCleanedUpOtherDialogsRef = useRef(false);
+
+    // Auto-open on mount if dialog was open when tab closed
+    useEffect(() => {
+      if (!persistenceKey || !persistOpenState) {
+        hasInitializedRef.current = true;
+        return;
+      }
+
+      // Only attempt auto-open once
+      // This prevents auto-open from running after manual opens
+      if (hasAutoOpenedRef.current) {
+        return;
+      }
+
+      // CRITICAL: Don't auto-open if dialog was manually opened
+      // This prevents auto-open from interfering with manual opens
+      if (wasManuallyOpenedRef.current) {
+        console.log('[Dialog Persistence] ⏭️ Skipping auto-open - dialog was manually opened', {
+          persistenceKey,
+          currentOpen: open,
+        });
+        return;
+      }
+
+      // Mark as initialized after first check
+      if (!hasInitializedRef.current) {
+        hasInitializedRef.current = true;
+      }
+
+      // Auto-open check (logging removed for performance)
+      
+      // CRITICAL: Don't auto-open if dialog is already open (user-initiated)
+      if (open === true) {
+        hasAutoOpenedRef.current = true;
+        return;
+      }
+
+      // CRITICAL: Don't auto-open if userId is not available (prevents unscoped persistence from being restored)
+      if (!userId) {
+        hasAutoOpenedRef.current = true;
+        return;
+      }
+
+      // Only auto-open if conditions are met
+      if (persistedOpen === true && open === false && wasRestored && !hasAutoOpenedRef.current && !wasManuallyOpenedRef.current) {
+        const AUTO_OPEN_LOCK_KEY = 'pace-core:dialog:auto-open-lock';
+        const lockTimestamp = sessionStorage.getItem(AUTO_OPEN_LOCK_KEY);
+        const now = Date.now();
+        
+        // Check if another dialog is already auto-opening (lock exists and is recent)
+        if (lockTimestamp) {
+          const lockAge = now - parseInt(lockTimestamp, 10);
+          if (lockAge < 1000) {
+            // Lock is recent - another dialog is auto-opening
+            // Check if there's already an open dialog with this persistence key
+            const existingOpenDialog = document.querySelector(`dialog[data-persistence-key="${persistenceKey}"][open]`);
+            if (existingOpenDialog) {
+              // Another instance is already open - skip
+              hasAutoOpenedRef.current = true;
+              return;
+            }
+            // Check if other dialog has persisted state
+            const otherDialogHasPersistedState = checkOtherDialogsHavePersistedState(persistenceKey);
+            if (otherDialogHasPersistedState) {
+              // Another dialog with persisted state is auto-opening - skip this one
+              clearDraft();
+              hasAutoOpenedRef.current = true;
+              return;
+            }
+          }
+          // Clear stale locks
+          if (lockAge > 2000) {
+            sessionStorage.removeItem(AUTO_OPEN_LOCK_KEY);
+          }
+        }
+
+        // Check if dialog with same key is already open in DOM (synchronous check)
+        const existingDialog = document.querySelector(`dialog[data-persistence-key="${persistenceKey}"][open]`);
+        if (existingDialog && existingDialog !== dialogRef.current && existingDialog !== internalRef.current) {
+          hasAutoOpenedRef.current = true;
+          return;
+        }
+
+        // Set lock and mark as auto-opened BEFORE calling onOpenChange
+        sessionStorage.setItem(AUTO_OPEN_LOCK_KEY, String(now));
+        hasAutoOpenedRef.current = true;
+        wasManuallyOpenedRef.current = false;
+        
+        console.log('[Dialog] 🔄 AUTO-OPEN', { persistenceKey });
+        
+        // Use small delay to prevent visual flash
+        const timeoutId = setTimeout(() => {
+          // Double-check: if dialog is still closed and no other instance opened it
+          const stillClosed = !open;
+          const noOtherInstance = !document.querySelector(`dialog[data-persistence-key="${persistenceKey}"][open]`);
+          
+          if (stillClosed && noOtherInstance) {
+            sessionStorage.removeItem(AUTO_OPEN_LOCK_KEY);
+            onOpenChange(true);
+          } else {
+            sessionStorage.removeItem(AUTO_OPEN_LOCK_KEY);
+          }
+        }, 75);
+
+        return () => {
+          clearTimeout(timeoutId);
+          sessionStorage.removeItem(AUTO_OPEN_LOCK_KEY);
+        };
+      }
+    }, [persistenceKey, persistOpenState, persistedOpen, open, onOpenChange, wasRestored, clearDraft]);
+
+    // When this dialog auto-opens, clear persisted state of all other dialogs
+    // This prevents multiple dialogs from being restored simultaneously
+    useEffect(() => {
+      if (!persistenceKey || !persistOpenState || !open || !hasAutoOpenedRef.current) {
+        return;
+      }
+
+      // Only run once when dialog first auto-opens
+      if (hasCleanedUpOtherDialogsRef.current) {
+        return;
+      }
+
+      // Clear all other dialog persisted states from sessionStorage
+      // AND close any other dialogs that are currently open in the DOM
+      // This ensures only the first auto-opened dialog remains open
+      try {
+        const keysToRemove: string[] = [];
+        for (let i = 0; i < sessionStorage.length; i++) {
+          const key = sessionStorage.key(i);
+          if (key && key.startsWith('pace-core:draft:dialog:') && key.endsWith(':open')) {
+            // Don't clear this dialog's own state
+            if (key !== `pace-core:draft:${persistenceKey}:open`) {
+              keysToRemove.push(key);
+            }
+          }
+        }
+
+        if (keysToRemove.length > 0) {
+          console.log('[Dialog Persistence] Clearing other dialog persisted states:', keysToRemove);
+          keysToRemove.forEach(key => sessionStorage.removeItem(key));
+        }
+
+        // Also close any other dialogs that are currently open in the DOM AND have persisted state
+        // This prevents dialogs with persisted state from being hidden behind this one
+        // We only close dialogs that have persisted state, not dialogs opened by app code
+        // We identify dialogs with persistence using a data attribute
+        const timeoutId = setTimeout(() => {
+          // Guard against test environment teardown
+          if (typeof document === 'undefined' || typeof sessionStorage === 'undefined') {
+            return;
+          }
+          
+          const otherOpenDialogs = document.querySelectorAll('dialog[open][role="dialog"]');
+          const currentDialog = dialogRef.current || internalRef.current;
+          if (otherOpenDialogs.length > 0 && currentDialog) {
+            let closedCount = 0;
+            otherOpenDialogs.forEach((dialog) => {
+              // Don't close this dialog
+              const dialogElement = dialog as HTMLDialogElement;
+              if (dialogElement !== currentDialog) {
+                // Check if this dialog has a data-persistence-key attribute
+                // This indicates it was auto-opened from persistence
+                const dialogPersistenceKey = dialogElement.getAttribute('data-persistence-key');
+                if (dialogPersistenceKey && dialogPersistenceKey !== persistenceKey) {
+                  // Check if this dialog's persisted state is true
+                  let hasPersistedState = false;
+                  try {
+                    const key = `pace-core:draft:${dialogPersistenceKey}:open`;
+                    const stored = sessionStorage.getItem(key);
+                    if (stored) {
+                      const parsed = JSON.parse(stored);
+                      if (parsed && parsed.data === true) {
+                        hasPersistedState = true;
+                      }
+                    }
+                  } catch {
+                    // Invalid data - skip
+                  }
+
+                  // Only close if this dialog has persisted state (was auto-opened)
+                  if (hasPersistedState) {
+                    console.log('[Dialog Persistence] Closing other dialog with persisted state:', dialogPersistenceKey);
+                    dialogElement.close();
+                    closedCount++;
+                  }
+                }
+                // If dialog doesn't have data-persistence-key, it was opened by app code - don't close it
+              }
+            });
+            if (closedCount > 0) {
+              console.log('[Dialog Persistence] Closed', closedCount, 'other dialog(s) with persisted state');
+            }
+          }
+        }, 100);
+
+        hasCleanedUpOtherDialogsRef.current = true;
+        
+        // Also clear the auto-open lock
+        if (typeof sessionStorage !== 'undefined') {
+          sessionStorage.removeItem('pace-core:dialog:auto-open-lock');
+        }
+        
+        // Cleanup timeout on unmount or dependency change
+        return () => {
+          clearTimeout(timeoutId);
+        };
+      } catch (error) {
+        console.warn('[Dialog Persistence] Failed to clear other dialog states:', error);
+      }
+    }, [open, persistenceKey, persistOpenState]);
+
+    // When dialog closes (user action), immediately clear persisted state
+    // This prevents the dialog from auto-opening again after user explicitly closed it
+    useEffect(() => {
+      if (!persistenceKey || !persistOpenState) {
+        return;
+      }
+
+      if (!hasInitializedRef.current) {
+        return;
+      }
+
+      // If dialog is closed and user closed it, clear persisted state immediately
+      if (!open && wasClosedByUserRef.current) {
+        clearDraft();
+        wasClosedByUserRef.current = false;
+      }
+    }, [open, persistenceKey, persistOpenState, clearDraft]);
+
+    // Check lock BEFORE allowing dialog to open (synchronous check)
+    // This prevents React from even trying to open if another dialog is open
+    useEffect(() => {
+      if (!open) {
+        return;
+      }
+
+      // Synchronously check if we can acquire the lock
+      const lockAcquired = acquireDialogLock(persistenceKey);
+      if (!lockAcquired) {
+        // Another dialog is open - prevent this one from opening
+        console.warn('[Dialog] ⚠️ Cannot open - another dialog holds the lock', {
+          persistenceKey,
+        });
+        // Immediately close this dialog's React state
+        onOpenChange?.(false);
+        return;
+      }
+      
+      // Lock acquired successfully - dialog can proceed to open
+    }, [open, persistenceKey, onOpenChange]);
+
+    // Track when dialog closes via onOpenChange to mark as closed by user
+    // This handles Cancel buttons and other programmatic closes
+    const previousOpenRef = useRef(open);
+    useEffect(() => {
+      // If dialog was open and is now closed, and it wasn't auto-opened, mark as closed by user
+      if (previousOpenRef.current === true && open === false && hasInitializedRef.current) {
+        // Only mark as closed by user if it wasn't an auto-open scenario
+        // Auto-open sets hasAutoOpenedRef before calling onOpenChange, so we can detect it
+        if (!hasAutoOpenedRef.current || wasManuallyOpenedRef.current) {
+          // Dialog was manually opened and then closed - mark as closed by user
+          wasClosedByUserRef.current = true;
+        }
+      }
+      previousOpenRef.current = open;
+    }, [open]);
+
+    // Persist open state changes
+    useEffect(() => {
+      if (!persistenceKey || !persistOpenState) {
+        return;
+      }
+
+      // Only persist after initial mount check is complete
+      // This prevents overwriting the persisted state before auto-open can read it
+      if (!hasInitializedRef.current) {
+        return;
+      }
+
+      // Persisting open state (logging removed for performance)
+
+      let logTimeoutId: ReturnType<typeof setTimeout> | null = null;
+
+      // Only persist when dialog is open
+      if (open) {
+        // Reset the flag when opening
+        wasClosedByUserRef.current = false;
+        // If dialog is manually opened (not via auto-open), mark it so auto-open doesn't interfere
+        // This prevents auto-open from trying to open an already-open dialog
+        // We check if hasAutoOpenedRef is false to determine if this is a manual open
+        // (auto-open sets hasAutoOpenedRef to true before calling onOpenChange)
+        if (!hasAutoOpenedRef.current) {
+          // Mark as manually opened to prevent auto-open from interfering
+          wasManuallyOpenedRef.current = true;
+          // Also mark as "opened" to prevent auto-open from trying to open it again
+          hasAutoOpenedRef.current = true;
+        }
+        setPersistedOpen(true);
+      } else {
+        // Only clear draft if user explicitly closed (not if it was never opened or auto-opened then closed)
+        if (wasClosedByUserRef.current) {
+          clearDraft();
+          wasClosedByUserRef.current = false;
+          // Reset manual open flag when dialog is closed
+          wasManuallyOpenedRef.current = false;
+        }
+      }
+      
+      // Cleanup timeout on unmount or dependency change
+      return () => {
+        if (logTimeoutId) {
+          clearTimeout(logTimeoutId);
+        }
+      };
+    }, [open, persistenceKey, persistOpenState, setPersistedOpen, clearDraft]);
+
+    // Note: We do NOT automatically clear the draft when dialog closes
+    // The draft should only be cleared on explicit user actions (e.g., form submit success)
+    // This allows the dialog to restore its state after tab switches
+    const internalRef = useRef<HTMLDialogElement>(null);
     
-    return finalStyle;
-  }, [smartDimensions, style, maxWidth, maxWidthPercent]);
+    // Use the dialogRef from context, or fall back to internal ref or forwarded ref
+    const actualDialogRef = dialogRef.current ? dialogRef : (ref ? (ref as React.RefObject<HTMLDialogElement>) : internalRef);
 
-  return (
-    <DialogPortal>
-      <DialogOverlay className={overlayClassName} />
-      <DialogPrimitive.Content
+    // Default to 80% viewport height if no height constraint is provided
+    // This allows the dialog to grow to 80% before enabling scrolling
+    const effectiveMaxHeightPercent = maxHeightPercent ?? (maxHeight ? undefined : 80);
+    
+    // Determine if we have a height constraint that requires flex layout
+    const hasHeightConstraint = Boolean(effectiveMaxHeightPercent || maxHeight);
+
+    const smartDimensions = useSmartDimensions({ 
+      maxHeightPercent: effectiveMaxHeightPercent, 
+      maxWidthPercent,
+      maxHeight, 
+      maxWidth,
+      minHeight,
+      minWidth,
+      enableScrolling 
+    });
+
+    // Focus trap
+    const { containerRef } = useFocusTrap({
+      isActive: open,
+      autoFocus: true,
+      restoreFocus: true,
+      onEscape: preventCloseOnEscape ? undefined : () => onOpenChange(false),
+    });
+
+    // Merge refs
+    const mergedRef = useCallback((node: HTMLDialogElement | null) => {
+      // Set context dialog ref
+      if (dialogRef && 'current' in dialogRef) {
+        (dialogRef as React.MutableRefObject<HTMLDialogElement | null>).current = node;
+      }
+      // Set internal ref
+      if (internalRef && 'current' in internalRef) {
+        internalRef.current = node;
+      }
+      // Set focus trap container ref
+      if (containerRef && 'current' in containerRef) {
+        (containerRef as React.MutableRefObject<HTMLElement | null>).current = node;
+      }
+      // Handle forwarded ref
+      if (typeof ref === 'function') {
+        ref(node);
+      } else if (ref && 'current' in ref) {
+        (ref as React.MutableRefObject<HTMLDialogElement | null>).current = node;
+      }
+    }, [dialogRef, containerRef, ref]);
+
+    // Handle dialog open/close
+    useEffect(() => {
+      const dialog = dialogRef.current || internalRef.current;
+      if (!dialog) return;
+
+      if (open) {
+        // Log all dialogs in DOM before opening
+        const allDialogsBefore = document.querySelectorAll('dialog[role="dialog"]');
+        const dialogsBefore = Array.from(allDialogsBefore).map((d) => {
+          const dialogEl = d as HTMLDialogElement;
+          return {
+            persistenceKey: dialogEl.getAttribute('data-persistence-key') || 'NO-KEY',
+            open: dialogEl.open,
+            isCurrent: d === dialog,
+          };
+        });
+        console.log('[Dialog] 🟢 OPENING', {
+          persistenceKey,
+          dialogsInDOM: dialogsBefore,
+          totalDialogs: allDialogsBefore.length,
+        });
+        
+        // Use requestAnimationFrame to ensure DOM is ready
+        // Lock was already checked in the earlier useEffect, so we can proceed
+        requestAnimationFrame(() => {
+          if (dialog && open) {
+            // Before opening, close any other open dialogs (safety check)
+            const allDialogs = document.querySelectorAll('dialog[role="dialog"]');
+            allDialogs.forEach((d) => {
+              const dialogEl = d as HTMLDialogElement;
+              if (dialogEl !== dialog && dialogEl.open) {
+                dialogEl.setAttribute('data-duplicate-cleanup', 'true');
+                dialogEl.close();
+              }
+            });
+            
+            console.log('[Dialog] ✅ showModal() called', { persistenceKey });
+            dialog.showModal();
+          }
+        });
+      } else {
+        // Close dialog before it's removed from DOM
+        if (dialog.open) {
+          console.log('[Dialog] 🔴 CLOSING', { persistenceKey });
+          dialog.close();
+          // Release the lock
+          releaseDialogLock(persistenceKey);
+          
+          // After closing, check if any other dialogs with persistence are trying to open
+          // Only close dialogs that have persistence (data-persistence-key attribute)
+          // Non-persistent dialogs should be left alone
+          setTimeout(() => {
+            const allDialogs = document.querySelectorAll('dialog[role="dialog"]');
+            allDialogs.forEach((d) => {
+              const dialogEl = d as HTMLDialogElement;
+              if (dialogEl !== dialog && dialogEl.open) {
+                const otherPersistenceKey = dialogEl.getAttribute('data-persistence-key');
+                // Only close dialogs that have persistence (they might auto-open)
+                // Non-persistent dialogs are user-controlled and shouldn't be closed
+                if (otherPersistenceKey) {
+                  console.warn('[Dialog] 🗑️ Closing other persisted dialog after lock release:', {
+                    persistenceKey,
+                    otherPersistenceKey,
+                  });
+                  dialogEl.setAttribute('data-duplicate-cleanup', 'true');
+                  dialogEl.close();
+                }
+              }
+            });
+          }, 50);
+        }
+      }
+    }, [open, persistenceKey, dialogRef]);
+
+    // Handle close event - sync state when dialog is closed externally
+    // Also track when dialog is closed by user action (for persistence clearing)
+    useEffect(() => {
+      const dialog = dialogRef.current || internalRef.current;
+      if (!dialog) return;
+
+      const handleClose = () => {
+        // Check if this close was initiated by the user (via close button)
+        const wasUserClosed = dialog.hasAttribute('data-user-closed');
+        if (wasUserClosed) {
+          dialog.removeAttribute('data-user-closed');
+          if (hasInitializedRef.current) {
+            wasClosedByUserRef.current = true;
+          }
+        }
+
+        // Ignore duplicate cleanup closes
+        const isDuplicateCleanup = dialog.hasAttribute('data-duplicate-cleanup');
+        if (isDuplicateCleanup) {
+          dialog.removeAttribute('data-duplicate-cleanup');
+          return;
+        }
+        
+        if (!dialog.open && open) {
+          // Mark as closed by user if this wasn't an auto-open scenario
+          if (hasInitializedRef.current && !wasUserClosed) {
+            wasClosedByUserRef.current = true;
+          }
+          onOpenChange(false);
+        } else if (!dialog.open && !open && hasInitializedRef.current && wasUserClosed) {
+          wasClosedByUserRef.current = true;
+        }
+      };
+
+      dialog.addEventListener('close', handleClose);
+      return () => {
+        dialog.removeEventListener('close', handleClose);
+      };
+    }, [open, onOpenChange, dialogRef]);
+
+    // Handle cancel event (Escape or backdrop click)
+    useEffect(() => {
+      const dialog = dialogRef.current || internalRef.current;
+      if (!dialog) return;
+
+      const handleCancel = (e: Event) => {
+        if (preventCloseOnEscape || preventCloseOnOutsideClick) {
+          e.preventDefault();
+          return;
+        }
+        // Mark as closed by user and clear persisted state
+        wasClosedByUserRef.current = true;
+        if (persistenceKey && persistOpenState && clearDraft) {
+          clearDraft();
+        }
+        onOpenChange(false);
+      };
+
+      dialog.addEventListener('cancel', handleCancel);
+      return () => {
+        dialog.removeEventListener('cancel', handleCancel);
+      };
+    }, [preventCloseOnEscape, preventCloseOnOutsideClick, onOpenChange, dialogRef, persistenceKey, persistOpenState, clearDraft]);
+
+    // Merge smart dimensions with provided style
+    const mergedStyle = React.useMemo(() => {
+      if (Object.keys(smartDimensions).length === 0) {
+        return style;
+      }
+
+      const finalStyle: React.CSSProperties = { ...smartDimensions, ...style };
+      
+      if (!maxWidth && !maxWidthPercent) {
+        const { maxWidth: _, ...styleWithoutMaxWidth } = finalStyle;
+        return styleWithoutMaxWidth;
+      }
+      
+      return finalStyle;
+    }, [smartDimensions, style, maxWidth, maxWidthPercent]);
+
+    // Track if lock has been acquired (set by useEffect when open becomes true)
+    const [lockAcquired, setLockAcquired] = React.useState(false);
+    
+    // Check lock BEFORE allowing dialog to open (synchronous check)
+    // This prevents React from even trying to open if another dialog is open
+    useEffect(() => {
+      if (!open) {
+        setLockAcquired(false);
+        return;
+      }
+
+      // Synchronously check if we can acquire the lock
+      const acquired = acquireDialogLock(persistenceKey);
+      setLockAcquired(acquired);
+      
+      if (!acquired) {
+        // Another dialog is open - prevent this one from opening
+        console.warn('[Dialog] ⚠️ Cannot open - another dialog holds the lock', {
+          persistenceKey,
+        });
+        // Immediately close this dialog's React state
+        onOpenChange?.(false);
+        return;
+      }
+      
+      // Lock acquired successfully - dialog can proceed to open
+    }, [open, persistenceKey, onOpenChange]);
+
+    // Synchronously check if we can render (must hold lock if open)
+    const canRender = React.useMemo(() => {
+      if (!open) {
+        return true; // Can always render when closed
+      }
+      if (!persistenceKey) {
+        return true; // Non-persisted dialogs can always render
+      }
+      // Use the lockAcquired state which is set by the effect
+      return lockAcquired;
+    }, [open, persistenceKey, lockAcquired]);
+
+    return (
+      <DialogPortal>
+        {open && canRender && (
+          <dialog
+            ref={mergedRef}
+            className={cn(
+              'fixed left-[50%] top-[50%] z-[51] w-full translate-x-[-50%] translate-y-[-50%] border bg-background shadow-lg duration-200',
+              'animate-in fade-in-0 zoom-in-95 slide-in-from-left-1/2 slide-in-from-top-[48%]',
+              'sm:rounded-lg',
+              // Reset native dialog styles
+              'm-0 p-0 max-w-none max-h-none w-auto h-auto border-0 bg-transparent outline-none',
+              // Apply our custom styling
+              'border bg-background shadow-lg',
+              // Style native backdrop pseudo-element (Tailwind v4 supports arbitrary variants)
+              '[&::backdrop]:bg-black/50 [&::backdrop]:animate-in [&::backdrop]:fade-in-0',
+              // Only apply size classes if not using smart width
+              !maxWidth && !maxWidthPercent && sizeClasses[size],
+              // Auto size gets special handling
+              size === 'auto' && 'w-fit max-w-[90vw] sm:max-w-[80vw]',
+              // Layout classes: use flex when we have height constraints or enableScrolling is true
+              // Flex layout is needed for proper scrolling when height is constrained
+              (enableScrolling || hasHeightConstraint) ? 'flex flex-col px-6' : 'grid gap-4 p-6',
+              // Full screen handling
+              size === 'full' && 'sm:left-[50%] sm:top-[50%] sm:translate-x-[-50%] sm:translate-y-[-50%] left-0 top-0 translate-x-0 translate-y-0 h-full rounded-none sm:h-auto sm:rounded-lg',
+              // Overflow handling for scrolling mode or when height is constrained
+              (enableScrolling || hasHeightConstraint) && 'overflow-hidden',
+              className
+            )}
+            style={mergedStyle}
+            role="dialog"
+            aria-modal="true"
+            aria-labelledby={titleId}
+            aria-describedby={descriptionId}
+            title={title}
+            aria-description={description}
+            data-persistence-key={persistenceKey && persistOpenState ? persistenceKey : undefined}
+            {...props}
+          >
+            <DialogCloseContext.Provider value={markClosedByUser}>
+              {children}
+              {showCloseButton && (
+                <DialogClose />
+              )}
+            </DialogCloseContext.Provider>
+          </dialog>
+        )}
+      </DialogPortal>
+    );
+  }
+);
+DialogContent.displayName = 'DialogContent';
+
+/**
+ * DialogClose component
+ * Button to close the dialog
+ */
+const DialogClose = React.forwardRef<HTMLButtonElement, DialogCloseProps>(
+  ({ className, onClick, ...props }, ref) => {
+    // Call all hooks unconditionally at the top level
+    // Hooks must be called in the same order on every render
+    const { onOpenChange, markClosedByUser: contextMarkClosedByUser } = useDialogContext();
+    // Prefer DialogContext markClosedByUser (available to all components), fallback to DialogCloseContext (for backwards compatibility)
+    const dialogCloseContextValue = React.useContext(DialogCloseContext);
+    const markClosedByUser = contextMarkClosedByUser || dialogCloseContextValue;
+    
+    const handleClick = (e: React.MouseEvent<HTMLButtonElement>) => {
+      // Mark dialog as closed by user before calling onOpenChange
+      // This ensures the persisted state is cleared when user clicks close button
+      if (markClosedByUser) {
+        markClosedByUser();
+      }
+      
+      onClick?.(e);
+      onOpenChange(false);
+    };
+
+    return (
+      <button
         ref={ref}
-        onEscapeKeyDown={preventCloseOnEscape ? handleEscapeKeyDown : undefined}
-        onPointerDownOutside={handlePointerDownOutside}
+        type="button"
+        onClick={handleClick}
         className={cn(
-          'fixed left-[50%] top-[50%] z-[51] w-full translate-x-[-50%] translate-y-[-50%] border bg-background shadow-lg duration-200 data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[state=closed]:slide-out-to-left-1/2 data-[state=closed]:slide-out-to-top-[48%] data-[state=open]:slide-in-from-left-1/2 data-[state=open]:slide-in-from-top-[48%] sm:rounded-lg',
-          // Reset native dialog styles that interfere with our custom styling
-          'm-0 p-0 max-w-none max-h-none w-auto h-auto border-0 bg-transparent outline-none',
-          // Apply our custom styling
-          'border bg-background shadow-lg',
-          // Only apply size classes if not using smart width
-          !maxWidth && !maxWidthPercent && sizeClasses[size],
-          // Auto size gets special handling for content fitting
-          size === 'auto' && 'w-fit max-w-[90vw] sm:max-w-[80vw]',
-          // Layout classes based on scrolling mode
-          enableScrolling ? 'flex flex-col' : 'grid gap-4 p-6',
-          // Full screen handling
-          size === 'full' && 'sm:left-[50%] sm:top-[50%] sm:translate-x-[-50%] sm:translate-y-[-50%] left-0 top-0 translate-x-0 translate-y-0 h-full rounded-none sm:h-auto sm:rounded-lg',
-          // Overflow handling for scrolling mode
-          enableScrolling && 'overflow-hidden',
+          'absolute right-4 top-4 z-10 rounded-sm opacity-70 ring-offset-background transition-opacity hover:opacity-100 focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2 disabled:pointer-events-none',
           className
         )}
-        style={mergedStyle}
         {...props}
       >
-        {children}
-        {showCloseButton && (
-          <DialogPrimitive.Close className="absolute right-4 top-4 z-10 rounded-sm opacity-70 ring-offset-background transition-opacity hover:opacity-100 focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2 disabled:pointer-events-none data-[state=open]:bg-accent data-[state=open]:text-muted-foreground">
-            <X className="size-4" />
-            <span className="sr-only">Close</span>
-          </DialogPrimitive.Close>
-        )}
-      </DialogPrimitive.Content>
-    </DialogPortal>
-  );
-});
-DialogContent.displayName = DialogPrimitive.Content.displayName;
+        <X className="size-4" />
+        <span className="sr-only">Close</span>
+      </button>
+    );
+  }
+);
+DialogClose.displayName = 'DialogClose';
 
 /**
  * DialogHeader component
  * Semantic header container for dialog title and description with optional sticky behavior
- * 
- * @param props - Header configuration and styling
- * @returns JSX.Element - The dialog header container using semantic <header> element
- * 
- * @example
- * ```tsx
- * <DialogHeader sticky={true}>
- *   <DialogTitle>Sticky Header</DialogTitle>
- *   <DialogDescription>This header stays visible while scrolling.</DialogDescription>
- * </DialogHeader>
- * ```
  */
 const DialogHeader = ({
   className,
@@ -589,7 +1414,7 @@ const DialogHeader = ({
   <header
     className={cn(
       'flex flex-col space-y-1.5 text-center sm:text-left',
-      sticky ? 'sticky top-0 z-10 bg-background p-6 pb-4 border-b' : 'p-6 pb-4',
+      sticky ? 'sticky top-0 z-10 bg-background pt-6 pb-4 border-b' : 'py-2',
       className
     )}
     {...props}
@@ -600,27 +1425,6 @@ DialogHeader.displayName = 'DialogHeader';
 /**
  * DialogBody component
  * Semantic main content area for dialog body content with scrollable functionality
- * Supports both React children and safe HTML content rendering
- * 
- * @param props - Body configuration and styling
- * @returns JSX.Element - The scrollable dialog body container using semantic <main> element
- * 
- * @example
- * ```tsx
- * // Using React children
- * <DialogBody>
- *   <section className="space-y-4">
- *     <h4>Content Title</h4>
- *     <p>Long content that will scroll...</p>
- *   </section>
- * </DialogBody>
- * 
- * // Using HTML content
- * <DialogBody 
- *   htmlContent="<h2>Import Instructions</h2><p>Upload a CSV file with the following format:</p><ul><li>Required columns: name, email</li><li>Optional columns: phone, address</li></ul>"
- *   allowHtml={true}
- * />
- * ```
  */
 const DialogBody = ({
   className,
@@ -640,7 +1444,6 @@ const DialogBody = ({
     };
   }, [maxHeight, style]);
 
-  // Process HTML content if provided
   const processedHtmlContent = React.useMemo(() => {
     if (!htmlContent || !allowHtml) {
       return null;
@@ -654,13 +1457,46 @@ const DialogBody = ({
     return result.html;
   }, [htmlContent, allowHtml, strictSanitization, logWarnings]);
 
-  // Determine if htmlContent was provided (even if processing failed)
   const hasHtmlContent = Boolean(htmlContent && allowHtml);
 
+  // Check if parent dialog has height constraint by checking if it uses flex layout
+  // When dialog has height constraint, it uses flex layout, and DialogBody should
+  // use flex properties to properly participate in the layout and only scroll when constrained
+  const { dialogRef, open } = useDialogContext();
+  const [isInFlexContainer, setIsInFlexContainer] = React.useState(false);
+
+  React.useEffect(() => {
+    if (!open) {
+      setIsInFlexContainer(false);
+      return;
+    }
+
+    // Check if dialog uses flex layout (indicates height constraint)
+    const checkFlexLayout = () => {
+      const dialog = dialogRef?.current;
+      if (!dialog) {
+        setIsInFlexContainer(false);
+        return;
+      }
+      const styles = window.getComputedStyle(dialog);
+      const isFlex = styles.display === 'flex' && styles.flexDirection === 'column';
+      setIsInFlexContainer(isFlex);
+    };
+
+    // Check after a brief delay to ensure styles are applied
+    const timeoutId = setTimeout(checkFlexLayout, 0);
+    checkFlexLayout(); // Also check immediately
+
+    return () => clearTimeout(timeoutId);
+  }, [open, dialogRef]);
+
   return (
     <main
       className={cn(
-        'overflow-y-auto px-6 py-2',
+        'overflow-y-auto py-2',
+        // When in a flex container with height constraint, use flex properties
+        // so DialogBody takes up available space and only scrolls when content exceeds it
+        isInFlexContainer && 'flex-1 min-h-0',
         className
       )}
       style={mergedStyle}
@@ -669,16 +1505,16 @@ const DialogBody = ({
       {...props}
     >
       {processedHtmlContent ? (
-        <div 
+        <p 
           dangerouslySetInnerHTML={{ __html: processedHtmlContent }}
           className="prose prose-sm max-w-none"
         />
       ) : (
         <>
           {hasHtmlContent && !processedHtmlContent && (
-            <div className="text-acc-500 mb-2">
+            <p className="text-acc-500 mb-2">
               No HTML content processed. Showing children instead.
-            </div>
+            </p>
           )}
           {children}
         </>
@@ -691,17 +1527,6 @@ DialogBody.displayName = 'DialogBody';
 /**
  * DialogFooter component
  * Semantic footer container for dialog action buttons with optional sticky behavior
- * 
- * @param props - Footer configuration and styling
- * @returns JSX.Element - The dialog footer container using semantic <footer> element
- * 
- * @example
- * ```tsx
- * <DialogFooter sticky={true}>
- *   <Button variant="outline">Cancel</Button>
- *   <Button>Save changes</Button>
- * </DialogFooter>
- * ```
  */
 const DialogFooter = ({
   className,
@@ -710,9 +1535,8 @@ const DialogFooter = ({
 }: DialogFooterProps) => (
   <footer
     className={cn(
-      // Only apply default layout classes if no custom className is provided
       !className && 'flex flex-col-reverse sm:flex-row sm:justify-end sm:space-x-2',
-      !className && (sticky ? 'sticky bottom-0 z-10 bg-background p-6 pt-4 border-t' : 'p-6 pt-4'),
+      !className && (sticky ? 'sticky bottom-0 z-10 bg-background pt-4 pb-6 border-t' : 'py-2'),
       className
     )}
     {...props}
@@ -720,62 +1544,70 @@ const DialogFooter = ({
 );
 DialogFooter.displayName = 'DialogFooter';
 
-const DialogTitle = React.forwardRef<
-  React.ElementRef<typeof DialogPrimitive.Title>,
-  DialogTitleProps
->(({ className, htmlContent, allowHtml = true, children, ...props }, ref) => {
-  const processedHtmlContent = React.useMemo(() => {
-    if (!htmlContent || !allowHtml) {
-      return null;
-    }
+/**
+ * DialogTitle component
+ * Title element with ARIA support
+ */
+const DialogTitle = React.forwardRef<HTMLHeadingElement, DialogTitleProps>(
+  ({ className, htmlContent, allowHtml = true, children, ...props }, ref) => {
+    const { titleId } = useDialogContext();
 
-    const result = renderSafeHtml(htmlContent, {
-      strict: true,
-      logWarnings: false
-    });
+    const processedHtmlContent = React.useMemo(() => {
+      if (!htmlContent || !allowHtml) {
+        return null;
+      }
 
-    return result.html;
-  }, [htmlContent, allowHtml]);
+      const result = renderSafeHtml(htmlContent, {
+        strict: true,
+        logWarnings: false
+      });
 
-  return (
-    <DialogPrimitive.Title
-      ref={ref}
-      className={cn(
-        className
-      )}
-      {...props}
-    >
-      {processedHtmlContent ? (
-        <span dangerouslySetInnerHTML={{ __html: processedHtmlContent }} />
-      ) : (
-        children
-      )}
-    </DialogPrimitive.Title>
-  );
-});
-DialogTitle.displayName = DialogPrimitive.Title.displayName;
+      return result.html;
+    }, [htmlContent, allowHtml]);
 
-const DialogDescription = React.forwardRef<
-  HTMLHeadingElement,
-  DialogDescriptionProps
->(({ className, htmlContent, allowHtml = true, children, ...props }, ref) => {
-  const processedHtmlContent = React.useMemo(() => {
-    if (!htmlContent || !allowHtml) {
-      return null;
-    }
+    return (
+      <h2
+        ref={ref}
+        id={titleId}
+        className={cn(className)}
+        {...props}
+      >
+        {processedHtmlContent ? (
+          <span dangerouslySetInnerHTML={{ __html: processedHtmlContent }} />
+        ) : (
+          children
+        )}
+      </h2>
+    );
+  }
+);
+DialogTitle.displayName = 'DialogTitle';
 
-    const result = renderSafeHtml(htmlContent, {
-      strict: true,
-      logWarnings: false
-    });
+/**
+ * DialogDescription component
+ * Description element with ARIA support
+ */
+const DialogDescription = React.forwardRef<HTMLParagraphElement, DialogDescriptionProps>(
+  ({ className, htmlContent, allowHtml = true, children, ...props }, ref) => {
+    const { descriptionId } = useDialogContext();
 
-    return result.html;
-  }, [htmlContent, allowHtml]);
+    const processedHtmlContent = React.useMemo(() => {
+      if (!htmlContent || !allowHtml) {
+        return null;
+      }
 
-  return (
-    <DialogPrimitive.Description asChild>
-      <h5
+      const result = renderSafeHtml(htmlContent, {
+        strict: true,
+        logWarnings: false
+      });
+
+      return result.html;
+    }, [htmlContent, allowHtml]);
+
+    return (
+      <p
         ref={ref}
+        id={descriptionId}
         className={cn(className)}
         {...props}
       >
@@ -784,16 +1616,15 @@ const DialogDescription = React.forwardRef<
         ) : (
           children
         )}
-      </h5>
-    </DialogPrimitive.Description>
-  );
-});
-DialogDescription.displayName = DialogPrimitive.Description.displayName;
+      </p>
+    );
+  }
+);
+DialogDescription.displayName = 'DialogDescription';
 
 export {
   Dialog,
   DialogPortal,
-  DialogOverlay,
   DialogClose,
   DialogTrigger,
   DialogContent,