npm - @dmitryvim/form-builder - Versions diffs - 0.1.4 → 0.1.6 - Mend

@dmitryvim/form-builder 0.1.4 → 0.1.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (11) hide show

package/README.md +34 -125
package/dist/README.md +284 -0
package/dist/example.html +108 -0
package/dist/form-builder.js +1040 -0
package/dist/index.html +447 -172
package/dist/sample.html +1615 -0
package/docs/13_form_builder.html +663 -0
package/docs/REQUIREMENTS.md +281 -0
package/docs/integration.md +445 -0
package/docs/schema.md +427 -0
package/package.json +6 -3

package/README.md CHANGED Viewed

@@ -2,35 +2,43 @@
 JSON Schema → Dynamic Forms → Structured Output
+A reusable, zero-dependency form generation library that converts JSON schemas into dynamic, interactive forms with real-time validation and file upload support.
 ## Live Demo
 Try it now: **[https://picazru.github.io/form-builder/dist/index.html](https://picazru.github.io/form-builder/dist/index.html)**
 ## Quick Start
-### Embed in Your Website
+### CDN Integration
 ```html
-<!-- Full page embed -->
+<!-- Embed via iframe -->
 <iframe src="https://picazru.github.io/form-builder/dist/index.html"
-        width="100%" height="600px"
-        frameborder="0"
-        style="border-radius: 8px;"></iframe>
+        width="100%" height="600px" frameborder="0"></iframe>
-<!-- With custom schema via URL parameter -->
-<iframe src="https://picazru.github.io/form-builder/dist/index.html?schema=eyJ2ZXJzaW9uIjoiMC4zIi..."
+<!-- With custom schema -->
+<iframe src="https://picazru.github.io/form-builder/dist/index.html?schema=BASE64_SCHEMA"
         width="100%" height="600px"></iframe>
 ```
-### Install via npm
+### NPM Installation
 ```bash
-npm install @picazru/form-builder
+npm install @dmitryvim/form-builder
 ```
-## Integration
+## Core Features
+- **Schema-driven forms**: JSON Schema v0.3 → Interactive forms
+- **File uploads**: Built-in support with configurable handlers
+- **Real-time validation**: Client-side validation with error display
+- **Framework agnostic**: Works with any web stack
+- **Zero dependencies**: Self-contained HTML/CSS/JavaScript
+- **Read-only mode**: Display form data without editing
+- **Draft saving**: Save incomplete forms without validation
-### Basic Schema
+## Basic Example
 ```json
 {
@@ -44,131 +52,32 @@ npm install @picazru/form-builder
       "required": true
     },
     {
-      "type": "file",
-      "key": "avatar",
-      "label": "Profile Picture",
+      "type": "files",
+      "key": "attachments",
+      "label": "Attachments",
+      "maxCount": 3,
       "accept": {
-        "extensions": ["jpg", "png"]
+        "extensions": ["pdf", "jpg", "png"]
       }
     }
   ]
 }
 ```
-### Configure File Handlers
-When embedding the form builder, configure file upload handlers on your page:
-```html
-<!DOCTYPE html>
-<html>
-<head>
-    <title>My App with Form Builder</title>
-</head>
-<body>
-    <!-- Embed the form builder -->
-    <iframe id="formBuilder"
-            src="https://picazru.github.io/form-builder/dist/index.html"
-            width="100%" height="600px"></iframe>
-    <script>
-    // Configure file upload handlers
-    window.addEventListener('message', (event) => {
-        if (event.origin !== 'https://picazru.github.io') return;
-        if (event.data.type === 'formBuilderReady') {
-            // Send configuration to the iframe
-            const iframe = document.getElementById('formBuilder');
-            iframe.contentWindow.postMessage({
-                type: 'configure',
-                config: {
-                    uploadHandler: async (file) => {
-                        // Your S3 upload logic
-                        const formData = new FormData();
-                        formData.append('file', file);
-                        const response = await fetch('/api/upload', {
-                            method: 'POST',
-                            body: formData
-                        });
-                        const result = await response.json();
-                        return result.fileUrl;
-                    }
-                }
-            }, 'https://picazru.github.io');
-        }
-    });
-    </script>
-</body>
-</html>
-```
-### Direct Page Integration
-If you want to integrate directly on your page (not iframe):
+## Integration Options
-```html
-<script>
-window.addEventListener('formBuilderReady', (event) => {
-  const config = event.detail;
-  // Upload files to S3
-  config.setUploadHandler(async (file) => {
-    const formData = new FormData();
-    formData.append('file', file);
-    const response = await fetch('/api/upload', {
-      method: 'POST',
-      body: formData
-    });
-    const result = await response.json();
-    return result.fileUrl; // Return S3 URL or resource ID
-  });
-  // Download files
-  config.setDownloadHandler(async (resourceId) => {
-    window.open(`/api/download/${resourceId}`, '_blank');
-  });
-  // Generate thumbnails
-  config.setThumbnailHandler(async (resourceId) => {
-    return `/api/thumbnail/${resourceId}`;
-  });
-});
-</script>
-```
+- **CDN**: Direct iframe embedding
+- **NPM**: Import as module
+- **Direct**: Self-hosted deployment
-### Field Types
+See [Integration Guide](docs/integration.md) for complete setup instructions.
-- **text** - Single line text with validation
-- **textarea** - Multi-line text
-- **number** - Numeric input with min/max
-- **select** - Dropdown with options
-- **file** - Single file upload with preview
-- **files** - Multiple file uploads
-- **group** - Nested objects with repeat support
+## Documentation
-### Form Output
-```json
-{
-  "name": "John Doe",
-  "avatar": "https://bucket.s3.amazonaws.com/files/avatar.jpg"
-}
-```
-## Development
-```bash
-git clone https://github.com/picazru/form-builder.git
-cd form-builder
-npm install
-npm run dev    # Start development server
-npm test       # Run tests
-npm run build  # Build for production
-```
+- [Integration Guide](docs/integration.md) - How to use and integrate
+- [Schema Reference](docs/schema.md) - Complete schema documentation
+- [Requirements](docs/requirements.md) - Product and business requirements
+- [Development Guide](development.md) - Development and testing
 ## License

package/dist/README.md ADDED Viewed

@@ -0,0 +1,284 @@
+# Form Builder Library
+A reusable JavaScript library for generating dynamic forms from JSON schemas.
+## Quick Start
+### 1. Include the Library
+```html
+<script src="https://unpkg.com/@dmitryvim/form-builder@latest/dist/form-builder.js"></script>
+```
+Or via npm:
+```bash
+npm install @dmitryvim/form-builder
+```
+### 2. Basic Usage
+```javascript
+// Define your schema
+const schema = {
+  "version": "0.3",
+  "title": "User Registration",
+  "elements": [
+    {
+      "type": "text",
+      "key": "name",
+      "label": "Full Name",
+      "required": true
+    },
+    {
+      "type": "text",
+      "key": "email",
+      "label": "Email",
+      "required": true
+    }
+  ]
+};
+// Get container element
+const container = document.getElementById('form-container');
+// Render the form
+const form = FormBuilder.renderForm(schema, container, {
+  onSubmit: (data) => {
+    console.log('Form submitted:', data);
+  },
+  onDraft: (data) => {
+    console.log('Draft saved:', data);
+  },
+  onError: (errors) => {
+    console.log('Validation errors:', errors);
+  }
+});
+```
+## API Reference
+### FormBuilder.renderForm(schema, container, options)
+Renders a form in the specified container.
+**Parameters:**
+- `schema` - JSON schema object (v0.3)
+- `container` - DOM element to render form in
+- `options` - Configuration object (optional)
+**Options:**
+- `prefill` - Object with prefilled values
+- `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:
+```javascript
+FormBuilder.setUploadHandler(async (file) => {
+  // Upload file to your backend
+  const response = await fetch('/upload', {
+    method: 'POST',
+    body: file
+  });
+  const result = await response.json();
+  return result.resourceId; // Return resource ID
+});
+```
+### FormBuilder.setDownloadHandler(downloadFn)
+Sets custom file download handler:
+```javascript
+FormBuilder.setDownloadHandler(async (resourceId, fileName) => {
+  window.open(`/download/${resourceId}`, '_blank');
+});
+```
+## Supported Field Types
+- `text` - Single line text input
+- `textarea` - Multi-line text input
+- `number` - Numeric input with constraints
+- `select` - Dropdown selection
+- `file` - Single file upload
+- `files` - Multiple file upload
+- `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": "Video Cover Generation",
+  "elements": [
+    {
+      "type": "text",
+      "key": "concept",
+      "label": "Animation Concept (Optional)",
+      "required": false,
+      "maxLength": 100,
+      "placeholder": "e.g., fun, elegant, dynamic, cozy..."
+    },
+    {
+      "type": "group",
+      "key": "slides_input",
+      "label": "Video Slides",
+      "element_label": "Slide $index", // 🆕 Custom title for each item
+      "repeat": {
+        "min": 1,
+        "max": 10
+      },
+      "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": 10,
+          "maxSizeMB": 10
+        }
+      ]
+    }
+  ]
+};
+// Configure file upload
+FormBuilder.setUploadHandler(async (file) => {
+  const formData = new FormData();
+  formData.append('file', file);
+  const response = await fetch('/api/upload', {
+    method: 'POST',
+    body: formData
+  });
+  const result = await response.json();
+  return result.resourceId;
+});
+// Render form
+FormBuilder.renderForm(schema, document.getElementById('form'), {
+  onSubmit: async (data) => {
+    const response = await fetch('/api/submit', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(data)
+    });
+    if (response.ok) {
+      alert('Form submitted successfully!');
+    }
+  }
+});
+```
+## Files
+- `form-builder.js` - Main library file
+- `sample.html` - Interactive demo page
+- Complete documentation at `/docs/`

package/dist/example.html ADDED Viewed

@@ -0,0 +1,108 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Form Builder - Simple Example</title>
+    <script src="https://cdn.tailwindcss.com"></script>
+</head>
+<body class="bg-gray-50 p-8">
+    <div class="max-w-2xl mx-auto">
+        <h1 class="text-3xl font-bold mb-8">Form Builder Library Example</h1>
+        <div class="bg-white rounded-lg shadow p-6 mb-8">
+            <h2 class="text-xl font-semibold mb-4">Generated Form</h2>
+            <div id="form-container"></div>
+        </div>
+        <div class="bg-white rounded-lg shadow p-6">
+            <h2 class="text-xl font-semibold mb-4">Form Output</h2>
+            <pre id="output" class="bg-gray-100 p-4 rounded text-sm overflow-auto">Submit the form to see output...</pre>
+        </div>
+    </div>
+    <script src="form-builder.js"></script>
+    <script>
+        // Example schema demonstrating element_label feature
+        const schema = {
+            "version": "0.3",
+            "title": "Video Cover Generation",
+            "elements": [
+                {
+                    "type": "text",
+                    "key": "concept",
+                    "label": "Animation Concept (Optional)",
+                    "required": false,
+                    "maxLength": 100,
+                    "placeholder": "e.g., fun, elegant, dynamic, cozy..."
+                },
+                {
+                    "type": "group",
+                    "key": "slides_input",
+                    "label": "Video Slides",
+                    "element_label": "Slide $index",
+                    "repeat": {
+                        "min": 1,
+                        "max": 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
+                        }
+                    ]
+                }
+            ]
+        };
+        // Configure file upload simulation
+        FormBuilder.setUploadHandler(async (file) => {
+            // Simulate upload delay
+            await new Promise(resolve => setTimeout(resolve, 1000));
+            // Generate fake resource ID
+            const resourceId = 'res_' + Math.random().toString(36).substr(2, 12);
+            console.log(`File "${file.name}" uploaded with ID: ${resourceId}`);
+            return resourceId;
+        });
+        // Render the form
+        const container = document.getElementById('form-container');
+        const output = document.getElementById('output');
+        FormBuilder.renderForm(schema, container, {
+            onSubmit: (data) => {
+                output.textContent = JSON.stringify(data, null, 2);
+                alert('Form submitted successfully! Check the output below.');
+            },
+            onDraft: (data) => {
+                output.textContent = 'DRAFT:\n' + JSON.stringify(data, null, 2);
+                console.log('Draft saved:', data);
+            },
+            onError: (errors) => {
+                alert('Validation errors: ' + errors.join(', '));
+            }
+        });
+    </script>
+</body>
+</html>