@digigov/form 2.0.0-16da9467 → 2.0.0-16fbe090

package/src/hooks/useFieldFocusManager.ts

@@ -0,0 +1,162 @@
+import { useCallback, useEffect, useRef } from 'react';
+import type { Control, FieldValues, Ref, UseFormReturn } from 'react-hook-form';
+import {
+  extractFieldEntries,
+  mapElementsToFields,
+  sortElementsByPosition,
+} from '@digigov/form/hooks/utils';
+
+export interface UseFieldFocusManagerProps<T extends FieldValues> {
+  enabled?: boolean;
+  control: Control<T>;
+  subscribe: UseFormReturn['subscribe'];
+  setFocus: UseFormReturn['setFocus'];
+}
+
+/**
+ * Custom hook to manage focus on form fields.
+ *
+ * It collects all focusable elements from the form fields and sorts them according to their position in the DOM.
+ */
+export function useFieldFocusManager<T extends FieldValues>({
+  enabled = true,
+  control,
+  subscribe,
+  setFocus,
+}: UseFieldFocusManagerProps<T>) {
+  /** Array to hold any external focusable elements registered by the user */
+  const customFocusableElements = useRef(new Map<string, HTMLElement>());
+  /** Map to hold focusable elements by field name */
+  const focusableElements = useRef(new Map<string, Ref>());
+
+  // When disabled, clear custom focusable elements and focusable elements map
+  useEffect(() => {
+    if (!enabled) {
+      customFocusableElements.current.clear();
+      focusableElements.current.clear();
+      return;
+    }
+  }, [enabled]);
+
+  const updateFocusableElements = useCallback(() => {
+    // Clear existing focusable elements
+    focusableElements.current.clear();
+    // Extract from form fields
+    const formElements = extractFieldEntries(control._fields);
+    // Extract from custom elements (convert to FieldRefs format first)
+    const customFieldRefs = mapElementsToFields(
+      customFocusableElements.current
+    );
+    const customElements = extractFieldEntries(customFieldRefs);
+
+    // Combine both maps
+    const combinedElements = new Map(formElements);
+    customElements.forEach((element, fieldName) => {
+      combinedElements.set(fieldName, element);
+    });
+
+    // Sort once by DOM position
+    focusableElements.current = sortElementsByPosition(combinedElements);
+  }, [control._fields]);
+
+  // Register / unregister custom focusable elements
+  const registerCustomFocusableElement = useCallback(
+    (fieldName: string, element: HTMLElement) => {
+      if (fieldName && element) {
+        customFocusableElements.current.set(fieldName, element);
+        updateFocusableElements();
+      }
+
+      return function unregister() {
+        customFocusableElements.current.delete(fieldName);
+        updateFocusableElements();
+      };
+    },
+    [updateFocusableElements]
+  );
+
+  // Collect focusable elements when fields change
+  useEffect(() => {
+    if (!enabled || !subscribe) return;
+    const callback = subscribe({
+      formState: {
+        errors: true,
+        // Subscribe to any form state change that might indicate field structure changes
+      },
+      callback: () => {
+        // Defer to next tick to ensure DOM is updated
+        setTimeout(updateFocusableElements, 0);
+      },
+    });
+
+    // Initial update
+    updateFocusableElements();
+
+    return () => callback();
+  }, [enabled, updateFocusableElements, subscribe]);
+
+  // Subscribe to errors and focus the first field (according to the DOM) with an error
+  const focusOnError = useCallback(
+    (errors: Record<string, any>) => {
+      if (!enabled) return;
+      if (!errors || Object.keys(errors).length === 0) return;
+      for (const [fieldName, element] of Array.from(
+        focusableElements.current
+      )) {
+        if (hasFieldError(errors, fieldName)) {
+          if (element && typeof element.focus === 'function') {
+            element.focus(); // Focus the element directly
+            return;
+          } else if (element && element.name) {
+            setFocus(fieldName); // Field is registered with react-hook-form
+            return;
+          }
+        }
+      }
+    },
+    [enabled, setFocus]
+  );
+
+  return {
+    /**
+     * Registers a custom focusable element with the given field name.
+     *
+     * Returns a callback function to unregister the element by field name.
+     *
+     * @param fieldName - The name of the field to associate with the element.
+     * @param element - The HTML element to register as focusable.
+     */
+    registerCustomFocusableElement,
+    focusOnError,
+  };
+}
+
+// Helper function to check for nested field errors
+function hasFieldError(
+  errors: Record<string, any>,
+  fieldName: string
+): boolean {
+  if (!errors || typeof errors !== 'object') return false;
+
+  // Handle direct field names first
+  if (errors[fieldName]) {
+    return true;
+  }
+
+  // Split the field name and traverse the error object
+  const keys = fieldName.split(/[.[\]]+/).filter(Boolean);
+  let current = errors;
+
+  for (const key of keys) {
+    if (current && typeof current === 'object') {
+      current = current[key];
+    } else {
+      return false;
+    }
+  }
+
+  // Check if we found a truthy error value
+  return !!current;
+}
+
+export default useFieldFocusManager;

