feat: Introduces the ability to make objects and array changes reacti…

…ve by "tracking" them

## Summary

To improve that experience, you can now set a `track` flag when creating the signal. When set to true, this will make the signal reactive to changes in the object or array properties.

> 📒 Think about this as using the `@track` decorator in LWC properties. It works the exact same way behind the scenes.

```javascript
import { $signal } from "c/signals";

const obj = $signal({ x: 1, y: 2 }, { track: true });
const computedFromObj = $computed(() => obj.value.x + obj.value.y);

// When a value in the object changes, the computed value will automatically update
obj.value.x = 2;

console.log(computedFromObj.value); // 4
```

README.md

@@ -176,6 +176,28 @@ export const counterPlusTwo = $computed(() => counterPlusOne.value + 1);
 
 Because `$computed` values return a signal, you can use them as you would use any other signal.
 
+## Tracking objects and arrays
+
+By default, for a signal to be reactive it needs to be reassigned. This can be cumbersome when dealing with objects
+and arrays, as you would need to reassign the whole object or array to trigger the reactivity.
+
+To improve that experience, you can set the `track` flag to true when creating the signal. This will make the signal
+reactive to changes in the object or array properties.
+
+> 📒 Think about this as using the `@track` decorator in LWC properties. It works the exact same way behind the scenes.
+
+```javascript
+import { $signal } from "c/signals";
+
+const obj = $signal({ x: 1, y: 2 }, { track: true });
+const computedFromObj = $computed(() => obj.value.x + obj.value.y);
+
+// When a value in the object changes, the computed value will automatically update
+obj.value.x = 2;
+
+console.log(computedFromObj.value); // 4
+```
+
 ## Reacting to multiple signals
 
 You can also use multiple signals in a single `computed` and react to changes in any of them.

examples/computed-from-multiple-signals/lwc/businessCard/businessCard.html

@@ -6,4 +6,4 @@
       <div>Contact Name: {contactInfo.contactName}</div>
     </div>
   </div>
-</template>
+</template>

examples/computed-from-multiple-signals/lwc/businessCard/businessCard.js

@@ -10,4 +10,4 @@ export default class BusinessCard extends LightningElement {
         contactName: contactName.value
       })
   ).value;
-}
+}

examples/computed-from-multiple-signals/lwc/businessCard/businessCard.js-meta.xml

@@ -8,4 +8,4 @@
         <target>lightningCommunity__Default</target>
         <target>lightningCommunity__Page</target>
     </targets>
-</LightningComponentBundle>
+</LightningComponentBundle>

examples/computed-from-multiple-signals/lwc/contactInfoForm/contactInfoForm.html

@@ -10,4 +10,4 @@
     value={contactName}
     onchange={handleContactNameChange}
   ></lightning-input>
-</template>
+</template>

examples/computed-from-multiple-signals/lwc/contactInfoForm/contactInfoForm.js

@@ -13,4 +13,4 @@ export default class ContactInfoForm extends LightningElement {
   handleContactNameChange(event) {
     contactName.value = event.target.value;
   }
-}
+}

examples/computed-from-multiple-signals/lwc/contactInfoForm/contactInfoForm.js-meta.xml

@@ -8,4 +8,4 @@
         <target>lightningCommunity__Default</target>
         <target>lightningCommunity__Page</target>
     </targets>
-</LightningComponentBundle>
+</LightningComponentBundle>

examples/counter/lwc/countChanger/countChanger.html

@@ -3,4 +3,4 @@
     <button onclick={decrementCount}>Decrement</button>
     <button onclick={incrementCount}>Increment</button>
   </div>
-</template>
+</template>

examples/counter/lwc/countChanger/countChanger.js

@@ -9,4 +9,4 @@ export default class CountChanger extends LightningElement {
   decrementCount() {
     counter.value--;
   }
-}
+}

examples/counter/lwc/countTracker/countTracker.html

@@ -1,4 +1,4 @@
 <template>
   The current count is ($computed reactive property): {reactiveProperty} <br />
   The counter plus two value is (nested computed): {counterPlusTwo}
-</template>
+</template>

examples/counter/lwc/countTracker/countTracker.js

@@ -8,4 +8,4 @@ export default class CountTracker extends LightningElement {
 
   counterPlusTwo = $computed(() => (this.counterPlusTwo = counterPlusTwo.value))
     .value;
-}
+}

examples/demo-signals/lwc/demoSignals/contact-info.js

@@ -2,4 +2,4 @@ import { $signal } from "c/signals";
 
 export const accountName = $signal("ACME");
 
-export const contactName = $signal("John Doe");
+export const contactName = $signal("John Doe");

examples/demo-signals/lwc/demoSignals/demoSignals.js-meta.xml

@@ -4,4 +4,4 @@
     <description>Demo Signals</description>
     <isExposed>false</isExposed>
     <masterLabel>Demo Signals</masterLabel>
-</LightningComponentBundle>
+</LightningComponentBundle>

examples/demo-signals/lwc/demoSignals/shopping-cart.js

@@ -19,14 +19,17 @@ import updateShoppingCart from "@salesforce/apex/ShoppingCartController.updateSh
  */
 
 // Store each state change in the cart history
