@lucas-barake/effect-form-react 0.11.0 → 0.13.0

package/src/FormReact.tsx

@@ -1,12 +1,21 @@
-import { RegistryContext, useAtom, useAtomSet, useAtomSubscribe, useAtomValue } from "@effect-atom/atom-react"
-import type * as Atom from "@effect-atom/atom/Atom"
+import {
+  RegistryContext,
+  useAtom,
+  useAtomMount,
+  useAtomSet,
+  useAtomSubscribe,
+  useAtomValue,
+} from "@effect-atom/atom-react"
+import * as Atom from "@effect-atom/atom/Atom"
 import { Field, FormAtoms, Mode, Validation } from "@lucas-barake/effect-form"
 import type * as FormBuilder from "@lucas-barake/effect-form/FormBuilder"
-import { getNestedValue, isPathOrParentDirty, isPathUnderRoot } from "@lucas-barake/effect-form/Path"
+import { getNestedValue, isPathOrParentDirty } from "@lucas-barake/effect-form/Path"
 import * as Cause from "effect/Cause"
 import type * as Effect from "effect/Effect"
+import * as Layer from "effect/Layer"
 import * as Option from "effect/Option"
 import * as ParseResult from "effect/ParseResult"
+import * as Predicate from "effect/Predicate"
 import type * as Schema from "effect/Schema"
 import * as AST from "effect/SchemaAST"
 import * as React from "react"
@@ -42,12 +51,32 @@ export interface FieldComponentProps<
   readonly props: P
 }
 
+/**
+ * A bundled field definition + component for reusable form fields.
+ * Created with `FormReact.makeField`.
+ *
+ * @category Models
+ */
+export interface FieldBundle<
+  K extends string,
+  S extends Schema.Schema.Any,
+  P extends Record<string, unknown> = Record<string, never>,
+> {
+  readonly _tag: "FieldBundle"
+  readonly field: Field.FieldDef<K, S>
+  readonly component: React.FC<FieldComponentProps<S, P>>
+}
+
+const isFieldBundle = (x: unknown): x is FieldBundle<string, Schema.Schema.Any, Record<string, unknown>> =>
+  Predicate.isTagged(x, "FieldBundle")
+
 /**
  * Extracts the extra props type from a field component.
  *
  * @category Type-level utilities
  */
 export type ExtractExtraProps<C> = C extends React.FC<FieldComponentProps<any, infer P>> ? P
+  : C extends FieldBundle<any, any, infer P> ? P
   : Record<string, never>
 
 /**
@@ -69,7 +98,8 @@ export type ArrayItemComponentMap<S extends Schema.Schema.Any> = S extends Schem
  * @category Models
  */
 export type FieldComponentMap<TFields extends Field.FieldsRecord> = {
-  readonly [K in keyof TFields]: TFields[K] extends Field.FieldDef<any, infer S> ? React.FC<FieldComponentProps<S, any>>
+  readonly [K in keyof TFields]: TFields[K] extends Field.FieldDef<any, infer S>
+    ? React.FC<FieldComponentProps<S, any>> | FieldBundle<any, S, any>
     : TFields[K] extends Field.ArrayFieldDef<any, infer S> ? ArrayItemComponentMap<S>
     : never
 }
