@jmruthers/pace-core 0.5.1 → 0.5.4

package/src/components/Form/Form.test.tsx

@@ -0,0 +1,1158 @@
+/**
+ * @file Form Component Tests
+ * @package @jmruthers/pace-core
+ * @module Components/Form
+ * @since 0.1.0
+ *
+ * Comprehensive test suite for the Form component and its sub-components.
+ * Tests form rendering, validation, submission, and accessibility.
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { render, screen, fireEvent, waitFor, act } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { z } from 'zod';
+import { Form, FormField, FormFieldset, FormErrorSummary, FormLiveRegion } from './index';
+import { renderWithProviders } from '../../__tests__/helpers/test-utils';
+
+// Mock the cn utility
+vi.mock('../../utils/cn', () => ({
+  cn: (...classes: (string | undefined)[]) => classes.filter(Boolean).join(' ')
+}));
+
+// Mock the Label component
+vi.mock('../Label', () => ({
+  Label: ({ children, htmlFor, ...props }: any) => (
+    <label htmlFor={htmlFor} {...props}>
+      {children}
+    </label>
+  )
+}));
+
+// Mock the Alert component
+vi.mock('../Alert', () => ({
+  Alert: ({ children, variant, className, ...props }: any) => (
+    <div role="alert" className={`alert alert-${variant} ${className || ''}`} {...props}>
+      {children}
+    </div>
+  )
+}));
+
+describe('Form Component', () => {
+  const user = userEvent.setup();
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe('Rendering', () => {
+    it('renders with basic props', () => {
+      const onSubmit = vi.fn();
+      
+      renderWithProviders(
+        <Form onSubmit={onSubmit}>
+          <FormField name="test" label="Test Field" />
+        </Form>
+      );
+      
+      const form = document.querySelector('form');
+      expect(form).toBeInTheDocument();
+      expect(screen.getByLabelText('Test Field')).toBeInTheDocument();
+    });
+
+    it('renders with custom className', () => {
+      const onSubmit = vi.fn();
+      
+      renderWithProviders(
+        <Form onSubmit={onSubmit} className="custom-form">
+          <FormField name="test" label="Test Field" />
+        </Form>
+      );
+      
+      const form = document.querySelector('form');
+      expect(form).toHaveClass('custom-form');
+    });
+
+    it('renders with children function', () => {
+      const onSubmit = vi.fn();
+      const childrenFn = vi.fn().mockReturnValue(
+        <FormField name="test" label="Test Field" />
+      );
+      
+      renderWithProviders(
+        <Form onSubmit={onSubmit}>
+          {childrenFn}
+        </Form>
+      );
+      
+      expect(childrenFn).toHaveBeenCalledWith(
+        expect.objectContaining({
+          control: expect.any(Object),
+          formState: expect.any(Object),
+          handleSubmit: expect.any(Function)
+        })
+      );
+      expect(screen.getByLabelText('Test Field')).toBeInTheDocument();
+    });
+
+    it('renders with default values', () => {
+      const onSubmit = vi.fn();
+      const defaultValues = { name: 'John', email: 'john@example.com' };
+      
+      renderWithProviders(
+        <Form onSubmit={onSubmit} defaultValues={defaultValues}>
+          <FormField name="name" label="Name" />
+          <FormField name="email" label="Email" />
+        </Form>
+      );
+      
+      expect(screen.getByDisplayValue('John')).toBeInTheDocument();
+      expect(screen.getByDisplayValue('john@example.com')).toBeInTheDocument();
+    });
+  });
+
+  describe('Form Submission', () => {
+    it('calls onSubmit when form is submitted successfully', async () => {
+      const onSubmit = vi.fn();
+      const schema = z.object({
+        name: z.string().min(1, 'Name is required')
+      });
+      
+      renderWithProviders(
+        <Form schema={schema} onSubmit={onSubmit}>
+          <FormField name="name" label="Name" />
+          <button type="submit">Submit</button>
+        </Form>
+      );
+      
+      await user.type(screen.getByLabelText('Name'), 'John Doe');
+      await user.click(screen.getByRole('button', { name: 'Submit' }));
+      
+      expect(onSubmit).toHaveBeenCalledWith({ name: 'John Doe' }, expect.any(Object));
+    });
+
+    it('calls onError when form has validation errors', async () => {
+      const onSubmit = vi.fn();
+      const onError = vi.fn();
+      const schema = z.object({
+        name: z.string().min(1, 'Name is required')
+      });
+      
+      renderWithProviders(
+        <Form schema={schema} onSubmit={onSubmit} onError={onError}>
+          <FormField name="name" label="Name" />
+          <button type="submit">Submit</button>
+        </Form>
+      );
+      
+      await user.click(screen.getByRole('button', { name: 'Submit' }));
+      
+      expect(onError).toHaveBeenCalledWith(
+        expect.objectContaining({
+          name: expect.objectContaining({
+            message: 'Required'
+          })
+        }),
+        expect.any(Object)
+      );
+      expect(onSubmit).not.toHaveBeenCalled();
+    });
+
+    it('handles form submission without schema', async () => {
+      const onSubmit = vi.fn();
+      
+      renderWithProviders(
+        <Form onSubmit={onSubmit}>
+          <FormField name="name" label="Name" />
+          <button type="submit">Submit</button>
+        </Form>
+      );
+      
+      await user.type(screen.getByLabelText('Name'), 'John Doe');
+      await user.click(screen.getByRole('button', { name: 'Submit' }));
+      
+      expect(onSubmit).toHaveBeenCalledWith({ name: 'John Doe' }, expect.any(Object));
+    });
+  });
+
+  describe('Validation Modes', () => {
+    it('validates on submit by default', async () => {
+      const onSubmit = vi.fn();
+      const schema = z.object({
+        name: z.string().min(1, 'Name is required')
+      });
+      
+      renderWithProviders(
+        <Form schema={schema} onSubmit={onSubmit}>
+          <FormField name="name" label="Name" />
+          <button type="submit">Submit</button>
+        </Form>
+      );
+      
+      // Type and clear to trigger validation
+      await user.type(screen.getByLabelText('Name'), 'John');
+      await user.clear(screen.getByLabelText('Name'));
+      await user.click(screen.getByRole('button', { name: 'Submit' }));
+      
+      expect(screen.getByText('Name is required')).toBeInTheDocument();
+    });
+
+    it('validates on change when mode is onChange', async () => {
+      const onSubmit = vi.fn();
+      const schema = z.object({
+        name: z.string().min(1, 'Name is required')
+      });
+      
+      renderWithProviders(
+        <Form schema={schema} onSubmit={onSubmit} mode="onChange">
+          <FormField name="name" label="Name" />
+          <button type="submit">Submit</button>
+        </Form>
+      );
+      
+      // Type and clear to trigger validation
+      await user.type(screen.getByLabelText('Name'), 'John');
+      await user.clear(screen.getByLabelText('Name'));
+      
+      await waitFor(() => {
+        expect(screen.getByText('Name is required')).toBeInTheDocument();
+      });
+    });
+
+    it('validates on blur when mode is onBlur', async () => {
+      const onSubmit = vi.fn();
+      const schema = z.object({
+        name: z.string().min(1, 'Name is required')
+      });
+      
+      renderWithProviders(
+        <Form schema={schema} onSubmit={onSubmit} mode="onBlur">
+          <FormField name="name" label="Name" />
+          <button type="submit">Submit</button>
+        </Form>
+      );
+      
+      // Focus and blur to trigger validation
+      await user.click(screen.getByLabelText('Name'));
+      await user.tab();
+      
+      await waitFor(() => {
+        expect(screen.getByText('Required')).toBeInTheDocument();
+      });
+    });
+  });
+
+  describe('Accessibility', () => {
+    it('has proper form structure', () => {
+      const onSubmit = vi.fn();
+      
+      renderWithProviders(
+        <Form onSubmit={onSubmit}>
+          <FormField name="name" label="Name" />
+          <button type="submit">Submit</button>
+        </Form>
+      );
+      
+      const form = document.querySelector('form');
+      expect(form).toBeInTheDocument();
+      expect(form).toHaveAttribute('class', 'space-y-4');
+    });
+
+    it('provides form context to children', () => {
+      const onSubmit = vi.fn();
+      const childrenFn = vi.fn().mockReturnValue(
+        <FormField name="test" label="Test Field" />
+      );
+      
+      renderWithProviders(
+        <Form onSubmit={onSubmit}>
+          {childrenFn}
+        </Form>
+      );
+      
+      expect(childrenFn).toHaveBeenCalledWith(
+        expect.objectContaining({
+          control: expect.any(Object),
+          formState: expect.any(Object),
+          handleSubmit: expect.any(Function),
+          register: expect.any(Function),
+          watch: expect.any(Function),
+          setValue: expect.any(Function),
+          getValues: expect.any(Function),
+          reset: expect.any(Function)
+        })
+      );
+    });
+  });
+
+  describe('Edge Cases', () => {
+    it('handles empty children', () => {
+      const onSubmit = vi.fn();
+      
+      renderWithProviders(
+        <Form onSubmit={onSubmit}>
+          {null}
+        </Form>
+      );
+      
+      const form = document.querySelector('form');
+      expect(form).toBeInTheDocument();
+    });
+
+    it('handles undefined schema', () => {
+      const onSubmit = vi.fn();
+      
+      renderWithProviders(
+        <Form onSubmit={onSubmit} schema={undefined}>
+          <FormField name="test" label="Test Field" />
+        </Form>
+      );
+      
+      const form = document.querySelector('form');
+      expect(form).toBeInTheDocument();
+    });
+
+    it('handles complex nested data', async () => {
+      const onSubmit = vi.fn();
+      const schema = z.object({
+        user: z.object({
+          name: z.string(),
+          email: z.string().email()
+        }),
+        preferences: z.object({
+          theme: z.string(),
+          notifications: z.boolean().optional()
+        })
+      });
+      
+      renderWithProviders(
+        <Form schema={schema} onSubmit={onSubmit}>
+          <FormField name="user.name" label="Name" />
+          <FormField name="user.email" label="Email" />
+          <FormField name="preferences.theme" label="Theme" />
+          <button type="submit">Submit</button>
+        </Form>
+      );
+      
+      await user.type(screen.getByLabelText('Name'), 'John');
+      await user.type(screen.getByLabelText('Email'), 'john@example.com');
+      await user.type(screen.getByLabelText('Theme'), 'dark');
+      await user.click(screen.getByRole('button', { name: 'Submit' }));
+      
+      expect(onSubmit).toHaveBeenCalledWith({
+        user: {
+          name: 'John',
+          email: 'john@example.com'
+        },
+        preferences: {
+          theme: 'dark',
+          notifications: undefined
+        }
+      }, expect.any(Object));
+    });
+  });
+});
+
+describe('FormField Component', () => {
+  const user = userEvent.setup();
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe('Rendering', () => {
+    it('renders with basic props', () => {
+      const onSubmit = vi.fn();
+      
+      renderWithProviders(
+        <Form onSubmit={onSubmit}>
+          <FormField name="test" label="Test Field" />
+        </Form>
+      );
+      
+      const input = screen.getByLabelText('Test Field');
+      expect(input).toBeInTheDocument();
+      expect(input).toHaveAttribute('name', 'test');
+      expect(input).toHaveAttribute('id', 'test');
+    });
+
+    it('renders with custom type', () => {
+      const onSubmit = vi.fn();
+      
+      renderWithProviders(
+        <Form onSubmit={onSubmit}>
+          <FormField name="email" label="Email" type="email" />
+        </Form>
+      );
+      
+      const input = screen.getByLabelText('Email');
+      expect(input).toHaveAttribute('type', 'email');
+    });
+
+    it('renders with placeholder', () => {
+      const onSubmit = vi.fn();
+      
+      renderWithProviders(
+        <Form onSubmit={onSubmit}>
+          <FormField name="test" label="Test Field" placeholder="Enter text" />
+        </Form>
+      );
+      
+      const input = screen.getByLabelText('Test Field');
+      expect(input).toHaveAttribute('placeholder', 'Enter text');
+    });
+
+    it('renders with custom className', () => {
+      const onSubmit = vi.fn();
+      
+      renderWithProviders(
+        <Form onSubmit={onSubmit}>
+          <FormField name="test" label="Test Field" className="custom-field" />
+        </Form>
+      );
+      
+      const fieldContainer = screen.getByLabelText('Test Field').closest('div');
+      expect(fieldContainer).toHaveClass('custom-field');
+    });
+
+    it('renders with test ID', () => {
+      const onSubmit = vi.fn();
+      
+      renderWithProviders(
+        <Form onSubmit={onSubmit}>
+          <FormField name="test" label="Test Field" data-testid="test-field" />
+        </Form>
+      );
+      
+      const input = screen.getByTestId('test-field');
+      expect(input).toBeInTheDocument();
+    });
+  });
+
+  describe('Validation', () => {
+    it('shows required indicator when validation.required is true', () => {
+      const onSubmit = vi.fn();
+      
+      renderWithProviders(
+        <Form onSubmit={onSubmit}>
+          <FormField 
+            name="test" 
+            label="Test Field" 
+            validation={{ required: true }}
+          />
+        </Form>
+      );
+      
+      expect(screen.getByText('*')).toBeInTheDocument();
+      expect(screen.getByText('*')).toHaveAttribute('aria-label', 'required');
+    });
+
+    it('shows error message when validation fails', async () => {
+      const onSubmit = vi.fn();
+      const schema = z.object({
+        test: z.string().min(1, 'Field is required')
+      });
+      
+      renderWithProviders(
+        <Form schema={schema} onSubmit={onSubmit}>
+          <FormField name="test" label="Test Field" />
+          <button type="submit">Submit</button>
+        </Form>
+      );
+      
+      await user.click(screen.getByRole('button', { name: 'Submit' }));
+      
+      expect(screen.getByText('Required')).toBeInTheDocument();
+      expect(screen.getByText('Required')).toHaveAttribute('role', 'alert');
+    });
+
+    it('applies error styling when field has error', async () => {
+      const onSubmit = vi.fn();
+      const schema = z.object({
+        test: z.string().min(1, 'Field is required')
+      });
+      
+      renderWithProviders(
+        <Form schema={schema} onSubmit={onSubmit}>
+          <FormField name="test" label="Test Field" />
+          <button type="submit">Submit</button>
+        </Form>
+      );
+      
+      await user.click(screen.getByRole('button', { name: 'Submit' }));
+      
+      const input = screen.getByLabelText('Test Field');
+      expect(input).toHaveClass('border-destructive', 'focus-visible:ring-destructive');
+    });
+
+    it('validates with custom validation rules', async () => {
+      const onSubmit = vi.fn();
+      
+      renderWithProviders(
+        <Form onSubmit={onSubmit}>
+          <FormField 
+            name="test" 
+            label="Test Field"
+            validation={{
+              required: true,
+              minLength: {
+                value: 3,
+                message: 'Must be at least 3 characters'
+              }
+            }}
+          />
+          <button type="submit">Submit</button>
+        </Form>
+      );
+      
+      const input = screen.getByRole('textbox', { name: /test field/i });
+      await user.type(input, 'ab');
+      await user.click(screen.getByRole('button', { name: 'Submit' }));
+      
+      expect(screen.getByText('Must be at least 3 characters')).toBeInTheDocument();
+    });
+  });
+
+  describe('Custom Render Function', () => {
+    it('renders custom input when render function is provided', () => {
+      const onSubmit = vi.fn();
+      const renderFn = vi.fn().mockReturnValue(
+        <input data-testid="custom-input" />
+      );
+      
+      renderWithProviders(
+        <Form onSubmit={onSubmit}>
+          <FormField name="test" label="Test Field" render={renderFn} />
+        </Form>
+      );
+      
+      expect(renderFn).toHaveBeenCalledWith({
+        field: expect.objectContaining({
+          name: 'test',
+          value: undefined,
+          onChange: expect.any(Function),
+          onBlur: expect.any(Function),
+          ref: expect.any(Function)
+        })
+      });
+      expect(screen.getByTestId('custom-input')).toBeInTheDocument();
+    });
+  });
+
+  describe('Accessibility', () => {
+    it('associates label with input', () => {
+      const onSubmit = vi.fn();
+      
+      renderWithProviders(
+        <Form onSubmit={onSubmit}>
+          <FormField name="test" label="Test Field" />
+        </Form>
+      );
+      
+      const input = screen.getByLabelText('Test Field');
+      expect(input).toHaveAttribute('id', 'test');
+    });
+
+    it('shows error message with proper role', async () => {
+      const onSubmit = vi.fn();
+      const schema = z.object({
+        test: z.string().min(1, 'Field is required')
+      });
+      
+      renderWithProviders(
+        <Form schema={schema} onSubmit={onSubmit}>
+          <FormField name="test" label="Test Field" />
+          <button type="submit">Submit</button>
+        </Form>
+      );
+      
+      await user.click(screen.getByRole('button', { name: 'Submit' }));
+      
+      const errorMessage = screen.getByText('Required');
+      expect(errorMessage).toHaveAttribute('role', 'alert');
+    });
+  });
+});
+
+describe('FormFieldset Component', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe('Rendering', () => {
+    it('renders with legend', () => {
+      renderWithProviders(
+        <FormFieldset legend="Personal Information">
+          <div>Field content</div>
+        </FormFieldset>
+      );
+      
+      expect(screen.getByText('Personal Information')).toBeInTheDocument();
+      expect(screen.getByRole('group')).toBeInTheDocument();
+    });
+
+    it('renders with description', () => {
+      renderWithProviders(
+        <FormFieldset 
+          legend="Personal Information"
+          description="Please provide your personal details"
+        >
+          <div>Field content</div>
+        </FormFieldset>
+      );
+      
+      expect(screen.getByText('Please provide your personal details')).toBeInTheDocument();
+    });
+
+    it('renders with required indicator', () => {
+      renderWithProviders(
+        <FormFieldset legend="Personal Information" required>
+          <div>Field content</div>
+        </FormFieldset>
+      );
+      
+      expect(screen.getByText('*')).toBeInTheDocument();
+    });
+
+    it('renders with custom className', () => {
+      renderWithProviders(
+        <FormFieldset 
+          legend="Personal Information" 
+          className="custom-fieldset"
+        >
+          <div>Field content</div>
+        </FormFieldset>
+      );
+      
+      const fieldset = screen.getByRole('group');
+      expect(fieldset).toHaveClass('custom-fieldset');
+    });
+
+    it('forwards ref correctly', () => {
+      const ref = { current: null };
+      
+      renderWithProviders(
+        <FormFieldset legend="Personal Information" ref={ref}>
+          <div>Field content</div>
+        </FormFieldset>
+      );
+      
+      expect(ref.current).toBeInstanceOf(HTMLFieldSetElement);
+    });
+  });
+
+  describe('Accessibility', () => {
+    it('has proper ARIA attributes', () => {
+      renderWithProviders(
+        <FormFieldset 
+          legend="Personal Information"
+          description="Please provide your personal details"
+        >
+          <div>Field content</div>
+        </FormFieldset>
+      );
+      
+      const fieldset = screen.getByRole('group');
+      const description = screen.getByText('Please provide your personal details');
+      
+      expect(fieldset).toHaveAttribute('aria-describedby', description.id);
+    });
+
+    it('has proper semantic structure', () => {
+      renderWithProviders(
+        <FormFieldset legend="Personal Information">
+          <div>Field content</div>
+        </FormFieldset>
+      );
+      
+      const fieldset = screen.getByRole('group');
+      const legend = screen.getByText('Personal Information');
+      
+      expect(fieldset).toBeInTheDocument();
+      expect(legend).toBeInTheDocument();
+    });
+  });
+});
+
+describe('FormErrorSummary Component', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe('Rendering', () => {
+    it('renders nothing when no errors', () => {
+      renderWithProviders(
+        <FormErrorSummary errors={{}} />
+      );
+      
+      expect(screen.queryByRole('alert')).not.toBeInTheDocument();
+    });
+
+    it('renders with default title', () => {
+      const errors = {
+        name: { message: 'Name is required' },
+        email: { message: 'Email is invalid' }
+      };
+      
+      renderWithProviders(
+        <FormErrorSummary errors={errors} />
+      );
+      
+      expect(screen.getByText('Please fix the following errors:')).toBeInTheDocument();
+      expect(screen.getByText('Name is required')).toBeInTheDocument();
+      expect(screen.getByText('Email is invalid')).toBeInTheDocument();
+    });
+
+    it('renders with custom title', () => {
+      const errors = {
+        name: { message: 'Name is required' }
+      };
+      
+      renderWithProviders(
+        <FormErrorSummary 
+          errors={errors} 
+          title="Please correct these issues:"
+        />
+      );
+      
+      expect(screen.getByText('Please correct these issues:')).toBeInTheDocument();
+    });
+
+    it('renders with field names when showFieldNames is true', () => {
+      const errors = {
+        name: { message: 'Name is required' },
+        email: { message: 'Email is invalid' }
+      };
+      
+      renderWithProviders(
+        <FormErrorSummary 
+          errors={errors} 
+          showFieldNames={true}
+        />
+      );
+      
+      expect(screen.getByText('name: Name is required')).toBeInTheDocument();
+      expect(screen.getByText('email: Email is invalid')).toBeInTheDocument();
+    });
+
+    it('filters out empty errors', () => {
+      const errors = {
+        name: { message: 'Name is required' },
+        email: null,
+        phone: undefined,
+        address: ''
+      };
+      
+      renderWithProviders(
+        <FormErrorSummary errors={errors} />
+      );
+      
+      expect(screen.getByText('Name is required')).toBeInTheDocument();
+      expect(screen.queryByText('email:')).not.toBeInTheDocument();
+    });
+  });
+
+  describe('Error Message Handling', () => {
+    it('handles string error messages', () => {
+      const errors = {
+        name: 'Name is required'
+      };
+      
+      renderWithProviders(
+        <FormErrorSummary errors={errors} />
+      );
+      
+      expect(screen.getByText('Name is required')).toBeInTheDocument();
+    });
+
+    it('handles object error messages', () => {
+      const errors = {
+        name: { message: 'Name is required' }
+      };
+      
+      renderWithProviders(
+        <FormErrorSummary errors={errors} />
+      );
+      
+      expect(screen.getByText('Name is required')).toBeInTheDocument();
+    });
+  });
+});
+
+describe('FormLiveRegion Component', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  describe('Rendering', () => {
+    it('renders nothing when no message', () => {
+      const mockForm = {
+        formState: {
+          isSubmitting: false,
+          isSubmitSuccessful: false,
+          errors: {},
+          isValid: false,
+          isDirty: false
+        }
+      } as any;
+      
+      renderWithProviders(
+        <FormLiveRegion form={mockForm} />
+      );
+      
+      expect(screen.queryByRole('status')).not.toBeInTheDocument();
+    });
+
+    it('renders with default politeness', () => {
+      const mockForm = {
+        formState: {
+          isSubmitting: true,
+          isSubmitSuccessful: false,
+          errors: {},
+          isValid: false,
+          isDirty: false
+        }
+      } as any;
+      
+      renderWithProviders(
+        <FormLiveRegion form={mockForm} />
+      );
+      
+      const liveRegion = screen.getByRole('status');
+      expect(liveRegion).toHaveAttribute('aria-live', 'polite');
+    });
+
+    it('renders with custom politeness', () => {
+      const mockForm = {
+        formState: {
+          isSubmitting: true,
+          isSubmitSuccessful: false,
+          errors: {},
+          isValid: false,
+          isDirty: false
+        }
+      } as any;
+      
+      renderWithProviders(
+        <FormLiveRegion form={mockForm} politeness="assertive" />
+      );
+      
+      const liveRegion = screen.getByRole('status');
+      expect(liveRegion).toHaveAttribute('aria-live', 'assertive');
+    });
+  });
+
+  describe('Form State Announcements', () => {
+    it('announces submitting state', () => {
+      const mockForm = {
+        formState: {
+          isSubmitting: true,
+          isSubmitSuccessful: false,
+          errors: {},
+          isValid: false,
+          isDirty: false
+        }
+      } as any;
+      
+      renderWithProviders(
+        <FormLiveRegion form={mockForm} />
+      );
+      
+      expect(screen.getByText('Submitting form...')).toBeInTheDocument();
+    });
+
+    it('announces successful submission', async () => {
+      const mockForm = {
+        formState: {
+          isSubmitting: false,
+          isSubmitSuccessful: true,
+          errors: {},
+          isValid: false,
+          isDirty: false
+        }
+      } as any;
+      
+      renderWithProviders(
+        <FormLiveRegion form={mockForm} />
+      );
+      
+      // Advance timers to trigger the timeout
+      await act(async () => {
+        vi.advanceTimersByTime(500);
+      });
+      
+      // The message should be set after the timeout
+      expect(screen.getByRole('status')).toHaveTextContent('Form submitted successfully');
+    });
+
+    it('announces custom success message', async () => {
+      const mockForm = {
+        formState: {
+          isSubmitting: false,
+          isSubmitSuccessful: true,
+          errors: {},
+          isValid: false,
+          isDirty: false
+        }
+      } as any;
+      
+      renderWithProviders(
+        <FormLiveRegion 
+          form={mockForm} 
+          successMessage="Your data was saved successfully!"
+        />
+      );
+      
+      await act(async () => {
+        vi.advanceTimersByTime(500);
+      });
+      
+      expect(screen.getByRole('status')).toHaveTextContent('Your data was saved successfully!');
+    });
+
+    it('announces form errors', async () => {
+      const mockForm = {
+        formState: {
+          isSubmitting: false,
+          isSubmitSuccessful: false,
+          errors: {
+            name: { message: 'Name is required' },
+            email: { message: 'Email is invalid' }
+          },
+          isValid: false,
+          isDirty: false,
+          touchedFields: {}
+        }
+      } as any;
+      
+      renderWithProviders(
+        <FormLiveRegion form={mockForm} />
+      );
+      
+      // Error messages are set immediately without a timeout
+      expect(screen.getByRole('status')).toHaveTextContent('Form has 2 errors in: name, email');
+    });
+
+    it('announces single error', async () => {
+      const mockForm = {
+        formState: {
+          isSubmitting: false,
+          isSubmitSuccessful: false,
+          errors: {
+            name: { message: 'Name is required' }
+          },
+          isValid: false,
+          isDirty: false,
+          touchedFields: {}
+        }
+      } as any;
+      
+      renderWithProviders(
+        <FormLiveRegion form={mockForm} />
+      );
+      
+      // Error messages are set immediately without a timeout
+      expect(screen.getByRole('status')).toHaveTextContent('Form has 1 error in: name');
+    });
+
+    it('announces valid form', () => {
+      const mockForm = {
+        formState: {
+          isSubmitting: false,
+          isSubmitSuccessful: false,
+          errors: {},
+          isValid: true,
+          isDirty: true
+        }
+      } as any;
+      
+      renderWithProviders(
+        <FormLiveRegion form={mockForm} />
+      );
+      
+      expect(screen.getByRole('status')).toHaveTextContent('Form is valid');
+    });
+  });
+
+  describe('Field-Level Announcements', () => {
+    it('announces field errors when enabled', async () => {
+      const mockForm = {
+        formState: {
+          isSubmitting: false,
+          isSubmitSuccessful: false,
+          errors: {
+            name: { message: 'Name is required' }
+          },
+          touchedFields: { name: true },
+          isValid: false,
+          isDirty: false
+        }
+      } as any;
+      
+      renderWithProviders(
+        <FormLiveRegion form={mockForm} enableFieldAnnouncements={true} />
+      );
+      
+      await act(async () => {
+        vi.advanceTimersByTime(500);
+      });
+      
+      expect(screen.getByRole('status')).toHaveTextContent('name: Name is required');
+    });
+
+    it('does not announce field errors when disabled', () => {
+      const mockForm = {
+        formState: {
+          isSubmitting: false,
+          isSubmitSuccessful: false,
+          errors: {
+            name: { message: 'Name is required' }
+          },
+          touchedFields: { name: true },
+          isValid: false,
+          isDirty: false
+        }
+      } as any;
+      
+      renderWithProviders(
+        <FormLiveRegion form={mockForm} enableFieldAnnouncements={false} />
+      );
+      
+      vi.advanceTimersByTime(500);
+      
+      expect(screen.queryByText('name: Name is required')).not.toBeInTheDocument();
+    });
+  });
+
+  describe('Accessibility', () => {
+    it('has proper ARIA attributes', () => {
+      const mockForm = {
+        formState: {
+          isSubmitting: true,
+          isSubmitSuccessful: false,
+          errors: {},
+          isValid: false,
+          isDirty: false
+        }
+      } as any;
+      
+      renderWithProviders(
+        <FormLiveRegion form={mockForm} />
+      );
+      
+      const liveRegion = screen.getByRole('status');
+      expect(liveRegion).toHaveAttribute('aria-live', 'polite');
+      expect(liveRegion).toHaveAttribute('aria-atomic', 'true');
+    });
+
+    it('is visually hidden', () => {
+      const mockForm = {
+        formState: {
+          isSubmitting: true,
+          isSubmitSuccessful: false,
+          errors: {},
+          isValid: false,
+          isDirty: false
+        }
+      } as any;
+      
+      renderWithProviders(
+        <FormLiveRegion form={mockForm} />
+      );
+      
+      const liveRegion = screen.getByRole('status');
+      expect(liveRegion).toHaveClass('sr-only');
+      expect(liveRegion.getAttribute('style')).toContain('position: absolute');
+      expect(liveRegion.getAttribute('style')).toContain('left: -10000px');
+      expect(liveRegion.getAttribute('style')).toContain('width: 1px');
+      expect(liveRegion.getAttribute('style')).toContain('height: 1px');
+      expect(liveRegion.getAttribute('style')).toContain('overflow: hidden');
+    });
+  });
+});
+
+describe('Integration', () => {
+  const user = userEvent.setup();
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('works with complete form setup', async () => {
+    const onSubmit = vi.fn();
+    const onError = vi.fn();
+    const schema = z.object({
+      name: z.string().min(1, 'Name is required'),
+      email: z.string().email('Invalid email'),
+      age: z.coerce.number().min(18, 'Must be at least 18')
+    });
+    
+    renderWithProviders(
+      <Form 
+        schema={schema} 
+        onSubmit={onSubmit} 
+        onError={onError}
+        defaultValues={{ name: '', email: '', age: 0 }}
+      >
+        <FormFieldset legend="Personal Information">
+          <FormField name="name" label="Name" />
+          <FormField name="email" label="Email" type="email" />
+          <FormField name="age" label="Age" type="number" />
+        </FormFieldset>
+        <FormErrorSummary />
+        <button type="submit">Submit</button>
+      </Form>
+    );
+    
+    // Fill out form
+    await user.type(screen.getByLabelText('Name'), 'John Doe');
+    await user.type(screen.getByLabelText('Email'), 'john@example.com');
+    await user.type(screen.getByLabelText('Age'), '25');
+    
+    // Submit form
+    await user.click(screen.getByRole('button', { name: 'Submit' }));
+    
+    // Wait for form submission
+    await waitFor(() => {
+      expect(onSubmit).toHaveBeenCalledWith({
+        name: 'John Doe',
+        email: 'john@example.com',
+        age: 25
+      }, expect.any(Object));
+    });
+    expect(onError).not.toHaveBeenCalled();
+  });
+
+  it('handles form errors with error summary', async () => {
+    const onSubmit = vi.fn();
+    const onError = vi.fn();
+    const schema = z.object({
+      name: z.string().min(1, 'Name is required'),
+      email: z.string().email('Invalid email')
+    });
+    
+    renderWithProviders(
+      <Form 
+        schema={schema} 
+        onSubmit={onSubmit} 
+        onError={onError}
+      >
+        <FormField name="name" label="Name" />
+        <FormField name="email" label="Email" type="email" />
+        <FormErrorSummary />
+        <button type="submit">Submit</button>
+      </Form>
+    );
+    
+    // Submit empty form
+    await user.click(screen.getByRole('button', { name: 'Submit' }));
+    
+    expect(onError).toHaveBeenCalled();
+    expect(screen.getAllByText('Required')).toHaveLength(2);
+  });
+});