pulse-js-framework 1.8.3 → 1.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pulse-js-framework",
-  "version": "1.8.3",
+  "version": "1.9.0",
   "description": "A declarative DOM framework with CSS selector-based structure and reactive pulsations",
   "type": "module",
   "sideEffects": false,
@@ -149,6 +149,7 @@
     "test:async": "node test/async.test.js",
     "test:async-coverage": "node test/async-coverage.test.js",
     "test:form": "node test/form.test.js",
+    "test:form-v2": "node test/form-v2.test.js",
     "test:http": "node test/http.test.js",
     "test:devtools": "node test/devtools.test.js",
     "test:native": "node test/native.test.js",
@@ -168,6 +169,7 @@
     "test:integration": "node test/integration.test.js",
     "test:context-stress": "node test/context-stress.test.js",
     "test:form-edge-cases": "node test/form-edge-cases.test.js",
+    "test:form-coverage": "node test/form-coverage.test.js",
     "test:graphql-subscriptions": "node test/graphql-subscriptions.test.js",
     "test:http-edge-cases": "node test/http-edge-cases.test.js",
     "test:integration-advanced": "node test/integration-advanced.test.js",

package/runtime/form.js

@@ -32,6 +32,18 @@ function isAsyncValidator(rule) {
   return rule.async === true;
 }
 
+/**
+ * Check if localStorage is available (SSR-safe)
+ * @returns {boolean}
+ */
+function isLocalStorageAvailable() {
+  try {
+    return typeof localStorage !== 'undefined' && localStorage !== null;
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Built-in validation rules
  */
@@ -172,6 +184,74 @@ export const validators = {
     }
   }),
 
+  // ============================================================================
+  // Conditional Validators (#30)
+  // ============================================================================
+
+  /**
+   * Conditional validation - run rules only when condition is met
+   * @param {function(any, Object): boolean} condition - Condition function (value, allValues) => boolean
+   * @param {ValidationRule[]} rules - Validation rules to apply when condition is true
+   * @returns {ValidationRule}
+   *
+   * @example
+   * // Only validate shipping address when "different shipping" is checked
+   * validators.when(
+   *   (value, allValues) => allValues.differentShipping,
+   *   [validators.required(), validators.minLength(5)]
+   * )
+   */
+  when: (condition, rules) => {
+    const hasAsync = rules.some(r => isAsyncValidator(r));
+    const firstAsyncRule = rules.find(r => isAsyncValidator(r));
+
+    const rule = {
+      validate: hasAsync
+        ? async (value, allValues) => {
+            if (!condition(value, allValues)) return true;
+            for (const r of rules) {
+              const result = isAsyncValidator(r)
+                ? await r.validate(value, allValues)
+                : r.validate(value, allValues);
+              if (result !== true) return result;
+            }
+            return true;
+          }
+        : (value, allValues) => {
+            if (!condition(value, allValues)) return true;
+            for (const r of rules) {
+              const result = r.validate(value, allValues);
+              if (result !== true) return result;
+            }
+            return true;
+          }
+    };
+
+    if (hasAsync) {
+      rule.async = true;
+      rule.debounce = firstAsyncRule.debounce ?? 300;
+    }
+
+    return rule;
+  },
+
+  /**
+   * Inverse conditional validation - run rules unless condition is met
+   * @param {function(any, Object): boolean} condition - Condition function (value, allValues) => boolean
+   * @param {ValidationRule[]} rules - Validation rules to apply when condition is false
+   * @returns {ValidationRule}
+   *
+   * @example
+   * // Skip email validation when field is empty
+   * validators.unless(
+   *   (value) => !value,
+   *   [validators.email()]
+   * )
+   */
+  unless: (condition, rules) => {
+    return validators.when((value, allValues) => !condition(value, allValues), rules);
+  },
+
   // ============================================================================
   // Async Validators
   // ============================================================================
