@defra/forms-engine-plugin 0.0.1

package/src/server/plugins/engine/components/FileUploadField.ts

@@ -0,0 +1,262 @@
+import { type FileUploadFieldComponent } from '@defra/forms-model'
+import joi, { type ArraySchema } from 'joi'
+
+import {
+  FormComponent,
+  isUploadState
+} from '~/src/server/plugins/engine/components/FormComponent.js'
+import {
+  FileStatus,
+  UploadStatus,
+  type FileState,
+  type FileUpload,
+  type FileUploadMetadata,
+  type FormPayload,
+  type FormState,
+  type FormStateValue,
+  type FormSubmissionError,
+  type FormSubmissionState,
+  type SummaryList,
+  type SummaryListAction,
+  type SummaryListRow,
+  type UploadState,
+  type UploadStatusFileResponse,
+  type UploadStatusResponse
+} from '~/src/server/plugins/engine/types.js'
+import { render } from '~/src/server/plugins/nunjucks/index.js'
+import { type FormQuery } from '~/src/server/routes/types.js'
+
+export const uploadIdSchema = joi.string().uuid().required()
+
+export const fileSchema = joi
+  .object<FileUpload>({
+    fileId: joi.string().uuid().required(),
+    filename: joi.string().required(),
+    contentLength: joi.number().required()
+  })
+  .required()
+
+export const tempFileSchema = fileSchema.append({
+  fileStatus: joi
+    .string()
+    .valid(FileStatus.complete, FileStatus.rejected, FileStatus.pending)
+    .required(),
+  errorMessage: joi.string().optional()
+})
+
+export const formFileSchema = fileSchema.append({
+  fileStatus: joi.string().valid(FileStatus.complete).required()
+})
+
+export const metadataSchema = joi
+  .object<FileUploadMetadata>()
+  .keys({
+    retrievalKey: joi.string().email().required()
+  })
+  .required()
+
+export const tempStatusSchema = joi
+  .object<UploadStatusFileResponse>({
+    uploadStatus: joi
+      .string()
+      .valid(UploadStatus.ready, UploadStatus.pending)
+      .required(),
+    metadata: metadataSchema,
+    form: joi.object().required().keys({
+      file: tempFileSchema
+    }),
+    numberOfRejectedFiles: joi.number().optional()
+  })
+  .required()
+
+export const formStatusSchema = joi
+  .object<UploadStatusResponse>({
+    uploadStatus: joi.string().valid(UploadStatus.ready).required(),
+    metadata: metadataSchema,
+    form: joi.object().required().keys({
+      file: formFileSchema
+    }),
+    numberOfRejectedFiles: joi.number().valid(0).required()
+  })
+  .required()
+
+export const itemSchema = joi.object<FileState>({
+  uploadId: uploadIdSchema
+})
+
+export const tempItemSchema = itemSchema.append({
+  status: tempStatusSchema
+})
+
+export const formItemSchema = itemSchema.append({
+  status: formStatusSchema
+})
+
+export class FileUploadField extends FormComponent {
+  declare options: FileUploadFieldComponent['options']
+  declare schema: FileUploadFieldComponent['schema']
+  declare formSchema: ArraySchema<FileState>
+  declare stateSchema: ArraySchema<FileState>
+
+  constructor(
+    def: FileUploadFieldComponent,
+    props: ConstructorParameters<typeof FormComponent>[1]
+  ) {
+    super(def, props)
+
+    const { options, schema, title } = def
+
+    let formSchema = joi.array<FileState>().label(title).single().required()
+
+    if (options.required === false) {
+      formSchema = formSchema.optional()
+    }
+
+    if (typeof schema.length !== 'number') {
+      if (typeof schema.max === 'number') {
+        formSchema = formSchema.max(schema.max)
+      }
+
+      if (typeof schema.min === 'number') {
+        formSchema = formSchema.min(schema.min)
+      }
+    } else {
+      formSchema = formSchema.length(schema.length)
+    }
+
+    this.formSchema = formSchema.items(formItemSchema)
+    this.stateSchema = formSchema
+      .items(formItemSchema)
+      .default(null)
+      .allow(null)
+
+    this.options = options
+    this.schema = schema
+  }
+
+  getFormValueFromState(state: FormSubmissionState) {
+    const { name } = this
+    return this.getFormValue(state[name])
+  }
+
+  getFormValue(value?: FormStateValue | FormState) {
+    return this.isValue(value) ? value : undefined
+  }
+
+  getDisplayStringFromState(state: FormSubmissionState) {
+    const files = this.getFormValueFromState(state)
+    if (!files?.length) {
+      return ''
+    }
+
+    const unit = files.length === 1 ? 'file' : 'files'
+    return `Uploaded ${files.length} ${unit}`
+  }
+
+  getContextValueFromState(state: FormSubmissionState) {
+    const files = this.getFormValueFromState(state)
+    return files?.map(({ status }) => status.form.file.fileId) ?? null
+  }
+
+  getViewModel(
+    payload: FormPayload,
+    errors?: FormSubmissionError[],
+    query: FormQuery = {}
+  ) {
+    const { options, page } = this
+
+    // Allow preview URL direct access
+    const isForceAccess = 'force' in query
+
+    const viewModel = super.getViewModel(payload, errors)
+    const { attributes, id, value } = viewModel
+
+    const files = this.getFormValue(value) ?? []
+    const filtered = files.filter(
+      (file) => file.status.form.file.fileStatus === FileStatus.complete
+    )
+    const count = filtered.length
+
+    const rows: SummaryListRow[] = filtered.map((item, index) => {
+      const { status } = item
+      const { form } = status
+      const { file } = form
+
+      const tag = { classes: 'govuk-tag--green', text: 'Uploaded' }
+
+      const valueHtml = render
+        .view('components/fileuploadfield-value.html', {
+          context: { params: { tag } }
+        })
+        .trim()
+
+      const keyHtml = render
+        .view('components/fileuploadfield-key.html', {
+          context: {
+            params: {
+              name: file.filename,
+              errorMessage: errors && file.errorMessage
+            }
+          }
+        })
+        .trim()
+
+      const items: SummaryListAction[] = []
+
+      // Remove summary list actions from previews
+      if (!isForceAccess) {
+        const path = `/${item.uploadId}/confirm-delete`
+        const href = page?.getHref(`${page.path}${path}`) ?? '#'
+
+        items.push({
+          href,
+          text: 'Remove',
+          classes: 'govuk-link--no-visited-state',
+          attributes: { id: `${id}__${index}` },
+          visuallyHiddenText: file.filename
+        })
+      }
+
+      return {
+        key: {
+          html: keyHtml
+        },
+        value: {
+          html: valueHtml
+        },
+        actions: {
+          items
+        }
+      } satisfies SummaryListRow
+    })
+
+    // Set up the `accept` attribute
+    if ('accept' in options) {
+      attributes.accept = options.accept
+    }
+
+    const summaryList: SummaryList = {
+      classes: 'govuk-summary-list--long-key',
+      rows
+    }
+
+    return {
+      ...viewModel,
+
+      // File input can't have a initial value
+      value: '',
+
+      // Override the component name we send to CDP
+      name: 'file',
+
+      upload: {
+        count,
+        summaryList
+      }
+    }
+  }
+
+  isValue(value?: FormStateValue | FormState): value is UploadState {
+    return isUploadState(value)
+  }
+}

