refactor: decouple fields from state in DynamicForms (#2823)

* refactor: decouple fields from state in DynamicForms

* fix: remove options from fields

* fix: pass passwordComplexity as an arg

* fix: remove fields from return state in contact form

* chore: add changeset

Author: jorgemoya

.changeset/quiet-heads-heal.md

@@ -0,0 +1,135 @@
+---
+"@bigcommerce/catalyst-core": patch
+---
+
+Refactor DynamicForm actions to decouple fields and passwordComplexity from state, passing them as separate arguments instead. This reduces state payload size by removing fields from state objects and stripping options from fields before passing them to actions (options are only needed for rendering, not processing). All form actions now accept a `DynamicFormActionArgs` object as the first parameter containing fields and optional passwordComplexity, followed by the previous state and formData.
+
+## Migration steps
+
+### Step 1: Changes to DynamicForm component
+
+The `DynamicForm` component and related utilities have been updated to support the new action signature pattern:
+
+**`core/vibes/soul/form/dynamic-form/index.tsx`**:
+- Added `DynamicFormActionArgs<F>` interface that contains `fields` and optional `passwordComplexity`
+- Updated `DynamicFormAction<F>` type to accept `DynamicFormActionArgs<F>` as the first parameter
+- Removed `fields` and `passwordComplexity` from the `State` interface
+- Added automatic removal of `options` from fields before passing to actions (options are only needed for rendering)
+- Updated action binding to use `action.bind(null, { fields: fieldsWithoutOptions, passwordComplexity })`
+
+**`core/vibes/soul/form/dynamic-form/utils.ts`** (new file):
+- Added `removeOptionsFromFields()` utility function that strips the `options` property from field definitions before passing them to actions, reducing the state payload size
+
+```diff
++ export interface DynamicFormActionArgs<F extends Field> {
++   fields: Array<F | FieldGroup<F>>;
++   passwordComplexity?: PasswordComplexitySettings | null;
++ }
++
++ type Action<F extends Field, S, P> = (
++   args: DynamicFormActionArgs<F>,
++   state: Awaited<S>,
++   payload: P,
++ ) => S | Promise<S>;
++
+  interface State {
+    lastResult: SubmissionResult | null;
+-   fields: Array<F | FieldGroup<F>>;
+-   passwordComplexity?: PasswordComplexitySettings | null;
+  }
+```
+
+### Step 2: Update DynamicForm action signatures
+
+All form actions that use `DynamicForm` must be updated to accept `DynamicFormActionArgs<F>` as the first parameter instead of including fields in the state.
+
+Update your form action function signature:
+
+```diff
++ import { DynamicFormActionArgs } from '@/vibes/soul/form/dynamic-form';
+  import { Field, FieldGroup, schema } from '@/vibes/soul/form/dynamic-form/schema';
+
+- export async function myFormAction<F extends Field>(
+-   prevState: {
+-     lastResult: SubmissionResult | null;
+-     fields: Array<F | FieldGroup<F>>;
+-     passwordComplexity?: PasswordComplexitySettings | null;
+-   },
+-   formData: FormData,
+- ) {
++ export async function myFormAction<F extends Field>(
++   { fields, passwordComplexity }: DynamicFormActionArgs<F>,
++   _prevState: {
++     lastResult: SubmissionResult | null;
++   },
++   formData: FormData,
++ ) {
+```
+
+### Step 2: Remove fields and passwordComplexity from state interfaces
+
+Update state interfaces to remove fields and passwordComplexity properties:
+
+```diff
+  interface State {
+    lastResult: SubmissionResult | null;
+-   fields: Array<Field | FieldGroup<Field>>;
+-   passwordComplexity?: PasswordComplexitySettings | null;
+  }
+```
+
+### Step 3: Update action implementations
+
+Remove references to `prevState.fields` and `prevState.passwordComplexity` in action implementations:
+
+```diff
+  const submission = parseWithZod(formData, {
+-   schema: schema(prevState.fields, prevState.passwordComplexity),
++   schema: schema(fields, passwordComplexity),
+  });
+
+  if (submission.status !== 'success') {
+    return {
+      lastResult: submission.reply(),
+-     fields: prevState.fields,
+-     passwordComplexity: prevState.passwordComplexity,
+    };
+  }
+```
+
+### Step 4: Update action calls in components
+
+For actions used with `AddressListSection`, update the action signature to accept fields as the first parameter:
+
+```diff
+- export async function addressAction(
+-   prevState: Awaited<State>,
+-   formData: FormData,
+- ): Promise<State> {
++ export async function addressAction(
++   fields: Array<Field | FieldGroup<Field>>,
++   prevState: Awaited<State>,
++   formData: FormData,
++ ): Promise<State> {
+```
+
+### Step 5: Update DynamicForm usage
+
+No changes needed to `DynamicForm` component usage. The component automatically handles binding fields and passwordComplexity to actions. The `DynamicForm` component now:
+- Automatically removes options from fields before passing them to actions (reducing payload size)
+- Binds fields and passwordComplexity to the action using `action.bind()`
+- Maintains the same props interface, so existing usage continues to work
+
+### Affected files
+
+The following files were updated in this refactor:
+- `core/vibes/soul/form/dynamic-form/index.tsx` - Added `DynamicFormActionArgs` type and updated action binding
+- `core/vibes/soul/form/dynamic-form/utils.ts` - Added `removeOptionsFromFields` utility function
+- `core/app/[locale]/(default)/(auth)/register/_actions/register-customer.ts`
+- `core/app/[locale]/(default)/account/addresses/_actions/address-action.ts`
+- `core/app/[locale]/(default)/account/addresses/_actions/create-address.ts`
+- `core/app/[locale]/(default)/account/addresses/_actions/update-address.ts`
+- `core/app/[locale]/(default)/account/addresses/_actions/delete-address.ts`
+- `core/app/[locale]/(default)/gift-certificates/purchase/_actions/add-to-cart.tsx`
+- `core/app/[locale]/(default)/webpages/[id]/contact/_actions/submit-contact-form.ts`
+- `core/vibes/soul/sections/address-list-section/index.tsx`

core/app/[locale]/(default)/(auth)/register/_actions/register-customer.ts

@@ -6,6 +6,7 @@ import { parseWithZod } from '@conform-to/zod';
 import { getLocale, getTranslations } from 'next-intl/server';
 import { z } from 'zod';
 
+import { DynamicFormActionArgs } from '@/vibes/soul/form/dynamic-form';
 import { Field, FieldGroup, schema } from '@/vibes/soul/form/dynamic-form/schema';
 import { signIn } from '~/auth';
 import { client } from '~/client';
@@ -335,10 +336,9 @@ function parseRegisterCustomerInput(
 }
 
 export async function registerCustomer<F extends Field>(
-  prevState: {
+  { fields, passwordComplexity }: DynamicFormActionArgs<F>,
+  _prevState: {
     lastResult: SubmissionResult | null;
-    fields: Array<F | FieldGroup<F>>;
-    passwordComplexity?: Parameters<typeof schema>[1];
   },
   formData: FormData,
 ) {
@@ -347,19 +347,17 @@ export async function registerCustomer<F extends Field>(
   const cartId = await getCartId();
 
   const submission = parseWithZod(formData, {
-    schema: schema(prevState.fields, prevState.passwordComplexity),
+    schema: schema(fields, passwordComplexity),
   });
 
   if (submission.status !== 'success') {
     return {
       lastResult: submission.reply(),
-      fields: prevState.fields,
-      passwordComplexity: prevState.passwordComplexity,
     };
   }
 
   try {
-    const input = parseRegisterCustomerInput(submission.value, prevState.fields);
+    const input = parseRegisterCustomerInput(submission.value, fields);
     const response = await client.fetch({
       document: RegisterCustomerMutation,
       variables: {
@@ -375,8 +373,6 @@ export async function registerCustomer<F extends Field>(
         lastResult: submission.reply({
           formErrors: response.data.customer.registerCustomer.errors.map((error) => error.message),
         }),
-        fields: prevState.fields,
-        passwordComplexity: prevState.passwordComplexity,
       };
     }
 
@@ -397,23 +393,17 @@ export async function registerCustomer<F extends Field>(
         lastResult: submission.reply({
           formErrors: error.errors.map(({ message }) => message),
         }),
-        fields: prevState.fields,
-        passwordComplexity: prevState.passwordComplexity,
       };
     }
 
     if (error instanceof Error) {
       return {
         lastResult: submission.reply({ formErrors: [error.message] }),
-        fields: prevState.fields,
-        passwordComplexity: prevState.passwordComplexity,
       };
     }
 
     return {
       lastResult: submission.reply({ formErrors: [t('somethingWentWrong')] }),
-      fields: prevState.fields,
-      passwordComplexity: prevState.passwordComplexity,
     };
   }
 

core/app/[locale]/(default)/account/addresses/_actions/address-action.ts

@@ -11,21 +11,24 @@ export interface State {
   addresses: Address[];
   lastResult: SubmissionResult | null;
   defaultAddress?: DefaultAddressConfiguration;
-  fields: Array<Field | FieldGroup<Field>>;
 }
 
-export async function addressAction(prevState: Awaited<State>, formData: FormData): Promise<State> {
+export async function addressAction(
+  fields: Array<Field | FieldGroup<Field>>,
+  prevState: Awaited<State>,
+  formData: FormData,
+): Promise<State> {
   'use server';
 
   const intent = formData.get('intent');
 
   switch (intent) {
     case 'create': {
-      return await createAddress(prevState, formData);
+      return await createAddress(fields, prevState, formData);
     }
 
     case 'update': {
-      return await updateAddress(prevState, formData);
+      return await updateAddress(fields, prevState, formData);
     }
 
     case 'delete': {

core/app/[locale]/(default)/account/addresses/_actions/create-address.ts

@@ -196,7 +196,11 @@ function parseAddAddressInput(
   return inputSchema.parse(mappedInput);
 }
 
-export async function createAddress(prevState: Awaited<State>, formData: FormData): Promise<State> {
+export async function createAddress(
+  fields: Array<Field | FieldGroup<Field>>,
+  prevState: Awaited<State>,
+  formData: FormData,
+): Promise<State> {
   const t = await getTranslations('Account.Addresses');
   const customerAccessToken = await getSessionCustomerAccessToken();
 
@@ -210,7 +214,7 @@ export async function createAddress(prevState: Awaited<State>, formData: FormDat
   }
 
   try {
-    const input = parseAddAddressInput(submission.value, prevState.fields);
+    const input = parseAddAddressInput(submission.value, fields);
 
     const response = await client.fetch({
       document: AddCustomerAddressMutation,
@@ -242,7 +246,6 @@ export async function createAddress(prevState: Awaited<State>, formData: FormDat
       ],
       lastResult: submission.reply({ resetForm: true }),
       defaultAddress: prevState.defaultAddress,
-      fields: prevState.fields,
     };
   } catch (error) {
     // eslint-disable-next-line no-console

core/app/[locale]/(default)/account/addresses/_actions/delete-address.ts

@@ -86,7 +86,6 @@ export async function deleteAddress(prevState: Awaited<State>, formData: FormDat
       ),
       lastResult: submission.reply({ resetForm: true }),
       defaultAddress: prevState.defaultAddress,
-      fields: prevState.fields,
     };
   } catch (error) {
     // eslint-disable-next-line no-console

core/app/[locale]/(default)/account/addresses/_actions/update-address.ts

@@ -209,7 +209,11 @@ function parseUpdateAddressInput(
   return inputSchema.parse(mappedInput);
 }
 
-export async function updateAddress(prevState: Awaited<State>, formData: FormData): Promise<State> {
+export async function updateAddress(
+  fields: Array<Field | FieldGroup<Field>>,
+  prevState: Awaited<State>,
+  formData: FormData,
+): Promise<State> {
   const t = await getTranslations('Account.Addresses');
   const customerAccessToken = await getSessionCustomerAccessToken();
 
@@ -223,7 +227,7 @@ export async function updateAddress(prevState: Awaited<State>, formData: FormDat
   }
 
   try {
-    const input = parseUpdateAddressInput(submission.value, prevState.fields);
+    const input = parseUpdateAddressInput(submission.value, fields);
 
     const response = await client.fetch({
       document: UpdateCustomerAddressMutation,
@@ -251,7 +255,6 @@ export async function updateAddress(prevState: Awaited<State>, formData: FormDat
       ),
       lastResult: submission.reply({ resetForm: true }),
       defaultAddress: prevState.defaultAddress,
-      fields: prevState.fields,
     };
   } catch (error) {
     // eslint-disable-next-line no-console

core/app/[locale]/(default)/gift-certificates/purchase/_actions/add-to-cart.tsx

@@ -7,7 +7,8 @@ import { getFormatter, getTranslations } from 'next-intl/server';
 import { ReactNode } from 'react';
 import { z } from 'zod';
 
-import { Field, FieldGroup } from '@/vibes/soul/form/dynamic-form/schema';
+import { DynamicFormActionArgs } from '@/vibes/soul/form/dynamic-form';
+import { Field } from '@/vibes/soul/form/dynamic-form/schema';
 import { client } from '~/client';
 import { graphql, ResultOf } from '~/client/graphql';
 import { ExistingResultType } from '~/client/util';
@@ -19,7 +20,6 @@ import { getPreferredCurrencyCode } from '~/lib/currency';
 import { GiftCertificateSettingsFragment } from '../fragment';
 
 interface State {
-  fields: Array<Field | FieldGroup<Field>>;
   lastResult: SubmissionResult | null;
   successMessage?: ReactNode;
 }
@@ -100,8 +100,9 @@ const schema = (
     });
 };
 
-export async function addGiftCertificateToCart(
-  prevState: State,
+export async function addGiftCertificateToCart<F extends Field>(
+  _args: DynamicFormActionArgs<F>,
+  _prevState: State,
   formData: FormData,
 ): Promise<State> {
   const t = await getTranslations('GiftCertificates.Purchase');
@@ -117,7 +118,7 @@ export async function addGiftCertificateToCart(
   });
 
   if (submission.status !== 'success') {
-    return { lastResult: submission.reply(), fields: prevState.fields };
+    return { lastResult: submission.reply() };
   }
 
   const amountFormatted = format.number(submission.value.amount, {
@@ -148,7 +149,6 @@ export async function addGiftCertificateToCart(
 
     return {
       lastResult: submission.reply(),
-      fields: prevState.fields,
       successMessage: t.rich('successMessage', {
         cartLink: (chunks) => (
           <Link className="underline" href="/cart" prefetch="viewport" prefetchKind="full">
@@ -168,27 +168,23 @@ export async function addGiftCertificateToCart(
             return message;
           }),
         }),
-        fields: prevState.fields,
       };
     }
 
     if (error instanceof MissingCartError) {
       return {
         lastResult: submission.reply({ formErrors: [t('missingCart')] }),
-        fields: prevState.fields,
       };
     }
 
     if (error instanceof Error) {
       return {
         lastResult: submission.reply({ formErrors: [error.message] }),
-        fields: prevState.fields,
       };
     }
 
     return {
       lastResult: submission.reply({ formErrors: [t('unknownError')] }),
-      fields: prevState.fields,
     };
   }
 }