@lucas-barake/effect-form-react 0.12.0 → 0.13.1

package/src/FormReact.tsx

@@ -1,10 +1,18 @@
-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"
@@ -130,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>
@@ -151,6 +158,9 @@ export type BuiltForm<
   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<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>> = {
@@ -193,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,
@@ -209,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(
@@ -241,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)) {
@@ -257,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(() => {
@@ -291,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,
@@ -314,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,
@@ -420,7 +441,7 @@ const makeArrayFieldComponent = <S extends Schema.Schema.Any>(
       itemFieldComponents[itemKey] = makeFieldComponent(
         itemKey,
         itemDef,
-        crossFieldErrorsAtom,
+        errorsAtom,
         submitCountAtom,
         dirtyFieldsAtom,
         parsedMode,
@@ -436,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) {
@@ -456,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,
@@ -477,7 +497,7 @@ const makeFieldComponents = <
         key,
         def as Field.ArrayFieldDef<string, Schema.Schema.Any>,
         stateAtom,
-        crossFieldErrorsAtom,
+        errorsAtom,
         submitCountAtom,
         dirtyFieldsAtom,
         parsedMode,
@@ -494,7 +514,7 @@ const makeFieldComponents = <
       components[key] = makeFieldComponent(
         key,
         def,
-        crossFieldErrorsAtom,
+        errorsAtom,
         submitCountAtom,
         dirtyFieldsAtom,
         parsedMode,
@@ -509,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"}
@@ -544,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,
@@ -593,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,
@@ -614,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)
@@ -624,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,
@@ -683,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,
@@ -698,8 +810,10 @@ export const build = <
     setValues: setValuesAtom,
     setValue,
     getFieldAtom,
+    mount: mountAtom,
+    KeepAlive,
     ...fieldComponents,
-  } as BuiltForm<TFields, R, A, E, SubmitArgs, CM>
+  }
 }
 
 /**
@@ -767,10 +881,10 @@ export const forField = <K extends string, S extends Schema.Schema.Any>(
  * ))
  *
  * // Use in form builder
- * const form = FormBuilder.empty.addField(NameInput.field)
+ * const formBuilder = FormBuilder.empty.addField(NameInput.field)
  *
- * // Use in build()
- * const Form = FormReact.build(form, {
+ * // Use in make()
+ * const form = FormReact.make(formBuilder, {
  *   runtime,
  *   fields: { name: NameInput },
  *   onSubmit: (_, { decoded }) => Effect.log(decoded.name),
@@ -783,20 +897,16 @@ 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>>
+  component: React.FC<FieldComponentProps<S, P>>,
 ) => FieldBundle<K, S, P> => {
   const field = Field.makeField(options.key, options.schema)
   return (component) => {
-    // DX: Auto-generate a readable component name for DevTools
-    // e.g., key "email" -> "<EmailField />"
     if (!component.displayName) {
       const displayName = `${options.key.charAt(0).toUpperCase()}${options.key.slice(1)}Field`
-      // Cast to 'any' because strict TS marks function names as readonly,
-      // but React relies on mutation here.
       try {
         ;(component as any).displayName = displayName
       } catch {
-        // Ignore errors in environments where function props are frozen
+        // Ignore - some environments freeze function properties
       }
     }
     return {