@dmitryvim/form-builder 0.1.42 → 0.2.1

package/README.md

@@ -35,6 +35,22 @@ Try it now: **[https://picazru.github.io/form-builder/dist/index.html](https://p
 npm install @dmitryvim/form-builder
 ```
 
+### TypeScript Setup
+
+This package ships with complete TypeScript definitions. Ensure your `tsconfig.json` is configured for modern module resolution:
+
+```json
+{
+  "compilerOptions": {
+    "moduleResolution": "NodeNext",  // or "Bundler" for Vite/Webpack
+    "esModuleInterop": true,
+    "skipLibCheck": false
+  }
+}
+```
+
+**No need for custom `.d.ts` files** - types are auto-resolved from the package at `dist/types/index.d.ts`.
+
 ## Core Features
 
 - **🎯 Schema-driven forms**: JSON Schema v0.3 → Interactive forms with live preview
@@ -48,6 +64,16 @@ npm install @dmitryvim/form-builder
 - **🔧 Framework agnostic**: Works with any web stack (React, Vue, Angular, vanilla JS)
 - **📦 Zero dependencies**: Self-contained HTML/CSS/JavaScript
 - **📱 Responsive design**: Mobile-friendly with Tailwind CSS styling
+- **🏗️ Instance-based architecture**: Multiple independent forms with isolated state
+
+### New in v0.2.0
+
+- **🔄 onChange Events**: Real-time change notifications with debouncing (eliminates polling)
+- **🎨 CSS Theming**: 43 configurable theme properties (no `!important` overrides)
+- **📝 Partial Updates**: Update fields without re-rendering (`setFormData`, `updateField`)
+- **⚡ Async Thumbnails**: Dynamic thumbnail loading with async-only `getThumbnail`
+
+**Impact**: Eliminates ~280+ lines of workaround code for Klein integration
 
 ## Quick Examples
 
@@ -144,24 +170,52 @@ npm install @dmitryvim/form-builder
 
 ```javascript
 // ES6 imports
-import FormBuilder from "@dmitryvim/form-builder";
-
-// Configure and use
-FormBuilder.setFormRoot(document.getElementById("form-container"));
-FormBuilder.setUploadHandler(async (file) => {
-  // Your upload logic - return resource ID
-  return "resource-123";
-});
-FormBuilder.setActionHandler((value, key, relatedField) => {
-  // Handle action button clicks
-  console.log("Action clicked:", { value, key, relatedField });
-  if (relatedField) {
-    // Field-level action
-  } else {
-    // Form-level action
+import { createFormBuilder } from "@dmitryvim/form-builder";
+
+// Create form instance with v0.3.0 features
+const formBuilder = createFormBuilder({
+  uploadFile: async (file) => {
+    // Your upload logic - return resource ID
+    return "resource-123";
+  },
+  downloadFile: (resourceId, fileName) => {
+    // Handle file download
+    window.open(`/api/files/${resourceId}`, '_blank');
+  },
+  getThumbnail: async (resourceId) => {
+    // v0.2.0: Async-only thumbnail loading
+    const url = await fetchThumbnailUrl(resourceId);
+    return url;
+  },
+  actionHandler: (value, key, field) => {
+    // Handle action button clicks
+    console.log("Action clicked:", { value, key, field });
+  },
+  // v0.2.0: Real-time change events
+  onChange: (formData) => {
+    console.log("Form changed:", formData);
+    if (formData.valid) autoSave(formData.data);
+  },
+  // v0.2.0: CSS theming
+  theme: {
+    primaryColor: '#0066cc',
+    borderRadius: '4px',
   }
 });
-FormBuilder.renderForm(schema, prefillData);
+
+// Render form
+const rootElement = document.getElementById("form-container");
+formBuilder.renderForm(rootElement, schema, prefillData);
+
+// Get form data
+const result = formBuilder.getFormData();
+if (result.valid) {
+  console.log("Form data:", result.data);
+}
+
+// v0.2.0: Update fields without re-rendering
+formBuilder.updateField('email', 'newemail@example.com');
+formBuilder.setFormData({ name: 'John', email: 'john@example.com' });
 ```
 
 ### 2. CDN Integration
@@ -170,7 +224,15 @@ FormBuilder.renderForm(schema, prefillData);
 <!-- Direct script include (npm CDN) -->
 <script src="https://cdn.jsdelivr.net/npm/@dmitryvim/form-builder@latest/dist/form-builder.js"></script>
 <script>
-  window.FormBuilder.renderForm(schema);
+  const { createFormBuilder } = window.FormBuilder;
+
+  const formBuilder = createFormBuilder({
+    uploadFile: async (file) => "resource-id",
+    downloadFile: (resourceId) => { /* download */ }
+  });
+
+  const rootElement = document.getElementById("form-container");
+  formBuilder.renderForm(rootElement, schema);
 </script>
 
 <!-- Or use our S3 CDN -->
@@ -222,12 +284,188 @@ See [Integration Guide](docs/integration.md) for detailed setup instructions.
 - **Read-only mode**: Display data without editing
 - **Action buttons**: Custom buttons in readonly mode with configurable handlers
 
+## API Reference
+
+### Core Methods
+
+```typescript
+import { createFormBuilder } from '@dmitryvim/form-builder';
+
+// Create form instance
+const form = createFormBuilder({
+  // Required handlers
+  uploadFile: async (file: File) => string,           // Upload file, return resource ID
+  downloadFile: (resourceId: string, fileName: string) => void,
+
+  // Optional handlers
+  getThumbnail?: async (resourceId: string) => string | null, // v0.2.0: Async-only, for preview thumbnails
+  getDownloadUrl?: (resourceId: string) => string | null,     // Optional: URL for downloading full file
+  actionHandler?: (value: any, key: string, field: any) => void,
+
+  // v0.2.0: onChange events
+  onChange?: (formData: FormResult) => void,
+  onFieldChange?: (fieldPath: string, value: any, formData: FormResult) => void,
+  debounceMs?: number, // Default: 300ms
+
+  // v0.2.0: CSS theming
+  theme?: {
+    primaryColor?: string,
+    borderRadius?: string,
+    fontSize?: string,
+    fontFamily?: string,
+    // ... 39 more theme properties
+  }
+});
+
+// Render form
+form.renderForm(rootElement, schema, prefillData);
+
+// Get form data
+const result = form.getFormData(); // { valid, errors, data }
+
+// v0.2.0: Update data without re-rendering
+form.setFormData({ name: 'John', email: 'john@example.com' });
+form.updateField('email', 'newemail@example.com');
+form.updateField('address.city', 'New York'); // Nested paths
+
+// Switch modes
+form.setMode('readonly'); // or 'edit'
+
+// Cleanup
+form.destroy();
+```
+
+### Migration from v0.1.x
+
+**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" });
+FormBuilder.renderForm(root, schema);
+
+// NEW (v0.2.0)
+const form = createFormBuilder({ uploadFile: async (file) => "id" });
+form.renderForm(root, schema);
+```
+
+2. **Async getThumbnail** - Must return Promise
+```typescript
+// OLD (v0.1.x)
+getThumbnail: (resourceId) => `/thumbs/${resourceId}.jpg`
+
+// NEW (v0.2.0)
+getThumbnail: async (resourceId) => `/thumbs/${resourceId}.jpg`
+```
+
+See [CHANGELOG.md](CHANGELOG.md) for complete migration details.
+
+### Theming
+
+Customize appearance with 43 theme properties:
+
+```typescript
+const form = createFormBuilder({
+  theme: {
+    // Colors
+    primaryColor: '#0066cc',
+    borderColor: '#e0e0e0',
+    errorColor: '#d32f2f',
+
+    // Typography
+    fontSize: '16px',
+    fontFamily: '"Roboto", sans-serif',
+
+    // Spacing
+    borderRadius: '4px',
+    inputPaddingX: '12px',
+
+    // Buttons
+    buttonBgColor: '#0066cc',
+    buttonTextColor: '#ffffff',
+  }
+});
+```
+
+**Most Common Properties:**
+- `primaryColor` - Primary brand color
+- `borderRadius` - Border radius for inputs/buttons
+- `fontSize` - Base font size
+- `fontFamily` - Font family
+- `borderColor` - Input border color
+
+No `!important` overrides needed. See [CHANGELOG.md](CHANGELOG.md) for all 43 properties.
+
+### File Handling
+
+The form builder provides flexible file handling with separate hooks for uploads, downloads, and previews:
+
+```typescript
+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
+    });
+    const data = await response.json();
+    return data.resourceId; // Return unique resource ID
+  },
+
+  // Required: Download handler
+  downloadFile: (resourceId, fileName) => {
+    // Option 1: Direct download
+    window.open(`/api/files/${resourceId}/download`, '_blank');
+
+    // Option 2: Programmatic download
+    fetch(`/api/files/${resourceId}/download`)
+      .then(response => response.blob())
+      .then(blob => {
+        const url = URL.createObjectURL(blob);
+        const a = document.createElement('a');
+        a.href = url;
+        a.download = fileName;
+        a.click();
+        URL.revokeObjectURL(url);
+      });
+  },
+
+  // Optional: Thumbnail URLs for preview (async-only in v0.2.0)
+  getThumbnail: async (resourceId) => {
+    const response = await fetch(`/api/files/${resourceId}/thumbnail`);
+    const data = await response.json();
+    return data.thumbnailUrl; // Return URL or null
+  },
+
+  // Optional: Full file download URL (used instead of getThumbnail for downloads)
+  getDownloadUrl: (resourceId) => {
+    return `/api/files/${resourceId}/download`;
+  }
+});
+```
+
+**Handler Priority for Downloads:**
+
+When a user clicks the download button in readonly mode, the form builder uses this priority:
+
+1. **`getDownloadUrl`** - If provided, this URL is used for downloads
+2. **`getThumbnail`** - If `getDownloadUrl` is not provided, falls back to thumbnail URL
+3. **`downloadFile`** - If neither URL hook is provided, calls the download handler
+
+**Use Cases:**
+
+- **Separate thumbnail and download URLs**: Provide both `getThumbnail` (for optimized previews) and `getDownloadUrl` (for full files)
+- **Same URL for both**: Provide only `getThumbnail` if thumbnail URL is also the download URL
+- **Programmatic download**: Provide only `downloadFile` for custom download logic
+
 ## Documentation
 
-- [Integration Guide](docs/integration.md) - Complete setup and usage
-- [Schema Reference](docs/schema.md) - Field types and validation rules
-- [API Documentation](docs/api.md) - Method reference and examples
-- [Development Guide](CLAUDE.md) - Architecture and development workflow
+- **API Reference** - See above for core methods and theming
+- **Development Guide** - [CLAUDE.md](CLAUDE.md) for architecture and workflow
+- **Changelog** - [CHANGELOG.md](CHANGELOG.md) for version history and migration
 
 ## Live Demo
 
@@ -246,7 +484,7 @@ Features a 3-column interface:
 - **GitHub**: [picazru/form-builder](https://github.com/picazru/form-builder)
 - **NPM Package**: [@dmitryvim/form-builder](https://www.npmjs.com/package/@dmitryvim/form-builder)
 - **CDN**: [picaz-form-builder.website.yandexcloud.net](https://picaz-form-builder.website.yandexcloud.net/)
-- **Version**: 0.1.28
+- **Version**: 0.2.0 (Unreleased - Breaking Changes + New Features)
 - **License**: MIT - see [LICENSE](LICENSE) file
 
 Built with ❤️ for the web development community.