npm - resonantjs - Versions diffs - 1.1.7 → 1.2.0 - Mend

resonantjs 1.1.7 → 1.2.0

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 (23) hide show

package/README.md +181 -374
package/aiagent.md +207 -165
package/package.json +1 -1
package/resonant.js +136 -74
package/resonant.min.js +1 -1
package/resonant.min.js.map +1 -1
package/scripts/build.js +8 -1
package/test/additional_features.test.js +2 -2
package/test/array_methods.test.js +401 -0
package/test/complex_scenarios.test.js +413 -0
package/test/deep_nesting.test.js +2 -2
package/test/display_selective_rendering.test.js +172 -0
package/test/edge_cases.test.js +627 -0
package/test/error_handling.test.js +304 -0
package/test/existing_variable_binding.test.js +151 -0
package/test/html_examples.test.js +1 -1
package/test/input_binding_advanced.test.js +323 -0
package/test/mockDom.js +7 -5
package/test/resonant.test.js +1 -1
package/test/selective_rendering.test.js +141 -1
package/test/style_and_events.test.js +1 -1
package/test/template.test.js +1 -1
package/Demo.gif +0 -0

package/README.md CHANGED Viewed

@@ -1,76 +1,70 @@
-# ResonantJs 🚀
+# ResonantJs
 [![npm version](https://badge.fury.io/js/resonantjs.svg)](https://badge.fury.io/js/resonantjs)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-**ResonantJs** is a lightweight, powerful JavaScript framework that brings **reactive data-binding** to vanilla JavaScript applications. Build dynamic, responsive UIs with minimal code and zero dependencies.
+**Reactive data-binding for vanilla JavaScript. No build step. No virtual DOM. Just HTML attributes and plain objects.**
-> **Zero dependencies • ~11.5KB minified • Lightning fast • Easy to learn**
+```html
+<span res="count"></span>
+<button onclick="count++">+1</button>
-## ✨ Why Choose ResonantJs?
+<script src="https://unpkg.com/resonantjs@latest/resonant.min.js"></script>
+<script>
+  const res = new Resonant();
+  res.add('count', 0);
+</script>
+```
-- 🔄 **True Reactivity**: Data changes automatically update the DOM - no manual manipulation needed
-- 🎯 **Attribute-Based**: Use simple HTML attributes to create powerful data bindings
-- 🏗️ **Deep Object Support**: Handles nested objects and arrays with full reactivity
-- 💾 **Built-in Persistence**: Automatic localStorage integration for data persistence
-- 🎨 **Dynamic Styling**: Conditional CSS classes and styles based on your data
-- ⚡ **Performance**: Efficient updates with minimal overhead
-- 📦 **Tiny Footprint**: Under 11.5KB minified - perfect for any project size
+Change `count` anywhere in your code and the DOM updates automatically.
 ---
-## 🚀 Quick Start
-### Installation
+## Install
-#### NPM
 ```bash
 npm install resonantjs
 ```
-#### CDN
+Or drop in a script tag:
 ```html
-<script src="https://unpkg.com/resonantjs@latest/resonant.js"></script>
+<script src="https://unpkg.com/resonantjs@latest/resonant.min.js"></script>
 ```
-### Hello World Example
+~18 KB minified. Zero dependencies.
-```html
-<!DOCTYPE html>
-<html>
-<head>
-  <title>ResonantJs Demo</title>
-  <script src="https://unpkg.com/resonantjs@latest/resonant.js"></script>
-</head>
-<body>
-  <h1>Counter: <span res="counter"></span></h1>
-  <button onclick="counter++">Increment</button>
-  <button onclick="counter--">Decrement</button>
-  <script>
-    const resonant = new Resonant();
-    resonant.add("counter", 0, true); // value, localStorage persistence
-  </script>
-</body>
-</html>
-```
+---
+## Why ResonantJs?
-That's it! Your counter will automatically update the DOM and persist to localStorage.
+| | |
+|---|---|
+| **No build tools** | Works with a single `<script>` tag. Ship today. |
+| **Familiar mental model** | Plain objects, plain arrays, plain HTML. No JSX, no templates, no compilation. |
+| **Automatic DOM updates** | Change a value, the page updates. Arrays, nested objects, computed properties -- all reactive. |
+| **Selective re-rendering** | Only the changed array item re-renders. Siblings stay untouched. |
+| **Built-in persistence** | One flag to sync any variable to `localStorage`. |
+| **Tiny footprint** | ~18 KB minified, zero dependencies. |
 ---
-## 📖 Core Concepts
+## Quick Tour
-### 1. **Data Binding** (`res`)
-Bind HTML elements directly to your JavaScript variables:
+### Bind a variable
 ```html
-<span res="username"></span>        <!-- Simple variable -->
-<div res="user.profile.name"></div> <!-- Nested object property -->
+<h1>Hello, <span res="name"></span></h1>
 ```
-### 2. **Object Properties** (`res-prop`)
-Bind to specific properties within objects:
+```js
+const res = new Resonant();
+res.add('name', 'World');
+name = 'ResonantJs'; // DOM updates instantly
+```
+### Bind an object
 ```html
 <div res="user">
@@ -79,433 +73,246 @@ Bind to specific properties within objects:
 </div>
 ```
-### 3. **Array Rendering**
-Automatically render arrays with template-based elements:
+```js
+res.add('user', { name: 'Alice', email: 'alice@example.com' });
+user.name = 'Bob'; // only the name span updates
+```
+### Render an array
+Place `res` on a template element inside a list container. ResonantJs clones it once per item.
 ```html
 <ul>
-  <li res="todoItems">
+  <li res="tasks">
     <span res-prop="title"></span>
-    <button res-onclick="removeItem(item)">Delete</button>
+    <button res-onclick-remove="id">x</button>
   </li>
 </ul>
 ```
-### 4. **Conditional Display** (`res-display`)
-Show/hide elements based on conditions:
+```js
+res.add('tasks', [
+  { id: 1, title: 'Learn ResonantJs' },
+  { id: 2, title: 'Ship a feature' }
+]);
-```html
-<div res-display="user.isActive">Welcome back!</div>
-<div res-display="tasks.length > 0">You have tasks</div>
-<div res-display="user.role === 'admin'">Admin Panel</div>
+tasks.push({ id: 3, title: 'Profit' }); // new <li> appears
+tasks[0].title = 'Done!';                // only that <li> re-renders
 ```
-### 5. **Dynamic Styling** (`res-style`)
-Apply conditional CSS classes and styles:
+### Conditional display
 ```html
-<div res-style="task.completed ? 'completed' : 'pending'">Task</div>
-<span res-style="'priority-' + task.priority">High Priority</span>
+<div res-display="user.isAdmin">Admin Panel</div>
+<div res-display="tasks.length === 0">No tasks yet.</div>
 ```
-### 6. **Event Handling** (`res-onclick`)
-Bind click events with context:
+### Dynamic classes
 ```html
-<button res-onclick="editTask(item)">Edit</button>
-<button res-onclick-remove="true">Delete Item</button>
+<span res-prop="title" res-style="done ? 'completed' : ''"></span>
 ```
-### 7. **Computed Properties**
-Create reactive derived values that automatically update:
+### Computed properties
-```javascript
-const resonant = new Resonant();
-resonant.add('firstName', 'John');
-resonant.add('lastName', 'Doe');
+Derived values that recalculate automatically when dependencies change. Chains work too.
-// Computed property automatically updates when dependencies change
-resonant.computed('fullName', () => {
-  return firstName + ' ' + lastName;
-});
+```js
+res.add('price', 100);
+res.add('taxRate', 0.08);
+res.computed('tax',   () => price * taxRate);
+res.computed('total', () => price + tax);    // chains: updates when tax updates
 ```
 ```html
-<span res="fullName"></span> <!-- Automatically shows "John Doe" -->
+Total: $<span res="total"></span>
 ```
-### 8. **Input Binding**
-Two-way data binding for form elements:
+### Two-way input binding
 ```html
-<input type="text" res="user.name" />
+<input type="text" res="name" />
 <input type="checkbox" res="settings.darkMode" />
-<select res="user.country">
-  <option value="us">United States</option>
-  <option value="uk">United Kingdom</option>
-</select>
+<select res="country">...</select>
 ```
----
-## 🎯 Key Features
-### **Reactive Data Management**
-```javascript
-const resonant = new Resonant();
-// Add single variables
-resonant.add('counter', 0);
-resonant.add('user', { name: 'John', age: 30 });
+### Persistence
-// Batch initialization
-resonant.addAll({
-  tasks: [],
-  settings: { theme: 'light' },
-  currentUser: { name: 'Alice', role: 'admin' }
-});
-// Changes automatically update the UI
-user.name = 'Jane';           // DOM updates instantly
-tasks.push({ title: 'New task' }); // Array renders new item
+```js
+res.add('theme', 'light', true); // third arg = persist to localStorage
+theme = 'dark';                  // saved automatically
 ```
-### **Event Callbacks**
-React to data changes with custom logic:
+### Bind existing variables
-```javascript
-resonant.addCallback('tasks', (newValue, item, action) => {
-  console.log(`Tasks ${action}:`, item);
-  updateTaskCounter();
-  saveToAPI();
-});
+Already have a variable on `window`? Register it without passing a value.
-resonant.addCallback('user', (newValue, item, action) => {
-  if (action === 'modified') {
-    showNotification('Profile updated');
-  }
-});
+```js
+window.username = 'Alice';
+res.add('username');       // picks up 'Alice', makes it reactive
+res.add('username', true); // same, but also persists to localStorage
 ```
-### **Persistence**
-Automatic localStorage integration:
-```javascript
-// Data persists across browser sessions
-resonant.add('userPreferences', { theme: 'dark' }, true);
-resonant.add('appState', { currentView: 'dashboard' }, true);
+### Event handling
-// Changes are automatically saved
-userPreferences.theme = 'light'; // Saved to localStorage
+```html
+<button res-onclick="editTask">Edit</button>      <!-- receives the current item -->
+<button res-onclick-remove="id">Delete</button>    <!-- removes item by matching property -->
 ```
-### **Computed Properties**
-Reactive derived values that automatically recalculate:
-```javascript
-resonant.add('firstName', 'John');
-resonant.add('lastName', 'Doe');
-// Automatically updates when firstName or lastName changes
-resonant.computed('fullName', () => {
-  return firstName + ' ' + lastName;
-});
-// Cannot be set directly - read-only
-// fullName = 'Something'; // Will log warning and be ignored
+### Callbacks
-// Chain computed properties
-resonant.computed('greeting', () => {
-  return 'Hello, ' + fullName + '!';
+```js
+res.addCallback('tasks', (value, item, action) => {
+  console.log(action, item); // 'added', 'removed', 'modified', etc.
 });
 ```
-### **Advanced Array Operations**
-Full array reactivity with custom methods:
-```javascript
-// All operations trigger UI updates
-items.push(newItem);           // Add item
-items.splice(index, 1);        // Remove item
-items.update([...newItems]);   // Replace entire array
-items.set(index, newValue);    // Update specific index
-items.delete(index);           // Delete by index
-```
 ---
-## 🏗️ Real-World Examples
+## Build a Todo App
+Copy this into an `.html` file and open it in your browser.
-### Todo List with Filtering
 ```html
-<div>
-  <input res="newTask" placeholder="Add task..." />
+<!doctype html>
+<html>
+<head>
+  <style>.done { text-decoration: line-through; color: #999; }</style>
+  <script src="https://unpkg.com/resonantjs@latest/resonant.min.js"></script>
+</head>
+<body>
+  <h1>Todos (<span res="tasks.length"></span>)</h1>
+  <input placeholder="Add a task..." res="newTask" />
   <button onclick="addTask()">Add</button>
-  <select res="filter">
-    <option value="all">All Tasks</option>
-    <option value="active">Active</option>
-    <option value="completed">Completed</option>
-  </select>
   <ul>
-    <li res="filteredTasks"
-        res-display="filter === 'all' || (filter === 'active' && !completed) || (filter === 'completed' && completed)">
-      <input type="checkbox" res-prop="completed" />
-      <span res-prop="title" res-style="completed ? 'completed-task' : ''"></span>
-      <button res-onclick="deleteTask(item)">Delete</button>
+    <li res="tasks">
+      <input type="checkbox" res-prop="done" />
+      <span res-prop="name" res-style="done ? 'done' : ''"></span>
+      <button res-onclick="removeTask">x</button>
     </li>
   </ul>
-</div>
-<script>
-const resonant = new Resonant();
-resonant.addAll({
-  tasks: [
-    { title: 'Learn ResonantJs', completed: false },
-    { title: 'Build awesome app', completed: false }
-  ],
-  newTask: '',
-  filter: 'all',
-  filteredTasks: []
-});
+  <script>
+    const res = new Resonant();
+    res.addAll({
+      newTask: '',
+      tasks: [
+        { name: 'Learn ResonantJs', done: false },
+        { name: 'Ship a feature', done: true }
+      ]
+    });
-function addTask() {
-  if (newTask.trim()) {
-    tasks.push({ title: newTask, completed: false });
-    newTask = '';
-    updateFilter();
-  }
-}
-function deleteTask(task) {
-  const index = tasks.indexOf(task);
-  tasks.splice(index, 1);
-  updateFilter();
-}
-function updateFilter() {
-  filteredTasks.splice(0);
-  tasks.forEach(task => filteredTasks.push(task));
-}
-resonant.addCallback('filter', updateFilter);
-resonant.addCallback('tasks', updateFilter);
-updateFilter();
-</script>
-```
+    function addTask() {
+      const title = newTask.trim();
+      if (!title) return;
+      tasks.unshift({ name: title, done: false });
+      newTask = '';
+    }
-### Dashboard with Statistics
-```html
-<div class="dashboard">
-  <div class="stats">
-    <div class="stat-card">
-      <h3 res="stats.totalTasks"></h3>
-      <p>Total Tasks</p>
-    </div>
-    <div class="stat-card">
-      <h3 res="stats.completedTasks"></h3>
-      <p>Completed</p>
-    </div>
-    <div class="stat-card">
-      <h3 res="stats.completionRate"></h3>
-      <p>% Complete</p>
-    </div>
-  </div>
-  <div class="projects">
-    <div res="projects">
-      <div res-prop="" class="project-card">
-        <h3 res-prop="name"></h3>
-        <div class="progress-bar">
-          <div class="progress" res-style="'width: ' + progress + '%'"></div>
-        </div>
-        <div res-prop="tasks">
-          <div res-prop="" res-style="'task priority-' + priority">
-            <span res-prop="title"></span>
-            <span res-prop="assignee"></span>
-          </div>
-        </div>
-      </div>
-    </div>
-  </div>
-</div>
+    function removeTask(item) {
+      const idx = tasks.indexOf(item);
+      if (idx !== -1) tasks.delete(idx);
+    }
+  </script>
+</body>
+</html>
 ```
 ---
-## 📚 Advanced Patterns
-### **Nested Data Structures**
-Handle complex, deeply nested data:
-```javascript
-resonant.add('company', {
-  departments: [
-    {
-      name: 'Engineering',
-      teams: [
-        {
-          name: 'Frontend',
-          members: [
-            { name: 'Alice', role: 'Senior Dev', skills: ['React', 'Vue'] },
-            { name: 'Bob', role: 'Junior Dev', skills: ['HTML', 'CSS'] }
-          ]
-        }
-      ]
-    }
-  ]
-});
+## API Reference
-// All levels are reactive
-company.departments[0].teams[0].members[0].name = 'Alice Johnson';
-company.departments[0].teams[0].members.push(newMember);
-```
+### JavaScript
-### **Computed Properties**
-Create reactive calculated values that automatically update when dependencies change:
+| Method | Description |
+|---|---|
+| `new Resonant()` | Create an instance |
+| `.add(name, value?, persist?)` | Add a reactive variable. Omit `value` to bind an existing `window` variable. Pass `true` as second or third arg to persist to `localStorage`. |
+| `.addAll({ name: value, ... })` | Add multiple variables at once |
+| `.addCallback(name, fn)` | Listen for changes. `fn(currentValue, item, action)` |
+| `.computed(name, fn)` | Define a read-only derived value |
-```javascript
-const resonant = new Resonant();
-resonant.add('tasks', [
-  { title: 'Task 1', completed: true },
-  { title: 'Task 2', completed: false },
-  { title: 'Task 3', completed: true }
-]);
+### HTML Attributes
-// Computed properties automatically recalculate when 'tasks' changes
-resonant.computed('totalTasks', () => {
-  return tasks.length;
-});
+| Attribute | Description |
+|---|---|
+| `res="varName"` | Bind element to a variable (scalar, object, or array template) |
+| `res-prop="key"` | Bind to an object property within a `res` context |
+| `res-display="expr"` | Show/hide element based on a JS expression |
+| `res-style="expr"` | Apply CSS classes from a JS expression |
+| `res-onclick="fnName"` | Call a global function on click; receives current item if in an array |
+| `res-onclick-remove="prop"` | Remove the current item from its parent array by matching property |
-resonant.computed('completedTasks', () => {
-  return tasks.filter(t => t.completed).length;
-});
+### Array Methods
-resonant.computed('completionRate', () => {
-  return totalTasks > 0 ? Math.round((completedTasks / totalTasks) * 100) : 0;
-});
+Reactive arrays support all standard methods plus:
-// Shopping cart example
-resonant.add('items', [
-  { name: 'Widget', price: 10, quantity: 2 },
-  { name: 'Gadget', price: 15, quantity: 1 }
-]);
-resonant.add('taxRate', 0.08);
+| Method | Description |
+|---|---|
+| `.set(index, value)` | Update item at index |
+| `.delete(index)` | Remove item at index |
+| `.update(newArray)` | Replace entire array contents |
+| `.filterInPlace(fn)` | Mutating filter |
+| `.forceUpdate()` | Force re-render without changing data |
-resonant.computed('subtotal', () => {
-  return items.reduce((sum, item) => sum + (item.price * item.quantity), 0);
-});
+### Callback Actions
-resonant.computed('tax', () => {
-  return subtotal * taxRate;
-});
+`added` `removed` `modified` `updated` `filtered`
-resonant.computed('total', () => {
-  return subtotal + tax;
-});
-```
+---
-```html
-<!-- These automatically update when items change -->
-<div>Subtotal: $<span res="subtotal"></span></div>
-<div>Tax: $<span res="tax"></span></div>
-<div>Total: $<span res="total"></span></div>
-```
+## Performance
-### **Component-Like Patterns**
-Organize code into reusable patterns:
-```javascript
-function createTaskManager(containerId) {
-  const resonant = new Resonant();
-  resonant.addAll({
-    tasks: [],
-    filter: 'all',
-    newTask: ''
-  });
-  resonant.addCallback('tasks', updateStats);
-  return {
-    addTask: () => { /* implementation */ },
-    removeTask: (task) => { /* implementation */ },
-    setFilter: (filter) => { /* implementation */ }
-  };
-}
-```
+- **Selective array re-rendering** -- when a property on one array item changes, only that item's DOM subtree is updated. Siblings are untouched, including their `res-display` and `res-style` evaluations.
+- **Batched updates** -- rapid changes within the same tick are coalesced into a single DOM update.
+- **Computed property chains** -- cascading computed properties resolve in dependency order within a single pass.
+- **Stable keys** -- array items are tracked by stable keys for efficient reuse during re-renders.
 ---
-## 🎨 Examples & Demos
+## Browser Support
-Explore our comprehensive examples:
-- **[Basic Counter](./examples/example-basic.html)** - Simple reactive counter
-- **[Task Manager](./examples/example-taskmanager.html)** - Complete task management app
-- **[Houses Demo](./examples/example-houses.html)** - Complex nested data structures
-- **[Advanced Demo](./examples/example-taskmanager-simple-demo.html)** - Full-featured application
-Each example demonstrates different aspects of ResonantJs and can serve as starting points for your projects.
+Chrome 60+ / Firefox 55+ / Safari 12+ / Edge 79+ / Mobile browsers
 ---
-## 🚀 Performance & Browser Support
-### **Performance**
-- **Minimal overhead**: Only updates affected DOM elements
-- **Efficient diffing**: Smart change detection for nested objects
-- **Lazy evaluation**: Conditional expressions only run when dependencies change
-- **Memory efficient**: Automatic cleanup of unused observers
+## Examples
-### **Browser Support**
-- ✅ Chrome 60+
-- ✅ Firefox 55+
-- ✅ Safari 12+
-- ✅ Edge 79+
-- ✅ Mobile browsers (iOS Safari, Chrome Mobile)
+- [Basic Counter](./examples/example-basic.html)
+- [Task Manager](./examples/example-taskmanager.html)
+- [Nested Data (Houses)](./examples/example-houses.html)
+- [Tests Showcase](./examples/tests.html)
 ---
-## 🤝 Contributing
+## Development
-We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
-### Development Setup
 ```bash
 git clone https://github.com/amurgola/ResonantJs.git
 cd ResonantJs
 npm install
-npm test
+npm test          # run all tests
+npm run build     # run tests + minify
 ```
-### Running Tests
-```bash
-npm test                    # Run all tests
-npm test -- test/specific.test.js  # Run specific test file
-```
----
-## 📄 License
-ResonantJs is released under the **MIT License**. See [LICENSE](LICENSE) file for details.
 ---
-## 🙋‍♂️ Support & Community
+## License
-- **Issues**: [GitHub Issues](https://github.com/amurgola/ResonantJs/issues)
-- **Discussions**: [GitHub Discussions](https://github.com/amurgola/ResonantJs/discussions)
-- **Documentation**: [Full API Documentation](https://github.com/amurgola/ResonantJs/wiki)
+MIT -- see [LICENSE](LICENSE).
 ---
 <div align="center">
-**[⭐ Star us on GitHub](https://github.com/amurgola/ResonantJs)** • **[🚀 Try the Demo](./examples/example-taskmanager-simple-demo.html)** • **[📖 Read the Docs](https://github.com/amurgola/ResonantJs/wiki)**
+**[GitHub](https://github.com/amurgola/ResonantJs)** · **[npm](https://www.npmjs.com/package/resonantjs)** · **[Issues](https://github.com/amurgola/ResonantJs/issues)**
-*Built with ❤️ by [Andrew Paul Murgola](https://github.com/amurgola)*
+*Built by [Andrew Paul Murgola](https://github.com/amurgola)*
 </div>