trakked 1.0.0 → 1.1.0

package/README.md

@@ -1,6 +1,6 @@
 # Trakked
 
-A TypeScript library for frontend state management — undo/redo, dirty tracking, validation, and server-assigned ID handling.
+A TypeScript library for frontend state management — undo/redo, dirty tracking, validation, composable edits, and server-assigned ID handling.
 
 Built on the **TC39 decorator standard** (Stage 3). Requires TypeScript 5+ with `experimentalDecorators` **not** set.
 
@@ -251,6 +251,14 @@ tracker.beforeCommit();       // assign temporary negative IDs to new models bef
 
 `onCommit()` automatically transitions every tracked object's `state` to `Unchanged` and appends the state change into the existing last undo operation — so undo atomically reverts both the user's edits and the committed state together (no spurious extra undo steps).
 
+**Composing**
+
+```typescript
+tracker.startCoalescing();   // begin grouping subsequent changes
+tracker.endCoalescing();     // commit — all changes become one undo step
+tracker.rollbackCoalescing();  // revert — all changes since startCoalescing are rolled back
+```
+
 **Object construction**
 
 ```typescript
@@ -282,6 +290,52 @@ tracker.endSuppressTracking();
 
 Suppression is **nestable** via a counter, so calling `beginSuppressTracking()` twice requires two `endSuppressTracking()` calls to resume tracking.
 
+**Composing**
+
+Groups all tracked changes made between `startCoalescing()` and `endCoalescing()` into a single undo step. Call `rollbackCoalescing()` instead to revert all changes made during the composing session.
+
+```typescript
+tracker.startCoalescing();
+
+model.firstName = 'Alice';
+model.lastName  = 'Smith';
+model.email     = 'alice@example.com';
+
+// Keep changes — all three writes become one undo step
+tracker.endCoalescing();
+
+tracker.undo(); // reverts firstName, lastName, and email together
+```
+
+```typescript
+tracker.startCoalescing();
+
+model.firstName = 'Alice';
+model.lastName  = 'Smith';
+
+// Discard changes — all writes since startCoalescing are reverted
+tracker.rollbackCoalescing();
+// model.firstName and model.lastName are back to their previous values
+```
+
+Nesting is not supported: a second call to `startCoalescing()` while composing is already active is a no-op.
+
+**Typical use case — edit modal**
+
+Open a modal that edits a slice of the model. If the user confirms, the entire set of modal edits lands in the undo history as one step. If the user cancels, all edits are rolled back invisibly.
+
+```typescript
+function openEditModal(model: PersonModel) {
+  tracker.startCoalescing();
+
+  showModal({
+    model,
+    onConfirm: () => tracker.endCoalescing(),
+    onCancel:  () => tracker.rollbackCoalescing(),
+  });
+}
+```
+
 ---
 
 ### `TrackedObject`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trakked",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Operation tracking, undo/redo, dirty state, and validation for TypeScript",
   "type": "module",
   "main": "./dist/prod/index.cjs",