@dmitryvim/form-builder 0.2.9 → 0.2.11

package/README.md

@@ -42,7 +42,7 @@ This package ships with complete TypeScript definitions. Ensure your `tsconfig.j
 ```json
 {
   "compilerOptions": {
-    "moduleResolution": "NodeNext",  // or "Bundler" for Vite/Webpack
+    "moduleResolution": "NodeNext", // or "Bundler" for Vite/Webpack
     "esModuleInterop": true,
     "skipLibCheck": false
   }
@@ -77,6 +77,33 @@ This package ships with complete TypeScript definitions. Ensure your `tsconfig.j
 
 ## Quick Examples
 
+### Root-Level Properties (v0.2.9+)
+
+The root schema now supports container-like properties:
+
+- **`columns`** - Grid layout for root-level fields (1-4 columns)
+- **`prefillHints`** - Quick-fill templates for entire form
+
+**Example:**
+
+```json
+{
+  "version": "0.3",
+  "title": "Contact Form",
+  "columns": 2,
+  "prefillHints": [
+    {"label": "Work", "values": {"email": "work@company.com"}, "icon": "💼"},
+    {"label": "Personal", "values": {"email": "personal@email.com"}, "icon": "🏠"}
+  ],
+  "elements": [
+    {"type": "text", "key": "name", "label": "Name"},
+    {"type": "text", "key": "email", "label": "Email"}
+  ]
+}
+```
+
+See [CLAUDE.md](CLAUDE.md) for complete documentation.
+
 ### Simple Contact Form
 
 ```json
@@ -178,7 +205,7 @@ const formBuilder = createFormBuilder({
   },
   downloadFile: (resourceId, fileName) => {
     // Handle file download
-    window.open(`/api/files/${resourceId}`, '_blank');
+    window.open(`/api/files/${resourceId}`, "_blank");
   },
   getThumbnail: async (resourceId) => {
     // v0.2.0: Async-only thumbnail loading
@@ -196,9 +223,9 @@ const formBuilder = createFormBuilder({
   },
   // v0.2.0: CSS theming
   theme: {
-    primaryColor: '#0066cc',
-    borderRadius: '4px',
-  }
+    primaryColor: "#0066cc",
+    borderRadius: "4px",
+  },
 });
 
 // Render form
@@ -212,8 +239,8 @@ if (result.valid) {
 }
 
 // v0.2.0: Update fields without re-rendering
-formBuilder.updateField('email', 'newemail@example.com');
-formBuilder.setFormData({ name: 'John', email: 'john@example.com' });
+formBuilder.updateField("email", "newemail@example.com");
+formBuilder.setFormData({ name: "John", email: "john@example.com" });
 ```
 
 ### 2. CDN Integration
@@ -226,7 +253,9 @@ formBuilder.setFormData({ name: 'John', email: 'john@example.com' });
 
   const formBuilder = createFormBuilder({
     uploadFile: async (file) => "resource-id",
-    downloadFile: (resourceId) => { /* download */ }
+    downloadFile: (resourceId) => {
+      /* download */
+    },
   });
 
   const rootElement = document.getElementById("form-container");
@@ -343,6 +372,7 @@ form.destroy();
 **Breaking Changes in v0.2.0:**
 
 1. **Instance-Only API** - Global static methods removed
+
 ```typescript
 // OLD (v0.1.x)
 FormBuilder.configure({ uploadFile: async (file) => "id" });
@@ -354,12 +384,13 @@ form.renderForm(root, schema);
 ```
 
 2. **Async getThumbnail** - Must return Promise
+
 ```typescript
 // OLD (v0.1.x)
-getThumbnail: (resourceId) => `/thumbs/${resourceId}.jpg`
+getThumbnail: (resourceId) => `/thumbs/${resourceId}.jpg`;
 
 // NEW (v0.2.0)
-getThumbnail: async (resourceId) => `/thumbs/${resourceId}.jpg`
+getThumbnail: async (resourceId) => `/thumbs/${resourceId}.jpg`;
 ```
 
 See [CHANGELOG.md](CHANGELOG.md) for complete migration details.
@@ -372,26 +403,27 @@ Customize appearance with 43 theme properties:
 const form = createFormBuilder({
   theme: {
     // Colors
-    primaryColor: '#0066cc',
-    borderColor: '#e0e0e0',
-    errorColor: '#d32f2f',
+    primaryColor: "#0066cc",
+    borderColor: "#e0e0e0",
+    errorColor: "#d32f2f",
 
     // Typography
-    fontSize: '16px',
+    fontSize: "16px",
     fontFamily: '"Roboto", sans-serif',
 
     // Spacing
-    borderRadius: '4px',
-    inputPaddingX: '12px',
+    borderRadius: "4px",
+    inputPaddingX: "12px",
 
     // Buttons
-    buttonBgColor: '#0066cc',
-    buttonTextColor: '#ffffff',
-  }
+    buttonBgColor: "#0066cc",
+    buttonTextColor: "#ffffff",
+  },
 });
 ```
 
 **Most Common Properties:**
+
 - `primaryColor` - Primary brand color
 - `borderRadius` - Border radius for inputs/buttons
 - `fontSize` - Base font size
@@ -409,10 +441,10 @@ const form = createFormBuilder({
   // Required: Upload handler
   uploadFile: async (file) => {
     const formData = new FormData();
-    formData.append('file', file);
-    const response = await fetch('/api/upload', {
-      method: 'POST',
-      body: formData
+    formData.append("file", file);
+    const response = await fetch("/api/upload", {
+      method: "POST",
+      body: formData,
     });
     const data = await response.json();
     return data.resourceId; // Return unique resource ID
@@ -421,14 +453,14 @@ const form = createFormBuilder({
   // Required: Download handler
   downloadFile: (resourceId, fileName) => {
     // Option 1: Direct download
-    window.open(`/api/files/${resourceId}/download`, '_blank');
+    window.open(`/api/files/${resourceId}/download`, "_blank");
 
     // Option 2: Programmatic download
     fetch(`/api/files/${resourceId}/download`)
-      .then(response => response.blob())
-      .then(blob => {
+      .then((response) => response.blob())
+      .then((blob) => {
         const url = URL.createObjectURL(blob);
-        const a = document.createElement('a');
+        const a = document.createElement("a");
         a.href = url;
         a.download = fileName;
         a.click();
@@ -446,7 +478,7 @@ const form = createFormBuilder({
   // Optional: Full file download URL (used instead of getThumbnail for downloads)
   getDownloadUrl: (resourceId) => {
     return `/api/files/${resourceId}/download`;
-  }
+  },
 });
 ```
 
@@ -470,17 +502,25 @@ When a user clicks the download button in readonly mode, the form builder uses t
 
 ### Conditional Field Visibility
 
-Show or hide fields based on form data values using the `displayIf` property:
+Show or hide fields based on form data values using the `enableIf` property:
 
 ```typescript
-interface DisplayCondition {
-  key: string;        // Field key to check (supports nested paths)
-  equals?: any;       // Value to compare (initial operator)
+interface EnableCondition {
+  key: string; // Field key to check (supports nested paths)
+  equals?: any; // Value to compare (initial operator)
+  scope?: "relative" | "absolute"; // v0.2.9: Evaluation context (default: "relative")
   // Future: notEquals, in, exists, greaterThan, lessThan, and/or
 }
 ```
 
+**Scope Behavior (v0.2.9+):**
+
+- **`scope: "relative"`** (default): Checks fields within current container
+- **`scope: "absolute"`**: Checks fields in root-level form data
+- Use absolute scope when referencing root-level fields from inside containers
+
 **Simple Condition:**
+
 ```json
 {
   "type": "select",
@@ -495,7 +535,7 @@ interface DisplayCondition {
   "type": "text",
   "key": "background_image",
   "label": "Background Image URL",
-  "displayIf": {
+  "enableIf": {
     "key": "background_mode",
     "equals": "use_image"
   }
@@ -503,12 +543,13 @@ interface DisplayCondition {
 ```
 
 **Nested Path:**
+
 ```json
 {
   "type": "text",
   "key": "city_details",
   "label": "City-Specific Information",
-  "displayIf": {
+  "enableIf": {
     "key": "address.city",
     "equals": "New York"
   }
@@ -516,25 +557,48 @@ interface DisplayCondition {
 ```
 
 **Array Indices:**
+
 ```json
 {
   "type": "text",
   "key": "first_item_note",
   "label": "Note for First Item",
-  "displayIf": {
+  "enableIf": {
     "key": "items[0].quantity",
     "equals": 1
   }
 }
 ```
 
+**Absolute Scope (v0.2.9+):**
+
+```json
+{
+  "type": "container",
+  "key": "shipping_options",
+  "elements": [
+    {
+      "type": "text",
+      "key": "express_note",
+      "label": "Express Shipping Note",
+      "enableIf": {
+        "key": "shipping_type",
+        "equals": "express",
+        "scope": "absolute"
+      }
+    }
+  ]
+}
+```
+
 **Hide Entire Sections:**
+
 ```json
 {
   "type": "container",
   "key": "advanced_settings",
   "label": "Advanced Settings",
-  "displayIf": {
+  "enableIf": {
     "key": "mode",
     "equals": "advanced"
   },
@@ -560,19 +624,19 @@ interface DisplayCondition {
 
 **Future Extensibility:**
 
-The `displayIf` system is designed for future expansion:
+The `enableIf` system is designed for future expansion:
 
 ```typescript
 // Future operators (planned)
 {
-  "displayIf": {
+  "enableIf": {
     "key": "age",
     "greaterThan": 18
   }
 }
 
 {
-  "displayIf": {
+  "enableIf": {
     "key": "status",
     "in": ["active", "pending"]
   }
@@ -580,7 +644,7 @@ The `displayIf` system is designed for future expansion:
 
 // Future complex conditions (planned)
 {
-  "displayIf": {
+  "enableIf": {
     "and": [
       { "key": "role", "equals": "admin" },
       { "key": "verified", "equals": true }