fix(preact-form): track read FormGroup state

The Preact useFormGroup is a line-for-line copy of the React hook and
shares its defect: any field change in a group re-ran the render prop
and all of its children, even when nothing there read group state.

Apply the same tracked subscription as in react-form, so the group
only re-renders when state that has been read changes.

Refs #2377

Author: max-te

.changeset/quiet-preact-groups-render.md

@@ -0,0 +1,5 @@
+---
+'@tanstack/preact-form': patch
+---
+
+Rerender `FormGroup` only when group state read during render changes, instead of on every field change in the group.

docs/framework/preact/guides/form-groups.md

@@ -175,3 +175,5 @@ Just like you're able to access `group.state.meta.errors`, you're also able to a
 - `group.state.meta.isGroupValid`: `true` when the group-level validators have no errors
 - `group.state.meta.isValid`: `true` when both the field-level and group-level validators have no errors
 - `group.state.meta.isSubmitting`: `true` when the group is in the process of being submitted
+
+A group only rerenders when a part of `group.state` that it has read changes. A group that renders only `form.Field`s therefore does not rerender while those fields are edited; each field rerenders on its own.

packages/preact-form/src/useFormGroup.tsx

@@ -1,4 +1,4 @@
-import { useMemo, useState } from 'preact/hooks'
+import { useMemo, useRef, useState } from 'preact/hooks'
 import { useSelector } from '@tanstack/preact-store'
 import { FormGroupApi, functionalUpdate } from '@tanstack/form-core'
 import { useIsomorphicLayoutEffect } from './useIsomorphicLayoutEffect'
@@ -201,77 +201,23 @@ export function useFormGroup<
     setPrevOptions({ form: opts.form, name: opts.name })
   }
 
