@digigov/form 0.8.4 → 0.8.5-alpha

package/esm/FormBuilder/FormBuilder.mdx

@@ -0,0 +1,271 @@
+---
+id: FormBuilder
+title: FormBuilder
+sidebar_label: FormBuilder
+---
+
+`FormBuilder` is a React component that provides an easy way to efficiently create reusable form page. Forms are a flexible mechanism for collecting user input because there are suitable widgets for entering many different types of data, including text boxes, checkboxes, radio buttons, dropdowns and so on  for submission to a server. Actually when we use `stepForm` for building step-forms all we do is to render `FormBuilder` component.
+
+`stepForm` component: 
+
+<Story packageName="@digigov/form" component="FormBuilder" story="Default.tsx" />
+
+### Importing and using FormBuilder Component
+
+To import `FormBuilder` component simply import it from `'@digigov/form`.
+
+```javascript
+
+import {FormBuilder} from '@digigov/form';
+
+```
+Now you can use the current component inisde of your component
+
+
+```javascript
+import BasicLayout, {
+  Top,
+  Content,
+  Main,
+  Bottom,
+} from '@digigov/ui/layouts/Basic';
+import {FormBuilder} from '@digigov/form';
+
+export default function MyComponent({ props }) {
+
+  return (
+    <BasicLayout>
+      .
+      .
+      <Content>
+        <Main>
+          .
+          .
+          <FormBuilder></FormBuilder>
+          .
+          .
+        </Main>
+      </Content>
+      <Bottom>
+        <GovGRFooter />
+      </Bottom>
+    </BasicLayout>
+  );
+}
+}
+```
+
+### Props
+
+`FormBuilder` component accepts several arguments as input props.
+
+| Name          |      Type     |  Default      | Description |
+| ------------- | :-----------: | :-----------: | :-----------: | 
+| children      | node |        |      allow you to pass components as data.  |
+| steps      | array |        |      an array which includes each step-form format data |
+| name      | string |        |      the name of the step.  |
+| title      | string |        |     the title from each step   |
+| fields      | array |        |     an array of object fields which they describe each field for each step-form |
+| key      | string |        |     the key value of the input field |
+| label      | object |        |    an object prop which describes the label primary and the secondary name of the field   |
+| primary      | string |        |    the name of te field |
+| required      | boolean |   false     |   describes the validation of the field  |
+| submitButton      | boolean |     false   |  if true, it creates a button to continue to the next step   |
+| type      | string |        |    describes the format of each field, e.x  `type:'string'` is a simple input format field |
+
+
+
+### Field types
+
+Below are demostrated some examples for each type of field
+
+
+### FormBuilder implementation
+
+The examples above are implemented by using the code below
+
+```javascript
+
+import React, { useState } from 'react';
+import BasicLayout, {
+  Top,
+  Content,
+  Main,
+  Bottom,
+} from '@digigov/ui/layouts/Basic';
+import Header, { HeaderTitle } from '@digigov/ui/app/Header';
+import GovGRLogo from '@digigov/ui/govgr/Logo';
+import GovGRFooter from '@digigov/ui/govgr/Footer';
+import Button from '@digigov/ui/core/Button';
+import PageTitle, {
+  PageTitleSection,
+  PageTitleCaption,
+  PageTitleHeading,
+} from '@digigov/ui/app/PageTitle';
+import BackButton from '@digigov/ui/core/Button/BackButton';
+import FormBuilder, { Fieldset, FieldsetLabel, Field } from '@digigov/form';
+import { useTranslation } from '@digigov/ui/app';
+
+const FIELDS = [
+  {
+    key: 'phone',
+    label: {
+      primary: 'Mobile phone',
+      secondary: 'A valid mobile number, eg. +306988848888',
+    },
+    required: true,
+    type: 'mobile_phone',
+  },
+  {
+    key: 'choice_single',
+    label: { primary: 'Is this true or not' },
+    type: 'choice:single',
+    required: true,
+    extra: {
+      options: [
+        {
+          label: { primary: 'Yes' },
+          value: 'yes',
+        },
+        {
+          label: { primary: 'No', secondary: 'Explanation about no option' },
+          value: 'no',
+        },
+      ],
+    },
+  },
+  {
+    key: 'choice_single_notitle',
+    type: 'choice:single',
+    extra: {
+      options: [
+        {
+          label: { primary: 'One' },
+          value: '1',
+        },
+        {
+          label: { primary: 'Two' },
+          value: '2',
+        },
+      ],
+    },
+  },
+  {
+    key: 'choice_multiple',
+    label: 'Select from below',
+    type: 'choice:multiple',
+    extra: {
+      options: [
+        {
+          label: { primary: 'Choice 1', secondary: 'Choice 1 explanation' },
+          value: 'choice_1',
+        },
+        {
+          label: { primary: 'Choice 2' },
+          value: 'choice_2',
+        },
+      ],
+    },
+  },
+  {
+    key: 'choice_single_select',
+    label: 'Select from below',
+    type: 'choice:single',
+    extra: {
+      options: [
+        {
+          label: { primary: 'Choice 1', secondary: 'Choice 1 explanation' },
+          value: 'choice_1',
+        },
+        {
+          label: { primary: 'Choice 2 lenghty explanation without reason' },
+          value: 'choice_2',
+        },
+      ],
+      component: 'Select',
+    },
+  },
+  {
+    key: 'number',
+    label: { primary: 'A positive number' },
+    required: true,
+    width: '100px',
+    type: 'int',
+  },
+  {
+    key: 'string',
+    label: null,
+    width: '100px',
+    required: true,
+    type: 'string',
+  },
+];
+const initialValues = {
+  phone: '6988888888',
+  choice_multiple: ['choice_2'],
+  string: 'default content',
+};
+
+const useStyles = makeStyles(
+  {
+    top: { minHeight: '75px' },
+    main: {},
+    side: {},
+  },
+  { name: 'MuiSite' }
+);
+
+export default function Index() {
+  const styles = useStyles();
+  const [data, setData] = useState(null);
+  const { t } = useTranslation();
+  return (
+    <BasicLayout>
+      <Top className={styles.top}>
+        <Header>
+          <GovGRLogo />
+          <HeaderTitle>Service name</HeaderTitle>
+        </Header>
+      </Top>
+      <Content>
+        <Main className={styles.main}>
+          <BackButton>{t('button.back')}</BackButton>
+          <PageTitle>
+            <PageTitleSection>
+              <PageTitleCaption>Before we start</PageTitleCaption>
+            </PageTitleSection>
+            <PageTitleHeading>Submit a form</PageTitleHeading>
+          </PageTitle>
+          <FormBuilder
+            fields={FIELDS}
+            onSubmit={setData}
+            initial={initialValues}
+          >
+            <Fieldset>
+              <FieldsetLabel>This is a fieldset</FieldsetLabel>
+              {FIELDS.map((field) => (
+                <Field key={field.key} name={field.key} />
+              ))}
+            </Fieldset>
+            <Button type="submit">{t('button.continue')}</Button>
+          </FormBuilder>
+          {data && <pre>{JSON.stringify(data, null, 2)}</pre>}
+        </Main>
+      </Content>
+      <Bottom>
+        <GovGRFooter />
+      </Bottom>
+    </BasicLayout>
+  );
+}
+
+```
+
+
+
+
+
+
+
+
+

