[OGUI-1831] Introduce react hook form library (#3210)

Introduced react-hook-form library for better form state management and validation.

Author: sKrzysieK

Configuration/webapp/app/api/axiosInstance.ts

@@ -21,7 +21,6 @@ const axiosInstance = axios.create({
   baseURL: API_URL,
   headers: {
     'Content-Type': 'application/json',
-    'User-Agent': 'axios 0.21.1',
   },
   withCredentials: false,
 });

Configuration/webapp/app/components/form/AccordionHeader.tsx

@@ -25,6 +25,14 @@ interface AccordionHeaderProps extends PropsWithChildren {
   viewFormToggle: () => void;
 }
 
+/**
+ * Accordion header component.
+ * @param {AccordionHeaderProps} props - The props of the accordion header.
+ * @param {string} props.title - The title of the accordion header.
+ * @param {boolean} props.viewForm - Whether the form is visible.
+ * @param {() => void} props.viewFormToggle - The callback to toggle the form visibility.
+ * @returns {ReactElement} The accordion header component.
+ */
 export const AccordionHeader: FC<AccordionHeaderProps> = ({
   title,
   viewForm,

Configuration/webapp/app/components/form/Form.tsx

@@ -19,6 +19,9 @@ import Stack from '@mui/material/Stack';
 import { Widget } from './Widget';
 import { AccordionHeader } from './AccordionHeader';
 import { Typography } from '@mui/material';
+import type { Control } from 'react-hook-form';
+import { type InputsType } from '~/routes/configuration';
+import { KEY_SEPARATOR } from './constants';
 
 export type FormItem = { [key: string]: string | object | FormItem };
 
@@ -28,8 +31,10 @@ export type FormRestrictions = {
 
 interface FormProps extends PropsWithChildren {
   sectionTitle: string;
+  sectionPrefix: string;
   items: FormItem;
   itemsRestrictions: FormRestrictions;
+  control: Control<InputsType>;
 }
 
 /**
@@ -45,7 +50,23 @@ function isFormRestrictions(obj: FormRestrictions[string]): obj is FormRestricti
   return obj instanceof Object && !(obj instanceof Array);
 }
 
-export const Form: FC<FormProps> = ({ sectionTitle, items, itemsRestrictions }) => {
+/**
+ * Form component.
+ * @param {FormProps} props - The props of the form.
+ * @param {string} props.sectionTitle - The title of the section.
+ * @param {string} props.sectionPrefix - The prefix of the section.
+ * @param {FormItem} props.items - The items of the form.
+ * @param {FormRestrictions} props.itemsRestrictions - The restrictions of the items.
+ * @param {Control<InputsType>} props.control - The control of the form.
+ * @returns {ReactElement} The form component.
+ */
+export const Form: FC<FormProps> = ({
+  sectionTitle,
+  sectionPrefix,
+  items,
+  itemsRestrictions,
+  control,
+}) => {
   const [viewForm, setViewForm] = useState<boolean>(true);
 
   const renderItem = useCallback(
@@ -54,11 +75,20 @@ export const Form: FC<FormProps> = ({ sectionTitle, items, itemsRestrictions })
         <Form
           key={key}
           sectionTitle={key}
+          sectionPrefix={`${sectionPrefix}${KEY_SEPARATOR}${key}`}
           items={items[key] as FormItem}
           itemsRestrictions={itemsRestrictions[key] as FormRestrictions}
+          control={control}
         />
       ) : (
-        <Widget key={key} title={key} type={value} value={items[key]} />
+        <Widget
+          key={key}
+          sectionPrefix={`${sectionPrefix}${KEY_SEPARATOR}${key}`}
+          label={key}
+          type={value}
+          value={items[key]}
+          control={control}
+        />
       ),
     [items, itemsRestrictions],
   );

Configuration/webapp/app/components/form/SaveButton.tsx

@@ -0,0 +1,47 @@
+/**
+ * @license
+ * Copyright 2019-2020 CERN and copyright holders of ALICE O2.
+ * See http://alice-o2.web.cern.ch/copyright for details of the copyright holders.
+ * All rights not expressly granted are reserved.
+ *
+ * This software is distributed under the terms of the GNU General Public
+ * License v3 (GPL Version 3), copied verbatim in the file "COPYING".
+ *
+ * In applying this license CERN does not waive the privileges and immunities
+ * granted to it by virtue of its status as an Intergovernmental Organization
+ * or submit itself to any jurisdiction.
+ */
+
+import { Fab, Typography } from '@mui/material';
+
+interface SaveButtonProps {
+  onClick: () => void;
+  disabled: boolean;
+}
+
+const fabStyle = {
+  position: 'absolute',
+  bottom: 16,
+  right: 16,
+  padding: 5,
+};
+
+/**
+ * Save button component.
+ * @param {SaveButtonProps} props - The props of the save button.
+ * @param {() => void} props.onClick - The callback to click the save button.
+ * @param {boolean} props.disabled - Whether the save button is disabled.
+ * @returns {ReactElement} The save button component.
+ */
+export const SaveButton = ({ onClick, disabled }: SaveButtonProps) => (
+  <Fab
+    color="primary"
+    aria-label="add"
+    onClick={onClick}
+    disabled={disabled}
+    sx={fabStyle}
+    variant="extended"
+  >
+    <Typography variant="h6">SAVE</Typography>
+  </Fab>
+);

Configuration/webapp/app/components/form/Widget.tsx

@@ -13,26 +13,39 @@
  */
 
 import { type FC, type PropsWithChildren, type ReactElement } from 'react';
-import FormControlLabel from '@mui/material/FormControlLabel';
-import TextField from '@mui/material/TextField';
-import Switch from '@mui/material/Switch';
+import { useFormState, type Control } from 'react-hook-form';
+import type { InputsType } from '~/routes/configuration';
+import { FormTextInput } from './widgets/FormTextInput';
+import { FormNumberInput } from './widgets/FormNumberInput';
+import { FormToggleInput } from './widgets/FormToggleInput';
 
-interface WidgetProps extends PropsWithChildren {
-  title: string;
+export interface WidgetProps extends PropsWithChildren {
+  sectionPrefix: string;
+  label: string;
   type: 'string' | 'number' | 'boolean' | 'array';
   value: unknown;
+  control: Control<InputsType>;
 }
 
-export const Widget: FC<WidgetProps> = ({ title, type, value }): ReactElement => {
+/**
+ * Widget component.
+ * @param {WidgetProps} props - The props of the widget.
+ * @param {string} props.type - The type of the widget.
+ * @param {string} props.label - The label of the widget.
+ * @param {unknown} props.value - The value of the widget.
+ * @param {Control<InputsType>} props.control - The control of the widget.
+ * @returns {ReactElement} The widget component.
+ */
+export const Widget: FC<WidgetProps> = ({ type, ...rest }): ReactElement => {
+  const { dirtyFields } = useFormState({ control: rest.control });
+  const isDirty = dirtyFields[rest.sectionPrefix];
   switch (type) {
     case 'string':
-      return <TextField type="text" defaultValue={value} label={title} />;
+      return <FormTextInput {...rest} isDirty={Boolean(isDirty)} />;
     case 'number':
-      return <TextField type="number" defaultValue={value} label={title} />;
+      return <FormNumberInput {...rest} isDirty={Boolean(isDirty)} />;
     case 'boolean':
-      return (
-        <FormControlLabel control={<Switch defaultChecked={value === 'true'} />} label={title} />
-      );
+      return <FormToggleInput {...rest} isDirty={Boolean(isDirty)} />;
     case 'array':
       return <>array not implemented</>; // TODO OGUI-1803: add implementation after the decision is made
   }

Configuration/webapp/app/components/form/constants.ts

@@ -0,0 +1,16 @@
+/**
+ * @license
+ * Copyright 2019-2020 CERN and copyright holders of ALICE O2.
+ * See http://alice-o2.web.cern.ch/copyright for details of the copyright holders.
+ * All rights not expressly granted are reserved.
+ *
+ * This software is distributed under the terms of the GNU General Public
+ * License v3 (GPL Version 3), copied verbatim in the file "COPYING".
+ *
+ * In applying this license CERN does not waive the privileges and immunities
+ * granted to it by virtue of its status as an Intergovernmental Organization
+ * or submit itself to any jurisdiction.
+ */
+
+export const KEY_SEPARATOR = '__';
+export const DEFAULT_PREFIX = 'Configuration';

Configuration/webapp/app/components/form/utils/getDefaultValuesFromConfigObject.ts

@@ -0,0 +1,52 @@
+/**
+ * @license
+ * Copyright 2019-2020 CERN and copyright holders of ALICE O2.
+ * See http://alice-o2.web.cern.ch/copyright for details of the copyright holders.
+ * All rights not expressly granted are reserved.
+ *
+ * This software is distributed under the terms of the GNU General Public
+ * License v3 (GPL Version 3), copied verbatim in the file "COPYING".
+ *
+ * In applying this license CERN does not waive the privileges and immunities
+ * granted to it by virtue of its status as an Intergovernmental Organization
+ * or submit itself to any jurisdiction.
+ */
+
+import { DEFAULT_PREFIX, KEY_SEPARATOR } from '../constants';
+import type { FormItem } from '../Form';
+
+/**
+ * Get the default values from the configuration object.
+ * @param {FormItem | undefined} obj - The configuration object.
+ * @param {string} prefix - The prefix of the configuration object.
+ * @returns {Record<string, string | number | boolean>} The default values.
+ */
+export const getDefaultValuesFromConfigObject = (
+  obj: FormItem | undefined,
+  prefix: string = DEFAULT_PREFIX,
+) => {
+  if (!obj) {
+    return {};
+  }
+  // omit arrays for now
+  if (Array.isArray(obj)) {
+    return {};
+  }
+  let result: Record<string, string | number | boolean> = {};
+  const entries = Object.entries(obj);
+  for (const [key, value] of entries) {
+    const newPrefix = `${prefix}${KEY_SEPARATOR}${key}`;
+    if (typeof value === 'object') {
+      result = { ...result, ...getDefaultValuesFromConfigObject(value as FormItem, newPrefix) };
+    } else {
+      if (value === 'true') {
+        result[newPrefix] = true;
+      } else if (value === 'false') {
+        result[newPrefix] = false;
+      } else {
+        result[newPrefix] = value;
+      }
+    }
+  }
+  return result;
+};

Configuration/webapp/app/components/form/widgets/FormNumberInput.tsx

@@ -0,0 +1,54 @@
+/**
+ * @license
+ * Copyright 2019-2020 CERN and copyright holders of ALICE O2.
+ * See http://alice-o2.web.cern.ch/copyright for details of the copyright holders.
+ * All rights not expressly granted are reserved.
+ *
+ * This software is distributed under the terms of the GNU General Public
+ * License v3 (GPL Version 3), copied verbatim in the file "COPYING".
+ *
+ * In applying this license CERN does not waive the privileges and immunities
+ * granted to it by virtue of its status as an Intergovernmental Organization
+ * or submit itself to any jurisdiction.
+ */
+
+interface FormNumberInputProps extends Omit<WidgetProps, 'type' | 'value'> {
+  isDirty: boolean;
+}
+
+import { Controller } from 'react-hook-form';
+import type { WidgetProps } from '../Widget';
+import { TextField } from '@mui/material';
+import type { ReactElement } from 'react';
+
+/**
+ * Number input widget for the form.
+ * @param {FormNumberInputProps} props - The props of the widget.
+ * @param {string} props.sectionPrefix - The prefix of the section.
+ * @param {string} props.label - The label of the widget.
+ * @param {Control<InputsType>} props.control - The control of the widget.
+ * @param {boolean} props.isDirty - Whether the widget is dirty.
+ * @returns {ReactElement} The number input widget.
+ */
+export const FormNumberInput = ({
+  sectionPrefix,
+  label,
+  control,
+  isDirty,
+}: FormNumberInputProps): ReactElement => (
+  <Controller
+    name={sectionPrefix}
+    control={control}
+    render={({ field, fieldState: { error } }) => (
+      <TextField
+        type="number"
+        label={label}
+        {...field}
+        error={Boolean(error)}
+        color={isDirty ? 'secondary' : 'primary'}
+        focused={isDirty}
+        helperText={error?.message}
+      />
+    )}
+  />
+);

Configuration/webapp/app/components/form/widgets/FormTextInput.tsx

@@ -0,0 +1,53 @@
+/**
+ * @license
+ * Copyright 2019-2020 CERN and copyright holders of ALICE O2.
+ * See http://alice-o2.web.cern.ch/copyright for details of the copyright holders.
+ * All rights not expressly granted are reserved.
+ *
+ * This software is distributed under the terms of the GNU General Public
+ * License v3 (GPL Version 3), copied verbatim in the file "COPYING".
+ *
+ * In applying this license CERN does not waive the privileges and immunities
+ * granted to it by virtue of its status as an Intergovernmental Organization
+ * or submit itself to any jurisdiction.
+ */
+
+import { TextField } from '@mui/material';
+import { type ReactElement } from 'react';
+import { Controller } from 'react-hook-form';
+import type { WidgetProps } from '../Widget';
+
+interface FormTextInputProps extends Omit<WidgetProps, 'type' | 'value'> {
+  isDirty: boolean;
+}
+
+/**
+ * Text input widget for the form.
+ * @param {FormTextInputProps} props - The props of the widget.
+ * @param {string} props.sectionTitle  - The section title of the widget.
+ * @param {string} props.label - The title of the widget.
+ * @param {Control<InputsType>} props.control - The control of the widget.
+ * @returns {ReactElement} The text input widget.
+ */
+export const FormTextInput = ({
+  sectionPrefix,
+  label,
+  control,
+  isDirty,
+}: FormTextInputProps): ReactElement => (
+  <Controller
+    name={sectionPrefix}
+    control={control}
+    render={({ field, fieldState: { error } }) => (
+      <TextField
+        type="text"
+        label={label}
+        {...field}
+        error={Boolean(error)}
+        color={isDirty ? 'secondary' : 'primary'}
+        focused={isDirty}
+        helperText={error?.message}
+      />
+    )}
+  />
+);