## Validation Migration Plan: [FormName]

### Validation Sources Found

- [ ] Yup validationSchema: `path/to/schema.ts`
- [ ] Inline validate function: line XX
- [ ] Field-level validations: lines XX, YY
- [ ] No explicit validation (form relies on required HTML attributes)

### Field Validations

| Field | Yup Validation | Zod Equivalent | Custom Message |
| ----- | -------------- | -------------- | -------------- |
| ...   | ...            | ...            | ...            |

### Cross-Field Validations

| Fields Involved | Yup Logic | Zod .refine() Logic |
| --------------- | --------- | ------------------- |
| ...             | ...       | ...                 |

### Conditional Validations

| Condition | Affected Fields | Zod Implementation |
| --------- | --------------- | ------------------ |
| ...       | ...             | ...                |

### Async Validations

| Field | Current Implementation | TanStack Approach |
| ----- | ---------------------- | ----------------- |
| ...   | ...                    | ...               |

### Submit Button Disabled Logic

Current: `disabled={!formikProps.isValid || !formikProps.dirty || loading}`
TanStack: `form.SubmitButton` handles isValid + dirty automatically

### Validation Timing

- validateOnMount: [true/false]
- validateOnChange: [true/false]
- validateOnBlur: [true/false]

import { z } from 'zod'

// Import any enums from generated GraphQL if needed
import { SomeEnum } from '~/generated/graphql'

// Define field schemas
const fieldSchema = z.object({
  id: z.nativeEnum(SomeEnum),
  // ... other fields
})

// Main form schema - implement ALL validations from the plan
export const <formName>ValidationSchema = z.object({
  // Required string (was: yup.string().required())
  fieldName: z.string().min(1, 'Field is required'),

  // Optional string (was: yup.string())
  optionalField: z.string().optional(),

  // Email validation (was: yup.string().email().required())
  email: z.string().email('Invalid email').min(1, 'Email is required'),

  // Number with range (was: yup.number().min(0).max(100))
  percentage: z.number().min(0).max(100),

  // Enum (was: yup.string().oneOf([...]))
  status: z.nativeEnum(SomeEnum),

  // Array (was: yup.array().of(...))
  items: z.array(fieldSchema),
})
// Add cross-field validations from the plan
.refine(
  (data) => /* validation logic from plan */,
  { message: 'Error message', path: ['fieldName'] }
)

export type <FormName>Values = z.infer<typeof <formName>ValidationSchema>

- import { useFormik } from 'formik'
- import * as Yup from 'yup'  // Remove if present
+ import { revalidateLogic, useStore } from '@tanstack/react-form'
+ import { useAppForm } from '~/hooks/forms/useAppform'

import { <formName>ValidationSchema } from './<formName>/validationSchema'

const formikProps = useFormik<FormValues>({
  initialValues: { name: '', ... },
  validateOnMount: true,
  enableReinitialize: true,
  validationSchema: someSchema,
  onSubmit: async (values) => { ... }
})

const form = useAppForm({
  defaultValues: {
    name: existingData?.name || '',
    // ... other fields
  },
  validationLogic: revalidateLogic(),
  validators: {
    onDynamic: <formName>ValidationSchema,
  },
  onSubmit: async ({ value }) => {
    const { field1, field2, ...rest } = value
    // ... submit logic
  },
})

const someField = useStore(form.store, (state) => state.values.someField)

- <TextInputField
-   name="fieldName"
-   label={translate('...')}
-   formikProps={formikProps}
- />
+ <form.AppField name="fieldName">
+   {(field) => (
+     <field.TextInputField
+       label={translate('...')}
+     />
+   )}
+ </form.AppField>

const handleSubmit = (event: React.FormEvent) => {
  event.preventDefault()
  form.handleSubmit()
}

return (
  <form onSubmit={handleSubmit}>
    {/* form content */}
  </form>
)

- <Button
-   onClick={formikProps.submitForm}
-   disabled={!formikProps.isValid || (isEdition && !formikProps.dirty)}
- >
+ <form.AppForm>
+   <form.SubmitButton disabled={externalLoadingState}>
      {submitButtonText}
