@defra/forms-model 3.0.429 → 3.0.431

package/src/form/form-editor/index.ts

@@ -17,6 +17,8 @@ export enum QuestionTypeSubGroup {
 export const pageTypeSchema = Joi.string()
   .required()
   .valid('question', 'guidance')
+  .description('Type of page - either a question page or guidance page')
+
 export const questionTypeSchema = Joi.string()
   .required()
   .valid(
@@ -32,6 +34,7 @@ export const questionTypeSchema = Joi.string()
     ComponentType.RadiosField,
     ComponentType.AutocompleteField
   )
+  .description('The high-level type of question, including grouped types')
 
 export const questionTypeFullSchema = Joi.string()
   .required()
@@ -50,6 +53,7 @@ export const questionTypeFullSchema = Joi.string()
     ComponentType.RadiosField,
     ComponentType.AutocompleteField
   )
+  .description('The specific component type to use for this question')
 
 export const writtenAnswerSubSchema = Joi.string()
   .required()
@@ -58,6 +62,8 @@ export const writtenAnswerSubSchema = Joi.string()
     ComponentType.MultilineTextField,
     ComponentType.NumberField
   )
+  .description('Subtype for written answer questions')
+
 export const dateSubSchema = Joi.string()
   .required()
   .valid(ComponentType.DatePartsField, ComponentType.MonthYearField)
@@ -69,59 +75,226 @@ export const listSubSchema = Joi.string()
     ComponentType.RadiosField,
     ComponentType.AutocompleteField
   )
+  .description('Subtype for date-related questions')
+
+export const nameSchema = Joi.string()
+  .trim()
+  .required()
+  .description('Unique identifier for the field')
+
+export const questionSchema = Joi.string()
+  .trim()
+  .required()
+  .description('The question text displayed to the user')
+
+export const hintTextSchema = Joi.string()
+  .trim()
+  .optional()
+  .allow('')
+  .description('Optional guidance text displayed below the question')
 
-export const nameSchema = Joi.string().trim().required()
-export const questionSchema = Joi.string().trim().required()
-export const hintTextSchema = Joi.string().trim().optional().allow('')
 export const questionOptionalSchema = Joi.string()
   .trim()
   .optional()
   .valid('', 'true')
-export const shortDescriptionSchema = Joi.string().trim().required()
-export const pageHeadingAndGuidanceSchema = Joi.string().trim().optional()
-export const pageHeadingSchema = Joi.string().trim().required()
-export const guidanceTextSchema = Joi.string().trim()
-export const needDeclarationSchema = Joi.string().trim().required()
-export const declarationTextSchema = Joi.string().trim().required()
-export const exactFilesSchema = Joi.number().empty('').integer().min(1).max(25)
-export const minFilesSchema = Joi.number().empty('').integer().min(0).max(25)
-export const maxFilesSchema = Joi.number().empty('').integer().min(1).max(25)
-export const minSchema = Joi.number().empty('').integer()
-export const maxSchema = Joi.number().empty('').integer()
-export const minLengthSchema = Joi.number().empty('').integer().min(1)
-export const maxLengthSchema = Joi.number().empty('').integer().min(1)
-export const maxFutureSchema = Joi.number().empty('').integer().min(0)
-export const maxPastSchema = Joi.number().empty('').integer().min(0)
-export const precisionSchema = Joi.number().empty('').integer().min(0).max(5)
-export const prefixSchema = Joi.string().trim().optional().allow('')
-export const regexSchema = Joi.string().optional().allow('')
-export const rowsSchema = Joi.number().empty('').integer().min(1)
-export const suffixSchema = Joi.string().trim().optional().allow('')
-export const classesSchema = Joi.string().trim().optional().allow('')
+  .description(
+    'Indicates whether a question is optional. Empty string or "true" values are accepted.'
+  )
+
+export const exactFilesSchema = Joi.number()
+  .empty('')
+  .integer()
+  .min(1)
+  .max(25)
+  .description(
+    'Specifies the exact number of files required for upload. Must be between 1 and 25.'
+  )
+
+export const minFilesSchema = Joi.number()
+  .empty('')
+  .integer()
+  .min(0)
+  .max(25)
+  .description(
+    'Minimum number of files required for upload. Must be between 0 and 25.'
+  )
+
+export const maxFilesSchema = Joi.number()
+  .empty('')
+  .integer()
+  .min(1)
+  .max(25)
+  .description(
+    'Maximum number of files allowed for upload. Must be between 1 and 25.'
+  )
+
 export const fileTypesSchema = Joi.array()
   .items(Joi.string())
   .single()
   .empty(null)
   .default([])
