@octanejs/formisch 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dominic Gannaway
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,73 @@
+# @octanejs/formisch
+
+Octane-native bindings for Formisch.
+
+This package targets Formisch `1.0.0-rc.0` and vendors its framework-selected
+core and modular methods at commit
+`4c494fd8cf105efd04a4b179e9c090595a0bf041`. It does not require React at runtime
+or in its public types.
+
+Formisch's core and method packages are workspace internals rather than
+independently installable npm dependencies. The published `@formisch/react`
+package is used only as a development-time differential oracle.
+
+The adapter preserves Formisch's programmatic `onChange` and validation-mode
+names. Native text controls use `onInput`; selects, checkboxes, and radios use
+native `onChange`.
+
+## Install
+
+```sh
+pnpm add @octanejs/formisch valibot
+```
+
+## Example
+
+```tsx
+import { Form, useField, useForm } from '@octanejs/formisch';
+import * as v from 'valibot';
+
+const schema = v.object({
+	email: v.pipe(v.string(), v.email('Enter a valid email')),
+});
+
+function EmailForm() @{
+	const form = useForm({ schema, validate: 'input' });
+	const email = useField(form, { path: ['email'] });
+
+	<Form of={form} onSubmit={async (output, event) => {
+		console.log(output.email, event);
+	}}>
+		<input
+			name={email.props.name}
+			ref={email.props.ref}
+			value={email.input as string}
+			onInput={email.props.onInput}
+			onBlur={email.props.onBlur}
+		/>
+		@if (email.errors) {
+			<p>{email.errors[0]}</p>
+		}
+		<button type="submit">Submit</button>
+	</Form>
+}
+```
+
+`useField` also exposes `props.onChange` for native select, checkbox, and radio
+controls. Its programmatic `field.onChange(value)` callback keeps Formisch's
+upstream name and triggers input/change validation.
+
+All Formisch modular methods—including `getInput`, `setInput`, `validate`,
+`handleSubmit`, `reset`, and field-array operations—are exported from the package
+root.
+
+## Compatibility
+
+- Upstream: `@formisch/react@1.0.0-rc.0`
+- Valibot: `^1.4.1`
+- Octane: exact workspace peer during development
+- React and React types: development-only differential oracle; neither is a
+  runtime or public-type dependency
+
+See [UPSTREAM.md](./UPSTREAM.md) for source provenance and `status.json` for the
+current divergence ledger.

package/UPSTREAM.md