package/src/server/plugins/engine/components/FormComponent.ts

@@ -0,0 +1,249 @@
+import { type FormComponentsDef, type Item } from '@defra/forms-model'
+
+import { ComponentBase } from '~/src/server/plugins/engine/components/ComponentBase.js'
+import { optionalText } from '~/src/server/plugins/engine/components/constants.js'
+import {
+  type FileState,
+  type FormPayload,
+  type FormState,
+  type FormStateValue,
+  type FormSubmissionError,
+  type FormSubmissionState,
+  type FormValue,
+  type RepeatItemState,
+  type RepeatListState,
+  type UploadState
+} from '~/src/server/plugins/engine/types.js'
+
+export class FormComponent extends ComponentBase {
+  type: FormComponentsDef['type']
+  hint: FormComponentsDef['hint']
+
+  isFormComponent = true
+
+  constructor(
+    def: FormComponentsDef,
+    props: ConstructorParameters<typeof ComponentBase>[1]
+  ) {
+    super(def, props)
+
+    const { hint, type } = def
+
+    this.type = type
+    this.hint = hint
+  }
+
+  get keys() {
+    const { collection, name } = this
+
+    if (collection) {
+      const { fields } = collection
+      return [name, ...fields.map(({ name }) => name)]
+    }
+
+    return [name]
+  }
+
+  getFormDataFromState(state: FormSubmissionState): FormPayload {
+    const { collection, name } = this
+
+    if (collection) {
+      return collection.getFormDataFromState(state)
+    }
+
+    return {
+      [name]: this.getFormValue(state[name])
+    }
+  }
+
+  getFormValueFromState(state: FormSubmissionState): FormValue | FormPayload {
+    const { collection, name } = this
+
+    if (collection) {
+      return collection.getFormValueFromState(state)
+    }
+
+    return this.getFormValue(state[name])
+  }
+
+  getFormValue(value?: FormStateValue | FormState) {
+    return this.isValue(value) ? value : undefined
+  }
+
+  getStateFromValidForm(payload: FormPayload): FormState {
+    const { collection, name } = this
+
+    if (collection) {
+      return collection.getStateFromValidForm(payload)
+    }
+
+    return {
+      [name]: this.getFormValue(payload[name]) ?? null
+    }
+  }
+
+  getErrors(errors?: FormSubmissionError[]): FormSubmissionError[] | undefined {
+    const { name } = this
+
+    // Filter component and child errors only
+    const list = errors?.filter(
+      (error) =>
+        error.name === name ||
+        error.path.includes(name) ||
+        this.keys.includes(error.name)
+    )
+
+    if (!list?.length) {
+      return
+    }
+
+    return list
+  }
+
+  getError(errors?: FormSubmissionError[]): FormSubmissionError | undefined {
+    return this.getErrors(errors)?.[0]
+  }
+
+  getViewModel(payload: FormPayload, errors?: FormSubmissionError[]) {
+    const { hint, name, options = {}, title, viewModel } = this
+
+    const isRequired = !('required' in options) || options.required !== false
+    const hideOptional = 'optionalText' in options && options.optionalText
+    const label = `${title}${!isRequired && !hideOptional ? optionalText : ''}`
+
+    if (hint) {
+      viewModel.hint = {
+        text: hint
+      }
+    }
+
+    // Filter component errors only
+    const componentErrors = this.getErrors(errors)
+    const componentError = this.getError(componentErrors)
+
+    if (componentErrors) {
+      viewModel.errors = componentErrors
+    }
+
+    if (componentError) {
+      viewModel.errorMessage = {
+        text: componentError.text
+      }
+    }
+
+    return {
+      ...viewModel,
+      label: {
+        text: label
+      },
+      id: name,
+      name,
+      value: payload[name]
+    }
+  }
+
+  getDisplayStringFromState(state: FormSubmissionState): string {
+    const value = this.getFormValueFromState(state)
+    return this.isValue(value) ? value.toString() : ''
+  }
+
+  getContextValueFromState(
+    state: FormSubmissionState
+  ): Item['value'] | Item['value'][] | null {
+    const value = this.getFormValueFromState(state)
+
+    // Filter object field values
+    if (this.isState(value)) {
+      const values = Object.values(value).filter(isFormValue)
+      return values.length ? values : null
+    }
+
+    // Filter array field values
+    if (this.isValue(value) && Array.isArray(value)) {
+      return value.filter(isFormValue)
+    }
+
+    return this.isValue(value) ? value : null
+  }
+
+  isValue(
+    value?: FormStateValue | FormState
+  ): value is NonNullable<FormStateValue> {
+    return isFormValue(value)
+  }
+
+  isState(value?: FormStateValue | FormState): value is FormState {
+    return isFormState(value)
+  }
+}
+
+/**
+ * Check for form value
+ */
+export function isFormValue(
+  value?: unknown
+): value is string | number | boolean {
+  return (
+    (typeof value === 'string' && value.length > 0) ||
+    typeof value === 'number' ||
+    typeof value === 'boolean'
+  )
+}
+
+/**
+ * Check for form state with nested values
+ */
+export function isFormState(value?: unknown): value is FormState {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    return false
+  }
+
+  // Skip empty objects
+  return !!Object.values(value).length
+}
+
+/**
+ * Check for repeat list state
+ */
+export function isRepeatState(value?: unknown): value is RepeatListState {
+  if (!Array.isArray(value)) {
+    return false
+  }
+
+  // Skip checks when empty
+  if (!value.length) {
+    return true
+  }
+
+  return value.every(isRepeatValue)
+}
+
+/**
+ * Check for repeat list value
+ */
+export function isRepeatValue(value?: unknown): value is RepeatItemState {
+  return isFormState(value) && typeof value.itemId === 'string'
+}
+
+/**
+ * Check for upload state
+ */
+export function isUploadState(value?: unknown): value is UploadState {
+  if (!Array.isArray(value)) {
+    return false
+  }
+
+  // Skip checks when empty
+  if (!value.length) {
+    return true
+  }
+
+  return value.every(isUploadValue)
+}
+
+/**
+ * Check for upload state value
+ */
+export function isUploadValue(value?: unknown): value is FileState {
+  return isFormState(value) && typeof value.uploadId === 'string'
+}

