@jmruthers/pace-core 0.6.5 → 0.6.7

package/src/components/Dialog/Dialog.tsx

@@ -90,10 +90,14 @@
 import * as React from 'react';
 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, useRef, useCallback, useId } 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
@@ -139,6 +143,8 @@ interface DialogContextValue {
   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);
@@ -204,10 +210,12 @@ export interface DialogContentProps extends React.HTMLAttributes<HTMLDialogEleme
   minHeight?: string;
   /** Minimum width in CSS units */
   minWidth?: string;
-  /** Dialog title for accessibility (sets native title attribute) */
+  /** Dialog title - sets native title attribute and aria-labelledby */
   title?: string;
-  /** Dialog description for accessibility (sets aria-description attribute) */
+  /** Dialog description - sets native aria-description attribute */
   description?: string;
+  /** Whether to persist open state across tab switches */
+  persistOpenState?: boolean;
 }
 
 /**
@@ -311,6 +319,8 @@ const Dialog = React.memo<DialogProps>(function Dialog({
   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;
@@ -328,14 +338,39 @@ const Dialog = React.memo<DialogProps>(function Dialog({
     dialogRef,
     titleId,
     descriptionId,
-  }), [open, handleOpenChange, 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}>
-      {children}
+      <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';
 
 /**
@@ -512,6 +547,89 @@ 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
@@ -538,16 +656,425 @@ const DialogContent = React.forwardRef<HTMLDialogElement, DialogContentProps>(
     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
+
+    // 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;
+
+    // Set dialog title in context for persistence
+    useEffect(() => {
+      if (setDialogTitle) {
+        setDialogTitle(title);
+      }
+    }, [title, setDialogTitle]);
+
+    // 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,
+      }
+    );
+
+    // 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);
+    
+    // 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);
     
     // 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);
 
+    // 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, 
+      maxHeightPercent: effectiveMaxHeightPercent, 
       maxWidthPercent,
       maxHeight, 
       maxWidth,
@@ -592,30 +1119,105 @@ const DialogContent = React.forwardRef<HTMLDialogElement, DialogContentProps>(
       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, dialogRef]);
+    }, [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 = () => {
-        // Only update state if dialog was closed externally (not via our state change)
-        // Check if dialog is actually closed and our state says it should be open
+        // 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;
         }
       };
 
@@ -635,6 +1237,11 @@ const DialogContent = React.forwardRef<HTMLDialogElement, DialogContentProps>(
           e.preventDefault();
           return;
         }
+        // Mark as closed by user and clear persisted state
+        wasClosedByUserRef.current = true;
+        if (persistenceKey && persistOpenState && clearDraft) {
+          clearDraft();
+        }
         onOpenChange(false);
       };
 
@@ -642,7 +1249,7 @@ const DialogContent = React.forwardRef<HTMLDialogElement, DialogContentProps>(
       return () => {
         dialog.removeEventListener('cancel', handleCancel);
       };
-    }, [preventCloseOnEscape, preventCloseOnOutsideClick, onOpenChange, dialogRef]);
+    }, [preventCloseOnEscape, preventCloseOnOutsideClick, onOpenChange, dialogRef, persistenceKey, persistOpenState, clearDraft]);
 
     // Merge smart dimensions with provided style
     const mergedStyle = React.useMemo(() => {
@@ -660,9 +1267,49 @@ const DialogContent = React.forwardRef<HTMLDialogElement, DialogContentProps>(
       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 && (
+        {open && canRender && (
           <dialog
             ref={mergedRef}
             className={cn(
@@ -673,18 +1320,18 @@ const DialogContent = React.forwardRef<HTMLDialogElement, DialogContentProps>(
               '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',
+              // Backdrop styling is handled via core.css only
               // 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 based on scrolling mode
-              enableScrolling ? 'flex flex-col px-6' : 'grid gap-4 p-6',
+              // 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
-              enableScrolling && 'overflow-hidden',
+              // Overflow handling for scrolling mode or when height is constrained
+              (enableScrolling || hasHeightConstraint) && 'overflow-hidden',
               className
             )}
             style={mergedStyle}
@@ -694,12 +1341,15 @@ const DialogContent = React.forwardRef<HTMLDialogElement, DialogContentProps>(
             aria-describedby={descriptionId}
             title={title}
             aria-description={description}
+            data-persistence-key={persistenceKey && persistOpenState ? persistenceKey : undefined}
             {...props}
           >
-            {children}
-            {showCloseButton && (
-              <DialogClose />
-            )}
+            <DialogCloseContext.Provider value={markClosedByUser}>
+              {children}
+              {showCloseButton && (
+                <DialogClose />
+              )}
+            </DialogCloseContext.Provider>
           </dialog>
         )}
       </DialogPortal>
@@ -708,19 +1358,53 @@ const DialogContent = React.forwardRef<HTMLDialogElement, DialogContentProps>(
 );
 DialogContent.displayName = 'DialogContent';
 
+/**
+ * Props for the DialogClose component
+ * @public
+ */
+export interface DialogCloseProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
+  /** Whether to merge props with child element instead of rendering a button */
+  asChild?: boolean;
+}
+
 /**
  * DialogClose component
  * Button to close the dialog
  */
 const DialogClose = React.forwardRef<HTMLButtonElement, DialogCloseProps>(
-  ({ className, ...props }, ref) => {
-    const { onOpenChange } = useDialogContext();
+  ({ className, asChild = false, children, 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 = useCallback((e: React.MouseEvent<HTMLElement>) => {
+      // 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 as React.MouseEvent<HTMLButtonElement>);
+      onOpenChange(false);
+    }, [onOpenChange, markClosedByUser, 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}
         type="button"
-        onClick={() => onOpenChange(false)}
+        onClick={handleClick}
         className={cn(
           '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
@@ -792,10 +1476,44 @@ const DialogBody = ({
 
   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 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}