@digigov/form 0.9.0 → 0.10.0

package/MultiplicityField/MultiplicityField.mdx

@@ -1,148 +1,580 @@
 ---
-id: MultiplicityField
-title: Multiplicity Field
-sidebar_label: Recursively ask user data
+id: ask-users-recursive
+title: Ask users for recursive data
 ---
 
 import LeadText from "@site/src/components/LeadText";
 
-<LeadText>Multiplicity field enables users add instances of a particular schema for an
-arbitrary amount of times until they are done. It can be used with a fixed
-length of instances, or a minimum and maximum length.</LeadText>
+<LeadText>Multiplicity & FieldArray fields allow users to input data described
+by a particular schema for an arbitrary number of times until they are
+done. It can be used to input a fixed, a minimum, and a maximum
+length of instances.</LeadText>
 
 ## What we are trying to achieve
 
-This field was developed as an accessible and guided way to fill arrays with
-objects described by a schema. For example, we can define the schema for a usual form by describing the fields
-it will render.
+First off, a bit of history. This field was developed to meet the needs of several
+GOV.GR services. They needed an easy way to add multiple objects in an array of
+data while they could still keep the usability of a web form, submitting data and
+validating the fields as well. As part of the prototype phase, an initial
+implementation was designed and used in Dilosi for several document templates.
+It used a single button to add new items in the array and opened a modal,
+blocking the rest of the user interface and prompting users to input data.
+During this process, the `FieldArray` component was conceived.
 
-These fields may describe an entity and its properties and it can be reused
-multiple times to generate data objects following this schema.
+Meanwhile, Digigov SDK got these requirements and started working on a more
+versatile version of this feature. The new field was developed from scratch as
+an accessible and guided way to fill arrays with objects. Also, we wanted to
+provide an easy-to-use component for developers. The input fields that will
+collect data for each item in the array are described by a JSON schema, then
+provided to `@digigov/form` to manage internally. These fields describe
+properties for a data entity like a citizen and their personal details, and it
+can be reused internally multiple times by `@digigov/form` to generate data
+objects based on this schema.
 
-```js
-const fields = [
-  {
-    key: "fullname",
-    name: "fullname",
-    type: "string",
-    required: true
-  },
-  {
-    key: "afm",
-    name: "afm",
-    type: "afm",
-    required: true
-  },
-];
-```
+## Accessibility & usability
+
+We aim to have semantically correct and valid forms, and as a result we cannot
+mix form-related HTML elements, like `form`, `input`, `label` with generic ones,
+eg. `div`, cards or other custom components. For example, if we try to add a
+paragraph element inside a form, React will throw warnings in our console.
+Instead of creating complex interfaces that try to do too much too fast, Digigov
+Form recommends using forms in their original way, filling and validating
+inputs, then submitting the form as a whole.
 
