@octanejs/testing-library 0.1.0 → 0.1.1

package/README.md

@@ -1,7 +1,7 @@
 # @octanejs/testing-library
 
 [React Testing Library](https://testing-library.com/docs/react-testing-library/intro/)
-for the [octane](https://github.com/octanejs/octane) renderer.
+for the [octane](https://github.com/octanejs/octane) UI framework.
 
 The split mirrors RTL's own architecture (and
 `docs/react-library-compat-plan.md` §2): **`@testing-library/dom` is
@@ -43,7 +43,8 @@ file, so `render` (and `rerender`) take two forms:
 ```ts
 render(Counter, { props: { step: 2 }, wrapper: Providers }); // body + props option
 render(createElement(Counter, { step: 2 }), { wrapper: Providers }); // RTL-style element
-rerender(Counter, { step: 3 }); // rerender takes bare props as the 2nd arg
+rerender(Counter, { props: { step: 3 } }); // symmetric with render's options
+rerender({ props: { step: 3 } }); // shorthand: original component, new props
 ```
 
 Same component ⇒ props update in place; a different component tears down and
@@ -61,9 +62,11 @@ React-specific remappings:
   In octane `onChange` means the platform `change` event (fires on
   commit/blur), and `onInput` fires per keystroke — port such tests to
   `fireEvent.input` (or better, `@testing-library/user-event`, which emits
-  real event sequences). There are **no controlled components**: `value` is a
-  plain attribute and inputs are native/uncontrolled, so there's no React-style
-  value re-assertion after events.
+  real event sequences). Controlled components ARE supported (2026-07-08):
+  a `value`/`checked` prop drives the DOM property and reasserts on every
+  commit and after discrete events, exactly like React — only the synthetic
+  `onChange` normalization is absent, so a controlled text input updates its
+  state from `onInput`.
 - **No enter/leave/focus double-dispatch.** RTL's `fireEvent.mouseEnter` also
   fires `mouseover` (and `focus` fires `focusin`, `select` fires `keyup`, …)
   purely to feed React's plugin system, which listens to different native
@@ -76,11 +79,12 @@ React-specific remappings:
   drain via dom-testing-library's `eventWrapper`, so non-discrete/programmatic
   events also commit — with their `useEffect` cascades — before `fireEvent`
   returns (the equivalent of RTL's `act()` around each dispatch).
-- **Host elements at the root render between comment anchors.**
+- **Host elements at the root are `container.firstChild`, like RTL.**
   `render(createElement('div', …))` goes through octane's value-position
-  renderer, so `container.firstChild` is a comment node — use
-  `container.firstElementChild` (or just queries). Component roots
-  (`render(App, …)`) mount their template directly, no anchors.
+  renderer, which mounts a lone host element anchorless (the element
+  self-delimits, no comment markers) — so RTL's `container.firstChild` idiom
+  works as-is. Component roots (`render(App, …)`) mount their template
+  directly, also without anchors.
 - **`renderHook` and hook slots.** Octane hooks are keyed by compiler-assigned
   call-site slots. Hook callbacks written in your test files Just Work — the
   vite plugin's surgical pass slots base-hook calls in plain `.ts`, and
@@ -112,3 +116,19 @@ afterEach(cleanup);
 
 `@octanejs/testing-library/pure` skips the side effects entirely, exactly like
 `@testing-library/react/pure`.
+
+
+## `@testing-library/user-event`
+
+Works as-is — no octane adapter needed. `user-event` is framework-agnostic and
+dispatches **real native events**, which is exactly octane's event model (a
+better fit than React, where it relies on the synthetic layer picking natives
+up). Install it alongside this package and use it unchanged; the pairing is
+pinned by `tests/user-event.test.ts` (click, `type()` per-keystroke `onInput`,
+`keyboard()`).
+
+## Status
+
+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).

package/package.json

@@ -1,8 +1,15 @@
 {
   "name": "@octanejs/testing-library",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "license": "MIT",
   "type": "module",
+  "octane": {
+    "hookSlots": {
+      "manual": [
+        "src"
+      ]
+    }
+  },
   "description": "React Testing Library for the octane renderer — reuses the framework-agnostic @testing-library/dom verbatim and ports only react-testing-library's thin React layer (render/cleanup/renderHook) onto octane's createRoot + act.",
   "author": {
     "name": "Dominic Gannaway",
@@ -29,9 +36,10 @@
   },
   "dependencies": {
     "@testing-library/dom": "^10.4.1",
-    "octane": "0.1.3"
+    "octane": "0.1.4"
   },
   "devDependencies": {
+    "@testing-library/user-event": "^14.6.1",
     "vitest": "^4.1.9"
   },
   "scripts": {

package/src/pure.ts

@@ -221,8 +221,14 @@ export type RenderResult = {
 	container: HTMLElement;
 	baseElement: HTMLElement;
 	debug: DebugFn;
-	/** Re-render (same component ⇒ props update in place, like RTL's rerender). */
-	rerender: (ui: OctaneUI, props?: any) => void;
+	/**
+	 * Re-render (same component ⇒ props update in place, like RTL's rerender).
+	 * Three forms, symmetric with `render`:
+	 *   rerender(createElement(Comp, props))  — RTL-classic descriptor
+	 *   rerender(Comp, { props })             — component + options (same as render)
+	 *   rerender({ props })                   — shorthand: original component, new props
+	 */
+	rerender: (ui?: OctaneUI | { props?: any }, options?: { props?: any }) => void;
 	unmount: () => void;
 	asFragment: () => DocumentFragment;
 } & BoundFunctions<typeof defaultQueries>;
@@ -279,14 +285,25 @@ export function render<P = any>(ui: OctaneUI<P>, options: RenderOptions<P> = {})
 			flushSync(() => {
 				root.unmount();
 			});
+			// Deletion passive destroys are DEFERRED to the passive flush (React
+			// parity); RTL's unmount is act-wrapped, so it observes them flushed.
+			drainPassiveEffects();
 		},
-		rerender: (rerenderUi: OctaneUI, rerenderProps?: any) => {
+		rerender: (rerenderUi?: OctaneUI | { props?: any }, rerenderOptions?: { props?: any }) => {
+			// Normalize the three forms (see RenderResult.rerender) to one element.
+			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 {
+				// `{ 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);
+			}
 			// The wrapper is re-applied so component identity is stable across
 			// rerenders (same body ⇒ octane updates props in place).
-			commitRender(
-				root,
-				mountable(wrapUiIfNeeded(toElement(rerenderUi, rerenderProps), WrapperComponent)),
-			);
+			commitRender(root, mountable(wrapUiIfNeeded(element, WrapperComponent)));
 		},
 		asFragment: () => document.createRange().createContextualFragment(container.innerHTML),
 		...(getQueriesForElement(baseElement, queries as any) as BoundFunctions<typeof defaultQueries>),
@@ -302,6 +319,9 @@ export function cleanup(): void {
 		flushSync(() => {
 			root.unmount();
 		});
+		// See RenderResult.unmount — deletion passive destroys flush here too
+		// (RTL's auto-cleanup is act-wrapped).
+		drainPassiveEffects();
 		if (container.parentNode === document.body) {
 			document.body.removeChild(container);
 		}
@@ -378,7 +398,9 @@ export function renderHook<Result, Props = undefined>(
 	return {
 		result,
 		rerender: (rerenderCallbackProps?: Props) =>
-			baseRerender(TestComponent, { renderCallbackProps: rerenderCallbackProps as Props }),
+			baseRerender(TestComponent, {
+				props: { renderCallbackProps: rerenderCallbackProps as Props },
+			}),
 		unmount,
 	};
 }