@digigov/form 0.10.7 → 0.10.9

package/src/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/GovGRLogo';
+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/src/inputs/Checkboxes/Checkboxes.stories.js

@@ -2,5 +2,6 @@ import Checkboxes from '@digigov/form/inputs/Checkboxes';
 export default {
   title: 'Digigov Form/inputs/Checkboxes',
   component: Checkboxes,
+  displayName: 'Checkboxes'
 };
 export * from '@digigov/form/inputs/Checkboxes/__stories__/Default';

package/src/inputs/DateInput/DateInput.stories.js

@@ -2,5 +2,6 @@ import DateInput from '@digigov/form/inputs/DateInput';
 export default {
   title: 'Digigov Form/inputs/DateInput',
   component: DateInput,
+  displayName: 'DateInput'
 };
 export * from '@digigov/form/inputs/DateInput/__stories__/Default';

package/src/inputs/FileInput/FileInput.stories.js

@@ -2,5 +2,6 @@ import FileInput from '@digigov/form/inputs/FileInput';
 export default {
   title: 'Digigov Form/inputs/FileInput',
   component: FileInput,
+  displayName: 'FileInput'
 };
 export * from '@digigov/form/inputs/FileInput/__stories__/Default';

package/src/inputs/Input/Input.stories.js

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

package/src/inputs/Label/Label.stories.js

@@ -2,5 +2,6 @@ import Label from '@digigov/form/inputs/Label';
 export default {
   title: 'Digigov Form/inputs/Label',
   component: Label,
+  displayName: 'Label'
 };
 export * from '@digigov/form/inputs/Label/__stories__/Default';

package/src/inputs/Radio/Radio.stories.js

@@ -2,5 +2,6 @@ import Radio from '@digigov/form/inputs/Radio';
 export default {
   title: 'Digigov Form/inputs/Radio',
   component: Radio,
+  displayName: 'Radio'
 };
 export * from '@digigov/form/inputs/Radio/__stories__/Default';

package/src/inputs/Select/Select.stories.js

@@ -2,5 +2,6 @@ import Select from '@digigov/form/inputs/Select';
 export default {
   title: 'Digigov Form/inputs/Select',
   component: Select,
+  displayName: 'Select'
 };
 export * from '@digigov/form/inputs/Select/__stories__/Default';

package/.eslintrc.js

@@ -1,3 +0,0 @@
-module.exports = {
-  extends: [require.resolve('@digigov/cli-lint/eslint.config')],
-};

package/.prettierrc.js

@@ -1,3 +0,0 @@
-module.exports = require('@digigov/cli-lint/prettierrc')();
-
-