-We aim to have semantically correct and valid forms. What this means is that we
-cannot mix form-related HTML elements (eg. form, input, label) with generic ones
-(eg. div, cards, custom components). React will start throwing warnings left and
-right if we try to add a paragraph element inside a form.
-
-Apart from this, Digigov Form recommends using forms in their original way of
-filling and validating inputs, then submitting the form as a whole. The process
-repeats if validation fails or proceeds if validation is successful. In any
-case, it is imperative to provide meaningful information to the users on
-how they proceed to fix the validation errors.
-
-Last but not least, we should make our interfaces entirely accessible to screen
-readers and other accessibilty tools and this requirement adds another dimension
-to this problem. Forms and fields should read like a well-written piece of text
-and make sense to the users. Thus we should avoid the use of magic UX solutions
-that require users to have some well-developed digital skills and most of the
-time are used for expert users. 
-
-Users should fill in data as this schema dictates, and every time they add
-something we should ask them if they want to continue adding or escape the loop.
-We can also add some limitations so we can ask for an array with specific
-cardinality. In this way we can validate each form state regardless of whether a
-user is in the process of data input or reviewing what they've added. In any
-case, the form should guide users through steps and validation errors, and avoid
-giving too much freedom in actions that could lead to estranged users losing
-their way out of the maze.
-
-But how can we code this feature as part of a Digigov form? 
-
-## Enter the Multiplicity field
-
-To deal with this problem, we have decided to create a composite field that uses
-externally defined object schema alongside some internal helpers. This field in
-fact is considered as a single key-value pair by the form. The only difference is that
-the value will be of type `Array` instead of any other primitive used for a
-field type.
-
-The component internally uses the
+Adding another dimension to this problem, we should make sure our interfaces
+are entirely accessible to screen readers and other accessibility tools. This is
+the reason we decided to design the flow to be as guided and recoverable as
+possible. Forms and fields should read like well-written pieces of text and
+make sense to the users. While validation fails, the system provides users with
+meaningful error messages and instructs them on how to fix the validation errors to
+ proceed. Once the validation is successful, the flow can proceed with
+ submmitting data. In any case, it is imperative to provide meaningful
+information to the users at each step. Thus, we should avoid the use of 🌈
+“magic“ ✨ UX solutions that presume users have developed digital skills and
+most of the time are used for expert use cases. 
+
+Initially, we used an add button that users clicked to explicitly create with
+their action a new item in the array, but in this way we cannot programmatically
+ensure that users still have stuff to enter to the system. What we decided to do
+is to turn this state check into a direct question that will be a part of the final
+form. We created a question that will make sure that users always provide the
+form with their intention.
+
+Both FieldArray and MultiplicityField will result in the same data output when
+users submit the form, which is an `array` that contains `objects` described by
+the `extra.fields` key. The component internally uses the
 [useFieldArray](https://www.react-hook-form.com/api/usefieldarray) hook from
 react-hook-form.
 
+:::caution
+
+We strongly recommend that services concerning citizens use `Multiplicity`, instead
+of `FieldArray`.
+
+Please be careful when and how you use a `FieldArray` component. Many users are not
+familiar with modern user interface design practices, and it is likely they will
+be confused. If you choose to use it, please provide meaningful hints in the
+`extra.label.object.nothing_added` and `extra.label.object.title_added` keys.
+
+:::
+
+
+Users should fill in data as this schema dictates, and every time
+they add something, we should ask them if they want to continue adding or escape
+the loop. We could also add some limits to the number of items users create,
+resulting in an array with specific cardinality. By doing so, we can validate the
+form state at any time, regardless of whether a user is in the process of data input
+or reviewing what they've added. In any case, the form should guide users
+through steps and validation errors, and avoid giving too much freedom of
+action that could lead to estranged users losing the intended path or their
+focus.
+
+Those are a lot of things to keep in mind, but luckily we've got you covered. How
+can we code this feature as part of a Digigov form, you ask? 
+
+## Introducing the Multiplicity field
+
+To deal with these features, we have decided to create a composite field that uses
+custom object schema for the input fields alongside some internal helpers to
+make sure that the flow is usable from beginning to end. In reality, this
+field is in fact considered as a normal single key-value pair by the
+`@digigov/form`, same as every other input type. The only difference is that the
+type of the value will be an `Array` instead of any other primitive used for a
+field type, like `string`, `number`, etc. Inside the array, each one of the
+indexes will be an object with nested field values.
+
+This field is the most complex component we currently offer, and it uses the
+[useFieldArray](https://www.react-hook-form.com/api/usefieldarray) hook from
+react-hook-form under the hood. First, let's take a look at what it looks like, and then we can
+break down its functionality and how you can use it. 
+
 ```jsx live
 import React from 'react';
 import Form, { Field } from '@digigov/form';
+import Button from '@digigov/ui/core/Button';
 
 export default function SimpleForm() {
   return <Form>
     <Field
-      key="children"
-      label={{ primary: "Children" }}
+      key="vehicles"
+      name="vehicles"
+      label={{ primary: "Vehicles" }}
       type="array"
-      multiplicity={true}
       extra={{
+        border: true,
+        label: {
+          object: {
+            title: 'Vehicle',
+            title_added: 'The vehicles you have already added',
+            add: 'Add',
+            delete: 'Remove',
+          },
+          question: {
+            title: 'Do you want to add more vehicles?',
+            objectLabel: {
+              primary: 'Add one more of your vehicles',
+              secondary: 'Fill in the details below and then click “Add“.',
+            },
+            yes: 'Yes',
+            no: 'No',
+          },
+        },
+        of: {
+          type: 'object',
+          label: {
+            primary: 'Vehicle details',
+            secondary: 'See and change the details of a vehicle',
+          },
+          extra: {
+            fields: [
+              {
+                key: 'registration_date',
+                type: 'date',
+                required: true,
+                label: { primary: 'Registration date' },
+              },
+              {
+                key: 'make',
+                type: 'string',
+                required: true,
+                label: {
+                  primary: 'Make',
+                },
+              },
+              {
+                key: 'model',
+                type: 'string',
+                required: true,
+                label: {
+                  primary: 'Model',
+                },
+              },
+            ],
+          },
+        },
+      }}
+      required
+    />
+    <Button type="submit">Submit</Button>
+  </Form>
+}
+```
+
+### How to use it
 
-      label: {
-        object: {
-          title: 'Συνυπογράφοντας',
-          title_added: 'Οι συνυπογράφοντες που έχετε προσθέσει',
-          add: 'Προσθήκη',
-          delete: 'Αφαίρεση συνυπογράφοντος',
+Before we begin, we should setup an empty form. We are going to need a main `Form`
+and a submit `Button` that will trigger the `onSubmit` events in our React form.
+
+```jsx
+import React from 'react';
+import Form from '@digigov/form';
+import Button from '@digigov/ui/core/Button';
+
+export default function MultiplicityForm() {
+  return <Form>
+    {/* this is where all fields will eventually be rendered */}
+    <Button type="submit">Submit</Button>
+  </Form>
+}
+```
+
+As you may have already assumed, this boilerplate code will not get us very far.
+We need an actual `Field` component that will be of `type: 'array'` since we
+need a value that contains multiple instances of a single schema. Given that we
+are asking users for information about their vehicles, we can also fill in the `key`,
+`label.primary`, as well as the `type` and `required`
+props.
+
+```jsx
+<Field
+  key="vehicles"
+  name="vehicles"
+  label={{ primary: "Vehicles" }}
+  type="array"
+  required
+/>
+```
+
+Although this code may seem enough at first glance, it will soon become clear
+that Multiplicity packs a lot of functionality. It needs context in the form of
+natural language, Greek, English, or any other language dictated by the user needs
+in order to carry meaning to the end users. 
+
+It also needs the schema of the form fields to be filled for each iteration. To
+do so, inside the `extra` key we can add an `of` key. This `of` key will contain
+a key named `label` and a key name `type`, signifying the label text and the type of the
+inner form, respectively. 
+
+Inside the `of` key you can add an `extra` key that will then contain a `fields`
+key describing the field props for all inputs needed.
+
+```js
+// this will be used as value for the `extra` prop 
+{
+  of: {
+    type: 'object',
+    label: {
+      primary: 'Vehicle details',
+      secondary: 'See and change the details of a vehicle',
+    },
+    extra: {
+      fields: [
+        {
+          key: 'registration_date',
+          type: 'date',
+          required: true,
+          label: { primary: 'Registration date' },
         },
-        question: {
-          title: 'Do you want to add any additional children?',
-          objectLabel: {
-            primary: 'Προσθήκη νέου συνυπογράφοντα',
-            secondary: 'Συμπληρώστε τα στοιχεία και μετά πατήστε «Προσθήκη»',
-          },
-          yes: 'Yes',
-          no: 'No',
+        {
+          key: 'make',
+          type: 'string',
+          required: true,
+          label: {
+            primary: 'Make',
+          },
         },
-      },
-      of: {
-        type: 'object',
-        label: {
-          primary: 'Στοιχεία συνυπογράφοντα',
-          secondary: 'Δείτε και αλλάξτε τα στοιχεία του συνυπογράφοντα',
+        {
+          key: 'model',
+          type: 'string',
+          required: true,
+          label: {
+            primary: 'Model',
+          },
         },
-        extra: {
-          fields: [
-            {
-              key: 'afm',
-              type: 'afm',
-              required: true,
-              label: { primary: 'ΑΦΜ' },
+      ],
+    },
+  },
+}
+```
+
+## Introducing the FieldArray field
+ 
+As a simpler alternative to Multiplicity, we also offer the original
+implementation called `FieldArray` which may be used in dashboards or other apps
+used by expert users or administrators of any kind. FieldArray skips all the
+extra safety features and protections of the Multiplicity and offers more
+flexibility for the end user.
+
+### How to use it
+
+We tried to maintain the differences in the API between the two implementations
+as little as possible. The only thing that is required for you to do to use the
+FieldArray instead of the Multiplicity, is to explicitly disable the
+multiplicity functionality, by using the `multiplicity={false}` prop.
+
+As a result, if you learn how to use one, you can easily use the other, and
+naturally, you can also change their behaviour by changing a single prop in your
+React code.
+
+```jsx
+<Field
+  key="vehicles"
+  name="vehicles"
+  label={{ primary: "Vehicles" }}
+  type="array"
+  // highlight-next-line
+  multiplicity={false}
+  required
+/>
+```
+
+The end result looks very different from Multiplicity at first glance, but you
+can achieve the same results with both of them. 
+
+```jsx live
+import React from 'react';
+import Form, { Field } from '@digigov/form';
+import Button from '@digigov/ui/core/Button';
+
+export default function SimpleForm() {
+  return <Form>
+    <Field
+      key="vehicles"
+      name="vehicles"
+      label={{ primary: "Vehicles" }}
+      type="array"
+      multiplicity={false}
+      extra={{
+        border: true,
+        label: {
+          object: {
+            title: 'Vehicle',
+            title_added: 'The vehicles you have already added',
+            nothing_added: 'You have not added any vehicles yet.',
+            add: 'Add vehicle',
+            delete: 'Remove',
+          },
+          question: {
+            title: 'Do you want to add more vehicles?',
+            objectLabel: {
+              primary: 'Add one more of your vehicles',
+              secondary: 'Fill in the details below and then click “Add“.',
             },
-            {
-              key: 'firstName',
-              required: true,
-              type: 'string',
-              label: {
-                primary: 'Όνομα',
+            yes: 'Yes',
+            no: 'No',
+          },
+        },
+        of: {
+          type: 'object',
+          label: {
+            primary: 'Vehicle details',
+            secondary: 'See and change the details of a vehicle',
+          },
+          extra: {
+            fields: [
+              {
+                key: 'registration_date',
+                type: 'date',
+                required: true,
+                label: { primary: 'Registration date' },
+              },
+              {
+                key: 'make',
+                type: 'string',
+                required: true,
+                label: {
+                  primary: 'Make',
+                },
+              },
+              {
+                key: 'model',
+                type: 'string',
+                required: true,
+                label: {
+                  primary: 'Model',
+                },
               },
+            ],
+          },
+        },
+      }}
+      required
+    />
+    <Button type="submit">Submit</Button>
+  </Form>
+}
+```
+
+## Validating form data
+
+Luckily, if you want to validate the values of the nested fields, for instance,
+the first name of a vehicle, you don't have to perform any further actions. The fields'
+validation will work right out of the box, same as any other form.
+
+There is another use case that is available as part of the
+MultiplicityField. Given that the value of this field type is an array, we
+should expect to need some length validation sooner than later.
+
+### Exact length
+
+You can easily validate the exact length of the items added to the multipliticy
+array, simply by using the `extra.length` prop.
+
+```jsx
+<Field
+  extra={{
+    length: 2,
+    of: { ... },
+    label: { ... },
+  }}
+/>
+```
+
+The example below will validate this and show all the error messages necessary
+to make sure that the users understand what is going wrong with the process.
+
+```jsx live
+import React from 'react';
+import Form, { Field } from '@digigov/form';
+import Button from '@digigov/ui/core/Button';
+
+export default function SimpleForm() {
+  return <Form>
+    <Field
+      key="vehicles"
+      name="vehicles"
+      label={{ primary: "Vehicles" }}
+      type="array"
+      multiplicity={true}
+      extra={{
+        border: true,
+        length: 3,
+        label: {
+          object: {
+            title: 'Vehicle',
+            title_added: 'The vehicles you have already added',
+            add: 'Add',
+            delete: 'Remove',
+          },
+          question: {
+            title: 'Do you want to add more vehicles?',
+            objectLabel: {
+              primary: 'Add one more of your vehicles',
+              secondary: 'Fill in the details below and then click “Add“.',
             },
-            {
-              key: 'lastName',
-              required: true,
-              type: 'string',
-              label: {
-                primary: 'Επώνυμο',
+            yes: 'Yes',
+            no: 'No',
+          },
+        },
+        of: {
+          type: 'object',
+          label: {
+            primary: 'Vehicle details',
+            secondary: 'See and change the details of a vehicle',
+          },
+          extra: {
+            fields: [
+              {
+                key: 'registration_date',
+                type: 'date',
+                required: true,
+                label: { primary: 'Registration date' },
+              },
+              {
+                key: 'make',
+                type: 'string',
+                required: true,
+                label: {
+                  primary: 'Make',
+                },
               },
+              {
+                key: 'model',
+                type: 'string',
+                required: true,
+                label: {
+                  primary: 'Model',
+                },
+              },
+            ],
+          },
+        },
+      }}
+      required
+    />
+    <Button type="submit">Submit</Button>
+  </Form>
+}
+```
+
+### Min or max length
+
+You can also use the min or max length validation to define the cardinality
+range for the array. You can use only the `min` key to add a minimum length of
+items or only the `max` key to limit them.
+
+:::caution
+
+Do not mix and match the exact `length` validation with the `min` or `max`.
+
+:::
+
+```jsx
+<Field
+  extra={{
+    min: 2,
+    max: 5,
+    of: { ... },
+    label: { ... },
+  }}
+/>
+```
+
+The example below will validate this and show all the error messages necessary
+to make sure that the users understand what is going wrong with the process.
+
+```jsx live
+import React from 'react';
+import Form, { Field } from '@digigov/form';
+import Button from '@digigov/ui/core/Button';
+
+export default function SimpleForm() {
+  return <Form>
+    <Field
+      key="vehicles"
+      name="vehicles"
+      label={{ primary: "Vehicles" }}
+      type="array"
+      multiplicity={true}
+      extra={{
+        border: true,
+        min: 2,
+        max: 5,
+        label: {
+          object: {
+            title: 'Vehicle',
+            title_added: 'The vehicles you have already added',
+            nothing_added: 'You have not added any vehicles yet.',
+            add: 'Add',
+            delete: 'Remove',
+          },
+          question: {
+            title: 'Do you want to add more vehicles?',
+            objectLabel: {
+              primary: 'Add one more of your vehicles',
+              secondary: 'Fill in the details below and then click “Add“.',
             },
-          ],
+            yes: 'Yes',
+            no: 'No',
+          },
+        },
+        of: {
+          type: 'object',
+          label: {
+            primary: 'Vehicle details',
+            secondary: 'See and change the details of a vehicle',
+          },
+          extra: {
+            fields: [
+              {
+                key: 'registration_date',
+                type: 'date',
+                required: true,
+                label: { primary: 'Registration date' },
+              },
+              {
+                key: 'make',
+                type: 'string',
+                required: true,
+                label: {
+                  primary: 'Make',
+                },
+              },
+              {
+                key: 'model',
+                type: 'string',
+                required: true,
+                label: {
+                  primary: 'Model',
+                },
+              },
+            ],
+          },
         },
-      },
       }}
       required
     />
+    <Button type="submit">Submit</Button>
   </Form>
 }
-```
+```