@digigov/form 0.10.6 → 0.10.8

package/Questions/index.mdx

@@ -1,13 +1,418 @@
 ---
-title: Questions
-parent: docs/ui/components
+id: ask-questions-steps
+title: Asking questions in multiple steps
 ---
 
-## Example
+import {
+  TableContainer,
+  Table,
+  TableCaption,
+  TableHead,
+  TableRow,
+  TableBody,
+  TableHeadCell,
+  TableDataCell,
+} from '@digigov/react-core';
 
+import LeadText from "@site/src/components/LeadText";
 
-## API
+<LeadText>Question pages are used to ask users meaningful questions needed by
+your GOV.GR service, or even gather data about their persona or their
+application status. Use step questions to make bigger forms less scary and
+easier to fill out.</LeadText>
 
-### Properties
+## Introduction to Question pages
 
-### Styles
+Asking questions is a vital part of interacting with our users, and asking them
+to provide information needed for your service. We want to build forms that
+are accessible to a lot of people regardless of their cognitive or other
+impairments, challenges, or other technological drawbacks.
+
+In our case, we don't have to worry about profit, conversions, and sales, but
+there are other hidden costs. If there are too many questions in the form,
+you’ll lose users. You’ll also lose users if there are questions in the form
+that users consider impertinent or irrelevant—or, even worse, you’ll get made-up
+data. If you find that your users have names like John Doe or Mickey Mouse and
+live on Anystreet, in Anywhere, you’ve collected a lot of rubbish that costs a
+lot to clean up. Plus, there is the further hidden cost of loss of goodwill.
+Even if users struggle through to the end of a form and answer honestly, if it’s
+more work than they expected, they’ll be annoyed about it. That's the exact
+opposite of our goals of making concise, easy-to-use services.
+
+```jsx live
+import React from 'react';
+import Questions, { Step, StepForm, StepTitle } from '@digigov/form/Questions';
+import { Field } from '@digigov/form';
+
+const steps = [
+  {
+    name: 'residency',
+    title: 'Where do you live?',
+    fields: [
+      {
+        key: 'countries',
+        type: 'choice:single',
+        required: true,
+        extra: {
+          options: [
+            {
+              label: {
+                primary: 'Greece',
+              },
+              value: 'greece',
+            },
+            {
+              label: {
+                primary: 'Cyprus',
+              },
+              value: 'cyprus',
+            },
+            {
+              label: {
+                primary: 'European Union',
+              },
+              value: 'eu',
+            },
+            {
+              label: {
+                primary: 'United States of America',
+              },
+              value: 'usa',
+            },
+          ],
+        },
+      },
+    ],
+  },
+  {
+    name: 'bod',
+    title: 'When is your birthday?',
+    fields: [
+      {
+        key: 'bod',
+        label: {
+          primary: 'Birthday',
+        },
+        type: 'date',
+        required: true
+      }
+    ]
+  }
+];
+
+export default function Index() {
+  return (
+    <Questions
+      name={'example'}
+      steps={steps}
+      onSubmit={(data) => {
+        console.log(data);
+      }}
+    >
+      <Step name="residency">
+        <StepTitle />
+        <StepForm submitButton={true}>
+          <Field name="countries" />
+        </StepForm>
+      </Step>
+      <Step name="bod">
+        <StepTitle />
+        <StepForm submitButton={true}>
+          <Field name="bod" />
+        </StepForm>
+      </Step>
+    </Questions>
+  );
+}
+```
+
+When we started working on forms, we started following the GOV.UK paradigm,
+asking just one question per screen, making it very manageable on mobiles. When
+we sent this early design around internally for comments, a common response was
+that it felt odd on large screens and it slowed users down. In reality, even if
+it adds more clicks, it makes the process feel simpler and easy - there wasn’t
+too much to take in and process at any one time. So we stuck with the simpler
+screens for everyone. [Read
+more](https://designnotes.blog.gov.uk/2014/07/14/things-we-learnt-designing-register-to-vote/)
+about this topic.
+
+The approach gave us other advantages. For example, say someone makes a mistake
+answering a question: entering an email address with no ‘@’. The mistake and how
+to correct it is a lot clearer if the question is on the screen. With longer
+pages, it’s common for the question to be off the top or bottom of the screen,
+making it harder to find.
+
+For more information about the design specification of question pages, you can
+read our [“Question pages“ pattern
+page](https://guide.services.gov.gr/docs/questions-pages).
+
+## How to use it
+
+Each step can be defined using a `Step` React component and all steps should be
+place inside a `Questions` component, that will provide the steps subcomponents
+the required state.
+
+First, you declare an array called `steps` and then you pass it to `<Questions
+/>` as a prop. Then for each step you can declare a `<Step />` component and
+its subsequent subcomponents that you customise as needed, like the step title,
+description or form. You can also add components that are not form-specific,
+adding paragraphs or other custom components.
+
+```jsx
+<Questions
+  name="example"
+  steps={steps}
+  onSubmit={(data) => doSomething(data)}
+>
+  {/* more steps could be rendered here ... */}
+  <Step name="age">
+    <StepTitle />
+    <StepDescription />
+    <StepForm submitButton={true}>
+      <Field name="age" />
+    </StepForm>
+  </Step>
+  {/* and of course more could be down here as well */}
+</Questions>
+```
+
+### Step specification
+
+Steps can be described using `StepInterface` interface declared as a JSON
+object. The most basic properties are the following:
+
+* `name` - a unique identifier, must be different for each step
+* `title` - the main questions title that communicates to the users what this
+  question page is about, rendered by `StepTitle`
+* `fields` - an array that describes each input field that will be rendered in
+  the `StepForm`. Each fields implements the `FieldSpec` interface as a JSON object.
+
+```json title="step-name.json"
+{
+  name: 'name',
+  title: 'What is your name?',
+  fields: [
+    {
+      key: 'name',
+      type: 'string',
+      required: true,
+    }
+  ]
+}
+```
+
+### Branching between steps
+
+Each step will be rendered in the order that matches their index inside the
+array of fields. You can change this order and create branching between any two
+steps.
+
+Each step can be programmaticaly linked to the next step so you can do some
+basic branching between each step. The `nextStep` property will need to be a
+function that will take the form state as an argument and will return the key of
+the next `step`.
+
+```json title="next-step.json"
+const steps = [
+  {
+    name: 'age',
+    title: 'What is your age?',
+    fields: [
+      {
+        key: 'age',
+        type: 'int',
+        required: true,
+      }
+    ],
+    // highlight-start
+    nextStep: (data) => {
+      return data.age < 18 ? 'citizen-adult' : citizen-underage;
+    }
+    // highlight-end
+  },
+  {
+    name: 'citizen-underage',
+    title: 'Are you a student?',
+    fields: [ ... ]
+  },
+  {
+    // highlight-next-line
+    name: 'citizen-adult',
+    title: 'Are you currently employed?',
+    fields: [
+      {
+        key: 'citizen-underage-employed',
+        type: 'choice:single',
+        required: true,
+        extra: {
+          options: [
+            {
+              label: {primary: "Yes"},
+              value: 'yes',
+            },
+            {
+              label: {primary: "No"},
+              value: 'no',
+            }
+          ]
+        }
+      }
+    ]
+  },
+];
+```
+
+For example, you may use a form to determine if citizens are adults or not, and
+we want to ask users different questions according to their persona. We can use
+a branch between the `age` step and the other two steps.  
+
+```jsx live
+import React from 'react';
+import GovGRFooter from '@digigov/ui/govgr/Footer';
+import Header from '@digigov/ui/app/Header';
+import HeaderSection from '@digigov/ui/app/Header/HeaderSection';
+import HeaderContent from '@digigov/ui/app/Header/HeaderContent';
+import GovGRLogo from '@digigov/ui/govgr/Logo';
+import BasicLayout, {
+  Top,
+  Content,
+  Main,
+  Bottom,
+} from '@digigov/ui/layouts/Basic';
+import Questions, { Step, StepForm, StepTitle } from '@digigov/form/Questions';
+import { Field } from '@digigov/form';
+import TranslatorsHeader from 'translators-landing/components/TranslatorsHeader';
+
+const steps = [
+  {
+    name: 'age',
+    title: 'What is your age?',
+    fields: [
+      {
+        key: 'age',
+        type: 'int',
+        required: true,
+      }
+    ],
+    nextStep: (data) => {
+      return data.age < 18 ? 'citizen-adult' : 'citizen-underage';
+    }
+  },
+  {
+    name: 'citizen-underage',
+    title: 'Are you a student?',
+    fields: [
+      {
+        key: 'citizen-underage-student',
+        type: 'choice:single',
+        required: true,
+        extra: {
+          options: [
+            {
+              label: {primary: "Yes"},
+              value: 'yes',
+            },
+            {
+              label: {primary: "No"},
+              value: 'no',
+            }
+          ]
+        }
+      }
+    ]
+  },
+  {
+    name: 'citizen-adult',
+    title: 'Are you currently employed?',
+    fields: [
+      {
+        key: 'citizen-adult-employed',
+        type: 'choice:single',
+        required: true,
+        extra: {
+          options: [
+            {
+              label: {primary: "Yes"},
+              value: 'yes',
+            },
+            {
+              label: {primary: "No"},
+              value: 'no',
+            }
+          ]
+        }
+      }
+    ]
+  },
+];
+
+export default function Index() {
+  return (
+    <BasicLayout>
+      <Top>
+        <Header>
+          <HeaderSection>
+            <HeaderContent>
+              <GovGRLogo href="#" />
+            </HeaderContent>
+          </HeaderSection>
+        </Header>
+      </Top>
+      <Content>
+        <Main>
+          <Questions
+            name={'example'}
+            steps={steps}
+            onSubmit={(data) => {
+              console.log(data);
+            }}
+          >
+            <Step name="age">
+              <StepTitle />
+              <StepForm submitButton={true}>
+                <Field name="age" />
+              </StepForm>
+            </Step>
+            <Step name="citizen-underage">
+              <StepTitle />
+              <StepForm submitButton={true}>
+                <Field name="citizen-underage-student" />
+              </StepForm>
+            </Step>
+            <Step name="citizen-adult">
+              <StepTitle />
+              <StepForm submitButton={true}>
+                <Field name="citizen-adult-employed" />
+              </StepForm>
+            </Step>
+          </Questions>
+        </Main>
+      </Content>
+      <Bottom>
+        <GovGRFooter />
+      </Bottom>
+    </BasicLayout>
+  );
+}
+```
+
+## Prop types 
+
+<TableContainer>
+  <Table>
+    <TableHead>
+      <TableRow>
+        <TableHeadCell>Περίοδος</TableHeadCell>
+        <TableHeadCell>Κανονικό ποσό</TableHeadCell>
+        <TableHeadCell>Μειωμένο ποσό</TableHeadCell>
+      </TableRow>
+    </TableHead>
+    <TableBody>
+      <TableRow>
+        <TableDataCell>Πρώτες 6 εβδομάδες   </TableDataCell>
+        <TableDataCell> €109.80 / εβδομάδα</TableDataCell>
+        <TableDataCell> €69.80 / εβδομάδα</TableDataCell>
+      </TableRow>
+    </TableBody>
+  </Table>
+</TableContainer>

package/es/Field/FieldBase.js

@@ -2,7 +2,7 @@ import _extends from "@babel/runtime/helpers/extends";
 import _objectWithoutProperties from "@babel/runtime/helpers/objectWithoutProperties";
 var _excluded = ["required", "name", "component", "wrapper", "control", "type", "controlled", "enabled", "editable", "defaultValue", "label", "extra", "layout", "error", "register"];
 import React from 'react';
-import FieldContainer from '@digigov/form/Field/FieldContainer';
+import FieldBaseContainer from '@digigov/form/Field/FieldBaseContainer';
 import { Controller } from 'react-hook-form';
 export var FieldBase = function FieldBase(props) {
   var required = props.required,
@@ -30,7 +30,7 @@ export var FieldBase = function FieldBase(props) {
   }
 
   if (controlled) {
-    return /*#__PURE__*/React.createElement(FieldContainer, {
+    return /*#__PURE__*/React.createElement(FieldBaseContainer, {
       label: label,
       layout: layout,
       error: error,
@@ -55,7 +55,7 @@ export var FieldBase = function FieldBase(props) {
     }));
   }
 
-  return /*#__PURE__*/React.createElement(FieldContainer, {
+  return /*#__PURE__*/React.createElement(FieldBaseContainer, {
     label: label,
     layout: layout,
     error: error,

package/es/Field/{FieldContainer.js → FieldBaseContainer.js}

@@ -1,14 +1,14 @@
 import _extends from "@babel/runtime/helpers/extends";
 import React from 'react';
-import CoreField from '@digigov/react-core/Field';
-import CoreLabel from '@digigov/react-core/Label';
+import FieldContainer from '@digigov/react-core/FieldContainer';
+import LabelContainer from '@digigov/react-core/LabelContainer';
 import CoreFieldset from '@digigov/react-core/Fieldset';
 import Hint from '@digigov/react-core/Hint';
 import FieldsetLegend from '@digigov/react-core/FieldsetLegend';
 import ErrorMessage from '@digigov/react-core/ErrorMessage';
 import { useTranslation } from '@digigov/ui/app/i18n';
 import Label from '@digigov/form/inputs/Label';
-export var FieldContainer = function FieldContainer(_ref) {
+export var FieldBaseContainer = function FieldBaseContainer(_ref) {
   var name = _ref.name,
       wrapper = _ref.wrapper,
       label = _ref.label,
@@ -23,7 +23,7 @@ export var FieldContainer = function FieldContainer(_ref) {
   var errorContext = (error === null || error === void 0 ? void 0 : error.message.context) || {};
 
   if (wrapper === 'fieldset') {
-    return /*#__PURE__*/React.createElement(CoreField, _extends({
+    return /*#__PURE__*/React.createElement(FieldContainer, _extends({
       error: !!error
     }, layout), /*#__PURE__*/React.createElement(CoreFieldset, null, /*#__PURE__*/React.createElement(FieldsetLegend, {
       size: "s"
@@ -31,13 +31,13 @@ export var FieldContainer = function FieldContainer(_ref) {
       id: "".concat(name, "-error")
     }, t(errorMessage, errorContext)), children));
   } else {
-    return /*#__PURE__*/React.createElement(CoreField, _extends({
+    return /*#__PURE__*/React.createElement(FieldContainer, _extends({
       error: !!error
-    }, layout), /*#__PURE__*/React.createElement(CoreLabel, null, label && /*#__PURE__*/React.createElement(Label, {
+    }, layout), /*#__PURE__*/React.createElement(LabelContainer, null, label && /*#__PURE__*/React.createElement(Label, {
       label: label
     }), error && /*#__PURE__*/React.createElement(ErrorMessage, {
       id: "".concat(name, "-error")
     }, t(errorMessage, errorContext)), children));
   }
 };
-export default FieldContainer;
+export default FieldBaseContainer;

package/es/FieldArray/FieldArray.stories.js

@@ -1,7 +1,8 @@
 import FieldArray from '@digigov/form/FieldArray';
 export default {
   title: 'Digigov Form/FieldArray',
-  component: FieldArray
+  component: FieldArray,
+  displayName: 'FieldArray'
 };
 export * from '@digigov/form/FieldArray/__stories__/Default';
 export * from '@digigov/form/FieldArray/__stories__/WithExactLength';

package/es/FieldArray/index.js

@@ -7,7 +7,7 @@ import FieldObject from '@digigov/form/FieldObject';
 import { Button, Card, Hint } from '@digigov/ui';
 import { FieldsetLabel } from '@digigov/form/Fieldset';
 import Fieldset from '@digigov/react-core/Fieldset';
-import FieldContainer from '@digigov/form/Field/FieldContainer';
+import FieldContainer from '@digigov/form/Field/FieldBaseContainer';
 export var FieldArray = function FieldArray(_ref) {
   var _customField$extra, _customField$extra$la, _customField$extra4, _customField$extra4$l;
 

package/es/Fieldset/index.js

@@ -4,7 +4,7 @@ var _excluded = ["children"],
     _excluded2 = ["children"];
 import React from 'react';
 import Grid from '@digigov/ui/layouts/Grid';
-import CoreFieldset from '@digigov/react-core/Fieldset';
+import Fieldset from '@digigov/react-core/Fieldset';
 import FieldsetLegend from '@digigov/react-core/FieldsetLegend';
 import Hint from '@digigov/react-core/Hint';
 import NormalText from '@digigov/ui/typography/NormalText';
@@ -30,8 +30,5 @@ export var FieldsetBody = function FieldsetBody(_ref3) {
     xs: 12
   }, /*#__PURE__*/React.createElement(NormalText, null, children));
 };
-export var Fieldset = function Fieldset(_ref4) {
-  var children = _ref4.children;
-  return /*#__PURE__*/React.createElement(CoreFieldset, null, children);
-};
+export { Fieldset };
 export default Fieldset;

package/es/FormBuilder/FormBuilder.stories.js

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

package/es/MultiplicityField/MultiplicityField.stories.js

@@ -1,7 +1,8 @@
 import MultiplicityField from '@digigov/form/MultiplicityField';
 export default {
   title: 'Digigov Form/MultiplicityField',
-  component: MultiplicityField
+  component: MultiplicityField,
+  displayName: 'MultiplicityField'
 };
 export * from '@digigov/form/MultiplicityField/__stories__/Default';
 export * from '@digigov/form/MultiplicityField/__stories__/WithMinLength';

package/es/MultiplicityField/index.js

@@ -6,7 +6,7 @@ import { Card, CardText, CardAction, Button, Heading, CardHeading } from '@digig
 import AddObjects from '@digigov/form/MultiplicityField/add-objects';
 import { useFieldArray } from 'react-hook-form';
 import FieldObject from '@digigov/form/FieldObject';
-import FieldContainer from '@digigov/form/Field/FieldContainer';
+import FieldContainer from '@digigov/form/Field/FieldBaseContainer';
 // epeidh einai forwardRef to ref mas to dinei xwrista apo ta props
 export var Multiplicity = function Multiplicity(_ref) {
   var extra = _ref.extra,

package/es/Questions/Questions.stories.js

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

package/es/Questions/__stories__/Default.js

@@ -0,0 +1,103 @@
+import React from 'react';
+import GovGRFooter from '@digigov/ui/govgr/Footer';
+import Header from '@digigov/ui/app/Header';
+import HeaderSection from '@digigov/ui/app/Header/HeaderSection';
+import HeaderContent from '@digigov/ui/app/Header/HeaderContent';
+import GovGRLogo from '@digigov/ui/govgr/Logo';
+import BasicLayout, { Top, Content, Main, Bottom } from '@digigov/ui/layouts/Basic';
+import Questions, { Step, StepForm, StepTitle } from '@digigov/form/Questions';
+import { Field } from '@digigov/form';
+var steps = [{
+  name: 'age',
+  title: 'What is your age?',
+  fields: [{
+    key: 'age',
+    type: 'int',
+    required: true
+  }],
+  nextStep: function nextStep(data) {
+    return data.age > 17 ? 'citizen-adult' : 'citizen-underage';
+  }
+}, {
+  name: 'citizen-underage',
+  title: 'Are you a student?',
+  fields: [{
+    key: 'citizen-underage-student',
+    type: 'radio',
+    required: true,
+    options: [{
+      label: {
+        primary: 'Yes'
+      },
+      value: 'yes'
+    }, {
+      label: {
+        primary: 'No'
+      },
+      value: 'no'
+    }]
+  }]
+}, {
+  name: 'citizen-adult',
+  title: 'Are you currently employed?',
+  fields: [{
+    key: 'citizen-adult-employed',
+    type: 'radio',
+    required: true,
+    options: [{
+      label: {
+        primary: 'Yes'
+      },
+      value: 'yes'
+    }, {
+      label: {
+        primary: 'No'
+      },
+      value: 'no'
+    }]
+  }]
+}];
+
+var _ref = /*#__PURE__*/React.createElement(Top, null, /*#__PURE__*/React.createElement(Header, null, /*#__PURE__*/React.createElement(HeaderSection, null, /*#__PURE__*/React.createElement(HeaderContent, null, /*#__PURE__*/React.createElement(GovGRLogo, {
+  href: "#"
+})))));
+
+var _ref2 = /*#__PURE__*/React.createElement(Step, {
+  name: "age"
+}, /*#__PURE__*/React.createElement(StepTitle, null), /*#__PURE__*/React.createElement(StepForm, {
+  submitButton: true
+}, /*#__PURE__*/React.createElement(Field, {
+  key: "age",
+  name: "age"
+})));
+
+var _ref3 = /*#__PURE__*/React.createElement(Step, {
+  name: "citizen-underage"
+}, /*#__PURE__*/React.createElement(StepTitle, null), /*#__PURE__*/React.createElement(StepForm, {
+  submitButton: true
+}, /*#__PURE__*/React.createElement(Field, {
+  key: "citizen-underage-student",
+  name: "citizen-underage-student"
+})));
+
+var _ref4 = /*#__PURE__*/React.createElement(Step, {
+  name: "citizen-adult"
+}, /*#__PURE__*/React.createElement(StepTitle, null), /*#__PURE__*/React.createElement(StepForm, {
+  submitButton: true
+}, /*#__PURE__*/React.createElement(Field, {
+  key: "citizen-adult-employed",
+  name: "citizen-adult-employed"
+})));
+
+var _ref5 = /*#__PURE__*/React.createElement(Bottom, null, /*#__PURE__*/React.createElement(GovGRFooter, null));
+
+export function Default() {
+  return /*#__PURE__*/React.createElement(BasicLayout, null, _ref, /*#__PURE__*/React.createElement(Content, null, /*#__PURE__*/React.createElement(Main, null, /*#__PURE__*/React.createElement(Questions, {
+    name: 'example',
+    steps: steps,
+    onSubmit: function onSubmit(data) {
+      console.log(data);
+    }
+  }, _ref2, _ref3, _ref4))), _ref5);
+}
+export default Default;