@defra/forms-engine-plugin 0.0.1

package/src/server/plugins/engine/pageControllers/RepeatPageController.test.ts

@@ -0,0 +1,264 @@
+import { FormModel } from '~/src/server/plugins/engine/models/FormModel.js'
+import { RepeatPageController } from '~/src/server/plugins/engine/pageControllers/RepeatPageController.js'
+import {
+  type FormContextRequest,
+  type FormPageViewModel,
+  type FormSubmissionError,
+  type RepeatListState,
+  type RepeaterSummaryPageViewModel
+} from '~/src/server/plugins/engine/types.js'
+import definition from '~/test/form/definitions/repeat.js'
+
+describe('RepeatPageController', () => {
+  const itemId1 = 'abc-123'
+  const itemId2 = 'xyz-987'
+
+  let pageUrl: URL
+  let pageItemUrl: URL
+  let pageSummaryUrl: URL
+
+  let model: FormModel
+  let controller: RepeatPageController
+  let requestPage: FormContextRequest
+  let requestPageItem: FormContextRequest
+  let requestPageSummary: FormContextRequest
+
+  beforeEach(() => {
+    const { pages } = definition
+
+    pageUrl = new URL('/repeat/pizza-order', 'http://example.com')
+
+    pageItemUrl = new URL(
+      `${pageUrl.pathname}/${itemId1}`,
+      'http://example.com'
+    )
+
+    pageSummaryUrl = new URL(
+      `${pageUrl.pathname}/summary`,
+      'http://example.com'
+    )
+
+    model = new FormModel(definition, {
+      basePath: 'test'
+    })
+
+    controller = new RepeatPageController(model, pages[0])
+
+    requestPage = {
+      method: 'get',
+      url: pageUrl,
+      path: pageUrl.pathname,
+      params: {
+        path: 'pizza-order',
+        slug: 'repeat'
+      },
+      query: {},
+      app: { model }
+    }
+
+    requestPageItem = {
+      method: 'get',
+      url: pageItemUrl,
+      path: pageItemUrl.pathname,
+      params: {
+        path: 'pizza-order',
+        slug: 'repeat',
+        itemId: itemId1
+      },
+      query: {},
+      app: { model }
+    }
+
+    requestPageSummary = {
+      method: 'get',
+      url: pageSummaryUrl,
+      path: pageSummaryUrl.pathname,
+      params: {
+        path: 'pizza-order',
+        slug: 'repeat'
+      },
+      query: {},
+      app: { model }
+    }
+  })
+
+  describe('Properties', () => {
+    it('returns summary view name', () => {
+      expect(controller).toHaveProperty(
+        'listSummaryViewName',
+        'repeat-list-summary'
+      )
+    })
+
+    it('returns delete view name', () => {
+      expect(controller).toHaveProperty('listDeleteViewName', 'item-delete')
+    })
+
+    it('returns repeater config', () => {
+      expect(controller).toHaveProperty('repeat', {
+        options: {
+          name: 'pizza',
+          title: 'Pizza'
+        },
+        schema: {
+          max: 3,
+          min: 2
+        }
+      })
+    })
+  })
+
+  describe('Path methods', () => {
+    describe('Summary path', () => {
+      it('returns path to summary page', () => {
+        expect(controller.getSummaryPath()).toBe('/summary')
+      })
+
+      it('returns path to repeater summary page', () => {
+        expect(controller.getSummaryPath(requestPage)).toBe(
+          '/pizza-order/summary'
+        )
+      })
+    })
+  })
+
+  describe('Item view model', () => {
+    let viewModel: FormPageViewModel
+
+    beforeEach(() => {
+      viewModel = controller.getViewModel(
+        requestPageItem,
+        model.getFormContext(requestPageItem, {})
+      )
+    })
+
+    it('updates section title with repeater title and count', () => {
+      expect(viewModel).toHaveProperty('sectionTitle', 'Food: Pizza 1')
+    })
+  })
+
+  describe.each([
+    {
+      description: 'No items',
+      list: [] satisfies RepeatListState,
+      viewModel: {
+        pageTitle: 'You have added 0 Pizzas',
+        showTitle: true,
+        sectionTitle: 'Food'
+      }
+    },
+    {
+      description: '1 item',
+      list: [
+        {
+          itemId: itemId1,
+          toppings: 'Ham',
+          quantity: 2
+        }
+      ] satisfies RepeatListState,
+      viewModel: {
+        pageTitle: 'You have added 1 Pizza',
+        showTitle: true,
+        sectionTitle: 'Food'
+      }
+    },
+    {
+      description: '2 items',
+      list: [
+        {
+          itemId: itemId1,
+          toppings: 'Ham',
+          quantity: 2
+        },
+        {
+          itemId: itemId2,
+          toppings: 'Cheese',
+          quantity: 1
+        }
+      ] satisfies RepeatListState,
+      viewModel: {
+        pageTitle: 'You have added 2 Pizzas',
+        showTitle: true,
+        sectionTitle: 'Food'
+      }
+    }
+  ])(
+    'List summary view model ($description)',
+    ({ list, viewModel: expected }) => {
+      let viewModel: RepeaterSummaryPageViewModel
+
+      beforeEach(() => {
+        viewModel = controller.getListSummaryViewModel(
+          requestPageSummary,
+          model.getFormContext(requestPageSummary, {}),
+          list
+        )
+      })
+
+      it('should customise page title', () => {
+        expect(viewModel).toHaveProperty('pageTitle', expected.pageTitle)
+        expect(viewModel).toHaveProperty('showTitle', expected.showTitle)
+      })
+
+      it('should extend default view model', () => {
+        const defaults = controller.viewModel
+
+        expect(viewModel).toHaveProperty('name', defaults.name)
+        expect(viewModel).toHaveProperty('page', defaults.page)
+        expect(viewModel).toHaveProperty('sectionTitle', expected.sectionTitle)
+        expect(viewModel).toHaveProperty('isStartPage', defaults.isStartPage)
+        expect(viewModel).toHaveProperty('serviceUrl', defaults.serviceUrl)
+        expect(viewModel).toHaveProperty('feedbackLink', defaults.feedbackLink)
+
+        // Unless overridden
+        expect(viewModel).not.toHaveProperty('pageTitle', defaults.pageTitle)
+      })
+    }
+  )
+
+  describe('Form validation', () => {
+    it('includes title text and errors', () => {
+      const result = controller.collection.validate()
+
+      expect(result.errors).toEqual<FormSubmissionError[]>([
+        {
+          path: ['toppings'],
+          href: '#toppings',
+          name: 'toppings',
+          text: 'Select toppings',
+          context: {
+            key: 'toppings',
+            label: 'Toppings',
+            title: 'Toppings'
+          }
+        },
+        {
+          path: ['quantity'],
+          href: '#quantity',
+          name: 'quantity',
+          text: 'Enter quantity',
+          context: {
+            key: 'quantity',
+            label: 'Quantity',
+            title: 'Quantity'
+          }
+        },
+        {
+          path: ['itemId'],
+          href: '#itemId',
+          name: 'itemId',
+          text: 'Select itemId',
+          context: {
+            key: 'itemId',
+            label: 'itemId'
+          }
+        }
+      ])
+    })
+
+    it('includes all field errors', () => {
+      const result = controller.collection.validate()
+      expect(result.errors).toHaveLength(3)
+    })
+  })
+})

