cx 26.7.3 → 26.7.5

package/dist/ui.js

@@ -268,6 +268,7 @@ CSS.classPrefix = "cx";
 CSSHelper.alias("cx", CSS);
 
 let isBatching = 0;
+let updateSequence = 0;
 let promiseSubscribers = new SubscriberList();
 function batchUpdates(callback) {
 	if (VDOM$1.DOM.unstable_batchedUpdates)
@@ -284,14 +285,21 @@ function batchUpdates(callback) {
 function isBatchingUpdates() {
 	return isBatching > 0;
 }
+// Returns a sequence number identifying the update; pass it to notifyBatchedUpdateCompleted once the
+// update is rendered.
 function notifyBatchedUpdateStarting() {
+	let seq = ++updateSequence;
 	promiseSubscribers.execute((x) => {
 		x.pending++;
 	});
+	return seq;
 }
-function notifyBatchedUpdateCompleted() {
+function notifyBatchedUpdateCompleted(seq) {
 	promiseSubscribers.execute((x) => {
 		let cb = x;
+		// ignore updates that started before this subscriber attached -- counting them would let the notify
+		// callback fire before the updates the subscriber is actually waiting on are rendered
+		if (seq <= cb.watermark) return;
 		cb.finished++;
 		if (cb.finished >= cb.pending) cb.complete(true);
 	});
@@ -303,6 +311,7 @@ function batchUpdatesAndNotify(callback, notifyCallback, timeout = 1000) {
 	const update = {
 		pending: 0,
 		finished: 0,
+		watermark: updateSequence,
 		complete: (success) => {
 			if (!done) {
 				done = true;
@@ -2094,6 +2103,36 @@ class LinkedListsNode {
 	}
 }
 
+// On by default. Once a synchronous update burst grows deep, Cx starts issuing updates from microtasks
+// so React's global nested-update counter resets before continuing -- preventing "Maximum update depth
+// exceeded" on large renders that write to the store while they render (e.g. a several-hundred-page
+// report). For updates that settle in a single render -- virtually all of them -- this is equivalent to
+// rendering synchronously; it only diverges under a deep re-entrant render burst. If you suspect it
+// causes trouble, opt out at app startup with disableSyncUpdateCoalescing() -- and please report the
+// issue so it can be fixed.
+// Synchronous updates allowed within one burst before Cx switches to issuing updates from a microtask.
+// Kept under React's ~50 nested-update limit (which is global to the root, not per component); the
+// default trades a little initial-render time for a safety margin. Override via
+// enableSyncUpdateCoalescing(limit) if needed.
+const defaultSyncBurstLimit = 35;
+let syncBurstLimit = defaultSyncBurstLimit;
+// Microtask-issued updates allowed within one burst before Cx escalates to setTimeout. Deep enough that
+// only a store that never converges reaches it; timeouts let the event loop turn, so the page stays
+// responsive and batchUpdatesAndNotify fallback timers can fire instead of the tab hanging.
+let microtaskBurstLimit = 1000;
+function enableSyncUpdateCoalescing(limit) {
+	syncBurstLimit = limit ?? defaultSyncBurstLimit;
+}
+function disableSyncUpdateCoalescing() {
+	syncBurstLimit = Infinity;
+}
+// Module-global because React's nested-update limit is global to the root, not per component. The burst
+// counter resets only when all notifications settle (see completeNotification) -- tying the burst
+// window to unsettled work makes it immune to how React schedules the flushes. Legacy React chains
+// re-entrant updates synchronously within one task, but React 19 may run each round from its own
+// microtask, so no task/microtask boundary is a reliable reset point.
+let syncBurstRounds = 0; // updates issued in the current burst
+let outstandingNotifications = 0; // reported notifications not yet rendered, across all Cx instances
 class Cx extends VDOM.Component {
 	widget;
 	store;
@@ -2102,13 +2141,18 @@ class Cx extends VDOM.Component {
 	flags;
 	renderCount;
 	unsubscribe;
-	componentDidCatch;
 	forceUpdateCallback;
 	deferCounter;
 	pendingUpdateTimer;
 	unsubscribeIdleRequest;
-	// 0 when no synchronous setState is in flight; >0 while one is pending (re-entrancy guard for update())
-	stateUpdateDepth = 0;
+	// store notifications reported to batchUpdatesAndNotify subscribers but not yet rendered and completed
+	owedNotifications = new Set();
+	// setState is not allowed before the component mounts; pre-mount notifications set flags.dirty instead
+	// and componentDidMount picks them up (see update())
+	mounted = false;
+	// true once this instance has contributed to syncBurstRounds for the current render round; cleared on
+	// render, so bursts are counted per round rather than per notification (see update())
+	burstRoundCounted = false;
 	constructor(props) {
 		super(props);
 		if (props.instance) {
@@ -2134,13 +2178,11 @@ class Cx extends VDOM.Component {
 		if (props.subscribe) {
 			this.unsubscribe = this.store.subscribe(this.update.bind(this));
 		}
-		this.onStateUpdateCompleted = this.onStateUpdateCompleted.bind(this);
 		this.flags = {};
 		this.renderCount = 0;
-		if (props.onError) this.componentDidCatch = this.componentDidCatchHandler.bind(this);
 		this.forceUpdateCallback = this.forceUpdate.bind(this);
-		this.deferCounter = 0;
-		this.waitForIdle();
+		// deferredUntilIdle content stays hidden until the idle callback scheduled on mount bumps the token
+		this.deferCounter = props.deferredUntilIdle ? 1 : 0;
 	}
 	UNSAFE_componentWillReceiveProps(props) {
 		let newStore = props.instance ? props.instance.store : props.store ? props.store : props.parentInstance.store;
@@ -2170,6 +2212,10 @@ class Cx extends VDOM.Component {
 		throw new Error("Could not resolve a widget instance in the Cx component.");
 	}
 	render() {
+		this.burstRoundCounted = false;
+		// an error was captured and is being dispatched to the onError callback (see componentDidCatch);
+		// render nothing until the callback repairs the state
+		if (this.state.error) return null;
 		if (this.props.deferredUntilIdle && this.state.deferToken < this.deferCounter) return null;
 		let cultureInfo = this.props.cultureInfo ?? getCurrentCulture();
 		return jsx(CxContext, {
@@ -2183,6 +2229,10 @@ class Cx extends VDOM.Component {
 		});
 	}
 	componentDidMount() {
+		this.mounted = true;
+		// schedule the deferredUntilIdle reveal here rather than in the constructor -- the idle callback
+		// could otherwise fire before the component mounts and issue a setState React does not allow yet
+		this.waitForIdle();
 		this.componentDidUpdate();
 		if (this.props.options && this.props.options.onPipeUpdate) this.props.options.onPipeUpdate(this.update.bind(this));
 	}
@@ -2194,32 +2244,68 @@ class Cx extends VDOM.Component {
 	update() {
 		let data = this.store.getData();
 		debug(appDataFlag, data);
-		if (this.flags.preparing) this.flags.dirty = true;
-		// Synchronous path (while batching, or for `immediate` instances). At most one setState may be in flight
-		// per Cx: if one is already pending (stateUpdateDepth != 0) skip issuing another. Re-entrant setStates
-		// nested deep -- e.g. a large initial render that writes to the store while it renders -- are what trip
-		// React's "Maximum update depth exceeded"; coalescing them into a single in-flight update avoids that.
-		// The pending update's completion callback re-reads the store and renders again if it changed
-		// (see onStateUpdateCompleted), so no change is dropped.
+		if (this.flags.preparing || !this.mounted) this.flags.dirty = true;
+		// Synchronous path: while batching (incl. batchUpdatesAndNotify, which page-breaking relies on) or for
+		// `immediate` instances.
 		else if (this.props.immediate || isBatchingUpdates()) {
-			if (this.stateUpdateDepth == 0) {
-				this.stateUpdateDepth = 1;
-				notifyBatchedUpdateStarting();
-				this.setState(
-					{
-						data: data,
-					},
-					this.onStateUpdateCompleted,
-				);
+			// Every notification is reported to batchUpdatesAndNotify subscribers up front and completed only
+			// once the setState that renders it commits, so notify callbacks never fire before the DOM reflects
+			// the change. Each notification always gets its own setState; only its timing escalates as the
+			// burst grows: synchronous at first, then from a microtask (lets React's commit finish so its
+			// global nested-update counter resets instead of tripping "Maximum update depth exceeded"), and
+			// finally from a timeout (lets the event loop turn, so a store that never converges degrades to a
+			// responsive page instead of a frozen tab).
+			let seq = notifyBatchedUpdateStarting();
+			this.owedNotifications.add(seq);
+			outstandingNotifications++;
+			// Count render rounds rather than notifications: only the first notification an instance
+			// receives per render round bumps the shared depth (the flag clears on render). This tracks
+			// React's nested-commit count -- the thing the escalation must stay under -- so a round that
+			// writes many values doesn't burn through the budget in one go.
+			if (!this.burstRoundCounted) {
+				this.burstRoundCounted = true;
+				++syncBurstRounds;
+				if (process.env.NODE_ENV !== "production" && syncBurstRounds === microtaskBurstLimit + 1)
+					console.error(
+						"Cx: store updates are not converging after " +
+							microtaskBurstLimit +
+							" render rounds -- possible update loop. Updates are now issued from timeouts to keep the page responsive. Look for code that writes a new value to the store on every render.",
+					);
 			}
+			if (syncBurstRounds <= syncBurstLimit) this.issueStateUpdate(seq);
+			else if (syncBurstRounds <= microtaskBurstLimit) queueMicrotask(() => this.issueStateUpdate(seq));
+			else setTimeout(() => this.issueStateUpdate(seq), 0);
 		} else {
 			// standard mode: coalesce sequential store commands into a single deferred update
 			this.scheduleStateUpdate();
 		}
 	}
+	// Render the latest store data and report the notification completed once the commit is done, so
+	// batchUpdatesAndNotify resolves only when the DOM reflects the store.
+	issueStateUpdate(seq) {
+		// skip notifications no longer owed -- unmount may have already released them
+		if (!this.owedNotifications.has(seq)) return;
+		this.setState(
+			{
+				data: this.store.getData(),
+			},
+			() => this.completeNotification(seq),
+		);
+	}
+	completeNotification(seq) {
+		// skip notifications no longer owed -- unmount may have already released them
+		if (!this.owedNotifications.delete(seq)) return;
+		outstandingNotifications--;
+		notifyBatchedUpdateCompleted(seq);
+		// everything settled -- the next burst starts fresh, and so does React's nested-update counter
+		// (the commit that settled the last notification ends without scheduling further synchronous work)
+		if (outstandingNotifications === 0) syncBurstRounds = 0;
+	}
 	scheduleStateUpdate() {
 		if (!this.pendingUpdateTimer) {
-			notifyBatchedUpdateStarting();
+			let seq = notifyBatchedUpdateStarting();
+			this.owedNotifications.add(seq);
+			outstandingNotifications++;
 			this.pendingUpdateTimer = setTimeout(() => {
 				delete this.pendingUpdateTimer;
 				// read fresh data at fire time so the coalesced update renders the latest store state
@@ -2227,45 +2313,20 @@ class Cx extends VDOM.Component {
 					{
 						data: this.store.getData(),
 					},
-					notifyBatchedUpdateCompleted,
+					() => this.completeNotification(seq),
 				);
 			}, 0);
 		}
 	}
-	// Completion callback for the synchronous setState above. If the store changed while that update was
-	// rendering -- i.e. the render itself wrote to the store, as happens throughout a large initial render --
-	// render once more with the latest data, keeping this callback armed; otherwise the burst has settled, so
-	// clear the in-flight flag and report completion. Re-arming coalesces until the store reaches a fixpoint;
-	// a genuinely non-converging update loop is still caught by React's own max-update-depth guard.
-	onStateUpdateCompleted() {
-		let latestData = this.store.getData();
-		notifyBatchedUpdateCompleted();
-		if (this.state.data === latestData) {
-			this.stateUpdateDepth = 0;
-		} else {
-			this.stateUpdateDepth++;
-			if (this.stateUpdateDepth < 20 && isBatchingUpdates())
-				this.setState(
-					{
-						data: latestData,
-					},
-					this.onStateUpdateCompleted,
-				);
-			else this.scheduleStateUpdate();
-		}
-	}
 	waitForIdle() {
 		if (!this.props.deferredUntilIdle) return;
 		if (this.unsubscribeIdleRequest) this.unsubscribeIdleRequest();
 		let token = ++this.deferCounter;
 		this.unsubscribeIdleRequest = onIdleCallback(
 			() => {
-				this.setState(
-					{
-						deferToken: token,
-					},
-					this.onStateUpdateCompleted,
-				);
+				this.setState({
+					deferToken: token,
+				});
 			},
 			{
 				timeout: this.props.idleTimeout || 30000,
@@ -2273,6 +2334,9 @@ class Cx extends VDOM.Component {
 		);
 	}
 	componentWillUnmount() {
+		// Release notifications that will never render so a waiting batchUpdatesAndNotify can settle instead
+		// of waiting out its fallback timeout.
+		for (let seq of this.owedNotifications) this.completeNotification(seq);
 		if (this.pendingUpdateTimer) clearTimeout(this.pendingUpdateTimer);
 		if (this.unsubscribeIdleRequest) this.unsubscribeIdleRequest();
 		if (this.unsubscribe) this.unsubscribe();
@@ -2291,9 +2355,25 @@ class Cx extends VDOM.Component {
 			props.cultureInfo !== this.props.cultureInfo
 		);
 	}
-	componentDidCatchHandler(error, info) {
+	// Render null for the failed subtree while the error is dispatched to componentDidCatch below --
+	// returning a state update here is what React expects of an error boundary (rendering the broken
+	// children again would just rethrow).
+	static getDerivedStateFromError() {
+		return {
+			error: true,
+		};
+	}
+	componentDidCatch(error, info) {
 		this.flags.preparing = false;
+		// without an onError callback this instance is not an error boundary -- rethrow so the error
+		// reaches the nearest ancestor boundary, matching the behavior before getDerivedStateFromError
+		// was introduced
+		if (!this.props.onError) throw error;
 		this.props.onError(error, this.getInstance(), info);
+		// the callback had a chance to repair the state (e.g. replace the failing content) -- resume rendering
+		this.setState({
+			error: false,
+		});
 	}
 }
 class CxContext extends VDOM.Component {
@@ -4388,7 +4468,9 @@ export {
 	contentAppend,
 	createCulture,
 	createFunctionalComponent,
+	disableSyncUpdateCoalescing,
 	enableCultureSensitiveFormatting,
+	enableSyncUpdateCoalescing,
 	equal,
 	executeKeyboardShortcuts,
 	exploreChildren,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cx",
-  "version": "26.7.3",
+  "version": "26.7.5",
   "description": "Advanced JavaScript UI framework for admin and dashboard applications with ready to use grid, form and chart components.",
   "exports": {
     "./data": {

package/src/ui/Cx.spec.tsx

@@ -6,6 +6,28 @@ import { bind } from "./bind";
 import { createTestRenderer, createTestWidget, act } from "../util/test/createTestRenderer";
 import assert from "assert";
 import { HtmlElement } from "../widgets/HtmlElement";
+import { batchUpdatesAndNotify } from "./batchUpdates";
+
+// A widget that, each time it explores, bumps `n` by one until it reaches `target`. This reproduces the
+// shape of a large report's initial render: the render writes to the store, which schedules another
+// render, until the store reaches a fixpoint. It drives Cx's coalescing update path across many rounds.
+function convergingWidget(target: number) {
+   return (
+      <cx>
+         <div
+            text={bind("n")}
+            onExplore={(context: any, instance: any) => {
+               let n = instance.store.get("n");
+               if (n < target) instance.store.set("n", n + 1);
+            }}
+         />
+      </cx>
+   );
+}
+
+function renderedValue(component: any): number {
+   return Number(component.toJSON().children[0]);
+}
 
 describe("Cx", () => {
    it("can render cx content", async () => {
@@ -207,4 +229,67 @@ describe("Cx", () => {
          ["render", "0"],
       ]);
    });
+
+   // Coalescing of re-entrant synchronous updates is the default. These cover the two guarantees that
+   // matter for large, store-mutating-during-render trees (e.g. report page-breaking).
+
+   it("resolves batchUpdatesAndNotify only after the store reaches its fixpoint", async () => {
+      const TARGET = 6; // shallow, like page-breaking convergence -> stays fully synchronous under a notifier
+      let store = new Store({ data: { n: 0 } });
+      const component = await createTestRenderer(store, convergingWidget(TARGET));
+      assert.equal(renderedValue(component), TARGET);
+
+      let notifiedStoreValue = -1;
+      let notifiedRenderedValue = -1;
+      await act(async () => {
+         batchUpdatesAndNotify(
+            () => {
+               store.set("n", 0); // reset -> the render cascade re-converges back up to TARGET
+            },
+            () => {
+               notifiedStoreValue = store.get("n");
+               notifiedRenderedValue = renderedValue(component);
+            },
+         );
+      });
+
+      // The notify callback is what page-breaking relies on: it must run only once the change is fully
+      // implemented -- both the store and the rendered DOM are at the final value, never an intermediate.
+      assert.equal(notifiedStoreValue, TARGET, "notify saw a pre-fixpoint store value");
+      assert.equal(notifiedRenderedValue, TARGET, "notify fired before the DOM reflected the final value");
+   });
+
+   it("does not fire the notify callback early when an update is already in flight", async () => {
+      const TARGET = 50;
+      let store = new Store({ data: { n: 0 } });
+      const component = await createTestRenderer(store, convergingWidget(TARGET));
+      assert.equal(renderedValue(component), TARGET);
+
+      let notifiedStoreValue = -1;
+      let notifiedRenderedValue = -1;
+      await act(async () => {
+         store.set("n", 0); // puts an update in flight before the notifier below subscribes
+         batchUpdatesAndNotify(
+            () => {
+               store.set("n", 1);
+            },
+            () => {
+               notifiedStoreValue = store.get("n");
+               notifiedRenderedValue = renderedValue(component);
+            },
+         );
+      });
+
+      // The write issued inside batchUpdatesAndNotify must be rendered before the notify callback runs,
+      // even though it landed while a previous update was still converging.
+      assert.equal(notifiedStoreValue, TARGET, "notify saw a pre-fixpoint store value");
+      assert.equal(notifiedRenderedValue, TARGET, "notify fired before the DOM reflected the final value");
+   });
+
+   it("converges a deep render burst without tripping React's max-update-depth guard", async () => {
+      const TARGET = 200; // far beyond React's ~50 nested-update limit; only survives because of the yield
+      let store = new Store({ data: { n: 0 } });
+      const component = await createTestRenderer(store, convergingWidget(TARGET));
+      assert.equal(renderedValue(component), TARGET);
+   });
 });