@jucie.io/state 1.0.24 → 1.0.25

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jucie.io/state",
-  "version": "1.0.24",
+  "version": "1.0.25",
   "description": "Modular state management system with path-based access, history, and reactive plugins",
   "type": "module",
   "main": "./dist/main.js",

package/plugins/history/README.md

@@ -1,12 +1,12 @@
 # @jucio.io/state/history
 
-History management plugin for @jucio.io/state that provides undo/redo functionality with markers, batching, and commit listeners.
+History management plugin for @jucio.io/state that provides undo/redo functionality with markers, grouping, and commit listeners.
 
 ## Features
 
 - ⏪ **Undo/Redo**: Full undo and redo support with automatic change tracking
 - 🏷️ **Markers**: Add descriptive markers to create logical undo/redo boundaries
-- 📦 **Batching**: Group multiple changes into a single undo/redo step
+- 📦 **Grouping**: Group multiple changes into a single undo/redo step (can span multiple calls; commit when done)
 - 🔔 **Commit Listeners**: React to history commits
 - 🎯 **Smart Change Consolidation**: Automatically merges changes to the same path
 - 📏 **Configurable History Size**: Limit the number of stored changes
@@ -106,34 +106,42 @@ if (state.history.canRedo()) {
 
 **Returns:** `boolean`
 
-### Batching
+### Grouping
 
-#### `batch()`
+#### `group(callback?)`
 
-Start a batch to group multiple changes into a single undo/redo step.
+Start grouping changes into a single undo/redo step. Grouping can span multiple calls; call `commit()` (or the returned function) when done. Pass a function to run in grouping mode and commit when it returns (quick single-block use).
 
 ```javascript
-const endBatch = state.history.batch();
-
+// Span multiple calls
+state.history.group();
 state.set(['user', 'name'], 'Alice');
 state.set(['user', 'age'], 30);
-state.set(['user', 'email'], 'alice@example.com');
+state.history.commit(); // All changes are now a single undo/redo step
 
-endBatch(); // All three changes are now a single undo/redo step
+// Or use the returned function
+const endGroup = state.history.group();
+state.set(['user', 'email'], 'alice@example.com');
+endGroup();
 
-state.history.undo(); // Undoes all three changes at once
+// Quick single-block: pass a callback
+state.history.group(() => {
+  state.set(['user', 'name'], 'Alice');
+  state.set(['user', 'age'], 30);
+});
+state.history.undo(); // Undoes both changes at once
 ```
 
-**Returns:** `Function` - Call the returned function to end the batch
+**Returns:** `HistoryManager` (for chaining) if a callback was provided; otherwise `Function` to call when done
 
-#### `commit()`
+#### `commit(description?)`
 
-Manually commit pending changes and end the current batch.
+Manually commit pending changes and end the current group.
 
 ```javascript
-state.history.batch();
+state.history.group();
 state.set(['data', 'value'], 1);
-state.history.commit(); // Forces commit
+state.history.commit('Initial value'); // Commits and ends grouping
 ```
 
 **Returns:** `HistoryManager` instance (for chaining)
@@ -219,11 +227,11 @@ state.install(HistoryManager.configure({
 
 ## Advanced Usage
 
-### Complex Batching with Markers
+### Grouping with Markers
 
 ```javascript
-// Start a complex operation
-state.history.batch();
+// Start a complex operation (grouping can span multiple calls)
+state.history.group();
 state.history.addMarker('Start user registration');
 
 state.set(['user', 'name'], 'Alice');
@@ -270,10 +278,10 @@ state.plugins.history.reset();
 ```javascript
 // Track form edits
 function handleFieldChange(field, value) {
-  const endBatch = state.history.batch();
+  state.history.group();
   state.set(['form', field], value);
   state.history.addMarker(`Update ${field}`);
-  endBatch();
+  state.history.commit();
 }
 
 // Implement undo/redo buttons
@@ -290,7 +298,7 @@ function handleUndo() {
 
 ```javascript
 function performComplexOperation() {
-  const endBatch = state.history.batch();
+  state.history.group();
   
   // Step 1: Update user
   state.set(['user', 'status'], 'processing');
@@ -301,7 +309,7 @@ function performComplexOperation() {
   // Step 3: Update timestamp
   state.set(['lastUpdate'], Date.now());
   
-  endBatch();
+  state.history.commit();
   state.history.addMarker('Complex operation completed');
 }