@@ -0,0 +1,95 @@
+# Upstream provenance and parity crosswalk
+
+- Repository: https://github.com/open-circle/formisch
+- Package: `@formisch/react@1.0.0-rc.0`
+- Tag commit: `4c494fd8cf105efd04a4b179e9c090595a0bf041`
+- Advertised compatibility: exactly `1.0.0-rc.0`
+- React oracle: `@formisch/react@1.0.0-rc.0`, React 19.2.7
+- Schema peer: Valibot `^1.4.1`
+- License: MIT
+
+The byte-exact upstream source, tests, package metadata, and licenses are kept
+under `upstream/frameworks/react`, `upstream/packages/core`, and
+`upstream/packages/methods`. Those files are development evidence and are not
+published by `@octanejs/formisch`.
+
+The npm package contains only compiled output. The canonical repository at the
+pinned commit supplies the source and test boundaries. `src/core` and
+`src/methods` mirror the React-selected core and methods modules because neither
+workspace package is published independently at this release. The React adapter
+is re-authored with Octane hooks and `.tsrx` components.
+
+## Public export crosswalk
+
+| Upstream export | Disposition | Evidence |
+| --- | --- | --- |
+| `Field`, `FieldProps`, `FieldStore`, `FieldElementProps` | Ported | `src/components/Field/Field.tsrx`, `src/hooks/useField/useField.ts`; form, hydration, and public-type tests |
+| `FieldArray`, `FieldArrayProps`, `FieldArrayStore` | Ported | `src/components/FieldArray/FieldArray.tsrx`, `src/hooks/useFieldArray/useFieldArray.ts`; form and public-type tests |
+| `Form`, `FormProps`, `FormStore` | Ported | `src/components/Form/Form.tsrx`, `src/hooks/useForm/useForm.ts`; form, SSR, hydration, and public-type tests |
+| `UseFieldConfig`, `useField` | Ported | `src/hooks/useField/useField.ts`; form, differential, hydration, and public-type tests |
+| `UseFieldArrayConfig`, `useFieldArray` | Ported | `src/hooks/useFieldArray/useFieldArray.ts`; form and public-type tests |
+| `useForm` | Ported | `src/hooks/useForm/useForm.ts`; form, differential, SSR, hydration, and public-type tests |
+| `DeepPartial`, `FieldElement`, `FormConfig`, `FormSchema`, `PartialValues`, `PathValue`, `RequiredPath`, `Schema`, `SubmitEventHandler`, `SubmitHandler`, `ValidArrayPath`, `ValidPath`, `ValidationMode` | Reused from the pinned core | `src/core/types`; `typetests/public-api.test-d.ts` |
+| `DeepErrorEntry`, `FocusFieldConfig`, `GetFieldDeepErrorEntriesConfig`, `GetFormDeepErrorEntriesConfig`, `focus`, `getDeepErrorEntries` | Reused from pinned methods | `src/methods/focus`, `src/methods/getDeepErrorEntries`; export test |
+| `GetFieldDeepErrorsConfig`, `GetFormDeepErrorsConfig`, `getDeepErrors` | Reused from pinned methods | `src/methods/getDeepErrors`; export test |
+| `GetFieldDirtyInputConfig`, `GetFormDirtyInputConfig`, `getDirtyInput` | Reused from pinned methods | `src/methods/getDirtyInput`; export test |
+| `GetFieldDirtyPathsConfig`, `GetFormDirtyPathsConfig`, `getDirtyPaths` | Reused from pinned methods | `src/methods/getDirtyPaths`; export test |
+| `GetFieldErrorsConfig`, `GetFormErrorsConfig`, `getErrors` | Reused from pinned methods | `src/methods/getErrors`; export test |
+| `GetFieldInputConfig`, `GetFormInputConfig`, `getInput` | Reused from pinned methods | `src/methods/getInput`; export test |
+| `handleSubmit` | Reused from the React-selected pinned method | `src/methods/handleSubmit`; form test |
+| `InsertConfig`, `insert` | Reused from pinned methods | `src/methods/insert`; form and methods-engine tests |
+| `IsFieldDirtyConfig`, `IsFormDirtyConfig`, `isDirty` | Reused from pinned methods | `src/methods/isDirty`; export test |
+| `IsFieldEditedConfig`, `IsFormEditedConfig`, `isEdited` | Reused from pinned methods | `src/methods/isEdited`; export test |
+| `IsFieldTouchedConfig`, `IsFormTouchedConfig`, `isTouched` | Reused from pinned methods | `src/methods/isTouched`; export test |
+| `IsFieldValidConfig`, `IsFormValidConfig`, `isValid` | Reused from pinned methods | `src/methods/isValid`; export test |
+| `MoveConfig`, `move` | Reused from pinned methods | `src/methods/move`; methods-engine test |
+| `PickDirtyConfig`, `pickDirty` | Reused from pinned methods | `src/methods/pickDirty`; export test |
+| `RemoveConfig`, `remove` | Reused from pinned methods | `src/methods/remove`; methods-engine test and playground |
+| `ReplaceConfig`, `replace` | Reused from pinned methods | `src/methods/replace`; methods-engine test |
+| `ResetFieldConfig`, `ResetFormConfig`, `reset` | Reused from pinned methods | `src/methods/reset`; form and methods-engine tests |
+| `SetFieldErrorsConfig`, `SetFormErrorsConfig`, `setErrors` | Reused from pinned methods | `src/methods/setErrors`; export test |
+| `SetFieldInputConfig`, `SetFormInputConfig`, `setInput` | Reused from pinned methods | `src/methods/setInput`; methods-engine test |
+| `submit` | Reused from pinned methods | `src/methods/submit`; export test |
+| `SwapConfig`, `swap` | Reused from pinned methods | `src/methods/swap`; methods-engine test |
+| `ValidateFormConfig`, `validate` | Reused from pinned methods | `src/methods/validate`; export test |
+
+## Intentional divergences
+
+- Text controls expose native `onInput` for per-edit updates. Selects,
+  checkboxes, and radios retain native `onChange`.
+- React synthetic event and renderable types become native DOM events and
+  `OctaneNode`.
+- React StrictMode's delayed signal cleanup does not apply because Octane does
+  not double-invoke components in StrictMode.
+
+## Upstream test disposition
+
+The pinned repository has 56 runtime/type test artifacts: 10 in the React
+adapter, 21 in core, and 25 in methods. Every artifact now has an executable
+disposition:
+
+- All 18 core runtime files (302 cases) and all 23 methods runtime files (205
+  cases) run byte-exact against the pinned implementation and again unchanged
+  against the Octane-selected source.
+- All seven React runtime files run byte-exact against React (42 cases) and have
+  one-for-one `.tsrx` adaptations with the same 42 case identities. The
+  StrictMode replay case remains executable as the declared
+  `formisch-no-strictmode-replay` divergence.
+- All eight upstream type-test files run in pristine `tsc` lanes and in
+  one-for-one adapted `tsrx-tsc` lanes. The committed inventories cover 164
+  test groups and 217 assertions (381 hashed groups in total).
+- The pristine React type overlay keeps the three upstream test files
+  byte-exact and supplies only adjacent declaration shims for Formisch's
+  build-time framework selector. Overlay byte drift is a failing negative
+  control.
+
+`audit/react-parity.json` registers all ten required runtime and type lanes, including a port-only resolver canary.
+`audit/type-parity.json` records the allowed import-only type transformations,
+and `audit/test-classifications.json` classifies every port-authored test.
+Negative controls reject missing, renamed, skipped, or structurally changed
+runtime/type evidence.
+
+Additional Octane evidence remains deliberately separate from the upstream
+claim: `tests/differential/parity.test.ts` is React/Octane differential
+coverage; conformance, hydration, and SSR files are Octane-only framework or
+divergence contracts.

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@octanejs/formisch",
+  "version": "0.0.1",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=22.22.2"
+  },
+  "octane": {
+    "hookSlots": {
+      "manual": [
+        "src"
+      ]
+    }
+  },
+  "description": "Formisch bindings for Octane, with a vendored React-free Formisch core and modular methods.",
+  "author": {
+    "name": "Dominic Gannaway",
+    "email": "dg@domgan.com"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/octanejs/octane.git",
+    "directory": "packages/formisch"
+  },
+  "main": "src/index.ts",
+  "module": "src/index.ts",
+  "types": "src/index.ts",
+  "files": [
+    "src",
+    "README.md",
+    "UPSTREAM.md"
+  ],
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "peerDependencies": {
+    "valibot": "^1.4.1",
+    "octane": "0.1.46"
+  },
+  "devDependencies": {
+    "@formisch/react": "1.0.0-rc.0",
+    "@testing-library/dom": "^10.4.1",
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "16.3.2",
+    "@testing-library/user-event": "^14.6.1",
+    "@tsrx/react": "^0.2.61",
+    "@types/react": "^19.2.17",
+    "@types/react-dom": "^19.2.3",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7",
+    "valibot": "^1.4.1",
+    "vitest": "^4.1.10",
+    "@octanejs/testing-library": "0.1.43",
+    "octane": "0.1.46"
+  },
+  "scripts": {
+    "test": "vitest run --root ../.. --project formisch",
+    "test:parity": "node ../../scripts/react-parity/formisch-check.mjs",
+    "typecheck": "tsrx-tsc --noEmit -p tsconfig.json && tsrx-tsc --noEmit -p typetests/tsconfig.json"
+  }
+}

