@voltro/testing 0.51.0 → 0.53.0

package/dist/client.d.ts

@@ -1,9 +1,13 @@
 import { Effect } from 'effect';
 import { Exit } from 'effect/Exit';
+import { FieldErrors } from '@voltro/client';
+import { FormBinding } from '@voltro/client';
+import { FormStateSnapshot } from '@voltro/client';
 import { ReactElement } from 'react';
 import { ReactNode } from 'react';
 import { RunForkOptions } from 'effect/Runtime';
 import { RuntimeFiber } from 'effect/Fiber';
+import { UseFormBindingOptions } from '@voltro/client';
 
 /**
  * The runtime the hooks get. EXPORTED so it can be guarded.
@@ -33,6 +37,23 @@ export declare const FAKE_RUNTIME: {
     dispose: () => Effect.Effect<void, never, never>;
 };
 
+export declare interface FormBindingHarness<Input extends Record<string, unknown>, Output> {
+    /** The live binding, as of the latest render. */
+    readonly binding: () => FormBinding<Input, Output>;
+    /** Set one field (dotted paths reach nested values), wrapped in `act`. */
+    readonly fill: (path: string, value: unknown) => void;
+    /** Blur one field — what reveals its error under the default timing. */
+    readonly blur: (path: string) => void;
+    /** Submit; resolves the output or `undefined` when blocked. */
+    readonly submit: () => Promise<Output | undefined>;
+    /** The VISIBLE errors right now. */
+    readonly errors: () => FieldErrors;
+    readonly state: () => FormStateSnapshot;
+    /** The underlying fake api — recorded `calls`, `setSubscription`, … */
+    readonly client: VoltroTestClient;
+    readonly unmount: () => void;
+}
+
 declare type Handler = (input: never) => unknown;
 
 export declare const makeVoltroTestClient: (config?: VoltroTestClientConfig) => VoltroTestClient;
@@ -44,6 +65,40 @@ export declare interface RecordedCall {
     readonly input: unknown;
 }
 