package/esm/FormBuilder/FormBuilder.stories.js

@@ -0,0 +1,6 @@
+import FormBuilder from '@digigov/form/FormBuilder';
+export default {
+  title: 'Digigov Form/FormBuilder',
+  component: FormBuilder
+};
+export * from '@digigov/form/FormBuilder/__stories__/Default';

package/esm/FormBuilder/__stories__/Default.js

@@ -0,0 +1,25 @@
+import React from 'react';
+import FormBuilder, { Field } from '@digigov/form';
+import { Button } from '@digigov/ui/core';
+
+var _ref = /*#__PURE__*/React.createElement(Button, {
+  type: "submit"
+}, "\u03A3\u03C5\u03BD\u03AD\u03C7\u03B5\u03B9\u03B1");
+
+export var Default = function Default() {
+  return /*#__PURE__*/React.createElement(FormBuilder, {
+    onSubmit: function onSubmit(data) {
+      debugger;
+      console.log(data);
+    }
+  }, /*#__PURE__*/React.createElement(Field, {
+    key: "business-title",
+    name: "business-title",
+    type: "string",
+    label: {
+      primary: 'Όνομα επιχείρησης'
+    },
+    required: true
+  }), _ref);
+};
+export default Default;

package/esm/FormBuilder/index.js

@@ -0,0 +1,2 @@
+import { FormBuilder } from '@digigov/form/FormBuilder/FormBuilder';
+export default FormBuilder;

package/esm/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/esm/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/esm/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/esm/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/esm/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/esm/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/esm/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';