package/src/components/Field/Field.tsrx

@@ -0,0 +1,22 @@
+import type { FormSchema, RequiredPath, ValidPath } from '../../core/index.ts';
+import type { FieldStore, FormStore } from '../../types/index.ts';
+import { useField } from '../../hooks/useField/useField.ts';
+import type { OctaneNode } from 'octane';
+import type * as v from 'valibot';
+
+export interface FieldProps<
+	TSchema extends FormSchema = FormSchema,
+	TFieldPath extends RequiredPath = RequiredPath,
+> {
+	readonly of: FormStore<TSchema>;
+	readonly path: ValidPath<v.InferInput<TSchema>, TFieldPath>;
+	readonly children: (store: FieldStore<TSchema, TFieldPath>) => OctaneNode;
+}
+
+export function Field<TSchema extends FormSchema, TFieldPath extends RequiredPath>({
+	of,
+	path,
+	children,
+}: FieldProps<TSchema, TFieldPath>): OctaneNode {
+	return children(useField(of, { path }));
+}

package/src/components/Field/Field.tsrx.d.ts

@@ -0,0 +1,17 @@
+import type { FormSchema, RequiredPath, ValidPath } from '../../core/index.ts';
+import type { FieldStore, FormStore } from '../../types/index.ts';
+import type { OctaneNode } from 'octane';
+import type * as v from 'valibot';
+
+export interface FieldProps<
+	TSchema extends FormSchema = FormSchema,
+	TFieldPath extends RequiredPath = RequiredPath,
+> {
+	readonly of: FormStore<TSchema>;
+	readonly path: ValidPath<v.InferInput<TSchema>, TFieldPath>;
+	readonly children: (store: FieldStore<TSchema, TFieldPath>) => OctaneNode;
+}
+
+export declare function Field<TSchema extends FormSchema, TFieldPath extends RequiredPath>(
+	props: FieldProps<TSchema, TFieldPath>,
+): OctaneNode;

