@digigov/form 2.0.0-36b707c1 → 2.0.0-385c7994

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.mdx → doc.mdx}

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

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,12 +1,10 @@
 import React, { useCallback } from 'react';
-import { ControlledFieldProps } from '@digigov/form/Field/types';
-import { FieldOptionProps } from '@digigov/form/inputs/Label';
-import { Hint } from '@digigov/react-core/Hint';
-import UIAutoComplete, {
-  AutoCompleteProps as UIAutoCompleteProps,
-} from '@digigov/ui/form/AutoComplete';
-import { Base } from '@digigov/react-core/Base';
-
+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
   extends Omit<
     UIAutoCompleteProps,
@@ -17,7 +15,7 @@ export interface AutoCompleteInputExtra
     | 'onConfirm'
     | 'dropdownArrow'
   > {
-  options: Array<FieldOptionProps>;
+  options: FieldOptionProps[];
 }
 
 export interface AutoCompleteInputProps
@@ -33,36 +31,39 @@ export const AutoCompleteInput: React.FC<AutoCompleteInputProps> = ({
   extra: { options },
   onChange,
   value,
-  error,
   ...props
 }) => {
-  const suggest = useCallback(function suggest(
-    query: string,
-    syncResults: (options: any[]) => void
-  ): void {
-    syncResults(
-      query
-        ? options.filter(function (option) {
-          return (
-            `${option.value} ${option.label?.primary || ''} ${option.label?.secondary || ''
-              }`
-              .toLowerCase()
-              .indexOf(query.toLowerCase()) !== -1
-          );
-        })
-        : options
-    );
-  },
-    [options]);
+  const suggest = useCallback(
+    function suggest(
+      query: string,
+      syncResults: (options: any[]) => void
+    ): void {
+      syncResults(
+        query
+          ? options.filter(function (option) {
+              return (
+                `${option.value} ${option.label?.primary || ''} ${
+                  option.label?.secondary || ''
+                }`
+                  .toLowerCase()
+                  .indexOf(query.toLowerCase()) !== -1
+              );
+            })
+          : options
+      );
+    },
+    [options]
+  );
 
   return (
-    <UIAutoComplete
+    <AutoComplete
       multiple={type === 'choice:multiple' ? true : false}
       source={suggest}
       onConfirm={(value) => {
         if (Array.isArray(value)) {
-          const selectedValues = value.map(item => item.value);
-          selectedValues.length > 0 ? onChange(selectedValues) : onChange(undefined);
+          const selectedValues = value.map((item) => item.value);
+          if (selectedValues.length > 0) onChange(selectedValues);
+          else onChange(undefined);
         } else {
           onChange(value.value);
         }
@@ -87,6 +88,7 @@ export const AutoCompleteInput: React.FC<AutoCompleteInputProps> = ({
         ...props,
         reset: undefined,
         required: undefined,
+        Field: undefined,
       }}
       name={name}
       id={`${name}-id`}
@@ -95,4 +97,4 @@ export const AutoCompleteInput: React.FC<AutoCompleteInputProps> = ({
   );
 };
 
-export default AutoCompleteInput;
+export default AutoCompleteInput;

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.mdx → doc.mdx}

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

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();
 });