v0.17.0

CuboMX Release: Asynchronous DOM & Enhanced Lifecycles

This release marks a significant step forward in the maturity and predictability of the CuboMX framework. The highlight is a major architectural shift to an asynchronous model for DOM manipulations, making your components more robust and easier to reason about. We've also introduced a new lifecycle hook to enhance global state awareness.

---

💥 Breaking Changes

ArrayItems Methods are Now Asynchronous

To eliminate race conditions and ensure the DOM is fully updated and hydrated before your code proceeds, all methods on ArrayItems proxies (from mx-item) that manipulate the DOM now return a Promise.

What this means: You must now use await when calling methods that add, remove, or replace items in a list.

Why this is better: When the Promise resolves, you are guaranteed that the new element is fully hydrated and reactive. This makes your code more predictable and eliminates an entire class of bugs related to timing.

Migration Guide:

Simply add await to your ArrayItems method calls.

Old (Synchronous) Code:

// This no longer works as expected
myComponent.items.add({ name: "New Item" });
// The next line might execute before the new item is in the DOM and reactive

New (Asynchronous) Code:

// Use await to ensure the operation is complete
const newItemProxy = await myComponent.items.add({ name: "New Item" });
// You can now safely interact with newItemProxy, it's fully hydrated!

Affected Methods:

• add() / push()
• prepend() / unshift()
• delete()
• remove()
• pop()
• shift()
• clear()
• replace()

---

✨ New Features

New Lifecycle Hook: onDOMUpdate()

We've introduced a new lifecycle hook that allows components and stores to react to global DOM changes.

The onDOMUpdate() method is called on all active components and stores whenever a new component is initialized anywhere in the DOM (e.g., via items.add() or CuboMX.swap()).

This is perfect for:

• Recalculating layouts or element positions when new content appears.
• Notifying a global store about structural changes in the application.
• Updating UI counters or indicators that depend on the number of components on the page.

Example:

CuboMX.store("navigation", {
    componentCount: 0,
    onDOMUpdate() {
        // This will run every time a new component is added to the page
        this.componentCount = document.querySelectorAll("[mx-data]").length;
        console.log(`Total active components: ${this.componentCount}`);
    },
});

Note: This hook is not called when components are removed from the DOM. Use the destroy() hook for cleanup logic.

---

🛠️ Improvements & Bug Fixes

Improved mx-item Hydration Order

The initial hydration logic for mx-item has been improved. When CuboMX initializes on a list of items rendered by the server, it now guarantees that the order of items in the JavaScript array perfectly matches their order in the DOM.

This fixes potential bugs where the array order could diverge from the visual order during the initial page load.