@jmruthers/pace-core 0.6.10 → 0.6.11

package/src/components/Form/Form.tsx

@@ -69,10 +69,15 @@
  * - @hookform/resolvers/zod - Zod validation integration
  * - zod - Schema validation
  * - React 19+ - Hooks and context
+ *
+ * @remarks
+ * Form calls useLocation (react-router-dom) and useUnifiedAuth for persistence key derivation.
+ * Use Form inside a React Router provider and UnifiedAuthProvider; outside those contexts
+ * those hooks will throw. Tests must wrap Form in the appropriate providers (see test utils).
  */
 
-import React, { useEffect, useMemo, useRef } from 'react';
-import { useForm, FormProvider, UseFormReturn, FieldValues, DefaultValues, SubmitHandler, SubmitErrorHandler, useFormContext, Controller, FieldPath, ControllerRenderProps, ControllerFieldState, UseFormStateReturn, useWatch } from 'react-hook-form';
+import React, { useMemo } from 'react';
+import { useForm, FormProvider, UseFormReturn, FieldValues, DefaultValues, SubmitHandler, SubmitErrorHandler, useFormContext, Controller, FieldPath, ControllerRenderProps, ControllerFieldState, UseFormStateReturn } from 'react-hook-form';
 import { zodResolver } from '@hookform/resolvers/zod';
 import { z } from 'zod';
 import { useLocation } from 'react-router-dom';
@@ -80,8 +85,11 @@ import { useUnifiedAuth } from '../../providers/services/UnifiedAuthProvider';
 import { cn } from '../../utils/core/cn';
 import { useSessionDraft } from '../../hooks/useSessionDraft';
 import { deriveFormKey } from '../../utils/persistence/keyDerivation';
-import { filterSensitiveFields, isSensitiveField } from '../../utils/persistence/sensitiveFieldDetection';
+import { filterSensitiveFields } from '../../utils/persistence/sensitiveFieldDetection';
 import { createLogger } from '../../utils/core/logger';