package/src/server/plugins/engine/pageControllers/RepeatPageController.ts

@@ -0,0 +1,458 @@
+import { randomUUID } from 'crypto'
+
+import { type PageRepeat, type Repeat } from '@defra/forms-model'
+import Boom from '@hapi/boom'
+import { type ResponseToolkit } from '@hapi/hapi'
+import Joi from 'joi'
+
+import { isRepeatState } from '~/src/server/plugins/engine/components/FormComponent.js'
+import { redirectPath } from '~/src/server/plugins/engine/helpers.js'
+import { type FormModel } from '~/src/server/plugins/engine/models/index.js'
+import { QuestionPageController } from '~/src/server/plugins/engine/pageControllers/QuestionPageController.js'
+import {
+  type FormContext,
+  type FormContextRequest,
+  type FormPageViewModel,
+  type FormPayload,
+  type FormSubmissionState,
+  type ItemDeletePageViewModel,
+  type RepeatItemState,
+  type RepeatListState,
+  type RepeaterSummaryPageViewModel,
+  type SummaryList,
+  type SummaryListAction
+} from '~/src/server/plugins/engine/types.js'
+import {
+  FormAction,
+  type FormRequest,
+  type FormRequestPayload
+} from '~/src/server/routes/types.js'
+
+export class RepeatPageController extends QuestionPageController {
+  declare pageDef: PageRepeat
+
+  listSummaryViewName = 'repeat-list-summary'
+  listDeleteViewName = 'item-delete'
+  repeat: Repeat
+
+  constructor(model: FormModel, pageDef: PageRepeat) {
+    super(model, pageDef)
+
+    this.repeat = pageDef.repeat
+
+    const { options, schema } = this.repeat
+    const itemId = Joi.string().uuid().required()
+
+    this.collection.formSchema = this.collection.formSchema.append({ itemId })
+    this.collection.stateSchema = Joi.object<RepeatItemState>().keys({
+      [options.name]: Joi.array()
+        .items(this.collection.stateSchema.append({ itemId }))
+        .min(schema.min)
+        .max(schema.max)
+        .label(`${options.title} list`)
+        .required()
+    })
+  }
+
+  get keys() {
+    const { repeat } = this
+    return [repeat.options.name, ...super.keys]
+  }
+
+  getFormParams(request?: FormContextRequest) {
+    const params = super.getFormParams(request)
+
+    // Apply an itemId to the form payload
+    if (request?.payload) {
+      params.itemId = request.params.itemId ?? randomUUID()
+    }
+
+    return params
+  }
+
+  getFormDataFromState(
+    request: FormContextRequest | undefined,
+    state: FormSubmissionState
+  ) {
+    const { repeat } = this
+
+    const params = this.getFormParams(request)
+    const list = this.getListFromState(state)
+    const itemId = this.getItemId(request)
+
+    // Create payload with repeater list state
+    if (!itemId) {
+      return {
+        ...params,
+        [repeat.options.name]: list
+      }
+    }
+
+    // Create payload with repeater item state
+    const item = this.getItemFromList(list, itemId)
+
+    return {
+      ...params,
+      ...item
+    }
+  }
+
+  getStateFromValidForm(
+    request: FormContextRequest,
+    state: FormSubmissionState,
+    payload: FormPayload
+  ) {
+    const itemId = this.getItemId(request)
+
+    if (!itemId) {
+      throw Boom.badRequest('No item ID found')
+    }
+
+    const list = this.getListFromState(state)
+    const item = this.getItemFromList(list, itemId)
+
+    const itemState = super.getStateFromValidForm(request, state, payload)
+    const updated: RepeatItemState = { ...itemState, itemId }
+    const newList = [...list]
+
+    if (!item) {
+      // Adding a new item
+      newList.push(updated)
+    } else {
+      // Update an existing item
+      newList[list.indexOf(item)] = updated
+    }
+
+    return {
+      [this.repeat.options.name]: newList
+    }
+  }
+
+  proceed(
+    request: FormContextRequest,
+    h: Pick<ResponseToolkit, 'redirect' | 'view'>
+  ) {
+    const nextPath = this.getSummaryPath(request)
+    return super.proceed(request, h, nextPath)
+  }
+
+  getItemFromList(list: RepeatListState, itemId?: string) {
+    return list.find((item) => item.itemId === itemId)
+  }
+
+  getListFromState(state: FormSubmissionState) {
+    const { name } = this.repeat.options
+    const values = state[name]
+
+    return isRepeatState(values) ? values : []
+  }
+
+  makeGetRouteHandler() {
+    return async (
+      request: FormRequest,
+      context: FormContext,
+      h: Pick<ResponseToolkit, 'redirect' | 'view'>
+    ) => {
+      const { path } = this
+      const { query } = request
+      const { state } = context
+
+      const itemId = this.getItemId(request)
+      const list = this.getListFromState(state)
+
+      if (!itemId) {
+        const summaryPath = this.getSummaryPath(request)
+        const nextPath = redirectPath(`${path}/${randomUUID()}`, {
+          returnUrl: query.returnUrl,
+          force: query.force
+        })
+
+        // Only redirect to new item when list is empty
+        return super.proceed(request, h, list.length ? summaryPath : nextPath)
+      }
+
+      return super.makeGetRouteHandler()(request, context, h)
+    }
+  }
+
+  makeGetListSummaryRouteHandler() {
+    return (
+      request: FormRequest,
+      context: FormContext,
+      h: Pick<ResponseToolkit, 'redirect' | 'view'>
+    ) => {
+      const { path } = this
+      const { query } = request
+      const { state } = context
+
+      const list = this.getListFromState(state)
+
+      if (!list.length) {
+        const nextPath = redirectPath(`${path}/${randomUUID()}`, {
+          returnUrl: query.returnUrl
+        })
+
+        return super.proceed(request, h, nextPath)
+      }
+
+      const viewModel = this.getListSummaryViewModel(request, context, list)
+
+      return h.view(this.listSummaryViewName, viewModel)
+    }
+  }
+
+  makePostListSummaryRouteHandler() {
+    return (
+      request: FormRequestPayload,
+      context: FormContext,
+      h: Pick<ResponseToolkit, 'redirect' | 'view'>
+    ) => {
+      const { path, repeat } = this
+      const { query } = request
+      const { schema, options } = repeat
+      const { state } = context
+
+      const list = this.getListFromState(state)
+
+      if (!list.length) {
+        const nextPath = redirectPath(`${path}/${randomUUID()}`, {
+          returnUrl: query.returnUrl
+        })
+
+        return super.proceed(request, h, nextPath)
+      }
+
+      const { action } = this.getFormParams(request)
+
+      const hasErrorMin =
+        action === FormAction.Continue && list.length < schema.min
+
+      const hasErrorMax =
+        (action === FormAction.AddAnother && list.length >= schema.max) ||
+        (action === FormAction.Continue && list.length > schema.max)
+
+      // Show error if repeat limits apply
+      if (hasErrorMin || hasErrorMax) {
+        const count = hasErrorMax ? schema.max : schema.min
+        const itemTitle = `${options.title}${count === 1 ? '' : 's'}`
+
+        context.errors = [
+          {
+            path: [],
+            href: '',
+            name: '',
+            text: hasErrorMax
+              ? `You can only add up to ${count} ${itemTitle}`
+              : `You must add at least ${count} ${itemTitle}`
+          }
+        ]
+
+        const viewModel = this.getListSummaryViewModel(request, context, list)
+
+        return h.view(this.listSummaryViewName, viewModel)
+      }
+
+      if (action === FormAction.AddAnother) {
+        const nextPath = redirectPath(`${path}/${randomUUID()}`, {
+          returnUrl: query.returnUrl
+        })
+
+        return super.proceed(request, h, nextPath)
+      }
+
+      const nextPath = this.getNextPath(context)
+      return super.proceed(request, h, nextPath)
+    }
+  }
+
+  makeGetItemDeleteRouteHandler() {
+    return (
+      request: FormRequest,
+      context: FormContext,
+      h: Pick<ResponseToolkit, 'redirect' | 'view'>
+    ) => {
+      const { viewModel } = this
+      const { state } = context
+
+      const list = this.getListFromState(state)
+      const itemId = this.getItemId(request)
+      const item = this.getItemFromList(list, itemId)
+
+      if (!item || list.length === 1) {
+        throw Boom.notFound(
+          item
+            ? 'Last list item cannot be removed'
+            : 'List item to remove not found'
+        )
+      }
+
+      const { title } = this.repeat.options
+
+      return h.view(this.listDeleteViewName, {
+        ...viewModel,
+        context,
+        backLink: this.getBackLink(request, context),
+        pageTitle: `Are you sure you want to remove this ${title}?`,
+        itemTitle: `${title} ${list.indexOf(item) + 1}`,
+        buttonConfirm: { text: `Remove ${title}` },
+        buttonCancel: { text: 'Cancel' }
+      } satisfies ItemDeletePageViewModel)
+    }
+  }
+
+  makePostItemDeleteRouteHandler() {
+    return async (
+      request: FormRequestPayload,
+      context: FormContext,
+      h: Pick<ResponseToolkit, 'redirect' | 'view'>
+    ) => {
+      const { repeat } = this
+      const { state } = context
+
+      const { confirm } = this.getFormParams(request)
+
+      const list = this.getListFromState(state)
+      const itemId = this.getItemId(request)
+      const item = this.getItemFromList(list, itemId)
+
+      if (!item || list.length === 1) {
+        throw Boom.notFound(
+          item
+            ? 'Last list item cannot be removed'
+            : 'List item to remove not found'
+        )
+      }
+
+      // Remove the item from the list
+      if (confirm) {
+        list.splice(list.indexOf(item), 1)
+
+        const update = {
+          [repeat.options.name]: list
+        }
+
+        await this.mergeState(request, state, update)
+      }
+
+      return this.proceed(request, h)
+    }
+  }
+
+  getViewModel(
+    request: FormContextRequest,
+    context: FormContext
+  ): FormPageViewModel {
+    const { state } = context
+
+    const list = this.getListFromState(state)
+    const itemId = this.getItemId(request)
+    const item = this.getItemFromList(list, itemId)
+
+    const viewModel = super.getViewModel(request, context)
+    const itemNumber = item ? list.indexOf(item) + 1 : list.length + 1
+    const repeatCaption = `${this.repeat.options.title} ${itemNumber}`
+
+    return {
+      ...viewModel,
+
+      sectionTitle: viewModel.sectionTitle
+        ? `${viewModel.sectionTitle}: ${repeatCaption}`
+        : repeatCaption
+    }
+  }
+
+  getListSummaryViewModel(
+    request: FormContextRequest,
+    context: FormContext,
+    list: RepeatListState
+  ): RepeaterSummaryPageViewModel {
+    const { collection, href, repeat } = this
+    const { query } = request
+    const { isForceAccess, errors } = context
+
+    const { title } = repeat.options
+
+    const summaryList: SummaryList = {
+      classes: 'govuk-summary-list--long-actions',
+      rows: []
+    }
+
+    let count = 0
+
+    if (Array.isArray(list)) {
+      count = list.length
+
+      const summaryPath = this.getSummaryPath(request)
+
+      list.forEach((item, index) => {
+        const items: SummaryListAction[] = []
+
+        // Remove summary list actions from previews
+        if (!isForceAccess) {
+          items.push({
+            href: redirectPath(`${href}/${item.itemId}`, {
+              returnUrl: query.returnUrl ?? this.getHref(summaryPath)
+            }),
+            text: 'Change',
+            classes: 'govuk-link--no-visited-state',
+            visuallyHiddenText: `item ${index + 1}`
+          })
+
+          if (count > 1) {
+            items.push({
+              href: redirectPath(`${href}/${item.itemId}/confirm-delete`, {
+                returnUrl: query.returnUrl
+              }),
+              text: 'Remove',
+              classes: 'govuk-link--no-visited-state',
+              visuallyHiddenText: `item ${index + 1}`
+            })
+          }
+        }
+
+        const itemDisplayText = collection.fields.length
+          ? collection.fields[0].getDisplayStringFromState(item)
+          : ''
+
+        summaryList.rows.push({
+          key: {
+            text: `${title} ${index + 1}`
+          },
+          value: {
+            text: itemDisplayText || 'Not supplied'
+          },
+          actions: {
+            items
+          }
+        })
+      })
+    }
+
+    return {
+      ...this.viewModel,
+      backLink: this.getBackLink(request, context),
+      repeatTitle: title,
+      pageTitle: `You have added ${count} ${title}${count === 1 ? '' : 's'}`,
+      showTitle: true,
+      context,
+      errors,
+      checkAnswers: [{ summaryList }]
+    }
+  }
+
+  getSummaryPath(request?: FormContextRequest) {
+    const { path } = this
+
+    const summaryPath = super.getSummaryPath()
+
+    if (!request) {
+      return summaryPath
+    }
+
+    const { query } = request
+
+    return redirectPath(`${path}${summaryPath}`, {
+      returnUrl: query.returnUrl
+    })
+  }
+}