package/src/server/plugins/engine/components/Html.test.ts

@@ -0,0 +1,48 @@
+import { ComponentType, type HtmlComponent } from '@defra/forms-model'
+
+import { ComponentCollection } from '~/src/server/plugins/engine/components/ComponentCollection.js'
+import { type Guidance } from '~/src/server/plugins/engine/components/helpers.js'
+import { FormModel } from '~/src/server/plugins/engine/models/FormModel.js'
+import definition from '~/test/form/definitions/basic.js'
+
+describe('HTML', () => {
+  let model: FormModel
+
+  beforeEach(() => {
+    model = new FormModel(definition, {
+      basePath: 'test'
+    })
+  })
+
+  describe('Defaults', () => {
+    let def: HtmlComponent
+    let collection: ComponentCollection
+    let guidance: Guidance
+
+    beforeEach(() => {
+      def = {
+        title: 'HTML guidance',
+        name: 'myComponent',
+        type: ComponentType.Html,
+        content: '<p class="govuk-body">\nLorem ipsum dolor sit amet</p>',
+        options: {}
+      } satisfies HtmlComponent
+
+      collection = new ComponentCollection([def], { model })
+      guidance = collection.guidance[0]
+    })
+
+    describe('View model', () => {
+      it('sets Nunjucks component defaults', () => {
+        const viewModel = guidance.getViewModel()
+
+        expect(viewModel).toEqual(
+          expect.objectContaining({
+            attributes: {},
+            content: def.content
+          })
+        )
+      })
+    })
+  })
+})