-  const reactiveStateValue = useSelector(
-    formGroupApi.store,
-    (state) => state.value,
+  const trackedKeysRef = useRef(
+    new Set<keyof typeof formGroupApi.state.meta | 'value'>(),
   )
 
-  const reactiveMetaIsTouched = useSelector(
-    formGroupApi.store,
-    (state) => state.meta.isTouched,
-  )
-  const reactiveMetaIsBlurred = useSelector(
-    formGroupApi.store,
-    (state) => state.meta.isBlurred,
-  )
-  const reactiveMetaIsDirty = useSelector(
-    formGroupApi.store,
-    (state) => state.meta.isDirty,
-  )
-  const reactiveMetaErrorMap = useSelector(
-    formGroupApi.store,
-    (state) => state.meta.errorMap,
-  )
-  const reactiveMetaErrorSourceMap = useSelector(
-    formGroupApi.store,
-    (state) => state.meta.errorSourceMap,
-  )
-  const reactiveMetaIsValidating = useSelector(
-    formGroupApi.store,
-    (state) => state.meta.isValidating,
-  )
-
-  // Submission lifecycle and aggregated validity now live on `state.meta`
-  // (mirroring `FieldApi.state.meta`).
-  const reactiveMetaIsSubmitting = useSelector(
-    formGroupApi.store,
-    (state) => state.meta.isSubmitting,
-  )
-  const reactiveMetaIsSubmitted = useSelector(
-    formGroupApi.store,
-    (state) => state.meta.isSubmitted,
-  )
-  const reactiveMetaSubmissionAttempts = useSelector(
-    formGroupApi.store,
-    (state) => state.meta.submissionAttempts,
-  )
-  const reactiveMetaIsSubmitSuccessful = useSelector(
-    formGroupApi.store,
-    (state) => state.meta.isSubmitSuccessful,
-  )
-  const reactiveMetaCanSubmit = useSelector(
-    formGroupApi.store,
-    (state) => state.meta.canSubmit,
-  )
-  const reactiveMetaIsValid = useSelector(
-    formGroupApi.store,
-    (state) => state.meta.isValid,
-  )
-  const reactiveMetaIsFieldsValid = useSelector(
-    formGroupApi.store,
-    (state) => state.meta.isFieldsValid,
-  )
-  const reactiveMetaIsFieldsValidating = useSelector(
-    formGroupApi.store,
-    (state) => state.meta.isFieldsValidating,
-  )
-  const reactiveMetaIsGroupValid = useSelector(
-    formGroupApi.store,
-    (state) => state.meta.isGroupValid,
-  )
+  const trackedState = useSelector(formGroupApi.store, (state) => state, {
+    compare: (prev, next) =>
+      [...trackedKeysRef.current].every((key) =>
+        key === 'value'
+          ? prev.value === next.value
+          : prev.meta[key] === next.meta[key],
+      ),
+  })
 
-  // This makes me sad, but if I understand correctly, this is what we have to do for reactivity to work properly with React compiler.
   const extendedFieldApi = useMemo(() => {
+    // Consumers memoized on `group` (e.g. with `memo`)
+    // need a new identity whenever a tracked slice changes
+    void trackedState
     const reactiveFieldApi = {
       ...formGroupApi,
       handleSubmit: ((...props: never[]) => {
@@ -280,78 +226,30 @@ export function useFormGroup<
       get state() {
         return {
           ...formGroupApi.state,
-          value: reactiveStateValue,
+          get value() {
+            trackedKeysRef.current.add('value')
+            return formGroupApi.state.value
+          },
           get meta() {
-            return {
-              ...formGroupApi.state.meta,
-              isTouched: reactiveMetaIsTouched,
-              isBlurred: reactiveMetaIsBlurred,
-              isDirty: reactiveMetaIsDirty,
-              errorMap: reactiveMetaErrorMap,
-              errorSourceMap: reactiveMetaErrorSourceMap,
-              isValidating: reactiveMetaIsValidating,
-              isSubmitting: reactiveMetaIsSubmitting,
-              isSubmitted: reactiveMetaIsSubmitted,
-              submissionAttempts: reactiveMetaSubmissionAttempts,
-              isSubmitSuccessful: reactiveMetaIsSubmitSuccessful,
-              canSubmit: reactiveMetaCanSubmit,
-              isValid: reactiveMetaIsValid,
-              isFieldsValid: reactiveMetaIsFieldsValid,
-              isFieldsValidating: reactiveMetaIsFieldsValidating,
-              isGroupValid: reactiveMetaIsGroupValid,
-            } satisfies typeof formGroupApi.state.meta
+            const trackedMeta = { ...formGroupApi.state.meta }
+            for (const key of Object.keys(
+              trackedMeta,
+            ) as (keyof typeof trackedMeta)[]) {
+              Object.defineProperty(trackedMeta, key, {
+                enumerable: true,
+                get() {
+                  trackedKeysRef.current.add(key)
+                  return formGroupApi.state.meta[key]
+                },
+              })
+            }
+            return trackedMeta
           },
         } satisfies typeof formGroupApi.state
       },
     }
-
-    const extendedApi: FormGroupApi<
-      TParentData,
-      TName,
-      TData,
-      TOnMount,
-      TOnChange,
-      TOnChangeAsync,
-      TOnBlur,
-      TOnBlurAsync,
-      TOnSubmit,
-      TOnSubmitAsync,
-      TOnDynamic,
-      TOnDynamicAsync,
-      TSubmitMeta,
-      TFormOnMount,
-      TFormOnChange,
-      TFormOnChangeAsync,
-      TFormOnBlur,
-      TFormOnBlurAsync,
-      TFormOnSubmit,
-      TFormOnSubmitAsync,
-      TFormOnDynamic,
-      TFormOnDynamicAsync,
-      TFormOnServer,
-      TParentSubmitMeta
-    > = reactiveFieldApi as never
-
-    return extendedApi
-  }, [
-    formGroupApi,
-    reactiveStateValue,
-    reactiveMetaIsTouched,
-    reactiveMetaIsBlurred,
-    reactiveMetaIsDirty,
-    reactiveMetaErrorMap,
-    reactiveMetaErrorSourceMap,
-    reactiveMetaIsValidating,
-    reactiveMetaIsSubmitting,
-    reactiveMetaIsSubmitted,
-    reactiveMetaSubmissionAttempts,
-    reactiveMetaIsSubmitSuccessful,
-    reactiveMetaCanSubmit,
-    reactiveMetaIsValid,
-    reactiveMetaIsFieldsValid,
-    reactiveMetaIsFieldsValidating,
-    reactiveMetaIsGroupValid,
-  ])
+    return reactiveFieldApi as never as typeof formGroupApi
+  }, [formGroupApi, trackedState])
 
   useIsomorphicLayoutEffect(formGroupApi.mount, [formGroupApi])
 

packages/preact-form/tests/useFormGroup.test.tsx

@@ -320,4 +320,172 @@ describe('form.FormGroup', () => {
     expect(button.disabled).toBe(false)
     expect(onGroupSubmit).toHaveBeenCalledTimes(1)
   })
+
+  it('should not rerender group children when a field changes and group state is not read', async () => {
+    const renderGroupChildren = vi.fn()
+
+    function Comp() {
+      const form = useForm({
+        defaultValues: {
+          step1: { firstName: '', lastName: '' },
+        },
+      })
+
+      return (
+        <form.FormGroup name="step1">
+          {() => {
+            renderGroupChildren()
+            return (
+              <form.Field
+                name="step1.firstName"
+                children={(field) => (
+                  <input
+                    data-testid="first-name"
+                    value={field.state.value}
+                    onInput={(e) => field.handleChange(e.currentTarget.value)}
+                  />
+                )}
+              />
+            )
+          }}
+        </form.FormGroup>
+      )
+    }
+
+    const { getByTestId } = render(<Comp />)
+    const rendersAfterMount = renderGroupChildren.mock.calls.length
+
+    await user.type(getByTestId('first-name'), 'abc')
+
+    expect(getByTestId('first-name')).toHaveValue('abc')
+    expect(renderGroupChildren).toHaveBeenCalledTimes(rendersAfterMount)
+  })
+
+  it('should rerender for group meta it reads but not for unrelated value changes', async () => {
+    const renderGroupChildren = vi.fn()
+
+    function Comp() {
+      const form = useForm({
+        defaultValues: {
+          step1: { firstName: '' },
+        },
+      })
+
+      return (
+        <form.FormGroup
+          name="step1"
+          validators={{
+            onChange: ({ value }) =>
+              value.firstName.includes('!')
+                ? 'No exclamation marks'
+                : undefined,
+          }}
+        >
+          {(group) => {
+            renderGroupChildren()
+            return (
+              <>
+                <form.Field
+                  name="step1.firstName"
+                  children={(field) => (
+                    <input
+                      data-testid="first-name"
+                      value={field.state.value}
+                      onInput={(e) => field.handleChange(e.currentTarget.value)}
+                    />
+                  )}
+                />
+                <pre data-testid="group-errors">
+                  {JSON.stringify(group.state.meta.errorMap)}
+                </pre>
+              </>
+            )
+          }}
+        </form.FormGroup>
+      )
+    }
+
+    const { getByTestId } = render(<Comp />)
+    const rendersAfterMount = renderGroupChildren.mock.calls.length
+
+    await user.type(getByTestId('first-name'), 'abc')
+    expect(renderGroupChildren).toHaveBeenCalledTimes(rendersAfterMount)
+
+    await user.type(getByTestId('first-name'), '!')
+    await waitFor(() =>
+      expect(getByTestId('group-errors')).toHaveTextContent(
+        'No exclamation marks',
+      ),
+    )
+  })
+
+  it('should read the current group value in handlers without subscribing up front', async () => {
+    const onRead = vi.fn()
+
+    function Comp() {
+      const form = useForm({
+        defaultValues: {
+          step1: { firstName: '' },
+        },
+      })
+
+      return (
+        <form.FormGroup name="step1">
+          {(group) => (
+            <>
+              <form.Field
+                name="step1.firstName"
+                children={(field) => (
+                  <input
+                    data-testid="first-name"
+                    value={field.state.value}
+                    onInput={(e) => field.handleChange(e.currentTarget.value)}
+                  />
+                )}
+              />
+              <button
+                data-testid="read-value"
+                onClick={() => onRead(group.state.value)}
+              />
+            </>
+          )}
+        </form.FormGroup>
+      )
+    }
+
+    const { getByTestId } = render(<Comp />)
+
+    await user.type(getByTestId('first-name'), 'abc')
+    await user.click(getByTestId('read-value'))
+
+    expect(onRead).toHaveBeenCalledWith({ firstName: 'abc' })
+  })
+
+  it('should expose the group store state through group.state', async () => {
+    const onRead = vi.fn()
+
+    function Comp() {
+      const form = useForm({
+        defaultValues: {
+          step1: { firstName: 'initial' },
+        },
+      })
+
+      return (
+        <form.FormGroup name="step1">
+          {(group) => (
+            <button data-testid="read-state" onClick={() => onRead(group)} />
+          )}
+        </form.FormGroup>
+      )
+    }
+
+    const { getByTestId } = render(<Comp />)
+    await user.click(getByTestId('read-state'))
+
+    const group = onRead.mock.calls[0]![0]
+    expect(group.state).toEqual(group.store.state)
+    expect(group.state.meta).toEqual(group.store.state.meta)
+    expect(structuredClone(group.state)).toEqual(group.store.state)
+  })
 })