native-document 1.0.95 → 1.0.99

package/docs/observables.md

@@ -5,7 +5,6 @@ Observables are the reactive core of NativeDocument. They allow you to create va
 ## Creating Simple Observables
 
 ```javascript
-// Create an observable with an initial value
 const count = Observable(0);
 const message = Observable("Hello World");
 const isVisible = Observable(true);
@@ -36,17 +35,16 @@ console.log(name.val()); // "BOB"
 ```
 
 ## Listening to Changes
+
 The `.subscribe()` method allows you to listen to every change in an observable. The callback receives both the new value and the previous value.
 
 ```javascript
 const counter = Observable(0);
 
-// Subscribe to changes
 counter.subscribe(newValue => {
-  console.log("Counter is now:", newValue);
+    console.log("Counter is now:", newValue);
 });
 
-// Function will be called on every change
 counter.set(1); // Logs: "Counter is now: 1"
 counter.set(2); // Logs: "Counter is now: 2"
 ```
@@ -58,18 +56,14 @@ The `.on()` method allows you to watch for specific values in an observable. The
 ```javascript
 const status = Observable("idle");
 
-// Watch for specific value - callback called twice:
-// - once with true when value is reached
-// - once with false when value changes away
 status.on("loading", (isActive) => {
-  console.log(`Loading state: ${isActive}`);
+    console.log(`Loading state: ${isActive}`);
 });
 
 status.on("success", (isActive) => {
-  console.log(`Success state: ${isActive}`);
+    console.log(`Success state: ${isActive}`);
 });
 
-// Test the watchers
 status.set("loading"); // Logs: "Loading state: true"
 status.set("success"); // Logs: "Loading state: false", "Success state: true"
 status.set("idle");    // Logs: "Success state: false"
@@ -100,51 +94,43 @@ status.set("idle");    // Logs: "Success state: false"
 ```javascript
 const status = Observable("idle");
 
-// Scenario: 1000 components, each watching different states
-
-// ❌ .subscribe() - ALL 1000 callbacks run on EVERY change
+// ❌ .subscribe() — ALL 1000 callbacks run on EVERY change
 for (let i = 0; i < 1000; i++) {
-  status.subscribe(value => {
-    if (value === `state-${i}`) updateComponent(i); // Only 1 cares, all 1000 run
-  });
+    status.subscribe(value => {
+        if (value === `state-${i}`) updateComponent(i);
+    });
 }
 
-// ✅ .on() - Only relevant callback runs
+// ✅ .on() — Only relevant callback runs
 for (let i = 0; i < 1000; i++) {
-  status.on(`state-${i}`, (isActive) => {
-    if (isActive) updateComponent(i); // Only this one runs
-  });
+    status.on(`state-${i}`, (isActive) => {
+        if (isActive) updateComponent(i);
+    });
 }
 ```
+
 ## Observable .when() Method
 
 The `.when()` method creates a transitive object that passes the observable and target value without creating additional observables. It's memory-efficient for conditional operations like CSS class binding.
 
-## Syntax
-
 ```javascript
 observable.when(targetValue)
 ```
 
 Returns an object with `{$target: targetValue, $observer: observable}` that can be used with conditional operations.
+
 ### Primary Use Case: CSS Class Binding
 
 ```javascript
 const status = Observable("loading");
 
-// Memory-efficient conditional class binding
 const element = Div({
-  class: {
-    "spinner": status.when("loading"),
-    "success": status.when("success"), 
-    "error": status.when("error")
-  }
+    class: {
+        "spinner": status.when("loading"),
+        "success": status.when("success"),
+        "error":   status.when("error")
+    }
 });