@@ -287,6 +367,11 @@ export const validators = {
  * @property {function(Object): void} [onSubmit] - Submit handler
  * @property {function(Object): void} [onError] - Error handler
  * @property {'onChange'|'onBlur'|'onSubmit'} [mode='onChange'] - Validation mode
+ * @property {function(Object): Object} [validate] - Form-level validation function
+ * @property {boolean} [persist=false] - Enable draft persistence to localStorage
+ * @property {string} [persistKey='pulse-form-draft'] - localStorage key for drafts
+ * @property {number} [persistDebounce=300] - Debounce delay for saving drafts (ms)
+ * @property {string[]} [persistExclude=[]] - Field names to exclude from persistence
  */
 
 /**
@@ -321,9 +406,39 @@ export function useForm(initialValues, validationSchema = {}, options = {}) {
     validateOnSubmit = true,
     onSubmit,
     onError,
-    mode = 'onChange'
+    mode = 'onChange',
+    validate: formValidate,
+    persist = false,
+    persistKey = 'pulse-form-draft',
+    persistDebounce = 300,
+    persistExclude = []
   } = options;
 
+  // ========================================================================
+  // Draft Persistence: Restore saved draft (#36)
+  // ========================================================================
+
+  let restoredValues = { ...initialValues };
+  const canPersist = persist && isLocalStorageAvailable();
+
+  if (canPersist) {
+    try {
+      const savedDraft = localStorage.getItem(persistKey);
+      if (savedDraft) {
+        const parsed = JSON.parse(savedDraft);
+        if (parsed && typeof parsed === 'object') {
+          for (const key of Object.keys(initialValues)) {
+            if (key in parsed && !persistExclude.includes(key)) {
+              restoredValues[key] = parsed[key];
+            }
+          }
+        }
+      }
+    } catch {
+      // Ignore parse errors — use initial values
+    }
+  }
+
   // Create field states
   const fields = {};
   const fieldNames = Object.keys(initialValues);
@@ -334,13 +449,14 @@ export function useForm(initialValues, validationSchema = {}, options = {}) {
 
   for (const name of fieldNames) {
     const initialValue = initialValues[name];
+    const startValue = restoredValues[name];
     const rules = validationSchema[name] || [];
 
     // Separate sync and async rules
     const syncRules = rules.filter(r => !isAsyncValidator(r));
     const asyncRules = rules.filter(r => isAsyncValidator(r));
 
-    const value = pulse(initialValue);
+    const value = pulse(startValue);
     const error = pulse(null);
     const touched = pulse(false);
     const validating = pulse(false);
@@ -508,13 +624,34 @@ export function useForm(initialValues, validationSchema = {}, options = {}) {
     };
   }
 
+  // ========================================================================
   // Form-level state
+  // ========================================================================
+
   const isSubmitting = pulse(false);
   const submitCount = pulse(0);
+  const submitError = pulse(null);     // #29: Server-side submit error
+  const formError = pulse(null);       // #32: Form-level validation error
+
+  // ========================================================================
+  // Draft Persistence: hasDraft state (#36)
+  // ========================================================================
 
+  const hasDraft = pulse(canPersist && (() => {
+    try {
+      return localStorage.getItem(persistKey) !== null;
+    } catch {
+      return false;
+    }
+  })());
+
+  // ========================================================================
   // Computed form state
+  // ========================================================================
+
   const isValid = computed(() => {
-    return fieldNames.every(name => fields[name].valid.get());
+    // All fields must be valid AND no form-level error
+    return fieldNames.every(name => fields[name].valid.get()) && formError.get() === null;
   });
 
   const isValidating = computed(() => {
@@ -535,6 +672,9 @@ export function useForm(initialValues, validationSchema = {}, options = {}) {
       const err = fields[name].error.get();
       if (err) result[name] = err;
     }
+    // Include form-level error under _form key
+    const fErr = formError.get();
+    if (fErr) result._form = fErr;
     return result;
   });
 
@@ -578,6 +718,56 @@ export function useForm(initialValues, validationSchema = {}, options = {}) {
     }
   }
 
+  // ========================================================================
+  // Form-Level Validation (#32)
+  // ========================================================================
+
+  /**
+   * Run form-level validation (cross-field)
+   * @returns {Promise<boolean>} true if valid
+   */
+  async function runFormLevelValidation() {
+    if (!formValidate) return true;
+
+    const allValues = getValues();
+    let result;
+    try {
+      result = formValidate(allValues);
+      // Support async validate functions
+      if (result && typeof result.then === 'function') {
+        result = await result;
+      }
+    } catch (err) {
+      formError.set(err.message || 'Form validation failed');
+      return false;
+    }
+
+    if (!result || typeof result !== 'object') {
+      formError.set(null);
+      return true;
+    }
+
+    // Check if any errors were returned
+    const errorKeys = Object.keys(result);
+    if (errorKeys.length === 0) {
+      formError.set(null);
+      return true;
+    }
+
+    // Apply errors to fields and form
+    batch(() => {
+      for (const [key, message] of Object.entries(result)) {
+        if (key === '_form') {
+          formError.set(message);
+        } else if (fields[key]) {
+          fields[key].error.set(message);
+        }
+      }
+    });
+
+    return false;
+  }
+
   /**
    * Validate all fields (sync only, for immediate check)
    */
@@ -592,10 +782,13 @@ export function useForm(initialValues, validationSchema = {}, options = {}) {
   }
 
   /**
-   * Validate all fields (sync + async)
+   * Validate all fields (sync + async) + form-level validation
    * @returns {Promise<boolean>}
    */
   async function validateAll() {
+    // Clear form-level error before re-validating
+    formError.set(null);
+
     // First run all sync validations
     let allValid = validateAllSync();
 
@@ -611,9 +804,90 @@ export function useForm(initialValues, validationSchema = {}, options = {}) {
       }
     }
 
+    // Run form-level validation if field-level passed
+    if (allValid && formValidate) {
+      allValid = await runFormLevelValidation();
+    }
+
     return allValid;
   }
 
