feat: add "Is part of cultural route" selection to enrolment form

also:
- with the request of the product owner don't restore any previous
  answer to "Is part of cultural route" question from local storage
  persisted Formik form's data, but instead always reset the question
  to its initial value i.e. no data given at all
- update generated GraphQL types using backend running
  City-of-Helsinki/palvelutarjotin#509 i.e. the backend support for the
  `is_part_of_cultural_route` field in enrolments and queue enrolments
- update playwright tests

Refs: PT-453

Author: karisal-anders

public/locales/en/enrolment.json

@@ -17,6 +17,13 @@
     "labelIsSharingDataAccepted": "I agree to share my information with the event organizer",
     "labelLanguage": "Language",
     "labelNotificationLanguage": "Language used in notifications",
+    "culturalRoute": {
+      "labelIsPartOf": "The visit is part of the cultural route",
+      "labelNoOrUnknown": "No / I don't know",
+      "labelYes": "Yes",
+      "helperText": "Cultural routes are implementation proposals for the City of Helsinki's cultural education plan from early childhood education to upper secondary education. <a>Read more</a>",
+      "readMoreUrl": "/en/cms-page/cultural-education/cultural-routes"
+    },
     "person": {
       "labelEmailAddress": "Email address",
       "labelName": "Name",

public/locales/fi/enrolment.json

@@ -17,6 +17,13 @@
     "labelIsSharingDataAccepted": "Hyväksyn tietojeni jakamisen tapahtuman järjestäjän kanssa",
     "labelLanguage": "Kieli",
     "labelNotificationLanguage": "Ilmoitusten kieli",
+    "culturalRoute": {
+      "labelIsPartOf": "Käynti sisältyy kulttuuripolkuun",
+      "labelNoOrUnknown": "Ei / en tiedä",
+      "labelYes": "Kyllä",
+      "helperText": "Kulttuuripolut ovat Helsingin kaupungin kulttuurikasvatussuunnitelman toteutusehdotuksia varhaiskasvatuksesta toiselle asteelle. <a>Lue lisää kulttuuripoluista</a>",
+      "readMoreUrl": "/fi/cms-page/kulttuurikasvatus/kulttuuripolulla-kulttuuria-kaikille"
+    },
     "person": {
       "labelEmailAddress": "Sähköpostiosoite",
       "labelName": "Nimi",

public/locales/sv/enrolment.json

@@ -17,6 +17,13 @@
     "labelIsSharingDataAccepted": "Jag samtycker till att dela mina uppgifter med arrangören av evenemanget.",
     "labelLanguage": "Språk",
     "labelNotificationLanguage": "Språket för meddelanden",
+    "culturalRoute": {
+      "labelIsPartOf": "Besöket ingår i kulturstigen",
+      "labelNoOrUnknown": "Nej / jag vet inte",
+      "labelYes": "Ja",
+      "helperText": "Kulturstigarna är förslag på genomförande av Helsingfors stads kulturfostransplan från småbarnspedagogik till gymnasieutbildning. <a>Läs mer om kulturstigarna</a>",
+      "readMoreUrl": "/sv/cms-page/kulturpedagogik/kulturstigen-kultur-for-alla"
+    },
     "person": {
       "labelEmailAddress": "E-post",
       "labelName": "Namn",

src/common/components/formikPersist/FormikPersist.tsx

@@ -1,5 +1,8 @@
 import { FormikProps, useFormikContext } from 'formik';
+import cloneDeep from 'lodash/cloneDeep';
+import get from 'lodash/get';
 import isEqual from 'lodash/isEqual';
+import set from 'lodash/set';
 import * as React from 'react';
 
 import useIsMounted from '../../../hooks/useIsMounted';
@@ -26,13 +29,16 @@ export interface PersistProps {
   debounceTime?: number;
   isSessionStorage?: boolean;
   initialValues: Record<string, unknown>;
+  // Dot-notation paths of fields that are restored using initial values:
+  alwaysFreshFields?: string[];
 }
 
 const FormikPersist = ({
   debounceTime = 300,
   isSessionStorage = false,
   name,
   initialValues,
+  alwaysFreshFields = [],
 }: PersistProps): null => {
   const isMounted = useIsMounted();
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -78,7 +84,12 @@ const FormikPersist = ({
       storedFormikStateObject &&
       objectStructureMatches(initialValues, storedFormikStateObject.values)
     ) {
-      formik.setValues(storedFormikStateObject.values, true);
+      const valuesToRestore = cloneDeep(storedFormikStateObject.values);
+      // Restore fresh fields with their initial values instead of stored ones:
+      for (const path of alwaysFreshFields) {
+        set(valuesToRestore, path, get(initialValues, path));
+      }
+      formik.setValues(valuesToRestore, true);
     }
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, []);

src/domain/enrolment/__tests__/utils.test.ts

@@ -0,0 +1,27 @@
+import { IsPartOfCulturalRoute } from '../enrolmentForm/constants';
+import { validIsPartOfCulturalRouteToBoolean } from '../utils';
+
+describe('validIsPartOfCulturalRouteToBoolean', () => {
+  test.each<IsPartOfCulturalRoute | string>([
+    IsPartOfCulturalRoute.YES, // Test that the enum version works
+    'YES', // Test that the string version also works
+  ])('validIsPartOfCulturalRouteToBoolean(%p) returns true', (input) => {
+    expect(validIsPartOfCulturalRouteToBoolean(input)).toBe(true);
+  });
+
+  test.each<IsPartOfCulturalRoute | string>([
+    IsPartOfCulturalRoute.NO_OR_UNKNOWN, // Test that the enum version works
+    'NO_OR_UNKNOWN', // Test that the string version also works
+  ])('validIsPartOfCulturalRouteToBoolean(%p) returns false', (input) => {
+    expect(validIsPartOfCulturalRouteToBoolean(input)).toBe(false);
+  });
+
+  test.each(['', ' ', 'yes', 'NO', 'unanswered', null, undefined, true, 0, 1])(
+    'validIsPartOfCulturalRouteToBoolean(%p) throws on invalid value',
+    (input) => {
+      expect(() => validIsPartOfCulturalRouteToBoolean(input)).toThrow(
+        `Invalid isPartOfCulturalRoute value ${input}`
+      );
+    }
+  );
+});

src/domain/enrolment/enrolmentForm/EnrolmentForm.tsx

@@ -17,6 +17,7 @@ import {
   nameToLabelPath,
 } from './constants';
 import styles from './enrolmentForm.module.scss';
+import IsPartOfCulturalRouteField from './IsPartOfCulturalRouteField';
 import getValidationSchema from './ValidationSchema';
 import ErrorMessage from '../../../common/components/form/ErrorMessage';
 import CheckboxField from '../../../common/components/form/fields/CheckboxField';
@@ -103,6 +104,7 @@ const EnrolmentForm: React.FC<Props> = ({
             <FormikPersist
               name={FORM_NAMES.ENROLMENT_FORM}
               initialValues={initialValues}
+              alwaysFreshFields={['isPartOfCulturalRoute']}
             />
             <h2>{t('enrolment:enrolmentForm.studyGroup.titleNotifier')}</h2>
             <FormErrorNotification
@@ -206,6 +208,10 @@ const EnrolmentForm: React.FC<Props> = ({
               </FormGroup>
             </div>
 
+            <FormGroup>
+              <IsPartOfCulturalRouteField formikFieldName="isPartOfCulturalRoute" />
+            </FormGroup>
+
             <div className={styles.rowWith2Columns}>
               <div>
                 <h2>{t('enrolment:enrolmentForm.studyGroup.titleGroup')}</h2>

src/domain/enrolment/enrolmentForm/IsPartOfCulturalRouteField.tsx

@@ -0,0 +1,62 @@
+import { Link } from '@city-of-helsinki/react-helsinki-headless-cms';
+import { useField } from 'formik';
+import { RadioButton, SelectionGroup } from 'hds-react';
+import { Trans, useTranslation } from 'next-i18next';
+import React from 'react';
+
+import { IsPartOfCulturalRoute, nameToLabelPath } from './constants';
+import type { I18nNamespace } from '../../../types';
+
+type Props = {
+  formikFieldName: string;
+};
+
+/**
+ * React component for "Is part of cultural route?" field in the enrolment form,
+ * with choices of "No / I don't know" and "Yes".
+ */
+const IsPartOfCulturalRouteField: React.FC<Props> = ({ formikFieldName }) => {
+  const { t } = useTranslation<I18nNamespace>();
+  const [field, meta] = useField(formikFieldName);
+  const errorText = meta.touched && meta.error ? t(meta.error) : undefined;
+  const readMoreUrl = t('enrolment:enrolmentForm.culturalRoute.readMoreUrl');
+
+  return (
+    <SelectionGroup
+      label={t(nameToLabelPath['isPartOfCulturalRoute'])}
+      direction="horizontal"
+      required
+      aria-required
+      errorText={errorText}
+      /* @ts-expect-error TS2322 SelectionGroup's types allow only string, but Trans works */
+      helperText={
+        <Trans
+          t={t}
+          i18nKey={'enrolment:enrolmentForm.culturalRoute.helperText'}
+          components={{ a: <Link href={readMoreUrl} /> }}
+        />
+      }
+    >
+      <RadioButton
+        id="isPartOfCulturalRoute-noOrUnknown"
+        name={field.name}
+        value={IsPartOfCulturalRoute.NO_OR_UNKNOWN}
+        label={t('enrolment:enrolmentForm.culturalRoute.labelNoOrUnknown')}
+        checked={field.value === IsPartOfCulturalRoute.NO_OR_UNKNOWN}
+        onChange={field.onChange}
+        onBlur={field.onBlur}
+      />
+      <RadioButton
+        id="isPartOfCulturalRoute-yes"
+        name={field.name}
+        value={IsPartOfCulturalRoute.YES}
+        label={t('enrolment:enrolmentForm.culturalRoute.labelYes')}
+        checked={field.value === IsPartOfCulturalRoute.YES}
+        onChange={field.onChange}
+        onBlur={field.onBlur}
+      />
+    </SelectionGroup>
+  );
+};
+
+export default IsPartOfCulturalRouteField;

src/domain/enrolment/enrolmentForm/ValidationSchema.tsx

@@ -1,5 +1,6 @@
 import * as Yup from 'yup';
 
+import { IsPartOfCulturalRoute } from './constants';
 import { VALIDATION_MESSAGE_KEYS } from '../../app/forms/constants';
 
 type EnrolmentFormValidationSchemaProps = {
@@ -14,6 +15,10 @@ export default function getValidationSchema({
   isQueueEnrolment,
 }: EnrolmentFormValidationSchemaProps) {
   return Yup.object().shape({
+    isPartOfCulturalRoute: Yup.string().oneOf(
+      [IsPartOfCulturalRoute.NO_OR_UNKNOWN, IsPartOfCulturalRoute.YES],
+      VALIDATION_MESSAGE_KEYS.STRING_REQUIRED
+    ),
     hasEmailNotification: Yup.bool().oneOf(
       [true],
       'enrolment:enrolmentForm.validation.hasEmailNotification'

src/domain/enrolment/enrolmentForm/__tests__/EnrolmentForm.test.tsx

@@ -23,7 +23,10 @@ import {
   within,
   sleep,
 } from '../../../../utils/testUtils';
-import { defaultEnrolmentInitialValues } from '../constants';
+import {
+  defaultEnrolmentInitialValues,
+  IsPartOfCulturalRoute,
+} from '../constants';
 import EnrolmentForm, { Props } from '../EnrolmentForm';
 
 configure({ defaultHidden: true });
@@ -113,6 +116,14 @@ test('renders form and user can fill it and submit and form is saved to local st
 
   // // close dropdown
 
+  // Answer "Is part of cultural route?" question
+  const culturalRouteGroup = await screen.findByRole('group', {
+    name: /käynti sisältyy kulttuuripolkuun/i,
+  });
+  await userEvent.click(
+    within(culturalRouteGroup).getByRole('radio', { name: /kyllä/i })
+  );
+
   await userEvent.click(screen.getByRole('combobox', { name: /luokka-aste/i }));
 
   await userEvent.type(screen.getByLabelText(/lapsia/i), '10');
@@ -411,6 +422,7 @@ if (isFeatureEnabled('FORMIK_PERSIST')) {
       isSameResponsiblePerson: true,
       isSharingDataAccepted: false,
       isMandatoryAdditionalInformationRequired: false,
+      isPartOfCulturalRoute: IsPartOfCulturalRoute.NO_OR_UNKNOWN,
       language: '',
       studyGroup: {
         person: {
@@ -504,6 +516,23 @@ if (isFeatureEnabled('FORMIK_PERSIST')) {
       expect(
         screen.getByRole('combobox', { name: /luokka-aste/i })
       ).toHaveTextContent('1. luokka');
+
+      // Test that "Is part of cultural route?" question is not answered,
+      // because this field should not be restored from local storage:
+      const culturalRouteGroup = await screen.findByRole('group', {
+        name: /käynti sisältyy kulttuuripolkuun/i,
+      });
+      const isNotPartOfCulturalRoute = within(culturalRouteGroup).getByRole(
+        'radio',
+        { name: /ei \/ en tiedä/i }
+      );
+      const isPartOfCulturalRoute = within(culturalRouteGroup).getByRole(
+        'radio',
+        { name: /kyllä/i }
+      );
+      expect(isNotPartOfCulturalRoute).not.toBeChecked();
+      expect(isPartOfCulturalRoute).not.toBeChecked();
+
       const childrenCountInput = screen.getByRole('spinbutton', {
         name: /lapsia \*/i,
       });

src/domain/enrolment/enrolmentForm/__tests__/IsPartOfCulturalRouteField.test.tsx

@@ -0,0 +1,91 @@
+import { Formik } from 'formik';
+import * as React from 'react';
+
+import {
+  render,
+  screen,
+  userEvent,
+  within,
+  configure,
+} from '../../../../utils/testUtils';
+import { IsPartOfCulturalRoute } from '../constants';
+import IsPartOfCulturalRouteField from '../IsPartOfCulturalRouteField';
+
+configure({ defaultHidden: true });
+
+const renderComponent = (initialValue: IsPartOfCulturalRoute | '' = '') =>
+  render(
+    <Formik
+      initialValues={{ isPartOfCulturalRoute: initialValue }}
+      onSubmit={jest.fn()}
+    >
+      <IsPartOfCulturalRouteField formikFieldName="isPartOfCulturalRoute" />
+    </Formik>
+  );
+
+const getGroup = () =>
+  screen.findByRole('group', { name: /käynti sisältyy kulttuuripolkuun/i });
+
+const getNoOrUnknownRadio = (group: HTMLElement) =>
+  within(group).getByRole('radio', { name: /ei \/ en tiedä/i });
+
+const getYesRadio = (group: HTMLElement) =>
+  within(group).getByRole('radio', { name: /kyllä/i });
+
+describe('IsPartOfCulturalRouteField', () => {
+  it('renders the selection group with both radio options', async () => {
+    renderComponent();
+    const group = await getGroup();
+    expect(getNoOrUnknownRadio(group)).toBeInTheDocument();
+    expect(getYesRadio(group)).toBeInTheDocument();
+  });
+
+  it('has no radio checked when initial value is empty', async () => {
+    renderComponent('');
+    const group = await getGroup();
+    expect(getNoOrUnknownRadio(group)).not.toBeChecked();
+    expect(getYesRadio(group)).not.toBeChecked();
+  });
+
+  it('checks "No / I don\'t know" when initial value is NO_OR_UNKNOWN', async () => {
+    renderComponent(IsPartOfCulturalRoute.NO_OR_UNKNOWN);
+    const group = await getGroup();
+    expect(getNoOrUnknownRadio(group)).toBeChecked();
+    expect(getYesRadio(group)).not.toBeChecked();
+  });
+
+  it('checks "Yes" when initial value is YES', async () => {
+    renderComponent(IsPartOfCulturalRoute.YES);
+    const group = await getGroup();
+    expect(getNoOrUnknownRadio(group)).not.toBeChecked();
+    expect(getYesRadio(group)).toBeChecked();
+  });
+
+  it('checks only "Yes" radio after clicking it', async () => {
+    renderComponent('');
+    const group = await getGroup();
+    await userEvent.click(getYesRadio(group));
+    expect(getYesRadio(group)).toBeChecked();
+    expect(getNoOrUnknownRadio(group)).not.toBeChecked();
+  });
+
+  it('checks only "No / I don\'t know" radio after clicking it', async () => {
+    renderComponent('');
+    const group = await getGroup();
+    await userEvent.click(getNoOrUnknownRadio(group));
+    expect(getNoOrUnknownRadio(group)).toBeChecked();
+    expect(getYesRadio(group)).not.toBeChecked();
+  });
+
+  it('renders a translated "read more" link with correct href', async () => {
+    renderComponent();
+    await getGroup();
+    const link = screen.getByRole('link', {
+      name: /lue lisää kulttuuripoluista/i,
+    });
+    expect(link).toHaveAttribute(
+      'href',
+      '/fi/cms-page/kulttuurikasvatus/kulttuuripolulla-kulttuuria-kaikille'
+    );
+  });
+});