-
-// The class binding system recognizes the .when() pattern:
-// - Checks if status.val() === "loading" 
-// - Toggles 'spinner' class accordingly
-// - Uses status.on("loading", callback) internally for efficiency
 ```
 
 ### Benefits
@@ -153,29 +139,150 @@ const element = Div({
 - **Optimized for class binding**: Works seamlessly with NativeDocument's class system
 - **Simple API**: Just pass the value to watch for
 
-### Implementation Note
+## Method Comparison
 
-The `.when()` method simply returns a plain object that other parts of the framework (like class binding) can recognize and handle efficiently using the `.on()` method internally.
+| Method | Memory Impact | Use Case | Return Value               |
+|--------|---------------|----------|----------------------------|
+| `.when(value)` | ✅ Zero — transitive object | CSS classes, conditional checks | `{$target, $observer}`     |
+| `.on(value, callback)` | ✅ Minimal — single listener per value | Specific value watching | void                       |
+| `.check(callback)` | ❌ Creates new ObservableChecker | Complex conditions | ObservableChecker instance |
+| `.subscribe(callback)` | ❌ Creates listener for all changes | General change detection | void                       |
+| `.persist(key, options?)` | ✅ No new observable | localStorage binding | `this` (chainable) |
 
-## Method Comparison
+## Observable Checkers
 
-| Method | Memory Impact                         | Use Case | Return Value                |
-|--------|---------------------------------------|----------|-----------------------------|
-| `.when(value)` | ✅ Zero - transitive object            | CSS classes, conditional checks | `{$target, $observer}`      |
-| `.on(value, callback)` | ✅ Minimal - single listener per value | Specific value watching | Unsubscribe function        |
-| `.check(callback)` | ❌ Creates new Observable Checker      | Complex conditions | Observable Checker instance |
-| `.subscribe(callback)` | ❌ Creates listener for all changes    | General change detection | Unsubscribe function        |
+Create derived observables with conditions or transformations. All aliases point to the same underlying `ObservableChecker` — use whichever reads most naturally for your use case.
 
+```javascript
+const age = Observable(17);
 
-## Observable Objects vs Simple Objects
+// check — canonical name
+const isAdult = age.check(value => value >= 18);
+console.log(isAdult.val()); // false
 
-**Important distinction:**
+age.set(20);
+console.log(isAdult.val()); // true
+```
+
+### Available Aliases
+
+| Alias | Best suited for |
+|-------|-----------------|
+| `.check(fn)` | General conditions |
+| `.is(fn)` | Boolean / state checks |
+| `.select(fn)` | Extracting a field |
+| `.pluck(fn)` | Extracting a field (Lodash style) |
+| `.transform(fn)` | Explicit value transformation |
+
+```javascript
+// All return an ObservableChecker — pick what reads best
+ShowIf(user.is(u => u.isAdmin), AdminPanel())
+
+const email = user.select(u => u.email);
+const label = status.transform(s => s.toUpperCase());
+const name  = user.pluck(u => u.name);
+```
+## Observable.format()
+
+Creates a derived observable that formats the current value using `Intl`.
+Automatically reacts to both value changes and locale changes via `Store.setLocale()`.
+```javascript
+const price = Observable(15000);
+const date  = Observable(new Date());
+const count = Observable(3);
+
+// Currency
+price.format('currency')                           // "15 000 FCFA"
+price.format('currency', { currency: 'EUR' })      // "15 000,00 €"
+price.format('currency', { notation: 'compact' })  // "15 K FCFA"
+
+// Number
+price.format('number')                             // "15 000"
+
+// Percent
+Observable(0.15).format('percent')                 // "15,0 %"
+Observable(0.15).format('percent', { decimals: 2}) // "15,00 %"
+
+// Date
+date.format('date')                                // "3 mars 2026"
+date.format('date', { dateStyle: 'full' })         // "mardi 3 mars 2026"
+date.format('date', { format: 'DD/MM/YYYY' })      // "03/03/2026"
+date.format('date', { format: 'DD MMM YYYY' })     // "03 mar 2026"
+date.format('date', { format: 'DD MMMM YYYY' })    // "03 mars 2026"
+
+// Time
+date.format('time')                                // "20:30"
+date.format('time', { second: '2-digit' })         // "20:30:00"
+date.format('time', { format: 'HH:mm:ss' })        // "20:30:00"
+
+// Datetime
+date.format('datetime')                            // "3 mars 2026, 20:30"
+date.format('datetime', { dateStyle: 'full' })     // "mardi 3 mars 2026, 20:30"
+date.format('datetime', { format: 'DD/MM/YYYY HH:mm' }) // "03/03/2026 20:30"
+
+// Relative
+date.format('relative')                            // "dans 11 jours"
+date.format('relative', { unit: 'month' })         // "dans 1 mois"
+
+// Plural
+count.format('plural', { singular: 'billet', plural: 'billets' }) // "3 billets"
+
+// Custom formatter — works like transform()
+price.format(value => `${value.toLocaleString()} FCFA`)
+```
+
+### Locale Reactivity
+
+All formatted observables automatically recalculate when the locale changes:
+```javascript
+const price = Observable(15000);
+const label = price.format('currency', { currency: 'XOF' });
+
+label.val();               // "15 000 FCFA"
+
+Store.get('locale').set('en-US');
+label.val();               // "$15,000.00"
+
+Store.get('locale').set('fr-TG');
+label.val();               // "15 000 FCFA"
+```
+
+### Extending Formatters
+
+Add custom format types via `Formatters`:
+```javascript
+import { Formatters } from 'native-document';
+
+Formatters.duration = (value, locale) => {
+    const hours   = Math.floor(value / 3600);
+    const minutes = Math.floor((value % 3600) / 60);
+    return `${hours}h${minutes < 10 ? '0' : ''}${minutes}`;
+};
+
+const duration = Observable(3661);
+duration.format('duration'); // "1h01"
+```
+
+### Available Format Types
+
+| Type | Input | Options |
+|------|-------|---------|
+| `currency` | `number` | `currency`, `notation`, `minimumFractionDigits`, `maximumFractionDigits` |
+| `number` | `number` | `notation`, `minimumFractionDigits`, `maximumFractionDigits` |
+| `percent` | `number` | `decimals` |
+| `date` | `Date \| number` | `dateStyle`, `format` |
+| `time` | `Date \| number` | `hour`, `minute`, `second`, `format` |
+| `datetime` | `Date \| number` | `dateStyle`, `hour`, `minute`, `second`, `format` |
+| `relative` | `Date \| number` | `unit`, `numeric` |
+| `plural` | `number` | `singular`, `plural` |
+
+## Observable Objects vs Simple Objects
 
 ```javascript
 // Observable.object() creates a PROXY with reactive properties
 const userProxy = Observable.object({
-  name: "Alice",
-  age: 25
+    name: "Alice",
+    age: 25
 });
 
 // Each property is an individual observable