package/src/components/Field/index.ts

@@ -0,0 +1 @@
+export * from './Field.tsrx';

package/src/components/FieldArray/FieldArray.tsrx

@@ -0,0 +1,22 @@
+import type { FormSchema, RequiredPath, ValidArrayPath } from '../../core/index.ts';
+import type { FieldArrayStore, FormStore } from '../../types/index.ts';
+import { useFieldArray } from '../../hooks/useFieldArray/useFieldArray.ts';
+import type { OctaneNode } from 'octane';
+import type * as v from 'valibot';
+
+export interface FieldArrayProps<
+	TSchema extends FormSchema = FormSchema,
+	TFieldArrayPath extends RequiredPath = RequiredPath,
+> {
+	readonly of: FormStore<TSchema>;
+	readonly path: ValidArrayPath<v.InferInput<TSchema>, TFieldArrayPath>;
+	readonly children: (store: FieldArrayStore<TSchema, TFieldArrayPath>) => OctaneNode;
+}
+
+export function FieldArray<TSchema extends FormSchema, TFieldArrayPath extends RequiredPath>({
+	of,
+	path,
+	children,
+}: FieldArrayProps<TSchema, TFieldArrayPath>): OctaneNode {
+	return children(useFieldArray(of, { path }));
+}

package/src/components/FieldArray/FieldArray.tsrx.d.ts

@@ -0,0 +1,18 @@
+import type { FormSchema, RequiredPath, ValidArrayPath } from '../../core/index.ts';
+import type { FieldArrayStore, FormStore } from '../../types/index.ts';
+import type { OctaneNode } from 'octane';
+import type * as v from 'valibot';
+
+export interface FieldArrayProps<
+	TSchema extends FormSchema = FormSchema,
+	TFieldArrayPath extends RequiredPath = RequiredPath,
+> {
+	readonly of: FormStore<TSchema>;
+	readonly path: ValidArrayPath<v.InferInput<TSchema>, TFieldArrayPath>;
+	readonly children: (store: FieldArrayStore<TSchema, TFieldArrayPath>) => OctaneNode;
+}
+
+export declare function FieldArray<
+	TSchema extends FormSchema,
+	TFieldArrayPath extends RequiredPath,
+>(props: FieldArrayProps<TSchema, TFieldArrayPath>): OctaneNode;

package/src/components/FieldArray/index.ts

@@ -0,0 +1 @@
+export * from './FieldArray.tsrx';

package/src/components/Form/Form.tsrx

@@ -0,0 +1,28 @@
+import { type FormSchema, INTERNAL, type SubmitEventHandler } from '../../core/index.ts';
+import { handleSubmit } from '../../methods/index.ts';
+import type { FormStore } from '../../types/index.ts';
+import type { OctaneNode } from 'octane';
+import type { Octane } from 'octane/jsx-runtime';
+
+export type FormProps<TSchema extends FormSchema = FormSchema> =
+	Omit<
+		Octane.FormHTMLAttributes<HTMLFormElement>,
+		'onSubmit' | 'novalidate' | 'noValidate' | 'children'
+	> & {
+		readonly of: FormStore<TSchema>;
+		readonly onSubmit: SubmitEventHandler<TSchema>;
+		readonly children?: OctaneNode;
+	};
+
+export function Form<TSchema extends FormSchema>({ of, onSubmit, children, ...other }: FormProps<
+	TSchema
+>) @{
+	<form
+		{...other}
+		noValidate
+		ref={(element) => {
+			if (element) of[INTERNAL].element = element;
+		}}
+		onSubmit={handleSubmit(of, onSubmit)}
+	>{children}</form>
+}

package/src/components/Form/Form.tsrx.d.ts

@@ -0,0 +1,15 @@
+import type { FormSchema, SubmitEventHandler } from '../../core/index.ts';
+import type { FormStore } from '../../types/index.ts';
+import type { OctaneNode } from 'octane';
+import type { Octane } from 'octane/jsx-runtime';
+
+export type FormProps<TSchema extends FormSchema = FormSchema> = Omit<
+	Octane.FormHTMLAttributes<HTMLFormElement>,
+	'onSubmit' | 'novalidate' | 'noValidate' | 'children'
+> & {
+	readonly of: FormStore<TSchema>;
+	readonly onSubmit: SubmitEventHandler<TSchema>;
+	readonly children?: OctaneNode;
+};
+
+export declare function Form<TSchema extends FormSchema>(props: FormProps<TSchema>): OctaneNode;

