@digigov/form 0.13.2 → 1.0.0-079f34f3d

package/MultiplicityField/MultiplicityField.mdx

@@ -3,12 +3,13 @@ id: ask-users-recursive
 title: Ask users for recursive data
 ---
 
-import LeadText from "@site/src/components/LeadText";
+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>
+<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
 
@@ -47,11 +48,11 @@ 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
+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. 
+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
@@ -78,7 +79,6 @@ be confused. If you choose to use it, please provide meaningful hints in the
 
 :::
 
-
 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,
@@ -90,7 +90,7 @@ 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? 
+can we code this feature as part of a Digigov form, you ask?
 
 ## Introducing the Multiplicity field
 
@@ -106,77 +106,79 @@ 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. 
+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';
+import Button from '@digigov/ui/form/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',
+  return (
+    <Form>
+      <Field
+        key="vehicles"
+        name="vehicles"
+        label={{ primary: 'Vehicles' }}
+        type="array"
+        extra={{
+          border: true,
           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' },
+            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: 'make',
-                type: 'string',
-                required: true,
-                label: {
-                  primary: 'Make',
+              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: 'model',
-                type: 'string',
-                required: true,
-                label: {
-                  primary: 'Model',
+                {
+                  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>
+        }}
+        required
+      />
+      <Button type="submit">Submit</Button>
+    </Form>
+  );
 }
 ```
 
@@ -188,13 +190,15 @@ 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';
+import Button from '@digigov/ui/form/Button';
 
 export default function MultiplicityForm() {
-  return <Form>
-    {/* this is where all fields will eventually be rendered */}
-    <Button type="submit">Submit</Button>
-  </Form>
+  return (
+    <Form>
+      {/* this is where all fields will eventually be rendered */}
+      <Button type="submit">Submit</Button>
+    </Form>
+  );
 }
 ```
 
@@ -209,7 +213,7 @@ props.
 <Field
   key="vehicles"
   name="vehicles"
-  label={{ primary: "Vehicles" }}
+  label={{ primary: 'Vehicles' }}
   type="array"
   required
 />
@@ -218,18 +222,18 @@ props.
 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. 
+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. 
+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 
+// this will be used as value for the `extra` prop
 {
   of: {
     type: 'object',
@@ -268,7 +272,7 @@ key describing the field props for all inputs needed.
 ```
 
 ## 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
@@ -290,7 +294,7 @@ React code.
 <Field
   key="vehicles"
   name="vehicles"
-  label={{ primary: "Vehicles" }}
+  label={{ primary: 'Vehicles' }}
   type="array"
   // highlight-next-line
   multiplicity={false}
@@ -299,79 +303,81 @@ React code.
 ```
 
 The end result looks very different from Multiplicity at first glance, but you
-can achieve the same results with both of them. 
+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';
+import Button from '@digigov/ui/form/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',
+  return (
+    <Form>
+      <Field
+        key="vehicles"
+        name="vehicles"
+        label={{ primary: 'Vehicles' }}
+        type="array"
+        multiplicity={false}
+        extra={{
+          border: true,
           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' },
+            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: 'make',
-                type: 'string',
-                required: true,
-                label: {
-                  primary: 'Make',
+              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: 'model',
-                type: 'string',
-                required: true,
-                label: {
-                  primary: 'Model',
+                {
+                  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>
+        }}
+        required
+      />
+      <Button type="submit">Submit</Button>
+    </Form>
+  );
 }
 ```
 
@@ -406,74 +412,76 @@ 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';
+import Button from '@digigov/ui/form/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',
+  return (
+    <Form>
+      <Field
+        key="vehicles"
+        name="vehicles"
+        label={{ primary: 'Vehicles' }}
+        type="array"
+        multiplicity={true}
+        extra={{
+          border: true,
+          length: 3,
           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' },
+            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: 'make',
-                type: 'string',
-                required: true,
-                label: {
-                  primary: 'Make',
+              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: 'model',
-                type: 'string',
-                required: true,
-                label: {
-                  primary: 'Model',
+                {
+                  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>
+        }}
+        required
+      />
+      <Button type="submit">Submit</Button>
+    </Form>
+  );
 }
 ```
 
@@ -506,75 +514,77 @@ 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';
+import Button from '@digigov/ui/form/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',
+  return (
+    <Form>
+      <Field
+        key="vehicles"
+        name="vehicles"
+        label={{ primary: 'Vehicles' }}
+        type="array"
+        multiplicity={true}
+        extra={{
+          border: true,
+          min: 2,
+          max: 5,
           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' },
+            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“.',
               },
-              {
-                key: 'make',
-                type: 'string',
-                required: true,
-                label: {
-                  primary: 'Make',
+              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: 'model',
-                type: 'string',
-                required: true,
-                label: {
-                  primary: 'Model',
+                {
+                  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>
+        }}
+        required
+      />
+      <Button type="submit">Submit</Button>
+    </Form>
+  );
 }
 ```