+  // ========================================================================
+  // Draft Persistence Helpers (#36)
+  // ========================================================================
+
+  let persistTimer = null;
+
+  /**
+   * Save current form values to localStorage
+   */
+  function saveDraft() {
+    if (!canPersist) return;
+    try {
+      const values = getValues();
+      const filtered = {};
+      for (const [key, val] of Object.entries(values)) {
+        if (!persistExclude.includes(key)) {
+          // Only persist JSON-serializable values
+          if (val !== undefined && typeof val !== 'function' && !(typeof val === 'object' && val !== null && typeof val.then === 'function')) {
+            filtered[key] = val;
+          }
+        }
+      }
+      localStorage.setItem(persistKey, JSON.stringify(filtered));
+      hasDraft.set(true);
+    } catch {
+      // Ignore storage errors (quota exceeded, etc.)
+    }
+  }
+
+  /**
+   * Clear saved draft from localStorage
+   */
+  function clearDraft() {
+    if (persistTimer) {
+      clearTimeout(persistTimer);
+      persistTimer = null;
+    }
+    if (isLocalStorageAvailable()) {
+      try {
+        localStorage.removeItem(persistKey);
+      } catch {
+        // Ignore
+      }
+    }
+    hasDraft.set(false);
+  }
+
+  /**
+   * Debounced draft save - schedules a save after persistDebounce ms
+   */
+  function scheduleDraftSave() {
+    if (!canPersist) return;
+    if (persistTimer) {
+      clearTimeout(persistTimer);
+    }
+    persistTimer = setTimeout(saveDraft, persistDebounce);
+  }
+
+  // Set up draft persistence effect
+  if (canPersist) {
+    // Watch for field value changes and debounce-save
+    const disposeEffect = effect(() => {
+      // Track all field values
+      for (const name of fieldNames) {
+        fields[name].value.get();
+      }
+      // Schedule save (debounced)
+      scheduleDraftSave();
+    });
+    onCleanup(disposeEffect);
+  }
+
+  // ========================================================================
+  // Form Control Methods
+  // ========================================================================
+
   /**
    * Reset form to initial values
    */
@@ -626,7 +900,14 @@ export function useForm(initialValues, validationSchema = {}, options = {}) {
         fields[name].touched.set(false);
       }
       isSubmitting.set(false);
+      submitError.set(null);
+      formError.set(null);
     });
+
+    // Clear draft on reset
+    if (canPersist) {
+      clearDraft();
+    }
   }
 
   /**
@@ -638,6 +919,7 @@ export function useForm(initialValues, validationSchema = {}, options = {}) {
     }
 
     submitCount.update(c => c + 1);
+    submitError.set(null);  // #29: Clear previous submit error
 
     // Mark all fields as touched
     batch(() => {
@@ -663,10 +945,18 @@ export function useForm(initialValues, validationSchema = {}, options = {}) {
       if (onSubmit) {
         await onSubmit(getValues());
       }
+
+      // Clear draft on successful submit
+      if (canPersist) {
+        clearDraft();
+      }
+
       return true;
     } catch (err) {
+      const errorMessage = err.message || 'Submit failed';
+      submitError.set(errorMessage);  // #29: Set reactive submit error
       if (onError) {
-        onError({ _form: err.message || 'Submit failed' });
+        onError({ _form: errorMessage });
       }
       return false;
     } finally {
@@ -680,7 +970,9 @@ export function useForm(initialValues, validationSchema = {}, options = {}) {
   function setErrors(errorMap) {
     batch(() => {
       for (const [name, message] of Object.entries(errorMap)) {
-        if (fields[name]) {
+        if (name === '_form') {
+          formError.set(message);
+        } else if (fields[name]) {
           fields[name].error.set(message);
         }
       }
@@ -688,17 +980,32 @@ export function useForm(initialValues, validationSchema = {}, options = {}) {
   }
 
   /**
-   * Clear all errors
+   * Clear all errors (field-level and form-level)
    */
   function clearErrors() {
     batch(() => {
       for (const name of fieldNames) {
         fields[name].error.set(null);
       }
+      formError.set(null);
+      submitError.set(null);
     });
   }
 