@@ -183,18 +290,17 @@ console.log(userProxy.name.val()); // "Alice"
 userProxy.name.set("Bob");
 
 // Get all values as plain object
-console.log(userProxy.$value); // { name: "Bob", age: 25 }
-console.log(Observable.value(userProxy)); // { name: "Bob", age: 25 }
+console.log(userProxy.$value);           // { name: "Bob", age: 25 }
+console.log(userProxy.val()); // { name: "Bob", age: 25 }
 
 // Observable(object) creates a SINGLE observable containing the whole object
 const userSingle = Observable({
-  name: "Alice", 
-  age: 25
+    name: "Alice",
+    age: 25
 });
 
-// The entire object is the observable value
 console.log(userSingle.val()); // { name: "Alice", age: 25 }
-userSingle.set({ name: "Bob", age: 30 }); // Replace entire object
+userSingle.set({ name: "Bob", age: 30 });
 ```
 
 **Observable.object is an alias:**
@@ -203,66 +309,75 @@ userSingle.set({ name: "Bob", age: 30 }); // Replace entire object
 Observable.object(data) === Observable.json(data) === Observable.init(data)
 ```
 
-## Working with Observable Proxies
+## Working with Object Observable
 
 ```javascript
 const user = Observable.object({
-  name: "Alice",
-  age: 25,
-  email: "alice@example.com"
+    name: "Alice",
+    age: 25,
+    email: "alice@example.com"
 });
 
-// Access individual properties (each is an observable)
-console.log(user.name.val()); // "Alice"
-console.log(user.name.$value); // "Alice" (proxy syntax)
+// Access individual properties
+console.log(user.name.val());    // "Alice"
+console.log(user.name.$value);   // "Alice"
 
 // Update individual properties
 user.name.set("Bob");
-user.age.$value = 30; // Using proxy syntax
+user.age.$value = 30;
 
 // Get the complete object value
-console.log(user.$value); // { name: "Bob", age: 30, email: "alice@example.com" }
-console.log(Observable.value(user)); // Same as above
+console.log(user.$value);             // { name: "Bob", age: 30, email: "alice@example.com" }
+console.log(user.val());  // Same as above
 
 // Listen to individual property changes
 user.name.subscribe(newName => {
-  console.log("New name:", newName);
+    console.log("New name:", newName);
 });
 
-// Update multiple properties
-Observable.update(user, {
-  name: "Charlie",
-  age: 35
+// Update multiple properties at once
+user.set({
+    name: "Charlie",
+    age: 35
 });
 ```
 
 ```javascript
 const todos = Observable.array([
-  "Buy groceries",
-  "Call doctor"
+    "Buy groceries",
+    "Call doctor"
 ]);
 
-// Add elements
 todos.push("Clean house");
-
-// Remove last element
 todos.pop();
 
-// Use array methods
 const completed = todos.filter(todo => todo.includes("✓"));
 ```
 
