@octanejs/hook-form 0.1.20 → 0.1.21

package/README.md

@@ -42,12 +42,26 @@ blur/commit), so the handler upstream calls `onChange` is exposed as
 - Register OPTIONS keep their upstream names: `register('x', { onChange, onBlur })`
   callbacks are invoked as before.
 
-Everything else — validation modes, `formState` proxy subscriptions,
+The remaining adapted behavior — validation modes, `formState` proxy subscriptions,
 `useFieldArray`, `useWatch`/`Watch`, `FormStateSubscribe`, `reset`/`setValue`/
 `trigger` semantics, SSR via `octane/server` — matches upstream behavior; the
-port runs react-hook-form's own ~1,200-test suite (see
-`packages/hook-form/tests/`) plus differential tests asserting byte-identical
-DOM against the real react-hook-form.
+automated parity checks run all 1,193 tests and eight snapshots unchanged
+against the pinned React package as a pristine baseline. The Octane port
+separately runs its byte-locked adapted DOM and server suites without title
+filters. Their manifests record 1,187 collected entries representing 1,178
+unique file/full-name identities and require every entry to execute and pass.
+The nine duplicate entries are repeated titles within the DOM inventory; the
+server inventory is disjoint. The structured divergence ledger in
+[`audit/react-parity.json`](./audit/react-parity.json) records the native-event,
+scheduling, render-bailout, and test-flush differences, including consumer
+impact and migration guidance. Differential tests also assert byte-identical
+DOM against the real react-hook-form. See
+[`UPSTREAM.md`](./UPSTREAM.md) for the pin,
+source inventory, export crosswalk, and test dispositions. The root Vitest
+project declares upstream and differential files as `react-parity` execution
+group ownership; the generic sharded config derives the remaining local
+conformance suite according to the
+[React parity test-execution contract](../../docs/react-parity-testing.md).
 
 ## License
 

package/UPSTREAM.md