+import { useFormPersistence } from './useFormPersistence';
+import { Input } from '../Input';
+import { Label } from '../Label';
 
 /**
  * Props for the Form component
@@ -248,238 +256,15 @@ export function Form<TFieldValues extends FieldValues = FieldValues>({
     shouldUnregister: false,
   });
 
-  // Track if we've already restored persisted values to prevent infinite loops
-  const hasRestoredRef = useRef(false);
-  const isRestoringRef = useRef(false);
-  const restoreTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
-  const lastRestoredRef = useRef<string | null>(null);
-
-  // Restore persisted values after form initialization
-  // CRITICAL: Must run when persistedValues changes (e.g., when dialog auto-opens)
-  useEffect(() => {
-    // Clear any pending restore
-    if (restoreTimeoutRef.current) {
-      clearTimeout(restoreTimeoutRef.current);
-    }
-
-    // Skip if already restored or currently restoring
-    if (isRestoringRef.current) {
-      return;
-    }
-
-    if (!persistenceKey || !persistedValues || Object.keys(persistedValues).length === 0) {
-      // Mark as restored even if no persisted values (prevents re-running)
-      if (!hasRestoredRef.current) {
-        hasRestoredRef.current = true;
-      }
-      return;
-    }
-
-    // Skip if we've already restored these exact values
-    const persistedValuesStr = JSON.stringify(persistedValues);
-    if (lastRestoredRef.current === persistedValuesStr && hasRestoredRef.current) {
-      return;
-    }
-
-    isRestoringRef.current = true;
-
-    // Defer restoration to prevent blocking and allow form to initialize
-    restoreTimeoutRef.current = setTimeout(() => {
-      // CRITICAL: Handle both numeric keys (from old array-based persistence) and field names
-      // If persistedValues has numeric keys, map them to fieldNames
-      const persistedKeys = Object.keys(persistedValues as Record<string, unknown>);
-      const hasNumericKeys = persistedKeys.length > 0 && persistedKeys.every(key => /^\d+$/.test(key));
-      
-      let valuesToRestore: Partial<TFieldValues>;
-      if (hasNumericKeys && fieldNames.length === persistedKeys.length) {
-        // Map numeric keys to field names
-        valuesToRestore = {} as Partial<TFieldValues>;
-        for (let i = 0; i < fieldNames.length; i++) {
-          const fieldName = fieldNames[i];
-          const numericKey = String(i);
-          if (numericKey in persistedValues) {
-            (valuesToRestore as Record<string, unknown>)[fieldName] = (persistedValues as Record<string, unknown>)[numericKey];
-          }
-        }
-        logger.debug('[Form Persistence] Mapped numeric keys to field names:', {
-          numericKeys: persistedKeys,
-          fieldNames,
-          mappedValues: valuesToRestore,
-        });
-      } else {
-        // Use persistedValues as-is (should have field names as keys)
-        valuesToRestore = persistedValues as Partial<TFieldValues>;
-      }
-
-      // Filter sensitive fields
-      const restoreKeys = Object.keys(valuesToRestore);
-      const filteredPersisted = filterSensitiveFields(
-        valuesToRestore,
-        restoreKeys.length > 0 ? restoreKeys : fieldNames,
-        fieldTypes
-      );
-
-      // Debug: Check which fields are being filtered
-      const sensitiveFields = restoreKeys.filter(name => {
-        const type = fieldTypes?.[name];
-        return isSensitiveField(name, type);
-      });
-
-      logger.debug('[Form Persistence] ✅ Restoring persisted values:', {
-        persistenceKey,
-        persistedValuesKeys: persistedKeys,
-        persistedValuesString: JSON.stringify(persistedValues),
-        hasNumericKeys,
-        valuesToRestoreKeys: Object.keys(valuesToRestore),
-        filteredPersistedKeys: Object.keys(filteredPersisted),
-        fieldNames,
-        sensitiveFields,
-        filteredCount: Object.keys(filteredPersisted).length,
-        persistedCount: persistedKeys.length,
-        timestamp: new Date().toISOString(),
-      });
-
-      // Set values that might not have been in defaultValues
-      const valuesToSet: Partial<TFieldValues> = {};
-      let hasValuesToSet = false;
-
-      for (const [key, value] of Object.entries(filteredPersisted)) {
-        const currentValue = methods.getValues(key as FieldPath<TFieldValues>);
-        // Only set if different from current value (to avoid unnecessary updates)
-        if (currentValue !== value) {
-          (valuesToSet as Record<string, unknown>)[key] = value;
-          hasValuesToSet = true;
-        }
-      }
-
-      if (hasValuesToSet) {
-        logger.debug('[Form Persistence] 🔄 Setting form values via reset():', {
-          persistenceKey,
-          valuesToSetKeys: Object.keys(valuesToSet),
-          valuesToSet,
-          timestamp: new Date().toISOString(),
-        });
-        // Use reset to update all values at once
-        methods.reset({
-          ...methods.getValues(),
-          ...valuesToSet,
-        } as TFieldValues);
-        logger.debug('[Form Persistence] ✅ Form values set successfully', {
-          persistenceKey,
-          currentValues: methods.getValues(),
-        });
-      } else {
-        logger.debug('[Form Persistence] ⏭️ No values to set (all values already match)', {
-          persistenceKey,
-        });
-      }
-
-      lastRestoredRef.current = persistedValuesStr;
-      hasRestoredRef.current = true;
-      isRestoringRef.current = false;
-      restoreTimeoutRef.current = null;
-    }, 100); // Small delay to ensure form is ready
-
-    return () => {
-      if (restoreTimeoutRef.current) {
-        clearTimeout(restoreTimeoutRef.current);
-        restoreTimeoutRef.current = null;
-      }
-    };
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [persistedValues, persistenceKey]); // Run when persistedValues changes (e.g., dialog auto-opens)
-
-  // Log component mount
-
-  // Watch form values for persistence
-  // CRITICAL: Don't pass name parameter - useWatch without name returns all values as an object
-  // If we pass fieldNames array, it returns an array with numeric indices, not an object with field names
-  const watchedValues = useWatch({
-    control: methods.control,
-    // Don't pass name - we want all values as an object, not an array
-  }) as Partial<TFieldValues>;
-
-  // Track previous values to prevent unnecessary persistence updates
-  const previousValuesRef = useRef<string | null>(null);
-  const persistTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
-
-  // Persist form values (filtered for sensitive fields)
-  useEffect(() => {
-    if (!persistenceKey || !watchedValues || isRestoringRef.current) {
-      return;
-    }
-
-    // Skip if values haven't actually changed
-    const currentValuesStr = JSON.stringify(watchedValues);
-    if (currentValuesStr === previousValuesRef.current) {
-      return;
-    }
-
-    previousValuesRef.current = currentValuesStr;
-
-    // Clear any pending persistence
-    if (persistTimeoutRef.current) {
-      clearTimeout(persistTimeoutRef.current);
-    }
-
-    // Debounce persistence to prevent excessive updates while user is typing
-    persistTimeoutRef.current = setTimeout(() => {
-      // Filter sensitive fields before persisting
-      // CRITICAL: Use all keys from watchedValues to ensure we capture all values
-      const allFieldNames = Object.keys(watchedValues as Record<string, unknown>);
-      const filteredValues = filterSensitiveFields(
-        watchedValues as Record<string, unknown>,
-        allFieldNames.length > 0 ? allFieldNames : fieldNames,
-        fieldTypes
-      );
-
-      // Debug: Check which fields are being filtered
-      const sensitiveFields = allFieldNames.filter(name => {
-        const type = fieldTypes?.[name];
-        return isSensitiveField(name, type);
-      });
-
-      logger.debug('[Form Persistence] 💾 Persisting form values:', {
-        persistenceKey,
-        filteredValuesKeys: Object.keys(filteredValues),
-        originalValuesKeys: Object.keys(watchedValues as Record<string, unknown>),
-        allFieldNames,
-        sensitiveFields,
-        filteredCount: Object.keys(filteredValues).length,
-        originalCount: allFieldNames.length,
-        timestamp: new Date().toISOString(),
-      });
-
-      setPersistedValues(filteredValues as Partial<TFieldValues>);
-      
-      // Log sessionStorage after setting (with delay to allow write, only if available)
-      if (persistenceKey && typeof sessionStorage !== 'undefined') {
-        setTimeout(() => {
-          try {
-            const storageKey = `pace-core:draft:${persistenceKey}`;
-            const stored = sessionStorage.getItem(storageKey);
-            logger.debug('[Form Persistence] 📦 SessionStorage AFTER setPersistedValues:', {
-              persistenceKey,
-              storageKey,
-              stored: stored ? JSON.parse(stored) : null,
-            });
-          } catch (error) {
-            // Ignore errors in test environments where sessionStorage may be unavailable
-            logger.debug('[Form Persistence] Could not access sessionStorage after setPersistedValues', { error });
-          }
-        }, 100);
-      }
-      persistTimeoutRef.current = null;
-    }, 300); // Debounce for 300ms
-
-    return () => {
-      if (persistTimeoutRef.current) {
-        clearTimeout(persistTimeoutRef.current);
-        persistTimeoutRef.current = null;
-      }
-    };
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [watchedValues, persistenceKey]); // CRITICAL: Only depend on watchedValues and persistenceKey to prevent infinite loops
+  useFormPersistence({
+    persistenceKey,
+    fieldNames,
+    fieldTypes,
+    methods,
+    persistedValues,
+    setPersistedValues,
+    clearDraft,
+  });
 
   // Enhanced submit handler that clears draft on success
   const handleSubmit = methods.handleSubmit(
@@ -697,59 +482,51 @@ export function FormField<
   const { control } = useFormContext<TFieldValues>();
 
   return (
-    <label className={cn("space-y-2", className)}>
-      {label && (
-        <>
-          {label}
-          {validation?.required && (
-            <span className="text-destructive ml-1" aria-label="required">
-              *
-            </span>
-          )}
-        </>
-      )}
-      
-      <Controller
-        name={name}
-        control={control}
-        rules={validation}
-        render={(props) => {
-          const { field, fieldState } = props;
-          const fieldError = fieldState.error;
-          
-          // Safely extract error message
-          const errorMessage = fieldError && typeof fieldError === 'object' && 'message' in fieldError 
-            ? String(fieldError.message) 
+    <Controller
+      name={name}
+      control={control}
+      rules={validation}
+      render={(props) => {
+        const { field, fieldState } = props;
+        const fieldError = fieldState.error;
+
+        // Safely extract error message
+        const errorMessage =
+          fieldError && typeof fieldError === 'object' && 'message' in fieldError
+            ? String(fieldError.message)
             : undefined;
 
-          if (render) {
-            return render(props);
-          }
-          
-          return (
-            <>
-              <input
-                {...field}
-                id={name}
-                type={type}
-                placeholder={placeholder}
-                data-testid={testId}
-                aria-label={label || placeholder || name}
-                className={cn(
-                  "flex h-10 w-full rounded-md border border-input bg-background px-3 py-2 text-sm ring-offset-background file:border-0 file:bg-transparent file:text-sm file:font-medium placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-50",
-                  fieldError && "border-destructive focus-visible:ring-destructive"
-                )}
-                {...inputProps}
-              />
-              {errorMessage && (
-                <p className="text-destructive" role="alert">
-                  {errorMessage}
-                </p>
-              )}
-            </>
-          );
-        }}
-      />
-    </label>
+        if (render) {
+          return render(props);
+        }
+
+        const { size: inputSize, ...inputPropsRest } = inputProps ?? {};
+        const inputSizeProp =
+          typeof inputSize === 'string' && ['sm', 'md', 'lg'].includes(inputSize)
+            ? inputSize
+            : undefined;
+        return (
+          <Label
+            htmlFor={name}
+            required={!!validation?.required}
+            error={errorMessage}
+            className={cn('space-y-2', className)}
+          >
+            {label}
+            <Input
+              {...field}
+              id={name}
+              type={type}
+              placeholder={placeholder}
+              error={!!fieldError}
+              data-testid={testId}
+              aria-label={label || placeholder || name}
+              {...inputPropsRest}
+              size={inputSizeProp}
+            />
+          </Label>
+        );
+      }}
+    />
   );
 }

package/src/components/Form/useFormPersistence.ts

@@ -0,0 +1,257 @@
+/**
+ * @file Form Persistence Hook
+ * @package @jmruthers/pace-core
+ * @module Components/Form
+ * @since 0.1.0
+ *
+ * Internal hook that syncs form state with session draft (restore on mount/change, persist on value change).
+ * Used only by Form; not part of the public API.
+ */
+
+import { useEffect, useRef } from 'react';
+import { useWatch, type UseFormReturn, type FieldValues, type FieldPath } from 'react-hook-form';
+import { filterSensitiveFields, isSensitiveField } from '../../utils/persistence/sensitiveFieldDetection';
+import { createLogger } from '../../utils/core/logger';
+
+export interface UseFormPersistenceOptions<TFieldValues extends FieldValues> {
+  persistenceKey: string | null;
+  fieldNames: string[];
+  fieldTypes: Record<string, string>;
+  methods: UseFormReturn<TFieldValues>;
+  persistedValues: Partial<TFieldValues>;
+  setPersistedValues: (values: Partial<TFieldValues>) => void;
+  clearDraft: () => void;
+}
+
+function applyRestoreToForm<TFieldValues extends FieldValues>(
+  methods: UseFormReturn<TFieldValues>,
+  persistedValues: Partial<TFieldValues>,
+  fieldNames: string[],
+  fieldTypes: Record<string, string>,
+  persistenceKey: string | null,
+  logger: ReturnType<typeof createLogger>
+): void {
+  const persistedKeys = Object.keys(persistedValues as Record<string, unknown>);
+  const hasNumericKeys = persistedKeys.length > 0 && persistedKeys.every(key => /^\d+$/.test(key));
+
+  let valuesToRestore: Partial<TFieldValues>;
+  if (hasNumericKeys && fieldNames.length === persistedKeys.length) {
+    valuesToRestore = {} as Partial<TFieldValues>;
+    for (let i = 0; i < fieldNames.length; i++) {
+      const fieldName = fieldNames[i];
+      const numericKey = String(i);
+      if (numericKey in persistedValues) {
+        (valuesToRestore as Record<string, unknown>)[fieldName] = (persistedValues as Record<string, unknown>)[numericKey];
+      }
+    }
+    logger.debug('[Form Persistence] Mapped numeric keys to field names:', {
+      numericKeys: persistedKeys,
+      fieldNames,
+      mappedValues: valuesToRestore,
+    });
+  } else {
+    valuesToRestore = persistedValues as Partial<TFieldValues>;
+  }
+
+  const restoreKeys = Object.keys(valuesToRestore);
+  const filteredPersisted = filterSensitiveFields(
+    valuesToRestore,
+    restoreKeys.length > 0 ? restoreKeys : fieldNames,
+    fieldTypes
+  );
+
+  const sensitiveFields = restoreKeys.filter(name => {
+    const type = fieldTypes?.[name];
+    return isSensitiveField(name, type);
+  });
+
+  logger.debug('[Form Persistence] ✅ Restoring persisted values:', {
+    persistenceKey,
+    persistedValuesKeys: persistedKeys,
+    persistedValuesString: JSON.stringify(persistedValues),
+    hasNumericKeys,
+    valuesToRestoreKeys: Object.keys(valuesToRestore),
+    filteredPersistedKeys: Object.keys(filteredPersisted),
+    fieldNames,
+    sensitiveFields,
+    filteredCount: Object.keys(filteredPersisted).length,
+    persistedCount: persistedKeys.length,
+    timestamp: new Date().toISOString(),
+  });
+
+  const valuesToSet: Partial<TFieldValues> = {};
+  let hasValuesToSet = false;
+
+  for (const [key, value] of Object.entries(filteredPersisted)) {
+    const currentValue = methods.getValues(key as FieldPath<TFieldValues>);
+    if (currentValue !== value) {
+      (valuesToSet as Record<string, unknown>)[key] = value;
+      hasValuesToSet = true;
+    }
+  }
+
+  if (hasValuesToSet) {
+    logger.debug('[Form Persistence] 🔄 Setting form values via reset():', {
+      persistenceKey,
+      valuesToSetKeys: Object.keys(valuesToSet),
+      valuesToSet,
+      timestamp: new Date().toISOString(),
+    });
+    methods.reset({
+      ...methods.getValues(),
+      ...valuesToSet,
+    } as TFieldValues);
+    logger.debug('[Form Persistence] ✅ Form values set successfully', {
+      persistenceKey,
+      currentValues: methods.getValues(),
+    });
+  } else {
+    logger.debug('[Form Persistence] ⏭️ No values to set (all values already match)', {
+      persistenceKey,
+    });
+  }
+}
+
+/**
+ * Runs restore and persist effects that sync form state with session draft.
+ * Intentionally not exported; internal to Form.
+ */
+export function useFormPersistence<TFieldValues extends FieldValues = FieldValues>(
+  options: UseFormPersistenceOptions<TFieldValues>
+): void {
+  const {
+    persistenceKey,
+    fieldNames,
+    fieldTypes,
+    methods,
+    persistedValues,
+    setPersistedValues,
+  } = options;
+
+  const logger = createLogger('FormPersistence');
+
+  const hasRestoredRef = useRef(false);
+  const isRestoringRef = useRef(false);
+  const restoreTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const lastRestoredRef = useRef<string | null>(null);
+  const previousValuesRef = useRef<string | null>(null);
+  const persistTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  // Watch form values for persistence (useWatch without name returns all values as an object)
+  const watchedValues = useWatch({
+    control: methods.control,
+  }) as Partial<TFieldValues>;
+
+  // Restore persisted values after form initialization
+  useEffect(() => {
+    if (restoreTimeoutRef.current) {
+      clearTimeout(restoreTimeoutRef.current);
+    }
+
+    if (isRestoringRef.current) {
+      return;
+    }
+
+    if (!persistenceKey || !persistedValues || Object.keys(persistedValues).length === 0) {
+      if (!hasRestoredRef.current) {
+        hasRestoredRef.current = true;
+      }
+      return;
+    }
+
+    const persistedValuesStr = JSON.stringify(persistedValues);
+    if (lastRestoredRef.current === persistedValuesStr && hasRestoredRef.current) {
+      return;
+    }
+
+    isRestoringRef.current = true;
+
+    restoreTimeoutRef.current = setTimeout(() => {
+      applyRestoreToForm(methods, persistedValues, fieldNames, fieldTypes, persistenceKey, logger);
+      lastRestoredRef.current = persistedValuesStr;
+      hasRestoredRef.current = true;
+      isRestoringRef.current = false;
+      restoreTimeoutRef.current = null;
+    }, 100);
+
+    return () => {
+      if (restoreTimeoutRef.current) {
+        clearTimeout(restoreTimeoutRef.current);
+        restoreTimeoutRef.current = null;
+      }
+    };
+    // Omit methods from deps to avoid reset loops: including methods would retrigger on every render
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [persistedValues, persistenceKey]);
+
+  // Persist form values (filtered for sensitive fields)
+  useEffect(() => {
+    if (!persistenceKey || !watchedValues || isRestoringRef.current) {
+      return;
+    }
+
+    const currentValuesStr = JSON.stringify(watchedValues);
+    if (currentValuesStr === previousValuesRef.current) {
+      return;
+    }
+
+    previousValuesRef.current = currentValuesStr;
+
+    if (persistTimeoutRef.current) {
+      clearTimeout(persistTimeoutRef.current);
+    }
+
+    persistTimeoutRef.current = setTimeout(() => {
+      const allFieldNames = Object.keys(watchedValues as Record<string, unknown>);
+      const filteredValues = filterSensitiveFields(
+        watchedValues as Record<string, unknown>,
+        allFieldNames.length > 0 ? allFieldNames : fieldNames,
+        fieldTypes
+      );
+
+      const sensitiveFields = allFieldNames.filter(name => {
+        const type = fieldTypes?.[name];
+        return isSensitiveField(name, type);
+      });
+
+      logger.debug('[Form Persistence] 💾 Persisting form values:', {
+        persistenceKey,
+        filteredValuesKeys: Object.keys(filteredValues),
+        originalValuesKeys: Object.keys(watchedValues as Record<string, unknown>),
+        allFieldNames,
+        sensitiveFields,
+        filteredCount: Object.keys(filteredValues).length,
+        originalCount: allFieldNames.length,
+        timestamp: new Date().toISOString(),
+      });
+
+      setPersistedValues(filteredValues as Partial<TFieldValues>);
+
+      if (persistenceKey && typeof sessionStorage !== 'undefined') {
+        setTimeout(() => {
+          try {
+            const storageKey = `pace-core:draft:${persistenceKey}`;
+            const stored = sessionStorage.getItem(storageKey);
+            logger.debug('[Form Persistence] 📦 SessionStorage AFTER setPersistedValues:', {
+              persistenceKey,
+              storageKey,
+              stored: stored ? JSON.parse(stored) : null,
+            });
+          } catch (error) {
+            logger.debug('[Form Persistence] Could not access sessionStorage after setPersistedValues', { error });
+          }
+        }, 100);
+      }
+      persistTimeoutRef.current = null;
+    }, 300);
+
+    return () => {
+      if (persistTimeoutRef.current) {
+        clearTimeout(persistTimeoutRef.current);
+        persistTimeoutRef.current = null;
+      }
+    };
+    // Omit setPersistedValues, fieldNames, fieldTypes from deps to prevent infinite persist/reset loops
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [watchedValues, persistenceKey]);
+}