+   </form.SubmitButton>
+ </form.AppForm>

formikProps.setFieldValue('fieldName', newValue)

form.setFieldValue('fieldName', newValue)

formikProps.values.fieldName

field.state.value

const fieldValue = useStore(form.store, (state) => state.values.fieldName)

import { withForm } from '~/hooks/forms/useAppform'
import { emptyCreateCustomerDefaultValues } from './formInitialization/validationSchema'

// Define props interface
interface CustomerInformationProps {
  isEdition: boolean
  customer?: CustomerDetails
}

// Default props for the HOC
const defaultProps: CustomerInformationProps = {
  isEdition: false,
}

// Create the component using withForm
const CustomerInformation = withForm({
  defaultValues: emptyCreateCustomerDefaultValues,
  props: defaultProps,
  render: function Render({ form, isEdition, customer }) {
    return (
      <div>
        <form.AppField name="name">
          {(field) => (
            <field.TextInputField label="Name" />
          )}
        </form.AppField>
        {/* More fields... */}
      </div>
    )
  },
})

export default CustomerInformation

<CustomerInformation form={form} isEdition={isEdition} customer={customer} />

import { z } from 'zod'

// Nested object schema
const addressSchema = z.object({
  addressLine1: z.string().optional(),
  city: z.string().optional(),
  zipcode: z.string().optional(),
  country: z.string().optional(),
})

// Main schema with refinements
export const customerValidationSchema = z
  .object({
    name: z.string().min(1, 'Name is required'),
    externalId: z.string().min(1, 'External ID is required'),
    currency: z.string().optional(),
    timezone: z.string().optional(),
    billingConfiguration: z.object({
      documentLocale: z.string().optional(),
    }),
    shippingAddress: addressSchema,
    // ... more fields
  })
  .refine(
    (data) => {
      // Cross-field validation
      if (data.someCondition) {
        return data.relatedField !== undefined
      }
      return true
    },
    {
      message: 'Related field is required when condition is true',
      path: ['relatedField'],
    }
  )

// Export empty default values for typing
export const emptyDefaultValues: z.infer<typeof customerValidationSchema> = {
  name: '',
  externalId: '',
  currency: undefined,
  // ... all fields with default values
}

// mappers.ts
import type { CustomerFragment } from '~/generated/graphql'
import type { CustomerFormValues } from './validationSchema'

export const mapFromApiToForm = (customer: CustomerFragment): CustomerFormValues => ({
  name: customer.name || '',
  externalId: customer.externalId || '',
  currency: customer.currency || undefined,
  billingConfiguration: {
    documentLocale: customer.billingConfiguration?.documentLocale || undefined,
  },
  // ... transform nested objects
})

export const mapFromFormToApi = (values: CustomerFormValues): CreateCustomerInput => ({
  name: values.name,
  externalId: values.externalId,
  currency: values.currency || null,
  billingConfiguration: {
    documentLocale: values.billingConfiguration.documentLocale || null,
  },
  // ... transform back to API format
})

const form = useAppForm({
  defaultValues: customer
    ? mapFromApiToForm(customer)
    : emptyDefaultValues,
  // ...
  onSubmit: async ({ value }) => {
    const input = mapFromFormToApi(value)
    await createCustomer({ variables: { input } })
  },
})

const form = useAppForm({
  // ...
  onSubmit: async ({ value, formApi }) => {
    try {
      await createCustomer({ variables: { input: value } })
    } catch (error) {
      if (error instanceof ApolloError) {
        const serverErrors = parseServerErrors(error)

        // Set errors on specific fields
        formApi.setErrorMap({
          onSubmit: {
            fields: {
              externalId: serverErrors.externalId,
              email: serverErrors.email,
            },
          },
        })
      }
    }
  },
})