+### Subscribing to an Observable Object
+
+Subscribing to an `Observable.object()` reacts to changes on any individual property — you don't need to subscribe to each property separately.
+```javascript
+const user = Observable.object({ name: 'Alice', age: 25 });
+
+user.subscribe(value => {
+    console.log('User changed:', value); // { name: 'Bob', age: 25 }
+});
+
+user.name.set('Bob'); // triggers the parent subscribe
+user.age.set(30);     // triggers the parent subscribe
+```
+
 ## Computed Observables
 
 Computed observables automatically recalculate when their dependencies change.
 
 ```javascript
 const firstName = Observable("John");
-const lastName = Observable("Doe");
+const lastName  = Observable("Doe");
 
-// Updates automatically
 const fullName = Observable.computed(() => {
-  return `${firstName.val()} ${lastName.val()}`;
+    return `${firstName.val()} ${lastName.val()}`;
 }, [firstName, lastName]);
 
 console.log(fullName.val()); // "John Doe"
@@ -279,31 +394,29 @@ const count = Observable(0);
 const increment = () => count.set(count.val() + 1);
 const decrement = () => (count.$value--);
 
-// Reactive interface
 const app = Div({ class: "counter" }, [
     Button("-").nd.onClick(decrement),
-    Span({ class: "count" }, count), // Automatic display
+    Span({ class: "count" }, count),
     Button("+").nd.onClick(increment)
 ]);
 ```
 
-# Batching Operations
+## Batching Operations
 
-Batching is a performance optimization technique that delays notifications to **dependent observers** (like computed observables) until the end of a batch operation. Individual observable subscribers still receive their notifications immediately, but computed observables that depend on the batch function are only triggered once at the end.
+Batching is a performance optimization technique that delays notifications to **dependent computed observables** until the end of a batch operation. Individual observable subscribers still receive their notifications immediately.
 
 ### Understanding Batch Behavior
 
 ```javascript
 const name = Observable("John");
-const age = Observable(25);
+const age  = Observable(25);
 
-// Direct subscribers always get immediate notifications
 name.subscribe(value => console.log("Name changed to:", value));
-age.subscribe(value => console.log("Age changed to:", value));
+age.subscribe(value  => console.log("Age changed to:", value));
 
 const updateProfile = Observable.batch(() => {
-    name.set("Alice");  // Logs: "Name changed to: Alice" 
-    age.set(30);        // Logs: "Age changed to: 30"
+    name.set("Alice"); // Logs: "Name changed to: Alice"
+    age.set(30);       // Logs: "Age changed to: 30"
 });
 
 updateProfile(); // Individual subscribers are notified immediately
@@ -311,34 +424,28 @@ updateProfile(); // Individual subscribers are notified immediately
 
 ### Batching with Computed Dependencies
 
-The real power of batching shows when computed observables depend on the batch function:
-
 ```javascript
 const firstName = Observable("John");
-const lastName = Observable("Doe");
+const lastName  = Observable("Doe");
 
-// Direct subscribers get immediate notifications
 firstName.subscribe(name => console.log("First name:", name));
-lastName.subscribe(name => console.log("Last name:", name));
+lastName.subscribe(name  => console.log("Last name:", name));
 
-// Batch function for name updates
 const updateName = Observable.batch((first, last) => {
     firstName.set(first); // Logs: "First name: Alice"
     lastName.set(last);   // Logs: "Last name: Smith"
 });
 
-// Computed that depends on the BATCH FUNCTION (not individual observables)
 const fullName = Observable.computed(() => {
     return `${firstName.val()} ${lastName.val()}`;
 }, updateName); // ← Depends on the batch function
 
 fullName.subscribe(name => console.log("Full name:", name));
 
-// When we call the batch:
 updateName("Alice", "Smith");
 // Logs:
-// "First name: Alice"     ← immediate notification
-// "Last name: Smith"      ← immediate notification  
+// "First name: Alice"      ← immediate
+// "Last name: Smith"       ← immediate
 // "Full name: Alice Smith" ← single notification at the end
 ```
 
@@ -348,12 +455,12 @@ updateName("Alice", "Smith");
 const score = Observable(0);
 const lives = Observable(3);
 
-// Method 1: Computed depends on individual observables
+// Method 1: depends on individual observables — recalculates twice
 const gameStatus1 = Observable.computed(() => {
     return `Score: ${score.val()}, Lives: ${lives.val()}`;
-}, [score, lives]); // ← Depends on individual observables
+}, [score, lives]);
 
-// Method 2: Computed depends on batch function
+// Method 2: depends on batch function — recalculates once
 const updateGame = Observable.batch(() => {
     score.set(score.val() + 100);
     lives.set(lives.val() - 1);
@@ -361,48 +468,37 @@ const updateGame = Observable.batch(() => {
 
 const gameStatus2 = Observable.computed(() => {
     return `Score: ${score.val()}, Lives: ${lives.val()}`;
-}, updateGame); // ← Depends on the batch function
+}, updateGame);
 
-// Without batching - gameStatus1 recalculates twice:
-score.set(100);  // gameStatus1 recalculates
-lives.set(2);    // gameStatus1 recalculates again
+score.set(100); // gameStatus1 recalculates
+lives.set(2);   // gameStatus1 recalculates again
 
-// With batching - gameStatus2 recalculates only once:
-updateGame();    // gameStatus2 recalculates only at the end
+updateGame();   // gameStatus2 recalculates only once
 ```
 
 ### Practical Example: Shopping Cart
 
 ```javascript
-const items = Observable.array([]);
-const discount = Observable(0);
+const items        = Observable.array([]);
+const discount     = Observable(0);
 const shippingCost = Observable(0);
 
-// Individual subscribers for immediate UI updates
-items.subscribe(items => {
-    console.log('Items count : '+items.length);
-});
-
-discount.subscribe(discount => {
-    console.log(`Discount: ${discount}%`);
-});
+items.subscribe(items       => console.log('Items count: ' + items.length));
+discount.subscribe(discount => console.log(`Discount: ${discount}%`));
 
-// Batch function for cart operations
 const updateCart = Observable.batch((cartData) => {
-    items.splice(0); // Clear current items
+    items.splice(0);
     cartData.items.forEach(item => items.push(item));
     discount.set(cartData.discount);
     shippingCost.set(cartData.shipping);
 });
 
-// Expensive calculation that should only run after complete cart updates
 const cartTotal = Observable.computed(() => {
-    const itemsTotal = items.val().reduce((sum, item) => sum + (item.price * item.quantity), 0);
-    const discountAmount = itemsTotal * (discount.val() / 100);
+    const itemsTotal      = items.val().reduce((sum, item) => sum + (item.price * item.quantity), 0);
+    const discountAmount  = itemsTotal * (discount.val() / 100);
     return itemsTotal - discountAmount + shippingCost.val();
-}, updateCart); // ← Only recalculates when updateCart() is called
+}, updateCart);
 
-// Example usage
 updateCart({
     items: [
         { name: "Product A", price: 29.99, quantity: 2 },
@@ -411,161 +507,77 @@ updateCart({
     discount: 10,
     shipping: 5.99
 });
-// Individual subscribers fire immediately, cartTotal calculates once at the end
 ```
 
 ### Async Batching
 
-Batch functions handle asynchronous operations, delaying dependent notifications until the promise resolves:
-
 ```javascript
 const isLoading = Observable(false);
-const userData = Observable(null);
-const error = Observable(null);
+const userData  = Observable(null);
+const error     = Observable(null);
 
-// These subscribe immediately to loading states
-isLoading.subscribe(loading => {
-    console.log('Loading.....');
-});
+isLoading.subscribe(loading => console.log('Loading.....'));
 
 const fetchUser = Observable.batch(async (userId) => {
-    isLoading.set(true);    // Immediate notification
-    error.set(null);        // Immediate notification
-    
+    isLoading.set(true);
+    error.set(null);
+
     try {
         const response = await fetch(`/api/users/${userId}`);
-        const data = await response.json();
-        userData.set(data);   // Immediate notification
+        const data     = await response.json();
+        userData.set(data);
     } catch (err) {
-        error.set(err.message); // Immediate notification
+        error.set(err.message);
     } finally {
-        isLoading.set(false);   // Immediate notification
+        isLoading.set(false);
     }
-    // Dependent computed observables are notified HERE
 });
 
-// This computed depends on the batch function
 const userDisplay = Observable.computed(() => {
     if (isLoading.val()) return "Loading...";
-    if (error.val()) return `Error: ${error.val()}`;
-    if (userData.val()) return `Hello ${userData.val().name}`;
+    if (error.val())     return `Error: ${error.val()}`;
+    if (userData.val())  return `Hello ${userData.val().name}`;
     return "No user";
-}, fetchUser); // ← Only updates when fetchUser() completes
+}, fetchUser);
 
 await fetchUser(123);
 ```
 
 ### Single Batch Dependency Only
 
-**Important**: Computed observables can only depend on **one batch function**, not multiple:
+Computed observables can only depend on **one batch function**, not multiple:
 
 ```javascript
-const user = Observable.object({ name: "", email: "" });
-const settings = Observable.object({ theme: "light", lang: "en" });
-
 const updateProfile = Observable.batch((profileData) => {
     user.name.set(profileData.name);
     user.email.set(profileData.email);
     settings.theme.set(profileData.theme);
-    settings.lang.set(profileData.lang);
 });
 
-// ✅ Correct: Single batch dependency
-const profileSummary = Observable.computed(() => {
-    return {
-        user: user.$value,
-        settings: settings.$value,
-        lastUpdated: Date.now()
-    };
-}, updateProfile); // ← Single batch function
+// ✅ Single batch dependency
+const profileSummary = Observable.computed(() => ({
+    user:        user.$value,
+    settings:    settings.$value,
+    lastUpdated: Date.now()
+}), updateProfile);
 
-// ❌ This is NOT supported:
+// ❌ Not supported
 // Observable.computed(callback, [batch1, batch2])
 ```
 