package/src/components/Form/index.ts

@@ -0,0 +1 @@
+export * from './Form.tsrx';

package/src/components/index.ts

@@ -0,0 +1,3 @@
+export * from './Field/index.ts';
+export * from './FieldArray/index.ts';
+export * from './Form/index.ts';

package/src/core/array/copyItemState/copyItemState.ts

@@ -0,0 +1,101 @@
+import { initializeFieldStore } from '../../field/initializeFieldStore/index.ts';
+import { batch, untrack } from '../../framework/index.ts';
+import type { InternalFieldStore, InternalFormStore } from '../../types/index.ts';
+
+/**
+ * Copies the deeply nested state (signal values) from one field store to
+ * another. This includes the `elements`, `errors`, `startInput`, `input`,
+ * `isTouched`, `isEdited`, `isDirty`, and for arrays `startItems` and `items`
+ * properties. Recursively walks through the field stores and copies all signal
+ * values.
+ *
+ * @param internalFormStore The form store providing the empty input config.
+ * @param fromInternalFieldStore The source field store to copy from.
+ * @param toInternalFieldStore The destination field store to copy to.
+ */
+export function copyItemState(
+	internalFormStore: InternalFormStore,
+	fromInternalFieldStore: InternalFieldStore,
+	toInternalFieldStore: InternalFieldStore,
+): void {
+	// Batch all state updates for optimal reactivity performance
+	batch(() => {
+		// Untrack to avoid creating reactive dependencies during copy operation
+		untrack(() => {
+			// Copy elements reference
+			toInternalFieldStore.elements = fromInternalFieldStore.elements;
+
+			// Copy errors
+			toInternalFieldStore.errors.value = fromInternalFieldStore.errors.value;
+
+			// Copy start input
+			toInternalFieldStore.startInput.value = fromInternalFieldStore.startInput.value;
+
+			// Copy current input
+			toInternalFieldStore.input.value = fromInternalFieldStore.input.value;
+
+			// Copy touched state
+			toInternalFieldStore.isTouched.value = fromInternalFieldStore.isTouched.value;
+
+			// Copy edited state
+			toInternalFieldStore.isEdited.value = fromInternalFieldStore.isEdited.value;
+
+			// Copy dirty state
+			toInternalFieldStore.isDirty.value = fromInternalFieldStore.isDirty.value;
+
+			// If both stores are arrays, copy array-specific state
+			if (fromInternalFieldStore.kind === 'array' && toInternalFieldStore.kind === 'array') {
+				// Get source items array
+				const fromItems = fromInternalFieldStore.items.value;
+
+				// Copy start items
+				toInternalFieldStore.startItems.value = fromInternalFieldStore.startItems.value;
+
+				// Copy current items
+				toInternalFieldStore.items.value = fromItems;
+
+				// Copy state for each array item
+				for (let index = 0; index < fromItems.length; index++) {
+					// If destination child doesn't exist, initialize it
+					if (!toInternalFieldStore.children[index]) {
+						// Create empty child object
+						// @ts-expect-error
+						toInternalFieldStore.children[index] = {};
+
+						// Initialize field store for new child
+						initializeFieldStore(
+							internalFormStore,
+							toInternalFieldStore.children[index],
+							// @ts-expect-error
+							toInternalFieldStore.schema.item,
+							undefined,
+							[...toInternalFieldStore.path, index],
+						);
+					}
+
+					// Recursively copy child state
+					copyItemState(
+						internalFormStore,
+						fromInternalFieldStore.children[index],
+						toInternalFieldStore.children[index],
+					);
+				}
+
+				// Otherwise, if both stores are objects, copy object children
+			} else if (
+				fromInternalFieldStore.kind === 'object' &&
+				toInternalFieldStore.kind === 'object'
+			) {
+				// Copy state for each object property
+				for (const key in fromInternalFieldStore.children) {
+					// Recursively copy child state
+					copyItemState(
+						internalFormStore,
+						fromInternalFieldStore.children[key],
+						toInternalFieldStore.children[key],
+					);
+				}
+			}
+		});
+	});
+}

package/src/core/array/copyItemState/index.ts

@@ -0,0 +1 @@
+export * from './copyItemState.ts';

package/src/core/array/index.ts

@@ -0,0 +1,3 @@
+export * from './copyItemState/index.ts';
+export * from './resetItemState/index.ts';
+export * from './swapItemState/index.ts';

package/src/core/array/resetItemState/index.ts

@@ -0,0 +1 @@
+export * from './resetItemState.ts';