docs: Add v7.0.0 migration guide for TypeScript users

Addresses #1054

Creates comprehensive migration guide documenting TypeScript-specific
breaking changes when upgrading from v6 to v7:

- FormState properties now optional (dirty, pristine, valid, etc.)
- FieldMetaState type no longer exported
- AnyObject type no longer exported
- UseFieldConfig no longer generic
- FormProps no longer accepts arbitrary props

Also includes final-form v5.0.0 changes and migration strategy.

Updates README with link to migration guide.

Author: erikras-gilfoyle-agent

MIGRATION_V7.md

@@ -0,0 +1,209 @@
+# Migration Guide: react-final-form v6 → v7
+
+## Overview
+
+Version 7.0.0 includes a complete TypeScript rewrite (migrated from Flow). While the runtime behavior remains largely unchanged, there are several TypeScript-specific breaking changes you need to be aware of.
+
+## Breaking Changes
+
+### 1. FormState Properties Now Optional
+
+In v7.0.0, most FormState boolean properties can be `undefined`:
+
+**❌ Before (v6.x):**
+```typescript
+const { dirty, pristine, valid } = formState;
+if (dirty && !pristine) { // Works fine
+  // ...
+}
+```
+
+**✅ After (v7.0.0):**
+```typescript
+const { dirty, pristine, valid } = formState;
+if ((dirty ?? false) && !(pristine ?? true)) { // Must handle undefined
+  // ...
+}
+```
+
+**Affected properties:**
+- `dirty`, `pristine`, `valid`, `invalid`
+- `dirtySinceLastSubmit`, `modifiedSinceLastSubmit`
+- `submitFailed`, `submitSucceeded`, `submitting`, `validating`
+- `hasSubmitErrors`, `hasValidationErrors`
+
+**Note:** `values` is still guaranteed to be defined.
+
+### 2. FieldMetaState Type No Longer Exported
+
+**❌ Before (v6.x):**
+```typescript
+import { FieldMetaState } from 'react-final-form';
+
+const meta: FieldMetaState = { /* ... */ };
+```
+
+**✅ After (v7.0.0):**
+```typescript
+import { FieldRenderProps } from 'react-final-form';
+
+const meta: FieldRenderProps<any>['meta'] = { /* ... */ };
+
+// Or define it locally:
+type FieldMetaState = {
+  active?: boolean;
+  data?: Record<string, any>;
+  dirty?: boolean;
+  // ... etc
+};
+```
+
+### 3. AnyObject Type No Longer Exported
+
+**❌ Before (v6.x):**
+```typescript
+import { AnyObject } from 'react-final-form';
+```
+
+**✅ After (v7.0.0):**
+```typescript
+// Define locally:
+type AnyObject = Record<string, any>;
+```
+
+### 4. UseFieldConfig No Longer Generic
+
+**❌ Before (v6.x):**
+```typescript
+const config: UseFieldConfig<string> = {
+  validate: (value) => value ? undefined : 'Required'
+};
+```
+
+**✅ After (v7.0.0):**
+```typescript
+const config: UseFieldConfig = {
+  validate: (value) => value ? undefined : 'Required'
+};
+```
+
+### 5. FormProps No Longer Accepts Arbitrary Props
+
+In v6.x, you could pass arbitrary props (like `style`, `className`) directly to `<Form>`. In v7.0.0, this is no longer supported due to stricter TypeScript typing.
+
+**❌ Before (v6.x):**
+```tsx
+<Form
+  onSubmit={handleSubmit}
+  style={{ padding: '20px' }}
+  className="my-form"
+>
+  {/* ... */}
+</Form>
+```
+
+**✅ After (v7.0.0):**
+```tsx
+<Form onSubmit={handleSubmit}>
+  {({ handleSubmit }) => (
+    <form onSubmit={handleSubmit} style={{ padding: '20px' }} className="my-form">
+      {/* ... */}
+    </form>
+  )}
+</Form>
+
+// Or wrap in a div:
+<div style={{ padding: '20px' }} className="my-form">
+  <Form onSubmit={handleSubmit}>
+    {/* ... */}
+  </Form>
+</div>
+```
+
+## final-form v5.0.0 Changes
+
+If you're also upgrading final-form to v5.0.0, be aware of these changes:
+
+### 1. InternalFormState Requires asyncErrors
+
+**❌ Before (v4.x):**
+```typescript
+const mockFormState: InternalFormState = {
+  values: {},
+  // ...
+};
+```
+
+**✅ After (v5.0.0):**
+```typescript
+const mockFormState: InternalFormState = {
+  values: {},
+  asyncErrors: {}, // Now required
+  // ...
+};
+```
+
+### 2. Mutator Type Signature Changed
+
+**❌ Before (v4.x):**
+```typescript
+const mutator: Mutator = (args, state, tools) => {
+  // ...
+};
+```
+
+**✅ After (v5.0.0):**
+```typescript
+// If you get type errors with existing mutators:
+const mutator = ((args, state, tools) => {
+  // ...
+}) as unknown as Mutator;
+```
+
+## Migration Strategy
+
+For a medium to large codebase, expect to modify 100+ files. Here's a recommended approach:
+
+1. **Update dependencies:**
+   ```bash
+   npm install react-final-form@^7.0.0 final-form@^5.0.0
+   ```
+
+2. **Fix compilation errors in this order:**
+   - Handle optional boolean properties (use `?? false` or `?? true`)
+   - Replace `FieldMetaState` imports with `FieldRenderProps['meta']`
+   - Replace `AnyObject` imports with local type definition
+   - Remove generic from `UseFieldConfig<T>` → `UseFieldConfig`
+   - Fix `<Form>` props (move styling to wrapper or inner `<form>`)
+
+3. **Test thoroughly:**
+   - All form submissions
+   - Validation behavior
+   - Field state management
+   - Meta information display
+
+4. **Update mocks/tests:**
+   - Add `asyncErrors: {}` to InternalFormState mocks
+   - Cast mutators if needed
+
+## Need Help?
+
+If you encounter issues during migration:
+
+1. Check the [TypeScript examples](https://github.com/final-form/react-final-form/tree/main/examples/typescript)
+2. Review [closed issues](https://github.com/final-form/react-final-form/issues?q=is%3Aissue+typescript)
+3. Open a [new issue](https://github.com/final-form/react-final-form/issues/new) with a reproduction
+
+## Benefits of v7.0.0
+
+Despite the migration effort, v7.0.0 brings significant benefits:
+
+- **Better TypeScript support** - First-class TypeScript instead of generated types from Flow
+- **Improved type inference** - Better autocomplete and type checking
+- **Modern codebase** - Easier for contributors to work with
+- **Long-term maintainability** - TypeScript ecosystem is more active than Flow
+
+---
+
+**Version**: 7.0.0  
+**Last Updated**: 2026-02-13

README.md

@@ -39,6 +39,10 @@ React Final Form is a thin React wrapper for [Final Form](https://final-form.org
 
 ## [Getting Started](https://final-form.org/docs/react-final-form/getting-started)
 
+## 🔄 Upgrading from v6 to v7?
+
+See the [Migration Guide](./MIGRATION_V7.md) for TypeScript-specific breaking changes and how to handle them.
+
 ## [Philosophy](https://final-form.org/docs/react-final-form/philosophy)
 
 ## [Examples](https://final-form.org/docs/react-final-form/examples)