Refactor | Add JSDocs for the new dialog system

Author: Destiny911gtr

contexts/dialog-context/dialog-context.tsx

@@ -13,18 +13,41 @@ const DialogContext = React.createContext<DialogContextValue | undefined>(
   undefined,
 );
 
+/**
+ * Dialog provider component for the global dialog system
+ * @description Must be placed at the root of your app to enable dialog functionality
+ * @param {React.ReactNode} children - Your app components
+ * @example
+ * ```tsx
+ * function App() {
+ *   return (
+ *     <DialogProvider>
+ *       <YourAppContent />
+ *     </DialogProvider>
+ *   );
+ * }
+ * ```
+ */
 export function DialogProvider({ children }: { children: React.ReactNode }) {
   const queueRef = useRef(new DialogQueue());
   const [activeDialog, setActiveDialog] = useState<DialogConfig | null>(null);
   const timerRef = useRef<number | null>(null);
+  const activeDialogIdRef = useRef<string | null>(null);
 
   const processQueue = useCallback(() => {
     const next = queueRef.current.getNext();
     setActiveDialog(next);
+    activeDialogIdRef.current = next?.id || null;
 
     if (next?.autoHideDuration && next.autoHideDuration > 0) {
       timerRef.current = setTimeout(() => {
-        hideDialog(next.id);
+        if (next?.id) {
+          const dialog = queueRef.current.get(next.id);
+          queueRef.current.removeById(next.id);
+          dialog?.onDismiss?.();
+        }
+        activeDialogIdRef.current = null;
+        processQueue();
       }, next.autoHideDuration);
     }
   }, []);
@@ -185,16 +208,19 @@ export function DialogProvider({ children }: { children: React.ReactNode }) {
     (id?: string) => {
       clearTimer();
 
-      const targetId = id || activeDialog?.id;
+      const targetId = id || activeDialogIdRef.current;
       if (targetId) {
         const dialog = queueRef.current.get(targetId);
         queueRef.current.removeById(targetId);
         dialog?.onDismiss?.();
+        if (targetId === activeDialogIdRef.current) {
+          activeDialogIdRef.current = null;
+        }
       }
 
       processQueue();
     },
-    [activeDialog, clearTimer, processQueue],
+    [clearTimer, processQueue],
   );
 
   const clearDialogsByIds = useCallback(
@@ -279,6 +305,47 @@ export function DialogProvider({ children }: { children: React.ReactNode }) {
   );
 }
 
+/**
+ * Hook for accessing the dialog context API
+ * @description Provides all dialog management methods
+ * @returns {DialogContextValue} Dialog context with all management methods
+ * @throws {Error} If used outside of DialogProvider
+ * @example
+ * ```tsx
+ * const { showError, showSuccess, showPersistent, clearDialogsByIds } = useDialog();
+ *
+ * // Show error with icon
+ * showError("Network error", {
+ *   title: "Connection Failed",
+ *   icon: () => <WifiOff size={50} color="#ef4444" />
+ * });
+ *
+ * // Show dialog with custom content
+ * showDialog({
+ *   title: "Confirm Action",
+ *   content: () => (
+ *     <View className="py-4">
+ *       <Text className="text-center mb-4">Are you sure?</Text>
+ *       <ProgressBar progress={75} />
+ *     </View>
+ *   )
+ * });
+ *
+ * // Show persistent dialog with progress
+ * const controller = showPersistent({
+ *   message: "Uploading...",
+ *   customId: "upload-progress"
+ * });
+ * controller.updateProgress(50);
+ *
+ * // Clear specific dialogs by custom ID
+ * clearDialogsByIds(["upload-progress", "toast-notification"]);
+ *
+ * // Priority queue: HIGH will interrupt LOW
+ * showInfo("This will be queued");
+ * showError("This shows immediately and interrupts");
+ * ```
+ */
 export function useDialog(): DialogContextValue {
   const context = React.useContext(DialogContext);
   if (!context) {

contexts/dialog-context/dialog-templates.tsx

@@ -1,14 +1,40 @@
-import React from "react";
 import {
   AlertCircle,
   CheckCircle,
   Info,
   Loader2,
   XCircle,
 } from "lucide-react-native";
+import React from "react";
 import { DialogConfig, DialogPriority } from "./dialog-types";
 
+/**
+ * Pre-configured dialog templates for common use cases
+ * @description Ready-to-use dialog configurations with appropriate icons, priorities, and behaviors
+ * @example
+ * ```tsx
+ * const { showError, showSuccess } = useDialog();
+ *
+ * // Use error template
+ * showError(DialogTemplates.error("Failed to save file"));
+ *
+ * // Use success template with custom title
+ * showSuccess(DialogTemplates.success("File uploaded successfully", {
+ *   title: "Upload Complete"
+ * }));
+ * ```
+ */
 export const DialogTemplates = {
+  /**
+   * Error dialog template with high priority and red X icon
+   * @param {string} message - Error message to display
+   * @param {Partial<DialogConfig>} options - Additional configuration overrides
+   * @returns {DialogConfig} Complete error dialog configuration
+   * @example
+   * ```tsx
+   * showError(DialogTemplates.error("Network connection failed"));
+   * ```
+   */
   error: (message: string, options?: Partial<DialogConfig>): DialogConfig => ({
     type: "error",
     priority: DialogPriority.HIGH,
@@ -20,6 +46,16 @@ export const DialogTemplates = {
     timestamp: Date.now(),
   }),
 
+  /**
+   * Success dialog template with green checkmark and auto-hide
+   * @param {string} message - Success message to display
+   * @param {Partial<DialogConfig>} options - Additional configuration overrides
+   * @returns {DialogConfig} Complete success dialog configuration
+   * @example
+   * ```tsx
+   * showSuccess(DialogTemplates.success("File uploaded successfully!"));
+   * ```
+   */
   success: (
     message: string,
     options?: Partial<DialogConfig>,
@@ -35,6 +71,16 @@ export const DialogTemplates = {
     timestamp: Date.now(),
   }),
 
+  /**
+   * Info dialog template with blue info icon and low priority
+   * @param {string} message - Information message to display
+   * @param {Partial<DialogConfig>} options - Additional configuration overrides
+   * @returns {DialogConfig} Complete info dialog configuration
+   * @example
+   * ```tsx
+   * showInfo(DialogTemplates.info("New features available"));
+   * ```
+   */
   info: (message: string, options?: Partial<DialogConfig>): DialogConfig => ({
     type: "info",
     priority: DialogPriority.LOW,
@@ -47,6 +93,16 @@ export const DialogTemplates = {
     timestamp: Date.now(),
   }),
 
+  /**
+   * Warning dialog template with amber warning icon
+   * @param {string} message - Warning message to display
+   * @param {Partial<DialogConfig>} options - Additional configuration overrides
+   * @returns {DialogConfig} Complete warning dialog configuration
+   * @example
+   * ```tsx
+   * showAlert(DialogTemplates.warning("Battery is low"));
+   * ```
+   */
   warning: (
     message: string,
     options?: Partial<DialogConfig>,
@@ -61,6 +117,16 @@ export const DialogTemplates = {
     timestamp: Date.now(),
   }),
 
+  /**
+   * Loading dialog template with spinner and persistent priority
+   * @param {string} message - Loading message to display
+   * @param {Partial<DialogConfig>} options - Additional configuration overrides
+   * @returns {DialogConfig} Complete loading dialog configuration
+   * @example
+   * ```tsx
+   * const controller = showPersistent(DialogTemplates.loading("Processing data..."));
+   * ```
+   */
   loading: (
     message: string,
     options?: Partial<DialogConfig>,
@@ -75,6 +141,16 @@ export const DialogTemplates = {
     timestamp: Date.now(),
   }),
 
+  /**
+   * Critical error dialog template with highest priority and cannot be dismissed
+   * @param {string} message - Critical error message to display
+   * @param {Partial<DialogConfig>} options - Additional configuration overrides
+   * @returns {DialogConfig} Complete critical error dialog configuration
+   * @example
+   * ```tsx
+   * showDialog(DialogTemplates.critical("System failure - app must restart"));
+   * ```
+   */
   critical: (
     message: string,
     options?: Partial<DialogConfig>,