@digigov/form 2.0.0-cbc56209 → 2.0.0-d2ffc726

package/src/hooks/__tests__/useFieldFocusManager.spec.tsx

@@ -0,0 +1,1079 @@
+import React from 'react';
+import {
+  renderHook,
+  act,
+  render,
+  screen,
+  fireEvent,
+  waitFor,
+} from '@testing-library/react';
+import { useForm, useFieldArray } from 'react-hook-form';
+import { expect } from 'vitest';
+
+import { useFieldFocusManager } from '@digigov/form/hooks/useFieldFocusManager';
+
+// Mock component that uses the hook
+function TestFormComponent({
+  enabled = true,
+  onRegisterElement,
+}: {
+  enabled?: boolean;
+  onRegisterElement?: (register: any) => void;
+}) {
+  const form = useForm({
+    defaultValues: {
+      firstName: '',
+      lastName: '',
+      email: '',
+    },
+    shouldFocusError: false, // Disable default focus behavior for testing
+  });
+
+  const { registerCustomFocusableElement, focusOnError } = useFieldFocusManager(
+    {
+      enabled,
+      control: form.control,
+      subscribe: form.subscribe,
+      setFocus: form.setFocus,
+    }
+  );
+
+  // Expose register function for testing
+  React.useEffect(() => {
+    if (onRegisterElement) {
+      onRegisterElement(registerCustomFocusableElement);
+    }
+  }, [registerCustomFocusableElement, onRegisterElement]);
+
+  return (
+    <form onSubmit={form.handleSubmit(() => {}, focusOnError)}>
+      <input
+        {...form.register('firstName', { required: 'First name is required' })}
+        data-testid="firstName"
+        placeholder="First Name"
+      />
+      <input
+        {...form.register('lastName', { required: 'Last name is required' })}
+        data-testid="lastName"
+        placeholder="Last Name"
+      />
+      <input
+        {...form.register('email', { required: 'Email is required' })}
+        data-testid="email"
+        placeholder="Email"
+      />
+      <button type="submit" data-testid="submit">
+        Submit
+      </button>
+    </form>
+  );
+}
+
+// FieldArray test component
+function TestFieldArrayComponent({
+  enabled = true,
+  onRegisterElement,
+}: {
+  enabled?: boolean;
+  onRegisterElement?: (register: any) => void;
+}) {
+  const form = useForm({
+    defaultValues: {
+      users: [{ name: '', email: '' }],
+      items: [{ title: '', description: '' }],
+    },
+    shouldFocusError: false,
+  });
+
+  const { fields: userFields, append: appendUser } = useFieldArray({
+    control: form.control,
+    name: 'users',
+  });
+
+  const { fields: itemFields, append: appendItem } = useFieldArray({
+    control: form.control,
+    name: 'items',
+  });
+
+  const { registerCustomFocusableElement, focusOnError } = useFieldFocusManager(
+    {
+      enabled,
+      control: form.control,
+      subscribe: form.subscribe,
+      setFocus: form.setFocus,
+    }
+  );
+
+  React.useEffect(() => {
+    if (onRegisterElement) {
+      onRegisterElement(registerCustomFocusableElement);
+    }
+  }, [registerCustomFocusableElement, onRegisterElement]);
+
+  return (
+    <form onSubmit={form.handleSubmit(() => {}, focusOnError)}>
+      <div data-testid="users-section">
+        {userFields.map((field, index) => (
+          <div key={field.id} data-testid={`user-${index}`}>
+            <input
+              {...form.register(`users.${index}.name`, {
+                required: 'Name is required',
+              })}
+              data-testid={`user-${index}-name`}
+              placeholder={`User ${index} Name`}
+            />
+            <input
+              {...form.register(`users.${index}.email`, {
+                required: 'Email is required',
+              })}
+              data-testid={`user-${index}-email`}
+              placeholder={`User ${index} Email`}
+            />
+          </div>
+        ))}
+        <button
+          type="button"
+          onClick={() => appendUser({ name: '', email: '' })}
+          data-testid="add-user"
+        >
+          Add User
+        </button>
+      </div>
+
+      <div data-testid="items-section">
+        {itemFields.map((field, index) => (
+          <div key={field.id} data-testid={`item-${index}`}>
+            <input
+              {...form.register(`items.${index}.title`, {
+                required: 'Title is required',
+              })}
+              data-testid={`item-${index}-title`}
+              placeholder={`Item ${index} Title`}
+            />
+            <input
+              {...form.register(`items.${index}.description`)}
+              data-testid={`item-${index}-description`}
+              placeholder={`Item ${index} Description`}
+            />
+          </div>
+        ))}
+        <button
+          type="button"
+          onClick={() => appendItem({ title: '', description: '' })}
+          data-testid="add-item"
+        >
+          Add Item
+        </button>
+      </div>
+
+      <button type="submit" data-testid="submit">
+        Submit
+      </button>
+    </form>
+  );
+}
+
+// Nested FieldArray component
+function TestNestedFieldArrayComponent() {
+  const form = useForm({
+    defaultValues: {
+      projects: [
+        {
+          name: '',
+          tasks: [{ title: '', assignee: '' }],
+        },
+      ],
+    },
+    shouldFocusError: false,
+  });
+
+  const { fields: projectFields, append: appendProject } = useFieldArray({
+    control: form.control,
+    name: 'projects',
+  });
+
+  const { focusOnError } = useFieldFocusManager({
+    control: form.control,
+    subscribe: form.subscribe,
+    setFocus: form.setFocus,
+  });
+
+  return (
+    <form onSubmit={form.handleSubmit(() => {}, focusOnError)}>
+      {projectFields.map((projectField, projectIndex) => (
+        <div key={projectField.id} data-testid={`project-${projectIndex}`}>
+          <input
+            {...form.register(`projects.${projectIndex}.name`, {
+              required: 'Project name is required',
+            })}
+            data-testid={`project-${projectIndex}-name`}
+            placeholder={`Project ${projectIndex} Name`}
+          />
+
+          <NestedTasksFieldArray
+            control={form.control}
+            register={form.register}
+            projectIndex={projectIndex}
+          />
+        </div>
+      ))}
+
+      <button
+        type="button"
+        onClick={() =>
+          appendProject({ name: '', tasks: [{ title: '', assignee: '' }] })
+        }
+        data-testid="add-project"
+      >
+        Add Project
+      </button>
+
+      <button type="submit" data-testid="submit">
+        Submit
+      </button>
+    </form>
+  );
+}
+
+function NestedTasksFieldArray({
+  control,
+  register,
+  projectIndex,
+}: {
+  control: any;
+  register: any;
+  projectIndex: number;
+}) {
+  const { fields: taskFields, append: appendTask } = useFieldArray({
+    control,
+    name: `projects.${projectIndex}.tasks`,
+  });
+
+  return (
+    <div data-testid={`project-${projectIndex}-tasks`}>
+      {taskFields.map((taskField, taskIndex) => (
+        <div
+          key={taskField.id}
+          data-testid={`project-${projectIndex}-task-${taskIndex}`}
+        >
+          <input
+            {...register(`projects.${projectIndex}.tasks.${taskIndex}.title`, {
+              required: 'Task title is required',
+            })}
+            data-testid={`project-${projectIndex}-task-${taskIndex}-title`}
+            placeholder={`Task ${taskIndex} Title`}
+          />
+          <input
+            {...register(
+              `projects.${projectIndex}.tasks.${taskIndex}.assignee`,
+              {
+                required: 'Assignee is required',
+              }
+            )}
+            data-testid={`project-${projectIndex}-task-${taskIndex}-assignee`}
+            placeholder={`Task ${taskIndex} Assignee`}
+          />
+        </div>
+      ))}
+
+      <button
+        type="button"
+        onClick={() => appendTask({ title: '', assignee: '' })}
+        data-testid={`add-task-${projectIndex}`}
+      >
+        Add Task
+      </button>
+    </div>
+  );
+}
+
+describe('useFieldFocusManager', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe('basic functionality', () => {
+    it('should return registerCustomFocusableElement function', () => {
+      const { result } = renderHook(() => {
+        const form = useForm();
+        return useFieldFocusManager({
+          control: form.control,
+          subscribe: form.subscribe,
+          setFocus: form.setFocus,
+        });
+      });
+
+      expect(result.current.registerCustomFocusableElement).toBeInstanceOf(
+        Function
+      );
+    });
+
+    it('should be enabled by default', () => {
+      const { result } = renderHook(() => {
+        const form = useForm();
+        return useFieldFocusManager({
+          control: form.control,
+          subscribe: form.subscribe,
+          setFocus: form.setFocus,
+        });
+      });
+
+      expect(result.current.registerCustomFocusableElement).toBeDefined();
+    });
+  });
+
+  describe('error focusing behavior', () => {
+    it('should focus the first field with an error in DOM order', async () => {
+      render(<TestFormComponent />);
+
+      const firstNameInput = screen.getByTestId('firstName');
+      const submitButton = screen.getByTestId('submit');
+
+      // Submit form to trigger validation errors
+      fireEvent.click(submitButton);
+
+      // First field in DOM order should be focused
+      await waitFor(() => expect(firstNameInput).toHaveFocus());
+    });
+
+    it('should focus the first field with error even if not the first field in form', async () => {
+      function TestForm() {
+        const form = useForm({
+          defaultValues: {
+            firstName: 'Valid',
+            lastName: '',
+            email: '',
+          },
+          shouldFocusError: false,
+        });
+
+        const { focusOnError } = useFieldFocusManager({
+          control: form.control,
+          subscribe: form.subscribe,
+          setFocus: form.setFocus,
+        });
+
+        return (
+          <form onSubmit={form.handleSubmit(() => {}, focusOnError)}>
+            <input
+              {...form.register('firstName')}
+              data-testid="firstName"
+              placeholder="First Name"
+            />
+            <input
+              {...form.register('lastName', {
+                required: 'Last name is required',
+              })}
+              data-testid="lastName"
+              placeholder="Last Name"
+            />
+            <input
+              {...form.register('email', { required: 'Email is required' })}
+              data-testid="email"
+              placeholder="Email"
+            />
+            <button type="submit" data-testid="submit">
+              Submit
+            </button>
+          </form>
+        );
+      }
+
+      render(<TestForm />);
+
+      const lastNameInput = screen.getByTestId('lastName');
+      const submitButton = screen.getByTestId('submit');
+
+      // Submit form to trigger validation errors
+      fireEvent.click(submitButton);
+
+      // Wait for focus to be applied
+      await act(async () => {
+        await new Promise((resolve) => setTimeout(resolve, 50));
+      });
+
+      // lastName should be focused as it's the first field with an error
+      expect(lastNameInput).toHaveFocus();
+    });
+
+    it('should not focus any field when there are no errors', async () => {
+      function TestForm() {
+        const form = useForm({
+          defaultValues: {
+            firstName: 'John',
+            lastName: 'Doe',
+            email: 'john@example.com',
+          },
+          shouldFocusError: false,
+        });
+
+        const { focusOnError } = useFieldFocusManager({
+          control: form.control,
+          subscribe: form.subscribe,
+          setFocus: form.setFocus,
+        });
+
+        return (
+          <form onSubmit={form.handleSubmit(() => {}, focusOnError)}>
+            <input
+              {...form.register('firstName', {
+                required: 'First name is required',
+              })}
+              data-testid="input"
+              placeholder="First Name"
+            />
+            <input
+              {...form.register('lastName', {
+                required: 'Last name is required',
+              })}
+              data-testid="input"
+              placeholder="Last Name"
+            />
+            <input
+              {...form.register('email', { required: 'Email is required' })}
+              data-testid="input"
+              placeholder="Email"
+            />
+            <button type="submit" data-testid="submit">
+              Submit
+            </button>
+          </form>
+        );
+      }
+
+      render(<TestForm />);
+
+      const submitButton = screen.getByTestId('submit');
+
+      // Submit form - should not trigger any focus since all fields are valid
+      fireEvent.click(submitButton);
+
+      // Wait for any potential focus changes
+      await act(async () => {
+        await new Promise((resolve) => setTimeout(resolve, 50));
+      });
+
+      // No input should be focused (submit button should retain focus)
+      for (const input of screen.getAllByTestId('input')) {
+        expect(input).not.toHaveFocus();
+      }
+    });
+
+    it('should focus fields in correct DOM order regardless of registration order', async () => {
+      function SimpleOrderTest() {
+        const form = useForm({
+          defaultValues: {
+            field1: 'valid',
+            field2: '',
+            field3: '',
+          },
+          shouldFocusError: false,
+        });
+
+        const { focusOnError } = useFieldFocusManager({
+          control: form.control,
+          subscribe: form.subscribe,
+          setFocus: form.setFocus,
+        });
+
+        return (
+          <form onSubmit={form.handleSubmit(() => {}, focusOnError)}>
+            <input {...form.register('field1')} data-testid="field1" />
+            <input
+              {...form.register('field2', { required: 'Required' })}
+              data-testid="field2"
+            />
+            <input
+              {...form.register('field3', { required: 'Required' })}
+              data-testid="field3"
+            />
+            <button type="submit" data-testid="submit">
+              Submit
+            </button>
+          </form>
+        );
+      }
+
+      render(<SimpleOrderTest />);
+
+      const submitButton = screen.getByTestId('submit');
+      fireEvent.click(submitButton);
+
+      await act(async () => {
+        await new Promise((resolve) => setTimeout(resolve, 50));
+      });
+
+      // field2 should be focused as it's the first field with an error in DOM order
+      const field2Input = screen.getByTestId('field2');
+      expect(field2Input).toHaveFocus();
+    });
+  });
+
+  describe('FieldArray support', () => {
+    it('should focus first field array field with error', async () => {
+      render(<TestFieldArrayComponent />);
+
+      const submitButton = screen.getByTestId('submit');
+
+      // Submit form to trigger validation errors on the first user's name field
+      fireEvent.click(submitButton);
+
+      await act(async () => {
+        await new Promise((resolve) => setTimeout(resolve, 50));
+      });
+
+      // First field in first user should be focused (users.0.name)
+      const firstUserNameInput = screen.getByTestId('user-0-name');
+      expect(firstUserNameInput).toHaveFocus();
+    });
+
+    it('should focus field arrays in DOM order', async () => {
+      render(<TestFieldArrayComponent />);
+
+      const addUserButton = screen.getByTestId('add-user');
+
+      // Add another user (but don't add items yet)
+      fireEvent.click(addUserButton);
+
+      // Fill in the first user's fields to make them valid
+      const firstUserName = screen.getByTestId('user-0-name');
+      const firstUserEmail = screen.getByTestId('user-0-email');
+
+      fireEvent.change(firstUserName, { target: { value: 'John' } });
+      fireEvent.change(firstUserEmail, {
+        target: { value: 'john@example.com' },
+      });
+
+      // Also fill in the first item's title to make it valid
+      const firstItemTitle = screen.getByTestId('item-0-title');
+      fireEvent.change(firstItemTitle, { target: { value: 'Valid Title' } });
+
+      const submitButton = screen.getByTestId('submit');
+      fireEvent.click(submitButton);
+
+      await act(async () => {
+        await new Promise((resolve) => setTimeout(resolve, 50));
+      });
+
+      // Should focus the second user's name field (first error in DOM order)
+      const secondUserNameInput = screen.getByTestId('user-1-name');
+      expect(secondUserNameInput).toHaveFocus();
+    });
+
+    it('should handle dynamically added field array items', async () => {
+      render(<TestFieldArrayComponent />);
+
+      const addUserButton = screen.getByTestId('add-user');
+      const addItemButton = screen.getByTestId('add-item');
+
+      // Add multiple users and items
+      fireEvent.click(addUserButton);
+      fireEvent.click(addUserButton);
+      fireEvent.click(addItemButton);
+
+      // Verify elements were added
+      expect(screen.getByTestId('user-0-name')).toBeInTheDocument();
+      expect(screen.getByTestId('user-1-name')).toBeInTheDocument();
+      expect(screen.getByTestId('user-2-name')).toBeInTheDocument();
+      expect(screen.getByTestId('item-0-title')).toBeInTheDocument();
+
+      const submitButton = screen.getByTestId('submit');
+      fireEvent.click(submitButton);
+
+      await act(async () => {
+        await new Promise((resolve) => setTimeout(resolve, 50));
+      });
+
+      // Should focus the first field with an error (first user's name)
+      const firstUserNameInput = screen.getByTestId('user-0-name');
+      expect(firstUserNameInput).toHaveFocus();
+    });
+
+    it('should focus items array fields when users are valid', async () => {
+      render(<TestFieldArrayComponent />);
+
+      const addItemButton = screen.getByTestId('add-item');
+      fireEvent.click(addItemButton);
+
+      // Fill in user fields to make them valid
+      const userNameInput = screen.getByTestId('user-0-name');
+      const userEmailInput = screen.getByTestId('user-0-email');
+
+      fireEvent.change(userNameInput, { target: { value: 'John' } });
+      fireEvent.change(userEmailInput, {
+        target: { value: 'john@example.com' },
+      });
+
+      const submitButton = screen.getByTestId('submit');
+      fireEvent.click(submitButton);
+
+      await act(async () => {
+        await new Promise((resolve) => setTimeout(resolve, 50));
+      });
+
+      // Should focus the first item's title field (first error in items array)
+      const firstItemTitleInput = screen.getByTestId('item-0-title');
+      expect(firstItemTitleInput).toHaveFocus();
+    });
+
+    it('should handle mixed field array and regular field errors', async () => {
+      function MixedFieldsForm() {
+        const form = useForm({
+          defaultValues: {
+            regularField: '',
+            users: [{ name: '', email: '' }],
+          },
+          shouldFocusError: false,
+        });
+
+        const { fields } = useFieldArray({
+          control: form.control,
+          name: 'users',
+        });
+
+        const { focusOnError } = useFieldFocusManager({
+          control: form.control,
+          subscribe: form.subscribe,
+          setFocus: form.setFocus,
+        });
+
+        return (
+          <form onSubmit={form.handleSubmit(() => {}, focusOnError)}>
+            <input
+              {...form.register('regularField', {
+                required: 'Regular field is required',
+              })}
+              data-testid="regular-field"
+              placeholder="Regular Field"
+            />
+
+            {fields.map((field, index) => (
+              <div key={field.id}>
+                <input
+                  {...form.register(`users.${index}.name`, {
+                    required: 'Name is required',
+                  })}
+                  data-testid={`user-${index}-name`}
+                  placeholder={`User ${index} Name`}
+                />
+              </div>
+            ))}
+
+            <button type="submit" data-testid="submit">
+              Submit
+            </button>
+          </form>
+        );
+      }
+
+      render(<MixedFieldsForm />);
+
+      const submitButton = screen.getByTestId('submit');
+      fireEvent.click(submitButton);
+
+      await act(async () => {
+        await new Promise((resolve) => setTimeout(resolve, 50));
+      });
+
+      // Should focus the regular field first (appears first in DOM)
+      const regularFieldInput = screen.getByTestId('regular-field');
+      expect(regularFieldInput).toHaveFocus();
+    });
+  });
+
+  describe('nested FieldArrays', () => {
+    it('should focus nested field array fields', async () => {
+      render(<TestNestedFieldArrayComponent />);
+
+      const submitButton = screen.getByTestId('submit');
+      fireEvent.click(submitButton);
+
+      await act(async () => {
+        await new Promise((resolve) => setTimeout(resolve, 50));
+      });
+
+      // Should focus the project name field first
+      const projectNameInput = screen.getByTestId('project-0-name');
+      expect(projectNameInput).toHaveFocus();
+    });
+
+    it('should focus nested task fields when project name is valid', async () => {
+      render(<TestNestedFieldArrayComponent />);
+
+      // Fill in project name to make it valid
+      const projectNameInput = screen.getByTestId('project-0-name');
+      fireEvent.change(projectNameInput, { target: { value: 'Project 1' } });
+
+      const submitButton = screen.getByTestId('submit');
+      fireEvent.click(submitButton);
+
+      await act(async () => {
+        await new Promise((resolve) => setTimeout(resolve, 50));
+      });
+
+      // Should focus the first task's title field
+      const taskTitleInput = screen.getByTestId('project-0-task-0-title');
+      expect(taskTitleInput).toHaveFocus();
+    });
+
+    it('should handle adding nested field arrays dynamically', async () => {
+      render(<TestNestedFieldArrayComponent />);
+
+      const addProjectButton = screen.getByTestId('add-project');
+      const addTaskButton = screen.getByTestId('add-task-0');
+
+      // Add another project and task
+      fireEvent.click(addProjectButton);
+      fireEvent.click(addTaskButton);
+
+      // Verify elements were added
+      expect(screen.getByTestId('project-0-name')).toBeInTheDocument();
+      expect(screen.getByTestId('project-1-name')).toBeInTheDocument();
+      expect(screen.getByTestId('project-0-task-0-title')).toBeInTheDocument();
+      expect(screen.getByTestId('project-0-task-1-title')).toBeInTheDocument();
+
+      const submitButton = screen.getByTestId('submit');
+      fireEvent.click(submitButton);
+
+      await act(async () => {
+        await new Promise((resolve) => setTimeout(resolve, 50));
+      });
+
+      // Should focus the first project's name field
+      const firstProjectNameInput = screen.getByTestId('project-0-name');
+      expect(firstProjectNameInput).toHaveFocus();
+    });
+
+    it('should focus deeply nested fields in correct order', async () => {
+      render(<TestNestedFieldArrayComponent />);
+
+      // Fill in first project name and first task title to test deep nesting
+      const projectNameInput = screen.getByTestId('project-0-name');
+      const taskTitleInput = screen.getByTestId('project-0-task-0-title');
+
+      fireEvent.change(projectNameInput, { target: { value: 'Project 1' } });
+      fireEvent.change(taskTitleInput, { target: { value: 'Task 1' } });
+
+      const submitButton = screen.getByTestId('submit');
+      fireEvent.click(submitButton);
+
+      await act(async () => {
+        await new Promise((resolve) => setTimeout(resolve, 50));
+      });
+
+      // Should focus the first task's assignee field (next field with error)
+      const taskAssigneeInput = screen.getByTestId('project-0-task-0-assignee');
+      expect(taskAssigneeInput).toHaveFocus();
+    });
+  });
+
+  describe('custom focusable elements', () => {
+    it('should register and focus custom elements', async () => {
+      function TestForm() {
+        const form = useForm({
+          defaultValues: {
+            firstName: '',
+          },
+          shouldFocusError: false,
+        });
+
+        const { registerCustomFocusableElement, focusOnError } =
+          useFieldFocusManager({
+            control: form.control,
+            subscribe: form.subscribe,
+            setFocus: form.setFocus,
+          });
+
+        return (
+          <form onSubmit={form.handleSubmit(() => {}, focusOnError)}>
+            <input
+              {...form.register('firstName', {
+                required: 'First name is required',
+              })}
+              data-testid="firstName"
+              placeholder="First Name"
+            />
+            <div
+              data-testid="custom-element"
+              tabIndex={0}
+              ref={(el) => {
+                if (el) {
+                  registerCustomFocusableElement('customField', el);
+                }
+              }}
+            >
+              Custom focusable element
+            </div>
+            <button type="submit" data-testid="submit">
+              Submit
+            </button>
+          </form>
+        );
+      }
+
+      render(<TestForm />);
+
+      const submitButton = screen.getByTestId('submit');
+
+      // Submit form to trigger validation errors
+      fireEvent.click(submitButton);
+
+      // Wait for focus to be applied
+      await act(async () => {
+        await new Promise((resolve) => setTimeout(resolve, 50));
+      });
+
+      // First field should still be focused since it has an error
+      const firstNameInput = screen.getByTestId('firstName');
+      expect(firstNameInput).toHaveFocus();
+    });
+
+    it('should return an unregister function', () => {
+      let registerFunction: any;
+
+      render(
+        <TestFormComponent
+          onRegisterElement={(register) => {
+            registerFunction = register;
+          }}
+        />
+      );
+
+      const mockElement = document.createElement('div');
+      const unregister = registerFunction('testField', mockElement);
+
+      expect(unregister).toBeInstanceOf(Function);
+    });
+
+    it('should register custom elements for field array items', async () => {
+      function TestFormWithCustomElements() {
+        const form = useForm({
+          defaultValues: {
+            items: [{ customField: '' }],
+          },
+          shouldFocusError: false,
+        });
+
+        const { fields } = useFieldArray({
+          control: form.control,
+          name: 'items',
+        });
+
+        const { registerCustomFocusableElement, focusOnError } =
+          useFieldFocusManager({
+            control: form.control,
+            subscribe: form.subscribe,
+            setFocus: form.setFocus,
+          });
+
+        return (
+          <form onSubmit={form.handleSubmit(() => {}, focusOnError)}>
+            {fields.map((field, index) => (
+              <div key={field.id}>
+                <div
+                  data-testid={`custom-element-${index}`}
+                  tabIndex={0}
+                  ref={(el) => {
+                    if (el) {
+                      registerCustomFocusableElement(
+                        `items.${index}.customField`,
+                        el
+                      );
+                    }
+                  }}
+                >
+                  Custom element {index}
+                </div>
+              </div>
+            ))}
+            <button type="submit" data-testid="submit">
+              Submit
+            </button>
+          </form>
+        );
+      }
+
+      render(<TestFormWithCustomElements />);
+
+      const customElement = screen.getByTestId('custom-element-0');
+      expect(customElement).toBeInTheDocument();
+
+      // The custom element should be registered and available for focusing
+      expect(customElement.tabIndex).toBe(0);
+    });
+  });
+
+  describe('enabled/disabled behavior', () => {
+    it('should not focus fields when disabled', async () => {
+      render(<TestFormComponent enabled={false} />);
+
+      const firstNameInput = screen.getByTestId('firstName');
+      const submitButton = screen.getByTestId('submit');
+
+      // Submit form to trigger validation errors
+      fireEvent.click(submitButton);
+
+      // Wait for any potential focus changes
+      await act(async () => {
+        await new Promise((resolve) => setTimeout(resolve, 50));
+      });
+
+      // No field should be focused since the hook is disabled
+      expect(firstNameInput).not.toHaveFocus();
+    });
+
+    it('should not focus field array fields when disabled', async () => {
+      render(<TestFieldArrayComponent enabled={false} />);
+
+      const submitButton = screen.getByTestId('submit');
+      fireEvent.click(submitButton);
+
+      await act(async () => {
+        await new Promise((resolve) => setTimeout(resolve, 50));
+      });
+
+      // No field should be focused since the hook is disabled
+      const firstUserNameInput = screen.getByTestId('user-0-name');
+      expect(firstUserNameInput).not.toHaveFocus();
+    });
+  });
+
+  describe('edge cases', () => {
+    it('should handle form with no fields', () => {
+      function EmptyForm() {
+        const form = useForm();
+        useFieldFocusManager({
+          control: form.control,
+          subscribe: form.subscribe,
+          setFocus: form.setFocus,
+        });
+
+        return (
+          <form>
+            <button type="submit">Submit</button>
+          </form>
+        );
+      }
+
+      expect(() => render(<EmptyForm />)).not.toThrow();
+    });
+
+    it('should handle unregistering custom elements', () => {
+      let registerFunction: any;
+
+      render(
+        <TestFormComponent
+          onRegisterElement={(register) => {
+            registerFunction = register;
+          }}
+        />
+      );
+
+      const mockElement = document.createElement('div');
+      const unregister = registerFunction('testField', mockElement);
+
+      // Should not throw when unregistering
+      expect(() => unregister()).not.toThrow();
+    });
+
+    it('should handle empty field arrays', async () => {
+      function EmptyFieldArrayForm() {
+        const form = useForm({
+          defaultValues: {
+            items: [],
+          },
+          shouldFocusError: false,
+        });
+
+        const { fields } = useFieldArray({
+          control: form.control,
+          // @ts-expect-error it expects `never`
+          name: 'items',
+        });
+
+        useFieldFocusManager({
+          control: form.control,
+          subscribe: form.subscribe,
+          setFocus: form.setFocus,
+        });
+
+        return (
+          <form onSubmit={form.handleSubmit(() => {})}>
+            {fields.map((field, index) => (
+              <input
+                key={field.id}
+                {...form.register(`items.${index}.title` as any)}
+                data-testid={`item-${index}-title`}
+              />
+            ))}
+            <button type="submit" data-testid="submit">
+              Submit
+            </button>
+          </form>
+        );
+      }
+
+      render(<EmptyFieldArrayForm />);
+
+      const submitButton = screen.getByTestId('submit');
+
+      // Should not throw when submitting form with empty field arrays
+      expect(() => fireEvent.click(submitButton)).not.toThrow();
+
+      await act(async () => {
+        await new Promise((resolve) => setTimeout(resolve, 50));
+      });
+
+      // No errors should occur and no elements should be focused
+      expect(screen.queryByTestId('item-0-title')).not.toBeInTheDocument();
+    });
+
+    it('should handle field arrays with non-sequential indices', async () => {
+      function NonSequentialFieldArrayForm() {
+        const form = useForm({
+          defaultValues: {
+            items: { 0: { title: '' }, 2: { title: '' } },
+          },
+          shouldFocusError: false,
+        });
+
+        const { focusOnError } = useFieldFocusManager({
+          control: form.control,
+          subscribe: form.subscribe,
+          setFocus: form.setFocus,
+        });
+
+        return (
+          <form onSubmit={form.handleSubmit(() => {}, focusOnError)}>
+            <input
+              {...form.register('items.0.title' as any, {
+                required: 'Title required',
+              })}
+              data-testid="item-0-title"
+            />
+            <input
+              {...form.register('items.2.title' as any, {
+                required: 'Title required',
+              })}
+              data-testid="item-2-title"
+            />
+            <button type="submit" data-testid="submit">
+              Submit
+            </button>
+          </form>
+        );
+      }
+
+      render(<NonSequentialFieldArrayForm />);
+
+      const submitButton = screen.getByTestId('submit');
+      fireEvent.click(submitButton);
+
+      // Should focus the first field in DOM order
+      await waitFor(() => {
+        const firstItemInput = screen.getByTestId('item-0-title');
+        expect(firstItemInput).toHaveFocus();
+      });
+    });
+  });
+});