+  /**
+   * Clear form-level error only
+   */
+  function clearFormError() {
+    formError.set(null);
+  }
+
   const dispose = () => {
+    // Clear persist timer
+    if (persistTimer) {
+      clearTimeout(persistTimer);
+      persistTimer = null;
+    }
+    // Clear debounce timers
     for (const name of fieldNames) {
       const timers = debounceTimers[name];
       if (timers) {
@@ -719,6 +1026,8 @@ export function useForm(initialValues, validationSchema = {}, options = {}) {
     isTouched,
     isSubmitting,
     submitCount,
+    submitError,         // #29: Reactive submit error
+    formError,           // #32: Form-level validation error
     errors,
     getValues,
     setValues,
@@ -729,6 +1038,9 @@ export function useForm(initialValues, validationSchema = {}, options = {}) {
     handleSubmit,
     setErrors,
     clearErrors,
+    clearFormError,      // #32: Clear form-level error
+    hasDraft,            // #36: Whether a saved draft exists
+    clearDraft,          // #36: Clear saved draft
     dispose
   };
 }
@@ -1077,9 +1389,294 @@ export function useFieldArray(initialValues = [], itemRules = []) {
   };
 }
 
+// ============================================================================
+// File Upload Field (#34)
+// ============================================================================
+
+/**
+ * Create a reactive file upload field with drag-and-drop, preview, and validation.
+ *
+ * @param {Object} [options={}] - File field options
+ * @param {string[]} [options.accept] - Allowed MIME types (e.g. ['image/png', 'image/jpeg'])
+ * @param {number} [options.maxSize] - Maximum file size in bytes
+ * @param {boolean} [options.multiple=false] - Allow multiple files
+ * @param {number} [options.maxFiles=Infinity] - Maximum number of files (when multiple=true)
+ * @param {boolean} [options.preview=false] - Generate preview URLs for image files
+ * @param {function(File[]): boolean|string} [options.validate] - Custom validation function
+ * @returns {Object} File field state and controls
+ *
+ * @example
+ * const avatar = useFileField({
+ *   accept: ['image/png', 'image/jpeg'],
+ *   maxSize: 5 * 1024 * 1024,
+ *   preview: true
+ * });
+ *
+ * // Input binding
+ * el('input[type=file]', { onchange: avatar.onChange, accept: 'image/*' });
+ *
+ * // Drop zone
+ * el('.dropzone', {
+ *   ondragenter: avatar.onDragEnter,
+ *   ondragover: avatar.onDragOver,
+ *   ondragleave: avatar.onDragLeave,
+ *   ondrop: avatar.onDrop,
+ *   class: () => avatar.isDragging.get() ? 'drag-over' : ''
+ * });
+ */
+export function useFileField(options = {}) {
+  const {
+    accept,
+    maxSize,
+    multiple = false,
+    maxFiles = Infinity,
+    preview = false,
+    validate: customValidate
+  } = options;
+
+  // Reactive state
+  const files = pulse([]);
+  const previews = pulse([]);
+  const error = pulse(null);
+  const touched = pulse(false);
+  const isDragging = pulse(false);
+  const valid = computed(() => error.get() === null);
+
+  // Track object URLs for cleanup
+  let previewUrls = [];
+
+  /**
+   * Check if URL.createObjectURL is available (SSR-safe)
+   */
+  function canCreateObjectURL() {
+    return typeof URL !== 'undefined' && typeof URL.createObjectURL === 'function';
+  }
+
+  /**
+   * Revoke all existing preview URLs to prevent memory leaks
+   */
+  function revokePreviewUrls() {
+    if (canCreateObjectURL()) {
+      for (const url of previewUrls) {
+        try {
+          URL.revokeObjectURL(url);
+        } catch {
+          // Ignore revoke errors
+        }
+      }
+    }
+    previewUrls = [];
+    previews.set([]);
+  }
+
+  /**
+   * Generate preview URLs for image files
+   */
+  function generatePreviews(fileList) {
+    if (!preview || !canCreateObjectURL()) return;
+
+    revokePreviewUrls();
+
+    const urls = [];
+    for (const file of fileList) {
+      if (file.type && file.type.startsWith('image/')) {
+        const url = URL.createObjectURL(file);
+        urls.push(url);
+        previewUrls.push(url);
+      } else {
+        urls.push(null);
+      }
+    }
+    previews.set(urls);
+  }
+
+  /**
+   * Validate files against constraints
+   * @param {File[]} fileList - Files to validate
+   * @returns {string|null} Error message or null
+   */
+  function validateFiles(fileList) {
+    if (fileList.length === 0) return null;
+
+    // Check file count
+    if (!multiple && fileList.length > 1) {
+      return 'Only one file is allowed';
+    }
+    if (multiple && fileList.length > maxFiles) {
+      return `Maximum ${maxFiles} files allowed`;
+    }
+
+    // Check each file
+    for (const file of fileList) {
+      // Type validation
+      if (accept && accept.length > 0) {
+        const fileType = file.type || '';
+        const matched = accept.some(type => {
+          if (type.endsWith('/*')) {
+            // Wildcard match: image/* matches image/png
+            const prefix = type.slice(0, -2);
+            return fileType.startsWith(prefix);
+          }
+          return fileType === type;
+        });
+        if (!matched) {
+          return `File type "${fileType || 'unknown'}" is not allowed`;
+        }
+      }
+
+      // Size validation
+      if (maxSize && file.size > maxSize) {
+        const sizeMB = (maxSize / (1024 * 1024)).toFixed(1);
+        return `File "${file.name}" exceeds maximum size of ${sizeMB}MB`;
+      }
+    }
+
+    // Custom validation
+    if (customValidate) {
+      const result = customValidate(fileList);
+      if (result !== true && typeof result === 'string') {
+        return result;
+      }
+    }
+
+    return null;
+  }
+
+  /**
+   * Process and set files
+   * @param {File[]} fileList - Files to set
+   */
+  function setFiles(fileList) {
+    touched.set(true);
+
+    const fileArray = Array.from(fileList);
+    const validationError = validateFiles(fileArray);
+
+    if (validationError) {
+      error.set(validationError);
+      return;
+    }
+
+    error.set(null);
+    files.set(fileArray);
+    generatePreviews(fileArray);
+  }
+
+  // Event handlers
+  const onChange = (event) => {
+    const inputFiles = event?.target?.files;
+    if (inputFiles) {
+      setFiles(inputFiles);
+    }
+  };
+
+  const onDragEnter = (event) => {
+    event.preventDefault();
+    event.stopPropagation();
+    isDragging.set(true);
+  };
+
+  const onDragOver = (event) => {
+    event.preventDefault();
+    event.stopPropagation();
+    isDragging.set(true);
+  };
+
+  const onDragLeave = (event) => {
+    event.preventDefault();
+    event.stopPropagation();
+    isDragging.set(false);
+  };
+
+  const onDrop = (event) => {
+    event.preventDefault();
+    event.stopPropagation();
+    isDragging.set(false);
+
+    const droppedFiles = event?.dataTransfer?.files;
+    if (droppedFiles && droppedFiles.length > 0) {
+      setFiles(droppedFiles);
+    }
+  };
+
+  const clear = () => {
+    revokePreviewUrls();
+    batch(() => {
+      files.set([]);
+      error.set(null);
+    });
+  };
+
+  const removeFile = (index) => {
+    const currentFiles = files.get();
+    if (index < 0 || index >= currentFiles.length) return;
+
+    const newFiles = currentFiles.filter((_, i) => i !== index);
+
+    // Revoke removed preview URL
+    if (preview && canCreateObjectURL()) {
+      const currentPreviews = previews.get();
+      if (currentPreviews[index]) {
+        try {
+          URL.revokeObjectURL(currentPreviews[index]);
+        } catch {
+          // Ignore
+        }
+      }
+      const newPreviews = currentPreviews.filter((_, i) => i !== index);
+      previewUrls = previewUrls.filter((_, i) => i !== index);
+      previews.set(newPreviews);
+    }
+
+    files.set(newFiles);
+
+    // Re-validate remaining files
+    if (newFiles.length > 0) {
+      const validationError = validateFiles(newFiles);
+      error.set(validationError);
+    } else {
+      error.set(null);
+    }
+  };
+
+  const reset = () => {
+    revokePreviewUrls();
+    batch(() => {
+      files.set([]);
+      error.set(null);
+      touched.set(false);
+      isDragging.set(false);
+    });
+  };
+
+  const dispose = () => {
+    revokePreviewUrls();
+  };
+  onCleanup(dispose);
+
+  return {
+    files,
+    previews,
+    error,
+    touched,
+    valid,
+    isDragging,
+    onChange,
+    onDragEnter,
+    onDragOver,
+    onDragLeave,
+    onDrop,
+    clear,
+    removeFile,
+    reset,
+    dispose
+  };
+}
+
 export default {
   useForm,
   useField,
   useFieldArray,
+  useFileField,
   validators
 };