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

packages/components/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lambdacurry/forms",
-  "version": "0.19.7",
+  "version": "0.20.0",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

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/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,83 @@
+import { useEffect, useMemo } from 'react';
+import type { FieldValues } from 'react-hook-form';
+import { useRemixFormContext } from 'remix-hook-form';
+import type { UseRemixFormReturn } from 'remix-hook-form';
+import { type ScrollToErrorOptions, scrollToFirstError } from '../../utils/scrollToError';
+
+export interface UseScrollToErrorOnSubmitOptions extends ScrollToErrorOptions {
+  delay?: number;
+  enabled?: boolean;
+  scrollOnServerErrors?: boolean;
+  scrollOnMount?: boolean;
+  methods?: UseRemixFormReturn<FieldValues>; // Optional methods parameter
+}
+
+export const useScrollToErrorOnSubmit = (options: UseScrollToErrorOnSubmitOptions = {}) => {
+  // Use provided methods or fall back to context
+  const contextMethods = useRemixFormContext();
+  const {
+    methods,
+    delay = 100,
+    enabled = true,
+    scrollOnServerErrors = true,
+    scrollOnMount = true,
+    ...scrollOptions
+  } = options;
+  const formMethods = methods || contextMethods;
+
+  const { formState } = formMethods;
+
+  // Memoize scroll options to prevent unnecessary re-renders
+  const { behavior, block, inline, offset, shouldFocus, retryAttempts, selectors } = scrollOptions;
+
+  // biome-ignore lint: Compare `selectors` by value via join to avoid unstable array identity.
+  const memoizedScrollOptions = useMemo(
+    () => ({
+      behavior,
+      block,
+      inline,
+      offset,
+      shouldFocus,
+      retryAttempts,
+      selectors,
+    }),
+    [behavior, block, inline, offset, shouldFocus, retryAttempts, selectors?.join(',')],
+  );
+
+  // 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,
+  ]);
+};

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

@@ -1,3 +1,8 @@
+// Add scroll-to-error functionality
+export * from './hooks/useScrollToErrorOnSubmit';
+export * from './components/ScrollToErrorOnSubmit';
+
+// Keep all existing exports
 export * from './checkbox';
 export * from './form';
 export * from './form-error';

packages/components/src/utils/index.ts

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

packages/components/src/utils/scrollToError.ts

@@ -0,0 +1,75 @@
+import type { FieldErrors } from 'react-hook-form';
+
+export interface ScrollToErrorOptions {
+  behavior?: ScrollBehavior;
+  block?: ScrollLogicalPosition;
+  inline?: ScrollLogicalPosition;
+  offset?: number;
+  shouldFocus?: boolean;
+  retryAttempts?: number;
+  selectors?: string[];
+}
+
+const DEFAULT_ERROR_SELECTORS = [
+  '[data-slot="form-message"]', // Target error message first (best UX)
+  '[data-slot="form-control"][aria-invalid="true"]', // Input with error state
+];
+
+const findFirstErrorElement = (selectors: string[]): HTMLElement | null => {
+  for (const selector of selectors) {
+    const element = document.querySelector(selector) as HTMLElement;
+    if (element) {
+      return element;
+    }
+  }
+  return null;
+};
+
+const scrollToElement = (element: HTMLElement, offset: number, behavior: ScrollBehavior): void => {
+  const elementRect = element.getBoundingClientRect();
+  const offsetTop = elementRect.top + window.pageYOffset - offset;
+
+  window.scrollTo({
+    top: Math.max(0, offsetTop),
+    behavior,
+  });
+};
+
+const focusElement = (element: HTMLElement, shouldFocus: boolean, behavior: ScrollBehavior): void => {
+  if (shouldFocus && element.focus) {
+    setTimeout(() => element.focus(), behavior === 'smooth' ? 300 : 0);
+  }
+};
+
+export const scrollToFirstError = (errors: FieldErrors, options: ScrollToErrorOptions = {}) => {
+  const {
+    behavior = 'smooth',
+    offset = 80,
+    shouldFocus = true,
+    retryAttempts = 3,
+    selectors = DEFAULT_ERROR_SELECTORS,
+  } = options;
+
+  if (Object.keys(errors).length === 0) return false;
+
+  const attemptScroll = (attempt = 0): boolean => {
+    const selectorList = selectors.length > 0 ? selectors : DEFAULT_ERROR_SELECTORS;
+    const element = findFirstErrorElement(selectorList);
+    if (element) {
+      scrollToElement(element, offset, behavior);
+      focusElement(element, shouldFocus, behavior);
+      return true;
+    }
+
+    // Retry for async rendering (common with Remix)
+    if (attempt < retryAttempts) {
+      setTimeout(() => attemptScroll(attempt + 1), 100);
+      return true;
+    }
+
+    console.warn('Could not find any form error elements to scroll to');
+    return false;
+  };
+
+  return attemptScroll();
+};