-### Performance Benefits
-
-```javascript
-const items = Observable.array([]);
-
-// Expensive computed operation
-const expensiveCalculation = Observable.computed(() => {
-    console.log("🔄 Recalculating..."); // This helps visualize when it runs
-    return items.val()
-        .filter(item => item.active)
-        .map(item => item.price * item.quantity)
-        .reduce((sum, total) => sum + total, 0);
-}, [items]); // ← Depends on individual observable
-
-const batchUpdateItems = Observable.batch(() => {
-    items.push({ active: true, price: 10, quantity: 2 });
-    items.push({ active: true, price: 15, quantity: 1 });
-    items.push({ active: false, price: 20, quantity: 3 });
-});
-
-const optimizedCalculation = Observable.computed(() => {
-    console.log("✅ Optimized recalculation");
-    return items.val()
-        .filter(item => item.active)
-        .map(item => item.price * item.quantity)
-        .reduce((sum, total) => sum + total, 0);
-}, batchUpdateItems); // ← Depends on batch function
-
-// Without batching:
-items.push({ active: true, price: 10, quantity: 2 });  // 🔄 Recalculating...
-items.push({ active: true, price: 15, quantity: 1 });  // 🔄 Recalculating...
-items.push({ active: false, price: 20, quantity: 3 }); // 🔄 Recalculating...
-
-// With batching:
-batchUpdateItems(); // ✅ Optimized recalculation (only once!)
-```
-
 ### Best Practices
 
-1. **Use batch dependencies for expensive computations**: When you have costly computed observables that shouldn't recalculate on every individual change
-
-2. **Keep individual subscribers for immediate feedback**: UI feedback like input validation should use direct subscriptions
-
-3. **Batch related operations**: Group logically connected updates that should trigger dependent computations together
-
-4. **Don't over-batch**: Only use batching when you have computed observables that benefit from delayed updates
-
-### Common Patterns
-
-### State Machine with Batched Transitions
-```javascript
-const gameState = Observable.object({
-    level: 1,
-    score: 0,
-    lives: 3
-});
-
-// Individual subscribers for immediate UI updates
-gameState.score.subscribe(score => updateScoreDisplay(score));
-gameState.lives.subscribe(lives => updateLivesDisplay(lives));
-
-// Batch function for state transitions
-const levelUp = Observable.batch(() => {
-    gameState.level.set(gameState.level.val() + 1);
-    gameState.score.set(gameState.score.val() + 1000);
-    gameState.lives.set(gameState.lives.val() + 1);
-});
-
-// Complex computed that should only run after complete transitions
-const gameStatusMessage = Observable.computed(() => {
-    const state = gameState.$value;
-    return `Level ${state.level}: ${state.score} points, ${state.lives} lives remaining`;
-}, levelUp); // ← Only updates when levelUp() is called
-```
+- Use batch dependencies for expensive computations that shouldn't recalculate on every individual change
+- Keep individual subscribers for immediate feedback (input validation, UI updates)
+- Group logically connected updates that should trigger dependent computations together
+- Don't over-batch — only use when computed observables benefit from delayed updates
 
 ### When NOT to Use Batch Dependencies
 
-- **Real-time updates**: When computed observables need to update immediately
-- **Simple computations**: When the computational cost is minimal
-- **Debugging**: Batching can make the flow harder to debug
-- **Single observable changes**: No benefit when only one observable changes
-
-The key insight is that batching in NativeDocument is about **controlling when dependent computed observables recalculate**, not about suppressing individual observable notifications.
+- Real-time updates where computed observables need to update immediately
+- Simple computations where the cost is minimal
+- Debugging contexts — batching can make the flow harder to trace
+- Single observable changes — no benefit when only one observable changes
 
 ## String Templates with Observables
 
@@ -573,10 +585,10 @@ The key insight is that batching in NativeDocument is about **controlling when d
 
 ```javascript
 const name = Observable("Alice");
-const age = Observable(25);
+const age  = Observable(25);
 
 const template = "Hello ${name}, you are ${age} years old";
-const message = template.use({ name, age });
+const message  = template.use({ name, age });
 
 console.log(message.val()); // "Hello Alice, you are 25 years old"
 
@@ -588,25 +600,9 @@ console.log(message.val()); // "Hello Bob, you are 25 years old"
 
 ```javascript
 const greeting = Observable("Hello");