@@ -0,0 +1,103 @@
+# react-hook-form upstream contract
+
+## Pin and source boundary
+
+| Field | Value |
+|---|---|
+| Package | `react-hook-form` |
+| Version | `7.81.0` |
+| Canonical tag commit | `46b217e034dd92f7aa3cb3a478815556b416b299` |
+| Supported upstream range | exactly `7.81.0` |
+| React oracle | `19.2.7` |
+| Canonical archive SHA-256 | `2d49ffe1a26427eb579201d574fa6a76903f8a15bae5b0bab20c434273ebc8bd` |
+| License | MIT, © Beier (Bill) Luo |
+
+The npm artifact publishes compiled `dist/` output and declarations only. The
+byte-exact source, original tests, snapshots, Jest configuration, package
+metadata, and license therefore come from the canonical repository at the tag
+commit above. They live under `upstream/`, are excluded from the published
+package, and are locked file-by-file by `upstream/SHA256SUMS`.
+
+Run `pnpm --dir packages/hook-form upstream:verify` to check the vendored bytes
+and the one-for-one adapted-suite inventory. Run
+`pnpm --dir packages/hook-form test:upstream` to execute the original React/Jest
+suite unchanged.
+
+## Runtime export crosswalk
+
+| Upstream export | Octane disposition | Evidence |
+|---|---|---|
+| `Controller` | Ported to `src/controller.tsrx` | `tests/upstream/controller.test.tsx`, `tests/upstream/useController.test.tsx` |
+| `Form` | Ported to `src/form.tsrx` | `tests/upstream/form.test.tsx` |
+| `FormProvider` | Ported to `src/FormProvider.tsrx` | `tests/upstream/useFormContext.test.tsx` |
+| `FormStateSubscribe` | Ported to `src/formStateSubscribe.tsrx` | `tests/upstream/formStateSubscribe.test.tsx` |
+| `Watch` | Ported to `src/watch.tsrx` | `tests/upstream/watch.test.tsx` |
+| `appendErrors` | Reused framework-neutral logic | `tests/upstream/logic/appendErrors.test.ts` |
+| `createFormControl` | Reused framework-neutral logic | `tests/upstream/logic/createFormControl.test.ts` |
+| `get` | Reused framework-neutral utility | `tests/upstream/utils/get.test.ts` |
+| `set` | Reused framework-neutral utility | `tests/upstream/utils/set.test.ts` |
+| `useController` | Ported to Octane hooks; `field.onInput` is the documented event divergence | `tests/upstream/useController.test.tsx` |
+| `useFieldArray` | Ported to Octane hooks | `tests/upstream/useFieldArray.test.tsx` and `tests/upstream/useFieldArray/` |
+| `useForm` | Ported to Octane hooks | `tests/upstream/useForm.test.tsx` and `tests/upstream/useForm/` |
+| `useFormContext` | Ported to Octane context | `tests/upstream/useFormContext.test.tsx` |
+| `useFormState` | Ported to Octane hooks | `tests/upstream/useFormState.test.tsx` |
+| `useWatch` | Ported to Octane hooks | `tests/upstream/useWatch.test.tsx` |
+| `types/controller` exports | Ported; event-facing controller fields expose `onInput` | `typetests/` and package typecheck |
+| `types/errors` exports | Ported at the same module path | `typetests/` and package typecheck |
+| `types/events` exports | Ported; native change events map to input events | `typetests/` and package typecheck |
+| `types/fieldArray` exports | Ported at the same module path | `typetests/` and package typecheck |
+| `types/fields` exports | Ported; event-facing fields expose `onInput` | `typetests/` and package typecheck |
+| `types/form` exports | Ported at the same module path | `typetests/` and package typecheck |
+| `types/path` exports | Ported at the same module path | `typetests/` and package typecheck |
+| `types/resolvers` exports | Ported at the same module path | `typetests/` and package typecheck |
+| `types/utils` exports | Ported at the same module path | `typetests/` and package typecheck |
+| `types/validator` exports | Ported at the same module path | `typetests/` and package typecheck |
+| `types/watch` exports | Ported at the same module path | `typetests/` and package typecheck |
+
+`tests/conformance/exports.test.ts` compares the runtime namespace to the real
+package and fails for either a missing export or an accidental extra.
+`index.react-server.ts` is not a public runtime export in Octane because Octane
+does not implement React Server Components; ordinary SSR is supported and
+covered by every adapted `*.server.test.tsx` counterpart.
+
+## Test-suite disposition
+
+The tagged repository contains 119 test artifacts: 115 test files plus four
+snapshots. Every relative path under upstream `src/__tests__/` has an adapted
+counterpart under `tests/upstream/`. The verifier extracts registrations from
+both trees and currently accounts for 1,178 upstream registrations and 1,181
+adapted registrations.
+
+The unfiltered execution inventories are a separate collection-time
+measurement. They contain 1,187 entries representing 1,178 unique
+file/full-name identities. All nine duplicate entries are repeated titles
+within the DOM inventory; the server inventory shares no file or test identity
+with it. The manifest records these measurements structurally, and validation
+recomputes them from the committed inventories.
+
+Three upstream titles are deliberately mapped to their Octane equivalents:
+
+- `field.onChange` → `field.onInput` in the controller promise case;
+- the same native-event rename in the resolver subscriber case; and
+- React's batched trigger notification case → Octane's documented commit-order
+  notification case.
+
+The adapted suite adds three Octane regression cases for registered array-valued
+dirty fields. These are explicit additions, not substitutes for upstream cases.
+There are no skipped, todo, or expected-failure cases. Any removed/renamed test
+artifact, unrecorded title change, missing extra, or vendored-byte drift fails
+`upstream:verify`.
+
+In the root Vitest project, `testExecution.group: react-parity` owns the adapted
+upstream and differential test patterns. The ordinary sharded config derives
+their complement, so the package-authored conformance cases still run without
+repeating manifest-owned parity work. This follows the repository-wide
+[React parity test-execution contract](../../docs/react-parity-testing.md); the
+workflow does not enumerate this package.
+
+The pristine lane runs all 1,193 tests and eight snapshots in the original Jest
+suite against React. Its local Jest wrapper removes only the optional
+`jest-preview` dashboard transforms/setup; test source, SWC transformation,
+environments, assertions, and snapshots remain upstream-exact. The adapted and
+differential lanes then verify the Octane port, including the native input-event
+divergence.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@octanejs/hook-form",
-  "version": "0.1.20",
+  "version": "0.1.21",
   "license": "MIT",
   "type": "module",
   "engines": {
@@ -24,27 +24,41 @@
   "types": "src/index.ts",
   "files": [
     "src",
-    "README.md"
+    "README.md",
+    "UPSTREAM.md"
   ],
   "exports": {
     ".": "./src/index.ts"
   },
   "peerDependencies": {
-    "octane": "0.1.23"
+    "octane": "0.1.24"
   },
   "devDependencies": {
+    "@swc/core": "1.15.41",
+    "@swc/jest": "0.2.39",
     "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "16.3.2",
+    "@types/react": "^19.2.17",
+    "@types/react-dom": "^19.2.3",
     "@tsrx/react": "^0.2.56",
     "esbuild": "^0.28.1",
+    "jest": "30.4.2",
+    "jest-environment-jsdom": "30.4.1",
+    "jest-fixed-jsdom": "0.0.10",
     "react": "^19.2.7",
     "react-dom": "^19.2.7",
     "react-hook-form": "7.81.0",
     "vitest": "^4.1.10",
+    "whatwg-fetch": "3.6.20",
     "zod": "^3.25.76",
-    "@octanejs/testing-library": "0.1.20",
-    "octane": "0.1.23"
+    "@octanejs/testing-library": "0.1.21",
+    "octane": "0.1.24"
   },
   "scripts": {
-    "test": "vitest run"
+    "test": "pnpm upstream:verify && pnpm test:type-parity && vitest run --root ../.. --project hook-form && vitest run --root ../.. --project hook-form-differential && vitest run --root ../.. --project hook-form-server && vitest run --root ../.. --project hook-form-pristine",
+    "test:upstream": "jest --config tests/upstream-jest.config.cjs --rootDir upstream --runInBand --no-watchman",
+    "upstream:verify": "node ../../scripts/react-parity/hook-form-upstream.mjs",
+    "test:type-parity": "node ../../scripts/react-parity/hook-form-types.mjs",
+    "typecheck": "tsrx-tsc --noEmit -p tsconfig.json && tsrx-tsc --noEmit -p typetests/tsconfig.json"
   }
 }