@@ -108,7 +138,6 @@ export type BuiltForm<
   SubmitArgs = void,
   CM extends FieldComponentMap<TFields> = FieldComponentMap<TFields>,
 > = {
-  // Atoms for fine-grained subscriptions (use with useAtomValue)
   readonly values: Atom.Atom<Option.Option<Field.EncodedFromFields<TFields>>>
   readonly isDirty: Atom.Atom<boolean>
   readonly hasChangedSinceSubmit: Atom.Atom<boolean>
@@ -128,7 +157,10 @@ export type BuiltForm<
   readonly revertToLastSubmit: Atom.Writable<void, void>
   readonly setValues: Atom.Writable<void, Field.EncodedFromFields<TFields>>
   readonly setValue: <S>(field: FormBuilder.FieldRef<S>) => Atom.Writable<void, S | ((prev: S) => S)>
-  readonly getFieldAtom: <S>(field: FormBuilder.FieldRef<S>) => Atom.Atom<S>
+  readonly getFieldAtom: <S>(field: FormBuilder.FieldRef<S>) => Atom.Atom<Option.Option<S>>
+
+  readonly mount: Atom.Atom<void>
+  readonly KeepAlive: React.FC
 } & FieldComponents<TFields, CM>
 
 type FieldComponents<TFields extends Field.FieldsRecord, CM extends FieldComponentMap<TFields>> = {
@@ -171,7 +203,7 @@ const AutoSubmitContext = createContext<(() => void) | null>(null)
 const makeFieldComponent = <S extends Schema.Schema.Any, P extends Record<string, unknown>>(
   fieldKey: string,
   fieldDef: Field.FieldDef<string, S>,
-  crossFieldErrorsAtom: Atom.Writable<Map<string, string>, Map<string, string>>,
+  errorsAtom: Atom.Writable<Map<string, Validation.ErrorEntry>, Map<string, Validation.ErrorEntry>>,
   submitCountAtom: Atom.Atom<number>,
   dirtyFieldsAtom: Atom.Atom<ReadonlySet<string>>,
   parsedMode: Mode.ParsedMode,
@@ -187,15 +219,14 @@ const makeFieldComponent = <S extends Schema.Schema.Any, P extends Record<string
     const autoSubmitOnBlur = useContext(AutoSubmitContext)
     const fieldPath = arrayCtx ? `${arrayCtx.parentPath}.${fieldKey}` : fieldKey
 
-    const { crossFieldErrorAtom, touchedAtom, valueAtom } = React.useMemo(
+    const { errorAtom, touchedAtom, valueAtom } = React.useMemo(
       () => getOrCreateFieldAtoms(fieldPath),
       [fieldPath],
     )
 
     const [value, setValue] = useAtom(valueAtom) as [Schema.Schema.Encoded<S>, (v: unknown) => void]
     const [isTouched, setTouched] = useAtom(touchedAtom)
-    const crossFieldError = useAtomValue(crossFieldErrorAtom)
-    const setCrossFieldErrors = useAtomSet(crossFieldErrorsAtom)
+    const storedError = useAtomValue(errorAtom)
     const submitCount = useAtomValue(submitCountAtom)
 
     const validationAtom = React.useMemo(
@@ -219,13 +250,14 @@ const makeFieldComponent = <S extends Schema.Schema.Any, P extends Record<string
 
       const shouldValidate = parsedMode.validation === "onChange"
         || (parsedMode.validation === "onBlur" && isTouched)
+        || (parsedMode.validation === "onSubmit" && submitCount > 0)
 
       if (shouldValidate) {
         validate(value)
       }
-    }, [value, isTouched, validate])
+    }, [value, isTouched, submitCount, validate])
 