const form = useAppForm({
  // ...
  onSubmitInvalid: ({ formApi }) => {
    // Get the first field with an error
    const firstErrorField = Object.keys(formApi.state.fieldMeta).find(
      (key) => formApi.state.fieldMeta[key]?.errors?.length > 0
    )

    if (firstErrorField) {
      // Scroll to the error field
      const element = document.querySelector(`[name="${firstErrorField}"]`)
      element?.scrollIntoView({ behavior: 'smooth', block: 'center' })
    }
  },
})

const showBillingFields = useStore(
  form.store,
  (state) => state.values.customerType === 'business'
)

return (
  <>
    <form.AppField name="customerType">
      {(field) => <field.ComboBoxField options={customerTypes} />}
    </form.AppField>

    {showBillingFields && (
      <form.AppField name="vatNumber">
        {(field) => <field.TextInputField label="VAT Number" />}
      </form.AppField>
    )}
  </>
)

// Data-test attributes for testing
export const MY_FORM_TEST_ID = 'my-form'
export const MY_FORM_TITLE_TEST_ID = 'my-form-title'
export const MY_FORM_HEADLINE_TEST_ID = 'my-form-headline'
export const MY_FORM_DESCRIPTION_TEST_ID = 'my-form-description'
export const MY_FORM_NAME_INPUT_TEST_ID = 'my-form-name-input'
export const MY_FORM_SUBMIT_BUTTON_TEST_ID = 'my-form-submit-button'
export const MY_FORM_CANCEL_BUTTON_TEST_ID = 'my-form-cancel-button'
export const MY_FORM_CLOSE_BUTTON_TEST_ID = 'my-form-close-button'
export const MY_FORM_LOADING_SKELETON_TEST_ID = 'my-form-loading-skeleton'
// Add more as needed for sections, alerts, tables, etc.

// Form element
<form data-test={MY_FORM_TEST_ID} onSubmit={handleSubmit}>

// Typography/headings
<Typography data-test={MY_FORM_TITLE_TEST_ID} variant="bodyHl">
  {translate('...')}
</Typography>

// Buttons
<Button data-test={MY_FORM_CLOSE_BUTTON_TEST_ID} variant="quaternary" icon="close" />

// Form fields - use data-test prop
<form.AppField name="name">
  {(field) => (
    <field.TextInputField
      data-test={MY_FORM_NAME_INPUT_TEST_ID}
      label={translate('...')}
    />
  )}
</form.AppField>

// Submit button - use dataTest prop (note: camelCase)
<form.SubmitButton dataTest={MY_FORM_SUBMIT_BUTTON_TEST_ID}>
  {translate('...')}
</form.SubmitButton>

// For components that don't support data-test, extend them allowing dataTest as optional prop or, if not possible, wrap in a div as following
<div data-test={MY_FORM_TABLE_TEST_ID}>
  <Table ... />
</div>

import { render } from '~/test-utils'

import MyForm, {
  MY_FORM_CANCEL_BUTTON_TEST_ID,
  MY_FORM_CLOSE_BUTTON_TEST_ID,
  MY_FORM_DESCRIPTION_TEST_ID,
  MY_FORM_HEADLINE_TEST_ID,
  MY_FORM_NAME_INPUT_TEST_ID,
  MY_FORM_SUBMIT_BUTTON_TEST_ID,
  MY_FORM_TEST_ID,
  MY_FORM_TITLE_TEST_ID,
} from '../MyForm'

describe('MyForm', () => {
  it('renders form element', async () => {
    await act(() => render(<MyForm />))

    // ✅ CORRECT: Use data-test constants
    expect(screen.getByTestId(MY_FORM_TEST_ID)).toBeInTheDocument()
    expect(screen.getByTestId(MY_FORM_TITLE_TEST_ID)).toBeInTheDocument()
    expect(screen.getByTestId(MY_FORM_SUBMIT_BUTTON_TEST_ID)).toBeInTheDocument()
  })

  // ❌ WRONG: Never reference translation keys
  // expect(screen.getByText('text_123456789')).toBeInTheDocument()
})

// Get mocked useParams
const mockUseParams = jest.requireMock('react-router-dom').useParams as jest.Mock

// Mock translation
jest.mock('~/hooks/core/useInternationalization', () => ({
  useInternationalization: () => ({
    translate: (key: string) => key,
  }),
}))