package/src/FormProvider.tsrx

@@ -3,9 +3,14 @@
 // methods to all children via context; the memoized value keeps context
 // identity stable across parent re-renders (same deps as upstream).
 import { useMemo } from 'octane';
+import type { Control, FieldValues, FormProviderProps, UseFormReturn } from './types';
 import { HookFormContext, HookFormControlContext } from './useFormControlContext.ts';
 
-export function FormProvider(props) @{
+export function FormProvider<
+	TFieldValues extends FieldValues,
+	TContext = any,
+	TTransformedValues = TFieldValues,
+>(props: FormProviderProps<TFieldValues, TContext, TTransformedValues>) @{
 	const {
 		children,
 		watch,
@@ -19,6 +24,7 @@ export function FormProvider(props) @{
 		formState,
 		resetField,
 		reset,
+		resetDefaultValues,
 		handleSubmit,
 		unregister,
 		control,
@@ -40,6 +46,7 @@ export function FormProvider(props) @{
 			formState,
 			resetField,
 			reset,
+			resetDefaultValues,
 			handleSubmit,
 			unregister,
 			control,
@@ -56,6 +63,7 @@ export function FormProvider(props) @{
 			handleSubmit,
 			register,
 			reset,
+			resetDefaultValues,
 			resetField,
 			setError,
 			setFocus,
@@ -68,9 +76,9 @@ export function FormProvider(props) @{
 		],
 	);
 
-	<HookFormContext.Provider value={memoizedValue}>
+	<HookFormContext.Provider value={memoizedValue as unknown as UseFormReturn}>
 		<HookFormControlContext.Provider
-			value={memoizedValue.control}
+			value={memoizedValue.control as Control}
 		>{children}</HookFormControlContext.Provider>
 	</HookFormContext.Provider>
 }

package/src/controller.tsrx

@@ -4,5 +4,12 @@
 // custom-hook call slot-wrapped by the compiler; the plain-.ts slotting pass
 // only slots BASE octane hooks (see compiler/slot-hooks.js).
 import { useController } from './useController.ts';
+import type { ControllerProps, FieldPath, FieldValues } from './types';
 
-export const Controller = (props) => props.render(useController(props));
+export const Controller = <
+	TFieldValues extends FieldValues = FieldValues,
+	TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>,
+	TTransformedValues = TFieldValues,
+>(props: ControllerProps<TFieldValues, TName, TTransformedValues>) => props.render(
+	useController<TFieldValues, TName, TTransformedValues>(props),
+);

package/src/form.tsrx

@@ -5,11 +5,14 @@
 import { useState, useCallback, useEffect } from 'octane';
 import { flatten } from './utils/flatten.ts';
 import { useFormContext } from './useFormContext.ts';
+import type { FieldValues, FormProps } from './types';
 
 const POST_REQUEST = 'post';
 
-export function Form(props) {
-	const methods = useFormContext();
+export function Form<TFieldValues extends FieldValues, TTransformedValues = TFieldValues>(
+	props: FormProps<TFieldValues, TTransformedValues>,
+) {
+	const methods = useFormContext<TFieldValues, any, TTransformedValues>();
 	const [mounted, setMounted] = useState(false);
 	const {
 		control = methods.control,
@@ -39,7 +42,7 @@ export function Form(props) {
 			} catch {
 			}
 
-			const flattenFormValues = flatten(data);
+			const flattenFormValues = flatten(data as FieldValues);
 
 			for (const key in flattenFormValues) {
 				formData.append(key, flattenFormValues[key]);
@@ -47,7 +50,7 @@ export function Form(props) {
 
 			if (onSubmit) {
 				await onSubmit({
-					data,
+					data: data as TTransformedValues,
 					event,
 					method,
 					formData,
@@ -110,7 +113,7 @@ export function Form(props) {
 
 	return <form
 		noValidate={mounted}
-		action={action}
+		action={action as string | undefined}
 		method={method}
 		encType={encType}
 		onSubmit={submit}

package/src/formStateSubscribe.tsrx

@@ -3,8 +3,21 @@
 // Authored as .tsrx (full compile) so the useFormState call is slot-wrapped
 // (see controller.tsrx note).
 import { useFormState } from './useFormState.ts';
+import type { OctaneNode } from 'octane';
+import type { FieldValues, UseFormStateProps, UseFormStateReturn } from './types';
 
-export const FormStateSubscribe = (props) => {
+export type FormStateSubscribeProps<
+	TFieldValues extends FieldValues,
+	TTransformedValues = TFieldValues,
+> =
+	UseFormStateProps<TFieldValues, TTransformedValues> & {
+		render: (values: UseFormStateReturn<TFieldValues>) => OctaneNode;
+	};
+
+export const FormStateSubscribe = <
+	TFieldValues extends FieldValues,
+	TTransformedValues = TFieldValues,
+>(props: FormStateSubscribeProps<TFieldValues, TTransformedValues>) => {
 	const { control, disabled, exact, name, render } = props;
 	return render(useFormState({ control, name, disabled, exact }));
 };

package/src/watch.tsrx

@@ -3,5 +3,23 @@
 // watched fields update. Authored as .tsrx (full compile) so the useWatch call
 // is slot-wrapped (see controller.tsrx note).
 import { useWatch } from './useWatch.ts';
+import type { FieldPath, FieldValues, WatchProps, WatchRenderValue } from './types';
 
-export const Watch = (props) => props.render(useWatch({ name: props.names, ...props }));
+export const Watch = <
+	TFieldValues extends FieldValues = FieldValues,
+	TFieldName extends | FieldPath<TFieldValues>
+	| readonly [FieldPath<TFieldValues>, ...FieldPath<TFieldValues>[]]
+	| FieldPath<TFieldValues>[]
+	| readonly FieldPath<TFieldValues>[]
+	| undefined = undefined,
+	TContext = any,
+	TTransformedValues = TFieldValues,
+	TComputeValue = undefined,
+>(props: WatchProps<TFieldName, TFieldValues, TContext, TTransformedValues, TComputeValue>) =>
+	props.render(
+		useWatch({ name: props.names, ...props as any }) as WatchRenderValue<
+			TFieldName,
+			TFieldValues,
+			TComputeValue
+		>,
+	);