package/src/hooks/utils.ts

@@ -0,0 +1,122 @@
+import type { Field, FieldRefs, Ref } from 'react-hook-form';
+
+/**
+ * Recursively extracts field entries from nested form field structure.
+ * Handles both regular nested objects and array-like structures.
+ */
+export function extractFieldEntries(
+  fields: FieldRefs,
+  prefix = ''
+): Map<string, Ref> {
+  const elementMap = new Map<string, Ref>();
+
+  const fieldEntries = Object.entries(fields);
+  if (fieldEntries.length === 0) return elementMap;
+
+  Object.entries(fields).forEach(([fieldName, field]) => {
+    if (!field) return;
+    const fullFieldName = prefix ? `${prefix}.${fieldName}` : fieldName;
+
+    // Handle direct field with ref
+    if (isField(field)) {
+      const element = field._f.ref;
+      if (element) {
+        elementMap.set(fullFieldName, element);
+      }
+    }
+
+    // Handle array fields (numeric keys indicate array indices)
+    else if (isFieldRefs(field)) {
+      // Check if any keys are numeric (indicating an array structure)
+      // Filter out non-numeric keys like '_f' which contains field metadata
+      const keys = Object.keys(field);
+      const numericKeys = keys.filter((key) => /^\d+$/.test(key));
+      const hasNumericKeys = numericKeys.length > 0;
+
+      if (hasNumericKeys) {
+        // Process only the numeric array indices, ignore metadata keys like '_f'
+        numericKeys.forEach((index) => {
+          const arrayItem = field[index];
+          if (arrayItem && isFieldRefs(arrayItem)) {
+            const nestedEntries = extractFieldEntries(
+              arrayItem,
+              `${fullFieldName}.${index}`
+            );
+            // Merge nested entries into main map
+            nestedEntries.forEach((element, fieldName) => {
+              elementMap.set(fieldName, element);
+            });
+          }
+        });
+      } else {
+        // Handle regular nested objects
+        const nestedEntries = extractFieldEntries(field, fullFieldName);
+        // Merge nested entries into main map
+        nestedEntries.forEach((element, fieldName) => {
+          elementMap.set(fieldName, element);
+        });
+      }
+    }
+  });
+
+  return elementMap;
+}
+
+/** Type guard to check if a ref is a Field object */
+const isField = (fieldRef: FieldRefs[keyof FieldRefs]): fieldRef is Field =>
+  Boolean(
+    fieldRef &&
+      typeof fieldRef === 'object' &&
+      '_f' in fieldRef &&
+      fieldRef._f &&
+      'ref' in fieldRef._f
+  );
+
+/** Type guard to check if a ref is a FieldRefs object (nested fields) */
+const isFieldRefs = (
+  fieldRef: FieldRefs[keyof FieldRefs]
+): fieldRef is FieldRefs =>
+  Boolean(fieldRef && typeof fieldRef === 'object' && !isField(fieldRef));
+
+/**
+ * Sorts a map of HTML elements by their position in the DOM.
+ * Elements appearing earlier in the document order come first.
+ */
+export function sortElementsByPosition(
+  elements: Map<string, Ref>
+): Map<string, Ref> {
+  const sortedEntries = Array.from(elements.entries()).sort(([, a], [, b]) => {
+    if (isActualHTMLElement(a) && isActualHTMLElement(b)) {
+      const aPosition = a.compareDocumentPosition(b);
+      if (aPosition & Node.DOCUMENT_POSITION_FOLLOWING) return -1;
+      if (aPosition & Node.DOCUMENT_POSITION_PRECEDING) return 1;
+    }
+    return 0; // keep original order
+  });
+  return new Map(sortedEntries);
+}
+
+/** Type guard to check if a ref is an actual HTML element */
+const isActualHTMLElement = (ref: Ref): ref is Ref & HTMLElement =>
+  ref instanceof HTMLElement && typeof ref.focus === 'function';
+
+/**
+ * Maps a collection of HTML elements to a FieldRefs structure.
+ *
+ * It's not a direct conversion, but rather a way to create a simple FieldRefs
+ * structure that can be used with React Hook Form.
+ */
+export function mapElementsToFields(
+  elements: Map<string, HTMLElement>
+): Record<string, Field> {
+  const fields = {};
+  elements.forEach((element, fieldName) => {
+    fields[fieldName] = {
+      _f: {
+        ref: element,
+        name: fieldName,
+      },
+    };
+  });
+  return fields;
+}

