@dmitryvim/form-builder 0.1.5 → 0.1.6

package/dist/README.md

@@ -64,19 +64,40 @@ Renders a form in the specified container.
 **Parameters:**
 - `schema` - JSON schema object (v0.3)
 - `container` - DOM element to render form in
-- `options` - Configuration object
+- `options` - Configuration object (optional)
 
 **Options:**
 - `prefill` - Object with prefilled values
-- `readonly` - Boolean, renders form in read-only mode
-- `onSubmit` - Callback for form submission
-- `onDraft` - Callback for draft saving
-- `onError` - Callback for validation errors
+- `readonly` - Boolean, renders form in read-only mode (hides buttons)
+- `debug` - Boolean, enables debug logging to console
+- `onSubmit` - Callback for form submission `(data) => {}`
+- `onDraft` - Callback for draft saving `(data) => {}`  
+- `onError` - Callback for validation errors `(errors) => {}`
+- `buttons` - Custom button text: `{ submit: "Start Workflow", draft: "Save Progress" }`
+
+**Important:** Upload handlers must return a **string** resourceId, not an object.
 
 ### FormBuilder.validateSchema(schema)
 
 Validates a JSON schema and returns array of errors.
 
+**Returns:** `string[]` - Array of error messages (empty if valid)
+
+### FormBuilder.collectAndValidate(schema, formElement, skipValidation)
+
+⚠️ **Direct API for advanced users only**
+
+Collects form data and validates it. Most users should use `onSubmit`/`onDraft` callbacks instead.
+
+**Parameters:**
+- `schema` - The form schema
+- `formElement` - The form DOM element
+- `skipValidation` - Boolean, skip validation (for drafts)
+
+**Returns:** `{ result: object, errors: string[] }`
+
+**Important:** This is the correct destructuring format - there is no `.valid` or `.data` property.
+
 ### FormBuilder.setUploadHandler(uploadFn)
 
 Sets custom file upload handler:
