@digigov/form 0.8.4 → 0.8.5-alpha

package/es/MultiplicityField/MultiplicityField.mdx

@@ -0,0 +1,148 @@
+---
+id: MultiplicityField
+title: Multiplicity Field
+sidebar_label: Recursively ask user 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>
+
+## 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.
+
+These fields may describe an entity and its properties and it can be reused
+multiple times to generate data objects following this schema.
+
+```js
+const fields = [
+  {
+    key: "fullname",
+    name: "fullname",
+    type: "string",
+    required: true
+  },
+  {
+    key: "afm",
+    name: "afm",
+    type: "afm",
+    required: true
+  },
+];
+```
+
+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
+[useFieldArray](https://www.react-hook-form.com/api/usefieldarray) hook from
+react-hook-form.
+
+```jsx live
+import React from 'react';
+import Form, { Field } from '@digigov/form';
+
+export default function SimpleForm() {
+  return <Form>
+    <Field
+      key="children"
+      label={{ primary: "Children" }}
+      type="array"
+      multiplicity={true}
+      extra={{
+
+      label: {
+        object: {
+          title: 'Συνυπογράφοντας',
+          title_added: 'Οι συνυπογράφοντες που έχετε προσθέσει',
+          add: 'Προσθήκη',
+          delete: 'Αφαίρεση συνυπογράφοντος',
+        },
+        question: {
+          title: 'Do you want to add any additional children?',
+          objectLabel: {
+            primary: 'Προσθήκη νέου συνυπογράφοντα',
+            secondary: 'Συμπληρώστε τα στοιχεία και μετά πατήστε «Προσθήκη»',
+          },
+          yes: 'Yes',
+          no: 'No',
+        },
+      },
+      of: {
+        type: 'object',
+        label: {
+          primary: 'Στοιχεία συνυπογράφοντα',
+          secondary: 'Δείτε και αλλάξτε τα στοιχεία του συνυπογράφοντα',
+        },
+        extra: {
+          fields: [
+            {
+              key: 'afm',
+              type: 'afm',
+              required: true,
+              label: { primary: 'ΑΦΜ' },
+            },
+            {
+              key: 'firstName',
+              required: true,
+              type: 'string',
+              label: {
+                primary: 'Όνομα',
+              },
+            },
+            {
+              key: 'lastName',
+              required: true,
+              type: 'string',
+              label: {
+                primary: 'Επώνυμο',
+              },
+            },
+          ],
+        },
+      },
+      }}
+      required
+    />
+  </Form>
+}
+```

package/es/MultiplicityField/__stories__/Default.js

@@ -1,5 +1,5 @@
 import _extends from "@babel/runtime/helpers/extends";
-import React, { Suspense } from 'react';
+import React from 'react';
 import FormBuilder, { Field } from '@digigov/form';
 import { Button } from '@digigov/ui/core';
 var fields = [{
@@ -83,9 +83,7 @@ var _ref = /*#__PURE__*/React.createElement(Button, {
 }, "\u03A3\u03C5\u03BD\u03AD\u03C7\u03B5\u03B9\u03B1");
 
 export var Default = function Default() {
-  return /*#__PURE__*/React.createElement(Suspense, {
-    fallback: "loading"
-  }, /*#__PURE__*/React.createElement(FormBuilder, {
+  return /*#__PURE__*/React.createElement(FormBuilder, {
     onSubmit: function onSubmit(data) {
       debugger;
       console.log(data);
@@ -96,5 +94,5 @@ export var Default = function Default() {
     name: "multiplicity"
   }, fields[1])), /*#__PURE__*/React.createElement(Field, _extends({
     name: "phonenumber"
-  }, fields[2])), _ref));
+  }, fields[2])), _ref);
 };

package/es/MultiplicityField/__stories__/WithExactLength.js

@@ -1,5 +1,5 @@
 import _extends from "@babel/runtime/helpers/extends";
-import React, { Suspense } from 'react';
+import React from 'react';
 import FormBuilder, { Field } from '@digigov/form';
 import { Button } from '@digigov/ui/core';
 var fields = [{
@@ -78,9 +78,7 @@ var _ref = /*#__PURE__*/React.createElement(Button, {
 }, "\u03A3\u03C5\u03BD\u03AD\u03C7\u03B5\u03B9\u03B1");
 
 export var WithExactLength = function WithExactLength() {
-  return /*#__PURE__*/React.createElement(Suspense, {
-    fallback: "loading"
-  }, /*#__PURE__*/React.createElement(FormBuilder, {
+  return /*#__PURE__*/React.createElement(FormBuilder, {
     onSubmit: function onSubmit(data) {
       debugger;
       console.log(data);
@@ -91,5 +89,5 @@ export var WithExactLength = function WithExactLength() {
     name: "multiplicity"
   }, fields[1])), /*#__PURE__*/React.createElement(Field, _extends({
     name: "phonenumber"
-  }, fields[2])), _ref));
+  }, fields[2])), _ref);
 };

package/es/MultiplicityField/__stories__/WithMaxLength.js

@@ -1,5 +1,5 @@
 import _extends from "@babel/runtime/helpers/extends";
-import React, { Suspense } from 'react';
+import React from 'react';
 import FormBuilder, { Field } from '@digigov/form';
 import { Button } from '@digigov/ui/core';
 var fields = [{
@@ -81,9 +81,7 @@ var _ref = /*#__PURE__*/React.createElement(Button, {
 }, "\u03A3\u03C5\u03BD\u03AD\u03C7\u03B5\u03B9\u03B1");
 
 export var WithMaxLength = function WithMaxLength() {
-  return /*#__PURE__*/React.createElement(Suspense, {
-    fallback: "loading"
-  }, /*#__PURE__*/React.createElement(FormBuilder, {
+  return /*#__PURE__*/React.createElement(FormBuilder, {
     onSubmit: function onSubmit(data) {
       debugger;
       console.log(data);
@@ -94,5 +92,5 @@ export var WithMaxLength = function WithMaxLength() {
     name: "multiplicity"
   }, fields[1])), /*#__PURE__*/React.createElement(Field, _extends({
     name: "phonenumber"
-  }, fields[2])), _ref));
+  }, fields[2])), _ref);
 };

package/es/MultiplicityField/__stories__/WithMinAndMaxLength.js

@@ -1,5 +1,5 @@
 import _extends from "@babel/runtime/helpers/extends";
-import React, { Suspense } from 'react';
+import React from 'react';
 import FormBuilder, { Field } from '@digigov/form';
 import { Button } from '@digigov/ui/core';
 var fields = [{
@@ -82,9 +82,7 @@ var _ref = /*#__PURE__*/React.createElement(Button, {
 }, "\u03A3\u03C5\u03BD\u03AD\u03C7\u03B5\u03B9\u03B1");
 
 export var WithMinAndMaxLength = function WithMinAndMaxLength() {
-  return /*#__PURE__*/React.createElement(Suspense, {
-    fallback: "loading"
-  }, /*#__PURE__*/React.createElement(FormBuilder, {
+  return /*#__PURE__*/React.createElement(FormBuilder, {
     onSubmit: function onSubmit(data) {
       debugger;
       console.log(data);
@@ -95,5 +93,5 @@ export var WithMinAndMaxLength = function WithMinAndMaxLength() {
     name: "multiplicity"
   }, fields[1])), /*#__PURE__*/React.createElement(Field, _extends({
     name: "phonenumber"
-  }, fields[2])), _ref));
+  }, fields[2])), _ref);
 };

package/es/MultiplicityField/__stories__/WithMinLength.js

@@ -1,5 +1,5 @@
 import _extends from "@babel/runtime/helpers/extends";
-import React, { Suspense } from 'react';
+import React from 'react';
 import FormBuilder, { Field } from '@digigov/form';
 import { Button } from '@digigov/ui/core';
 var fields = [{
@@ -81,9 +81,7 @@ var _ref = /*#__PURE__*/React.createElement(Button, {
 }, "\u03A3\u03C5\u03BD\u03AD\u03C7\u03B5\u03B9\u03B1");
 
 export var WithMinLength = function WithMinLength() {
-  return /*#__PURE__*/React.createElement(Suspense, {
-    fallback: "loading"
-  }, /*#__PURE__*/React.createElement(FormBuilder, {
+  return /*#__PURE__*/React.createElement(FormBuilder, {
     onSubmit: function onSubmit(data) {
       debugger;
       console.log(data);
@@ -94,5 +92,5 @@ export var WithMinLength = function WithMinLength() {
     name: "multiplicity"
   }, fields[1])), /*#__PURE__*/React.createElement(Field, _extends({
     name: "phonenumber"
-  }, fields[2])), _ref));
+  }, fields[2])), _ref);
 };

package/es/Questions/Step/StepArrayReview.js

@@ -2,7 +2,7 @@ import React, { useContext } from 'react';
 import { QuestionsContext } from '@digigov/form/Questions/QuestionsContext';
 import PageTitle, { PageTitleHeading } from '@digigov/ui/app/PageTitle';
 import Button from '@digigov/ui/core/Button';
-import { FormBuilder } from '@digigov/form/FormBuilder';
+import FormBuilder from '@digigov/form/FormBuilder';
 import { Field } from '@digigov/form/Field';
 import { Fieldset } from '@digigov/form/Fieldset';
 import Label from '@digigov/form/inputs/Label';