package/src/server/plugins/engine/components/Html.ts

@@ -0,0 +1,29 @@
+import { type HtmlComponent } from '@defra/forms-model'
+
+import { ComponentBase } from '~/src/server/plugins/engine/components/ComponentBase.js'
+
+export class Html extends ComponentBase {
+  declare options: HtmlComponent['options']
+  content: HtmlComponent['content']
+
+  constructor(
+    def: HtmlComponent,
+    props: ConstructorParameters<typeof ComponentBase>[1]
+  ) {
+    super(def, props)
+
+    const { content, options } = def
+
+    this.content = content
+    this.options = options
+  }
+
+  getViewModel() {
+    const { content, viewModel } = this
+
+    return {
+      ...viewModel,
+      content
+    }
+  }
+}

package/src/server/plugins/engine/components/InsetText.test.ts

@@ -0,0 +1,48 @@
+import { ComponentType, type InsetTextComponent } from '@defra/forms-model'
+
+import { ComponentCollection } from '~/src/server/plugins/engine/components/ComponentCollection.js'
+import { type Guidance } from '~/src/server/plugins/engine/components/helpers.js'
+import { FormModel } from '~/src/server/plugins/engine/models/FormModel.js'
+import definition from '~/test/form/definitions/basic.js'
+
+describe('InsetText', () => {
+  let model: FormModel
+
+  beforeEach(() => {
+    model = new FormModel(definition, {
+      basePath: 'test'
+    })
+  })
+
+  describe('Defaults', () => {
+    let def: InsetTextComponent
+    let collection: ComponentCollection
+    let guidance: Guidance
+
+    beforeEach(() => {
+      def = {
+        title: 'Inset text guidance',
+        name: 'myComponent',
+        type: ComponentType.InsetText,
+        content: 'Lorem ipsum dolor sit amet',
+        options: {}
+      } satisfies InsetTextComponent
+
+      collection = new ComponentCollection([def], { model })
+      guidance = collection.guidance[0]
+    })
+
+    describe('View model', () => {
+      it('sets Nunjucks component defaults', () => {
+        const viewModel = guidance.getViewModel()
+
+        expect(viewModel).toEqual(
+          expect.objectContaining({
+            attributes: {},
+            content: def.content
+          })
+        )
+      })
+    })
+  })
+})

package/src/server/plugins/engine/components/InsetText.ts

@@ -0,0 +1,27 @@
+import { type InsetTextComponent } from '@defra/forms-model'
+
+import { ComponentBase } from '~/src/server/plugins/engine/components/ComponentBase.js'
+
+export class InsetText extends ComponentBase {
+  content: InsetTextComponent['content']
+
+  constructor(
+    def: InsetTextComponent,
+    props: ConstructorParameters<typeof ComponentBase>[1]
+  ) {
+    super(def, props)
+
+    const { content } = def
+
+    this.content = content
+  }
+
+  getViewModel() {
+    const { content, viewModel } = this
+
+    return {
+      ...viewModel,
+      content
+    }
+  }
+}