feat: implement scroll-to-error functionality for @lambdacurry/forms

- Add core scrollToFirstError utility with configurable options
- Create useScrollToErrorOnSubmit hook for Remix form integration
- Add ScrollToErrorOnSubmit component for declarative usage
- Leverage existing data-slot selectors for seamless integration
- Support both client-side and server-side validation errors
- Include retry logic for async rendering scenarios
- Export new functionality from main package entry points

Author: codegen-sh[bot]

apps/docs/src/remix-hook-form/phone-input.stories.tsx

@@ -37,11 +37,7 @@ const ControlledPhoneInputExample = () => {
     <RemixFormProvider {...methods}>
       <fetcher.Form onSubmit={methods.handleSubmit}>
         <div className="grid gap-8">
-          <PhoneInput
-            name="usaPhone"
-            label="Phone Number"
-            description="Enter a US phone number"
-          />
+          <PhoneInput name="usaPhone" label="Phone Number" description="Enter a US phone number" />
           <PhoneInput
             name="internationalPhone"
             label="International Phone Number"

apps/docs/src/remix-hook-form/select.test.tsx

@@ -1,80 +1,79 @@
+import type { StoryContext } from '@storybook/react';
 import { expect } from '@storybook/test';
 import { userEvent, within } from '@storybook/testing-library';
-import { StoryContext } from '@storybook/react';
 
 // Test selecting a US state
 export const testUSStateSelection = async ({ canvasElement }: StoryContext) => {
   const canvas = within(canvasElement);
-  
+
   // Find and click the US state dropdown
   const stateDropdown = canvas.getByLabelText('US State');
   await userEvent.click(stateDropdown);
-  
+
   // Select a state (e.g., California)
   const californiaOption = await canvas.findByText('California');
   await userEvent.click(californiaOption);
-  
+
   // Verify the selection
   expect(stateDropdown).toHaveTextContent('California');
 };
 
 // Test selecting a Canadian province
 export const testCanadaProvinceSelection = async ({ canvasElement }: StoryContext) => {
   const canvas = within(canvasElement);
-  
+
   // Find and click the Canada province dropdown
   const provinceDropdown = canvas.getByLabelText('Canadian Province');
   await userEvent.click(provinceDropdown);
-  
+
   // Select a province (e.g., Ontario)
   const ontarioOption = await canvas.findByText('Ontario');
   await userEvent.click(ontarioOption);
-  
+
   // Verify the selection
   expect(provinceDropdown).toHaveTextContent('Ontario');
 };
 
 // Test form submission
 export const testFormSubmission = async ({ canvasElement }: StoryContext) => {
   const canvas = within(canvasElement);
-  
+
   // Select a state
   const stateDropdown = canvas.getByLabelText('US State');
   await userEvent.click(stateDropdown);
   const californiaOption = await canvas.findByText('California');
   await userEvent.click(californiaOption);
-  
+
   // Select a province
   const provinceDropdown = canvas.getByLabelText('Canadian Province');
   await userEvent.click(provinceDropdown);
   const ontarioOption = await canvas.findByText('Ontario');
   await userEvent.click(ontarioOption);
-  
+
   // Select a custom region
   const regionDropdown = canvas.getByLabelText('Custom Region');
   await userEvent.click(regionDropdown);
   const customOption = await canvas.findByText('New York');
   await userEvent.click(customOption);
-  
+
   // Submit the form
   const submitButton = canvas.getByRole('button', { name: 'Submit' });
   await userEvent.click(submitButton);
-  
+
   // Verify the submission (mock response would be shown)
   await expect(canvas.findByText('Selected regions:')).resolves.toBeInTheDocument();
 };
 
 // Test validation errors
 export const testValidationErrors = async ({ canvasElement }: StoryContext) => {
   const canvas = within(canvasElement);
-  
+
   // Submit the form without selecting anything
   const submitButton = canvas.getByRole('button', { name: 'Submit' });
   await userEvent.click(submitButton);
-  
+
   // Verify error messages
   await expect(canvas.findByText('Please select a state')).resolves.toBeInTheDocument();
   await expect(canvas.findByText('Please select a province')).resolves.toBeInTheDocument();
   await expect(canvas.findByText('Please select a region')).resolves.toBeInTheDocument();
 };
-

package.json

@@ -2,10 +2,7 @@
   "name": "forms",
   "version": "0.2.0",
   "private": true,
-  "workspaces": [
-    "apps/*",
-    "packages/*"
-  ],
+  "workspaces": ["apps/*", "packages/*"],
   "scripts": {
     "start": "yarn dev",
     "dev": "turbo run dev",

packages/components/package.json

@@ -26,9 +26,7 @@
       "import": "./dist/ui/*.js"
     }
   },