-const user = Observable("Marie");
+const user     = Observable("Marie");
 
-// Observables are automatically integrated
 const element = Div(null, `${greeting} ${user}!`);
-// Updates when greeting or user changes
-```
-
-## Observable Checkers
-
-Create derived observables with conditions:
-
-```javascript
-const age = Observable(17);
-const isAdult = age.check(value => value >= 18);
-
-console.log(isAdult.val()); // false
-
-age.set(20);
-console.log(isAdult.val()); // true
 ```
 
 ## Memory Management
@@ -614,58 +610,46 @@ console.log(isAdult.val()); // true
 ```javascript
 const data = Observable("test");
 
-// Create a subscription
 const handler = value => console.log(value);
 data.subscribe(handler);
 
-
-// Clean up manually if needed
-data.unsubscribe('test', handler);
+// Remove specific subscription
+data.unsubscribe(handler);
 
 // Complete observable cleanup
 data.cleanup(); // Removes all listeners and prevents new subscriptions
 
-// Manual trigger (useful for forcing updates)
-data.trigger(); // Notifies all subscribers without changing the value
+// Manual trigger — forces update without changing the value
+data.trigger();
 
 // Extract values from any observable structure
-const complexData = Observable.object({
-    user: "John",
-    items: [1, 2, 3]
-});
-console.log(Observable.value(complexData)); // Plain object with extracted values
+const complexData = Observable.object({ user: "John", items: [1, 2, 3] });
+console.log(complexData.val()); // Plain object with extracted values
 ```
 
 ## Utility Methods
 
-### `off(value, callback?)` - Remove Watchers
+### `off(value, callback?)` — Remove Watchers
 
-Remove specific value watchers created with `.on()`:
 ```javascript
 const status = Observable("idle");
 
 const loadingHandler = (isActive) => console.log("Loading:", isActive);
 status.on("loading", loadingHandler);
 
-// Remove specific callback
-status.off("loading", loadingHandler);
-
-// Remove all watchers for a value
-status.off("loading");
+status.off("loading", loadingHandler); // Remove specific callback
+status.off("loading");                 // Remove all watchers for this value
 ```
 
-### `once(predicate, callback)` - Single-Time Listener
+### `once(predicate, callback)` — Single-Time Listener
 
-Execute callback only once when condition is met:
 ```javascript
 const count = Observable(0);
 
-// Wait for specific value
 count.once(5, (value) => {
     console.log("Reached 5!"); // Only called once
 });
 
-// With predicate function
 count.once(val => val > 10, (value) => {
     console.log("Greater than 10!"); // Only called once
 });
@@ -674,108 +658,142 @@ count.set(5); // Callback fires and unsubscribes
 count.set(5); // Callback doesn't fire again
 ```
 
-### `toggle()` - Boolean Toggle
+### `toggle()` — Boolean Toggle
 
-Toggle boolean observables:
 ```javascript
 const isVisible = Observable(false);
 
 isVisible.toggle(); // true
 isVisible.toggle(); // false
-isVisible.toggle(); // true
 
-// Useful with buttons
 Button("Toggle").nd.onClick(() => isVisible.toggle());
 ```
 
-### `reset()` - Reset to Initial Value
+### `reset()` — Reset to Initial Value
 
-Reset observable to its initial value (requires `reset: true` config):
 ```javascript
 const name = Observable("Alice", { reset: true });
 
 name.set("Bob");
-console.log(name.val()); // "Bob"
-
 name.reset();
-console.log(name.val()); // "Alice" (initial value)
+console.log(name.val()); // "Alice"
 
-// With objects
 const user = Observable({ name: "Alice", age: 25 }, { reset: true });
 user.set({ name: "Bob", age: 30 });
 user.reset(); // Back to { name: "Alice", age: 25 }
 ```
 
-### `equals(other)` - Value Comparison
+### `equals(other)` — Value Comparison
 
-Compare observable values:
 ```javascript
 const num1 = Observable(5);
 const num2 = Observable(5);
 const num3 = Observable(10);
 
-console.log(num1.equals(num2)); // true (same value)
-console.log(num1.equals(5));    // true (compare with raw value)
+console.log(num1.equals(num2)); // true
+console.log(num1.equals(5));    // true
 console.log(num1.equals(num3)); // false
 ```
 
-### `toBool()` - Boolean Conversion
+### `toBool()` — Boolean Conversion
 
-Convert observable value to boolean:
 ```javascript
 const text = Observable("");
 console.log(text.toBool()); // false
 
 text.set("Hello");
 console.log(text.toBool()); // true