-export const cartHistory = $signal([]);
+export const cartHistory = $signal([], { track: true });
+$effect(() => {
+  console.log("cartHistory", JSON.stringify(cartHistory.value, null, 2));
+});
 let isUndoing = false;
 
 export const undoCartChange = () => {
   isUndoing = true;
   const lastState = cartHistory.value[cartHistory.value.length - 1];
   // Remove the last state from the history
-  cartHistory.value = cartHistory.value.slice(0, -1);
+  cartHistory.value.splice(-1, 1);
   if (lastState) {
     updateCart(lastState);
   }
@@ -55,7 +58,7 @@ async function updateCartOnTheServer(newCart, previousValue, mutate) {
 
     // Store the previous value in the history
     if (shouldUpdateHistory) {
-      cartHistory.value = [...cartHistory.value, previousValue];
+      cartHistory.value.push(previousValue);
     }
   } catch (error) {
     mutate(null, error);

examples/server-communication/classes/ResourceController.cls-meta.xml

@@ -1,4 +1,4 @@
-<?xml version="1.0" encoding="UTF-8"?>
+<?xml version="1.0" encoding="UTF-8" ?>
 <ApexClass xmlns="http://soap.sforce.com/2006/04/metadata">
     <apiVersion>60.0</apiVersion>
     <status>Active</status>

examples/server-communication/lwc/displaySelectedAccount/displaySelectedAccount.html

@@ -3,7 +3,10 @@
   <div>
     <h1>Selected Account</h1>
     <template if:true={account.loading}>
-      <lightning-spinner alternative-text="Loading" size="large"></lightning-spinner>
+      <lightning-spinner
+        alternative-text="Loading"
+        size="large"
+      ></lightning-spinner>
     </template>
 
     <template if:false={account.loading}>
@@ -14,4 +17,4 @@ <h1>Selected Account</h1>
       </template>
     </template>
   </div>
-</template>
+</template>

examples/server-communication/lwc/displaySelectedAccount/displaySelectedAccount.js

@@ -4,4 +4,4 @@ import { getAccount } from "c/demoSignals";
 
 export default class DisplaySelectedAccount extends LightningElement {
   account = $computed(() => (this.account = getAccount.value)).value;
-}
+}

examples/server-communication/lwc/displaySelectedAccount/displaySelectedAccount.js-meta.xml

@@ -1,4 +1,4 @@
-<?xml version="1.0" encoding="UTF-8"?>
+<?xml version="1.0" encoding="UTF-8" ?>
 <LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
     <apiVersion>60.0</apiVersion>
     <description>Display Selected Account</description>
@@ -8,4 +8,4 @@
         <target>lightningCommunity__Default</target>
         <target>lightningCommunity__Page</target>
     </targets>
-</LightningComponentBundle>
+</LightningComponentBundle>

examples/server-communication/lwc/listAccounts/listAccounts.html

@@ -6,4 +6,4 @@
     options={accounts}
     onchange={handleAccountChange}
   ></lightning-select>
-</template>
+</template>

examples/server-communication/lwc/listAccounts/listAccounts.js

@@ -28,4 +28,4 @@ export default class ListAccounts extends LightningElement {
   handleAccountChange(event) {
     selectedAccountId.value = event.detail.value;
   }
-}
+}

examples/server-communication/lwc/listAccounts/listAccounts.js-meta.xml

@@ -1,4 +1,4 @@
-<?xml version="1.0" encoding="UTF-8"?>
+<?xml version="1.0" encoding="UTF-8" ?>
 <LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
     <apiVersion>60.0</apiVersion>
     <description>List Accounts</description>
@@ -8,4 +8,4 @@
         <target>lightningCommunity__Default</target>
         <target>lightningCommunity__Page</target>
     </targets>
-</LightningComponentBundle>
+</LightningComponentBundle>

examples/server-communication/lwc/serverFetcher/serverFetcher.html

@@ -1,13 +1,11 @@
 <!-- Server Fetcher -->
 <template>
-  <template if:true={contacts.loading}>
-    Loading
-  </template>
+  <template if:true={contacts.loading}> Loading </template>
   <template if:false={contacts.loading}>
     <template for:each={contacts.data} for:item="contact">
       <div key={contact.Id}>
         <p>{contact.Name}</p>
       </div>
     </template>
   </template>
-</template>
+</template>

examples/server-communication/lwc/serverFetcher/serverFetcher.js-meta.xml

@@ -1,4 +1,4 @@
-<?xml version="1.0" encoding="UTF-8"?>
+<?xml version="1.0" encoding="UTF-8" ?>
 <LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
     <apiVersion>60.0</apiVersion>
     <description>Server Fetcher</description>
@@ -8,4 +8,4 @@
         <target>lightningCommunity__Default</target>
         <target>lightningCommunity__Page</target>
     </targets>
-</LightningComponentBundle>
+</LightningComponentBundle>

examples/shopping-cart/controllers/ShoppingCartController.cls-meta.xml