+  .description(
+    'Array of allowed file types. Can be provided as a single value or an array.'
+  )
+
 export const documentTypesSchema = Joi.array()
   .items(Joi.string())
   .single()
   .empty(null)
   .default([])
+  .description(
+    'Array of allowed document types. Can be provided as a single value or an array.'
+  )
+
 export const imageTypesSchema = Joi.array()
   .items(Joi.string())
   .single()
   .empty(null)
   .default([])
+  .description(
+    'Array of allowed image types. Can be provided as a single value or an array.'
+  )
+
 export const tabularDataTypesSchema = Joi.array()
   .items(Joi.string())
   .single()
   .empty(null)
   .default([])
+export const enhancedActionSchema = Joi.string()
+  .trim()
+  .optional()
+  .allow('')
+  .description('Action field that can include enhanced functionality')
+
+export const radioIdSchema = Joi.string()
+  .trim()
+  .optional()
+  .allow('')
+  .description('Unique identifier for radio options')
+
+export const radioLabelSchema = Joi.string()
+  .trim()
+  .required()
+  .description('The visible text shown next to radio options')
+
+export const radioHintSchema = Joi.string()
+  .trim()
+  .optional()
+  .allow('')
+  .description(
+    'Optional hint text displayed with radio buttons to provide additional guidance'
+  )
+
+export const radioValueSchema = Joi.string()
+  .trim()
+  .optional()
+  .allow('')
+  .description(
+    'Array of allowed tabular data types. Can be provided as a single value or an array.'
+  )
+
+export const shortDescriptionSchema = Joi.string()
+  .trim()
+  .required()
+  .description('Brief description of the question for internal use')
+
+export const pageHeadingAndGuidanceSchema = Joi.string()
+  .trim()
+  .optional()
+  .description('Combined heading and guidance for the page')
+
+export const pageHeadingSchema = Joi.string()
+  .trim()
+  .required()
+  .description('Main heading displayed at the top of the page')
+
+export const guidanceTextSchema = Joi.string()
+  .trim()
+  .description('Guidance text to assist users in completing the page')
+
+export const needDeclarationSchema = Joi.string()
+  .trim()
+  .required()
+  .description('Whether a declaration is needed')
+
+export const declarationTextSchema = Joi.string()
+  .trim()
+  .required()
+  .description('Text of the declaration that users must agree to')
+
+export const minSchema = Joi.number()
+  .empty('')
+  .integer()
+  .description('Minimum value for numeric inputs')
+
+export const maxSchema = Joi.number()
+  .empty('')
+  .integer()
+  .description('Maximum value for numeric inputs')
+
+export const minLengthSchema = Joi.number()
+  .empty('')
+  .integer()
+  .min(1)
+  .description('Minimum character length for text inputs')
+
+export const maxLengthSchema = Joi.number()
+  .empty('')
+  .integer()
+  .min(1)
+  .description('Maximum character length for text inputs')
+
+export const maxFutureSchema = Joi.number()
+  .empty('')
+  .integer()
+  .min(1)
+  .description('Maximum days in the future allowed for date inputs')
+
+export const maxPastSchema = Joi.number()
+  .empty('')
+  .integer()
+  .min(1)
+  .description('Maximum days in the past allowed for date inputs')
+
+export const precisionSchema = Joi.number()
+  .empty('')
+  .integer()
+  .min(1)
+  .description('Decimal precision for numeric inputs')
+
+export const prefixSchema = Joi.string()
+  .trim()
+  .optional()
+  .allow('')
+  .description('Text to display before the input (e.g., £)')
+
+export const regexSchema = Joi.string()
+  .optional()
+  .allow('')
+  .description('Regular expression pattern for validation')
+
+export const rowsSchema = Joi.number()
+  .empty('')
+  .integer()
+  .min(1)
+  .description('Number of rows for multiline text fields')
+
+export const suffixSchema = Joi.string()
+  .trim()
+  .optional()
+  .allow('')
+  .description('Text to display after the input (e.g., kg)')
+
+export const classesSchema = Joi.string()
+  .trim()
+  .optional()
+  .allow('')
+  .description('Custom CSS classes to apply to the component')
 
 export const questionDetailsFullSchema = {
   classesSchema,
   documentTypesSchema,
+  enhancedActionSchema,
   exactFilesSchema,
   fileTypesSchema,
   hintTextSchema,
@@ -140,6 +313,10 @@ export const questionDetailsFullSchema = {
   questionOptionalSchema,
   questionSchema,
   questionTypeFullSchema,
+  radioHintSchema,
+  radioIdSchema,
+  radioLabelSchema,
+  radioValueSchema,
   regexSchema,
   rowsSchema,
   shortDescriptionSchema,
@@ -159,6 +336,7 @@ export const formEditorInputPageKeys = {
 export const formEditorInputPageSchema = Joi.object<FormEditorInputPage>()
   .keys(formEditorInputPageKeys)
   .required()
+  .description('Input schema for creating a new page in the form editor')
 
 export const formEditorInputheckAnswersSettingsKeys = {
   declarationText: shortDescriptionSchema
@@ -172,6 +350,7 @@ export const formEditorInputCheckAnswersSettingSchema =
   Joi.object<FormEditorInputCheckAnswersSettings>()
     .keys(formEditorInputheckAnswersSettingsKeys)
     .required()
+    .description('Configuration for the check-answers page')
 
 export const formEditorInputQuestionKeys = {
   question: questionSchema,
@@ -188,6 +367,9 @@ export const formEditorInputQuestionSchema =
   Joi.object<FormEditorInputQuestion>()
     .keys(formEditorInputQuestionKeys)
     .required()
+    .description(
+      'Input schema for creating or updating a question in the form editor'
+    )
 
 export const formEditorInputPageSettingsKeys = {
   pageHeadingAndGuidance: pageHeadingAndGuidanceSchema,
@@ -203,3 +385,4 @@ export const formEditorInputPageSettingsSchema =
   Joi.object<FormEditorInputPageSettings>()
     .keys(formEditorInputPageSettingsKeys)
     .required()
+    .description('Settings for page content and display in the form editor')

package/src/form/form-editor/types.ts

@@ -1,3 +1,5 @@
+import { type ComponentDef } from '~/src/components/types.js'
+
 /**
  * Interface for `FormEditor` Joi schema
  */
@@ -171,6 +173,36 @@ export interface FormEditor {
    * The types of tabular data files for upload
    */
   tabularDataTypes: string[]
+
+  /**
+   * The action required from within a sub-section
+   */
+  enhancedAction: string
+
+  /**
+   * Placeholder for inserted section to handle adding/editing radios or checkboxes
+   */
+  radiosOrCheckboxes: string
+
+  /**
+   * The unique id of the radio item
+   */
+  radioId: string
+
+  /**
+   * The display text of the radio item
+   */
+  radioLabel: string
+
+  /**
+   * The hint of the radio item
+   */
+  radioHint: string
+
+  /**
+   * The value of the radio item
+   */
+  radioValue: string
 }
 
 export type FormEditorInputPage = Pick<
@@ -210,6 +242,11 @@ export type FormEditorInputQuestion = Pick<
   | 'documentTypes'
   | 'imageTypes'
   | 'tabularDataTypes'
+  | 'enhancedAction'
+  | 'radioId'
+  | 'radioLabel'
+  | 'radioHint'
+  | 'radioValue'
 >
 
 export type FormEditorInputPageSettings = Pick<
@@ -222,6 +259,36 @@ export type FormEditorInputGuidancePage = Pick<
   'pageHeading' | 'guidanceText'
 >
 
+export type FormEditorInputQuestionDetails = Pick<
+  FormEditorInputQuestion,
+  | 'question'
+  | 'hintText'
+  | 'shortDescription'
+  | 'questionOptional'
+  | 'questionType'
+  | 'fileTypes'
+  | 'documentTypes'
+  | 'imageTypes'
+  | 'tabularDataTypes'
+  | 'enhancedAction'
+  | 'radioId'
+  | 'radioLabel'
+  | 'radioHint'
+  | 'radioValue'
+>
+
+export interface EnhancedActionState {
+  questionDetails: Partial<ComponentDef>
+  state: {
+    radioId?: string
+    radioLabel?: string
+    radioHint?: string
+    radioValue?: string
+    expanded?: boolean
+  }
+  listItems: { label?: string; hint?: string; value?: string; id?: string }[]
+}
+
 export interface GovukField {
   id?: string
   name?: string
@@ -236,6 +303,7 @@ export interface GovukField {
   items?: { text?: string; value?: string; checked?: boolean }[]
   rows?: number
   type?: string
+  customTemplate?: string
 }
 
 export interface FormEditorGovukField {
@@ -247,6 +315,7 @@ export interface FormEditorGovukField {
   documentTypes?: GovukField
   imageTypes?: GovukField
   tabularDataTypes?: GovukField
+  radiosOrCheckboxes?: GovukField
   errorMessage?: { text: string }
 }
 

package/src/form/form-manager/index.ts

@@ -5,8 +5,17 @@ import { pageSchema } from '~/src/index.js'
 
 export const patchPageSchema = Joi.object<PatchPageFields>()
   .keys({
-    title: pageSchema.extract('title').optional(),
-    path: pageSchema.extract('path').optional()
+    title: pageSchema
+      .extract('title')
+      .optional()
+      .description('New title to set for the page'),
+    path: pageSchema
+      .extract('path')
+      .optional()
+      .description('New URL path to set for the page')
   })
   .required()
   .min(1)
+  .description(
+    'Schema for partially updating a page, requiring at least one field to be provided'
+  )

package/src/form/form-metadata/index.ts

@@ -22,30 +22,63 @@ export const organisations = [
   'Veterinary Medicines Directorate – VMD'
 ]
 
-export const idSchema = Joi.string().hex().length(24).required()
-export const titleSchema = Joi.string().max(250).trim().required()
+export const idSchema = Joi.string()
+  .hex()
+  .length(24)
+  .required()
+  .description(
+    'Unique identifier for the form, 24-character hexadecimal string'
+  )
+
+export const titleSchema = Joi.string()
+  .max(250)
+  .trim()
+  .required()
+  .description('Title of the form, displayed to users')
+
 export const slugSchema = Joi.string()
   .pattern(/^[a-z0-9-]+$/, { name: 'letters, numbers and hyphens only' })
   .required()
+  .description('URL-friendly identifier used in form paths')
 
 export const organisationSchema = Joi.string()
   .valid(...organisations)
   .required()
+  .description('Defra organisation responsible for the form')
+
+export const teamNameSchema = Joi.string()
+  .max(100)
+  .trim()
+  .required()
+  .description('Name of the team responsible for the form')
 
-export const teamNameSchema = Joi.string().max(100).trim().required()
 export const teamEmailSchema = Joi.string()
   .email({ tlds: { allow: ['uk'] } })
   .trim()
   .required()
+  .description('Contact email for the team responsible for the form')
+
+export const phoneSchema = Joi.string()
+  .trim()
+  .description('Phone number for form-related inquiries')
+
+export const emailAddressSchema = Joi.string()
+  .email()
+  .trim()
+  .required()
+  .description('Email address for form-related inquiries')
 
-export const phoneSchema = Joi.string().trim()
+export const emailResponseTimeSchema = Joi.string()
+  .trim()
+  .required()
+  .description('Expected response time for email inquiries')
 
-export const emailAddressSchema = Joi.string().email().trim().required()
-export const emailResponseTimeSchema = Joi.string().trim().required()
-export const emailSchema = Joi.object<FormMetadataContactEmail>().keys({
-  address: emailAddressSchema,
-  responseTime: emailResponseTimeSchema
-})
+export const emailSchema = Joi.object<FormMetadataContactEmail>()
+  .keys({
+    address: emailAddressSchema,
+    responseTime: emailResponseTimeSchema
+  })
+  .description('Email contact details including response expectations')
 
 export const onlineUrlSchema = Joi.string()
   .uri({
@@ -53,34 +86,61 @@ export const onlineUrlSchema = Joi.string()
   })
   .trim()
   .required()
-export const onlineTextSchema = Joi.string().trim().required()
-export const onlineSchema = Joi.object<FormMetadataContactOnline>().keys({
-  url: onlineUrlSchema,
-  text: onlineTextSchema
-})
+  .description('URL for online contact method')
+
+export const onlineTextSchema = Joi.string()
+  .trim()
+  .required()
+  .description('Descriptive text for the online contact link')
 
-export const contactSchema = Joi.object<FormMetadataContact>().keys({
-  phone: phoneSchema,
-  email: emailSchema,
-  online: onlineSchema
-})
+export const onlineSchema = Joi.object<FormMetadataContactOnline>()
+  .keys({
+    url: onlineUrlSchema,
+    text: onlineTextSchema
+  })
+  .description('Online contact details with URL and descriptive text')
 
-export const submissionGuidanceSchema = Joi.string().trim()
+export const contactSchema = Joi.object<FormMetadataContact>()
+  .keys({
+    phone: phoneSchema,
+    email: emailSchema,
+    online: onlineSchema
+  })
+  .description('Complete contact information for form-related inquiries')
+
+export const submissionGuidanceSchema = Joi.string()
+  .trim()
+  .description('Guidance text shown to users when submitting the form')
 
 export const privacyNoticeUrlSchema = Joi.string()
   .uri({
     scheme: ['http', 'https']
   })
   .trim()
+  .description('URL to the privacy notice for this form')
 
 export const notificationEmailAddressSchema = Joi.string()
   .email({ tlds: { allow: ['uk'] } })
   .trim()
   .pattern(/\.gov\.uk$|\.org\.uk$/)
+  .description(
+    'Email address to receive form submission notifications, must be a .gov.uk or .org.uk address'
+  )
+
+export const authoredAtSchema = Joi.date()
+  .iso()
+  .required()
+  .description('ISO format timestamp of when an action occurred')
 
-export const authoredAtSchema = Joi.date().iso().required()
-export const authorIdSchema = Joi.string().trim().required()
-export const authorDisplayNameSchema = Joi.string().trim().required()
+export const authorIdSchema = Joi.string()
+  .trim()
+  .required()
+  .description('Unique identifier for the author')
+
+export const authorDisplayNameSchema = Joi.string()
+  .trim()
+  .required()
+  .description('Human-readable name of the author')
 
 export const formMetadataInputKeys = {
   title: titleSchema,
@@ -100,6 +160,7 @@ export const formMetadataInputKeys = {
 export const formMetadataInputSchema = Joi.object<FormMetadataInput>()
   .keys(formMetadataInputKeys)
   .required()
+  .description('Input data for creating or updating form metadata')
 
 /**
  * Joi schema for `FormMetadataAuthor` interface
@@ -111,29 +172,46 @@ export const formMetadataAuthorSchema = Joi.object<FormMetadataAuthor>()
     displayName: authorDisplayNameSchema
   })
   .required()
+  .description('Information about the author of a form or form change')
 
 /**
  * Joi schema for `FormMetadataState` interface
  * @see {@link FormMetadataState}
  */
-export const formMetadataStateSchema = Joi.object<FormMetadataState>().keys({
-  createdAt: authoredAtSchema,
-  createdBy: formMetadataAuthorSchema,
-  updatedAt: authoredAtSchema,
-  updatedBy: formMetadataAuthorSchema
-})
+export const formMetadataStateSchema = Joi.object<FormMetadataState>()
+  .keys({
+    createdAt: authoredAtSchema.description(
+      'When this version was first created'
+    ),
+    createdBy: formMetadataAuthorSchema.description('Who created this version'),
+    updatedAt: authoredAtSchema.description(
+      'When this version was last updated'
+    ),
+    updatedBy: formMetadataAuthorSchema.description(
+      'Who last updated this version'
+    )
+  })
+  .description('Metadata about a specific version state (draft or live)')
 
 /**
  * Joi schema for `FormMetadata` interface
  * @see {@link FormMetadata}
  */
-export const formMetadataSchema = formMetadataInputSchema.append<FormMetadata>({
-  id: idSchema,
-  slug: slugSchema,
-  draft: formMetadataStateSchema,
-  live: formMetadataStateSchema,
-  createdAt: authoredAtSchema,
-  createdBy: formMetadataAuthorSchema,
-  updatedAt: authoredAtSchema,
-  updatedBy: formMetadataAuthorSchema
-})
+export const formMetadataSchema = formMetadataInputSchema
+  .append<FormMetadata>({
+    id: idSchema,
+    slug: slugSchema,
+    draft: formMetadataStateSchema.description(
+      'Metadata for the draft version'
+    ),
+    live: formMetadataStateSchema.description(
+      'Metadata for the published version'
+    ),
+    createdAt: authoredAtSchema.description('When the form was first created'),
+    createdBy: formMetadataAuthorSchema.description('Who created the form'),
+    updatedAt: authoredAtSchema.description('When the form was last updated'),
+    updatedBy: formMetadataAuthorSchema.description('Who last updated the form')
+  })
+  .description(
+    'Complete metadata for a form, including version information and authoring details'
+  )