-
-// Useful for conditions
-const hasContent = text.toBool();
 ```
 
-### `intercept(callback)` - Value Interception
+### `intercept(callback)` — Value Interception
 
-Intercept and modify values before they're set:
 ```javascript
 const age = Observable(0);
 
-// Intercept sets to enforce constraints
 age.intercept((newValue, oldValue) => {
-    if (newValue < 0) return 0;
+    if (newValue < 0)   return 0;
     if (newValue > 120) return 120;
     return newValue;
 });
 
-age.set(-5);  // Actually sets 0
-age.set(150); // Actually sets 120
+age.set(-5);  // Sets 0
+age.set(150); // Sets 120
 age.set(25);  // Sets 25
 
-// Practical example: sanitize input
 const username = Observable("");
-username.intercept((value) => {
-    return value.toLowerCase().trim();
-});
+username.intercept((value) => value.toLowerCase().trim());
 
-username.set("  JohnDoe  "); 
+username.set("  JohnDoe  ");
 console.log(username.val()); // "johndoe"
 ```
 
+### `persist(key, options?)` — Persist to localStorage
+
+Binds an observable to localStorage. The value is automatically restored on load and saved on every change.
+```javascript
+// Simple persistence — key defaults to the variable name
+const theme = Observable('light').persist('theme');
+theme.set('dark'); // saved to localStorage automatically
+
+// On next page load
+const theme = Observable('light').persist('theme');
+theme.val(); // "dark" — restored from localStorage
+```
+
+With transform options — useful when the stored format differs from the runtime format:
+```javascript
+// Store as ISO string, restore as Date object
+const selectedDate = Observable(new Date()).persist('event:date', {
+    get: value => new Date(value),   // transform on load
+    set: value => value.toISOString() // transform on save
+});
+
+// Store only the user id, restore the full object later
+const user = Observable(null).persist('session:user', {
+    get: value => value ? JSON.parse(value) : null,
+    set: value => value ? JSON.stringify(value) : null
+});
+```
+
+**Without Store** — use `.persist()` directly on any observable for component-level persistence without polluting the global store:
+```javascript
+const FiltersPanel = () => {
+    const expanded = Observable(false).persist('filters:expanded');
+    const columns  = Observable(['name', 'date']).persist('table:columns');
+
+    return Div([/* ... */]);
+};
+```
+
+### `deepSubscribe(callback)` — Deep Change Detection
+
+Reacts to changes at any depth — array mutations, and property changes on nested observables.
+```javascript
+const tags = Observable.array([{ label: 'admin' }]);
+
+const unsub = tags.deepSubscribe(value => console.log('changed:', value));
+
+tags.push({ label: 'editor' });      // ✅ déclenche
+tags[0].label.set('superadmin');     // ✅ déclenche
+tags.splice(0, 1);                   // ✅ déclenche + cleanup du listener
+
+// Cleanup
+unsub();
+```
+
 ## Best Practices
 
 1. **Use descriptive names** for your observables
 2. **Understand the difference**: `Observable(object)` vs `Observable.object(object)`
-3. **Use proxies for convenience**: `obs.$value` instead of `obs.val()`
-4. **Group related data** with `Observable.object()` for individual property reactivity
-5. **Use `Observable.value()`** to extract plain values from complex structures
-6. **Prefer computed** for derived values
-7. **Clean up** unused observables to prevent memory leaks
-8. **Use `trigger()`** when you need to force updates without value changes
-9. **Avoid** direct modifications in subscription callbacks
+3. **Group related data** with `Observable.object()` for individual property reactivity
+4. **Use `Observable.value()`** to extract plain values from complex structures
+5. **Prefer computed** for derived values
+6. **Clean up** unused observables to prevent memory leaks
+7. **Use `trigger()`** when you need to force updates without value changes
+8. **Avoid** direct modifications in subscription callbacks
 
 ## Next Steps
 
-Now that you understand NativeDocument's observable, explore these advanced topics:
-
 - **[Elements](elements.md)** - Creating and composing UI
 - **[Conditional Rendering](conditional-rendering.md)** - Dynamic content
 - **[List Rendering](list-rendering.md)** - (ForEach | ForEachArray) and dynamic lists
@@ -792,4 +810,4 @@ Now that you understand NativeDocument's observable, explore these advanced topi
 
 - **[Cache](docs/utils/cache.md)** - Lazy initialization and singleton patterns
 - **[NativeFetch](docs/utils/native-fetch.md)** - HTTP client with interceptors
-- **[Filters](docs/utils/filters.md)** - Data filtering helpers
+- **[Filters](docs/utils/filters.md)** - Data filtering helpers