@dmitryvim/form-builder 0.2.4 → 0.2.6

package/README.md

@@ -81,7 +81,6 @@ This package ships with complete TypeScript definitions. Ensure your `tsconfig.j
 
 ```json
 {
-  "version": "0.3",
   "title": "Contact Form",
   "elements": [
     {
@@ -119,7 +118,6 @@ This package ships with complete TypeScript definitions. Ensure your `tsconfig.j
 
 ```json
 {
-  "version": "0.3",
   "title": "Product Registration",
   "elements": [
     {
@@ -468,6 +466,127 @@ When a user clicks the download button in readonly mode, the form builder uses t
 
 `getThumbnail` must be async (return `Promise`). TypeScript enforces this at compile-time. If you provide a synchronous handler, the error will occur at first file usage (not at form instantiation). This is intentional - we avoid validation calls that would trigger unnecessary API requests. Follow the **FAIL FAST** principle: errors surface naturally at usage.
 
+### Conditional Field Visibility
+
+Show or hide fields based on form data values using the `displayIf` property:
+
+```typescript
+interface DisplayCondition {
+  key: string;        // Field key to check (supports nested paths)
+  equals?: any;       // Value to compare (initial operator)
+  // Future: notEquals, in, exists, greaterThan, lessThan, and/or
+}
+```
+
+**Simple Condition:**
+```json
+{
+  "type": "select",
+  "key": "background_mode",
+  "label": "Background Mode",
+  "options": [
+    { "value": "use_color", "label": "Solid Color" },
+    { "value": "use_image", "label": "Image" }
+  ]
+},
+{
+  "type": "text",
+  "key": "background_image",
+  "label": "Background Image URL",
+  "displayIf": {
+    "key": "background_mode",
+    "equals": "use_image"
+  }
+}
+```
+
+**Nested Path:**
+```json
+{
+  "type": "text",
+  "key": "city_details",
+  "label": "City-Specific Information",
+  "displayIf": {
+    "key": "address.city",
+    "equals": "New York"
+  }
+}
+```
+
+**Array Indices:**
+```json
+{
+  "type": "text",
+  "key": "first_item_note",
+  "label": "Note for First Item",
+  "displayIf": {
+    "key": "items[0].quantity",
+    "equals": 1
+  }
+}
+```
+
+**Hide Entire Sections:**
+```json
+{
+  "type": "container",
+  "key": "advanced_settings",
+  "label": "Advanced Settings",
+  "displayIf": {
+    "key": "mode",
+    "equals": "advanced"
+  },
+  "elements": [
+    // All child elements are hidden when container is hidden
+  ]
+}
+```
+
+**How It Works:**
+
+- Fields with unmet conditions are **not rendered** and **excluded from form data**
+- Conditions are evaluated before rendering each element
+- Automatic re-evaluation when dependency fields change (integrated with onChange system)
+- Works in both edit and readonly modes
+- Safe handling of undefined/null values
+
+**Path Resolution:**
+
+- **Dot notation**: `user.profile.name`, `settings.theme.primaryColor`
+- **Array indices**: `items[0].name`, `addresses[1].city`
+- **Mixed**: `users[0].profile.email`
+
+**Future Extensibility:**
+
+The `displayIf` system is designed for future expansion:
+
+```typescript
+// Future operators (planned)
+{
+  "displayIf": {
+    "key": "age",
+    "greaterThan": 18
+  }
+}
+
+{
+  "displayIf": {
+    "key": "status",
+    "in": ["active", "pending"]
+  }
+}
+
+// Future complex conditions (planned)
+{
+  "displayIf": {
+    "and": [
+      { "key": "role", "equals": "admin" },
+      { "key": "verified", "equals": true }
+    ]
+  }
+}
+```
+
 ## Documentation
 
 - **API Reference** - See above for core methods and theming