@digigov/form 1.2.0-a7ffb5dc → 2.0.0-0138f8bd

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/index.ts

@@ -1,3 +1,6 @@
-export * from '@digigov/form/internal';
+export { default as Field } from '@digigov/form/Field';
+export { default as Fieldset } from '@digigov/form/Fieldset';
+export * from '@digigov/form/inputs/Label';
 import FormBuilder from '@digigov/form/FormBuilder';
+export * from '@digigov/form/types';
 export default FormBuilder;

package/src/inputs/AutoCompleteInput/AutoComplete.stories.js

@@ -1,7 +1,11 @@
 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 * from '@digigov/form/inputs/AutoCompleteInput/__stories__/Default';
+export { Default } from '@digigov/form/inputs/AutoCompleteInput/__stories__/Default';
+export { Multiple } from '@digigov/form/inputs/AutoCompleteInput/__stories__/Multiple';

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

@@ -1,13 +1,15 @@
-import React, { Suspense } from 'react';
+import React from 'react';
 import { Field } from '@digigov/form/Field';
 import FormBuilder from '@digigov/form/FormBuilder';
 import { FieldSpec } from '@digigov/form/types';
-import { results } from '@digigov/ui/form/AutoComplete/utils';
 import Button from '@digigov/ui/form/Button';