package/src/inputs/AutoCompleteInput/doc.mdx

@@ -11,8 +11,8 @@ options as the users type and also let them select an option from the list.
 
 ### Default
 
-<code src="@digigov/form/inputs/AutoCompleteInput/__stories__/Default.tsx" />
+<code src="@digigov/form/src/inputs/AutoCompleteInput/__stories__/Default.tsx" />
 
 ### Display multiple values
 
-<code src="@digigov/form/inputs/AutoCompleteInput/__stories__/Multiple.tsx" />
+<code src="@digigov/form/src/inputs/AutoCompleteInput/__stories__/Multiple.tsx" />

package/src/inputs/AutoCompleteInput/index.tsx

@@ -1,10 +1,8 @@
 import React, { useCallback } from 'react';
-import { ControlledFieldProps } from '@digigov/form/Field/types';
-import { FieldOptionProps } from '@digigov/form/inputs/Label';
-import {
-  AutoComplete,
-  AutoCompleteProps as UIAutoCompleteProps,
-} from '@digigov/ui/form/AutoComplete';
+import type { ControlledFieldProps } from '@digigov/form/Field/types';
+import type { FieldOptionProps } from '@digigov/form/inputs/Label';
+import type { AutoCompleteProps as UIAutoCompleteProps } from '@digigov/ui/form/AutoComplete';
+import { AutoComplete } from '@digigov/ui/form/AutoComplete';
 import { Hint } from '@digigov/ui/typography/Hint';
 import { Base } from '@digigov/ui/utils/Base';
 export interface AutoCompleteInputExtra

package/src/inputs/Checkboxes/doc.mdx

@@ -10,14 +10,14 @@ Checkboxes are used to let a user select one or more options of a limited number
 
 ### Default
 
-<code src="@digigov/form/inputs/Checkboxes/__stories__/Default.tsx" />
+<code src="@digigov/form/src/inputs/Checkboxes/__stories__/Default.tsx" />
 
 
 ### Conditional
 
-<code src="@digigov/form/inputs/Checkboxes/__stories__/Conditional.tsx" />
+<code src="@digigov/form/src/inputs/Checkboxes/__stories__/Conditional.tsx" />
 
 
 ### With divider
 
-<code src="@digigov/form/inputs/Checkboxes/__stories__/WithDivider.tsx" />
+<code src="@digigov/form/src/inputs/Checkboxes/__stories__/WithDivider.tsx" />

package/src/inputs/Checkboxes/index.tsx

@@ -1,6 +1,8 @@
 import React, { useState } from 'react';
-import { ControlledFieldProps } from '@digigov/form/Field/types';
-import { FieldOptionProps } from '@digigov/form/inputs/Label';
+import type { UseFormReturn } from 'react-hook-form';
+import type { ControlledFieldProps } from '@digigov/form/Field/types';
+import type { FieldOptionProps } from '@digigov/form/inputs/Label';
+import { omit } from '@digigov/form/utils';
 import {
   Checkbox,
   CheckboxItem,
@@ -17,94 +19,103 @@ export interface CheckboxesProps
     options: FieldOptionProps[];
   };
   fieldComponent: React.FC<Omit<ControlledFieldProps, 'value' | 'onChange'>>;
+  resetField: UseFormReturn['resetField'];
 }
 