-    const perFieldError: Option.Option<string> = React.useMemo(() => {
+    const livePerFieldError: Option.Option<string> = React.useMemo(() => {
       if (validationResult._tag === "Failure") {
         const parseError = Cause.failureOption(validationResult.cause)
         if (Option.isSome(parseError) && ParseResult.isParseError(parseError.value)) {
@@ -235,25 +267,33 @@ const makeFieldComponent = <S extends Schema.Schema.Any, P extends Record<string
       return Option.none()
     }, [validationResult])
 
-    const validationError = Option.isSome(perFieldError) ? perFieldError : crossFieldError
+    const isValidating = validationResult.waiting
+
+    const validationError: Option.Option<string> = React.useMemo(() => {
+      if (Option.isSome(livePerFieldError)) {
+        return livePerFieldError
+      }
+
+      if (Option.isSome(storedError)) {
+        // Hide field-sourced errors when validation passes or is pending (async gap).
+        // Refinement errors persist until re-submit - they can't be cleared by typing.
+        const shouldHideStoredError = storedError.value.source === "field" &&
+          (validationResult._tag === "Success" || isValidating)
+
+        if (shouldHideStoredError) {
+          return Option.none()
+        }
+        return Option.some(storedError.value.message)
+      }
+
+      return Option.none()
+    }, [livePerFieldError, storedError, validationResult, isValidating])
 
     const onChange = React.useCallback(
       (newValue: Schema.Schema.Encoded<S>) => {
         setValue(newValue)
-        setCrossFieldErrors((prev) => {
-          const next = new Map<string, string>()
-          for (const [errorPath, message] of prev) {
-            if (!isPathUnderRoot(errorPath, fieldPath)) {
-              next.set(errorPath, message)
-            }
-          }
-          return next.size !== prev.size ? next : prev
-        })
-        if (parsedMode.validation === "onChange") {
-          validate(newValue)
-        }
       },
-      [fieldPath, setValue, setCrossFieldErrors, validate],
+      [setValue],
     )
 
     const onBlur = React.useCallback(() => {
@@ -269,8 +309,11 @@ const makeFieldComponent = <S extends Schema.Schema.Any, P extends Record<string
       () => isPathOrParentDirty(dirtyFields, fieldPath),
       [dirtyFields, fieldPath],
     )
-    const isValidating = validationResult.waiting
-    const shouldShowError = isTouched || submitCount > 0
+    const shouldShowError = parsedMode.validation === "onChange"
+      ? (isDirty || submitCount > 0)
+      : parsedMode.validation === "onBlur"
+      ? (isTouched || submitCount > 0)
+      : submitCount > 0
 
     const fieldState: FieldState<S> = React.useMemo(() => ({
       value,
@@ -292,7 +335,7 @@ const makeArrayFieldComponent = <S extends Schema.Schema.Any>(
   fieldKey: string,
   def: Field.ArrayFieldDef<string, S>,
   stateAtom: Atom.Writable<Option.Option<FormBuilder.FormState<any>>, Option.Option<FormBuilder.FormState<any>>>,
-  crossFieldErrorsAtom: Atom.Writable<Map<string, string>, Map<string, string>>,
+  errorsAtom: Atom.Writable<Map<string, Validation.ErrorEntry>, Map<string, Validation.ErrorEntry>>,
   submitCountAtom: Atom.Atom<number>,
   dirtyFieldsAtom: Atom.Atom<ReadonlySet<string>>,
   parsedMode: Mode.ParsedMode,
@@ -398,7 +441,7 @@ const makeArrayFieldComponent = <S extends Schema.Schema.Any>(
       itemFieldComponents[itemKey] = makeFieldComponent(
         itemKey,
         itemDef,
-        crossFieldErrorsAtom,
+        errorsAtom,
         submitCountAtom,
         dirtyFieldsAtom,
         parsedMode,
@@ -414,7 +457,6 @@ const makeArrayFieldComponent = <S extends Schema.Schema.Any>(
     ...itemFieldComponents,
   }
 
-  // Proxy enables <Form.items.Item> and <Form.items.name> syntax
   return new Proxy(ArrayWrapper, {
     get(target, prop) {
       if (prop in properties) {
@@ -434,7 +476,7 @@ const makeFieldComponents = <
     Option.Option<FormBuilder.FormState<TFields>>,
     Option.Option<FormBuilder.FormState<TFields>>
   >,
-  crossFieldErrorsAtom: Atom.Writable<Map<string, string>, Map<string, string>>,
+  errorsAtom: Atom.Writable<Map<string, Validation.ErrorEntry>, Map<string, Validation.ErrorEntry>>,
   submitCountAtom: Atom.Atom<number>,
   dirtyFieldsAtom: Atom.Atom<ReadonlySet<string>>,
   parsedMode: Mode.ParsedMode,
@@ -455,7 +497,7 @@ const makeFieldComponents = <
         key,
         def as Field.ArrayFieldDef<string, Schema.Schema.Any>,
         stateAtom,
-        crossFieldErrorsAtom,
+        errorsAtom,
         submitCountAtom,
         dirtyFieldsAtom,
         parsedMode,
@@ -465,11 +507,14 @@ const makeFieldComponents = <
         arrayComponentMap,
       )
     } else if (Field.isFieldDef(def)) {
-      const fieldComponent = (componentMap as Record<string, React.FC<FieldComponentProps<any, any>>>)[key]
+      const componentOrBundle = (componentMap as Record<string, unknown>)[key]
+      const fieldComponent = isFieldBundle(componentOrBundle)
+        ? componentOrBundle.component
+        : componentOrBundle as React.FC<FieldComponentProps<any, any>>
       components[key] = makeFieldComponent(
         key,
         def,
-        crossFieldErrorsAtom,
+        errorsAtom,
         submitCountAtom,
         dirtyFieldsAtom,
         parsedMode,
@@ -484,34 +529,30 @@ const makeFieldComponents = <
 }
 
 /**
- * Builds a React form from a FormBuilder.
+ * Creates a React form from a FormBuilder.
  *
  * @example
  * ```tsx
  * import { FormBuilder } from "@lucas-barake/effect-form"
  * import { FormReact } from "@lucas-barake/effect-form-react"
  * import { useAtomValue, useAtomSet } from "@effect-atom/atom-react"
- * import * as Atom from "@effect-atom/atom/Atom"
  * import * as Schema from "effect/Schema"
- * import * as Layer from "effect/Layer"
- *
- * const runtime = Atom.runtime(Layer.empty)
  *
- * const loginForm = FormBuilder.empty
+ * const loginFormBuilder = FormBuilder.empty
  *   .addField("email", Schema.String)
  *   .addField("password", Schema.String)
  *
- * const form = FormReact.build(loginForm, {
- *   runtime,
+ * // Runtime is optional for forms without service requirements
+ * const loginForm = FormReact.make(loginFormBuilder, {
  *   fields: { email: TextInput, password: PasswordInput },
- *   onSubmit: (values) => Effect.log(`Login: ${values.email}`),
+ *   onSubmit: (_, { decoded }) => Effect.log(`Login: ${decoded.email}`),
  * })
  *
  * // Subscribe to atoms anywhere in the tree
  * function SubmitButton() {
- *   const isDirty = useAtomValue(form.isDirty)
- *   const submit = useAtomValue(form.submit)
- *   const callSubmit = useAtomSet(form.submit)
+ *   const isDirty = useAtomValue(loginForm.isDirty)
+ *   const submit = useAtomValue(loginForm.submit)
+ *   const callSubmit = useAtomSet(loginForm.submit)
  *   return (
  *     <button onClick={() => callSubmit()} disabled={!isDirty || submit.waiting}>
  *       {submit.waiting ? "Validating..." : "Login"}
@@ -519,48 +560,74 @@ const makeFieldComponents = <
  *   )
  * }
  *
- * function LoginDialog({ onClose }) {
+ * function LoginPage() {
  *   return (
- *     <form.Initialize defaultValues={{ email: "", password: "" }}>
- *       <form.email />
- *       <form.password />
+ *     <loginForm.Initialize defaultValues={{ email: "", password: "" }}>
+ *       <loginForm.email />
+ *       <loginForm.password />
  *       <SubmitButton />
- *     </form.Initialize>
+ *     </loginForm.Initialize>
  *   )
  * }
  * ```
  *
  * @category Constructors
  */
-export const build = <
-  TFields extends Field.FieldsRecord,
-  R,
-  A,
-  E,
-  SubmitArgs = void,
-  ER = never,
-  CM extends FieldComponentMap<TFields> = FieldComponentMap<TFields>,
->(
-  self: FormBuilder.FormBuilder<TFields, R>,
-  options: {
-    readonly runtime: Atom.AtomRuntime<R, ER>
-    readonly fields: CM
-    readonly mode?: SubmitArgs extends void ? Mode.FormMode : Mode.FormModeWithoutAutoSubmit
-    readonly onSubmit: (
-      args: SubmitArgs,
-      ctx: {
-        readonly decoded: Field.DecodedFromFields<TFields>
-        readonly encoded: Field.EncodedFromFields<TFields>
-        readonly get: Atom.FnContext
-      },
-    ) => A | Effect.Effect<A, E, R>
-  },
-): BuiltForm<TFields, R, A, E, SubmitArgs, CM> => {
-  const { fields: components, mode, onSubmit, runtime } = options
+export const make: {
+  <
+    TFields extends Field.FieldsRecord,
+    A,
+    E,
+    SubmitArgs = void,
+    CM extends FieldComponentMap<TFields> = FieldComponentMap<TFields>,
+  >(
+    self: FormBuilder.FormBuilder<TFields, never>,
+    options: {
+      readonly runtime?: Atom.AtomRuntime<never, never>
+      readonly fields: CM
+      readonly mode?: SubmitArgs extends void ? Mode.FormMode : Mode.FormModeWithoutAutoSubmit
+      readonly onSubmit: (
+        args: SubmitArgs,
+        ctx: {
+          readonly decoded: Field.DecodedFromFields<TFields>
+          readonly encoded: Field.EncodedFromFields<TFields>
+          readonly get: Atom.FnContext
+        },
+      ) => A | Effect.Effect<A, E, never>
+    },
+  ): BuiltForm<TFields, never, A, E, SubmitArgs, CM>
+
+  <
+    TFields extends Field.FieldsRecord,
+    R,
+    A,
+    E,
+    SubmitArgs = void,
+    ER = never,
+    CM extends FieldComponentMap<TFields> = FieldComponentMap<TFields>,
+  >(
+    self: FormBuilder.FormBuilder<TFields, R>,
+    options: {
+      readonly runtime: Atom.AtomRuntime<R, ER>
+      readonly fields: CM
+      readonly mode?: SubmitArgs extends void ? Mode.FormMode : Mode.FormModeWithoutAutoSubmit
+      readonly onSubmit: (
+        args: SubmitArgs,
+        ctx: {
+          readonly decoded: Field.DecodedFromFields<TFields>
+          readonly encoded: Field.EncodedFromFields<TFields>
+          readonly get: Atom.FnContext
+        },
+      ) => A | Effect.Effect<A, E, R>
+    },
+  ): BuiltForm<TFields, R, A, E, SubmitArgs, CM>
+} = (self: any, options: any): any => {
+  const { fields: components, mode, onSubmit, runtime: providedRuntime } = options
+  const runtime = providedRuntime ?? Atom.runtime(Layer.empty)
   const parsedMode = Mode.parse(mode)
   const { fields } = self
 
-  const formAtoms: FormAtoms.FormAtoms<TFields, R, A, E, SubmitArgs> = FormAtoms.make({
+  const formAtoms = FormAtoms.make({
     formBuilder: self,
     runtime,
     onSubmit,
@@ -568,18 +635,21 @@ export const build = <
 
   const {
     combinedSchema,
-    crossFieldErrorsAtom,
     dirtyFieldsAtom,
+    errorsAtom,
     fieldRefs,
     getFieldAtom,
     getOrCreateFieldAtoms,
     getOrCreateValidationAtom,
     hasChangedSinceSubmitAtom,
     isDirtyAtom,
+    keepAliveActiveAtom,
     lastSubmittedValuesAtom,
+    mountAtom,
     operations,
     resetAtom,
     revertToLastSubmitAtom,
+    rootErrorAtom,
     setValue,
     setValuesAtom,
     stateAtom,
@@ -589,7 +659,7 @@ export const build = <
   } = formAtoms
 
   const InitializeComponent: React.FC<{
-    readonly defaultValues: Field.EncodedFromFields<TFields>
+    readonly defaultValues: any
     readonly children: React.ReactNode
   }> = ({ children, defaultValues }) => {
     const registry = React.useContext(RegistryContext)
@@ -599,56 +669,110 @@ export const build = <
     const isInitializedRef = React.useRef(false)
 
     React.useEffect(() => {
-      setFormState(Option.some(operations.createInitialState(defaultValues)))
+      const isKeptAlive = registry.get(keepAliveActiveAtom)
+      const currentState = registry.get(stateAtom)
+
+      if (!isKeptAlive) {
+        setFormState(Option.some(operations.createInitialState(defaultValues)))
+      } else if (Option.isNone(currentState)) {
+        setFormState(Option.some(operations.createInitialState(defaultValues)))
+      }
+
       isInitializedRef.current = true
       // eslint-disable-next-line react-hooks/exhaustive-deps -- mount-only
-    }, [])
+    }, [registry])
 
     const debouncedAutoSubmit = useDebounced(() => {
       const stateOption = registry.get(stateAtom)
       if (Option.isNone(stateOption)) return
-      callSubmit(undefined as SubmitArgs)
+      callSubmit(undefined)
     }, parsedMode.autoSubmit && parsedMode.validation === "onChange" ? parsedMode.debounce : null)
 
+    // ─────────────────────────────────────────────────────────────────────────────
+    // Auto-Submit Coordination
+    // ─────────────────────────────────────────────────────────────────────────────
+    // Two-subscription model to avoid infinite loop:
+    // - Stream 1 reacts to value changes (reference equality), triggers or queues submit
+    // - Stream 2 reacts to submit completion, flushes queued changes
+    //
+    // Single subscription to stateAtom cannot distinguish value changes from submit
+    // metadata updates (submitCount, lastSubmittedValues).
+    // ─────────────────────────────────────────────────────────────────────────────
+
+    const lastValuesRef = React.useRef<unknown>(null)
+    const pendingChangesRef = React.useRef(false)
+    const wasSubmittingRef = React.useRef(false)
+
     useAtomSubscribe(
       stateAtom,
       React.useCallback(() => {
         if (!isInitializedRef.current) return
-        if (parsedMode.autoSubmit && parsedMode.validation === "onChange") {
+
+        const state = registry.get(stateAtom)
+        if (Option.isNone(state)) return
+        const currentValues = state.value.values
+
+        // Reference equality filters out submit metadata changes.
+        // Works because setFieldValue creates new values object (immutable update).
+        if (currentValues === lastValuesRef.current) return
+        lastValuesRef.current = currentValues
+
+        if (!parsedMode.autoSubmit || parsedMode.validation !== "onChange") return
+
+        const submitResult = registry.get(submitAtom)
+        if (submitResult.waiting) {
+          pendingChangesRef.current = true
+        } else {
           debouncedAutoSubmit()
         }
-      }, [debouncedAutoSubmit]),
+      }, [debouncedAutoSubmit, registry]),
+      { immediate: false },
+    )
+
+    useAtomSubscribe(
+      submitAtom,
+      React.useCallback(
+        (result) => {
+          if (!parsedMode.autoSubmit || parsedMode.validation !== "onChange") return
+
+          const isSubmitting = result.waiting
+          const wasSubmitting = wasSubmittingRef.current
+          wasSubmittingRef.current = isSubmitting
+
+          // Flush queued changes when submit completes
+          if (wasSubmitting && !isSubmitting) {
+            if (pendingChangesRef.current) {
+              pendingChangesRef.current = false
+              debouncedAutoSubmit()
+            }
+          }
+        },
+        [debouncedAutoSubmit],
+      ),
       { immediate: false },
     )
 
     const onBlurAutoSubmit = React.useCallback(() => {
-      if (parsedMode.autoSubmit && parsedMode.validation === "onBlur") {
-        const stateOption = registry.get(stateAtom)
-        if (Option.isNone(stateOption)) return
-        callSubmit(undefined as SubmitArgs)
-      }
+      if (!parsedMode.autoSubmit || parsedMode.validation !== "onBlur") return
+
+      const stateOption = registry.get(stateAtom)
+      if (Option.isNone(stateOption)) return
+
+      const { lastSubmittedValues, values } = stateOption.value
+      if (Option.isSome(lastSubmittedValues) && values === lastSubmittedValues.value.encoded) return
+
+      callSubmit(undefined)
     }, [registry, callSubmit])
 
     if (Option.isNone(state)) return null
 
-    return (
-      <AutoSubmitContext.Provider value={onBlurAutoSubmit}>
-        <form
-          onSubmit={(e) => {
-            e.preventDefault()
-            e.stopPropagation()
-          }}
-        >
-          {children}
-        </form>
-      </AutoSubmitContext.Provider>
-    )
+    return <AutoSubmitContext.Provider value={onBlurAutoSubmit}>{children}</AutoSubmitContext.Provider>
   }
 
   const fieldComponents = makeFieldComponents(
     fields,
     stateAtom,
-    crossFieldErrorsAtom,
+    errorsAtom,
     submitCountAtom,
     dirtyFieldsAtom,
     parsedMode,
@@ -658,12 +782,25 @@ export const build = <
     components,
   )
 
+  const KeepAlive: React.FC = () => {
+    const setKeepAliveActive = useAtomSet(keepAliveActiveAtom)
+
+    React.useLayoutEffect(() => {
+      setKeepAliveActive(true)
+      return () => setKeepAliveActive(false)
+    }, [setKeepAliveActive])
+
+    useAtomMount(mountAtom)
+    return null
+  }
+
   return {
     values: valuesAtom,
     isDirty: isDirtyAtom,
     hasChangedSinceSubmit: hasChangedSinceSubmitAtom,
     lastSubmittedValues: lastSubmittedValuesAtom,
     submitCount: submitCountAtom,
+    rootError: rootErrorAtom,
     schema: combinedSchema,
     fields: fieldRefs,
     Initialize: InitializeComponent,
@@ -673,47 +810,109 @@ export const build = <
     setValues: setValuesAtom,
     setValue,
     getFieldAtom,
+    mount: mountAtom,
+    KeepAlive,
     ...fieldComponents,
-  } as BuiltForm<TFields, R, A, E, SubmitArgs, CM>
+  }
 }
 
 /**
- * A curried helper that infers the schema type from a field definition or field reference.
+ * A curried helper that infers the schema type from a field definition.
  * Provides ergonomic type inference when defining field components.
  *
  * @example
  * ```tsx
- * import { FormReact } from "@lucas-barake/effect-form-react"
+ * import { Field, FormReact } from "@lucas-barake/effect-form-react"
  *
- * // Using a FieldRef from the built form
- * const TextInput = FormReact.forField(form.fields.email)(({ field }) => (
- *   <input value={field.value} onChange={e => field.onChange(e.target.value)} />
- * ))
- *
- * // Using a FieldDef (for reusable fields)
  * const EmailField = Field.makeField("email", Schema.String)
  * const TextInput = FormReact.forField(EmailField)(({ field }) => (
  *   <input value={field.value} onChange={e => field.onChange(e.target.value)} />
  * ))
  *
  * // With extra props - just specify the props type
- * const TextInput = FormReact.forField(form.fields.email)<{ placeholder?: string }>(({ field, props }) => (
+ * const TextInput = FormReact.forField(EmailField)<{ placeholder?: string }>(({ field, props }) => (
  *   <input value={field.value} placeholder={props.placeholder} ... />
  * ))
  * ```
  *
  * @category Constructors
  */
-export const forField: {
-  <S>(
-    _field: FormBuilder.FieldRef<S>,
-  ): <P extends Record<string, unknown> = Record<string, never>>(
-    component: React.FC<FieldComponentProps<Schema.Schema<S, S, never>, P>>,
-  ) => React.FC<FieldComponentProps<Schema.Schema<S, S, never>, P>>
-
-  <K extends string, S extends Schema.Schema.Any>(
-    _field: Field.FieldDef<K, S>,
-  ): <P extends Record<string, unknown> = Record<string, never>>(
-    component: React.FC<FieldComponentProps<S, P>>,
-  ) => React.FC<FieldComponentProps<S, P>>
-} = (_field: unknown) => (component: unknown) => component as any
+export const forField = <K extends string, S extends Schema.Schema.Any>(
+  _field: Field.FieldDef<K, S>,
+): <P extends Record<string, unknown> = Record<string, never>>(
+  component: React.FC<FieldComponentProps<S, P>>,
+) => React.FC<FieldComponentProps<S, P>> =>
+(component) => component
+
+/**
+ * Creates a bundled field definition + component for reusable form fields.
+ * Reduces boilerplate when you need both a field and its component together.
+ *
+ * Uses a curried API for better type inference - the schema type is captured
+ * first, so you only need to specify the extra props type (if any).
+ *
+ * @example
+ * ```tsx
+ * import { FormReact } from "@lucas-barake/effect-form-react"
+ * import * as Schema from "effect/Schema"
+ *
+ * // Define field + component in one place (no extra props)
+ * const NameInput = FormReact.makeField({
+ *   key: "name",
+ *   schema: Schema.String.pipe(Schema.nonEmptyString()),
+ * })(({ field }) => (
+ *   <input
+ *     value={field.value}
+ *     onChange={(e) => field.onChange(e.target.value)}
+ *     onBlur={field.onBlur}
+ *   />
+ * ))
+ *
+ * // With extra props - specify only the props type
+ * const EmailInput = FormReact.makeField({
+ *   key: "email",
+ *   schema: Schema.String,
+ * })<{ placeholder: string }>(({ field, props }) => (
+ *   <input
+ *     value={field.value}
+ *     onChange={(e) => field.onChange(e.target.value)}
+ *     placeholder={props.placeholder}
+ *   />
+ * ))
+ *
+ * // Use in form builder
+ * const formBuilder = FormBuilder.empty.addField(NameInput.field)
+ *
+ * // Use in make()
+ * const form = FormReact.make(formBuilder, {
+ *   runtime,
+ *   fields: { name: NameInput },
+ *   onSubmit: (_, { decoded }) => Effect.log(decoded.name),
+ * })
+ * ```
+ *
+ * @category Constructors
+ */
+export const makeField = <K extends string, S extends Schema.Schema.Any>(options: {
+  readonly key: K
+  readonly schema: S
+}): <P extends Record<string, unknown> = Record<string, never>>(
+  component: React.FC<FieldComponentProps<S, P>>,
+) => FieldBundle<K, S, P> => {
+  const field = Field.makeField(options.key, options.schema)
+  return (component) => {
+    if (!component.displayName) {
+      const displayName = `${options.key.charAt(0).toUpperCase()}${options.key.slice(1)}Field`
+      try {
+        ;(component as any).displayName = displayName
+      } catch {
+        // Ignore - some environments freeze function properties
+      }
+    }
+    return {
+      _tag: "FieldBundle",
+      field,
+      component,
+    }
+  }
+}