@@ -109,47 +130,117 @@ FormBuilder.setDownloadHandler(async (resourceId, fileName) => {
 - `select` - Dropdown selection
 - `file` - Single file upload
 - `files` - Multiple file upload
-- `group` - Nested objects with optional repeat
+- `group` - Nested objects with optional repeat and custom element titles
+
+## Troubleshooting Common Issues
+
+### ❌ Upload Handler Returns Object
+```javascript
+// Wrong - causes "resourceId.slice is not a function"
+FormBuilder.setUploadHandler(async (file) => {
+  const response = await uploadFile(file);
+  return { reference: response.id, name: file.name }; // ❌ Object
+});
+
+// Correct - return string only
+FormBuilder.setUploadHandler(async (file) => {
+  const response = await uploadFile(file);
+  return response.id; // ✅ String resourceId
+});
+```
+
+### ❌ Wrong API Usage
+```javascript
+// Wrong - no .valid or .data properties
+const result = FormBuilder.collectAndValidate(schema, form);
+if (result.valid) { // ❌ Property doesn't exist
+  console.log(result.data); // ❌ Property doesn't exist
+}
+
+// Correct - use destructuring
+const { result, errors } = FormBuilder.collectAndValidate(schema, form);
+if (errors.length === 0) { // ✅ Check errors array
+  console.log(result); // ✅ Data is in result
+}
+```
+
+### ❌ Group Elements Missing Elements Array
+```javascript
+// Wrong - causes "group.elements must be array"
+{
+  type: 'group',
+  key: 'address',
+  // Missing elements array ❌
+}
+
+// Correct - always include elements
+{
+  type: 'group', 
+  key: 'address',
+  label: 'Address Information',
+  element_label: 'Address #$index', // ✅ Optional custom title
+  elements: [ // ✅ Required array
+    { type: 'text', key: 'street', label: 'Street' }
+  ]
+}
+```
+
+### ❌ Readonly Mode Confusion
+```javascript
+// This only hides the default buttons, fields remain editable
+FormBuilder.renderForm(schema, container, { readonly: true });
+
+// For true read-only, you need to disable inputs manually or use a different approach
+```
 
 ## Complete Example
 
 ```javascript
 const schema = {
   "version": "0.3",
-  "title": "Product Form",
+  "title": "Video Cover Generation",
   "elements": [
-    {
-      "type": "file",
-      "key": "cover",
-      "label": "Cover Image",
-      "required": true,
-      "accept": {
-        "extensions": ["jpg", "png"],
-        "mime": ["image/jpeg", "image/png"]
-      },
-      "maxSizeMB": 5
-    },
     {
       "type": "text",
-      "key": "title", 
-      "label": "Product Title",
-      "required": true,
-      "maxLength": 100
+      "key": "concept",
+      "label": "Animation Concept (Optional)",
+      "required": false,
+      "maxLength": 100,
+      "placeholder": "e.g., fun, elegant, dynamic, cozy..."
     },
     {
       "type": "group",
-      "key": "features",
-      "label": "Features",
+      "key": "slides_input",
+      "label": "Video Slides",
+      "element_label": "Slide $index", // 🆕 Custom title for each item
       "repeat": {
         "min": 1,
-        "max": 5
+        "max": 10
       },
       "elements": [
         {
-          "type": "text",
-          "key": "name",
-          "label": "Feature Name",
-          "required": true
+          "type": "file",
+          "key": "main_image",
+          "label": "Main Image",
+          "required": true,
+          "accept": {
+            "extensions": ["png", "jpg", "jpeg", "webp"],
+            "mime": ["image/png", "image/jpeg", "image/webp"]
+          },
+          "maxSizeMB": 25
+        },
+        {
+          "type": "files",
+          "key": "elements",
+          "label": "Element Images (Optional)",
+          "required": false,
+          "accept": {
+            "extensions": ["png", "jpg", "jpeg", "webp"],
+            "mime": ["image/png", "image/jpeg", "image/webp"]
+          },
+          "minCount": 0,
+          "maxCount": 10,
+          "maxSizeMB": 10
         }
       ]
     }

package/dist/example.html

@@ -23,54 +23,54 @@
 
     <script src="form-builder.js"></script>
     <script>
-        // Example schema
+        // Example schema demonstrating element_label feature
         const schema = {
             "version": "0.3",
-            "title": "Contact Form",
+            "title": "Video Cover Generation",
             "elements": [
                 {
                     "type": "text",
-                    "key": "name",
-                    "label": "Full Name",
-                    "required": true,
-                    "minLength": 2,
-                    "maxLength": 50
-                },
-                {
-                    "type": "text",
-                    "key": "email", 
-                    "label": "Email Address",
-                    "required": true,
-                    "pattern": "^[^@\\s]+@[^@\\s]+\\.[^@\\s]+$"
-                },
-                {
-                    "type": "select",
-                    "key": "category",
-                    "label": "Category",
-                    "required": true,
-                    "options": [
-                        { "value": "general", "label": "General Inquiry" },
-                        { "value": "support", "label": "Technical Support" },
-                        { "value": "billing", "label": "Billing Question" }
-                    ]
-                },
-                {
-                    "type": "textarea",
-                    "key": "message",
-                    "label": "Message",
-                    "required": true,
-                    "maxLength": 1000
+                    "key": "concept",
+                    "label": "Animation Concept (Optional)",
+                    "required": false,
+                    "maxLength": 100,
+                    "placeholder": "e.g., fun, elegant, dynamic, cozy..."
                 },
                 {
-                    "type": "file",
-                    "key": "attachment",
-                    "label": "Attachment (Optional)",
-                    "required": false,
-                    "accept": {
-                        "extensions": ["pdf", "doc", "docx", "txt"],
-                        "mime": ["application/pdf", "application/msword", "text/plain"]
+                    "type": "group",
+                    "key": "slides_input",
+                    "label": "Video Slides",
+                    "element_label": "Slide $index",
+                    "repeat": {
+                        "min": 1,
+                        "max": 5
                     },
-                    "maxSizeMB": 5
+                    "elements": [
+                        {
+                            "type": "file",
+                            "key": "main_image",
+                            "label": "Main Image",
+                            "required": true,
+                            "accept": {
+                                "extensions": ["png", "jpg", "jpeg", "webp"],
+                                "mime": ["image/png", "image/jpeg", "image/webp"]
+                            },
+                            "maxSizeMB": 25
+                        },
+                        {
+                            "type": "files",
+                            "key": "elements",
+                            "label": "Element Images (Optional)",
+                            "required": false,
+                            "accept": {
+                                "extensions": ["png", "jpg", "jpeg", "webp"],
+                                "mime": ["image/png", "image/jpeg", "image/webp"]
+                            },
+                            "minCount": 0,
+                            "maxCount": 5,
+                            "maxSizeMB": 10
+                        }
+                    ]
                 }
             ]
         };

package/dist/form-builder.js

@@ -119,6 +119,10 @@
                             errors.push(`${here}: repeat.min > repeat.max`);
                         }
                     }
+                    // Validate element_label if provided (optional)
+                    if (el.element_label != null && typeof el.element_label !== 'string') {
+                        errors.push(`${here}: element_label must be a string`);
+                    }
                     if (Array.isArray(el.elements)) validateElements(el.elements, pathJoin(path, el.key));
                 }
             });
@@ -590,11 +594,17 @@
                 wrapper.dataset.groupPath = pathKey;
                 
                 const groupWrap = document.createElement('div');
+                
+                // Group title (above the whole group)
+                const groupTitle = document.createElement('div');
+                groupTitle.className = 'text-lg font-semibold text-gray-900 mb-4';
+                groupTitle.textContent = element.label || element.key;
+                groupWrap.appendChild(groupTitle);
+                
                 const header = document.createElement('div');
                 header.className = 'flex items-center justify-between my-2 pb-2 border-b border-gray-200';
                 
                 const left = document.createElement('div');
-                left.innerHTML = `<span>${element.label || element.key}</span>`;
                 header.appendChild(left);
                 
                 const right = document.createElement('div');
@@ -619,18 +629,48 @@
                     const refreshControls = () => {
                         const n = countItems();
                         addBtn.disabled = n >= max;
-                        left.innerHTML = `<span>${element.label || element.key}</span> <span class="text-gray-500 text-xs">[${n} / ${max === Infinity ? '∞' : max}, min=${min}]</span>`;
+                        left.innerHTML = `<span class="text-sm text-gray-600">Items: ${n} / ${max === Infinity ? '∞' : max} (min: ${min})</span>`;
+                    };
+
+                    const updateItemIndexes = () => {
+                        const items = itemsWrap.querySelectorAll(':scope > .groupItem');
+                        items.forEach((item, index) => {
+                            const titleElement = item.querySelector('h4');
+                            if (titleElement) {
+                                let labelText;
+                                if (element.element_label) {
+                                    labelText = element.element_label.replace('$index', index + 1);
+                                } else {
+                                    labelText = `${element.label || element.key} #${index + 1}`;
+                                }
+                                titleElement.textContent = labelText;
+                            }
+                        });
                     };
 
                     const addItem = (prefillObj) => {
+                        const itemIndex = countItems() + 1;
                         const item = document.createElement('div');
-                        item.className = 'groupItem border border-dashed border-gray-300 rounded-lg p-3 mb-3 bg-blue-50/30';
-                        const subCtx = { 
-                            path: pathJoin(ctx.path, element.key + `[${countItems()}]`), 
-                            prefill: prefillObj || {} 
-                        };
-                        element.elements.forEach(child => item.appendChild(renderElement(child, subCtx, options)));
+                        item.className = 'groupItem border border-dashed border-gray-300 rounded-lg p-4 mb-3 bg-blue-50/30';
+                        
+                        // Individual item title with index
+                        const itemTitle = document.createElement('div');
+                        itemTitle.className = 'flex items-center justify-between mb-4 pb-2 border-b border-gray-300';
                         
+                        const itemLabel = document.createElement('h4');
+                        itemLabel.className = 'text-md font-medium text-gray-800';
+                        
+                        // Use element_label if provided, with $index placeholder support
+                        let labelText;
+                        if (element.element_label) {
+                            labelText = element.element_label.replace('$index', itemIndex);
+                        } else {
+                            labelText = `${element.label || element.key} #${itemIndex}`;
+                        }
+                        itemLabel.textContent = labelText;
+                        itemTitle.appendChild(itemLabel);
+                        
+                        // Add remove button to title
                         const rem = document.createElement('button');
                         rem.type = 'button';
                         rem.className = 'bg-red-500 hover:bg-red-600 text-white px-2 py-1 rounded text-xs font-medium transition-colors';
@@ -639,8 +679,18 @@
                             if (countItems() <= (element.repeat.min ?? 0)) return;
                             itemsWrap.removeChild(item);
                             refreshControls();
+                            // Re-index remaining items
+                            updateItemIndexes();
                         });