-export const Checkboxes: React.FC<CheckboxesProps> = ({
-  name,
-  onChange,
-  value,
-  extra: { options, className },
-  disabled,
-  Field,
-  ...props
-}) => {
-  if (!value) value = [];
-  const handleChange =
-    (optionValue, idx, show) =>
-    (evt): void => {
-      let newValue: any = [];
-      if (evt.currentTarget.checked) {
-        newValue = value.concat([optionValue]);
-      } else {
-        newValue = value.filter((val) => val !== optionValue);
-      }
-      if (show && show.length > 0) {
-        setChecked((items) =>
-          items.map((item, index) => (index === idx ? !item : item))
-        );
-      }
+export const Checkboxes = React.forwardRef<HTMLInputElement, CheckboxesProps>(
+  (
+    {
+      name,
+      onChange,
+      value,
+      extra: { options, className },
+      disabled,
+      Field,
+      ...props
+    },
+    ref
+  ) => {
+    if (!value) value = [];
+    const handleChange =
+      (optionValue, idx, show) =>
+      (evt): void => {
+        let newValue: any = [];
+        if (evt.currentTarget.checked) {
+          newValue = value.concat([optionValue]);
+        } else {
+          newValue = value.filter((val) => val !== optionValue);
+        }
+        if (show && show.length > 0) {
+          setChecked((items) =>
+            items.map((item, index) => (index === idx ? !item : item))
+          );
+        }
 
-      // reset value to undefined instead of an empty array
-      // so the error state mechanism can throw validation errors
-      if (newValue.length === 0) newValue = undefined;
-      onChange(newValue);
-    };
-  const { t } = useTranslation();
-  const [checked, setChecked] = useState(
-    Array<boolean>(options.length).fill(false)
-  );
-  return (
-    <Checkbox className={className}>
-      {options.map(
-        (
-          {
-            label,
-            value: v,
-            show,
-            disabled: optionDisabled,
-            selected,
-            ...option
-          },
-          index
-        ) => (
-          <React.Fragment key={index}>
-            <CheckboxItem
-              key={`${name}.${index}`}
-              name={`${name}.${v}`}
-              id={`${name}.${v}`}
-              value={v}
-              disabled={disabled || optionDisabled}
-              checked={value?.includes(v)}
-              onChange={handleChange(v, index, show)}
-              {...option}
-              {...{
-                ...props,
-                reset: undefined,
-                defaultValue: undefined,
-                error: undefined,
-                onBlur: undefined,
-                required: undefined,
-                'aria-describedby': undefined,
-                type: 'checkbox',
-              }}
-            >
-              {(label && label.primary && t(label.primary)) || value}
-              {label && label.secondary && <Hint>{t(label.secondary)}</Hint>}
-            </CheckboxItem>
+        // reset value to undefined instead of an empty array
+        // so the error state mechanism can throw validation errors
+        if (newValue.length === 0) newValue = undefined;
+        onChange(newValue);
+      };
+    const { t } = useTranslation();
+    const [checked, setChecked] = useState(
+      Array<boolean>(options.length).fill(false)
+    );
+    return (
+      <Checkbox className={className}>
+        {options.map(
+          (
+            {
+              label,
+              value: v,
+              show,
+              disabled: optionDisabled,
+              selected,
+              ...option
+            },
+            index
+          ) => (
+            <React.Fragment key={index}>
+              <CheckboxItem
+                ref={index === 0 ? ref : undefined}
+                key={`${name}.${index}`}
+                name={`${name}.${v}`}
+                id={`${name}.${v}`}
+                value={v}
+                disabled={disabled || optionDisabled}
+                checked={value?.includes(v)}
+                onChange={handleChange(v, index, show)}
+                {...option}
+                {...{
+                  ...omit(props, ['resetField']),
+                  reset: undefined,
+                  defaultValue: undefined,
+                  error: undefined,
+                  onBlur: undefined,
+                  required: undefined,
+                  'aria-describedby': undefined,
+                  type: 'checkbox',
+                }}
+              >
+                {(label && label.primary && t(label.primary)) || value}
+                {label && label.secondary && <Hint>{t(label.secondary)}</Hint>}
+              </CheckboxItem>
 
-            {!!checked[index] && show && Field && (
-              <CheckboxConditional>
-                {show.map((fieldName) => (
-                  <Field name={fieldName} key={fieldName} />
-                ))}
-              </CheckboxConditional>
-            )}
-            {selected && selected()}
-          </React.Fragment>
-        )
-      )}
-    </Checkbox>
-  );
-};
+              {!!checked[index] && show && Field && (
+                <CheckboxConditional>
+                  {show.map((fieldName) => (
+                    <Field name={fieldName} key={fieldName} />
+                  ))}
+                </CheckboxConditional>
+              )}
+              {selected && selected()}
+            </React.Fragment>
+          )
+        )}
+      </Checkbox>
+    );
+  }
+);
+
+Checkboxes.displayName = 'Checkboxes';
 
 export default Checkboxes;

package/src/inputs/DateInput/doc.mdx

@@ -13,4 +13,4 @@ either with a textbox that validates the input or a special date picker interfac
 
 ### Default
 
