feat: record progress bar (#1171)

## JIRA Ticket

[BSS-383](https://jira.csiro.au/browse/BSS-383)

## Description

Add progress bar to top of record edit form to track completion of
required fields.

## Proposed Changes

- add progress bar component
- update current form screens to include new component
- pass state updater to form to update progress
- create helper functions for measuring completion

## How to Test

1. Navigate to any survey
2. Click "+ NEW RECORD" button
3. Input values into required fields an check that progress bar reflects
these changes
4. (optional) Publish and close record
5. (optional) Open published record and verify completion is retained

## Additional Information

The survey form seems reasonably unreliable and might be worth
considering a rebuild at some point.
- the form re-renders around 11 times on load and another 5 times every
few seconds (even without any changes)
- in testing I was able to get into a broken state where I would need to
kill the tab and reload to resolve
- the code uses class components and is thousands of lines long across
multiple files

## Checklist

- [x] I have confirmed all commits have been signed.
- [x] I have added JSDoc style comments to any new functions or classes.
- [x] Relevant documentation such as READMEs, guides, and class comments
are updated.

Author: luke-mcfarlane-rocketlab

app/src/gui/components/progress-bar.tsx

@@ -0,0 +1,44 @@
+interface ProgressBarProps {
+  percentage: number;
+  style?: React.CSSProperties;
+}
+
+/**
+ * ProgressBar component that visually represents the progress based on the percentage prop.
+ *
+ * @param {ProgressBarProps} props - The properties for the component.
+ * @param {number} props.percentage - A value between 0 and 1 representing the completion percentage.
+ * @param {React.CSSProperties} props.style - Additional styles for the progress bar.
+ * @returns {JSX.Element} A visual representation of the progress in the form of a bar and percentage text.
+ */
+export default function ProgressBar({percentage, style}: ProgressBarProps) {
+  const rounded = Math.round(percentage * 100);
+
+  return (
+    <div
+      style={{
+        ...style,
+        display: 'flex',
+        flexDirection: 'column',
+        gap: '6px',
+      }}
+    >
+      <div
+        style={{
+          backgroundColor: '#edeeeb',
+          borderRadius: '6px',
+        }}
+      >
+        <div
+          style={{
+            width: `${rounded}%`,
+            height: '32px',
+            backgroundColor: '#669911',
+            borderRadius: '6px',
+          }}
+        ></div>
+      </div>
+      <div style={{fontSize: '12px'}}>{rounded}% Completed</div>
+    </div>
+  );
+}

app/src/gui/components/record/RecordData.tsx

@@ -62,6 +62,7 @@ interface RecordDataTypes {
   handleUnlink: Function;
   setRevision_id?: Function;
   mq_above_md: boolean;
+  setProgress: React.Dispatch<React.SetStateAction<number>>;
   buttonRef: React.RefObject<HTMLDivElement>;
 }
 
@@ -148,6 +149,7 @@ export default function RecordData(props: RecordDataTypes) {
                         draftLastSaved={props.draftLastSaved}
                         mq_above_md={props.mq_above_md}
                         navigate={navigate}
+                        setProgress={props.setProgress}
                         buttonRef={props.buttonRef}
                       />
                     ) : (
@@ -206,6 +208,7 @@ export default function RecordData(props: RecordDataTypes) {
                       handleSetDraftLastSaved={props.handleSetDraftLastSaved}
                       handleSetDraftError={props.handleSetDraftError}
                       navigate={navigate}
+                      setProgress={props.setProgress}
                       buttonRef={props.buttonRef}
                     />
                   </Box>

app/src/gui/components/record/form.tsx

@@ -68,6 +68,7 @@ import {
 
 import {generateFAIMSDataID, getFirstRecordHead} from '@faims3/data-model';
 import {INDIVIDUAL_NOTEBOOK_ROUTE} from '../../../constants/routes';
+import {percentComplete, requiredFields} from '../../../lib/form-utils';
 import {logError} from '../../../logging';
 import CircularLoading from '../ui/circular_loading';
 import FormButtonGroup from './formButton';
@@ -1114,16 +1115,6 @@ class RecordForm extends React.Component<
   }
 
   isReady(): boolean {
-    // if (DEBUG_APP) {
-    //   if (!this.state.type_cached)
-    //     console.debug('isReady false because type_cached is false');
-    //   if (!this.state.initialValues)
-    //     console.debug('isReady false because initialValues is false');
-    //   if (!this.props.ui_specification)
-    //     console.debug('isReady false because ui_specification is false');
-    //   if (!this.state.view_cached)
-    //     console.debug('isReady false because view_cached is false');
-    // }
     return Boolean(
       this.state.type_cached &&
         this.state.initialValues &&
@@ -1145,39 +1136,6 @@ class RecordForm extends React.Component<
   }
 
   render() {
-    // we can't do this here because it changes state and forces a redraw
-    // if (this.state.draft_created !== null) {
-    //   // If a draft was created, that implies this form started from
-    //   // a non draft, so it must have been an existing record (see props
-    //   // as it's got a type {existing record} | {draft already created}
-    //   (this.context as any).dispatch({
-    //     type: ActionType.ADD_CUSTOM_ALERT,
-    //     payload: {
-    //       severity: 'success',
-    //       element: (
-    //         <React.Fragment>
-    //           <Link
-    //             component={RouterLink}
-    //             to={
-    //               ROUTES.NOTEBOOK +
-    //               this.props.project_id +
-    //               ROUTES.RECORD_EXISTING +
-    //               this.props.record_id! +
-    //               ROUTES.REVISION +
-    //               this.props.revision_id! +
-    //               ROUTES.RECORD_DRAFT +
-    //               this.state.draft_created
-    //             }
-    //           >
-    //             Created new draft
-    //           </Link>
-    //         </React.Fragment>
-    //       ),
-    //     },
-    //   });
-    //   this.setState({draft_created: null});
-    // }
-
     if (this.isReady()) {
       const viewName = this.requireView();
       const viewsetName = this.requireViewsetName();
@@ -1220,6 +1178,13 @@ class RecordForm extends React.Component<
               }}
             >
               {formProps => {
+                this.props.setProgress?.(
+                  percentComplete(
+                    requiredFields(this.props.ui_specification.fields),
+                    formProps.values
+                  )
+                );
+
                 //ONLY update if the updated field is the controller field
                 fieldNames = getFieldsMatchingCondition(
                   this.props.ui_specification,

app/src/gui/pages/record-create.tsx

@@ -63,6 +63,7 @@ import {ParentLinkProps} from '../components/record/relationships/types';
 import {getParentPersistenceData} from '../components/record/relationships/RelatedInformation';
 import InheritedDataComponent from '../components/record/inherited_data';
 import {NOTEBOOK_NAME_CAPITALIZED} from '../../buildconfig';
+import ProgressBar from '../components/progress-bar';
 import TransparentButton from '../components/buttons/transparent-button';
 import {scrollToDiv} from '../../lib/navigation';
 import ArrowDropDown from '@mui/icons-material/ArrowDropDown';
@@ -175,6 +176,8 @@ function DraftEdit(props: DraftEditProps) {
   const [parentLinks, setParentLinks] = useState([] as ParentLinkProps[]);
   const [is_link_ready, setIs_link_ready] = useState(false);
 
+  const [progress, setProgress] = useState(0);
+
   const buttonRef = useRef<HTMLDivElement | null>(null);
 
   useEffect(() => {
@@ -240,117 +243,113 @@ function DraftEdit(props: DraftEditProps) {
     });
     navigate(-1);
     return <React.Fragment />;
-  } else if (uiSpec === null) {
-    // Loading
-    return <CircularProgress size={12} thickness={4} />;
-  } else {
-    // Loaded, variant picked, show form:
+  }
 
-    return (
-      <React.Fragment>
-        <Box mb={2}>
-          <Typography variant={'h2'} component={'h1'}>
-            {uiSpec['viewsets'][type_name]['label'] ?? type_name} Record
-          </Typography>
-          <Typography variant={'subtitle1'} gutterBottom>
-            Add a record for the{' '}
-            {project_info !== null ? project_info.name : project_id} project.
-          </Typography>
-          <div
-            style={{
-              display: 'flex',
-              justifyContent: 'flex-end',
-            }}
-          >
-            <TransparentButton onClick={() => scrollToDiv(buttonRef)}>
-              <ArrowDropDown />
-              Jump to end
-            </TransparentButton>
-          </div>
-        </Box>
-        <Paper square>
-          <TabContext value={value}>
-            <AppBar position="static" color="primary">
-              <TabList
-                onChange={handleChange}
-                aria-label="simple tabs example"
-                indicatorColor={'secondary'}
-                textColor="secondary"
-              >
-                <Tab label="Create" value="1" sx={{color: '#c2c2c2'}} />
-                <Tab label="Meta" value="2" sx={{color: '#c2c2c2'}} />
-              </TabList>
-            </AppBar>
-            <TabPanel value="1" sx={{p: 0}}>
-              <Box>
-                <UnpublishedWarning />
-                <DraftSyncStatus
-                  last_saved={draftLastSaved}
-                  is_saving={isDraftSaving}
-                  error={draftError}
-                />
+  if (uiSpec === null) return <CircularProgress size={12} thickness={4} />;
+
+  return (
+    <React.Fragment>
+      <Box mb={2}>
+        <Typography variant={'h2'} component={'h1'}>
+          {uiSpec['viewsets'][type_name]['label'] ?? type_name} Record
+        </Typography>
+        <Typography variant={'subtitle1'} gutterBottom>
+          Add a record for the{' '}
+          {project_info !== null ? project_info.name : project_id} project.
+        </Typography>
+        <div
+          style={{
+            display: 'flex',
+            justifyContent: 'flex-end',
+          }}
+        >
+          <TransparentButton onClick={() => scrollToDiv(buttonRef)}>
+            <ArrowDropDown />
+            Jump to end
+          </TransparentButton>
+        </div>
+      </Box>
+      <div style={{padding: '10px'}}>
+        <ProgressBar percentage={progress} />
+      </div>
+      <div />
+      <Paper square>
+        <TabContext value={value}>
+          <AppBar position="static" color="primary">
+            <TabList
+              onChange={handleChange}
+              aria-label="simple tabs example"
+              indicatorColor={'secondary'}
+              textColor="secondary"
+            >
+              <Tab label="Create" value="1" sx={{color: '#c2c2c2'}} />
+              <Tab label="Meta" value="2" sx={{color: '#c2c2c2'}} />
+            </TabList>
+          </AppBar>
+          <TabPanel value="1" sx={{p: 0}}>
+            <Box>
+              <UnpublishedWarning />
+              <DraftSyncStatus
+                last_saved={draftLastSaved}
+                is_saving={isDraftSaving}
+                error={draftError}
+              />
+              <Box sx={{backgroundColor: grey[100], p: {xs: 0, sm: 1, md: 2}}}>
                 <Box
-                  sx={{backgroundColor: grey[100], p: {xs: 0, sm: 1, md: 2}}}
+                  component={Paper}
+                  elevation={0}
+                  p={{xs: 1, sm: 1, md: 2, lg: 2}}
+                  variant={is_mobile ? undefined : 'outlined'}
                 >
-                  <Box
-                    component={Paper}
-                    elevation={0}
-                    p={{xs: 1, sm: 1, md: 2, lg: 2}}
-                    variant={is_mobile ? undefined : 'outlined'}
-                  >
-                    {is_link_ready ? (
-                      <InheritedDataComponent
-                        parentRecords={parentLinks}
-                        ui_specification={uiSpec}
-                      />
-                    ) : (
-                      <CircularProgress size={24} />
-                    )}
-                    <RecordForm
-                      project_id={project_id}
-                      record_id={record_id}
-                      type={type_name}
+                  {is_link_ready ? (
+                    <InheritedDataComponent
+                      parentRecords={parentLinks}
                       ui_specification={uiSpec}
-                      draft_id={draft_id}
-                      handleSetIsDraftSaving={setIsDraftSaving}
-                      handleSetDraftLastSaved={setDraftLastSaved}
-                      handleSetDraftError={setDraftError}
-                      draftLastSaved={draftLastSaved}
-                      mq_above_md={mq_above_md}
-                      navigate={navigate}
-                      location={props.location}
-                      buttonRef={buttonRef}
                     />
-                  </Box>
+                  ) : (
+                    <CircularProgress size={24} />
+                  )}
+                  <RecordForm
+                    project_id={project_id}
+                    record_id={record_id}
+                    type={type_name}
+                    ui_specification={uiSpec}
+                    draft_id={draft_id}
+                    handleSetIsDraftSaving={setIsDraftSaving}
+                    handleSetDraftLastSaved={setDraftLastSaved}
+                    handleSetDraftError={setDraftError}
+                    draftLastSaved={draftLastSaved}
+                    mq_above_md={mq_above_md}
+                    navigate={navigate}
+                    location={props.location}
+                    setProgress={setProgress}
+                    buttonRef={buttonRef}
+                  />
                 </Box>
               </Box>
-            </TabPanel>
-            <TabPanel value="2">
-              <Box mt={2}>
-                <Typography variant={'h5'} gutterBottom>
-                  Discard Draft
-                </Typography>
-                <RecordDelete
-                  project_id={project_id}
-                  record_id={record_id}
-                  revision_id={null}
-                  draft_id={draft_id}
-                  show_label={true}
-                  handleRefresh={handleRefresh}
-                />
-              </Box>
-            </TabPanel>
-          </TabContext>
-        </Paper>
-      </React.Fragment>
-    );
-  }
+            </Box>
+          </TabPanel>
+          <TabPanel value="2">
+            <Box mt={2}>
+              <Typography variant={'h5'} gutterBottom>
+                Discard Draft
+              </Typography>
+              <RecordDelete
+                project_id={project_id}
+                record_id={record_id}
+                revision_id={null}
+                draft_id={draft_id}
+                show_label={true}
+                handleRefresh={handleRefresh}
+              />
+            </Box>
+          </TabPanel>
+        </TabContext>
+      </Paper>
+    </React.Fragment>
+  );
 }
 
-// type RecordCreateProps = {
-//   token?: null | undefined | TokenContents;
-// };
-
 export default function RecordCreate() {
   const {project_id, type_name, draft_id, record_id} = useParams<{
     project_id: ProjectID;