+
+const results = ['Αμερική', 'Ασία', 'Αυστραλία', 'Αφρική', 'Ευρώπη'];
+
 const fields: FieldSpec[] = [
   {
     key: 'autocomplete',
-    label: { primary: 'An autocomplete field' },
+    label: { primary: 'Επιλέξτε ήπειρο' },
     required: true,
     type: 'choice:single',
     extra: {
@@ -16,7 +18,7 @@ const fields: FieldSpec[] = [
         return {
           label: {
             primary: r,
-            secondary: `Country: ${r}`,
+            secondary: `'Ηπειρος: ${r}`,
           },
           value: r.toLowerCase(),
         };
@@ -27,19 +29,18 @@ const fields: FieldSpec[] = [
 
 const initialValues = {};
 
-export const Default = () => (
-  <Suspense fallback={<div>loading</div>}>
-    <FormBuilder
-      fields={fields}
-      onSubmit={(data) => {
-        console.log(data);
-      }}
-      initial={initialValues}
-    >
-      {fields.map((field) => (
-        <Field key={field.key} name={field.key} />
-      ))}
-      <Button type="submit">Submit</Button>
-    </FormBuilder>
-  </Suspense>
+export const Default = (_: any) => (
+  <FormBuilder
+    fields={fields}
+    onSubmit={(data) => {
+      console.log(data);
+    }}
+    initial={initialValues}
+  >
+    {fields.map((field) => (
+      <Field key={field.key} name={field.key} />
+    ))}
+    <Button type="submit">Submit</Button>
+  </FormBuilder>
 );
+export default Default;

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

@@ -0,0 +1,47 @@
+import React from 'react';
+import { Field } from '@digigov/form/Field';
+import FormBuilder from '@digigov/form/FormBuilder';
+import { FieldSpec } from '@digigov/form/types';
+import Button from '@digigov/ui/form/Button';
+
+const results = ['Αμερική', 'Ασία', 'Αυστραλία', 'Αφρική', 'Ευρώπη'];
+
+const fields: FieldSpec[] = [
+  {
+    key: 'autocomplete',
+    label: { primary: 'Επιλέξτε ήπειρο' },
+    required: true,
+    type: 'choice:multiple',
+    extra: {
+      component: 'AutoComplete',
+      options: results.map((r) => {
+        return {
+          label: {
+            primary: r,
+            secondary: `Ήπειρος: ${r}`,
+          },
+          value: r.toLowerCase(),
+        };
+      }),
+    },
+  },
+];
+
+const initialValues = {};
+
+export const Multiple = (_: any) => (
+  <FormBuilder
+    fields={fields}
+    onSubmit={(data) => {
+      console.log(data);
+    }}
+    initial={initialValues}
+  >
+    {fields.map((field) => (
+      <Field key={field.key} name={field.key} />
+    ))}
+    <Button type="submit">Submit</Button>
+  </FormBuilder>
+);
+
+export default Multiple;

package/src/inputs/AutoCompleteInput/doc.mdx

@@ -0,0 +1,18 @@
+---
+title: AutoComplete Input 
+---
+ 
+# AutoComplete input
+
+AutoCompleteInput element is an enhanced version of text input that shows suggested 
+options as the users type and also let them select an option from the list.
+
+## How to use
+
+### Default
+
+<code src="@digigov/form/inputs/AutoCompleteInput/__stories__/Default.tsx" />
+
+### Display multiple values
+
+<code src="@digigov/form/inputs/AutoCompleteInput/__stories__/Multiple.tsx" />

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

@@ -0,0 +1,28 @@
+import React from 'react';
+import { test, expect } from '@playwright/experimental-ct-react';
+import TestVariant from '@digigov/ui/utils/TestVariant'
+import { Default } from '@digigov/form/inputs/AutoCompleteInput/__stories__/Default';
+import { Multiple } from '@digigov/form/inputs/AutoCompleteInput/__stories__/Multiple';
+
+test('renders the All AutoCompleteInput variants', async ({ mount, page }) => {
+  await mount(
+    
+  <div>
+    <TestVariant title="Default">
+      <Default />
+    </TestVariant>
+    <TestVariant title="Multiple">
+      <Multiple />
+    </TestVariant>
+  </div>
+  )
+  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,11 +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';
-import UIAutoComplete, {
-  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
   extends Omit<
     UIAutoCompleteProps,
@@ -16,56 +15,66 @@ export interface AutoCompleteInputExtra
     | 'onConfirm'
     | 'dropdownArrow'
   > {
-  options: Array<FieldOptionProps>;
+  options: FieldOptionProps[];
 }
 
 export interface AutoCompleteInputProps
   extends Omit<ControlledFieldProps, 'value' | 'onChange' | 'extra'> {
   extra: AutoCompleteInputExtra;
   value: string;
-  onChange: (v: string) => void;
+  onChange: (v: string | string[] | undefined) => void;
 }
 
 export const AutoCompleteInput: React.FC<AutoCompleteInputProps> = ({
   name,
+  type,
   extra: { options },
   onChange,
   value,
   ...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
-            );
-          })
-        : []
-    );
-  },
-  []);
+  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) => {
-        onChange(value.value);
+        if (Array.isArray(value)) {
+          const selectedValues = value.map((item) => item.value);
+          if (selectedValues.length > 0) onChange(selectedValues);
+          else onChange(undefined);
+        } else {
+          onChange(value.value);
+        }
       }}
       templates={{
         suggestion({ label, value }) {
           return (
-            <div>
+            <Base as="div">
               {(label && label.primary && label.primary) || value}
               {label && label.secondary && <Hint>{label.secondary}</Hint>}
-            </div>
+            </Base>
           );
         },
         inputValue: (option) => {
@@ -75,7 +84,13 @@ export const AutoCompleteInput: React.FC<AutoCompleteInputProps> = ({
           return option.label.primary || option.value;
         },
       }}
-      {...props}
+      {...{
+        ...props,
+        reset: undefined,
+        required: undefined,
+        Field: undefined,
+      }}
+      name={name}
       id={`${name}-id`}
       defaultValue={value}
     />

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

@@ -1,9 +1,12 @@
 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 * from '@digigov/form/inputs/Checkboxes/__stories__/Default';
-export * from '@digigov/form/inputs/Checkboxes/__stories__/WithDivider';
-export * from '@digigov/form/inputs/Checkboxes/__stories__/Conditional';
+export { Default } from '@digigov/form/inputs/Checkboxes/__stories__/Default';
+export { WithDivider } from '@digigov/form/inputs/Checkboxes/__stories__/WithDivider';
+export { Conditional } from '@digigov/form/inputs/Checkboxes/__stories__/Conditional';

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

@@ -6,7 +6,6 @@ const fields: FieldSpec[] = [
   {
     key: 'landline',
     type: 'phone_number',
-
     label: {
       secondary: 'Εισάγετε το νούμερο του σταθερού σας τηλεφώνου.',
     },
@@ -24,7 +23,6 @@ const fields: FieldSpec[] = [
   {
     key: 'mobile_phone',
     type: 'mobile_phone',
-
     label: {
       secondary: 'Εισάγετε το νούμερο του κινητού σας τηλεφώνου.',
     },
@@ -41,7 +39,6 @@ const fields: FieldSpec[] = [
   },
   {
     key: 'email',
-
     type: 'email',
     label: {
       secondary: 'Εισάγετε την διεύθυνση του ηλεκτρονικού σας ταχυδρομείου.',
@@ -87,7 +84,7 @@ const fields: FieldSpec[] = [
   },
 ];
 
-export const Conditional = () => (
+export const Conditional = (_: any) => (
   <FormBuilder
     onSubmit={(data) => {
       console.log(data);
@@ -98,3 +95,5 @@ export const Conditional = () => (
     <Button type="submit">Συνέχεια</Button>
   </FormBuilder>
 );
+
+export default Conditional;

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