@@ -1,4 +1,4 @@
-<?xml version="1.0" encoding="UTF-8"?>
+<?xml version="1.0" encoding="UTF-8" ?>
 <ApexClass xmlns="http://soap.sforce.com/2006/04/metadata">
     <apiVersion>60.0</apiVersion>
     <status>Active</status>

examples/shopping-cart/lwc/checkoutButton/checkoutButton.html

@@ -1 +1 @@
-<template></template>
+<template></template>

examples/shopping-cart/lwc/checkoutButton/checkoutButton.js

@@ -1,13 +1,19 @@
 import TwElement from "c/twElement";
-import {$computed} from 'c/signals';
-import {shoppingCart} from "c/demoSignals";
+import { $computed, $effect } from "c/signals";
+import { shoppingCart } from "c/demoSignals";
 
 // States
 import ready from "./states/ready.html";
 import loading from "./states/loading.html";
 
 export default class CheckoutButton extends TwElement {
-  itemData = $computed(() => this.itemData = shoppingCart.value).value;
+  itemData = shoppingCart.value;
+
+  connectedCallback() {
+    $effect(() => {
+      this.itemData = shoppingCart.value;
+    });
+  }
 
   render() {
     return this.itemData.loading ? loading : ready;
@@ -16,4 +22,4 @@ export default class CheckoutButton extends TwElement {
   get isEmpty() {
     return this.itemData.data.items.length === 0;
   }
-}
+}

examples/shopping-cart/lwc/checkoutButton/checkoutButton.js-meta.xml

@@ -1,4 +1,4 @@
-<?xml version="1.0" encoding="UTF-8"?>
+<?xml version="1.0" encoding="UTF-8" ?>
 <LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
     <apiVersion>60.0</apiVersion>
     <description>Checkout Button</description>
@@ -8,4 +8,4 @@
         <target>lightningCommunity__Default</target>
         <target>lightningCommunity__Page</target>
     </targets>
-</LightningComponentBundle>
+</LightningComponentBundle>

examples/shopping-cart/lwc/checkoutButton/states/loading.html

@@ -1,5 +1,5 @@
 <template>
-    <div class="mx-auto max-w-4xl pb-16">
-        <c-stencil height="50"></c-stencil>
-    </div>
-</template>
+  <div class="mx-auto max-w-4xl pb-16">
+    <c-stencil height="50"></c-stencil>
+  </div>
+</template>

examples/shopping-cart/lwc/checkoutButton/states/ready.html

@@ -1,24 +1,23 @@
 <template>
-    <div class="mx-auto max-w-4xl pb-16">
-        <div class="mt-10">
-            <button type="submit"
-                    disabled={isEmpty}
-                    class="w-full rounded-md border border-transparent bg-indigo-600 px-4 py-3
-                    text-base font-medium text-white shadow-sm hover:bg-indigo-700 focus:outline-none
-                    focus:ring-2 focus:ring-indigo-500 focus:ring-offset-2 focus:ring-offset-gray-50
-                    disabled:opacity-50 disabled:cursor-not-allowed">
-                Checkout
-            </button>
-        </div>
+  <div class="mx-auto max-w-4xl pb-16">
+    <div class="mt-10">
+      <button
+        type="submit"
+        disabled={isEmpty}
+        class="w-full rounded-md border border-transparent bg-indigo-600 px-4 py-3 text-base font-medium text-white shadow-sm hover:bg-indigo-700 focus:outline-none focus:ring-2 focus:ring-indigo-500 focus:ring-offset-2 focus:ring-offset-gray-50 disabled:opacity-50 disabled:cursor-not-allowed"
+      >
+        Checkout
+      </button>
+    </div>
 
-        <div class="mt-6 text-center text-sm text-gray-500">
-            <p>
-                or &nbsp;
-                <a href="#" class="font-medium text-indigo-600 hover:text-indigo-500">
-                    Continue Shopping
-                    <span aria-hidden="true"> &rarr;</span>
-                </a>
-            </p>
-        </div>
+    <div class="mt-6 text-center text-sm text-gray-500">
+      <p>
+        or &nbsp;
+        <a href="#" class="font-medium text-indigo-600 hover:text-indigo-500">
+          Continue Shopping
+          <span aria-hidden="true"> &rarr;</span>
+        </a>
+      </p>
     </div>
-</template>
+  </div>
+</template>

examples/shopping-cart/lwc/shoppingCartDetails/shoppingCartDetails.js-meta.xml

@@ -1,4 +1,4 @@
-<?xml version="1.0" encoding="UTF-8"?>
+<?xml version="1.0" encoding="UTF-8" ?>
 <LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
     <apiVersion>60.0</apiVersion>
     <description>Shopping Cart Details</description>

examples/shopping-cart/lwc/shoppingCartDetails/states/loading.html

@@ -1,6 +1,6 @@
 <!-- loading -->
 <template>
-    <div class="mx-auto max-w-4xl px-4 items-center justify-center flex">
-        <c-stencil height="419" width="864"></c-stencil>
-    </div>
+  <div class="mx-auto max-w-4xl px-4 items-center justify-center flex">
+    <c-stencil height="419" width="864"></c-stencil>
+  </div>
 </template>