-  "files": [
-    "dist"
-  ],
+  "files": ["dist"],
   "scripts": {
     "prepublishOnly": "yarn run build",
     "build": "vite build",

packages/components/src/index.ts

@@ -1,5 +1,9 @@
 // Main exports from both remix-hook-form and ui directories
 
+// Add scroll-to-error utilities
+export { scrollToFirstError } from './utils/scrollToError';
+export type { ScrollToErrorOptions } from './utils/scrollToError';
+
 // Export all components from remix-hook-form
 export * from './remix-hook-form';
 

packages/components/src/remix-hook-form/canada-province-select.tsx

@@ -1,16 +1,8 @@
-import * as React from 'react';
-import { Select, type SelectProps } from './select';
 import { CANADA_PROVINCES } from '../ui/data/canada-provinces';
+import { Select, type SelectProps } from './select';
 
 export type CanadaProvinceSelectProps = Omit<SelectProps, 'options'>;
 
 export function CanadaProvinceSelect(props: CanadaProvinceSelectProps) {
-  return (
-    <Select
-      {...props}
-      options={CANADA_PROVINCES}
-      placeholder="Select a province"
-    />
-  );
+  return <Select {...props} options={CANADA_PROVINCES} placeholder="Select a province" />;
 }
-

packages/components/src/remix-hook-form/components/ScrollToErrorOnSubmit.tsx

@@ -0,0 +1,14 @@
+import { type UseScrollToErrorOnSubmitOptions, useScrollToErrorOnSubmit } from '../hooks/useScrollToErrorOnSubmit';
+
+export interface ScrollToErrorOnSubmitProps extends UseScrollToErrorOnSubmitOptions {
+  className?: string;
+}
+
+export const ScrollToErrorOnSubmit = ({ className, ...options }: ScrollToErrorOnSubmitProps) => {
+  useScrollToErrorOnSubmit(options);
+
+  // Return null or hidden div - follows existing patterns
+  return className ? <div className={className} aria-hidden="true" /> : null;
+};
+
+ScrollToErrorOnSubmit.displayName = 'ScrollToErrorOnSubmit';

packages/components/src/remix-hook-form/components/index.ts

@@ -0,0 +1 @@
+export * from './ScrollToErrorOnSubmit';

packages/components/src/remix-hook-form/hooks/index.ts

@@ -0,0 +1 @@
+export * from './useScrollToErrorOnSubmit';

packages/components/src/remix-hook-form/hooks/useScrollToErrorOnSubmit.ts

@@ -0,0 +1,54 @@
+import { useEffect, useMemo } from 'react';
+import { useRemixFormContext } from 'remix-hook-form';
+import { type ScrollToErrorOptions, scrollToFirstError } from '../../utils/scrollToError';
+
+export interface UseScrollToErrorOnSubmitOptions extends ScrollToErrorOptions {
+  delay?: number;
+  enabled?: boolean;
+  scrollOnServerErrors?: boolean;
+  scrollOnMount?: boolean;
+}
+
+export const useScrollToErrorOnSubmit = (options: UseScrollToErrorOnSubmitOptions = {}) => {
+  const { formState } = useRemixFormContext();
+  const { delay = 100, enabled = true, scrollOnServerErrors = true, scrollOnMount = true, ...scrollOptions } = options;
+
+  // Memoize scroll options to prevent unnecessary re-renders
+  const memoizedScrollOptions = useMemo(() => scrollOptions, [
+    scrollOptions.behavior,
+    scrollOptions.block,
+    scrollOptions.inline,
+    scrollOptions.offset,
+    scrollOptions.shouldFocus,
+    scrollOptions.retryAttempts,
+  ]);
+
+  // Handle form submission errors
+  useEffect(() => {
+    if (!enabled) return;
+    const hasErrors = Object.keys(formState.errors).length > 0;
+
+    // Scroll after submission attempt when errors exist
+    if (!formState.isSubmitting && hasErrors) {
+      const timeoutId = setTimeout(() => {
+        scrollToFirstError(formState.errors, memoizedScrollOptions);
+      }, delay);
+
+      return () => clearTimeout(timeoutId);
+    }
+  }, [formState.errors, formState.isSubmitting, enabled, delay, memoizedScrollOptions]);
+
+  // Handle server-side validation errors on mount (Remix SSR)
+  useEffect(() => {
+    if (!(enabled && scrollOnMount) || !scrollOnServerErrors) return;
+    const hasErrors = Object.keys(formState.errors).length > 0;
+
+    if (hasErrors && !formState.isSubmitting) {
+      const timeoutId = setTimeout(() => {
+        scrollToFirstError(formState.errors, memoizedScrollOptions);
+      }, delay);
+
+      return () => clearTimeout(timeoutId);
+    }
+  }, [enabled, scrollOnMount, scrollOnServerErrors, formState.errors, formState.isSubmitting, delay, memoizedScrollOptions]);
+};