@octanejs/testing-library 0.1.50 → 0.1.52

package/README.md

@@ -10,6 +10,9 @@ npm install @octanejs/testing-library
 pnpm add @octanejs/testing-library
 ```
 
+This package peers on **Octane `^0.2.5`**. Published 0.2.4 and earlier do not export
+`isInActScope`, which both public entries import.
+
 The split mirrors RTL's own architecture (and
 `docs/react-library-compat-plan.md` §2): **`@testing-library/dom` is
 framework-agnostic and reused verbatim** — every query, `screen`, `within`,
@@ -44,6 +47,11 @@ test('increments', () => {
 - `screen`, `waitFor`, `within`, … — dom-testing-library, re-exported
 - `fireEvent` — DOM event helpers, with focus/blur pairs for delegated handlers
 
+Multiple `rerender` calls inside one `act` callback commit together when that
+callback finishes. Await `act` before asserting results that depend on promises
+or effects. Promise work settles even when timeout clocks are frozen; advance
+fake timers explicitly when the behavior itself depends on a timer.
+
 ## Octane-specific surface
 
 **Components are values in plain-`.ts` tests** — there's no JSX in a `.ts`
@@ -155,3 +163,10 @@ text commit on `tab()`, checkbox click ordering, `keyboard()`).
 Current scope, known divergences, and verification status are tracked in the
 generated [bindings status table](../../docs/bindings-status.md), sourced from
 this package's [`status.json`](./status.json).
+
+## Runtime requirement
+
+This release requires Octane 0.2.5 or later in the 0.2 line. Upgrade Octane together
+with testing-library so the `isInActScope` API used for nested `act` batching is
+available. The packed-consumer checks exercise that API and rendering inside
+an outer `act` scope.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@octanejs/testing-library",
-  "version": "0.1.50",
+  "version": "0.1.52",
   "license": "MIT",
   "type": "module",
   "engines": {
@@ -41,14 +41,16 @@
     "@testing-library/dom": "^10.4.1"
   },
   "peerDependencies": {
-    "octane": "^0.1.51 || ^0.2.0"
+    "octane": "^0.2.5 || ^0.3.0"
   },
   "devDependencies": {
     "@testing-library/user-event": "^14.6.1",
-    "react": "^19.2.7",
-    "react-dom": "^19.2.7",
+    "esbuild": "^0.28.1",
+    "react": "19.2.7",
+    "react-dom": "19.2.7",
+    "semver": "7.8.5",
     "vitest": "^4.1.10",
-    "octane": "0.2.3"
+    "octane": "0.3.0"
   },
   "scripts": {
     "test": "vitest run"

package/src/pure.ts

@@ -22,6 +22,7 @@
  */
 import {
 	act,
+	isInActScope,
 	createElement,
 	createRoot,
 	drainPassiveEffects,
@@ -33,6 +34,7 @@ import {
 	withSlot,
 	type ComponentBody,
 	type ElementDescriptor,
+	type OctaneNode,
 	type Root,
 } from 'octane';
 import {
@@ -108,6 +110,7 @@ configureDTL({
 interface RootEntry {
 	container: Element;
 	root: Root;
+	valueRoot: boolean;
 }
 const mountedContainers = new Set<Element>();
 const mountedRootEntries: RootEntry[] = [];
@@ -116,13 +119,11 @@ const mountedRootEntries: RootEntry[] = [];
 // UI normalization — octane's two authoring forms into one mountable element.
 // ─────────────────────────────────────────────────────────────────────────────
 
-/** What `render`/`rerender` accept: a component body, or a `createElement` result. */
-export type OctaneUI<P = any> = ComponentBody<P> | ElementDescriptor<P>;
+/** A component body with optional props, or any Octane renderable. */
+export type OctaneUI<P = any> = ComponentBody<P> | OctaneNode;
 
-// A root can only mount a COMPONENT. `render(createElement('div', …))` (RTL's
-// `render(<div/>)`) produces a HOST descriptor, so it is returned from a pass-
-// through component and rendered by the runtime's value-position renderer.
-function ValueRoot(props: { children: unknown }): unknown {
+// Arrays and host values share a stable value-rendering owner across rerenders.
+function ValueRoot(props: { children: OctaneNode }): OctaneNode {
 	return props.children;
 }
 
@@ -137,12 +138,12 @@ function toElement<P>(ui: OctaneUI<P>, props: P | undefined): ElementDescriptor
 		return ui;
 	}
 	if (typeof ui !== 'function') {
-		throw new Error(
-			'render/rerender expects an octane component (a function) or an element ' +
-				`descriptor from createElement(...); received ${typeof ui}.`,
-		);
+		if (props !== undefined) {
+			throw new Error('render/rerender only accepts the props option with a bare component.');
+		}
+		return createElement(ValueRoot, { children: ui });
 	}
-	return createElement(ui, props);
+	return createElement(ui as ComponentBody<P>, props);
 }
 
 function wrapUiIfNeeded(
@@ -152,8 +153,10 @@ function wrapUiIfNeeded(
 	return wrapperComponent ? createElement(wrapperComponent, { children: element }) : element;
 }
 
-function mountable(element: ElementDescriptor): ElementDescriptor {
-	return typeof element.type === 'string'
+function mountable(element: ElementDescriptor, valueRoot: boolean): ElementDescriptor {
+	// Retain one value-rendering owner when rerender moves between an array,
+	// fragment, and single element. Keyed children keep their state across them.
+	return valueRoot && element.type !== ValueRoot
 		? createElement(ValueRoot, { children: element })
 		: element;
 }
@@ -170,14 +173,21 @@ function mountable(element: ElementDescriptor): ElementDescriptor {
 // `waitFor`/`findBy*`/`act` are for, same as RTL.
 function settleSync(): void {
 	for (let i = 0; i < 50 && hasPendingWork(); i++) {
-		drainPassiveEffects();
-		flushSync(() => {});
+		// Passive effects may schedule state updates too. They belong to this
+		// testing-library commit, so keep the drain inside its synchronous scope.
+		flushSync(() => {
+			drainPassiveEffects();
+		});
 	}
 }
 
 // Commit a render synchronously — flushSync for the render itself, then the
 // cascade settle. Equivalent to RTL's `act(() => root.render(ui))` (sync form).
 function commitRender(root: Root, element: ElementDescriptor): void {
+	if (isInActScope()) {
+		root.render(element);
+		return;
+	}
 	flushSync(() => {
 		root.render(element);
 	});
@@ -242,27 +252,32 @@ export function render<P = any>(ui: OctaneUI<P>, options: RenderOptions<P> = {})
 		container = baseElement.appendChild(document.createElement('div'));
 	}
 
-	const element = mountable(wrapUiIfNeeded(toElement(ui, props), WrapperComponent));
+	const normalized = wrapUiIfNeeded(toElement(ui, props), WrapperComponent);
+	const previousEntry = mountedRootEntries.find((entry) => entry.container === container);
+	const valueRoot =
+		previousEntry?.valueRoot ??
+		(typeof normalized.type !== 'function' || normalized.type === ValueRoot);
+	const element = mountable(normalized, valueRoot);
 
 	let root: Root;
 	if (!mountedContainers.has(container)) {
 		if (hydrate) {
-			// hydrateRoot adopts the server DOM during creation (it renders once,
-			// synchronously) — only the effect settle is left to do.
-			root = hydrateRoot(container, element);
+			// Adoption queues insertion/layout effects. Commit those before the
+			// passive settle, so descendants can use callbacks installed by them.
+			root = flushSync(() => hydrateRoot(container, element));
 			settleSync();
 		} else {
 			root = createRoot(container);
 			commitRender(root, element);
 		}
-		mountedRootEntries.push({ container, root });
+		mountedRootEntries.push({ container, root, valueRoot });
 		// Track the container regardless of whether WE created it, so cleanup()
 		// handles caller-supplied containers too (RTL does the same).
 		mountedContainers.add(container);
 	} else {
 		// Same container rendered again → reuse its root (same component updates
 		// props in place; a different component tears down and remounts).
-		root = mountedRootEntries.find((entry) => entry.container === container)!.root;
+		root = previousEntry!.root;
 		commitRender(root, element);
 	}
 
@@ -290,16 +305,22 @@ export function render<P = any>(ui: OctaneUI<P>, options: RenderOptions<P> = {})
 			let element: ElementDescriptor;
 			if (rerenderUi === undefined) {
 				element = toElement(ui, props); // re-run with the original props
-			} else if (isValidElement(rerenderUi) || typeof rerenderUi === 'function') {
-				element = toElement(rerenderUi as OctaneUI, rerenderOptions?.props);
-			} else {
+			} else if (
+				rerenderUi !== null &&
+				typeof rerenderUi === 'object' &&
+				!isValidElement(rerenderUi) &&
+				!Array.isArray(rerenderUi) &&
+				Object.prototype.hasOwnProperty.call(rerenderUi, 'props')
+			) {
 				// `{ props }` shorthand: reuse the ORIGINAL component with new props.
 				const comp = isValidElement(ui) ? (ui as ElementDescriptor).type : ui;
 				element = createElement(comp as any, (rerenderUi as { props?: any }).props);
+			} else {
+				element = toElement(rerenderUi, rerenderOptions?.props);
 			}
 			// The wrapper is re-applied so component identity is stable across
 			// rerenders (same body ⇒ octane updates props in place).
-			commitRender(root, mountable(wrapUiIfNeeded(element, WrapperComponent)));
+			commitRender(root, mountable(wrapUiIfNeeded(element, WrapperComponent), valueRoot));
 		},
 		asFragment: () => document.createRange().createContextualFragment(container.innerHTML),
 		...(getQueriesForElement(baseElement, queries as any) as BoundFunctions<typeof defaultQueries>),