```

feat: add automatic value clearing for conditional fields

- Add x-clear-on-hide schema extension to control value clearing behavior
- Implement setFieldValue method in FormContext for internal field updates
- Auto-clear field values when hidden via x-visible-when (defaults to true)
- Add watcher in FieldRenderer to clear values on visibility changes
- Update documentation for conditional fields and schema extensions
```

Author: zeejers

docs/guide/examples/conditional-fields.md

@@ -525,6 +525,7 @@ const schema: JSONSchema = {
 1. **Keep it simple**: Best for 1-3 conditional fields
 2. **Dot notation**: Reference nested fields with `parent.child` paths
 3. **Combine with `x-readonly-when`**: Show a field but make it readonly based on conditions
+4. **Values auto-clear**: When a field becomes hidden, its value is automatically cleared. Use `'x-clear-on-hide': false` to preserve values.
 
 ### For `oneOf`
 1. **Clear Labels**: Use descriptive `title` in each `oneOf` schema

docs/guide/schema-extensions.md

@@ -147,6 +147,60 @@ You can reference fields nested within objects using dot notation:
 
 ---
 
+## `x-clear-on-hide`
+
+**Purpose:** Control whether a field's value is cleared when it becomes hidden via `x-visible-when`
+
+**Type:** `boolean`
+
+**Default Behavior:** Fields with `x-visible-when` automatically clear their values when hidden. Use `x-clear-on-hide: false` to preserve values.
+
+**Example:**
+```typescript
+{
+  accountType: {
+    type: 'string',
+    enum: ['personal', 'business']
+  },
+  // Value is cleared when accountType changes away from 'business'
+  taxId: {
+    type: 'string',
+    title: 'Tax ID',
+    'x-visible-when': {
+      field: 'accountType',
+      operator: 'eq',
+      value: 'business'
+    }
+    // x-clear-on-hide defaults to true when x-visible-when is present
+  },
+  // Value is preserved even when hidden
+  internalNotes: {
+    type: 'string',
+    'x-visible-when': {
+      field: 'accountType',
+      operator: 'eq',
+      value: 'business'
+    },
+    'x-clear-on-hide': false  // Preserve value when hidden
+  }
+}
+```
+
+**Use Cases:**
+- Clear provider-specific settings when switching providers
+- Preserve user input that shouldn't be lost on visibility changes
+- Ensure stale data isn't submitted for hidden fields
+
+**Why clear by default?**
+When fields become hidden, their values typically become irrelevant. Clearing them:
+- Prevents stale data from being submitted
+- Ensures the form model matches the visible UI
+- Avoids confusion when switching between options
+
+**Note:** This only affects fields hidden via `x-visible-when`. Fields hidden with `x-hidden` or `x-roles` are not affected.
+
+---
+
 ## `x-hidden`
 
 **Purpose:** Completely hide a field from rendering (unconditionally)

packages/vue/src/components/DynamicForm.vue

@@ -163,6 +163,18 @@ const formContext = reactive({
       return getNestedValue(formVals, path) as T | undefined;
     });
   },
+  /**
+   * Set a field value by path.
+   * Supports dot notation for nested paths.
+   */
+  setFieldValue: (path: string, value: unknown) => {
+    if (isSingleField.value) {
+      // For single-field schemas, we need to update the nested path within the root field
+      setFieldValue(`${SINGLE_FIELD_PATH}.${path}`, value);
+    } else {
+      setFieldValue(path, value);
+    }
+  },
   /**
    * Watch all form values and call callback when they change.
    * Returns a stop function to unsubscribe.

packages/vue/src/components/FieldRenderer.vue

@@ -1,5 +1,5 @@
 <script setup lang="ts">
-import { computed } from 'vue';
+import { computed, watch } from 'vue';
 import type { JSONSchema, UISchemaElement } from '@quickflo/quickforms';
 import { useFormContext } from '../composables/useFormContext.js';
 
@@ -143,6 +143,27 @@ const visibleWhenResult = computed(() => {
   return evaluateCondition(condition, visibleWhenFieldValue.value);
 });
 
+// Check if field should clear its value when hidden
+// Defaults to true for x-visible-when fields, but can be overridden with x-clear-on-hide: false
+const shouldClearOnHide = computed(() => {
+  const schema = props.schema as any;
+  // If explicitly set, use that value
+  if (schema['x-clear-on-hide'] !== undefined) {
+    return schema['x-clear-on-hide'] === true;
+  }
+  // Default: clear on hide only if x-visible-when is configured
+  return visibleWhenConfig.value !== undefined;
+});
+
+// Watch visibility changes and clear value when field becomes hidden
+watch(visibleWhenResult, (isNowVisible, wasVisible) => {
+  // Only clear when transitioning from visible to hidden
+  if (wasVisible === true && isNowVisible === false && shouldClearOnHide.value) {
+    // Clear the field value
+    context.setFieldValue(props.path, undefined);
+  }
+});
+
 // Get reactive field value for x-readonly-when condition
 const readonlyWhenConfig = computed(() => {
   const schema = props.schema as any;

packages/vue/src/types/index.ts

@@ -201,6 +201,16 @@ export interface FormContext {
    * ```
    */
   useFieldValue: <T = unknown>(path: string) => ComputedRef<T | undefined>;
+  /**
+   * Set a field value by path. Used internally by FieldRenderer to clear
+   * values when fields become hidden via x-visible-when.
+   *
+   * @example
+   * ```ts
+   * formContext.setFieldValue('provider.model', undefined);
+   * ```
+   */
+  setFieldValue: (path: string, value: unknown) => void;
   /**
    * Watch form values and call callback when they change.
    * Returns a stop function to unsubscribe.