// Mock navigation
const mockGoBack = jest.fn()
jest.mock('~/hooks/core/useLocationHistory', () => ({
  useLocationHistory: () => ({ goBack: mockGoBack }),
}))

// Mock toast
const mockAddToast = jest.fn()
jest.mock('~/core/apolloClient', () => ({
  ...jest.requireActual('~/core/apolloClient'),
  addToast: (params: unknown) => mockAddToast(params),
}))

// Mock ResizeObserver (for tables)
window.ResizeObserver = jest.fn().mockReturnValue({
  observe: jest.fn(),
  unobserve: jest.fn(),
  disconnect: jest.fn(),
})

describe('FormName', () => {
  beforeEach(() => {
    mockUseParams.mockReturnValue({ id: '' })
    // ... other mock setups
  })

  afterEach(() => {
    cleanup()
    jest.clearAllMocks()
  })

  describe('Create Mode', () => {
    it('renders form element', async () => {
      await act(() => render(<FormName />))
      expect(screen.getByTestId(FORM_TEST_ID)).toBeInTheDocument()
    })

    it('renders all form sections', async () => {
      await act(() => render(<FormName />))
      expect(screen.getByTestId(FORM_TITLE_TEST_ID)).toBeInTheDocument()
      expect(screen.getByTestId(FORM_HEADLINE_TEST_ID)).toBeInTheDocument()
      expect(screen.getByTestId(FORM_DESCRIPTION_TEST_ID)).toBeInTheDocument()
    })

    it('renders form fields', async () => {
      await act(() => render(<FormName />))
      expect(screen.getByTestId(FORM_NAME_INPUT_TEST_ID)).toBeInTheDocument()
    })

    it('renders action buttons', async () => {
      await act(() => render(<FormName />))
      expect(screen.getByTestId(FORM_SUBMIT_BUTTON_TEST_ID)).toBeInTheDocument()
      expect(screen.getByTestId(FORM_CANCEL_BUTTON_TEST_ID)).toBeInTheDocument()
    })

    it('allows input in fields', async () => {
      const user = userEvent.setup()
      await act(() => render(<FormName />))

      const inputContainer = screen.getByTestId(FORM_NAME_INPUT_TEST_ID)
      const input = inputContainer.querySelector('input')

      if (input) {
        await user.type(input, 'Test Value')
        expect(input).toHaveValue('Test Value')
      }
    })
  })

  describe('Edit Mode', () => {
    beforeEach(() => {
      mockUseParams.mockReturnValue({ id: 'item-123' })
      // Setup mock data
    })

    it('renders form in edit mode', async () => {
      await act(() => render(<FormName />))
      expect(screen.getByTestId(FORM_TEST_ID)).toBeInTheDocument()
    })
  })

  describe('Loading State', () => {
    it('shows loading skeleton when data is loading', async () => {
      // Set loading state in mocks
      await act(() => render(<FormName />))
      // Verify loading state - content should not be visible
      expect(screen.queryByTestId(FORM_HEADLINE_TEST_ID)).not.toBeInTheDocument()
    })
  })

  describe('Button Behavior', () => {
    it('calls goBack on cancel', async () => {
      const user = userEvent.setup()
      await act(() => render(<FormName />))

      const cancelButton = screen.getByTestId(FORM_CANCEL_BUTTON_TEST_ID)
      await user.click(cancelButton)

      expect(mockGoBack).toHaveBeenCalled()
    })
  })

  describe('Snapshot Tests', () => {
    it('matches snapshot in create mode', async () => {
      const { container } = await act(() => render(<FormName />))
      expect(container).toMatchSnapshot()
    })

    it('matches snapshot in edit mode', async () => {
      mockUseParams.mockReturnValue({ id: 'item-123' })
      // Setup mock data
      const { container } = await act(() => render(<FormName />))
      expect(container).toMatchSnapshot()
    })
  })
})

/migrate-formik-to-tanstack <path-to-formik-form>

/migrate-formik-to-tanstack src/pages/settings/SomeForm.tsx