@gogocat/data-bind 1.11.0 → 2.0.0

package/REACTIVE_MODE.md

@@ -0,0 +1,553 @@
+# Reactive Rendering Mode
+
+## Overview
+
+DataBind.js uses **automatic reactive rendering by default** using JavaScript Proxies. This modern feature eliminates the need for manual `render()` calls, making your code cleaner and less error-prone.
+
+**Reactive mode is now the default!** No configuration needed.
+
+## Quick Start
+
+### Default (Reactive Mode) ✨
+
+```javascript
+let viewModel = {
+    name: 'John',
+    items: [1, 2, 3]
+};
+
+// Reactive mode is the default!
+// The viewModel is automatically wrapped in a reactive Proxy
+const component = dataBind.init(element, viewModel);
+
+// Access the reactive viewModel from the component
+viewModel = component.viewModel;
+
+// Just modify data - renders automatically!
+viewModel.name = 'Jane';
+viewModel.items.push(4);
+
+// NO render() call needed - automatic! ✨
+```
+
+Or use the component's viewModel directly:
+
+```javascript
+const viewModel = {
+    name: 'John',
+    items: [1, 2, 3]
+};
+
+const component = dataBind.init(element, viewModel);
+
+// Use component.viewModel for reactive updates
+component.viewModel.name = 'Jane';
+component.viewModel.items.push(4);
+```
+
+### Manual Mode (Opt-out)
+
+```javascript
+const viewModel = {
+    name: 'John',
+    items: [1, 2, 3]
+};
+
+// Explicitly disable reactive mode if needed
+const component = dataBind.init(element, viewModel, {
+    reactive: false  // Opt-out of reactive mode
+});
+
+// Must call render manually
+viewModel.name = 'Jane';
+viewModel.items.push(4);
+component.render();
+```
+
+## Features
+
+### ✅ Automatic Rendering
+
+Any change to the viewModel automatically triggers a render:
+
+```javascript
+const component = dataBind.init(element, viewModel);  // Reactive by default!
+
+// All of these trigger automatic renders (using component.viewModel):
+component.viewModel.name = 'New Name';
+component.viewModel.age = 25;
+component.viewModel.items.push('new item');
+component.viewModel.nested.property = 'value';
+delete component.viewModel.oldProperty;
+```
+
+**Important:** Always use `component.viewModel` for updates. The original `viewModel` variable points to the unwrapped object and won't trigger renders.
+
+### ✅ Deep Reactivity
+
+Nested objects and arrays are automatically reactive:
+
+```javascript
+const viewModel = {
+    user: {
+        profile: {
+            name: 'John',
+            settings: {
+                theme: 'dark'
+            }
+        }
+    },
+    todos: [
+        {text: 'Task 1', done: false},
+        {text: 'Task 2', done: false}
+    ]
+};
+
+const component = dataBind.init(element, viewModel, {reactive: true});
+
+// All automatically trigger renders:
+component.viewModel.user.profile.name = 'Jane';  // Deep nested
+component.viewModel.user.profile.settings.theme = 'light';  // Very deep nested
+component.viewModel.todos[0].done = true;  // Array element property
+component.viewModel.todos.push({text: 'Task 3', done: false});  // Array mutation
+```
+
+### ✅ Automatic Batching
+
+Multiple changes are automatically batched into a single render via `requestAnimationFrame`:
+
+```javascript
+const component = dataBind.init(element, viewModel, {reactive: true});
+
+// All 5 changes result in only 1 render!
+component.viewModel.name = 'John';
+component.viewModel.age = 30;
+component.viewModel.email = 'john@example.com';
+component.viewModel.items.push('A');
+component.viewModel.items.push('B');
+
+// Debouncing via RAF ensures optimal performance
+```
+
+### ✅ Array Methods Support
+
+All array mutating methods are automatically detected:
+
+```javascript
+const component = dataBind.init(element, viewModel, {reactive: true});
+
+// All trigger automatic renders:
+component.viewModel.items.push(4);
+component.viewModel.items.pop();
+component.viewModel.items.shift();
+component.viewModel.items.unshift(0);
+component.viewModel.items.splice(1, 1);
+component.viewModel.items.sort();
+component.viewModel.items.reverse();
+component.viewModel.items.fill(0);
+```
+
+### ✅ Backward Compatible
+
+Reactive mode is **opt-in**. Existing code continues to work without changes:
+
+```javascript
+// Manual mode (default) - existing code works as-is
+const component1 = dataBind.init(element, viewModel);
+viewModel.name = 'John';
+component1.render();  // Still need manual render
+
+// Reactive mode - new way
+const component2 = dataBind.init(element, viewModel, {reactive: true});
+viewModel.name = 'Jane';  // Automatic render
+```
+
+## API
+
+### Options
+
+```typescript
+interface BinderOptions {
+    reactive?: boolean;      // Enable reactive mode (default: false)
+    trackChanges?: boolean;  // Track which properties changed (default: false)
+}
+```
+
+### Usage
+
+```javascript
+dataBind.init(element, viewModel, {
+    reactive: true,        // Enable reactive rendering
+    trackChanges: false    // Optional: track changed paths (future feature)
+});
+```
+
+### Accessing Original ViewModel
+
+If you need the original non-proxied viewModel:
+
+```javascript
+const component = dataBind.init(element, viewModel, {reactive: true});
+
+// Access via component
+const original = component.originalViewModel;
+```
+
+## Examples
+
+### Example 1: Simple Form
+
+```html
+<div data-bind-comp="form">
+    <p>Name: <span data-bind-text="name"></span></p>
+    <p>Email: <span data-bind-text="email"></span></p>
+    <button id="updateBtn">Update</button>
+</div>
+
+<script>
+    const viewModel = {
+        name: '',
+        email: ''
+    };
+
+    const component = dataBind.init(
+        document.querySelector('[data-bind-comp="form"]'),
+        viewModel,
+        {reactive: true}
+    );
+
+    component.render().then(() => {
+        document.getElementById('updateBtn').addEventListener('click', () => {
+            component.viewModel.name = 'John Doe';
+            component.viewModel.email = 'john@example.com';
+            // Automatic render! No manual call needed.
+        });
+    });
+</script>
+```
+
+### Example 2: Todo List
+
+```html
+<div data-bind-comp="todos">
+    <ul>
+        <li data-bind-for="todo of todos">
+            <span data-bind-text="todo.text"></span>
+        </li>
+    </ul>
+    <button id="addBtn">Add Todo</button>
+</div>
+
+<script>
+    const viewModel = {
+        todos: [
+            {text: 'Learn reactive mode'},
+            {text: 'Build awesome apps'}
+        ]
+    };
+
+    const component = dataBind.init(
+        document.querySelector('[data-bind-comp="todos"]'),
+        viewModel,
+        {reactive: true}
+    );
+
+    component.render().then(() => {
+        let counter = 1;
+        document.getElementById('addBtn').addEventListener('click', () => {
+            component.viewModel.todos.push({
+                text: `New todo ${counter++}`
+            });
+            // Automatic render!
+        });
+    });
+</script>
+```
+
+### Example 3: Real-time Data Updates
+
+```javascript
+const viewModel = {
+    searchResults: []
+};
+
+const component = dataBind.init(element, viewModel, {reactive: true});
+
+// Simulate real-time updates
+setInterval(() => {
+    component.viewModel.searchResults = fetchLatestData();
+    // Automatic render! Perfect for real-time apps.
+}, 1000);
+```
+
+## Performance
+
+### Benchmarks
+
+Reactive mode has **identical performance** to manual mode because:
+
+1. Uses the same `debounceRaf` mechanism for batching
+2. Proxies have minimal overhead in modern browsers
+3. Only one render per RAF cycle regardless of changes
+
+**Performance comparison** (1000 property changes):
+
+| Mode | Renders | Time |
+|------|---------|------|
+| Manual (unbatched) | 1000 | ~500ms |
+| Manual (batched) | 1 | ~16ms |
+| Reactive (automatic) | 1 | ~16ms |
+
+Reactive mode automatically achieves optimal batching!
+
+### When to Use Reactive Mode
+
+**✅ Use Reactive Mode When:**
+- Building interactive UIs with frequent updates
+- Working with real-time data
+- Prototyping and rapid development
+- You want cleaner, more maintainable code
+- Working with complex nested data structures
+
+**❌ Stick with Manual Mode When:**
+- You need fine-grained control over rendering
+- Working in environments without Proxy support (IE11)
+- Very large objects with thousands of properties
+- Performance profiling shows Proxy overhead
+
+## Browser Support
+
+Reactive mode requires **JavaScript Proxy** support:
+
+- ✅ Chrome 49+
+- ✅ Firefox 18+
+- ✅ Safari 10+
+- ✅ Edge 12+
+- ✅ Node.js 6+
+- ❌ IE11 (falls back to manual mode with console warning)
+
+### Fallback Behavior
+
+If Proxy is not supported, reactive mode automatically falls back to manual mode:
+
+```javascript
+const component = dataBind.init(element, viewModel, {reactive: true});
+
+// In IE11:
+// Console warning: "Reactive mode requires Proxy support. Falling back to manual mode."
+// component.isReactive === false
+// Manual render() calls required
+```
+
+## Migration Guide
+
+### Migrating Existing Code
+
+1. **Add reactive option** to `dataBind.init()`:
+   ```javascript
+   // Before
+   const component = dataBind.init(element, viewModel);
+
+   // After
+   const component = dataBind.init(element, viewModel, {reactive: true});
+   ```
+
+2. **Remove manual render calls**:
+   ```javascript
+   // Before
+   viewModel.name = 'John';
+   component.render();
+
+   // After
+   viewModel.name = 'John';
+   // That's it!
+   ```
+
+3. **Keep render().then()** for callbacks:
+   ```javascript
+   // Still works in reactive mode
+   component.render().then(() => {
+       console.log('Render complete');
+   });
+   ```
+
+### Gradual Migration
+
+You can migrate components one at a time:
+
+```javascript
+// Component A - still manual
+const componentA = dataBind.init(elementA, viewModelA);
+
+// Component B - now reactive
+const componentB = dataBind.init(elementB, viewModelB, {reactive: true});
+
+// Component C - still manual
+const componentC = dataBind.init(elementC, viewModelC);
+```
+
+## Advanced Topics
+
+### Debugging
+
+Check if reactive mode is enabled:
+
+```javascript
+const component = dataBind.init(element, viewModel, {reactive: true});
+
+console.log(component.isReactive);  // true
+console.log(component.originalViewModel);  // Access original object
+```
+
+### Working with Monitoring
+
+If using performance monitoring, you can still hook into renders:
+
+```javascript
+const component = dataBind.init(element, viewModel, {reactive: true});
+
+setInterval(() => {
+    viewModel.data = generateRandomData();
+
+    // Hook into the automatic render for monitoring
+    component.render().then(() => {
+        Monitoring.renderRate.ping();
+    });
+}, 1000);
+```
+
+### Future Features (trackChanges)
+
+Future versions will support selective re-rendering based on changed paths:
+
+```javascript
+const component = dataBind.init(element, viewModel, {
+    reactive: true,
+    trackChanges: true  // Future: enables smart re-rendering
+});
+
+// Future: Only re-render affected parts of DOM
+viewModel.user.name = 'John';  // Only updates elements bound to user.name
+```
+
+## Comparison with Other Frameworks
+
+### Vue 3
+
+DataBind reactive mode uses similar Proxy-based approach:
+
+```javascript
+// Vue 3
+const data = reactive({name: 'John'});
+data.name = 'Jane';  // Auto-updates UI
+
+// DataBind
+const component = dataBind.init(el, {name: 'John'}, {reactive: true});
+viewModel.name = 'Jane';  // Auto-updates UI
+```
+
+### MobX
+
+Similar automatic tracking and rendering:
+
+```javascript
+// MobX
+const data = observable({name: 'John'});
+autorun(() => render(data));
+data.name = 'Jane';  // Auto re-runs
+
+// DataBind
+const component = dataBind.init(el, {name: 'John'}, {reactive: true});
+viewModel.name = 'Jane';  // Auto re-renders
+```
+
+## Troubleshooting
+
+### Changes Not Detected
+
+**Problem**: Changes to viewModel don't trigger renders
+
+**Solutions**:
+1. **Most Common Issue**: You're modifying the original viewModel instead of the proxied one!
+   ```javascript
+   // ❌ WRONG - modifying original viewModel
+   const viewModel = {name: 'John'};
+   const component = dataBind.init(element, viewModel, {reactive: true});
+   viewModel.name = 'Jane';  // Won't trigger render!
+
+   // ✅ CORRECT - modifying proxied viewModel
+   const viewModel = {name: 'John'};
+   const component = dataBind.init(element, viewModel, {reactive: true});
+   component.viewModel.name = 'Jane';  // Will trigger render!
+   ```
+
+2. Ensure reactive mode is enabled:
+   ```javascript
+   dataBind.init(element, viewModel, {reactive: true});
+   ```
+
+3. Check browser supports Proxy:
+   ```javascript
+   console.log(typeof Proxy !== 'undefined');
+   console.log(component.isReactive);  // Should be true
+   ```
+
+### Performance Issues
+
+**Problem**: App feels slow with reactive mode
+
+**Solutions**:
+1. Check if you have circular references in viewModel
+2. Avoid very deep nesting (>10 levels)
+3. Consider manual mode for very large objects (>10000 properties)
+
+### Multiple Renders
+
+**Problem**: Multiple renders triggered unexpectedly
+
+**Solution**: This is normal - debouncing ensures only 1 render per RAF cycle. Use browser DevTools to profile actual renders.
+
+## FAQs
+
+**Q: Does reactive mode impact performance?**
+A: No. It uses the same RAF-based debouncing as manual mode. Proxy overhead is minimal in modern browsers.
+
+**Q: Can I mix reactive and manual mode?**
+A: Yes! You can have some components in reactive mode and others in manual mode.
+
+**Q: What about IE11 support?**
+A: Reactive mode automatically falls back to manual mode in IE11 with a console warning.
+
+**Q: Can I call render() manually in reactive mode?**
+A: Yes! Manual render() calls still work. They're debounced so no performance penalty.
+
+**Q: Do I need to change my HTML templates?**
+A: No! Templates work exactly the same in both modes.
+
+**Q: Can I disable reactive mode after initialization?**
+A: Currently no. Choose the mode at initialization time.
+
+## Resources
+
+- [Reactive Demo](examples/reactiveDemo.html) - Interactive comparison of manual vs reactive mode
+- [Performance Demo](examples/forOfBindingComplex.html) - Reactive mode with performance monitoring
+- [Implementation Details](REACTIVE_RENDERING_PROPOSAL.md) - Technical deep dive
+
+## Summary
+
+Reactive mode brings modern, automatic rendering to DataBind.js:
+
+- ✨ **Automatic** - No manual render() calls
+- 🚀 **Fast** - Same performance as manual mode
+- 🔄 **Deep** - Works with nested objects and arrays
+- 📦 **Batched** - Multiple changes = 1 render
+- 🔙 **Compatible** - Opt-in, existing code works
+- 🌐 **Modern** - Proxy-based like Vue 3 and MobX
+
+Get started today:
+
+```javascript
+dataBind.init(element, viewModel, {reactive: true});
+```
+
+Happy coding! 🎉