+/**
+ * Render `useFormBinding` against a fake api and hand back form-shaped
+ * controls:
+ *
+ *     const form = await renderFormBinding('users.create', {
+ *       binding: { schema: UsersCreateInput },
+ *       mutation: (input) => {
+ *         if ((input as { email: string }).email === 'taken@x.io') {
+ *           throw new ValidationError({ field: 'email', message: 'validation.emailTaken' })
+ *         }
+ *         return { id: 'user_1' }
+ *       },
+ *     })
+ *     form.fill('email', 'taken@x.io')
+ *     await form.submit()
+ *     expect(form.errors()['email']).toBe('validation.emailTaken')
+ */
+export declare const renderFormBinding: <Input extends Record<string, unknown> = Record<string, unknown>, Output = unknown>(tag: string, options?: RenderFormBindingOptions<Input>) => Promise<FormBindingHarness<Input, Output>>;
+
+export declare interface RenderFormBindingOptions<Input extends Record<string, unknown>> {
+    /** The api name the binding asks for. Default `'app'`. */
+    readonly apiName?: string;
+    /** The mutation handler for THIS tag. Return the output; throw a
+     *  `ValidationError` / `ValidationErrors` to exercise server field-error
+     *  routing; throw anything else for the loud-failure path. Default: echo
+     *  `{ ok: true }`. */
+    readonly mutation?: (input: unknown) => unknown | Promise<unknown>;
+    /** Extra fake-api config (other mutations, subscriptions, actions). */
+    readonly client?: Omit<VoltroTestClientConfig, 'apiName'>;
+    /** Options for the binding itself — `schema` is usually the one you want
+     *  (the fake api carries no descriptors). */
+    readonly binding?: UseFormBindingOptions<Input>;
+}
+
 /**
  * The parts of a snapshot that are NOT the data.
  *

package/dist/client.js

@@ -1,22 +1,61 @@
 import { Effect as e } from "effect";
-import { createElement as t } from "react";
-import { FrameworkRuntimesContext as n, RpcErrorBus as r } from "@voltro/client";
-//#region src/client.tsx
-var i = {
+import { act as t, createElement as n } from "react";
+import { FrameworkRuntimesContext as r, RpcErrorBus as i, useFormBinding as a } from "@voltro/client";
+//#region src/formBindingHarness.tsx
+var o = async (e, r = {}) => {
+	if (globalThis.document === void 0) throw Error("renderFormBinding needs a DOM to render hooks — add `// @vitest-environment jsdom` to the spec.");
+	let { createRoot: i } = await import("react-dom/client"), o = r.apiName ?? "app", s = c({
+		apiName: o,
+		...r.client ?? {},
+		mutations: {
+			[e]: r.mutation ?? (() => ({ ok: !0 })),
+			...r.client?.mutations ?? {}
+		}
+	}), l, u = () => (l = a(o, e, r.binding ?? {}), null), d = i(globalThis.document.createElement("div"));
+	return await t(async () => {
+		d.render(n(s.Provider, null, n(u)));
+	}), {
+		binding: () => l,
+		fill: (e, n) => {
+			t(() => {
+				l.field(e).setValue(n);
+			});
+		},
+		blur: (e) => {
+			t(() => {
+				l.field(e).onBlur();
+			});
+		},
+		submit: async () => {
+			let e;
+			return await t(async () => {
+				e = await l.submit();
+			}), e;
+		},
+		errors: () => l.errors,
+		state: () => l.state,
+		client: s,
+		unmount: () => {
+			t(() => {
+				d.unmount();
+			});
+		}
+	};
+}, s = {
 	runPromise: e.runPromise,
 	runPromiseExit: e.runPromiseExit,
 	runFork: e.runFork,
 	dispose: () => e.void
-}, a = (a = {}) => {
-	let o = a.apiName ?? "app", s = /* @__PURE__ */ new Map(), c = /* @__PURE__ */ new Map(), l = /* @__PURE__ */ new Map(), u = [];
-	for (let [e, t] of Object.entries(a.subscriptions ?? {})) s.set(e, {
-		data: t,
+}, c = (t = {}) => {
+	let a = t.apiName ?? "app", o = /* @__PURE__ */ new Map(), c = /* @__PURE__ */ new Map(), l = /* @__PURE__ */ new Map(), u = [];
+	for (let [e, n] of Object.entries(t.subscriptions ?? {})) o.set(e, {
+		data: n,
 		error: void 0,
 		revision: 0,
 		pendingPatches: 0,
 		emittedAt: void 0
 	});
-	let d = (e) => s.get(e) ?? {
+	let d = (e) => o.get(e) ?? {
 		data: void 0,
 		error: void 0,
 		revision: -1,
@@ -62,27 +101,27 @@ var i = {
 			catch: (e) => e
 		});
 	};
-	for (let [e, t] of Object.entries(a.mutations ?? {})) g(e, "mutation", t);
-	for (let [e, t] of Object.entries(a.actions ?? {})) g(e, "action", t);
+	for (let [e, n] of Object.entries(t.mutations ?? {})) g(e, "mutation", n);
+	for (let [e, n] of Object.entries(t.actions ?? {})) g(e, "action", n);
 	let _ = {
-		runtime: i,
+		runtime: s,
 		cache: m,
 		client: h,
 		descriptors: {},
 		inspectBaseUrl: "http://test.local",
-		errorBus: new r()
+		errorBus: new i()
 	}, v = {
 		get: (e) => {
-			if (e !== o) throw Error(`makeVoltroTestClient: component asked for api '${e}' but the harness was built for '${o}'. Pass { apiName: '${e}' }.`);
+			if (e !== a) throw Error(`makeVoltroTestClient: component asked for api '${e}' but the harness was built for '${a}'. Pass { apiName: '${e}' }.`);
 			return _;
 		},
-		names: [o]
+		names: [a]
 	};
 	return {
-		Provider: ({ children: e }) => t(n.Provider, { value: v }, e),
+		Provider: ({ children: e }) => n(r.Provider, { value: v }, e),
 		setSubscription: (e, t, n) => {
 			let r = d(e);
-			s.set(e, {
+			o.set(e, {
 				data: t,
 				error: void 0,
 				revision: r.revision + 1,
@@ -91,7 +130,7 @@ var i = {
 			}), f(e);
 		},
 		failSubscription: (e, t) => {
-			s.set(e, {
+			o.set(e, {
 				data: void 0,
 				error: t,
 				revision: -1,
@@ -100,10 +139,10 @@ var i = {
 			}), f(e);
 		},
 		resetSubscription: (e) => {
-			s.delete(e), f(e);
+			o.delete(e), f(e);
 		},
 		calls: u
 	};
 };
 //#endregion
-export { i as FAKE_RUNTIME, a as makeVoltroTestClient };
+export { s as FAKE_RUNTIME, c as makeVoltroTestClient, o as renderFormBinding };