-<code src="@digigov/form/inputs/DateInput/__stories__/Default.tsx" />
+<code src="@digigov/form/src/inputs/DateInput/__stories__/Default.tsx" />

package/src/inputs/DateInput/index.tsx

@@ -1,7 +1,7 @@
 import React, { useMemo, useEffect } from 'react';
 import dayjs from 'dayjs';
 import customParseFormat from 'dayjs/plugin/customParseFormat';
-import { UncontrolledFieldProps } from '@digigov/form/Field/types';
+import type { UncontrolledFieldProps } from '@digigov/form/Field/types';
 import { useFormContext } from '@digigov/form/FormContext';
 import {
   DateInputContainer,
@@ -87,11 +87,21 @@ const makeDate = (val) => {
   return '';
 };
 
-const DatePart = ({ label, ...props }) => {
-  return <DateInputItem {...props}>{label}</DateInputItem>;
-};
+const DatePart = React.forwardRef<HTMLInputElement, Record<string, any>>(
+  ({ label, ...props }, ref) => {
+    return (
+      <DateInputItem {...props} ref={ref}>
+        {label}
+      </DateInputItem>
+    );
+  }
+);
+DatePart.displayName = 'DatePart';
 
-export const DateInput = ({ name, ...props }) => {
+export const DateInput = React.forwardRef<
+  HTMLInputElement,
+  Record<string, any>
+>(({ name, ...props }, ref) => {
   const { t } = useTranslation();
   const form = useFormContext();
 
@@ -116,6 +126,7 @@ export const DateInput = ({ name, ...props }) => {
   return (
     <DateInputContainer>
       <DatePart
+        ref={ref}
         label={t('form.label.day')}
         onChange={date.setDay}
         onBlur={(e) => {
@@ -166,6 +177,8 @@ export const DateInput = ({ name, ...props }) => {
       />
     </DateInputContainer>
   );
-};
+});
+
+DateInput.displayName = 'DateInput';
 
 export default DateInput;

package/src/inputs/DateTimeInput/doc.mdx

@@ -13,4 +13,4 @@ either with a textbox that validates the input or a special date picker interfac
 
 ### Default
 
-<code src="@digigov/form/inputs/DateTimeInput/__stories__/Default.tsx" />
+<code src="@digigov/form/src/inputs/DateTimeInput/__stories__/Default.tsx" />

package/src/inputs/DateTimeInput/index.tsx

@@ -1,7 +1,7 @@
 import React, { useMemo, useEffect } from 'react';
 import dayjs from 'dayjs';
 import customParseFormat from 'dayjs/plugin/customParseFormat';
-import { UncontrolledFieldProps } from '@digigov/form/Field/types';
+import type { UncontrolledFieldProps } from '@digigov/form/Field/types';
 import { useFormContext } from '@digigov/form/FormContext';
 import {
   DateInputContainer,
@@ -113,11 +113,21 @@ const makeDateTime = (val) => {
   return '';
 };
 
-const DateTimePart = ({ label, ...props }) => {
-  return <DateInputItem {...props}>{label}</DateInputItem>;
-};
+const DateTimePart = React.forwardRef<HTMLInputElement, Record<string, any>>(
+  ({ label, ...props }, ref) => {
+    return (
+      <DateInputItem {...props} ref={ref}>
+        {label}
+      </DateInputItem>
+    );
+  }
+);
+DateTimePart.displayName = 'DateTimePart';
 
-export const DateTimeInput = ({ name, ...props }) => {
+export const DateTimeInput = React.forwardRef<
+  HTMLInputElement,
+  Record<string, any>
+>(({ name, ...props }, ref) => {
   const { t } = useTranslation();
   const form = useFormContext();
 
@@ -142,6 +152,7 @@ export const DateTimeInput = ({ name, ...props }) => {
   return (
     <DateInputContainer>
       <DateTimePart
+        ref={ref}
         label={t('form.label.day')}
         onChange={dateTime.setDay}
         onBlur={(e) => {
@@ -228,6 +239,8 @@ export const DateTimeInput = ({ name, ...props }) => {
       />
     </DateInputContainer>
   );
-};
+});
+
+DateTimeInput.displayName = 'DateTimeInput';
 
 export default DateTimeInput;

package/src/inputs/FileInput/doc.mdx

@@ -12,4 +12,4 @@ Input element of type `file` let the user choose one or more files from their de
 
 ### Default
 
-<code src="@digigov/form/inputs/FileInput/__stories__/Default.tsx" />
+<code src="@digigov/form/src/inputs/FileInput/__stories__/Default.tsx" />