@digigov/form 2.0.0-6452adf3 → 2.0.0-66d7c5e2

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/AutoComplete.stories.js

@@ -1,7 +1,10 @@
 import AutoComplete from '@digigov/form/inputs/AutoCompleteInput';
+import doc from './doc.mdx?raw';
 export default {
   title: 'Digigov Form/inputs/AutoCompleteInput',
   component: AutoComplete,
+  tags: ['autodocs'],
+  markdown: doc,
   displayName: 'AutoCompleteInput',
 };
 export { Default } from '@digigov/form/inputs/AutoCompleteInput/__stories__/Default';

package/src/inputs/AutoCompleteInput/__stories__/Default.tsx

@@ -4,13 +4,7 @@ import FormBuilder from '@digigov/form/FormBuilder';
 import { FieldSpec } from '@digigov/form/types';
 import Button from '@digigov/ui/form/Button';
 
-const results = [
-  'Αμερική',
-  'Ασία',
-  'Αυστραλία',
-  'Αφρική',
-  'Ευρώπη',
-];
+const results = ['Αμερική', 'Ασία', 'Αυστραλία', 'Αφρική', 'Ευρώπη'];
 
 const fields: FieldSpec[] = [
   {
@@ -35,8 +29,7 @@ const fields: FieldSpec[] = [
 
 const initialValues = {};
 
-export const Default = () => (
-
+export const Default = (_: any) => (
   <FormBuilder
     fields={fields}
     onSubmit={(data) => {
@@ -49,6 +42,5 @@ export const Default = () => (
     ))}
     <Button type="submit">Submit</Button>
   </FormBuilder>
-
 );
-export default Default;
+export default Default;

package/src/inputs/AutoCompleteInput/__stories__/Multiple.tsx

@@ -4,13 +4,7 @@ import FormBuilder from '@digigov/form/FormBuilder';
 import { FieldSpec } from '@digigov/form/types';
 import Button from '@digigov/ui/form/Button';
 
-const results = [
-  'Αμερική',
-  'Ασία',
-  'Αυστραλία',
-  'Αφρική',
-  'Ευρώπη',
-];
+const results = ['Αμερική', 'Ασία', 'Αυστραλία', 'Αφρική', 'Ευρώπη'];
 
 const fields: FieldSpec[] = [
   {
@@ -35,7 +29,7 @@ const fields: FieldSpec[] = [
 
 const initialValues = {};
 
-export const Multiple = () => (
+export const Multiple = (_: any) => (
   <FormBuilder
     fields={fields}
     onSubmit={(data) => {

package/src/inputs/AutoCompleteInput/index.test.tsx

@@ -18,6 +18,10 @@ test('renders the All AutoCompleteInput variants', async ({ mount, page }) => {
   )
   await page.evaluate(() => document.fonts.ready);
 
+  // Move the mouse to the top-left corner to avoid random hover issues
+  await page.mouse.move(0, 0);
+
+
   const screenshot = await page.screenshot({ fullPage: true, animations: 'disabled' });
   expect(screenshot).toMatchSnapshot();
 });

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
@@ -17,7 +15,7 @@ export interface AutoCompleteInputExtra
     | 'onConfirm'
     | 'dropdownArrow'
   > {
-  options: Array<FieldOptionProps>;
+  options: FieldOptionProps[];
 }
 
 export interface AutoCompleteInputProps
@@ -33,7 +31,6 @@ export const AutoCompleteInput: React.FC<AutoCompleteInputProps> = ({
   extra: { options },
   onChange,
   value,
-  error,
   ...props
 }) => {
   const suggest = useCallback(
@@ -65,9 +62,8 @@ export const AutoCompleteInput: React.FC<AutoCompleteInputProps> = ({
       onConfirm={(value) => {
         if (Array.isArray(value)) {
           const selectedValues = value.map((item) => item.value);
-          selectedValues.length > 0
-            ? onChange(selectedValues)
-            : onChange(undefined);
+          if (selectedValues.length > 0) onChange(selectedValues);
+          else onChange(undefined);
         } else {
           onChange(value.value);
         }
@@ -92,6 +88,7 @@ export const AutoCompleteInput: React.FC<AutoCompleteInputProps> = ({
         ...props,
         reset: undefined,
         required: undefined,
+        Field: undefined,
       }}
       name={name}
       id={`${name}-id`}

package/src/inputs/Checkboxes/Checkboxes.stories.js

@@ -1,7 +1,10 @@
 import Checkboxes from '@digigov/form/inputs/Checkboxes';
+import doc from './doc.mdx?raw';
 export default {
   title: 'Digigov Form/inputs/Checkboxes',
   component: Checkboxes,
+  tags: ['autodocs'],
+  markdown: doc,
   displayName: 'Checkboxes',
 };
 export { Default } from '@digigov/form/inputs/Checkboxes/__stories__/Default';

package/src/inputs/Checkboxes/__stories__/Conditional.tsx

@@ -84,7 +84,7 @@ const fields: FieldSpec[] = [
   },
 ];
 
-export const Conditional = () => (
+export const Conditional = (_: any) => (
   <FormBuilder
     onSubmit={(data) => {
       console.log(data);

package/src/inputs/Checkboxes/__stories__/Default.tsx

@@ -2,7 +2,7 @@ import React from 'react';
 import FormBuilder, { Field } from '@digigov/form';
 import { Button } from '@digigov/ui/form/Button';
 
-export const Default = () => (
+export const Default = (_: any) => (
   <FormBuilder
     onSubmit={(data) => {
       console.log(data);

package/src/inputs/Checkboxes/__stories__/WithDivider.tsx

@@ -2,7 +2,7 @@ import React from 'react';
 import FormBuilder, { Field } from '@digigov/form';
 import { Button } from '@digigov/ui/form/Button';
 
-export const WithDivider = () => (
+export const WithDivider = (_: any) => (
   <FormBuilder
     onSubmit={(data) => {
       console.log(data);

package/src/inputs/Checkboxes/index.test.tsx

@@ -22,6 +22,10 @@ test('renders the All Checkboxes variants', async ({ mount, page }) => {
   )
   await page.evaluate(() => document.fonts.ready);
 
+  // Move the mouse to the top-left corner to avoid random hover issues
+  await page.mouse.move(0, 0);
+
+
   const screenshot = await page.screenshot({ fullPage: true, animations: 'disabled' });
   expect(screenshot).toMatchSnapshot();
 });

package/src/inputs/Checkboxes/index.tsx

@@ -1,6 +1,6 @@
 import React, { useState } from 'react';
-import { ControlledFieldProps } from '@digigov/form/Field/types';
-import { FieldOptionProps } from '@digigov/form/inputs/Label';
+import type { ControlledFieldProps } from '@digigov/form/Field/types';
+import type { FieldOptionProps } from '@digigov/form/inputs/Label';
 import {
   Checkbox,
   CheckboxItem,
@@ -14,99 +14,105 @@ export interface CheckboxesProps
   value?: string[];
   extra: {
     className?: string;
-    options: Array<FieldOptionProps>;
+    options: FieldOptionProps[];
   };
   fieldComponent: React.FC<Omit<ControlledFieldProps, 'value' | 'onChange'>>;
 }
 
-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;
-      if (evt.currentTarget.checked) {
-        // eslint-disable-next-line @typescript-eslint/ban-ts-comment
-        // @ts-ignore
-        newValue = value.concat([optionValue]);
-      } else {
-        // eslint-disable-next-line @typescript-eslint/ban-ts-comment
-        // @ts-ignore
-        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}`}
-              value={v}
-              disabled={disabled || optionDisabled}
-              checked={value?.includes(v)}
-              onChange={handleChange(v, index, show)}
-              {...option}
-              {...{
-                ...props,
-                reset: undefined,
-                defaultValue: 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}
+                {...{
+                  ...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>
 
-            {!!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;