@digigov/form 2.0.0-4be8f7cc → 2.0.0-555d1027

package/src/Field/doc.mdx

@@ -0,0 +1,207 @@
+---
+title: Form
+parent: docs/form/components
+---
+
+# Field
+
+Field allow users to create different types of inputs based on data that is described by a particular config schema.
+
+```jsx
+import React from 'react';
+import FormBuilder, { Field } from '@digigov/form';
+import { Button } from '@digigov/ui/form/Button';
+
+const fields = [
+  {
+    key: 'first_name',
+    type: 'string',
+    required: true,
+    label: {
+      primary: 'Ποιo είναι το όνομά σας;',
+    },
+  },
+];
+
+export const MyComponent = () => (
+  <FormBuilder onSubmit={(data) => console.log(data)}>
+    {fields.map(({ key, ...field }) => {
+      return <Field {...field} name={key} key={key} />;
+    })}
+    <Button type="submit">Συνέχεια</Button>
+  </FormBuilder>
+);
+export default MyComponent;
+```
+
+## Accessibility & Usability
+
+Our goal is to create semantically correct and valid forms, which means
+we must avoid mixing form-related HTML elements (like form, input, label) with generic
+ones (such as div, cards, or custom components). For instance, if a paragraph element is
+placed inside a form, React will display warnings in the console. Rather than building overly
+complex interfaces that attempt to accomplish too much too quickly, Digigov Form encourages
+using forms in their intended way—filling out and validating inputs, and then submitting the form
+as a whole.
+
+Additionally, we must ensure our interfaces are fully accessible to screen readers and other
+assistive technologies. This is why we designed the flow to be as guided and recoverable as possible.
+Forms and fields should be clear and logical, reading like well-written text for the users.
+If validation fails, the system provides users with meaningful error messages and clear instructions on how to correct the errors.
+Once validation is successful, the data can be submitted. It is crucial to provide helpful information to users at each step.
+Therefore, we should avoid relying on flashy “magic” UX solutions that assume users have advanced digital skills,
+as these are often intended for expert use cases.
+
+## Introducing the Field component
+
+Field is a component that creates `form` inputs dynamically based on a `data config` schema.
+The config structure is a `key-value` pair of data that describes the input fields and its usage.
+In order to create an input, we need to provide a specific type of input for each field,
+and we can use the `type` property for this.
+
+## Field types
+
+The `type` property determines the type of input field to be rendered. Below are the available types and their descriptions.
+
+| Type              | Input Description                                                                                                                  |
+| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| `int`             | A whole number.                                                                                                                    |
+| `string`          | A text string (e.g., name, address).                                                                                               |
+| `text`            | A larger text input, suitable for paragraphs or multiline text.                                                                    |
+| `boolean`         | A binary value, typically a checkbox or toggle (true/false).                                                                       |
+| `email`           | An email address (e.g., example@example.com).                                                                                      |
+| `uuid4`           | A universally unique identifier (UUID) in version 4 format.                                                                        |
+| `choice:multiple` | A selection of multiple options from a list (e.g., checkboxes).                                                                    |
+| `choice:single`   | A single selection from a list (e.g., radio buttons).                                                                              |
+| `mobile_phone`    | A phone number, typically with country code (e.g., +1-234-567-890).                                                                |
+| `date`            | A date input, typically in the format YYYY-MM-DD.                                                                                  |
+| `datetime`        | A date and time input, typically in the format YYYY-MM-DD HH:MM:SS.                                                                |
+| `otp`             | A one-time password, typically a short numeric or alphanumeric string.                                                             |
+| `afm`             | A Greek Tax Identification Number (AFM).                                                                                           |
+| `iban`            | An International Bank Account Number (IBAN).                                                                                       |
+| `file`            | A file upload input (e.g., for documents, images).                                                                                 |
+| `image`           | A file input that specifically handles images.                                                                                     |
+| `postal_code`     | A postal code input (e.g., ZIP code, postcode).                                                                                    |
+| `phone_number`    | A phone number input (e.g., with or without country code).                                                                         |
+| `array`           | A list of values, typically displayed as multiple inputs ([MultiplicityField](/components/@digigov/form/MultiplicityField.html)).  |
+| `object`          | A structured data object, often used for more complex or nested forms.                                                             |
+
+## Field properties
+
+The Field component accepts several properties, that describes the input fields and its usage.
+
+| Property       | Type                                                                                      | Description                                                                 |
+| -------------- | ----------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
+| `key`          | `string`                                                                                  | The name of the field (TODO: rename to `name`).                             |
+| `type`         | Describes the format of each field, e.g., `type: 'string'` is a simple input format field | The type of input field. Defines the kind of value it accepts.              |
+| `trim`         | `boolean`                                                                                 | If `true`, trims the input value.                                           |
+| `component`    | `any`                                                                                     | A custom React component for the input field.                               |
+| `autoComplete` | `string`                                                                                  | The `autocomplete` attribute value for the input field (e.g., 'on', 'off'). |
+| `maxLength`    | `number`                                                                                  | The maximum number of characters the input can accept.                      |
+| `condition`    | `Record<string, FieldCondition>`                                                          | Conditions for when the field should be shown, enabled, or validated.       |
+| `controlled`   | `boolean`                                                                                 | If `true`, the input value is controlled by React state.                    |
+| `label`        | `FieldLabelProps`                                                                         | The label associated with the input field.                                  |
+| `extra`        | `Record<string, any>`                                                                     | Extra custom attributes or settings for the field.                          |
+| `editable`     | `boolean`                                                                                 | If `false`, the field cannot be edited.                                     |
+| `variant`      | `'inline' \| 'dialog'`                                                                    | Defines the display variant of the field (e.g., inline or in a dialog).     |
+| `required`     | `boolean`                                                                                 | If `true`, the field is required to be filled.                              |
+| `enabled`      | `boolean`                                                                                 | If `false`, the field is disabled and cannot be interacted with.            |
+| `disabled`     | `boolean`                                                                                 | If `true`, the field is disabled.                                           |
+| `layout`       | `Record<string, GridProps['xs' \| 'sm' \| 'md' \| 'lg' \| 'xl']>`                         | Defines the layout settings for the field (grid system).                    |
+| `validators`   | `ValidatorSchema[]`                                                                       | Array of validators to be applied to the input field.                       |
+| `wrapper`      | `'label' \| 'fieldset'`                                                                   | Defines the wrapping element for the field (label or fieldset).             |
+| `maxWidth`     | `string`                                                                                  | The maximum width of the field.                                             |
+| `maxHeight`    | `string`                                                                                  | The maximum height of the field.                                            |
+| `width`        | `string`                                                                                  | The width of the field.                                                     |
+
+### How to use it
+
+The `Field` component is a fundamental building block of the `form`.
+We can implement a `Field` by using the `data config` or we can fill the `Field` directly with its properties.
+
+First, we need to import the `FormBuilder` component from the `@digigov/form` path.
+
+```jsx pure
+import React from 'react';
+import FormBuilder from '@digigov/form';
+import Button from '@digigov/ui/form/Button';
+
+export default function MyFieldComponent() {
+  return (
+    <FormBuilder>
+      {/* this is where all fields will eventually be rendered */}
+      <Button type="submit">Συνέχεια</Button>
+    </FormBuilder>
+  );
+}
+```
+
+#### Data config
+
+The `data config` is an array of objects that contains the configuration for each field.
+
+```jsx pure
+const fields = [
+  {
+    key: 'first_name',
+    type: 'string',
+    required: true,
+    label: {
+      primary: 'Ποιo είναι το όνομά σας;',
+    },
+  },
+];
+```
+
+Then we can use the `fields` array to render the Field(s).
+
+```jsx pure
+import React from 'react';
+import FormBuilder, { Field } from '@digigov/form';
+import { Button } from '@digigov/ui/form/Button';
+
+const fields = [
+  {
+    key: 'first_name',
+    type: 'string',
+    required: true,
+    label: {
+      primary: 'Ποιo είναι το όνομά σας;',
+    },
+  },
+];
+
+export const MyComponent = () => (
+  <FormBuilder onSubmit={(data) => console.log(data)}>
+    {fields.map(({ key, ...field }) => {
+      return <Field {...field} name={key} key={key} />;
+    })}
+    <Button type="submit">Συνέχεια</Button>
+  </FormBuilder>
+);
+export default MyComponent;
+```
+
+#### Directly
+
+We can also use the `Field` component directly and pass the properties to it.
+
+```jsx pure
+import React from 'react';
+import FormBuilder, { Field } from '@digigov/form';
+import { Button } from '@digigov/ui/form/Button';
+
+export const MyComponent = () => (
+  <FormBuilder onSubmit={(data) => console.log(data)}>
+    <Field
+      key="first_name"
+      name="first_name"
+      label={{ primary: 'Οχήματα' }}
+      type="sting"
+      required
+    />
+    <Button type="submit">Συνέχεια</Button>
+  </FormBuilder>
+);
+export default MyComponent;
+```

