Action/Submission Form System Cleanup

[hannasage]

Related JIRA Ticket: https://qmacbis.atlassian.net/browse/OY2-27178

Introduction

Purpose of the Discussion: This discussion aims to land on ideas that significantly enhance the maintainability and efficiency of our form system within the React codebase, and a strategy for implementation.

Summarized Objectives:

1. Enhanced Maintainability: We aim to restructure our form system to make it more maintainable, addressing current challenges in code management and future modifications.
2. Increased Efficiency in Form Generation: The goal is to streamline the process of creating new forms or variants, enabling quicker and more efficient form generation.
3. Simplified Testing Process: By extracting logic and data from React components, we intend to simplify the testing process, focusing on more manageable units and reducing the overall testing burden.
4. Documentation and Replicability: We plan to develop a system that is not only well-documented but also easily replicable, ensuring consistency and ease of understanding across the development team.

Background Information

Our current repository includes over 10 forms that have been developed through a process of copying and pasting code. This approach, while expedient at first, has led to a complex codebase that is difficult to manage and prone to subtle, hard-to-detect bugs. A strategic refactor is necessary to address these challenges and streamline our development process.

Development, Maintenance, and Testing Issues

• Multiple Subrouters: Having a sub-routing system exclusive to Waiver Actions and SPA Actions has created inconsistencies in how identical actions are plugged in and accessed depending on the ItemResult's authority. This is further complicated by New Submission's router that follows no similar structure.
• Multiple component extraction patterns: Having two patterns for extracting and re-using common form components and component groups doubles the area in which visual and semantic bugs can occur
• Repetition of exact behaviors: Forms exhibit the same behaviors with modals(*), redirection, banners, network interactions, etc. Therefor increasing the number of times this is programmed, we're multiplying our ability to introduce bugs in the expected behavior of a single form.

* Modals do have an exception with Withdraw actions, as they're destructive actions that require one additional confirmation before submission

Criteria for a New System

Needs:

1. Unified route structure and subrouter
2. Unified extraction pattern for components
3. Unifying consistently replicated UI behaviors
4. Approach must be able to be documented for posterity so new engineers can pick up the repo and learn how to use the form system.

💡 This is where our discussion comes in!

Wants:

1. Extraction of content strings for re-use/isolation of concern
2. TBD

Discussion Prompts

What's your ideal form system look like?
How does that system improve the developer experience and user experience?
What are the foreseeable cons of your desired approach?

[hannasage]

Pinging @pkim-gswell @13bfrancis @mdial89f @benjaminpaige

[hannasage]

What's your ideal form system look like?

My ideal system has clear separations of the primary form concerns as I see them: content, network behavior, UI/UX behavior, and form configurations. Each of these concerns are individually testable for rigidity (particularly network and config code), and create clearer steps for developing future forms (i.e. add this, then add that, then wire it up here, etc.)

A napkin-sketch of an idea:

In our current setup, networking is efficiently managed by submissionService, while modal and alert functionalities are neatly encapsulated within ModalContext and AlertContext.

To further refine our system, we propose introducing FormEngine.tsx, a robust engine designed to interpret configurations and render them, integrating seamlessly with our form and submission controls. Utilizing a prop such as isDestructive, it can also smartly handle conditional confirmations for destructive actions. The engine's prop structure will mirror the configuration setup, encompassing elements like content, schemas, and a field map needed for UI generation.

These configurations will be accessed through a unified router like FormRouter.tsx, utilizing a streamlined path structure like /new/spa/medicaid or /action/spa/issue-rai/MD-12-3456, replacing the current /:authority/:id/:type format with a slight variation, /:authority/:type/:id, so id can be undefined for new submissions but still accessed and used by actions.

---

FormRouter.tsx pseudocode:

// get params from URL
const { authority, type, id } =  useParams("/:authority/:type/:id")
// use authority and type to determine what config to pull in
const formConfig = getFormConfig(authority, type)
// render config using `FormEngine`
return <FormEngine {...formConfig} />

How does that system improve the developer experience and user experience?

DX:

1. Aforementioned steps are clearer for development, and create predictability when troubleshooting smoke test results during development.
2. Separation of concerns usually also means separation of library uses, meaning tests and needs like mocking become more predictable for each unit of separation
3. Reduction of the need to find/copy/paste an existing element, re-ensuring its accessibility, etc.

UX:

1. The code running their UI would be the same for every form, creating consistent expectations of behavior
2. More testable units provides security against users ever running into form-related bugs
3. New forms can be stood up expediently, leading to satisfied users

What are the foreseeable cons of your desired approach?

1. Unifying the code from a disparate pattern creates a heavy validation burden on Padma's part, and a bug may potentially slip through.
2. This pattern removes the verbose pattern we've been following, that is notably a common pattern for junior/mid engineers new to React. This creates more of a reliance on our documentation to provide clear information about the systems in place, which may be a norm that'd take some time to adopt.