-                        item.appendChild(rem);
+                        itemTitle.appendChild(rem);
+                        
+                        const subCtx = { 
+                            path: pathJoin(ctx.path, element.key + `[${countItems()}]`), 
+                            prefill: prefillObj || {} 
+                        };
+                        
+                        item.appendChild(itemTitle);
+                        element.elements.forEach(child => item.appendChild(renderElement(child, subCtx, options)));
                         itemsWrap.appendChild(item);
                         refreshControls();
                     };
@@ -681,8 +731,9 @@
     function collectAndValidate(schema, formRoot, skipValidation = false) {
         const errors = [];
 
-        function collectElement(element, scopeRoot) {
+        function collectElement(element, scopeRoot, elementPath = '') {
             const key = element.key;
+            const fullPath = elementPath ? `${elementPath}.${key}` : key;
             
             switch (element.type) {
                 case 'text':
@@ -690,26 +741,26 @@
                     const input = scopeRoot.querySelector(`[name$="${key}"]`);
                     const val = (input?.value ?? '').trim();
                     if (!skipValidation && element.required && val === '') {
-                        errors.push(`${key}: required`);
+                        errors.push(`Field "${fullPath}" is required`);
                         markValidity(input, 'required');
                     } else if (!skipValidation && val !== '') {
                         if (element.minLength != null && val.length < element.minLength) {
-                            errors.push(`${key}: minLength=${element.minLength}`);
+                            errors.push(`Field "${fullPath}" must be at least ${element.minLength} characters`);
                             markValidity(input, `minLength=${element.minLength}`);
                         }
                         if (element.maxLength != null && val.length > element.maxLength) {
-                            errors.push(`${key}: maxLength=${element.maxLength}`);
+                            errors.push(`Field "${fullPath}" must be at most ${element.maxLength} characters`);
                             markValidity(input, `maxLength=${element.maxLength}`);
                         }
                         if (element.pattern) {
                             try {
                                 const re = new RegExp(element.pattern);
                                 if (!re.test(val)) {
-                                    errors.push(`${key}: pattern mismatch`);
+                                    errors.push(`Field "${fullPath}" does not match required format`);
                                     markValidity(input, 'pattern mismatch');
                                 }
                             } catch {
-                                errors.push(`${key}: invalid pattern`);
+                                errors.push(`Field "${fullPath}" has invalid validation pattern`);
                                 markValidity(input, 'invalid pattern');
                             }
                         }
@@ -815,10 +866,10 @@
                         const max = element.repeat.max ?? Infinity;
                         if (!skipValidation && n < min) errors.push(`${key}: count < min=${min}`);
                         if (!skipValidation && n > max) errors.push(`${key}: count > max=${max}`);
-                        items.forEach(item => {
+                        items.forEach((item, index) => {
                             const obj = {};
                             element.elements.forEach(child => {
-                                obj[child.key] = collectElement(child, item);
+                                obj[child.key] = collectElement(child, item, `${fullPath}[${index}]`);
                             });
                             out.push(obj);
                         });
@@ -826,7 +877,7 @@
                     } else {
                         const obj = {};
                         element.elements.forEach(child => {
-                            obj[child.key] = collectElement(child, itemsWrap);
+                            obj[child.key] = collectElement(child, itemsWrap, fullPath);
                         });
                         return obj;
                     }
@@ -839,7 +890,7 @@
 
         const result = {};
         schema.elements.forEach(element => {
-            result[element.key] = collectElement(element, formRoot);
+            result[element.key] = collectElement(element, formRoot, '');
         });
         
         return { result, errors };
@@ -847,7 +898,20 @@
 
     // Main form rendering function
     function renderForm(schema, container, options = {}) {
-        const { prefill = {}, readonly = false, onSubmit, onDraft, onError } = options;
+        const { 
+            prefill = {}, 
+            readonly = false, 
+            debug = false,
+            onSubmit, 
+            onDraft, 
+            onError,
+            buttons = {}
+        } = options;
+        
+        if (debug) {
+            console.log('[FormBuilder Debug] Rendering form with schema:', schema);
+            console.log('[FormBuilder Debug] Options:', options);
+        }
         
         // Validate schema first
         const schemaErrors = validateSchema(schema);
@@ -877,9 +941,11 @@
             const submitBtn = document.createElement('button');
             submitBtn.type = 'button';
             submitBtn.className = 'bg-blue-600 text-white px-4 py-2 rounded-lg hover:bg-blue-700 transition-colors';
-            submitBtn.textContent = 'Submit Form';
+            submitBtn.textContent = buttons.submit || 'Submit Form';
             submitBtn.addEventListener('click', () => {
+                if (debug) console.log('[FormBuilder Debug] Submit button clicked');
                 const { result, errors } = collectAndValidate(schema, formEl, false);
+                if (debug) console.log('[FormBuilder Debug] Validation result:', { result, errors });
                 if (errors.length > 0) {
                     if (onError) onError(errors);
                 } else {
@@ -890,9 +956,11 @@
             const draftBtn = document.createElement('button');
             draftBtn.type = 'button';
             draftBtn.className = 'bg-gray-600 text-white px-4 py-2 rounded-lg hover:bg-gray-700 transition-colors';
-            draftBtn.textContent = 'Save Draft';
+            draftBtn.textContent = buttons.draft || 'Save Draft';
             draftBtn.addEventListener('click', () => {
+                if (debug) console.log('[FormBuilder Debug] Draft button clicked');
                 const { result } = collectAndValidate(schema, formEl, true); // Skip validation for drafts
+                if (debug) console.log('[FormBuilder Debug] Draft result:', result);
                 if (onDraft) onDraft(result);
             });
             
@@ -967,6 +1035,6 @@
     exports.setUploadHandler = setUploadHandler;
     exports.setDownloadHandler = setDownloadHandler;
     exports.setThumbnailHandler = setThumbnailHandler;
-    exports.version = '0.1.4';
+    exports.version = '0.1.5';
 
 }));

package/dist/index.html

@@ -1,4 +1,4 @@
-<!doctype html>
+I <!doctype html>
 <html lang="en">
 <head>
     <meta charset="utf-8" />

package/docs/schema.md

@@ -175,27 +175,28 @@ Nested object structure with optional repetition.
 }
 ```
 
-**With Repetition:**
+**With Repetition and Custom Element Titles:**
 ```json
 {
   "type": "group",
-  "key": "contacts",
-  "label": "Contacts",
+  "key": "slides",
+  "label": "Video Slides",
+  "element_label": "Slide $index",
   "repeat": {
     "min": 1,
     "max": 5
   },
   "elements": [
     {
-      "type": "text",
-      "key": "name",
-      "label": "Contact Name",
+      "type": "file",
+      "key": "image",
+      "label": "Slide Image",
       "required": true
     },
     {
       "type": "text",
-      "key": "email", 
-      "label": "Email",
+      "key": "title", 
+      "label": "Slide Title",
       "required": true
     }
   ]
@@ -204,6 +205,7 @@ Nested object structure with optional repetition.
 
 **Properties:**
 - `elements` - Array of nested form elements
+- `element_label` - Optional custom title for each group item (supports `$index` placeholder)
 - `repeat.min` - Minimum number of repetitions
 - `repeat.max` - Maximum number of repetitions
 

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "A reusable JSON schema form builder library",
   "main": "dist/form-builder.js",
   "files": [