package/src/Field/index.tsx

@@ -6,10 +6,14 @@ import {
   CalculatedField,
   FieldProps,
 } from '@digigov/form/Field/types';
-import { useField, calculateField } from '@digigov/form/Field/utils';
+import {
+  FIELD_COMPONENTS,
+  ALTERNATIVE_COMPONENTS,
+} from '@digigov/form/Field/utils';
+import { calculateField } from '@digigov/form/Field/utils/calculateField';
+import { useField } from '@digigov/form/Field/utils/useField';
 import FieldArray from '@digigov/form/FieldArray';
 import Multiplicity from '@digigov/form/MultiplicityField';
-
 export const Field: React.FC<FieldProps> = ({
   name,
   children,
@@ -20,6 +24,7 @@ export const Field: React.FC<FieldProps> = ({
     control,
     register,
     reset,
+    resetField,
     error,
     componentRegistry,
     formState,
@@ -30,18 +35,28 @@ export const Field: React.FC<FieldProps> = ({
     clearErrors,
   } = useField(name, customField?.type ? customField : null);
   const calculatedField: CalculatedField = useMemo(
-    () => calculateField(children, field, componentRegistry),
+    () =>
+      calculateField(
+        children,
+        field,
+        {
+          ...FIELD_COMPONENTS,
+          ...componentRegistry,
+        },
+        ALTERNATIVE_COMPONENTS
+      ),
     [field]
   );
-
   if (calculatedField.condition) {
     return (
       <FieldConditional
         control={control}
         reset={reset}
+        resetField={resetField}
         register={register}
         field={calculatedField as FieldWithCondition}
         error={error}
+        Field={Field}
       />
     );
   }
@@ -50,9 +65,18 @@ export const Field: React.FC<FieldProps> = ({
     return (
       <FieldArray
         control={control}
+        trigger={trigger}
         register={register}
-        error={error}
+        clearErrors={clearErrors}
+        error={
+          formState.isSubmitted && !formState.isSubmitting ? error : undefined
+        }
+        getValues={getValues}
+        setValue={setValue}
         formState={formState}
+        Field={Field}
+        reset={reset}
+        resetField={resetField}
         {...calculatedField}
       />
     );
@@ -73,18 +97,28 @@ export const Field: React.FC<FieldProps> = ({
         setValue={setValue}
         getValues={getValues}
         unregister={unregister}
+        resetField={resetField}
+        Field={Field}
         {...calculatedField}
       />
     );
   }
+  const editable =
+    customField.editable === false || customField.disabled === true
+      ? false
+      : true;
+  const customError = error ? error : formState?.errors[name];
   return (
     <FieldBase
       {...calculatedField}
+      editable={editable}
       name={name}
       control={control}
       register={register}
       reset={reset}
-      error={error}
+      error={customError}
+      resetField={resetField}
+      Field={Field}
     />
   );
 };

package/src/Field/types.tsx

@@ -1,11 +1,77 @@
 import React from 'react';
-import { ErrorOption, UseFormReturn } from 'react-hook-form';
-import { FieldSpec } from '@digigov/form/types';
-import { FieldCondition, FormData } from '@digigov/form/types';
+import { ErrorOption, UseFormReturn, UseFormProps } from 'react-hook-form';
+import { ValidatorSchema } from '@digigov/form/validators/types';
+import { FieldsetLegendProps } from '@digigov/ui/form/FieldContainer';
+import { GridProps } from '@digigov/ui/layouts/Grid';
 
+export interface FieldLabelProps {
+  primary?: string;
+  secondary?: string;
+  hint?: string;
+}
+
+export interface FieldSpec {
+  key: string; // !TODO rename key to name;
+  type?:
+    | 'int'
+    | 'string'
+    | 'text'
+    | 'boolean'
+    | 'email'
+    | 'uuid4'
+    | 'choice:multiple'
+    | 'choice:single'
+    | 'mobile_phone'
+    | 'date'
+    | 'datetime'
+    | 'otp'
+    | 'afm'
+    | 'amka'
+    | 'iban'
+    | 'file'
+    | 'image'
+    | 'postal_code'
+    | 'phone_number'
+    | 'array'
+    | 'object';
+  trim?: boolean;
+  component?: any;
+  autoComplete?: string;
+  placeholder?: string;
+  maxLength?: number;
+  condition?: Record<string, FieldCondition>;
+  controlled?: boolean;
+  label?: FieldLabelProps;
+  extra?: Record<string, any>;
+  editable?: boolean;
+  variant?: 'inline' | 'dialog';
+  required?: boolean;
+  enabled?: boolean;
+  disabled?: boolean; // TODO: keep disabled or editable
+  layout?: Record<
+    string,
+    | GridProps['xs']
+    | GridProps['sm']
+    | GridProps['md']
+    | GridProps['lg']
+    | GridProps['xl']
+  >;
+  validators?: ValidatorSchema[];
+  wrapper?: 'label' | 'fieldset';
+  maxWidth?: string;
+  maxHeight?: string;
+  width?: string;
+}
+
+export interface FieldCondition {
+  is: string | string[] | number | number[] | boolean | boolean[];
+  then?: Partial<FieldSpec>;
+  else?: Partial<FieldSpec>;
+}
 export interface ChildFieldMemoProps extends FieldConditionalProps {
   dependencies: FormData;
 }
+export type FormData = UseFormProps['defaultValues'];
 
 export interface FieldWithCondition extends Omit<CalculatedField, 'condition'> {
   condition: Record<string, FieldCondition>;
@@ -16,23 +82,29 @@ export interface FieldConditionalProps {
   control: UseFormReturn['control'];
   register: UseFormReturn['register'];
   reset: UseFormReturn['reset'];
+  resetField?: UseFormReturn['resetField'];
   error?: ErrorOption;
+  Field: React.FC<FieldProps>;
 }
 
-export type FieldComponentItem = {
+export interface FieldComponentItem {
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   component: any;
   controlled?: boolean;
   wrapper?: FieldSpec['wrapper'];
-};
+}
 
 export interface FieldContainerProps {
   name?: FieldSpec['key'];
+  register: FieldBaseProps['register'];
   layout?: FieldSpec['layout'];
   label?: FieldSpec['label'];
   error?: ErrorOption | Record<string, any>;
+  hasError?: boolean;
   children?: React.ReactNode;
+  controlled?: boolean;
   wrapper?: FieldSpec['wrapper'];
+  labelSize?: FieldsetLegendProps['size'];
 }
 
 export type FieldComponentRegistry = Record<string, FieldComponentItem>;
@@ -51,6 +123,7 @@ export interface ControlledFieldProps {
   error?: boolean;
   name?: string;
   disabled?: boolean;
+  Field?: React.FC<FieldProps>;
 }
 
 export interface UncontrolledFieldProps {
@@ -61,6 +134,7 @@ export interface UncontrolledFieldProps {
   extra?: Record<string, never>;
   type?: string;
   disabled?: boolean;
+  Field: React.FC<FieldProps>;
 }
 
 export interface CalculatedField extends OmittedFieldSpec {
@@ -77,6 +151,8 @@ export interface FieldBaseProps extends CalculatedField {
   control: UseFormReturn['control'];
   register: UseFormReturn['register'];
   reset: UseFormReturn['reset'];
+  resetField?: UseFormReturn['resetField'];
+  Field?: React.FC<FieldProps>;
 }
 
 export interface FieldProps extends FieldSpec {
@@ -89,6 +165,7 @@ export interface UseFieldProps {
   control: FieldBaseProps['control'];
   register: FieldBaseProps['register'];
   reset: FieldBaseProps['reset'];
+  resetField: FieldBaseProps['resetField'];
   watch: UseFormReturn['watch'];
   formState: UseFormReturn['formState'];
   getFieldState: UseFormReturn['getFieldState'];

package/src/Field/utils/calculateField.ts

@@ -0,0 +1,49 @@
+import {
+  FieldProps,
+  FieldSpec,
+  FieldComponentRegistry,
+  CalculatedField,
+} from '@digigov/form/Field/types';
+
+export function calculateField(
+  children: FieldProps['children'],
+  field: FieldSpec,
+  fieldComponentRegistry: FieldComponentRegistry,
+  alternativeComponents: FieldComponentRegistry
+): CalculatedField {
+  const calculatedField = { ...field };
+  if (children) {
+    calculatedField.component = children;
+    calculatedField.controlled = true;
+  } else if (typeof field.component === 'function') {
+    // leave as is
+  } else if (!field.component && !field.type) {
+    calculatedField.component = fieldComponentRegistry.string.component;
+    calculatedField.controlled =
+      fieldComponentRegistry.string?.controlled || false;
+  } else if (
+    typeof field?.extra?.component === 'string' &&
+    alternativeComponents[field.extra.component]
+  ) {
+    calculatedField.controlled =
+      alternativeComponents[field.extra.component]?.controlled || false;
+    calculatedField.component =
+      alternativeComponents[field.extra.component].component;
+    calculatedField.wrapper =
+      alternativeComponents[field.extra.component].wrapper;
+  } else if (
+    !field.component &&
+    field.type &&
+    fieldComponentRegistry[field.type]
+  ) {
+    calculatedField.component = fieldComponentRegistry[field.type].component;
+    calculatedField.wrapper = fieldComponentRegistry[field.type].wrapper;
+    calculatedField.controlled =
+      fieldComponentRegistry[field.type]?.controlled || false;
+  } else {
+    calculatedField.component = fieldComponentRegistry.string.component;
+    calculatedField.controlled =
+      fieldComponentRegistry.string?.controlled || false;
+  }
+  return calculatedField as CalculatedField;
+}

package/src/Field/utils/evaluateFieldWithConditions.ts

@@ -0,0 +1,30 @@
+import { FieldWithCondition, CalculatedField } from '@digigov/form/Field/types';
+
+export function evaluateFieldWithConditions(
+  field: FieldWithCondition,
+  variables: FormData
+): CalculatedField {
+  const newField = { ...field };
+  if (variables) {
+    for (const key in variables) {
+      if (field.condition[key] && field.condition[key].is) {
+        const is = field.condition[key].is;
+        if (
+          is === variables[key] ||
+          (Array.isArray(variables[key]) && variables[key].includes(is))
+        ) {
+          const then = field.condition[key].then || {};
+          for (const attr in then) {
+            newField[attr] = then[attr];
+          }
+        }
+      } else if (field.condition[key]) {
+        const otherwise = field.condition[key].else || {};
+        for (const attr in otherwise) {
+          newField[attr] = otherwise[attr];
+        }
+      }
+    }
+  }
+  return newField;
+}

package/src/Field/utils/index.ts

@@ -0,0 +1,84 @@
+import { FieldComponentRegistry } from '@digigov/form/Field/types';
+import AutoCompleteInput from '@digigov/form/inputs/AutoCompleteInput';
+import Checkboxes from '@digigov/form/inputs/Checkboxes';
+import DateInput from '@digigov/form/inputs/DateInput';
+import DateTimeInput from '@digigov/form/inputs/DateTimeInput';
+import FileInput from '@digigov/form/inputs/FileInput';
+import ImageInput from '@digigov/form/inputs/ImageInput';
+import Input from '@digigov/form/inputs/Input';
+import OtpInput from '@digigov/form/inputs/OtpInput';
+import Radio, { ControlledRadioButtonsGroup } from '@digigov/form/inputs/Radio';
+import Select from '@digigov/form/inputs/Select';
+
+export const FIELD_COMPONENTS: FieldComponentRegistry = {
+  text: {
+    component: Input,
+  },
+  string: {
+    component: Input,
+  },
+  file: {
+    wrapper: 'fieldset',
+    component: FileInput,
+    // controlled: true,
+  },
+  image: {
+    wrapper: 'fieldset',
+    component: ImageInput,
+    controlled: true,
+  },
+  date: {
+    wrapper: 'fieldset',
+    controlled: true,
+    component: DateInput,
+  },
+  datetime: {
+    wrapper: 'fieldset',
+    controlled: true,
+    component: DateTimeInput,
+  },
+  otp: {
+    wrapper: 'fieldset',
+    controlled: true,
+    component: OtpInput,
+  },
+  'choice:multiple': {
+    wrapper: 'fieldset',
+    controlled: true,
+    component: Checkboxes,
+  },
+  'choice:single': {
+    wrapper: 'fieldset',
+    controlled: false,
+    component: Radio,
+  },
+};
+
+export const ALTERNATIVE_COMPONENTS: FieldComponentRegistry = {
+  Select: {
+    component: Select,
+    controlled: false,
+  },
+  AutoComplete: {
+    component: AutoCompleteInput,
+    controlled: true,
+    wrapper: 'fieldset',
+  },
+};
+
+export const CONTROLLED_FIELD_COMPONENTS: FieldComponentRegistry = {
+  ...FIELD_COMPONENTS,
+  'choice:single': {
+    wrapper: 'fieldset',
+    controlled: true,
+    component: ControlledRadioButtonsGroup,
+  },
+  text: {
+    component: Input,
+    controlled: true,
+  },
+  string: {
+    component: Input,
+    controlled: true,
+  },
+};

package/src/Field/utils/useField.ts

@@ -0,0 +1,66 @@
+import { useContext, useMemo } from 'react';
+import { FieldSpec, UseFieldProps } from '@digigov/form/Field/types';
+import { FormContext } from '@digigov/form/FormContext';
+
+export const useField = (
+  name: string,
+  customField: FieldSpec | null
+): UseFieldProps => {
+  const {
+    fieldsMap,
+    control,
+    register,
+    reset,
+    resetField,
+    trigger,
+    clearErrors,
+    errors,
+    registerField,
+    watch,
+    componentRegistry,
+    getFieldState,
+    setValue,
+    getValues,
+    unregister,
+    formState,
+  } = useContext(FormContext);
+  if (!registerField) {
+    throw new Error(`
+      You can't use the Field component without wrapping it in FormBuilder.
+      https://devs.pages.grnet.gr/digigov/digigov-sdk/sdk-docs/forms/create-simple-form/
+    `);
+  }
+  let error = errors[name];
+
+  const nameIndexRegex = name.match(/^\[*(.*?)\.(\d+)\]*$/);
+  if (nameIndexRegex) {
+    const [, fieldArrayName, indexStr] = nameIndexRegex;
+    error = errors[fieldArrayName]?.[Number(indexStr)];
+  }
+  const nestedNameIndexRegex = name.match(/^\[*(.*?)\.(\d+)\.(.*?)\]*$/);
+  if (nestedNameIndexRegex) {
+    const [, fieldArrayName, indexStr, fieldItemName] = nestedNameIndexRegex;
+    error = errors[fieldArrayName]?.[Number(indexStr)]?.[fieldItemName];
+  }
+  useMemo(
+    () => customField?.type && registerField({ ...customField, key: name }),
+    [customField, name, registerField]
+  );
+  return {
+    field: customField || fieldsMap[name],
+    control,
+    register,
+    reset,
+    resetField,
+    trigger,
+    watch,
+    componentRegistry,
+    getFieldState,
+    setValue,
+    clearErrors,
+    getValues,
+    unregister,
+    formState,
+    error,
+  };
+};