@digigov/form 0.10.7 → 0.10.8

package/src/MultiplicityField/MultiplicityField.mdx

@@ -1,580 +0,0 @@
----
-id: ask-users-recursive
-title: Ask users for recursive data
----
-
-import LeadText from "@site/src/components/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
-
-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.
-
-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.
-
-## 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.
-
-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="vehicles"
-      name="vehicles"
-      label={{ primary: "Vehicles" }}
-      type="array"
-      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
-
-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' },
-        },
-        {
-          key: 'make',
-          type: 'string',
-          required: true,
-          label: {
-            primary: 'Make',
-          },
-        },
-        {
-          key: 'model',
-          type: 'string',
-          required: true,
-          label: {
-            primary: 'Model',
-          },
-        },
-      ],
-    },
-  },
-}
-```
-
-## 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“.',
-            },
-            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“.',
-            },
-            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>
-}
-```